# A/B Testing
Source: https://documentation.onesignal.com/docs/en/ab-testing

Optimize your push and email messaging with OneSignal's A/B testing to improve engagement and campaign performance.

A/B Testing helps you optimize messages by testing up to **10 variants** and evaluating performance based on metrics like open rates and click-through rates. This allows you to improve user engagement and make data-driven messaging decisions.

Marketers focused on Lifecycle and Growth can use insights from A/B tests to make impactful improvements that align with broader business goals. Whether you’re testing push notifications or emails, A/B testing allows you to experiment with different designs, copy, calls-to-action (CTAs), and more. For example, test whether:

* A push with an image outperforms text-only
* A CTA like “Claim Offer” works better than “Get Started”
* A short subject line gets more opens than a longer one

***

## Plan availability

* **Pro & Enterprise Plans**: Up to **10 variants**
* **Free & Growth Plans**: **2 variants**

[Compare Plans](https://onesignal.com/pricing)

***

## How A/B Testing works

<Note>
  A/B testing is only available when sending through the dashboard. It is not available with the API.

  To create A/B tests with Journeys, use [Journey Split Branches](./journeys-overview#split-branches).
</Note>

When creating [push](./push) and [email](./email-messaging) campaigns through the dashboard, click the **A/B Test** button and **Add Variant** to create additional tests.

Your Audience (included and excluded segments) will be all the users eligible for the campaign.

After you create the variants, you can select a portion of your audience to receive randomized variants i.e. 25% means 25% of the segment(s) selected will randomly receive one of the variants. A message with 2 variants (A & B) targeting 25% will have 12.5% of the audience get variant A and another 12.5% get variant B. A message with 10 variants (A-J) targeting 25% will have 2.5% of the users get each variant.

<Frame>
  <img />
</Frame>

<Info>
  By default, 25% of your audience receives the A/B test. For valid results, each variant must receive enough users. The more variants you use, the larger your test group must be.

  If you set 100%, the message will be sent evenly to all users in the audience and eliminates the ability to send the "winner" to remaining users.
</Info>

## Select a Winner

Messages that are sent as A/B tests will be marked as such under the **Messages Tab**. Click into the report for each test to see the full report or view the variant-specific reports.

We provide some statistics for you to view the performance and choose a winner. The below screenshot describes how to view different stats and select a winning variant. We will then send the winner variant to all the remaining members of your target audience.

<Frame>
  <img />
</Frame>

***

## Platform-specific instructions

<Tabs>
  <Tab title="Push A/B Testing">
    ### Create a Push A/B Test

    1. Go to **Messages > Push > New Push**
    2. Name your message (e.g., "Push AB Test - CTA Button")
    3. Select your segment(s)
    4. Click the **A/B Test** button

    <Frame>
      <img />
    </Frame>

    5. Add variants

    * Click **Add Variant** to duplicate and edit each new version.
    * Only change **one variable** at a time for meaningful insights.

    <Frame>
      <img />
    </Frame>

    6. A/B Test settings

    Select the percentage of your target audience that should receive each variant. See [How A/B Testing works](#how-a%2Fb-testing-works) for more details.

    The percentage is applied to the total audience, evenly distributed across each variant. Examples:

    * 25% of a message with 2 variants will sent 12.5% to each variant.
    * 25% of a message with 10 variants will sent 2.5% to each variant.
    * 50% of a message with 2 variants will sent 25% to each variant.
    * 50% of a message with 3 variants will sent 16.67% to each variant.
    * 100% of a message with 2 variants will sent 50% to each variant.
    * 100% of a message with 4 variants will sent 25% to each variant.

    Any percentage other than 100% will allow you to select a winner.

    7. Review results

    View results under **Messages > Push > A/B Tests Tab**. Click any test to view variant-specific reports.

    8. [Select a Winner](#select-a-winner)

    Use performance metrics to manually select a winner.
  </Tab>

  <Tab title="Email A/B Testing">
    ### Create an Email A/B Test

    1. Go to **Messages > Email > New Email**
    2. Name your message (e.g., "Email AB Test - Subject Line")
    3. Select your segment(s)
    4. Click the **A/B Test** button

    <Frame>
      <img />
    </Frame>

    5. Add variants

    * Click **Add Variant** to duplicate and edit each new version.
    * Only change **one variable** at a time for meaningful insights.

    <Frame>
      <img />
    </Frame>

    6. A/B Test settings

    Select the percentage of your target audience that should receive each variant. See [How A/B Testing works](#how-a%2Fb-testing-works) for more details.

    The percentage is applied to the total audience, evenly distributed across each variant. Examples:

    * 25% of a message with 2 variants will sent 12.5% to each variant.
    * 25% of a message with 10 variants will sent 2.5% to each variant.
    * 50% of a message with 2 variants will sent 25% to each variant.
    * 50% of a message with 3 variants will sent 16.67% to each variant.
    * 100% of a message with 2 variants will sent 50% to each variant.
    * 100% of a message with 4 variants will sent 25% to each variant.

    Any percentage other than 100% will allow you to select a winner.

    7. Review results

    View results under **Messages > Email > A/B Tests Tab**. Click any test to view variant-specific reports.

    8. [Select a Winner](#select-a-winner)

    Use performance metrics to manually select a winner.
  </Tab>
</Tabs>

***

## Best practices for A/B Testing

### Understand benchmarks

Review past performance data so you can evaluate test success meaningfully.

### Set a goal and hypothesis

Clearly define what you're testing and what success looks like.

### Change one variable at a time

Control your experiment by isolating variables like:

* Subject lines
* Layouts
* CTA copy
* Length of copy
* Images
* Offers
* Emojis
* Colors
* Fonts
* Icons
* GIFs

### Use controls

Include your "usual" version as a baseline for measuring improvements.

Create control groups by tagging users randomly and exclude that segment. You can [Export user data](./exporting-data) and create a segment from the CSV [import](./import).

### Test simultaneously

Send all variants at the same time to avoid timing bias.

### Continue testing

Iterate based on results to continuously optimize message performance.

***

## FAQ

### Can I A/B test different segments?

Not within the standard message form. However, you can test different segments using [Journeys](./journeys-overview) with **Split Branches** and **Yes/No Branches**.

### Can I automatically select a winner?

Not yet. You must manually choose the winning variant or use 100% to send all variants.

***

<Check>
  You're done! You can now test different variants of your messages and select a winner.
</Check>

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Action buttons for push notifications
Source: https://documentation.onesignal.com/docs/en/action-buttons

Add interactive action buttons to your push notifications on iOS, Android, and the web. Learn setup via Dashboard & API, supported platforms, click handling, icons, and event tracking.

<Frame>
  <img />
</Frame>

<Info>
  This guide applies only to push notifications. For in-app messages, see [In-App Messages: How to add Click Actions](./iam-click-actions).
</Info>

Action Buttons let you add multiple, labeled actions to a single push notification, so users can respond without opening your app or site first. Depending on the operating system and device, users reveal buttons by expanding the notification (long press, swipe + View, or an expand affordance).

***

## Add action buttons

You can configure Action Buttons in [Templates](./templates), directly when composing a message in the dashboard, or via the [API](/reference/push-notification).

### Dashboard & template setup

When creating a push, open **Advanced Options > Action Buttons**.

<Frame>
  <img />
</Frame>

### API setup

* **Mobile Apps**: Use the `buttons` parameter. Pass an array of up to 3 objects with `id`, `text`, and `icon`.
* **Web (Chrome)**: Use `web_buttons`, passing up to 2 objects with `id`, `text`, `icon`, and `url`.

***

## Action button properties

* **Action ID**: A unique identifier for the specific button action. The ID of the clicked button is passed to you so you can identify which button was clicked. (e.g. 'accept-button')

  * Must be unique per button.
  * Available in the OSNotification Payload and can be accessed within the SDK Notification Opened Event Handler.
  * API: `id` property

* **Label**: The text the button should display to your users. (e.g. 'Accept')

  * API: `text` property

* **Icon**: Optional icon displayed with the button label. Not available on all platforms and operating systems. See FAQ below for details.

  * Mobile apps must include the button within its image resources. See Action Button Icons below for details.
  * Websites can use a valid publicly reachable URL to an icon. Keep this small because it's downloaded on every notification display. (e.g. `http://site.com/icon.png`)
  * API: `icon` property

* **Launch URL 1**: The URL to open when the action button of the first button is clicked. Pass `'do_not_open'` to prevent opening any URL. (e.g. 'do\_not\_open')

  * Web only
  * Max 2 web buttons
  * API: `web_buttons.url` property

### Action button icons

* iOS supports action button icons for iOS 15+
* Android stopped supporting action button icons for [Android N (AKA 7)](https://android-developers.googleblog.com/2016/06/notifications-in-android-n.html)

***

## Handle action button clicks

When a user taps a button, OneSignal delivers the Action ID to your app/site. You can either use the default behavior (open your app/site) or override it.

### Default behavior (Open App/Site, Then Handle)

1. The app/site opens (or is focused on web).
2. Your click/open listener receives the event with the Action ID. (See [mobile SDK reference](./mobile-sdk-reference#addclicklistener-push) or [web SDK reference](./web-sdk-reference#addeventlistener-notifications) for click listener details.)
3. Use the Action ID to track which button was clicked and handle the click event accordingly. This could mean deep linking to a specific screen in your app or triggering a custom event.

#### Prevent app launch from action button clicks

* **Android:** Follow [Android SDK setup > Disable default open behavior](./android-sdk-setup#disable-default-open-behavior). This lets you intercept clicks in a [Service Extensions](./service-extensions) and run custom logic (e.g. call an API) without opening the app.
* **iOS:** Include an `ios_category` on the notification to associate actions via the [UNNotificationCategory Object](https://developer.apple.com/documentation/usernotifications/unnotificationcategory). See Apple's [Declaring Your Actionable Notification Types](https://developer.apple.com/documentation/usernotifications/declaring_your_actionable_notification_types) for more details.
* **Web (Chrome):** Use the `_osp=do_not_open` magic string to prevent opening any URL. This is supported on Chrome and Firefox, but not supported for the Safari web browser.

***

## Supported platforms & limits

| Platform                  | Buttons Supported | Notes                                                          |
| ------------------------- | ----------------- | -------------------------------------------------------------- |
| iOS                       | Up to 4           | Icons on iOS 15+. Requires categories for background handling. |
| Android / Amazon / Huawei | Up to 3           | No button icons from Android 7+.                               |
| Web – Chrome              | Up to 2           | Buttons and icons supported. `_osp=do_not_open` supported.     |
| Web – Firefox             | No buttons        | `_osp=do_not_open` works for the launch URL only.              |
| Web – Safari              | No buttons        | `_osp=do_not_open` not supported. Provide a real URL.          |

<Note>Users often need to **expand** the notification to see buttons (e.g., long press on iOS, swipe + **View** on some Android OEMs).</Note>

***

## Troubleshooting

### Buttons don’t show up

* Expand the notification (long press, swipe + View, or expand).
* Verify you added Action ID and Label for each button.
* Check platform limits (e.g., only 2 buttons on Chrome).

### Clicking a button doesn’t open the browser on mobile web

If the browser is in the background or fully closed, most mobile browsers (including Chrome) will not come to the foreground or open the URL, even though click events still trigger in the service worker. This is intentional browser behavior to prevent background apps from interrupting the user.

* Most mobile browsers won’t foreground themselves from a background service worker. Clicks still fire in the worker, but the tab doesn’t open. This is intentional.
* Ensure the launch URL and the button URL are exactly identical (including trailing slashes) if you expect the tab to be focused instead of opening a new one.

### Icons don’t appear

* iOS must be 15+ for button icons.
* Android 7+ does not render action button icons.
* On web, confirm the icon URL is publicly accessible and small (fast to download).

### Why is there a close action button?

By default web push notifications on Windows 10 include the Close button. However, if you add your own action button, then this close button is removed. So, in either case the notification will remain on-screen till the user interacts with it. This is designed by Google to give the users the chance to interact with the notification.

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Android notification categories
Source: https://documentation.onesignal.com/docs/en/android-notification-categories

Set up Android notification categories (channels) in OneSignal to improve user control and customization of push notifications.

Android notification categories (aka notification channels) were introduced in Android 8.0 (Oreo) to give users greater control over how they receive notifications from your app. This allows you to categorize your notifications and define different experiences such as display behavior, sound, vibration, badges, and lock screen visibility.

For example, if you have breaking news notifications, you can create a category for them and set "Urgent" importance and a custom sound to ensure they are displayed prominently versus less important notifications that may be muted or have a default sound.

OneSignal makes it easy to create and manage these categories directly within the dashboard. Alternatively, you can define categories programmatically in your app. See [Android’s guide to creating notification channels](https://developer.android.com/develop/ui/views/notifications/channels).

<Note>
  OneSignal's Android notification categories work for Google Android, Huawei Android, and Amazon FireOS.
</Note>

<Frame>
  <img alt="Android notification categories shown in device settings" />
</Frame>

***

## Default notification categories

OneSignal automatically creates two default categories:

### Miscellaneous

Used when you do not set a category.

* **Importance:** High
* **Sound:** Default
* **Vibration:** Default
* **Badges:** Enabled
* **Lockscreen:** Private

### Restored

Used when your app is force-quit and reopened. If your app has push notifications in the Notification Center when the app is force-quit, they are removed from the device. Reopening the app recreates (restores) those notifications. The OneSignal SDK automatically sets the category to "Restored" with the following settings to prevent unwanted sounds and pop-ups from multiple restored notifications.

* **Importance:** Low
* **Sound:** Off
* **Vibration:** Off
* **Badges:** Disabled
* **Lockscreen:** Private

<Note>
  If you always send push notifications with a custom category, the "Miscellaneous" channel won’t appear on user devices. The "Restored" channel will always appear to handle restored notifications after force-quitting the app.
</Note>

### Huawei-specific behavior

On Huawei devices, OneSignal does **not** set a default category. If you don't include one, Huawei will apply **High** importance by default.

For badge control on Huawei devices, you can also use dedicated Huawei badge parameters (`huawei_badge_class`, `huawei_badge_set_num`, `huawei_badge_add_num`) in the [Create message](/reference/create-message) API. See [Badges](./badges#huawei-badges) for details.

***

## Create Android notification categories in OneSignal

Before you begin, make sure you have a [OneSignal app configured with an Android platform](./android-sdk-setup).

1. Go to **Settings > Push & In-App > Android Notification Channels** in the OneSignal Dashboard.
2. Click **Add Group** to organize your categories (e.g., “News Updates”, “Social Activity”).
3. Click **Add Channel** within the group to create a new category.

<Frame>
  <img alt="OneSignal dashboard showing where to add Android notification categories" />
</Frame>

You’ll be asked to define the following:

### Name

*User-visible.* Keep it clear and descriptive.

### Description

*User-visible.* Briefly explain the type of notifications this category will handle.

### Importance

Controls how visible and interruptive the notification is:

* **Low:** Silent, no alerts
* **Medium:** No sound/vibration, minimal visual interruption
* **High:** Plays sound or vibrates, no screen pop-up
* **Urgent:** Plays sound and appears as a heads-up or banner-style notification.

### Sound

* **Off:** No sound
* **Default:** Device’s default notification tone
* **Custom:** Upload and reference a custom sound (no file extension).
  Example: `alert_beep` (not `alert_beep.wav`)

<Card title="Notification sounds" icon="volume-high" href="./notification-sounds">
  Full setup instructions for adding custom sounds to your notifications.
</Card>

### Vibration

* **Off:** No vibration
* **Default:** Uses device’s vibration pattern
* **Custom:** Define your own using a pattern (in ms).
  Example: `0, 300, 500, 300` → Wait 0ms, vibrate 300ms, pause 500ms, vibrate 300ms.

### LED Color

Some Android devices support LED indicators:

* **Off:** No LED
* **Default:** Device default
* **Custom:** ARGB hex value (e.g., `FF0000FF` for blue)

### Badges

Shows badge count on app icon:

* **Enabled:** Badge is shown
* **Disabled:** No badge displayed

### Lockscreen visibility

* **Public:** Full content shown
* **Private:** Only app name, hides content
* **Secret:** No notification visible on lock screen

<Check>
  Once your category is created, you can use it in your notifications.
</Check>

***

## Updating categories

After a device receives a notification with a category, Android locks that category’s behavior. **Changes to importance, sound, vibration, or other settings will not apply retroactively**. For example, if you send a push notification with a category using "High" importance and sound, then change the importance to "Urgent" and use a different sound file, the next push notification to that same device with that same category will not have "Urgent" importance or the new sound.

**Options**:

* **To update behavior:** Create a new category.
* **To test changes:** Clear app data or uninstall and reinstall the app.

You can update:

* Category name (shown as "channel name" in Android settings)
* Category group name (shown as "channel group name" in Android settings)

These update in Android's notification settings when the next notification is received using that category.

***

## Deleting categories

To remove a deleted category from the user’s device:

1. Delete the category from the OneSignal dashboard.
2. Ensure all notifications are cleared from the Notification Center.
3. Have the user:
   * Put the app in the background for 60+ seconds
   * Open it again (triggers SDK sync)

The SDK will re-sync and remove the deleted category from Android settings.

***

## Adding categories to notifications

Depending on how you created the Android Category and how you are sending the message, these are the ways you can reference the category in your push notifications.

### Sending from the OneSignal Dashboard

1. Within your Template or Push Message Composer, navigate to the Android settings.
2. Under **Category**, select your category if created within the OneSignal dashboard or select **(Created in App)** if created programmatically in your app.
   * If created programmatically, also set the **Existing Channel** field to the name defined in your code.

<Frame>
  <img alt="Android category selection dropdown in the push notification composer" />
</Frame>

### Sending with the REST API

If you created the category in the OneSignal dashboard, use the `android_channel_id` in the [Create message](/reference/push-notification) API request. You can find the Channel ID in the Android Category setup screen.

<Frame>
  <img alt="Channel ID field in the Android category setup screen" />
</Frame>

If using your own programmatically created Android channels, use the `existing_android_channel_id` parameter in the [Create message](/reference/push-notification) API request and set the name as defined in your code.

***

## FAQ

### Can categories play sounds in Do Not Disturb (DND) mode?

No. OneSignal does not set `setBypassDnd` on categories. To override DND, create your own channel programmatically and enable this setting. See [setBypassDnd](https://developer.android.com/reference/android/app/NotificationChannel#setBypassDnd\(boolean\)).

### Can I localize category names or descriptions?

No. OneSignal does not support multiple languages for categories. To support localization, define your own Android channels and reference them via `existing_android_channel_id` in your push API requests.

### Why is my Android category not working?

There are several reasons why your Android category may not be working as expected. To troubleshoot, check the following:

* **What is not working?**
  * Is the sound file not playing?
  * Is it not displaying on the device?
  * Do you not see the category in the Android Notification Settings?
* **How was the category created?**
  * If created in the OneSignal dashboard, make sure the settings are defined as you expect.
  * If created programmatically in your app, review your code. See [Android’s guide to creating notification channels](https://developer.android.com/develop/ui/views/notifications/channels).
* **Review the category settings:**
  * Make sure the settings are defined as you expect.
  * Is the sound file being referenced correctly? See the [Sound](#sound) section above.
  * Is the category name or ID being referenced correctly when sending the message?
* **Did you update the settings after sending a notification?**
  * If you updated the settings after sending a notification, Android will not apply those updates to your device. See [Updating categories](#updating-categories) above.
* **Check OneSignal SDK initialization:**
  * Make sure OneSignal is initialized in the `Application` class, not an `Activity`. See [Android SDK Setup](./android-sdk-setup).

<Info>
  Still need help? We're here to assist! Email `support@onesignal.com` with the above information including:

  * The Android category code if created programmatically in your app
  * The URL to the message in your OneSignal dashboard with the issue

  We'll assist you as soon as possible!
</Info>

***

## Related pages

<Columns>
  <Card title="Notification sounds" icon="volume-high" href="./notification-sounds">
    Set up custom notification sounds for Android, iOS, and other platforms.
  </Card>

  <Card title="Badges" icon="circle-1" href="./badges">
    Configure badge counts on app icons across platforms.
  </Card>

  <Card title="Android SDK setup" icon="android" href="./android-sdk-setup">
    Install and initialize the OneSignal Android SDK in your app.
  </Card>

  <Card title="Create message API" icon="code" href="/reference/create-message">
    Send push notifications programmatically using the REST API.
  </Card>
</Columns>


# Apps, Organizations, & Accounts
Source: https://documentation.onesignal.com/docs/en/apps-organizations

Add, rename, move, and delete OneSignal apps and organizations. Understand the relationship between accounts, apps, and organizations.

When you sign up at [OneSignal.com](https://onesignal.com), a user account is created and tied to your email address. With your account, you can create, manage, or be invited to multiple **Apps** and **Organizations**.

<Note>
  If your company already has a OneSignal App or Organization, email the account admin to request an invite. Share the [Manage Team Members](./manage-team-members) guide to help them give you access.
</Note>

***

## OneSignal account structure

Your email address is used to log in to your OneSignal account. From there, you can access the **Apps** and **Organizations** in which you are a [Team Member](./manage-team-members).

### Apps vs. Organizations

* A **OneSignal App** holds user and messaging data for a single project, across all platforms (web, iOS, Android, email, etc.). Each app exists within a single Organization.
* A **OneSignal Organization** is a container for managing multiple apps, billing, and team permissions.

You can have:

* Unlimited apps (free to create)
* Multiple organizations (free or paid)
* Apps for separate environments (e.g., dev, staging, production)
* Different access levels per app or organization

***

## Access levels and roles

OneSignal supports two levels of access:

### App-level access

* Access to only the specific app(s) a user is invited to.
* Cannot view billing or upgrade plan settings.

### Organization-level access

* Access to all apps within the organization.
* Only **Admin** roles can manage billing and upgrades.

### User roles

Access can be further scoped by roles:

#### Organization Roles

| Role        | Best for                   | Access summary                                                                                                                                                                |
| ----------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Admin       | Developers, Owners         | Full control over all org settings, billing, and messaging. Automatically includes all App Admin privileges across every app in the org                                       |
| Finance     | Finance teams              | View org settings, apps, members, and billing. Edit billing. No app-level permissions                                                                                         |
| Operations  | Ops teams                  | View access across all apps plus manage suppressions and sender identities                                                                                                    |
| Editor      | Marketers, PMs             | Full messaging workflow: create segments, build and send messages, manage webhooks and imports. Cannot modify underlying user or subscription records, or change app settings |
| Composer    | Content writers, Designers | Create and edit messages, templates, segments, and journeys. Cannot send, activate, or delete most content. No export access                                                  |
| Viewer      | Analysts, Read-only users  | View-only access across all apps. Cannot edit, send, or export                                                                                                                |
| Team Member | Minimal access users       | Can view the org and its apps list. No app-level permissions on its own. Access is layered on through app-level role assignments                                              |

#### App Roles

| Role       | Best for                    | Access summary                                                                                                       |
| ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Admin      | App owners, Lead developers | Full control over the app including settings, keys, integrations, and team management                                |
| Operations | Ops teams                   | View access across app features plus manage suppressions and sender identities                                       |
| Editor     | Marketers, PMs              | Create, edit, send, and delete messages and related content. Manage webhooks and imports. Cannot change app settings |
| Composer   | Content writers             | Create and edit messages, templates, and segments. Cannot send or activate. No export access                         |
| Viewer     | Read-only users             | View-only access to app data. Cannot edit, send, or export                                                           |

<Card title="Manage team members" icon="users" href="./manage-team-members">
  Invite users, assign roles, and manage access at the app or organization level.
</Card>

***

## Managing your user account

Enable [two-factor authentication](./2-step-authentication) to add an extra layer of security to your account. See [Data collection & security FAQ](./data-questions) for details.

### Reset password or email

1. Navigate to [Account Management](https://dashboard.onesignal.com/profile) or click **your email drop-down > Manage Account**.
2. Add your Email, New Password, and Confirm Password.
3. Click **Submit**.

<Frame>
  <img alt="OneSignal account management page showing email and password fields" />
</Frame>

### Delete your account

<Warning>
  Deleting your user account only removes your email from OneSignal. It does not delete apps or downgrade paid plans. Be sure to [Downgrade your plan](./billing-faq) if needed.
</Warning>

To delete:

1. Navigate to [Account Management](https://dashboard.onesignal.com/profile) or click **your email drop-down > Manage Account**.
2. Scroll down to **Delete Account**.
3. If you don't have the option to delete your account, contact `ar@onesignal.com`.

***

## Manage apps

* **Create an app**:
  * Log in at [onesignal.com](https://onesignal.com) and click **New App/Website**.
  * Or use the [Create an App API](/reference/create-an-app).

* **Rename an app**:
  * From the dashboard **All Apps** page, click **Options > Rename** next to the app.
  * Or use the [Update an App API](/reference/update-an-app)

* **Find App ID**:
  * See [Keys & IDs](./keys-and-ids).

* **Delete an app**:
  * You can delete apps within Free organizations and under 5,000 total subscriptions from the **All Apps** page via **Options > Delete**.
  * For larger apps, contact `support@onesignal.com`.

***

## Manage organizations

Enable [two-factor authentication](./2-step-authentication) at the organization level to require all team members to use 2FA.

* **Create an organization**:
  * Visit the **Organizations** page or click **New Organization** in the dashboard (no paid plan required).

* **Rename an organization**:
  * In **Organizations**, click **Options > Rename** next to the organization.

* **Find Org ID**:
  * Go to **Organizations**, select your organization, and copy the UUID from the address bar. Example: `https://dashboard.onesignal.com/organizations/THE_ORG_ID/apps`

* **Delete an organization**:
  * Go to **Organizations**, click **Options > Remove**.
  * You must move the apps out of the organization before deleting it.
  * If you need assistance, contact `support@onesignal.com` with the Org ID you want to delete.

### Add or move apps between organizations

* **Add app to organization**:
  * Go to **Organizations > select your Organization > Move Apps Into Organization**.
  * Select your apps and click **Move Apps**.
  * You need:
    * Admin access to the source Organization (where the app currently lives)
    * Admin access to the destination Organization (where you want to move it)
    * Admin access to the App itself
    * The app must currently belong to a Free Organization (apps in paid organizations cannot be moved self-service).

<Warning>
  When moving an app between two organizations, you must be an Admin on both. Being an Admin on the destination Organization and the app is not enough. You also need Admin access to the source Organization. If you are unsure who the source Organization admin is, contact `support@onesignal.com` with your App ID and we can help identify them.
</Warning>

<Note>
  If you need assistance, email `support@onesignal.com` with:

  * The App ID(s) you want to move
  * The Org ID to move them to.
  * You must contact Support from an email with Admin access to the Apps and Organization.
</Note>

***

## FAQ

### Where can I see when my app was created?

Use the [View App](/reference/view-an-app) or [View Apps](/reference/view-apps) API to get the `created_at` timestamp.

### Why do I see limitations on a paid plan?

Your app might not be assigned to the correct paid Organization. Follow [Add or move apps between organizations](#add-or-move-apps-between-organizations) to move your app to the paid org. If you need help, see the support contact details in that section.

### What are the best practices for agencies?

Agencies can manage client apps using one of two approaches:

1. **Centralized billing**
   Use a single Organization to manage and pay for all client apps.
2. **Client-managed billing**
   Each client sets up their own Organization and handles their own billing.

You can mix paid and free apps by assigning them to the appropriate Organization.

Need help? [Contact our Sales Team](https://onesignal.com/contact).

### How can we access analytics, messages, and users across multiple Apps?

OneSignal does not have a single cross-app dashboard view. Each app's data is accessed separately. Here are the recommended approaches for working across apps:

* **Analytics** — Use [Event Streams](./event-streams) to route message delivery and engagement data from each app to a centralized analytics platform like Snowflake, BigQuery, or Amplitude.
* **Messaging** — Use the [Create message API](/reference/create-message) to send messages to multiple apps in parallel from your backend. You can also create [Templates](./templates) once and copy them across apps using the [Copy template API](/reference/copy-template-to-another-app).
* **Users** — Use the [REST API](/reference/view-user) to query user data per app. If you need a unified view across apps, export Subscription records per app via [CSV export](/reference/csv-export) or stream events via Event Streams to an external data warehouse.

### How do we change our dashboard timezone?

Dashboard graphs display in UTC and cannot be changed. All other dates and times use your browser's timezone. To change the displayed timezone, update the timezone setting in your browser or operating system.

***

## Related pages

<Columns>
  <Card title="Manage team members" icon="users" href="./manage-team-members">
    Invite users, assign roles, and manage access at the app or organization level.
  </Card>

  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    Find your App ID, REST API key, and other credentials.
  </Card>

  <Card title="Two-factor authentication" icon="shield-halved" href="./2-step-authentication">
    Enable 2FA for your account or require it for your organization.
  </Card>

  <Card title="Billing FAQ" icon="credit-card" href="./billing-faq">
    Manage plans, billing, and subscriptions across organizations.
  </Card>
</Columns>


# Audit Logs
Source: https://documentation.onesignal.com/docs/en/audit-logs

Track and review user activity across your OneSignal organization for security, compliance, and accountability. Export to JSONL or query via the REST API.

## Overview

Audit Logs provide a **read-only** record of user actions across your OneSignal organization. Use audit logs to:

* **Investigate security incidents** by reviewing login activity, IP addresses, and user sessions.
* **Meet compliance requirements** by providing evidence for SOC 2, HIPAA, and internal audits.
* **Maintain accountability** by tracking who created, updated, or deleted templates, journeys, and notifications.
* **Export data** to JSONL for offline analysis, or **query the REST API** for programmatic access and SIEM integration.

Audit logs are **immutable**. You cannot edit or delete entries, ensuring an accurate and trustworthy audit trail.

<Frame>
  <img alt="Audit Logs table showing user actions across an organization" />
</Frame>

### Plan availability

Audit log retention varies by plan.

| Plan         | Retention Period | Notes                                                   |
| ------------ | ---------------- | ------------------------------------------------------- |
| Free         | 48 hours         | Included                                                |
| Growth       | 48 hours         | Included                                                |
| Professional | 48 hours         | Upgrade to 90 days with Legal & Security Package add-on |
| Enterprise   | 90 days          | Included                                                |

<Note>
  To increase retention or learn more about the Legal & Security Package, contact your Account Manager or our [Sales Team](https://onesignal.com/contact).
</Note>

***

## Accessing Audit Logs

### Org Level Audit Logs

Audit logs are available at the **Organization level** and include activity across **all apps** in that organization.

**Requirements:**

* You must be an **Organization Admin**. See [Manage Team Members](./manage-team-members) to update roles.

To access audit logs:

1. Navigate to **Organizations**
2. Select your organization
3. Click **Audit Logs**

### App Level Audit Logs

In addition to organization-level audit logs, you can view audit logs for a specific app:

1. Navigate to your **App**
2. Go to **Settings**
3. Click **Audit Logs**

App-level audit logs show only activity for that specific app, making it easier to investigate app-specific changes.

**Requirements:**

* You must be an **App Admin** or **Organization Admin**

***

## Understanding the Audit Log

Each row represents a single user action. You can customize visible columns using the Columns button in the top-right corner.

<Frame>
  <img alt="Audit logs columns button showing the available columns" />
</Frame>

| Column          | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| **Date & Time** | When the action occurred                                         |
| **User Action** | The type of action performed (e.g., Logged In, Template Updated) |
| **Email**       | Email address of the user who performed the action               |
| **Org Role**    | The user's organization-level role (Admin, Editor, Viewer)       |
| **App Role**    | The user's app-level role, if applicable                         |
| **Item Type**   | The type of object affected (Template, Notification, Journey)    |
| **Item Name**   | The name of the affected object                                  |
| **App Name**    | The app where the action occurred                                |
| **User**        | Display name of the user                                         |
| **IP Address**  | The IP address from which the action was performed               |

***

## Tracked events

Audit logs track user actions across your organization, including logins, template changes, notification activity, journey updates, member management, billing events, and more.

For a comprehensive list of all tracked events, see the [Complete event reference](#complete-event-reference).

***

## Viewing event details

Click the expand arrow (›) next to any event to view additional details:

<Frame>
  <img alt="Expanded audit log event showing detailed information including App ID, Browser, Event ID, and IP Address" />
</Frame>

Expanded details include:

| Field           | Description                                                     |
| --------------- | --------------------------------------------------------------- |
| **API Version** | API version used (when applicable)                              |
| **App ID**      | Unique identifier for the app                                   |
| **App Name**    | Name of the app where the action occurred                       |
| **App Role**    | User's role within the specific app                             |
| **Browser**     | User agent string (browser and OS information)                  |
| **Channel**     | Notification channel (push, email, sms) for notification events |
| **Email**       | User's email address                                            |
| **Event ID**    | Unique identifier for this specific event                       |
| **IP Address**  | Full IP address of the user                                     |
| **Item Name**   | Name of the affected object                                     |
| **Item Type**   | Type of object (template, notification, etc.)                   |
| **Location**    | Geographic location based on IP address                         |
| **Name**        | Display name of the user                                        |
| **Org ID**      | Unique identifier for the organization                          |
| **Org Role**    | User's organization-level role                                  |
| **Target ID**   | Unique identifier for the affected object                       |
| **Target Role** | Role associated with the target (for member events)             |
| **Timestamp**   | Formatted date and time of the event                            |
| **User Action** | The action type (e.g., notification.sent)                       |
| **User Agent**  | Full browser/client user agent string                           |
| **Version**     | Event schema version                                            |

***

## Search and filters

Use the search and filter options to find specific events:

### Search by email

Enter an email address in the search bar to find all actions performed by a specific user.

### Date range

Select from the following preset date ranges:

* **Last 24 hours**
* **Last 48 hours** (default)
* **Last 7 days**
* **Last 30 days**
* **Last 90 days** (requires extended retention)
* **Custom** - Select specific start and end dates

<Note>
  Date range options beyond your plan's retention period will display a lock icon. Contact sales for extended audit log history.
</Note>

### Filters

Click **Filters** to narrow results by:

| Filter          | Description                                               |
| --------------- | --------------------------------------------------------- |
| **User Action** | Filter by action type (Logged In, Template Updated, etc.) |
| **App ID**      | Filter by a specific app's unique identifier              |
| **IP Address**  | Filter by IP address                                      |
| **Item Type**   | Filter by object type (Template, Notification, Journey)   |
| **Target ID**   | Filter by the unique ID of the affected object            |

### Item type values

Filter audit logs by the type of object affected:

| Item Type         | Description                       |
| ----------------- | --------------------------------- |
| A/B Test          | A/B test experiments              |
| API Key           | API keys and tokens               |
| App               | Application settings              |
| Data Feed         | Data feed configurations          |
| Dynamic Content   | Dynamic content blocks            |
| Email Domain      | Email sending domains             |
| Email Suppression | Email suppression list entries    |
| Event Stream      | Event stream destinations         |
| Export            | Data exports                      |
| In-App Message    | In-app message campaigns          |
| Integration       | Third-party integrations          |
| Journey           | Automated journey workflows       |
| Member            | Team members                      |
| Notification      | Push, email, or SMS notifications |
| Organization      | Organization settings             |
| Segment           | Audience segments                 |
| Subscription      | User subscriptions                |
| Template          | Message templates                 |
| User              | End users/subscribers             |
| Webhook           | Webhook configurations            |

***

## Exporting audit logs

Export audit log data to a zipped `.json` file for offline analysis, compliance reporting, or integration with external tools.

To export audit logs:

1. Navigate to the **Audit Logs** page (at the organization or app level).
2. Apply any desired [filters](#search-and-filters) and date range.
3. Click **Export**.
4. The `.json.gz` file(s) will be emailed to you.

You'll have 3 days from creation to download your file before it expires.

### Export availability

The export window matches your plan's retention period.

| Plan         | Export Window                                        |
| ------------ | ---------------------------------------------------- |
| Free         | 2 days                                               |
| Growth       | 2 days                                               |
| Professional | 2 days (up to 90 days with Legal & Security Package) |
| Enterprise   | Up to 90 days                                        |

<Tip>
  Combine exports with the [Audit Logs API](/reference/list-audit-logs) for automated, recurring data pulls.
</Tip>

***

## API access

Query audit logs programmatically using the REST API. The API supports pagination, time-scoped queries, and filtering by app, action type, actor, target, and IP address.

**Requirements:**

* **Enterprise plan** with the audit logs entitlement enabled
* **Organization API Key** for authentication (app-level keys are not accepted)

See the [List audit logs API reference](/reference/list-audit-logs) for endpoint details, parameters, and example responses.

***

## Data retention

Audit log data is retained based on your plan:

* **Free and Growth plans**: 48-hour retention
* **Professional plan**: 48-hour retention by default, or 90-day retention with the Legal & Security Package add-on
* **Enterprise plan**: 90-day retention included

After the retention period, audit log entries are automatically removed and cannot be recovered.

<Info>
  Need longer retention? Contact your Account Manager or our [Sales Team](https://onesignal.com/contact) to discuss upgrading your plan.
</Info>

***

## Complete event reference

The following is a comprehensive list of all events tracked in audit logs, organized by category.

<AccordionGroup>
  <Accordion title="App events">
    | Action                 | Description                          |
    | ---------------------- | ------------------------------------ |
    | App Created            | A new app was created                |
    | App Renamed            | An app was renamed                   |
    | App Deleted            | An app was deleted                   |
    | App Settings Updated   | App settings were modified           |
    | App API Key Reset      | App API key was reset                |
    | App Auth Token Created | App authentication token was created |
    | App Auth Token Updated | App authentication token was updated |
    | App Auth Token Deleted | App authentication token was deleted |
    | App Auth Token Rotated | App authentication token was rotated |
  </Accordion>

  <Accordion title="Template events">
    | Action           | Description                        |
    | ---------------- | ---------------------------------- |
    | Template Created | A new message template was created |
    | Template Updated | An existing template was modified  |
    | Template Deleted | A template was removed             |
  </Accordion>

  <Accordion title="Notification events">
    | Action                 | Description                           |
    | ---------------------- | ------------------------------------- |
    | Notification Created   | A new notification was created        |
    | Notification Sent      | A notification was sent               |
    | Notification Updated   | A notification was modified           |
    | Notification Canceled  | A scheduled notification was canceled |
    | Notification Deleted   | A notification was removed            |
    | Notification Previewed | A notification was previewed          |
  </Accordion>

  <Accordion title="A/B test events">
    | Action                   | Description                           |
    | ------------------------ | ------------------------------------- |
    | A/B Test Created         | A new A/B test was created            |
    | A/B Test Updated         | An A/B test was modified              |
    | A/B Test Deleted         | An A/B test was deleted               |
    | A/B Test Canceled        | An A/B test was canceled              |
    | A/B Test Winner Selected | A winner was selected for an A/B test |
  </Accordion>

  <Accordion title="Journey events">
    | Action            | Description                      |
    | ----------------- | -------------------------------- |
    | Journey Created   | A new journey was created        |
    | Journey Updated   | An existing journey was modified |
    | Journey Set Live  | A journey was activated          |
    | Journey Archived  | A journey was archived           |
    | Journey Resumed   | A paused journey was resumed     |
    | Journey Scheduled | A journey was scheduled          |
    | Journey Deleted   | A journey was deleted            |
  </Accordion>

  <Accordion title="In-app message events">
    | Action                  | Description                      |
    | ----------------------- | -------------------------------- |
    | In-App Message Created  | A new in-app message was created |
    | In-App Message Updated  | An in-app message was modified   |
    | In-App Message Deleted  | An in-app message was deleted    |
    | In-App Message Enabled  | An in-app message was enabled    |
    | In-App Message Disabled | An in-app message was disabled   |
  </Accordion>

  <Accordion title="Segment events">
    | Action                 | Description                  |
    | ---------------------- | ---------------------------- |
    | Segment Created        | A new segment was created    |
    | Segment Updated        | A segment was modified       |
    | Segment Deleted        | A segment was deleted        |
    | Segment Paused         | A segment was paused         |
    | Segment Resumed        | A segment was resumed        |
    | Segment Set as Default | A segment was set as default |
  </Accordion>

  <Accordion title="Member events">
    | Action                     | Description                                    |
    | -------------------------- | ---------------------------------------------- |
    | Member Created             | A new team member was created                  |
    | Member Deleted             | A team member was deleted                      |
    | Member Role Changed in App | A member's app-level role was changed          |
    | Member Role Changed in Org | A member's organization-level role was changed |
    | Member Added to App        | A member was added to an app                   |
    | Member Removed from App    | A member was removed from an app               |
    | Member Added to Org        | A member was added to the organization         |
    | Member Removed from Org    | A member was removed from the organization     |
  </Accordion>

  <Accordion title="Organization events">
    | Action                | Description                                 |
    | --------------------- | ------------------------------------------- |
    | Organization Created  | A new organization was created              |
    | Organization Updated  | Organization settings were modified         |
    | Organization Deleted  | An organization was deleted                 |
    | Organization Disabled | The organization was disabled               |
    | Organization Enabled  | The organization was enabled                |
    | Logged In             | A user logged in                            |
    | Logged Out            | A user logged out                           |
    | User Added to Org     | A user was added to the organization        |
    | User Removed from Org | A user was removed from the organization    |
    | User Role Changed     | A user's role was changed                   |
    | App Added to Org      | An app was added to the organization        |
    | App Removed from Org  | An app was removed from the organization    |
    | 2FA Required          | Two-factor authentication was made required |
    | 2FA Made Optional     | Two-factor authentication was made optional |
    | Auth Token Created    | Organization auth token was created         |
    | Auth Token Updated    | Organization auth token was updated         |
    | Auth Token Deleted    | Organization auth token was deleted         |
    | Auth Token Rotated    | Organization auth token was rotated         |
  </Accordion>

  <Accordion title="Billing events">
    | Action                 | Description                    |
    | ---------------------- | ------------------------------ |
    | Subscription Created   | A new subscription was created |
    | Subscription Updated   | A subscription was modified    |
    | Subscription Canceled  | A subscription was canceled    |
    | Payment Method Added   | A payment method was added     |
    | Payment Method Updated | A payment method was updated   |
  </Accordion>

  <Accordion title="Webhook events">
    | Action              | Description               |
    | ------------------- | ------------------------- |
    | Webhook Created     | A new webhook was created |
    | Webhook Updated     | A webhook was modified    |
    | Webhook Deleted     | A webhook was deleted     |
    | Webhook Tested      | A webhook was tested      |
    | Webhook Activated   | A webhook was activated   |
    | Webhook Deactivated | A webhook was deactivated |
  </Accordion>

  <Accordion title="Event stream events">
    | Action                   | Description                     |
    | ------------------------ | ------------------------------- |
    | Event Stream Created     | A new event stream was created  |
    | Event Stream Updated     | An event stream was modified    |
    | Event Stream Deleted     | An event stream was deleted     |
    | Event Stream Activated   | An event stream was activated   |
    | Event Stream Deactivated | An event stream was deactivated |
    | Event Stream Tested      | An event stream was tested      |
  </Accordion>

  <Accordion title="Data feed events">
    | Action                | Description                 |
    | --------------------- | --------------------------- |
    | Data Feed Created     | A new data feed was created |
    | Data Feed Updated     | A data feed was modified    |
    | Data Feed Deleted     | A data feed was deleted     |
    | Data Feed Activated   | A data feed was activated   |
    | Data Feed Deactivated | A data feed was deactivated |
    | Data Feed Tested      | A data feed was tested      |
  </Accordion>

  <Accordion title="Integration events">
    | Action                       | Description                        |
    | ---------------------------- | ---------------------------------- |
    | Integration Activated        | An integration was activated       |
    | Integration Deactivated      | An integration was deactivated     |
    | Integration Settings Updated | Integration settings were modified |
  </Accordion>

  <Accordion title="Import events">
    | Action         | Description              |
    | -------------- | ------------------------ |
    | Import Created | A new import was created |
    | Import Updated | An import was modified   |
    | Import Started | An import was started    |
    | Import Failed  | An import failed         |
  </Accordion>

  <Accordion title="Export events">
    | Action         | Description              |
    | -------------- | ------------------------ |
    | Export Created | A new export was created |
  </Accordion>

  <Accordion title="User events">
    | Action       | Description            |
    | ------------ | ---------------------- |
    | User Created | A new user was created |
    | User Updated | A user was modified    |
    | User Deleted | A user was deleted     |
  </Accordion>

  <Accordion title="Subscription events">
    | Action               | Description                    |
    | -------------------- | ------------------------------ |
    | Subscription Created | A new subscription was created |
    | Subscription Updated | A subscription was modified    |
    | Subscription Deleted | A subscription was deleted     |
  </Accordion>

  <Accordion title="Custom event events">
    | Action                         | Description                                   |
    | ------------------------------ | --------------------------------------------- |
    | Custom Event Retention Updated | Custom event retention settings were modified |
  </Accordion>

  <Accordion title="Dynamic content events">
    | Action                  | Description                             |
    | ----------------------- | --------------------------------------- |
    | Dynamic Content Created | A new dynamic content block was created |
    | Dynamic Content Updated | A dynamic content block was modified    |
    | Dynamic Content Deleted | A dynamic content block was deleted     |
  </Accordion>

  <Accordion title="Email Domain events">
    | Action                      | Description                              |
    | --------------------------- | ---------------------------------------- |
    | Email Domain Created        | A new email sending domain was added     |
    | Email Domain Activated      | An email domain was activated            |
    | Email Domain Deactivated    | An email domain was deactivated          |
    | Email Domain Deleted        | An email domain was removed              |
    | Email Domain Sends Canceled | Sending was canceled for an email domain |
  </Accordion>

  <Accordion title="Email Suppression events">
    | Action              | Description                                            |
    | ------------------- | ------------------------------------------------------ |
    | Suppression Created | An email address was added to the suppression list     |
    | Suppression Deleted | An email address was removed from the suppression list |
  </Accordion>
</AccordionGroup>

***

## FAQ

### Who can access audit logs?

**Organization-level audit logs:** Organization Admins can access audit logs for the entire organization.

**App-level audit logs:** App Admins can access audit logs for apps they administer. Organization Admins can also access app-level audit logs for all apps in their organization.

See [Manage Team Members](./manage-team-members) to update roles.

### Can I view audit logs for a specific app?

Yes. Navigate to your app's **Settings** page and select **Audit Logs** to view activity for that specific app only. This is useful for investigating changes to a particular app without seeing activity from other apps in your organization.

### Can I export audit logs?

Yes. Click **Export** on the Audit Logs page to download a `.jsonl` file of the currently filtered results. The export window depends on your plan — see [Export availability](#export-availability) for details. For programmatic access, use the [List audit logs API](/reference/list-audit-logs) (Enterprise plans only).

### Can audit logs be deleted?

No. Audit logs are immutable and cannot be deleted by any user.

### Are API actions logged?

Yes, for select actions. API actions performed with Organization and App API keys are logged for auth token management (create, update, rotate, delete), app management (create, update), segment management (create, update, delete), template management (create, update, delete, copy to app), and subscription CSV export. The actor type displays as "API Key" with the key's name and scope. Additional API actions are planned for future releases.

### How do I increase my retention period?

Enterprise customers receive 90-day retention automatically. Professional customers can upgrade to 90-day retention by adding the Legal & Security Package. Contact your Account Manager or our [Sales Team](https://onesignal.com/contact) to discuss your requirements.

***


# Badges
Source: https://documentation.onesignal.com/docs/en/badges

Manage app icon badge counts for push notifications on iOS, Android, and Huawei, including auto-clearing, API control, and native badge logic.

Badges are the little numbered dots that appear on your mobile app icon. They help capture user attention and can influence engagement behavior. On iOS in particular, badges require additional setup and offer flexible control, as outlined below.

<Note>
  For Android Web Push notifications, the badge refers to the small icon shown on notifications—not the app icon—and can be customized. See [Web Push Badges](./push#badges).
</Note>

***

## Android badges

Android app icon badge behavior can be managed through [Android notification categories](./android-notification-categories). You can control whether a category (channel) displays a badge and set badge behavior on a per-category basis.

***

## Huawei badges

On Huawei devices, a badge can be displayed as a number or a dot on the app icon, depending on the user's device settings. Badges help indicate unread messages or pending actions, encouraging users to open the app. OneSignal lets you control Huawei badge counts directly through the dashboard or API.

<Accordion title="How Huawei badges work">
  The badge displays on the app icon as either a **numeric count** or a **dot**, depending on the user's device setting (**Settings > Notifications > App icon badges**). Your API call controls the underlying count; the device decides the visual style.

  **Parameters**

  | Parameter              | Type    | Range | Description                                                                                                                                                          |
  | ---------------------- | ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `huawei_badge_class`   | string  | —     | **(Required)** Fully qualified class name of your app's launcher Activity (e.g., `com.example.myapp.MainActivity`). Tells the Huawei system which app icon to badge. |
  | `huawei_badge_set_num` | integer | 0–99  | Sets the badge to an exact number. `0` clears the badge.                                                                                                             |
  | `huawei_badge_add_num` | integer | 1–99  | Increments the existing badge count by this amount.                                                                                                                  |

  **Behavior rules**

  * `huawei_badge_class` is required for any badge operation.
  * If both `huawei_badge_set_num` and `huawei_badge_add_num` are provided, `huawei_badge_set_num` takes priority.
  * If neither is provided (but `huawei_badge_class` is set), the badge count increments by 1 by default.

  **Send Huawei push with badges**

  <Tabs>
    <Tab title="Dashboard">
      1. Go to **Messages > Push** or **Templates**
      2. Under **Platform Settings > Send to Huawei Android > Badge**
      3. Choose either:
         * **Don't set** — badge is not affected by this notification
         * **Set to** — sets the badge to a specific number (0–99)
         * **Increase by** — increments the existing badge count (1–99)
    </Tab>

    <Tab title="API">
      Use the following parameters in the [Create message](/reference/create-message) API:

      * `huawei_badge_class` — *(string, required for badge)* The fully qualified class name of the app's launcher activity (e.g., `"com.example.myapp.MainActivity"`)
      * `huawei_badge_set_num` — *(integer, 0–99)* Sets the badge count to this exact number. Set to `0` to clear the badge.
      * `huawei_badge_add_num` — *(integer, 1–99)* Increments the existing badge count by this number. If omitted along with `huawei_badge_set_num`, defaults to incrementing by 1.

      **Set badge to a specific number:**

      ```json theme={null}
      {
        "huawei_badge_class": "com.example.myapp.MainActivity",
        "huawei_badge_set_num": 5
      }
      ```

      **Increment badge by a specific amount:**

      ```json theme={null}
      {
        "huawei_badge_class": "com.example.myapp.MainActivity",
        "huawei_badge_add_num": 1
      }
      ```

      **Clear the badge:**

      ```json theme={null}
      {
        "huawei_badge_class": "com.example.myapp.MainActivity",
        "huawei_badge_set_num": 0
      }
      ```
    </Tab>
  </Tabs>

  **Clearing badges**

  Huawei does **not** automatically clear the badge when a user opens the app or taps a notification. To clear the badge, you have two options:

  * **Via the API or dashboard**: Send a notification with `huawei_badge_set_num` set to `0` (or use **Set to > 0** in the dashboard). This can be a [data/background notification](./data-notifications) if you don't want a visible notification to appear.
  * **Via client-side code**: Your app can clear the badge locally using the Huawei badge API. This requires the `com.huawei.android.launcher.permission.CHANGE_BADGE` permission in your `AndroidManifest.xml`. See [Huawei's badge development guide](https://developer.huawei.com/consumer/en/doc/hmscore-guides/android-badging-0000001050042083) for implementation details.

  <Note>
    The `huawei_badge_set_num` parameter requires EMUI 10.0.0 or later and Push SDK 10.1.0 or later. On older devices, only `huawei_badge_add_num` is supported.
  </Note>
</Accordion>

***

## iOS badges

To ensure badge counts increment correctly on iOS, you must configure:

* The `OneSignalNotificationServiceExtension`
* App Groups

See [Mobile SDK setup](./mobile-sdk-setup) for full instructions.

By default, the OneSignal SDK will:

1. Clear the app icon badge when the app is opened.
2. Remove notifications from the Notification Center.

If you want to retain notifications and manage badge logic manually (e.g., using your own counter or syncing state across devices), you can disable this automatic behavior.

**Common use cases for manual badge control**

* Reset badge when the app launches or resumes
* Increment badge when a notification is received in the foreground
* Decrement when a message is read or dismissed
* Sync badge state across devices or app extensions via App Groups or your backend

### Disable automatic notification and badge clearing

In your app's `info.plist`, add the Key: `OneSignal_disable_badge_clearing` with Boolean type to Value `YES`

<Frame>
  <img alt="Xcode Info.plist editor showing OneSignal_disable_badge_clearing set to YES" />
</Frame>

```xml theme={null}
<key>OneSignal_disable_badge_clearing</key>
<true/>
```

This prevents the SDK from automatically removing notifications or resetting the badge when the app opens.

#### iOS native badge management

If you disable OneSignal's automatic badge clearing, you can use Apple's native APIs to control badge behavior.

<Warning>
  Apple deprecated `UIApplication.shared.applicationIconBadgeNumber` in iOS 17. You should now use the following methods from the [UserNotifications framework](https://developer.apple.com/documentation/UserNotifications/UNUserNotificationCenter/setBadgeCount\(_:withCompletionHandler:\)):
</Warning>

**Set badge count**

To set the badge on the app icon to a specific value:

```swift theme={null}
import UserNotifications
import UIKit

if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(5) { error in
    if let error = error {
      print("Failed to set badge count: \(error.localizedDescription)")
    } else {
      print("Badge count updated successfully.")
    }
  }
} else {
  UIApplication.shared.applicationIconBadgeNumber = 5
}
```

**Get current badge count**

iOS does not provide a method to retrieve the current badge count from the system. You must keep track of the badge count in your app's state (for example, using `UserDefaults`, your app's data model, or syncing with your backend).

```swift theme={null}
// Example: Store and retrieve badge count using UserDefaults
let badgeCount = UserDefaults.standard.integer(forKey: "badgeCount")
// Update badge count as needed
UserDefaults.standard.set(badgeCount, forKey: "badgeCount")
```

**Increment or decrement badge**

You must manage badge logic manually, as relative changes (like +1 or -1) are not supported in payloads. Update your stored badge count and then set it:

```swift theme={null}
// Example: Increment badge count and update system badge
let currentCount = UserDefaults.standard.integer(forKey: "badgeCount")
let updatedCount = max(0, currentCount + 1)
UserDefaults.standard.set(updatedCount, forKey: "badgeCount")

if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(updatedCount)
} else {
  UIApplication.shared.applicationIconBadgeNumber = updatedCount
}
```

**Clear badge**

To remove the badge entirely:

```swift theme={null}
if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(0)
} else {
  UIApplication.shared.applicationIconBadgeNumber = 0
}
```

### Send iOS push with badges

You can set the badge count in the OneSignal dashboard or using the API.

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Messages > Push** or **Templates**.
    2. Under **Platform Settings > Send to Apple iOS > Badges**.
    3. Choose either:
       * Set to a specific number.
       * Increase by a relative amount.

    <Frame>
      <img alt="OneSignal dashboard push message form showing iOS badge count options" />
    </Frame>
  </Tab>

  <Tab title="API">
    Use the following parameters in the [Create message](/reference/create-message) API:

    * `ios_badgeType` — Set to `SetTo` or `Increase`.
    * `ios_badgeCount` — The number to set or increase by.

    ```json theme={null}
    {
      "ios_badgeType": "Increase",
      "ios_badgeCount": 1
    }
    ```
  </Tab>
</Tabs>

When sending iOS push notifications, the badge count changes based on these options.

If the app is open, the badge count resets unless you [disable automatic badge clearing](#disable-automatic-notification-and-badge-clearing).

***

## FAQ

### Why isn't my badge count incrementing on iOS?

Ensure you have configured the `OneSignalNotificationServiceExtension` and App Groups. Without these, badge counts cannot increment correctly. See [Mobile SDK setup](./mobile-sdk-setup) for full instructions.

### How do I clear badges on Huawei?

Send a notification with `huawei_badge_set_num` set to `0`, or use **Set to > 0** in the dashboard. You can also use a [data/background notification](./data-notifications) to clear badges without showing a visible notification. Alternatively, clear the badge client-side using the Huawei badge API.

### Can I set badges for web push?

No. App icon badges are only supported on iOS, Android, and Huawei. For Android web push, the "badge" refers to the small icon shown on the notification itself — see [Web Push Badges](./push#badges).

***

## Related pages

<Columns>
  <Card title="Android notification categories" icon="android" href="./android-notification-categories">
    Control badge display and behavior per notification channel on Android.
  </Card>

  <Card title="Huawei authorization" icon="mobile" href="./authorize-onesignal-to-send-huawei-push">
    Set up Huawei push messaging with OneSignal.
  </Card>

  <Card title="Push overview" icon="bell" href="./push">
    Full reference for push notification features including web push badges.
  </Card>

  <Card title="Mobile SDK setup" icon="code" href="./mobile-sdk-setup">
    Configure the OneSignal SDK including badge prerequisites for iOS.
  </Card>
</Columns>


# Usage & billing
Source: https://documentation.onesignal.com/docs/en/billing-faq

OneSignal billing overview covering invoices, payment methods, plan changes, usage metrics, and cost management for all plan types.

<Note>
  For plan features and pricing tiers, see the public [Pricing page](https://onesignal.com/pricing).
</Note>

This guide explains:

* How to complete common billing tasks
* What affects your invoice amount
* How usage is calculated
* How to manage or reduce costs
* How billing relates to Apps and Organizations

***

## Common billing tasks

View your Organization's Billing and Usage within **Organizations > Billing**.

<Note>
  You must be an Organization Admin to view the billing page. See [Manage Team Members](./manage-team-members) and ask an Org Admin to add you as a Billing Contact. You can also view App-level usage in **Settings > Usage**.
</Note>

<Frame>
  <img alt="OneSignal Organization Billing page showing invoices, payment method, and usage" />
</Frame>

### Download an invoice

**Self-serve (Growth & legacy plans)**

1. Go to **Organizations > Billing**.
2. Under **Invoices**, select the invoice.
3. Click **Download**.

<Check>
  The invoice downloads immediately as a PDF.
</Check>

**Professional & Enterprise (contract plans)**

Email `ar@onesignal.com` with:

* Full company name
* Billing email (if available)
* Organization ID (found in **Organizations > Keys & IDs**)

***

### Update your payment method

**Self-serve (Growth & legacy plans)**

1. Go to **Organizations > Billing**.
2. Next to **Payment Method**, click **Update**.
3. Enter your updated payment details and **Save**.

<Check>
  Your updated payment method appears immediately in the billing page.
</Check>

**Professional & Enterprise (contract plans)**

1. Open the secure billing portal from your **Billing Welcome Email**.
2. Enter your updated payment details.
3. Save changes.

If you cannot find the billing portal link, email `ar@onesignal.com` with:

* Full company name
* Billing email (if available)
* Organization ID (found in **Organizations > Keys & IDs**)

***

### Change billing information

**Self-serve (Growth & legacy plans)**

1. Go to **Organizations > Billing**.
2. Next to **Billing Profile**, click **Edit**.
3. Enter your updated billing information and **Save**.

<Check>
  Your updated billing information appears immediately in the billing page.
</Check>

**Professional & Enterprise (contract plans)**

1. Open the secure billing portal from your **Billing Welcome Email**.
2. Enter your updated billing information.
3. Save changes.

If you cannot find the billing portal link, email `ar@onesignal.com` with:

* Full company name
* Billing email (if available)
* Organization ID (found in **Organizations > Keys & IDs**)

***

### Upgrade your plan

If you need higher limits or additional features, [contact our Sales team](https://onesignal.com/contact).

***

### Downgrade to Free

**Self-serve (Growth & legacy plans)**

1. Go to **Organizations > Billing**.
2. Select **Change Plan**.
3. Click the **Free** plan.
4. Confirm the downgrade.

<Warning>
  You will continue on the same plan until the end of your current billing cycle.

  Paid features are removed at the end of your current billing cycle.
</Warning>

**Professional & Enterprise (contract plans)**

Contract plans must follow agreement terms. Contact your Account Manager or `ar@onesignal.com` to discuss changes.

***

### Reactivate a suspended account

Self-serve accounts are disabled after **three failed payment attempts**.

To reactivate:

1. Pay any outstanding invoices.
2. Allow up to one business day for reactivation.

If your account is not restored, email `support@onesignal.com` with:

* Full company name
* Billing email (if available)
* Organization ID (found in **Organizations > Keys & IDs**)

***

## What affects your invoice amount?

Your invoice is based on one or more of the following:

* Active **Mobile Monthly Active Users (MAU)**
* Active **Web Push Subscribers**
* **Email sends**
* **In-App message impressions**
* **Event Streams volume**
* **Custom Event storage**

To confirm your pricing model, go to **Organizations > Billing**.

You will see either:

* **Mobile MAU + Web Push Subscribers** (current pricing model)
* **Push Subscribers** (legacy plans only)

***

## How billing is calculated

### Monthly Active Users (MAU)

A Monthly Active User (MAU) is a mobile push subscription active within the last 30 days, regardless of current subscription status.

* Each active subscription counts separately.
* One user with two active subscriptions counts as **2 MAU**.

Billing is calculated in **increments of 10 MAU**, rounded **down** to the nearest multiple of 10.

See [Subscriptions](./subscriptions) for more details.

### Web Push Subscribers

Users who subscribed to receive web push notifications from a supported web browser.

* Each subscribed browser counts separately.
* One user subscribed on two browsers counts as **2 subscribers**.

Billing is calculated in **increments of 10 subscribers**, rounded **down** to the nearest multiple of 10.

See [Subscriptions](./subscriptions) for more details.

***

### Push Subscribers (legacy plans only)

Push Subscriber pricing includes total subscribed mobile and web push subscriptions.

To reduce subscriber count, remove users via the dashboard or API. See [Delete Users](./delete-users).

<Note>
  To migrate from Push Subscriber pricing to MAU pricing, [contact our Sales team](https://onesignal.com/contact).
</Note>

***

## Messaging usage

### Email sends

You are billed for emails that leave OneSignal, including:

* Delivered
* Bounced
* Most Failures

Exceptions:

* **Invalid ESP credentials**
* **Delivery Error**

***

### RCS

RCS messages are billed per message segment based on the message type:

| Type           | Audience      | Description                                                                                                                                                                                                                       |
| -------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Rich**       | US            | Text-only messages — cannot include a title. Can include actions such as replies, dials, or links, but link actions must open in a new tab. Messages longer than 160 characters are broken into segments and charged per segment. |
| **Rich Media** | US            | Messages with media, cards with titles and/or actions that open in a web view (not a new tab), and carousel content.                                                                                                              |
| **Basic**      | International | Text messages up to 160 UTF-8 characters. Does not include any actions, media, or carousels.                                                                                                                                      |
| **Single**     | International | Text messages greater than 160 UTF-8 characters, up to the max message length of 3,072 characters. Can also include actions, media, or carousels.                                                                                 |

For more on RCS message types, see [Rich Communication Services (RCS)](./rcs-messaging#types-of-rcs-messages).

***

### In-App impressions

Counts each display of an [in-app message](./in-app-messages-setup) in mobile apps.

This metric does not include push notifications or email.

***

## Event-related billing

Event billing includes both **delivery volume** and **storage volume**.

### Event Streams (delivery volume)

Includes:

* [Event Streams](./event-streams)
* Webhooks
* Integration destinations

Events delivered through integrations count toward your monthly limit.

| Plan         | Active Event Streams | Monthly Event Limit |
| ------------ | -------------------- | ------------------- |
| Free         | 1                    | Up to 1,000 events  |
| Growth       | 3                    | Up to 10,000 events |
| Professional | Custom               | Based on volume     |
| Enterprise   | Custom               | Based on volume     |

<Info>
  Webhooks are a type of Event Stream destination. Events delivered through webhooks and integrations count toward your Event Streams monthly event limit.
</Info>

***

### Custom Events (storage volume)

<Warning>
  Custom Events storage is different from Event Streams. **Event Streams** send message data (delivery, clicks, failures) **out** of OneSignal to external destinations like webhooks and integrations. **Custom Events** are sent **into** OneSignal from your app or backend systems to power Segments, Journeys, and analytics. They have separate billing and separate plan limits.
</Warning>

[Custom Events](./custom-events) are billed based on the number of events **stored** per month. Each plan includes a monthly storage allotment; overages are charged at your contracted unit rate.

By default, all events are stored with unlimited retention. You can adjust the retention period per event type at any time.

Each plan includes:

| Plan       | Included Stored Events / Month |
| ---------- | ------------------------------ |
| Growth     | 1M                             |
| Pro        | 5M                             |
| Enterprise | 10M                            |

### How retention affects Custom Event cost

* Retention is measured per event name.
* Default retention is **unlimited**.
* Minimum retention is **30 days**.
* Billing is based on stored events at the end of the billing cycle.
* Shorter retention reduces billable stored events.

To adjust retention, go to **Data > Custom Events** in the OneSignal dashboard, then select the **Event Storage** tab. From there you can set retention per event name. Changes take effect at the next billing cycle.

<Info>
  Events received through integrations (e.g., Amplitude, Segment) also count toward your stored event total.
</Info>

***

## Analytics data retention

Dashboard reporting data — including message delivery reports, conversion metrics, and template analytics — is retained based on your plan:

| Plan         | Retention period |
| ------------ | ---------------- |
| Free         | 30 days          |
| Growth       | 90 days          |
| Professional | 1 year           |
| Enterprise   | 2 years          |

See the [Pricing page](https://onesignal.com/pricing) for more details on plan features.

## Message event retention

Message event data powers [segment filters](./segmentation#message-event-filters), letting you target users based on how they interacted with your messages. How far back that data is available depends on your plan:

| Plan         | Message event retention |
| ------------ | ----------------------- |
| Growth       | 30 days                 |
| Professional | 60 days                 |
| Enterprise   | 90 days                 |

The segment filter UI shows a time window of up to 90 days, but queries beyond your plan's retention period will not return results.

***

## FAQ

### How can I manage or reduce costs?

You can reduce billing by:

**If you are on MAU pricing:**

* Reduce duplicate mobile subscriptions or limit the number of subscriptions per user.
  * Use our [SDK privacy methods](./mobile-sdk-reference#privacy) to delay SDK initialization and subscription creation until you are ready to create a subscription for the user.

**If you rely heavily on email:**

* Send to more targeted segments.
* Clean inactive and invalid email addresses.

**If you use Custom Events:**

* Shorten retention periods.
* Consolidate similar event names.

**If you use Event Streams:**

* Audit integrations.
* Reduce unnecessary events.

For volume discounts (for example, more than 50k MAU or 250k emails per month), [contact our Sales team](https://onesignal.com/contact).

### How is billing related to Apps and Organizations?

* You can create unlimited apps and organizations.
* Apps are not billed individually.
* Billing occurs at the **Organization level**.
* You can create multiple Organizations to:
  * Separate apps that you want to be billed for vs those you do not want to be billed for.
  * Add apps for different brands, clients, or environments.
  * Example: a "Free" Organization for development or testing and a "Paid" Organization for production.

See [Apps & Organizations](./apps-organizations).

### When am I charged?

* **Self-serve (Growth & legacy plans)**: Monthly on the same calendar date you started.
* **Professional & Enterprise (contract plans)**: According to your contract terms.

### Can I cancel anytime?

* **Self-serve (Growth & legacy plans)**: Yes. Downgrade to Free.
* **Professional & Enterprise (contract plans)**: Contract terms apply.

### Can I pay by invoice?

**Custom Professional and Enterprise (contract plans)** can be paid by invoice. Ask your Account Manager or [contact our Sales team](https://onesignal.com/contact).

### Can someone else request invoices?

* **Self-serve (Growth & legacy plans)**: Only [Org Admins](./manage-team-members) can view and edit billing information in the Organization Billing page.
* **Professional & Enterprise (contract plans)**: Email `ar@onesignal.com` with:
  * Full company name
  * Billing email (if available)
  * Organization ID (found in **Organizations > Keys & IDs**)

### How do I add or remove billing contacts?

See [Manage Team Members](./manage-team-members) to remove team members from accessing the App and/or Organization.

To remove a billing contact, email `ar@onesignal.com` with:

* Full company name
* Billing email (if available)
* Organization ID (found in **Organizations > Keys & IDs**)

### What payment methods are accepted?

Visa, MasterCard, American Express, Discover, Diners Club International, JCB, and PayPal.

<Info>
  Payments are processed by Recurly using 128-bit SSL. OneSignal does not store your card details.
</Info>

**Currency**

We currently accept USD only.

### How does deleting subscriptions affect my bill?

For **web push**, billing is calculated based on number of subscriptions, so deleting subscriptions before the end of your billing cycle will lower your bill.

For **mobile push**, billing is calculated based on monthly active users. Deleting a subscription that has been active in your current billing cycle before the end of the cycle will lower your bill.

For **in-app messages, SMS, and Email**, billing is not based on your subscription count, so deleting subscriptions will not affect these parts of your bill.

***

## Related pages

<Columns>
  <Card title="Apps & Organizations" icon="building" href="./apps-organizations">
    Manage apps, organizations, and how billing is structured across them.
  </Card>

  <Card title="Manage Team Members" icon="users" href="./manage-team-members">
    Add or remove team members and control access to billing.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    How mobile and web push subscriptions are counted toward billing.
  </Card>

  <Card title="Pricing" icon="tag" href="https://onesignal.com/pricing">
    Compare plan features and pricing tiers.
  </Card>
</Columns>


# Web push browser behavior
Source: https://documentation.onesignal.com/docs/en/browser-behavior-and-unsubscribes

Learn how to unsubscribe from notifications and understand how browsers handle web push subscriptions.

This guide explains how to manage web push [subscriptions](./subscriptions) and how subscription status is affected by both user action and browser behavior.

***

## Understand push permissions

Users must give your website permission to send them push notifications. It is not possible to receive push notifications without explicitly granting the site permission using the system-level permission prompt.

<Frame>
  <img />
</Frame>

Permissions can be either:

* **Default**: permission has not been granted to denied.
* **Granted**: you allowed the website to send you notifications.
* **Denied**: you blocked the website to send you notifications. This can be a temporary block if you clicked the **x** to close the prompt repeatedly or a permanent block if you clicked **Block** or toggled off permission in the browser settings.

<Note>
  For more details on the native system-level permission prompt and/or any of the OneSignal prompts, see [Web permission prompts](./permission-requests).
</Note>

***

## How to unsubscribe from web notifications

You can unsubscribe from web push notifications in three ways:

### Unsubscribe within browser settings

You can manage or remove notification permissions directly in browser settings. Here are quick-access URLs and official docs to learn more:

* **Chrome**: `chrome://settings/content/notifications` ([Learn more on Chrome's docs](https://support.google.com/chrome/answer/3220216?hl=en\&co=GENIE.Platform%3DDesktop\&sjid=12874758545589453111-NA))
* **Edge**: `edge://settings/content/notifications` ([Learn more on Microsoft's docs](https://www.microsoft.com/en-us/edge/learning-center/how-to-turn-off-block-browser-notifications?form=MA13I2))
* **Firefox**: `about:preferences#privacy` scroll to Permissions > Notifications > Settings ([Learn more on Mozilla's docs](https://support.mozilla.org/en-US/kb/push-notifications-firefox))
* **Safari**: Settings > Websites > Notifications ([Learn more on Safari's docs](https://support.apple.com/guide/safari/customize-website-notifications-sfri40734/16.1/mac/13.0))

On these pages, just click the options to remove or block the website(s) you don't want notifications from.

### Unsubscribe while on the website

**Reset permission**

Most browsers have a "lock" or "settings" icon next to the URL. Clicking it reveals site-specific permissions where users can disable push notifications.

<Frame>
  <img />
</Frame>

**OneSignal prompts**

If the website contains the OneSignal [Bell Prompt](./permission-requests) or [Custom Link prompt](./permission-requests) users can unsubscribe directly via those UI elements and be able to resubscribe using the same as desired.

<Frame>
  <img />
</Frame>

### Deleting browser data, clearing cookies and site data

If you delete history and/or delete your cookies and site data, it will temporarily prevent notifications from showing. However, if you don't remove push permissions from the site, you may be automatically re-subscribed and start getting notifications again upon returning to the site.

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

***

## How to test your permission prompts

These steps explain how to test your prompt and subscription flow like a first time visitor.

<Steps>
  <Step title="Visit your site with the OneSignal SDK setup.">
    **Do not use an incognito, private, or guest browser setting.** This example uses Chrome version 135 on macOS but the flow should be relatively the same for most browsers.
  </Step>

  <Step title="Reset push permissions">
    Click the site settings or lock icon next to the site URL and select **Reset permission** or remove permissions for Notifications.
    Skip to the next step if you don't see this permission option.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Delete site data.">
    Click **Cookies and site data > Manage on-device site data** or follow the browser's flow to see your site's data option.

    <Frame>
      <img />
    </Frame>

    Delete the data for your site and exit the settings to get back to your site.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Open your developer tools.">Usually you can just right click the screen and press **Inspect**.</Step>

  <Step title="Follow the steps needed to prompt for push notifications and on the required system-level permission prompt, select &#x22;Allow&#x22;.">
    If you do not see the prompt or don't know the steps, see [Web permission prompts](./permission-requests).

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Check the console for any errors.">
    If you see anything in red related to OneSignal, see our [Web SDK troubleshooting](./troubleshooting-web-push) docs.
  </Step>

  <Step title="Get subscription ID">
    In the **Console** type or copy-paste this code: `OneSignal.User.PushSubscription.id`

    1. This will log your OneSignal subscription ID. Copy-paste this into your OneSignal Dashboard Audience > Subscriptions tab.
    2. If a subscription ID was not logged in the console, then you are not successfully subscribed. Please see [Web SDK troubleshooting](./troubleshooting-web-push) for details.

    <Frame>
      <img />
    </Frame>

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Next to the subscription, select the 3-dot options button and &#x22;Add to Test Users&#x22;. Then name and date the test user so it is recognizable.&#x22;">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Navigate to Messages > Push > New Message > New Push and on the Push create form add a Message.">
    See [Push](./push) for more details if needed.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Select &#x22;Test & Preview&#x22;, find and check your test user, then click &#x22;Send Test Push&#x22;.">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="You should receive the push you tested.">
    If you did not receive a push, see [Web push: Notifications not shown](./notifications-not-shown-web-push) for further debugging.

    <Frame>
      <img />
    </Frame>
  </Step>
</Steps>

<Check>
  You have successfully setup web push with OneSignal. Next steps:

  * [Web push setup](./web-push-setup) - additional non-developer web setup steps.
  * [Web SDK setup](./web-sdk-setup) - developer web SDK setup steps.
  * [Web SDK troubleshooting](./troubleshooting-web-push) - troubleshooting if you see errors in the console or not getting a subscription ID.
  * [Web push: Notifications not shown](./notifications-not-shown-web-push) - troubleshooting notifications not displaying on your device.
</Check>

***

### Receiving Notifications When the Browser is Closed

Browsers behave differently across platforms. Please refer to the table below for support for receiving notifications even when the browser is closed.

| Browser Name      | Android | Windows | macOS |
| ----------------- | ------- | ------- | ----- |
| Chrome / Chromium | Yes     | Yes     | No    |
| Firefox           | Yes     | Yes     | No    |
| Safari            | N/A     | N/A     | Yes   |
| Opera             | Yes     | Yes     | No    |
| Edge              | Yes     | Yes     | No    |

**Chrome** - Chrome runs as a background process by default even when all the windows are closed. As long as the background process is running, notifications will still be received. If the Chrome background process is not running, notifications will not be received.

**Firefox** - On Mac OS X, the process still exists even if windows are closed, and a notification can be received if all windows are closed (as long as there is still a dot in the dock showing Firefox is still running). On Windows, the process exits after all windows are closed so notifications cannot be received unless a Firefox window is still open.

**Safari** - Safari does not have to be running to receive notifications, as they are sent directly to the operating system. The user still has to sign up for Safari web notifications, but after that they will be received even when Safari is completely closed.

Subscribers have up to 3 days to retrieve the last known missing notification before messages expire permanently.

For example, suppose a subscriber was supposed to receive a Firefox web push notification, but Firefox was closed. If the subscriber opens Firefox within 3 days, the subscriber will receive only the last known web push notification that didn't expire. If the subscriber opens Firefox after 3 days, the web push notification sent more than 3 days ago will not be received.

***


# Channel setup
Source: https://documentation.onesignal.com/docs/en/channel-setup

Set up push notifications, in-app messages, email, SMS, RCS, and Live Activities in OneSignal to reach Users across every channel.

OneSignal supports multiple messaging channels, each with different capabilities and setup requirements. Choose the channels that match your goals, or combine several to build a multi-channel experience with [Journeys](./journeys-overview).

<Tip>
  Email and SMS can be configured without a developer. Push notifications, in-app messages, and Live Activities require SDK integration — see the [Developer guide](./developers) or [invite a developer](./manage-team-members) to your team.
</Tip>

***

## Messaging channels

<Columns>
  <Card title="Mobile push" icon="mobile" href="./mobile-push-setup">
    Alert-style notifications on iOS, Android, Huawei, and Amazon — even when the app isn't open.
  </Card>

  <Card title="Web push" icon="globe" href="./web-push-setup">
    Browser-based notifications that reach Users even when your site isn't open.
  </Card>

  <Card title="Email" icon="envelope" href="./email-setup">
    Marketing and transactional emails with built-in deliverability tools.
  </Card>

  <Card title="In-app messages" icon="window-maximize" href="./in-app-messages-setup">
    Rich, interactive messages displayed while Users are active in your app.
  </Card>

  <Card title="SMS" icon="comment-sms" href="./sms-setup">
    Direct text messages for urgent or time-sensitive communication.
  </Card>

  <Card title="RCS" icon="message" href="./rcs-messaging">
    Rich messaging with branded content and read receipts on Android.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="./live-activities">
    Real-time updates on the iOS lock screen. Similar capabilities available for Android.
  </Card>
</Columns>

***

## Channel comparison

| Channel         | Developer required? | Setup time | Best for                                                 |
| --------------- | ------------------- | ---------- | -------------------------------------------------------- |
| Email           | No                  | 15–60 min  | Marketing campaigns, transactional messages, newsletters |
| SMS             | No                  | 15–60 min  | Time-sensitive alerts, OTPs, appointment reminders       |
| Web push        | Yes                 | 15–45 min  | Re-engaging website visitors, announcements              |
| Mobile push     | Yes                 | 30–60 min  | App re-engagement, real-time alerts, promotions          |
| In-app messages | Yes (SDK)           | 30–45 min  | Onboarding, feature announcements, surveys               |
| RCS             | No                  | Varies     | Rich branded messaging on Android with read receipts     |
| Live Activities | Yes (SDK)           | 45–60 min  | Live scores, delivery tracking, event countdowns         |

***

## Next steps

After setting up a channel, continue with the rest of your OneSignal implementation.

<Columns>
  <Card title="Quickstart guide" icon="rocket" href="./quickstart-guide">
    Full implementation walkthrough: Users, segments, sending messages, and analytics.
  </Card>

  <Card title="Developer guide" icon="code" href="./developers">
    SDK reference, API docs, User identity, and testing for engineering teams.
  </Card>

  <Card title="Send messages" icon="paper-plane" href="./push">
    Compose and send your first message after setting up a channel.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Automate multi-channel flows based on User behavior.
  </Card>
</Columns>

***

## FAQ

### Which channel should I set up first?

Start with the channel that matches your most immediate goal. **Email** and **SMS** are the fastest to configure and don't require a developer. If you already have a mobile app, **push notifications** provide the highest visibility for re-engagement.

### Can I use multiple channels in the same OneSignal app?

Yes. A single OneSignal app supports all channels. Adding multiple channels lets you use [Journeys](./journeys-overview) to automate multi-channel flows — for example, sending a push notification, then following up with an email if the User doesn't engage.

### Do I need separate apps for testing and production?

Yes, this is strongly recommended. Use separate OneSignal apps for development, staging, and production to avoid sending test messages to real Users. See [Apps, Organizations, and accounts](./apps-organizations) for details.


# Confirmed receipt
Source: https://documentation.onesignal.com/docs/en/confirmed-delivery

Confirmed receipt tracks when a device receives a push notification sent through OneSignal. Covers requirements, platform limitations, and troubleshooting for iOS, Android, Huawei, and Web.

Confirmed receipt (also known as "Confirmed Delivery") tracks when a device actually **receives** a push notification sent from OneSignal. When the OneSignal SDK on the device receives a push, it sends a **confirmation receipt** back to OneSignal containing the notification ID and the device's [Subscription ID](./subscriptions). This lets you see exactly which Subscriptions received which notifications.

In your OneSignal Dashboard, "Confirmed receipt" appears in the [Push Notification Message Reports](./push-notification-message-reports). For all delivery and engagement metrics, see the [Analytics Metrics Glossary](./analytics-metrics-glossary).

<Frame>
  <img alt="Confirmed receipt flow" />
</Frame>

<Note>
  Confirmed receipt is different from "Delivered." Platform push services (APNs, FCM, ADM, HMS) report whether a notification was accepted by the service — not whether the device actually received it. Confirmed receipt is the device-side confirmation.
</Note>

***

## Requirements

* Available only on **paid plans**. [Compare plans](https://onesignal.com/pricing).
* Complete the [Web SDK Setup](./web-sdk-setup) and/or [Mobile SDK Setup](./mobile-sdk-setup).
  * Confirmed receipt only works if the device has the OneSignal SDK installed.
  * **Not supported** for subscriptions created via API only.

### Platform limitations

#### iOS

* Requires both the **Notification Service Extension** and **App Group** to be set up correctly.
* Push notifications must include the `mutable-content` key set to `1`. This is set automatically by OneSignal. Make sure you are not explicitly setting `mutable_content: false`.
* APNs keeps only **one message per app** when offline. If multiple pushes are sent while offline, only the latest is delivered.

#### Huawei

* Supported only for the `data` [Huawei message type](/reference/push-notification#body-huawei-msg-type).
* For the `message` type, Huawei provides receipt data only in their own dashboard.

#### Web

* Safari does **not** support confirmed receipt.

***

## Troubleshooting confirmed receipt

If you are not receiving push notifications at all, see [Notifications not showing](./notifications-show-successful-but-are-not-being-shown) first.

### iOS

Confirmed receipt on iOS requires two things working together:

1. A **Notification Service Extension** (NSE) that runs OneSignal code when a push arrives
2. An **App Group** shared between your main app target and the NSE target so they can exchange data

If either is missing or misconfigured, the device receives the push but never reports it back to OneSignal.

#### Verify your iOS setup

<Steps>
  <Step title="Confirm the NSE target exists and has the correct code">
    In Xcode, check that you have a **OneSignalNotificationServiceExtension** target listed under your project targets. If it does not exist, follow [Step 2 of the iOS SDK Setup](./ios-sdk-setup#step-2-add-a-notification-service-extension-nse).

    Open the NSE's `NotificationService.swift` (or `.m`) file. It must call `OneSignalExtension.didReceiveNotificationExtensionRequest` inside `didReceive(_:withContentHandler:)`. If the file still contains Apple's default template code, replace it with the [OneSignal NSE code](./ios-sdk-setup#step-2-add-a-notification-service-extension-nse).
  </Step>

  <Step title="Confirm the NSE has the OneSignalExtension package">
    Select your **NSE target > General > Frameworks and Libraries** (or **Build Phases > Link Binary With Libraries**). Verify that `OneSignalExtension` is listed. The main app target uses `OneSignalFramework`, but the NSE target must use `OneSignalExtension` — these are different packages.
  </Step>

  <Step title="Verify the App Group is configured correctly on both targets">
    The OneSignal SDK uses an App Group to share data between your main app and the NSE. There are two ways to configure this — pick the one that matches your setup.

    1. Select your **main app target > Signing & Capabilities > App Groups**.
    2. Confirm the App Group.

    If your App Group is `group.YOUR_MAIN_APP_BUNDLE_ID.onesignal` — where `YOUR_MAIN_APP_BUNDLE_ID` is your main app target's Bundle Identifier (found under **General > Identity**), then follow the Default App Group tab. Otherwise, follow the Custom App Group tab.

    <Tabs>
      <Tab title="Default App Group - group.YOUR_MAIN_APP_BUNDLE_ID.onesignal">
        1. Select your **NSE target > Signing & Capabilities > App Groups**.
        2. Confirm the **exact same** App Group is listed. If missing, add it via **+ Capability > App Groups** and select the same group.

        A common mistake is using the NSE's bundle identifier instead of the main app's:

        * **Correct:** `group.YOUR_MAIN_APP_BUNDLE_ID.onesignal`
        * **Wrong:** `group.YOUR_MAIN_APP_BUNDLE_ID.OneSignalNotificationServiceExtension.onesignal`

        Your main app target and NSE target should have the same App Group identifier.
      </Tab>

      <Tab title="Custom App Group">
        Use this option if your App Group identifier does not follow the `group.YOUR_MAIN_APP_BUNDLE_ID.onesignal` format.

        1. Select your **main app target > Signing & Capabilities > App Groups**.
        2. Confirm your custom App Group is listed.
        3. Select the `Info.plist` of your main app target and add the following key:

        ```xml theme={null}
        <key>OneSignal_app_groups_key</key>
        <string>group.your-custom-group-name</string>
        ```

        Replace `group.your-custom-group-name` with your actual App Group name.

        4. Select your **NSE target > Signing & Capabilities > App Groups**.
        5. Confirm the **exact same** custom App Group is listed. If missing, add it via **+ Capability > App Groups** and select the same group.
        6. Select the `Info.plist` of your NSE target and add the following key:

        ```xml theme={null}
        <key>OneSignal_app_groups_key</key>
        <string>group.your-custom-group-name</string>
        ```

        Replace `group.your-custom-group-name` with your actual App Group name.

        Your main app target and NSE target should have the same App Group identifier.
      </Tab>
    </Tabs>

    <Warning>
      If you use `.xcconfig` files for build settings, verify the App Group is not being overridden or omitted in those files.
    </Warning>
  </Step>

  <Step title="Confirm minimum deployment targets match">
    Select your **NSE target > General > Minimum Deployments**. This value must match your main app target's minimum deployment. A mismatch can prevent the NSE from running on certain OS versions.
  </Step>

  <Step title="Uncheck &#x22;Copy only when installing&#x22;">
    Select your **main app target > Build Phases > Embed App Extensions**. Make sure **"Copy only when installing" is unchecked**. If checked, the NSE is not embedded during development builds, so it never runs when testing.
  </Step>

  <Step title="Verify NSExtension Info.plist values">
    Select your **NSE target > Info** tab and expand the `NSExtension` key. Confirm it contains:

    ```xml theme={null}
    <key>NSExtensionPointIdentifier</key>
    <string>com.apple.usernotifications.service</string>
    <key>NSExtensionPrincipalClass</key>
    <string>$(PRODUCT_MODULE_NAME).NotificationService</string>
    ```

    If your NSE is written in Objective-C, use `NotificationService` instead of `$(PRODUCT_MODULE_NAME).NotificationService`.
  </Step>

  <Step title="Verify mutable-content is set">
    OneSignal automatically sets `mutable-content: 1` in the push payload, which tells iOS to invoke the NSE. If you send pushes via the [REST API](/reference/push-notification), verify you are not explicitly setting `mutable_content: false`. Without `mutable-content`, iOS does not run the NSE and confirmed receipt cannot fire.
  </Step>

  <Step title="Test that the NSE is running">
    Add this line temporarily inside `didReceive` before the OneSignal call:

    ```swift theme={null}
    bestAttemptContent.body = "[Modified] " + bestAttemptContent.body
    ```

    Send yourself a test push. If the notification body starts with `[Modified]`, the NSE is running correctly. If it does not, revisit the steps above — the NSE is not being invoked. Remove this line after testing.

    For advanced NSE debugging with Xcode Console logs, see [Debugging the iOS Notification Service Extension](./service-extensions#debugging-the-ios-notification-service-extension).
  </Step>
</Steps>

### Android

* If notifications are not displaying, see [Mobile push troubleshooting](./notifications-show-successful-but-are-not-being-shown).
* If notifications show but confirmed receipt is missing, a custom Android Service Extension may be blocking it. Check the [Android Service Extension guide](./service-extensions#android-service-extension).

### Web

* Safari is not supported.
* For other browsers, ensure migration to **v16 SDK** is complete:
  * Correct SDK init:
    ```html theme={null}
    <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
    ```
  * Correct Service Worker reference:
    ```html theme={null}
    importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
    ```

***

## FAQ

### Why are my confirmed receipt numbers low or missing?

The most common causes are setup issues (especially on iOS), inactive devices, and platform limitations.

1. **iOS misconfiguration:** The Notification Service Extension or App Group is missing or incorrect. See [Troubleshooting confirmed receipt on iOS](#ios).
2. **Inactive or abandoned devices:** Devices that are offline or no longer in use do not receive pushes or send confirmed receipt events. See [How do I handle inactive devices?](#how-do-i-handle-inactive-devices).
3. **Platform limitations:** Huawei `message` type and Safari do not support confirmed receipt.
4. **Android force quit:** Some device manufacturers treat swiping the app away as a force quit, which stops SDK events. See [Mobile push not shown guide](./notifications-show-successful-but-are-not-being-shown).

### How do I handle inactive devices?

Devices that are offline or abandoned do not receive push notifications or send confirmed receipt events. This is common when users replace or abandon devices.

To re-engage inactive users:

* Use **Audience Activity** to resend to users who did not confirm receipt.
* Create [Segments](./segmentation) based on **Last Session** (for example, inactive for 90+ days).
  * Combine with a [Re-engagement Journey](./journeys-examples#re-engagement-campaign) to win them back.
  * Periodically target inactive users to prune unreachable devices.

See [When do push Subscription statuses update?](./subscriptions#when-do-push-subscription-statuses-update) for more details on how OneSignal updates subscription status.

### Why does confirmed receipt show but the notification doesn't appear?

A confirmed receipt event means the device received the push payload. In rare cases, the notification may not display.

Possible causes:

* **Missed notification:** Send yourself a test push via [Find and set Test Users](./test-users) to rule this out.
* **iOS Focus Mode:** "Do Not Disturb," "Sleep," or other [Focus modes](./ios-focus-modes-and-interruption-levels) delay or group notifications. You may have dismissed a grouped notification without seeing it.
* **App code suppressing display:**
  * `event.preventDefault()` in the [foreground lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) or [Notification Service Extension](./service-extensions) stops the notification from displaying.
  * Calls to [`removeDeliveredNotifications(withIdentifiers:)`](https://developer.apple.com/documentation/usernotifications/unusernotificationcenter/removedeliverednotifications\(withidentifiers:\)) or [`removeAllDeliveredNotifications()`](https://developer.apple.com/documentation/usernotifications/unusernotificationcenter/removealldeliverednotifications\(\)) remove notifications after they arrive.
* **Push payload settings:**
  * Ensure `priority` is set to high. See [Push priority](./push#priority).
  * [`collapse_id`](./push#collapse_id) replaces older pushes with newer ones using the same ID.

***

## Related pages

<Columns>
  <Card title="Push notification message reports" icon="chart-bar" href="./push-notification-message-reports">
    Review delivery, engagement, and confirmed receipt metrics for each push.
  </Card>

  <Card title="Analytics metrics glossary" icon="book-open" href="./analytics-metrics-glossary">
    Definitions for every delivery and engagement metric in OneSignal.
  </Card>

  <Card title="iOS SDK setup" icon="apple" href="./ios-sdk-setup">
    Add the Notification Service Extension and App Group required for iOS.
  </Card>

  <Card title="Service extensions" icon="code" href="./service-extensions">
    Customize notification behavior on iOS and Android with service extensions.
  </Card>
</Columns>

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# Create a custom email unsubscribe page
Source: https://documentation.onesignal.com/docs/en/create-custom-unsubscribe-page

Learn how to replace OneSignal's default unsubscribe link with a branded, multi-language, and personalized email preferences page, while maintaining compliance and tracking.

## Overview

OneSignal provides a [default email-compliant unsubscribe experience](./unsubscribe-links-email-subscriptions) that injects a link into your email templates so users can unsubscribe with ease and their [subscription statuses](./subscriptions) are updated in real-time. If you want full control over branding, copy, and fields (such as category opt-outs), you can replace the default link with your own custom page and use the OneSignal API to unsubscribe or update user preferences.

This guide explains how to add your own custom unsubscribe page to emails (removing the default OneSignal link) and which of our APIs to use to unsubscribe the user's email Subscription.

If you want to add more functionality to your custom unsubscribe page (like opt out of specific email categories instead of all), this is detailed in our [Preference Center](./preference-center) tutorial.

***

## Remove OneSignal's default unsubscribe link

OneSignal automatically inserts a special link in the format `[unsubscribe_url]` to your email templates. This URL unsubscribes the user from all emails in OneSignal. See [Email Unsubscribe Links](./unsubscribe-links-email-subscriptions) for details.

To use your own page, **locate and remove the default link** in your template.

<Tabs>
  <Tab title="Drag-and-Drop Editor">
    In the drag-and-drop editor, the default link may appear nested like:

    <Frame>
      <img alt="Drag-and-Drop editor unsubscribe link" />
    </Frame>
  </Tab>

  <Tab title="HTML Editor">
    ```html theme={null}
    <a href="[unsubscribe_url]">Unsubscribe</a>
    ```
  </Tab>
</Tabs>

***

## Add your custom unsubscribe link

Now that you have removed our special link, you can replace it with your own URL.

Many times, these links require some additional data to be passed to your page. Use [Liquid variables](./message-personalization) to pass OneSignal data to your page.

Common parameters:

| Parameter                        | Description                           |
| -------------------------------- | ------------------------------------- |
| `subscription.email`             | Subscriber’s email address            |
| `subscription.external_id`       | User’s external ID                    |
| `app.id`                         | OneSignal App ID                      |
| `message.id`                     | ID of the email notification          |
| `subscription.language`          | Preferred language (for localization) |
| `subscription.unsubscribe_token` | Security token for API verification   |

**Example URL:**

```liquid theme={null}
https://examplesite.com/unsubscribe?app_id={{app.id}}&notification_id={{message.id}}&email={{subscription.email}}&language={{subscription.language}}&token={{subscription.unsubscribe_token}}
```

```html HTML theme={null}
  <div style="text-align: center;">
    <a
      href="https://examplesite.com/unsubscribe?app_id={{app.id}}&notification_id={{message.id}}&email={{subscription.email}}&language={{subscription.language}}&token={{subscription.unsubscribe_token}}"
      data-disable-tracking="true"
      style="display: inline; text-decoration: none;"
    >
      Unsubscribe
    </a>
    <p style="display: inline;"> from our emails</p>
  </div>
```

<Frame>
  <img alt="Add custom unsubscribe link" />
</Frame>

### Disable click tracking

Unsubscribe clicks are generally not used for engagement metrics. If you want to disable link tracking, you can add the `data-disable-tracking="true"` attribute to your link like this:

```html HTML theme={null}
  <a
    href="https://www.examplesite.com/unsubscribe?app_id={{app.id}}&notification_id={{message.id}}&email={{subscription.email}}&language={{subscription.language}}&token={{subscription.unsubscribe_token}}"
    data-disable-tracking="true"
  >
    Unsubscribe
  </a>
```

**Provider-specific attributes:**

| Provider  | Attribute                      |
| --------- | ------------------------------ |
| OneSignal | `data-disable-tracking="true"` |
| Mailgun   | `disable-tracking=true`        |
| SendGrid  | `clicktracking=off`            |
| Mandrill  | `mc:disable-tracking`          |

***

## Hosting your custom unsubscribe page

Deploy a web page that:

* Reads query parameters from the unsubscribe link.
* Displays user-friendly opt-out or preference options.
* Sends the unsubscribe or update request to OneSignal via API.

<Info> We provide a working [GitHub sample project](https://github.com/OneSignalDevelopers/custom-email-unsubscribe-page-sample) you can fork and deploy. </Info>

<Frame>
  <img alt="Sample unsubscribe page" />
</Frame>

***

## Calling the OneSignal API

Depending on your use case, you can use the following APIs to unsubscribe or update user preferences:

* [Update Subscription by Token](/reference/update-subscription-by-token)
* [Unsubscribe Email with Token](/reference/unsubscribe-with-token)
* [Update User](/reference/update-user)

<Tabs>
  <Tab title="Update Subscription by Token">
    This API is most commonly used when you have the user's email address and just want to subscribe or unsubscribe them from all emails.

    **Required query parameters:**

    * `app_id`
    * `token`

    **Authentication required**

    * Call this API from your server.
  </Tab>

  <Tab title="Unsubscribe Email with Token">
    Use this API if you want to track which specific email caused the unsubscribe. This uses the email message ID to track the unsubscribe. See [Unsubscribe Email with Token](/reference/unsubscribe-with-token) API for more details.

    **Required query parameters:**

    * `app_id`
    * `notification_id`
    * `token`

    **Optional parameters:**

    * `email`
    * `language`

    **Example JavaScript:**

    ```javascript JavaScript theme={null}
    const unsubscribeURL = (href) => {
      const unsubscribeURL = new URL(href)
      const appID = unsubscribeURL.searchParams.get("app_id")
      const notificationID = unsubscribeURL.searchParams.get("notification_id")
      const unsubscribeToken = unsubscribeURL.searchParams.get("token")
      const language = unsubscribeURL.searchParams.get("language")
      const email = unsubscribeURL.searchParams.get("email")
      return {
        unsubscribeURL: `https://api.onesignal.com/apps/${appID}/notifications/${notificationID}/unsubscribe?token=${unsubscribeToken}`,
        meta: { language, email },
      }
    }
    ```
  </Tab>

  <Tab title="Update User">
    Update the user's preferences using the [Update User](/reference/update-user) API.

    **Required query parameters:**

    * `app_id`
    * `alias_id` - The user's external ID is recommended.

    **Authentication required**

    * Call this API from your server.
  </Tab>
</Tabs>

***

<Check>
  You should now be equipped with everything you need to know about creating a custom unsubscribe page.
</Check>

***


# Data feeds
Source: https://documentation.onesignal.com/docs/en/data-feeds

Pull real-time data from your APIs into OneSignal email messages at send time using Data Feeds, with Liquid syntax for personalization.

Data Feeds let you pull **real-time data from your APIs directly into messages** at send time. This allows you to deliver highly personalized content without pre-loading data into OneSignal.

Use Data Feeds when your data changes frequently, such as:

* A user’s current rewards balance
* Latest order status
* Personalized product recommendations

Other personalization methods (like [Tags](./add-user-data-tags) or [Dynamic Content](./dynamic-content)) work well for static data. **Data Feeds are best for live, fast-changing values**.

<Note>
  Data Feeds are currently available **only for email messages sent through Journeys**.
  Need another channel? [Fill out this short survey](https://survey.survicate.com/954895d3e7ed1348/?p=anonymous).
</Note>

***

## How Data Feeds work

1. **Create a Data Feed** – Configure how OneSignal connects to your API.
2. **Attach the Data Feed** to a message template.
3. **Insert response fields** in your message using [Liquid syntax](./using-liquid-syntax).
4. **At send time**, OneSignal makes an API call for each recipient, parses the response, and injects the data into your message.

### Example: Display reward points

Suppose you want to show each customer their rewards balance:

```liquid theme={null}
Hi {{ first_name }},

You have {{ data_feed.rewards.points }} points!
Your membership status is {{ data_feed.rewards.status_level }}.

Keep shopping to earn more points!
```

When Sarah receives this email, the Liquid variables are replaced with her actual points balance and membership status. The following sections walk through setting up this example step by step.

## Creating and using a Data Feed

### 1. Set up your Data Feed configuration

Navigate to **Data > Data Feeds** in the sidebar to see the list of existing Data Feeds and create a new one.

Each Data Feed must have:

* **Name**: A descriptive name like "Customer Rewards API" to help you distinguish feeds. Unique names are recommended but not required.
* **Alias**: A short identifier like `rewards` used in Liquid syntax (e.g., `{{ data_feed.rewards.points }}`). Must be unique, lowercase, alphanumeric, with no spaces or special characters.
* **Method**: The HTTP method OneSignal uses to contact your API. Usually `GET`, but `POST` is also supported.
* **URL**: Your API endpoint. Supports Liquid syntax so OneSignal can fetch user-specific data.

For example, your rewards endpoint might accept the user's `external_id` (stored in OneSignal) as a URL parameter:

```liquid theme={null}
https://acme.com/customers/user_id={{ external_id }}/rewards
```

* **Headers**: Key-value pairs required by your API (e.g., authentication tokens). Supports Liquid syntax.
* **Body**: Optional JSON request body. Supports Liquid syntax, the same as [Journey webhooks](./journeys-webhook#personalization).

For example, your API might require the user's ID in the request body instead of the URL:

```json theme={null}
{
	"customer_id": "{{ subscription.external_id }}"
}
```

A complete Data Feed configuration looks like this:

<Frame>
  <img alt="Data Feed configuration showing name, alias, method, URL, and headers" />
</Frame>

<Tip>
  Test your feed before using it in production. Data Feed tests run against your [Test Users](./test-users), so verify that those subscriptions have attributes that return a real result from your API.
</Tip>

Finally, **Activate** your new Data Feed so it’s ready for use.

### 2. Attach the Data Feed to your message template

Attach your Data Feed to your message template so that OneSignal knows to use it.

1. Navigate to **Messages > Templates**
2. In the Message section, select the **Personalization** button

<Frame>
  <img alt="Personalization button in the message template editor" />
</Frame>

3. Toggle on **Data Feeds** and select your feed

<Frame>
  <img alt="Data Feeds toggle and feed selector in the message composer" />
</Frame>

4. Save your template

### 3. Use the data in your message

Use Liquid syntax to insert response data anywhere in your message. Continuing the rewards example, the API response for Sarah (whose `external_id` is `a1-b2c3`) might look like this:

```json theme={null}
{
	"external_id": "a1-b2c3",
	"points": 193,
	"status_level": "Gold"
}
```

To insert the number of points and the status level, use dot notation to reference the Data Feed alias and response fields:

```liquid theme={null}
You have {{ data_feed.rewards.points }} points!
Your membership status is {{ data_feed.rewards.status_level }}.
```

This tells OneSignal:

* Use a Data Feed
* Use the `rewards` Data Feed
  * Recall: the `rewards` feed knows to call the API with the `external_id` of the recipient
* From the response, insert the value of the `points` item (193) and the `status_level` item (Gold)

***

## Requirements and limits

Your API needs to:

* **Accept single-step authentication** with auth tokens in headers
* **Respond quickly.** Under 250ms recommended (this directly affects send speed)
* **Return JSON.** Other formats are not supported at this time.
  * If you need a different format, [share your use case](https://survey.survicate.com/954895d3e7ed1348/?p=anonymous).
* **Handle your send volume.** A low rate limit on your API slows message delivery.
* **Return reasonably-sized payloads.** Keep responses under 50 KB for best performance.

Current limits:

* **One Data Feed per template.** Fetch everything you need in a single API response.
* **One API call per Data Feed per message.**
* **Journeys only.** Not yet available for other sending methods.
* **No chaining calls.** The payload from one Data Feed cannot be used to call another.

<Info>
  Need multiple Data Feeds per template or support for other channels? [Share your use case](https://survey.survicate.com/954895d3e7ed1348/?p=anonymous) to help prioritize these features.
</Info>

***

## Setting up your API

Before creating a Data Feed, ensure your API can handle these requirements:

### Authentication

Your API should accept authentication via headers:

```
Authorization: Bearer YOUR_TOKEN
```

or

```
X-API-Key: YOUR_KEY
```

#### Disallowed headers

The following headers are restricted and cannot be set:

* `content-length`
* `referer`
* `metadata-flavor`
* `x-google-metadata-request`
* `host`
* `x-onesignal*`

### JSON request body

If you need to include a body in the request, your API should accept JSON. This may mean your headers need to include `Content-Type: application/json`.

### JSON response

Your API should return a JSON object. Typically this means your headers will include `Accept: application/json`.

### Personalization parameters

You'll typically pass user identifiers in the URL like this:

```liquid theme={null}
https://api.example.com/users/{{ external_id }}/data
https://api.example.com/rewards?email={{ email | url_encode }}
```

And/or in the body:

```json theme={null}
{
	"customer_id": "{{ external_id }}",
	"email": "{{ subscription.email }}"
}
```

Make sure this data will exist in OneSignal (usually as Tags, but other options are available such as [custom event properties](#examples-and-advanced-use-cases)).

### Rate limits

Consider your API's rate limits. Sending to 10,000 users means 10,000 API calls in rapid succession. Ensure your API can handle this volume.

### Error handling

If your API returns an error or doesn't have data for a user, the message won't be sent to that recipient. Make sure your API returns data for all expected users.

***

## Getting started checklist

Before implementing Data Feeds, answer these questions:

* What data do I want to show in my message? Working backwards from a simple outline with the items to be populated from your API identified will help you organize your thinking.
* Is this data available via a single API endpoint?
* How will I authenticate API requests?
* What identifier or other data item will I use to fetch personalized data?
* Is that identifier already stored in OneSignal? If not, how will it be populated?
* Can my API handle the volume of requests I'll generate?
* What happens if my API doesn't have data for a user?

***

## Examples and advanced use cases

Data Feeds can be used with Liquid syntax or in combination with other features in creative ways to produce more complex personalization.

<AccordionGroup>
  <Accordion title="Iterating with loops: abandoned cart">
    Let's say you have a Data Feed cart that returns an array of items in the user's cart, plus the cart total dollar amount:

    ```json theme={null}
    {
      "items": [
        {
          "name": "Blue Running Shoes",
          "price": 84.00,
          "image_url": "https://acme.com/blue-running-shoes.png"
        },
        {
          "name": "Protein Bar",
          "price": 5.99,
          "image_url": "https://acme.com/protein-bar.png"
        }
      ],
      "total": 89.99
    }
    ```

    If you want to show each item in the cart, plus the cart total, you can use a for loop in Liquid:

    ```html theme={null}
    <ul>
      {% for item in data_feed.cart.items %}
        <li>
          <strong>{{ item.name }}</strong><br>
          ${{ item.price }}<br>
          <img src="{{ item.image_url }}" alt="{{ item.name }}">
        </li>
      {% endfor %}
    </ul>

    <p>Cart total: ${{ data_feed.cart.total }}</p>

    ```

    This will result in:

    ```text theme={null}
    - Blue Running Shoes
    - $84.00
    - <running shoes image>
    - Protein Bar
    - $5.99
    - <protein bar image>
    Cart total: $89.99
    ```

    <Note>
      If you're using the email block editor, when inserting this sort of complex Liquid syntax, particularly if you need to include images or links, for best results use the custom HTML block element.
    </Note>

    <Tip>
      Want to see how to trigger this abandoned cart email using custom events? Check out the **Custom events properties** section below for the complete workflow.
    </Tip>
  </Accordion>

  <Accordion title="Custom events properties">
    Continuing the previous abandoned cart example, how might we know how to fetch that particular cart in the first place?

    One method might be to create a Journey triggered by a `cart_abandoned` [custom event](./custom-events), where the properties includes a cart\_id. In this example that event is being sent to OneSignal via API:

    ```bash theme={null}
    curl --request POST \
      --url https://api.onesignal.com/apps/{app_id}/custom_events \
      --header 'Accept: application/json' \
      --data '{
      "events": [
        {
          "name": "cart_abandoned",
          "external_id": "user_12345",
          "properties": {
            "cart_id": 98765
          }
        }
      ]
    }'
    ```

    <Frame>
      <img alt="Journey entry node triggered by a custom event" />
    </Frame>

    The user `user_12345` enters the journey when this event is fired, then reaches a node sending an email. That email template is set up with the `cart` Data Feed, where the URL is set to retrieve the contents of a particular cart like so:

    ```liquid theme={null}
    https://acme.com/carts/{{ journey.event.cart_abandoned.data.cart_id }}
    ```

    Thus, when this particular event is ingested and triggers the Journey:

    1. The `cart_id` value of `98765` will be stored to the Journey
    2. When the email step is reached, the `cart` Data Feed will reference that `cart_id` value and use it to call the cart API
    3. The returned JSON properties will be parsed and inserted into the email as in the previous example above

    <Tip>
      Want to see how to conditionally display Data Feed content based on order status? Check out the **Conditional display: order status** section below to learn more.
    </Tip>
  </Accordion>

  <Accordion title="Conditional display: order status">
    Let's say you want to include the status of a customer's order, but only include a tracking number link if the order has been shipped. You can use an `if` statement to do so:

    ```liquid theme={null}
    Your order is {{data_feed.order.status}}!

    {% if data_feed.order.tracking_number != empty %}
    Track it here: {{data_feed.order.tracking_url}}
    {% endif %}
    ```

    Here, the tracking link will only be displayed if the `tracking_number` exists.
  </Accordion>

  <Accordion title="Automation without personalization">
    Data Feeds can be used to automatically insert up-to-date information into your messages without necessarily needing to be personalized per recipient.

    For example, perhaps you insert a banner image at the top of your emails and change it monthly to keep up with holidays and other monthly events. Rather than remembering to upload a new image to OneSignal and changing all your templates each month, you might set up a Data Feed that fetches the current banner image URL from your CMS or other asset-management location.

    You would set up a `banner` Data Feed that points to an endpoint **without** any variables in the URL like so:

    ```liquid theme={null}
    https://acme.com/assets/email-banner
    ```

    Which returns a response with the current banner URL:

    ```json theme={null}
    {
    	"banner_url": "https://acme.com/assets/email-banner/2025july.png"
    }
    ```

    You'd set your email template to use `{{ data_feed.banner.banner_url }}` as the image source URL, automating this process going forward.
  </Accordion>

  <Accordion title="Personalized coupon codes">
    This example covers how to send personalized, single-use coupon codes in emails using a Data Feed that fetches a unique value from your API for each recipient.

    ### Goal

    Send an email such as:

    > Hi George,
    >
    > Complete your booking in the next 2 hours and save 10% with your personal code: XYZ123ABC

    Each user receives a unique coupon code, generated live via an external API call when the email is sent, valid for the given time window, and scoped to that user.

    ### Prerequisites

    * [Email channel configured](./email-setup) in OneSignal (your app has email capability enabled)
    * An external API that accepts a user identifier (for example, [`external_id`](./users#external-id)) and campaign identifier, and returns JSON with the coupon code, discount, and expiration
    * A unique identifier (such as `external_id`) for each user that your API can use to generate coupons
    * A [segment](./segmentation) or trigger (for example, "abandoned search in last 24h") used to send the email through a OneSignal Journey

    ### Step 1: Create the Data Feed

    <Steps>
      <Step title="Navigate to Data Feeds">
        In your OneSignal dashboard, select **Data > Data Feeds** from the navigation bar, then click **New Data Feed**.
      </Step>

      <Step title="Configure the Data Feed">
        Configure the following fields:

        * **Data Feed Name**: `coupon_code_generator`
        * **Alias**: `coupon`
        * **Method**: `GET`
        * **URL**: `https://api.example.com/generate-coupon?userId={{ external_id }}&campaign=AbandonedBooking10`
        * **Headers**:
          ```json theme={null}
          {
            "Authorization": "Bearer YOUR_API_TOKEN"
          }
          ```
      </Step>

      <Step title="Reference the API response">
        When the API returns JSON like this:

        ```json theme={null}
        {
          "code": "AB10-5F3K-HT9L",
          "discount_percent": "10%",
          "expires_in_hours": 2
        }
        ```

        You can reference its values in your email template as:

        * `{{ data_feed.coupon.code }}`
        * `{{ data_feed.coupon.discount_percent }}`
        * `{{ data_feed.coupon.expires_in_hours }}`
      </Step>

      <Step title="Test and activate the Data Feed">
        Click **Send Test** to verify your configuration, then click **Activate** to make the Data Feed available for use in templates.
      </Step>
    </Steps>

    ### Step 2: Create the email template

    1. In OneSignal, go to **Messages > Email > New Template**
    2. Use the Data Feed alias and fields within your message body. For example:

    ```html theme={null}
    <h2>Hi {{ first_name }},</h2>
    <p>
    Complete your booking in the next {{ data_feed.coupon.expires_in_hours }} hours and save
    {{ data_feed.coupon.discount_percent }} with your personal code:
    <strong>{{ data_feed.coupon.code }}</strong>
    </p>

    <p><a href="https://example.com/checkout?coupon={{ data_feed.coupon.code }}">Use Code Now →</a></p>
    ```

    <Note>
      * Use Liquid syntax in the form `{{ data_feed.<alias>.<field> }}`
      * Make sure the Data Feed is attached to the template
      * If using the drag-and-drop editor with custom Liquid logic, use an HTML block
    </Note>

    ### Step 3: Attach the Data Feed and trigger the email

    1. In the template composer, under **Personalization > Data Feeds**, toggle the feed on and select `coupon_code_generator`
    2. This ensures OneSignal makes the API call at send time for each recipient, populates the data, and injects it into the email
    3. Set up a Journey to automate the message:
       * **Entry condition**: Segment such as "abandoned search in last 24 hours"
       * **[Wait until](./custom-events#wait-until-event)**: Create a `booking_completed` custom event. Configure the wait to exit the Journey if this event fires, or continue after 1 hour. If they complete a booking, they exit without receiving the email; otherwise, they continue to receive the coupon.
       * **Send email**: Use the personalized coupon email template
       * Ensure the Journey uses the email channel and that recipients are subscribed to email

    ### Step 4: Manage coupon redemption and tracking

    Your backend should:

    1. Record each generated code along with `userId`, `code`, `campaign`, `expiration_time`, and a `redeemed` flag
    2. Validate and mark codes as redeemed upon checkout
    3. Log the redemption data (user, campaign, and time) for ROI analysis

    ### Complete workflow example

    | Step | Event                                    | Action                                                                                       |
    | ---- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
    | 1    | User triggers "abandoned search" segment | User enters Journey via segment                                                              |
    | 2    | Journey triggers email send              | OneSignal attaches Data Feed, calls your API with the user's `external_id` and campaign name |
    | 3    | API returns JSON                         | OneSignal populates data feed coupon fields and sends email                                  |
    | 4    | User receives email                      | Example: "Hi George! Save 10% with your personal code: AB10-5F3K-HT9L"                       |
    | 5    | User redeems code                        | Backend validates and logs redemption                                                        |

    ### Testing

    * Test with a user who has a known `external_id`
    * Call your API manually to confirm correct JSON responses
    * Use **Preview** in the OneSignal template editor to verify that data feed coupon fields populate
    * Check API logs for latency and errors
    * If a Data Feed call fails, OneSignal will skip sending the message to that recipient
  </Accordion>

  <Accordion title="Google Sheets: no-code data feed">
    If you want to send dynamic content in your emails but don't have a backend database or API, Google Sheets combined with Google Apps Script is a simple alternative. This guide walks you through setting up a Google Sheet as a live JSON endpoint that OneSignal can pull from at send time.

    <Note>
      This approach works well for any manually curated content that updates on a regular cadence — weekly newsletters, product roundups, editorial digests, event listings, and more.
    </Note>

    ### How it works

    1. You maintain a Google Sheet with your content (one row per item)
    2. A small Apps Script converts the sheet into a JSON endpoint
    3. OneSignal fetches that JSON at send time via a Data Feed
    4. Liquid tags in your email template populate with the sheet data

    ### Step 1: Set up your Google Sheet

    Create a new Google Sheet with your content. Use the first row as column headers — these become your Liquid variable names.

    **Example structure:**

    | title     | image        | price   | link         | category   |
    | --------- | ------------ | ------- | ------------ | ---------- |
    | Product A | https\://... | \$24.00 | https\://... | Category 1 |
    | Product B | https\://... | \$68.00 | https\://... | Category 2 |

    <Note>
      Keep column headers lowercase with no spaces — this makes them easier to reference in Liquid tags.
    </Note>

    ### Step 2: Add the Apps Script

    In your Google Sheet, go to **Extensions > Apps Script** and paste the following code:

    ```javascript theme={null}
    function doGet() {
      const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
      const data = sheet.getDataRange().getValues();
      const headers = data[0];
      const rows = data.slice(1);

      const result = {};

      rows.forEach((row, index) => {
        const slot = index + 1;
        headers.forEach((header, i) => {
          result[`item_${slot}_${header}`] = row[i];
        });
      });

      return ContentService.createTextOutput(JSON.stringify(result))
        .setMimeType(ContentService.MimeType.JSON);
    }
    ```

    This script reads your sheet and transforms it into a flat JSON object. Each row becomes a numbered item slot:

    ```json theme={null}
    {
      "item_1_title": "Product A",
      "item_1_price": "$24.00",
      "item_2_title": "Product B",
      "item_2_price": "$68.00"
    }
    ```

    ### Step 3: Deploy the script as a web app

    <Steps>
      <Step title="Open the Deploy menu">
        Click **Deploy > New deployment**.
      </Step>

      <Step title="Configure the deployment">
        Select type: **Web app**. Set **Execute as**: Me. Set **Who has access**: Anyone.
      </Step>

      <Step title="Deploy and copy the URL">
        Click **Deploy** and copy the web app URL. This is the URL you'll use in OneSignal.
      </Step>
    </Steps>

    <Warning>
      Any time you update the script, you must create a **new version** under Manage Deployments for changes to take effect on the live URL. Saving the script alone is not enough.
    </Warning>

    ### Step 4: Create a Data Feed in OneSignal

    <Steps>
      <Step title="Navigate to Data Feeds">
        In your OneSignal dashboard, go to **Data > Data Feeds** and click **New Data Feed**.
      </Step>

      <Step title="Configure the feed">
        Set a descriptive **Name** (e.g. `Weekly Content`) and an **Alias** you'll reference in Liquid tags (e.g. `weekly_content`). Set the **URL** to your Apps Script web app URL.
      </Step>

      <Step title="Activate">
        Save and activate the Data Feed so it's available for use in templates.
      </Step>
    </Steps>

    ### Step 5: Use Liquid tags in your email template

    Reference your sheet data in any email template using the following syntax:

    ```liquid theme={null}
    {{ data_feed.weekly_content.item_1_title }}
    {{ data_feed.weekly_content.item_1_price }}
    {{ data_feed.weekly_content.item_1_image }}
    {{ data_feed.weekly_content.item_2_title }}
    ```

    The pattern is always:

    ```liquid theme={null}
    {{ data_feed.{alias}.item_{row number}_{column header} }}
    ```

    ### Step 6: Attach the Data Feed to your message

    When creating a new email message or template, attach the Data Feed under **Personalization > Data Feeds** before sending. OneSignal fetches the latest data from your sheet at send time.

    ### Updating content

    To update your email content for the next send, open your Google Sheet and update the rows. No script changes or redeployment needed — the URL always serves the current sheet data.

    ### Tips

    * **Add or remove rows freely.** Just make sure your Liquid tags in the template match the number of rows in your sheet.
    * **Column headers are your variable names.** Renaming a column means updating the Liquid tags in your template to match.
    * **Test your endpoint first.** Paste your Apps Script URL directly in a browser to verify the JSON output before connecting it to OneSignal.
    * **Format numbers as text.** If you include currency or other formatted values, set those cells to Plain Text in Google Sheets to prevent formatting from being stripped.
    * **The script is reusable.** The same Apps Script works for any sheet structure — no modifications needed.
  </Accordion>
</AccordionGroup>

***

## FAQ

### My Data Feed values are not appearing in the message. What should I check?

Verify these in order:

1. The Data Feed is **attached** to the template (under **Personalization > Data Feeds**).
2. Your Liquid syntax matches the JSON response structure exactly — `{{ data_feed.<alias>.<field> }}`.
3. The API endpoint returns valid JSON when called manually with the same identifiers.
4. The recipient has the required identifier (e.g., `external_id`) stored in OneSignal.

### Why are messages sending slowly?

Data Feed API calls run at send time for every recipient. If your API responds slowly or cannot handle concurrent requests, message delivery slows proportionally. Aim for under 250 ms response time and ensure your infrastructure can handle your send volume.

### Why are some recipients not getting messages?

If the Data Feed API call fails for a recipient — due to a 404, timeout, or missing data — OneSignal skips that recipient entirely. Check the error log in your Data Feed configuration and your own API logs for failures. Verify those users have the required identifiers in OneSignal.

### Can I use more than one Data Feed in a template?

Not currently. Each template supports one Data Feed. Fetch all the data you need in a single API response. If you need multiple feeds, [share your use case](https://survey.survicate.com/954895d3e7ed1348/?p=anonymous).

### Are Data Feeds available for push notifications or SMS?

No. Data Feeds are currently available only for email messages sent through Journeys. Support for additional channels is planned — [share your use case](https://survey.survicate.com/954895d3e7ed1348/?p=anonymous) to help prioritize.

### What happens if my API is down when the message sends?

OneSignal skips any recipient whose Data Feed call fails. The message is not sent to that recipient, and no fallback value is inserted. Monitor your API uptime and error rates during scheduled sends.

## Related pages

<Columns>
  <Card title="Liquid syntax" icon="code" href="./using-liquid-syntax">
    Full reference for Liquid templating in OneSignal messages.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build automated messaging workflows that trigger Data Feed emails.
  </Card>

  <Card title="Custom events" icon="bolt" href="./custom-events">
    Trigger Journeys and pass event properties for Data Feed URLs.
  </Card>

  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Overview of all personalization methods — tags, Liquid, dynamic content, and Data Feeds.
  </Card>
</Columns>


# Data & background notifications
Source: https://documentation.onesignal.com/docs/en/data-notifications

Send silent push notifications to sync data or trigger background tasks on iOS and Android without displaying a visible message.

## What are silent notifications?

Silent notifications let you wake your app and perform background tasks—such as syncing or refreshing data—without showing a visible message or playing a sound.

On iOS, these are called **Background Notifications**, and on Android, they're known as **Data Notifications**. Together, they're often referred to as silent pushes and behave differently from normal, visible notifications.

### Limitations

* **Apps cannot receive silent pushes if**:
  * **iOS**: The app has been closed by the user, such as swiping it away from the app switcher. (See [Apple support](https://support.apple.com/en-us/HT201330)).
  * **Android**: The app has been force-quit via device settings or automatically by some manufacturers when swiped away. ([Android force-stop behavior](./notifications-show-successful-but-are-not-being-shown#android-app-is-force-stopped)).
* **Delivery is not guaranteed**:
  * Both Apple and Google treat silent notifications as *best-effort*. iOS may delay or drop delivery under Low Power Mode, Background App Refresh off, or if the app was closed by the user. Android may throttle or batch delivery under Doze or OEM power-saving rules.
  * Because of this, **silent notifications should never be used for critical updates**.
* **Subscribed users only**: The OneSignal SDK only sends data notifications to subscribed [Subscriptions](./subscriptions). To reach unsubscribed users, see [this iOS SDK workaround](https://github.com/OneSignal/OneSignal-iOS-SDK/issues/302).
* **Limited support for cross-platform SDKs**:
  * Silent notifications must be handled in native code (Java/Kotlin for Android, Swift/Obj-C for iOS).
  * iOS requires implementation of [`application:didReceiveRemoteNotification:fetchCompletionHandler:`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application).
  * Android requires implementation of a [Notification Service Extension](./service-extensions).

***

## Sending silent notifications from OneSignal

Follow these steps to send a silent notification from OneSignal:

<Steps>
  <Step title="Omit visible content">
    Remove any visible text or titles from the message. This includes:

    * **API**: `contents`, `headings`, `subtitle` in your [Create notification](/reference/create-message) API request.
    * **Dashboard**: Message, Title, Subtitle
  </Step>

  <Step title="Set content_available">
    * **API**: Set `content_available` to `true`.
    * **Dashboard**: Check **Content available** under "Send to Apple iOS". Despite the label, this setting applies to all platforms and signals to OneSignal that no visible message is included.
  </Step>

  <Step title="Add data to the notification">
    * **API**: Use the `data` parameter.
    * **Dashboard**: Use the **Additional Data** fields.
  </Step>
</Steps>

### Example API payload

```bash theme={null}
curl -X POST https://api.onesignal.com/notifications \
  -H "Authorization: Key YOUR_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "include_aliases": { "external_id": ["user-123"] },
    "target_channel": "push",
    "content_available": true,
    "data": {
      "action": "sync_data",
      "version": "2"
    }
  }'
```

***

## Platform-specific setup

### iOS background notification setup

To handle background notifications, your iOS app must have the **Background Modes > Remote Notifications** capability enabled in Xcode. This is typically added if you followed the [Mobile SDK Setup](./mobile-sdk-setup).

To process the notification, implement the `AppDelegate` method [`application(_:didReceiveRemoteNotification:fetchCompletionHandler:)`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application).

Apple documentation:

* [Pushing Background Updates to Your App](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app?language=objc)
* [Generating a Remote Notification](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification)

<Warning>
  If the user has closed the app (swiped it away from the app switcher), iOS will not deliver the notification.

  In such cases, include a visible `contents` message and process data in the [`UNNotificationServiceExtension.didReceive`](./service-extensions#ios-notification-service-extension).
</Warning>

***

### Android data notification setup

Handle data notifications on Android using the [Notification Service Extension](./service-extensions).

This lets you:

* Process notifications as long as the app hasn't been force closed
* Customize how notifications are displayed or suppressed

Android documentation:

* [FCM data messages](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages)
* [Optimize for Doze and App Standby](https://developer.android.com/training/monitoring-device-state/doze-standby)

<Warning>
  If the app has been force-stopped (via device settings or by some OEM battery optimization), Android will not deliver the notification. See [Android force-stop behavior](./notifications-show-successful-but-are-not-being-shown#android-app-is-force-stopped).
</Warning>

***

## Sending VoIP notifications

VoIP notifications are supported but require additional configuration outside the standard OneSignal SDKs. OneSignal does not register VoIP tokens automatically.

<Card title="VoIP Notifications Setup Guide" icon="phone" href="./voip-notifications">
  Configure VoIP push notifications for real-time calling on iOS.
</Card>

***

## FAQ

### Can silent notifications be used to detect uninstalls or unsubscribes?

Not reliably. Silent notifications are best-effort and not guaranteed to be delivered, as explained in the [Limitations](#limitations) section.

Instead:

* Send visible notifications (with content) to all your users at least once a month.
* Optionally send silent notifications as a supplemental check.

For more details on handling subscription status changes, see the [Subscriptions](./subscriptions) guide.

### Do confirmed deliveries work with silent notifications?

No. Confirmed deliveries require the SDK to execute a callback when the notification is displayed. Silent notifications are not displayed, so the SDK receipt callback is never triggered.

### Can I use silent notifications to measure how many users are reachable?

No, not reliably. Silent notifications aren't guaranteed delivery.

1. **Delivery is not guaranteed** — both Apple and Google treat silent notifications as best-effort and may delay or drop them. For example, iOS will drop them if the app is closed (force quit) and Android and iOS will throttle them under power-saving rules.

2. **Delivery is not confirmed** — confirmed deliveries do not work with silent notifications, so you have no way to know which users actually received the push.

To measure reachable users, send a visible notification and track delivery metrics in [Analytics](./analytics-overview).

***

<Columns>
  <Card title="Service extensions" icon="puzzle-piece" href="./service-extensions">
    Handle notification processing in native code on iOS and Android.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    Understand Subscription types and how they connect to Users.
  </Card>

  <Card title="Create Message API" icon="code" href="/reference/create-message">
    Send notifications programmatically, including silent pushes.
  </Card>
</Columns>


# Deep linking
Source: https://documentation.onesignal.com/docs/en/deep-linking

Send users from OneSignal push, in-app, email, and SMS messages to a specific screen in your Android or iOS app using Universal Links, App Links, or custom URI schemes.

## Overview

A deep link routes the recipient of a OneSignal message to a specific screen in your app instead of a web page. OneSignal delivers the link to the device; the operating system and your app are responsible for resolving it.

This guide covers how to use deep links **inside OneSignal messages** — it does not cover how to configure your app to receive them. For platform setup, see Apple's [Supporting universal links in your app](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) and Google's [About deep links](https://developer.android.com/training/app-links).

***

## Prerequisites

Before you can deep-link from a OneSignal message, your app must already be set up to receive the link type you plan to use:

* The [OneSignal Mobile SDK](./mobile-sdk-setup) is installed and initialized.
* Your app developers have configured a deep link handler for **each platform you target**:
  * **iOS** — [Universal Links](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) (Associated Domains entitlement + [apple-app-site-association (AASA) file](https://developer.apple.com/documentation/xcode/supporting-associated-domains) hosted on your domain) and/or a [custom URL scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) registered in `CFBundleURLTypes`.
  * **Android** — [App Links](https://developer.android.com/training/app-links) (intent filters with `autoVerify="true"` + [Digital Asset Links file (`assetlinks.json`)](https://developer.android.com/training/app-links/verify-applinks) hosted on your domain) and/or a custom URI scheme registered in your `AndroidManifest.xml`.
* For email and SMS/RCS, only Universal Links / App Links work — custom URI schemes are not clickable from those clients.

Once a link is working on the device for a regular tap (paste into Notes on iOS or run `adb shell am start -a android.intent.action.VIEW -d "<url>"` on Android), OneSignal can deliver it through any supported channel.

***

## Choose a link type

| Type                         | URL format                    | Supported in OneSignal       | Fallback when app is not installed |
| ---------------------------- | ----------------------------- | ---------------------------- | ---------------------------------- |
| **Universal Links** (iOS 9+) | `https://yourdomain.com/path` | Push, in-app, email, SMS/RCS | Opens the URL in Safari            |
| **App Links** (Android 6+)   | `https://yourdomain.com/path` | Push, in-app, email, SMS/RCS | Opens the URL in the browser       |
| **Custom URI schemes**       | `myapp://path`                | Push, in-app only            | Fails silently or shows an error   |

**Recommendation:** Use Universal Links / App Links (`https://`) for anything sent via email or SMS — custom schemes do not work in those clients. For push and in-app messages, either works.

<Info>
  On Android 12+, an `https://` link that is **not** a verified App Link opens in the user's default browser, not your app. If deep links from push or email are opening the browser on Android, the App Link verification is the first thing to check.
</Info>

***

## Send a deep link in a push notification

OneSignal supports two ways to attach a deep link to a push notification. Pick one based on how much control you want over navigation.

### Launch URL (`url` / `app_url`)

Set the Launch URL in the dashboard, or pass `url` (all platforms) or `app_url` (mobile only) in the API.

```json theme={null}
{
  "app_id": "YOUR_APP_ID",
  "contents": { "en": "Your order shipped" },
  "url": "https://yourdomain.com/orders/12345"
}
```

| Platform | Behavior when the notification is tapped                                                                                                                                               |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Android  | Android resolves the URL. Verified App Link → opens directly in your app. Non-verified `https://` → opens the browser. Custom scheme → opens the registered app.                       |
| iOS      | OneSignal's iOS SDK calls `openURL`, which opens Safari first, then bounces to your app through the Universal Link handshake. See [iOS Launch URL behavior](#ios-launch-url-behavior). |

### Additional Data (`data`) — recommended for mobile

Put the destination in Additional Data instead and do the navigation yourself in the [push click listener](#handle-deep-links-in-your-app). This avoids the iOS browser bounce entirely and lets you pass structured context.

```json theme={null}
{
  "app_id": "YOUR_APP_ID",
  "contents": { "en": "Your order shipped" },
  "data": {
    "deep_link": "https://yourdomain.com/orders/12345",
    "order_id": "12345"
  }
}
```

<Tip>
  For mobile push, prefer Additional Data + a click listener. You get full control over navigation, no browser flash on iOS, and you can pass extra fields (like `order_id`) that aren't part of the URL.
</Tip>

### iOS Launch URL behavior

OneSignal's iOS SDK uses `openURL` to handle the `url` / `app_url` property. Even with Universal Links correctly configured, this causes the link to open in the browser first and then redirect back into the app — a noticeable "flash" for users.

You have two ways to avoid it:

1. **Use `data` instead of `url`** and route from your [push click listener](#handle-deep-links-in-your-app). Recommended.
2. **Suppress Launch URLs globally.** Add a Boolean `OneSignal_suppress_launch_urls` with value `YES` to your app's `Info.plist`. OneSignal will stop calling `openURL`, and you must handle every deep link in the click listener.

***

## Send a deep link in an in-app message

In-app messages use click actions instead of a URL property. For the full list of click action types, see [In-app click actions](./iam-click-actions).

### Drag-and-drop editor

1. Add a button, image, or background click target.
2. Open **Add click action**.
3. Choose one of:
   * **URL** — opens the link in the device's browser (or, if Universal Links / App Links are configured for that domain, opens your app).
   * **Custom action ID** — passes the value to your [in-app click listener](#handle-deep-links-in-your-app) without opening anything. Use this when you want to navigate inside the app you control.
4. Enter your deep link (e.g. `https://yourdomain.com/promo`) or action identifier (e.g. `open_promo`).

### HTML editor

In sandboxed HTML in-app messages, use the [In-App Message JS API](./in-app-message-api):

* `OneSignalIamApi.openUrl(e)` — opens the URL in the device browser using default URL handling.
* `OneSignalIamApi.addClickName(e)` — sends a custom click name to your [in-app click listener](#handle-deep-links-in-your-app) without opening a browser.

```html theme={null}
<button id="open-in-app" data-onesignal-unique-label="open-in-app">Check it out!</button>
<script>
  document.getElementById("open-in-app").addEventListener("click", function(e) {
    OneSignalIamApi.addClickName(e);
  });
</script>
```

***

## Send a deep link in an email

By default, OneSignal rewrites every link in an email for click tracking. The rewritten URL uses OneSignal's tracking domain, which does **not** match your app's Associated Domain or Digital Asset Links host — so iOS and Android treat the link as a regular web URL and open the browser instead of your app.

To preserve deep linking in email, disable click tracking for the deep link using one of these options:

| Scope                       | How                                                                                                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Whole email (dashboard)** | Uncheck **Track link clicks** in the email editor.                                                                                                              |
| **Whole email (API)**       | Set `disable_email_click_tracking: true` in the Create message request.                                                                                         |
| **Single link (HTML)**      | Add `disable-tracking=true` to the anchor tag: `<a href="https://yourdomain.com/path" disable-tracking=true>…</a>`. Tracking stays enabled on every other link. |

<Frame>
  <img alt="OneSignal email editor with Track link clicks checkbox unchecked" />
</Frame>

<Warning>
  Disabling tracking removes click metrics from [Email Message Reports](./email-message-reports). Use the per-link `disable-tracking=true` attribute to keep analytics on non–deep-link URLs.
</Warning>

### Expected behavior

| Scenario                                                          | Result                                                                |
| ----------------------------------------------------------------- | --------------------------------------------------------------------- |
| iOS + Safari + Universal Link + tracking disabled                 | Opens app directly                                                    |
| iOS + Safari + Universal Link + tracking enabled                  | Opens Safari, link doesn't match AASA, stays in browser               |
| iOS + non-Safari mail client + Universal Link + app not installed | Falls back to web; can redirect to App Store                          |
| Android + App Link + tracking disabled                            | Opens app directly                                                    |
| Android + App Link + tracking enabled                             | Opens browser, link doesn't match `assetlinks.json`, stays in browser |

***

## Send a deep link in SMS or RCS

SMS and RCS messages support only `https://` links — custom schemes like `myapp://` won't open from the Messages app. Insert the link inline in the message body.

If you use OneSignal's trackable link feature (`{{ "https://..." | track_link }}` or the **Insert Trackable Link** button), the URL is replaced with a `1sgnl.co` short link, which breaks Universal Link / App Link domain matching. Do not wrap deep-link URLs in `track_link` — send them raw so the OS can match them to your app.

See [URLs, links, & deep links → SMS/RCS trackable links](./links#sms%2Frcs-trackable-links) for the tracking-link format.

***

## Handle deep links in your app

The most reliable way to route a OneSignal deep link is to intercept it with a click listener and do the navigation yourself. This works regardless of platform quirks (iOS `openURL`, Android 12+ verification, email tracking rewrites) as long as your listener receives the event.

### Push notification click listener

Register the listener as early as possible — in `Application.onCreate()` on Android or `application(_:didFinishLaunchingWithOptions:)` on iOS — so it is active before the user taps a cold-start notification.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.Notifications.addClickListener { event ->
    val url = event.notification.launchURL
    val data = event.notification.additionalData
    // Route to the correct screen based on url or data
  }
  ```

  ```swift Swift theme={null}
  class AppDelegate: UIResponder, UIApplicationDelegate, OSNotificationClickListener {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
      OneSignal.Notifications.addClickListener(self)
      return true
    }

    func onClick(event: OSNotificationClickEvent) {
      let url = event.notification.launchURL
      let data = event.notification.additionalData
      // Route to the correct screen based on url or data
    }
  }
  ```

  ```javascript React Native theme={null}
  OneSignal.Notifications.addEventListener('click', (event) => {
    const url = event.notification.launchURL;
    const data = event.notification.additionalData;
    // Route to the correct screen based on url or data
  });
  ```

  ```dart Flutter theme={null}
  OneSignal.Notifications.addClickListener((event) {
    final url = event.notification.launchUrl;
    final data = event.notification.additionalData;
    // Route to the correct screen based on url or data
  });
  ```

  ```csharp Unity (C#) theme={null}
  OneSignal.Notifications.Clicked += (sender, e) => {
    var url = e.Notification.LaunchURL;
    var data = e.Notification.AdditionalData;
    // Route to the correct screen based on url or data
  };
  ```
</CodeGroup>

For the full API including Java, Objective-C, and Cordova/Ionic, see [`addClickListener()` Push](./mobile-sdk-reference#addclicklistener-push).

### In-app message click listener

Fires when a user taps a button configured with a **Custom action ID** (or when `OneSignalIamApi.addClickName` is called in HTML).

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.InAppMessages.addClickListener { event ->
    val actionId = event.result.actionId
    // Route based on the action ID (your deep link or internal route name)
  }
  ```

  ```swift Swift theme={null}
  func onClick(event: OSInAppMessageClickEvent) {
    let actionId = event.result.actionId
    // Route based on the action ID (your deep link or internal route name)
  }
  ```

  ```javascript React Native theme={null}
  OneSignal.InAppMessages.addEventListener('click', (event) => {
    const actionId = event.result.actionId;
    // Route based on the action ID (your deep link or internal route name)
  });
  ```

  ```dart Flutter theme={null}
  OneSignal.InAppMessages.addClickListener((event) {
    final actionId = event.result.actionId;
    // Route based on the action ID (your deep link or internal route name)
  });
  ```
</CodeGroup>

For the full API, see [`addClickListener()` In-App](./mobile-sdk-reference#addclicklistener-in-app).

***

## Personalize deep links per user

Every URL field in OneSignal — Launch URL, Additional Data values, in-app URL actions, email body links — accepts [Liquid syntax](./using-liquid-syntax). Use it to inject the user's `external_id`, tags, or `custom_data` into the path or query string.

```text theme={null}
https://yourdomain.com/profile/{{subscription.external_id}}
https://yourdomain.com/orders/{{message.custom_data.order_id}}
https://yourdomain.com/topic/{{ interest | default: 'home' }}
```

See [Dynamic URLs](./links#dynamic-urls) for the full list of data sources and fallback filters.

***

## Test deep links from OneSignal

1. Send a test message from the OneSignal dashboard with your deep link as the Launch URL, Additional Data value, or in-app click action.
2. Tap the notification or in-app button on a real device (Universal Links do not activate in the iOS Simulator from all sources).
3. Confirm the app opens directly to the right screen and your click listener logs the expected URL or action ID.

For platform-level verification (before involving OneSignal), Apple provides the [Associated Domains validation tool](https://search.developer.apple.com/appsearch-validation-tool/) and Android offers `adb shell pm verify-app-links --re-verify <package>`.

<Note>
  On iOS, Universal Links do not activate from the Safari address bar. Test from Notes, Mail, Messages, or a OneSignal push/in-app message.
</Note>

***

## Troubleshooting

### iOS push opens Safari for a second before my app

OneSignal's SDK uses `openURL` for the Launch URL. Fix with one of the [two approaches above](#ios-launch-url-behavior): send the link in Additional Data and route from the click listener, or set `OneSignal_suppress_launch_urls=YES` in `Info.plist`.

### Android push opens the browser instead of the app

The `https://` link is not being recognized as a verified App Link. Check that your intent filter uses `android:autoVerify="true"`, that `assetlinks.json` is reachable at `https://yourdomain.com/.well-known/assetlinks.json` (HTTP 200, `application/json`, no redirects), and that its SHA-256 fingerprint matches the certificate you actually shipped (Play App Signing uses a different fingerprint than your local keystore). See Google's [Troubleshoot App Links](https://developer.android.com/training/app-links/troubleshoot).

### Deep link works in push but not in email

Email click tracking rewrites the URL and breaks domain matching. [Disable tracking](#send-a-deep-link-in-an-email) for that link or that email.

### Deep link is received but the app doesn't navigate

* The click listener was registered **after** the click event fired. Register in `Application.onCreate()` (Android) or `application(_:didFinishLaunchingWithOptions:)` (iOS), before any other async work.
* The `launchURL` or `actionId` doesn't match what your router expects. Log the raw value.
* On iOS, the Launch URL (`url`) is being used without suppressing it — the browser may consume the link before your listener fires. Switch to Additional Data.

### I updated my AASA file and iOS still doesn't open the app

Starting in iOS 14 / macOS 11, Apple's CDN fetches AASA files, not the device. The CDN requests a refresh within 24 hours, and installed devices re-check roughly once per week. Reinstall the app to force an immediate fetch during testing.

***

## FAQ

### Should I use Launch URL or Additional Data?

Additional Data is recommended for mobile deep links. It bypasses iOS's `openURL` browser flash and gives your click listener structured data instead of a string to parse. Launch URL is simpler and fine for web push or when you accept the iOS behavior.

### Do deep links work with OneSignal Journeys?

Yes. Set the Launch URL or Additional Data on any push or in-app step the same way you would for a one-off message. Email steps follow the same click-tracking rules — disable tracking on the deep link.

### Can I deep link into another app (not mine)?

Yes, for push and in-app only. Set a custom URL scheme that the other app registers (e.g. `whatsapp://send?phone=15551234567`). Custom schemes do not work in email or SMS clients.

### What happens if the user doesn't have the app installed?

With Universal Links (iOS) or App Links (Android), the `https://` URL loads as a normal web page — you can host a landing page that redirects to the App Store / Play Store. With a custom URI scheme (`myapp://`), the tap fails silently or shows an error; there is no fallback.

### Can I use a trackable SMS link as a deep link?

No. OneSignal's SMS trackable links rewrite the URL to `1sgnl.co`, which isn't associated with your app. Send the original `https://` URL so the OS can match it to your Associated Domain or Digital Asset Links entry.

### Do I need the OneSignal SDK to handle a deep link?

No, but it's recommended. Universal Links / App Links are handled by the OS regardless of which SDK sent the message. Using OneSignal's click listener gives you a consistent entry point across channels and avoids platform-specific quirks like the iOS `openURL` flash.

***

<Columns>
  <Card title="URLs, links, & deep links" icon="link" href="./links">
    Launch URLs, UTM parameters, dynamic URLs, and click tracking across every channel.
  </Card>

  <Card title="Mobile SDK reference" icon="code" href="./mobile-sdk-reference">
    Full API reference for push and in-app click listeners and notification events.
  </Card>

  <Card title="In-app click actions" icon="hand-pointer" href="./iam-click-actions">
    Configure URL, custom action ID, and other click actions for in-app buttons.
  </Card>

  <Card title="Mobile push setup" icon="mobile" href="./mobile-push-setup">
    Platform-specific push notification setup for Android and iOS.
  </Card>
</Columns>


# Design emails with drag-and-drop
Source: https://documentation.onesignal.com/docs/en/design-emails-with-drag-and-drop

Build responsive emails visually with OneSignal’s Drag and Drop Email Builder — settings, rows, content blocks, personalization, and compliance links.

## Overview

The OneSignal Drag and Drop Email Builder lets you visually design responsive emails exactly as they appear in recipients’ inboxes — without writing full HTML.

You build emails using three core components:

* **Settings** – global styles and layout applied across the entire email
* **Rows** – horizontal layout containers that control structure and responsiveness
* **Content** – individual blocks such as text, images, buttons, and HTML

The sections below cover each component and the recommended order for building an email.

<Note>
  Use the Drag and Drop Email Builder if you want to:

  * Design emails visually without managing full HTML (HTML blocks are available)
  * Reuse rows or templates across campaigns
  * Allow non-technical teammates to safely edit content

  If you need full HTML control, custom fonts everywhere, or advanced dark mode logic, use the [HTML Editor](./design-emails-with-html) instead.
</Note>

### Recommended build flow

Follow this order for the best results and fewer rendering issues:

1. Configure global styles in **Settings**
2. Add layout structure using **Rows**
3. Insert **Content** blocks
4. Add personalization and links
5. Add an unsubscribe link (for marketing emails)
6. Save as a template or send

<Check>
  When finished, your email should:

  * Be no wider than 600px
  * Render cleanly on mobile and desktop
  * Include required compliance links
</Check>

<Warning>
  **Common mistakes that cause rendering or deliverability issues:**

  * **Missing unsubscribe link** — required for marketing emails. Without one, inbox providers are more likely to flag your email as spam.
  * **Email wider than 600px** — causes horizontal scrolling on mobile and breaks layouts in many clients.
  * **Background images in rows** — Outlook and several mobile clients do not render them. Use Image blocks instead.
  * **No fallback fonts** — custom web fonts only load in a few clients. Always declare system font fallbacks.
  * **Oversized images** — emails over 1 MB load slowly and may be blocked. Individual images should be under 200 KB.
</Warning>

***

## Settings

Settings define the foundational layout and styles for your email. These values cascade down to rows and content blocks unless explicitly overridden.

<Frame>
  <img alt="Global settings panel in the Drag and Drop Editor" />
</Frame>

| Design Setting                | Description                                                            |
| ----------------------------- | ---------------------------------------------------------------------- |
| Content area width            | Width of the email in pixels. **Recommended:** `600px`.                |
| Content area alignment        | Align content left or center.                                          |
| Background color              | Color behind the content area.                                         |
| Content area background color | Color inside the content area.                                         |
| Default font                  | Applied to all text unless overridden. Custom fonts require HTML.      |
| Link color                    | Default color for all links.                                           |
| Language                      | Sets the HTML `lang` attribute for accessibility. Defaults to English. |

<Note>
  **Recommended default:** Configure as much styling as possible in Settings to ensure consistency and reduce per-block overrides.
</Note>

***

## Rows

Rows define the horizontal layout of your email. Each row can contain one or more columns, and each column can contain content blocks.

Drag and drop rows into the editor to build your structure.

<Frame>
  <img alt="Adding rows to structure an email" />
</Frame>

<Note>
  Use rows to control layout and spacing. Avoid relying on individual content blocks for major layout decisions.
</Note>

### Saved rows

Saved rows let you reuse headers, footers, or repeated sections across emails and templates.

Click the **save icon** on a row to save it.

<Frame>
  <img alt="Saving a row for reuse" />
</Frame>

Access saved rows from **Rows > Saved rows**.

<Frame>
  <img alt="Selecting a saved row" />
</Frame>

Saved row categories:

* **Empty** – blank row templates
* **My Saved Rows** – rows created by you or your team
* **Sample Rows** – OneSignal examples

### Row properties

Click the outer edge of a row to edit row-level settings.

<Note> If you see **Content** instead of **Row** when hovering, you’ve selected a content block. Click the outer container edge until the label reads **Row**. </Note>

| Row Property     | Description                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| Backgrounds      | Color or image behind the row. **Recommended:** set background color in Settings for consistency. |
| Borders          | Border color, width, and style.                                                                   |
| Layout           | Show or hide rows on mobile or desktop.                                                           |
| Columns          | Add, remove, or resize columns and adjust column padding.                                         |
| Delete/Duplicate | Select a row and use the **delete** or **duplicate** icons to remove or copy it.                  |

<Warning> Avoid background images in rows. Email client support is inconsistent. If the row contains only an image, use an **Image block** instead. </Warning>

***

## Content

Content blocks are the elements recipients see — text, images, buttons, dividers, and HTML.

Drag a content block into a row column. It automatically adapts to the column width.

<Frame>
  <img alt="Available content blocks" />
</Frame>

<Info>
  **Decision rules for content blocks:**

  * Use **Text blocks** for most copy.
  * Use **Image blocks** for visuals or custom typography.
  * Use **HTML blocks** only when you need advanced styling or behavior.
</Info>

### Custom fonts

The Drag and Drop Editor supports system fonts by default. To use custom fonts, you must use an HTML block.

```html HTML block theme={null}
<!-- Place this into a HTML block at the top of your email -->
<style type="text/css">
  /* Declare Bebas Neue (only loads in clients that support web fonts) */
  @font-face {
    font-family: 'Bebas Neue';
    font-style: normal;
    font-weight: 400;
    src: url('https://fonts.gstatic.com/s/bebasneue/v9/JTUSjIg69CK48gW7PXoo9Wlhzg.ttf') format('truetype');
  }
</style>

<h1 style="font-family:'Bebas Neue', Arial, Helvetica, sans-serif; 
           font-size:36px; line-height:1.2; margin:0; text-transform:uppercase;">
  Welcome!
</h1>
<p style="font-family:Arial, Helvetica, sans-serif; font-size:16px; margin:12px 0 0;">
  Thanks for subscribing.
</p>
```

<Warning>
  Many email clients (including Gmail and Outlook for Windows) do not load web fonts. Use system fonts for body text and reserve custom fonts for headlines only. Always include fallback fonts, or use images for guaranteed typography.
</Warning>

### Images & video

Upload images directly to the OneSignal dashboard so your team can reuse them. The editor supports cropping, filtering, and other effects. You can also reference externally hosted images and videos by URL — make sure each URL is publicly accessible.

#### Recommended image sizes for email

<AccordionGroup>
  <Accordion title="Aspect ratios">
    * Header/Banner images: `3:1` or `4:1` (e.g., `600×200` or `600×150`)
    * Hero images: `16:9` or `2:1` (e.g., `600×338` or `600×300`)
    * Square images: `1:1` (e.g., `300×300`) — good for product grids
    * Thumbnails: `1:1` or `4:3`
    * Max width: `600–700px` is standard (most email clients)
    * Design at `2x` for retina displays (e.g., `1200px` wide, displayed at `600px`)
  </Accordion>

  <Accordion title="File size">
    * Keep individual images under `100–200 KB`
    * Total email size (including images) under `1 MB`
    * Smaller images mean faster load times and better deliverability
  </Accordion>

  <Accordion title="File formats">
    * **JPG** — best for photos
    * **PNG** — best for graphics, logos, and images with transparency
    * **GIF** — for simple animations (keep file size small)
    * **WebP** — not widely supported in email yet; avoid
  </Accordion>

  <Accordion title="General tips">
    * Always include alt text for accessibility and for when images do not load
    * Use inline CSS for styling (many clients strip `<style>` tags)
    * Avoid background images (inconsistent client support)
    * Test across clients — Gmail, Outlook, and Apple Mail all render differently
    * Outlook often ignores image dimensions, so set both `width` and `height` attributes in HTML
  </Accordion>
</AccordionGroup>

### Links

OneSignal enables link tracking by default and supports multi-link tracking.

<Columns>
  <Card title="Links" icon="link" href="./links#email">
    Configure link tracking, multi-link tracking, and click analytics for email.
  </Card>

  <Card title="Deep linking" icon="arrow-up-right-from-square" href="./deep-linking">
    Route recipients to specific screens in your app from email links.
  </Card>
</Columns>

#### Unsubscribe links

All marketing emails must contain an unsubscribe link. Emails without one are more likely to be flagged as spam by inbox providers. When a recipient clicks the default OneSignal unsubscribe link, their email [Subscription](./subscriptions) is automatically set to unsubscribed.

Add the `[unsubscribe_url]` tag to your email using either method:

<Tabs>
  <Tab title="Editor (Special links)">
    1. Select the text you want to turn into the unsubscribe link.
    2. Click the link icon in the toolbar.
    3. Choose **Special links > Unsubscribe**.

    <Frame>
      <img alt="Adding the unsubscribe link using Special links in the editor" />
    </Frame>
  </Tab>

  <Tab title="HTML block">
    Paste the following into an HTML block:

    ```html theme={null}
    <a href="[unsubscribe_url]">Unsubscribe</a>
    ```
  </Tab>
</Tabs>

<Columns>
  <Card title="Unsubscribe links" icon="link-slash" href="./unsubscribe-links-email-subscriptions">
    Compliance requirements and how OneSignal handles unsubscribes.
  </Card>

  <Card title="Custom unsubscribe page" icon="browser" href="./create-custom-unsubscribe-page">
    Replace the default unsubscribe flow with your own branded page.
  </Card>
</Columns>

### HTML blocks

Use HTML blocks when you need control that drag-and-drop content blocks cannot provide:

* **Dark mode overrides** — add `prefers-color-scheme` CSS. See [Dark mode styling](#dark-mode-styling-with-drag-and-drop) below.
* **Custom fonts** — declare `@font-face` rules with fallback stacks.
* **Advanced layouts** — multi-column grids, conditional content, or Outlook-specific markup.

<Note>
  JavaScript is not supported in email. Use inline CSS — many clients strip `<style>` tags, classes, and IDs.
</Note>

### Personalization

Use Liquid templating to insert subscriber-specific content like names, tags, or fallback values. Example: `{{ first_name | default: "there" }}`

<Frame>
  <img alt="Using Liquid templating to personalize messages" />
</Frame>

<Columns>
  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Available personalization variables and how to use them.
  </Card>

  <Card title="Using Liquid syntax" icon="code" href="./using-liquid-syntax">
    Conditionals, filters, loops, and advanced Liquid patterns.
  </Card>
</Columns>

***

## Dark mode

Most emails render acceptably in dark mode without changes. However, emails with brand colors, logos on white backgrounds, or colored sections often need adjustments.

### Do I need dark mode styling?

Add dark mode overrides if your email includes any of the following:

* **Brand-colored sections** — saturated colors become harsh in dark mode and hurt readability
* **Logos or icons on white/light backgrounds** — the background may invert while the image stays light, making it invisible
* **Text on colored backgrounds** — inverted backgrounds can clash with non-inverted text colors
* **Call-to-action buttons** — button backgrounds may invert to unexpected colors

If your email is mostly text with minimal styling, the default rendering is usually acceptable.

### Preview dark mode in the editor

Use the **Preview Mode** button to get a general preview of dark mode rendering. This preview is an approximation — actual rendering varies by inbox provider (see the [client behavior table](#how-email-clients-handle-dark-mode) below).

<Frame>
  <img alt="Preview mode in the Drag and Drop Editor" />
</Frame>

<Frame>
  <img alt="Light and dark mode toggle in the Drag and Drop Editor" />
</Frame>

### How email clients handle dark mode

Every email client applies dark mode differently. You cannot control this behavior directly, but you can design emails that render well across all modes.

| Client                       | Behavior                                                         | Respects `prefers-color-scheme` CSS? |
| ---------------------------- | ---------------------------------------------------------------- | ------------------------------------ |
| **Apple Mail** (iOS/macOS)   | Full color inversion                                             | Yes                                  |
| **Gmail** (iOS/Android apps) | Partial inversion — changes light backgrounds but not all colors | No                                   |
| **Gmail** (Web)              | No dark mode rendering                                           | N/A                                  |
| **Outlook** (Windows)        | Full inversion using Word rendering engine                       | No — ignores most CSS overrides      |
| **Outlook** (Mac/iOS)        | Partial inversion                                                | Yes                                  |
| **Yahoo Mail**               | Partial inversion                                                | No                                   |
| **Samsung Mail**             | Full inversion                                                   | No                                   |

<Warning>
  **Common dark mode failures to watch for:**

  * **Disappearing logos** — a dark logo on a transparent PNG becomes invisible on a dark background. Add a white or light outline, or use a version with a built-in light background.
  * **Unreadable text** — dark text on a light background may stay dark after the background is inverted. Always pair text color overrides with background overrides.
  * **Clashing brand colors** — saturated brand colors that look great on white become harsh on dark backgrounds. Test desaturated or muted alternatives.
  * **Invisible buttons** — CTA buttons with dark text on a brand-colored background may lose contrast after partial inversion.
</Warning>

**Design tips:**

* Avoid pure white (`#FFFFFF`) and pure black (`#000000`). Use off-whites and dark grays to reduce the impact of full-inversion clients.
* Use transparent PNGs with care. They blend well with any background, but dark logos on transparent backgrounds become invisible in dark mode. Add a light outline or use a version with a built-in background for logos.
* On images that include text, outline dark text in white to ensure legibility. For white text on a dark background, outline in black.

### Dark mode styling with drag-and-drop

If only a few elements render poorly in dark mode, you can replace them with HTML blocks and override the styling directly using CSS classes and `!important` declarations.

<Steps>
  <Step title="Add an HTML block to the top of your email">
    Drag an **HTML block** into the first row of your email.

    <Frame>
      <img alt="Adding an HTML block to the top of your email" />
    </Frame>
  </Step>

  <Step title="Add dark mode CSS">
    Paste the following into the HTML block. The `prefers-color-scheme: dark` media query applies styles only when the recipient’s email client is in dark mode.

    ```html HTML block theme={null}
    <meta name="color-scheme" content="light dark" />
    <meta name="supported-color-schemes" content="light dark" />
    <style>
      :root {
        color-scheme: light dark;
      }

      @media (prefers-color-scheme: dark) {
        .email-body {
          background-color: #1a1a1a !important;
          color: #f0f0f0 !important;
        }

        .email-header {
          background-color: #2d2d2d !important;
        }

        .email-button {
          background-color: #0a84ff !important;
        }
      }
    </style>
    ```
  </Step>

  <Step title="Replace problem content with HTML blocks">
    Replace any content blocks that do not render correctly in dark mode with HTML blocks that use the CSS classes defined above.

    <CodeGroup>
      ```html email-header theme={null}
      <div class="email-header" style="background-color: #f5f5f5; padding: 0; text-align: center;">
        <img src="https://dashboard.onesignal.com/assets/email/your-email-strategy-starts-here.jpg" 
             alt="Your email strategy starts here" 
             width="600" 
             style="display: block; width: 100%; max-width: 600px; height: auto;" />
      </div>
      ```

      ```html email-body theme={null}
      <div class="email-body" style="background-color: #ffffff; color: #333333; padding: 24px; font-family: Arial, Helvetica, sans-serif; font-size: 16px; line-height: 1.5;">
        <p style="margin: 0 0 16px;">Hi {{ first_name | default: 'there' }}!</p>
        <p style="margin: 0 0 16px;">Ready to craft a stunning email? Here\u2019s how to get started:</p>
        <ul style="margin: 0 0 16px; padding-left: 20px;">
          <li style="margin-bottom: 8px;"><strong>Drag &amp; drop simplicity:</strong> Add text, images, and buttons to your email.</li>
          <li style="margin-bottom: 8px;"><strong>Build smarter with Saved Rows:</strong> Create reusable headers and footers for consistent branding.</li>
          <li style="margin-bottom: 8px;"><strong>Test &amp; preview:</strong> Verify your email on every device before sending.</li>
        </ul>
      </div>
      ```

      ```html email-button theme={null}
      <div class="email-body" style="background-color: #ffffff; padding: 0 24px 24px; text-align: center;">
        <a class="email-button" href="https://example.com" 
           style="background-color: #0066cc; color: #ffffff; padding: 14px 32px; 
                  text-decoration: none; border-radius: 4px; display: inline-block; 
                  font-family: Arial, Helvetica, sans-serif; font-size: 16px; font-weight: bold;">
          Get Started
        </a>
      </div>
      ```
    </CodeGroup>
  </Step>
</Steps>

<Check>
  Return to preview mode to verify the dark mode styles are applied correctly.
</Check>

***

## Save your work

Save your email design as a [**template**](./templates) for future use.

<Frame>
  <img alt="Save email as a template" />
</Frame>

***

## FAQ

### How do I add a custom unsubscribe link?

Replace the default `[unsubscribe_url]` with your own URL. You are responsible for updating the email Subscription status in OneSignal when a recipient unsubscribes. See [Create a custom unsubscribe page](./create-custom-unsubscribe-page) for setup details.

### Why does my email look different in Outlook?

Outlook on Windows uses the Microsoft Word rendering engine, which does not support modern CSS. Common issues include ignored `max-width`, collapsed background images, and missing web fonts. Test in Outlook specifically and use inline CSS with explicit `width` and `height` attributes on images.

### What is the maximum email size?

Keep total email size (HTML + images) under 1 MB. Emails over 102 KB of HTML are clipped by Gmail, which hides content below the fold behind a "View entire message" link. Optimize images and remove unused code to stay under this threshold.

### Can I reuse parts of an email across multiple campaigns?

Yes. Save any row as a **Saved Row** by clicking the save icon on the row. Saved rows appear under **Rows > My Saved Rows** and can be dragged into any email. For full email reuse, save the entire design as a [template](./templates).

### How do I preview my email before sending?

Use the **Preview** button in the top toolbar to see how your email renders on desktop and mobile. To send a live test, click **Send Test Email** and enter a recipient address. Test emails are delivered to the inbox so you can verify rendering, links, and personalization in actual email clients.

### Do emojis work in emails?

Yes, but they render differently across email clients. Outlook on Windows is the most inconsistent — emojis may appear as black-and-white outlines or boxes. If emojis are part of your subject line or CTA text, test across clients before sending.

### How do I import an existing HTML email template?

You can bring existing HTML templates into OneSignal three ways:

1. Forward the email to OneSignal using [Email Template forwarding](./email-template-forwarding)
2. Use the [Create Template API](/reference/create-template) to upload HTML programmatically
3. Copy-paste your HTML directly into the [HTML Editor](./design-emails-with-html)

## Related pages

<Columns>
  <Card title="Email overview" icon="envelope" href="./email-messaging">
    End-to-end guide to sending email with OneSignal.
  </Card>

  <Card title="Design emails with HTML" icon="code" href="./design-emails-with-html">
    Full HTML control, dark mode overrides, and advanced styling.
  </Card>

  <Card title="Email templates" icon="copy" href="./templates">
    Save and reuse email designs across campaigns.
  </Card>

  <Card title="Unsubscribe links" icon="link-slash" href="./unsubscribe-links-email-subscriptions">
    Add default or custom unsubscribe links for compliance.
  </Card>

  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Personalize emails with tags, Liquid syntax, and dynamic content.
  </Card>

  <Card title="AB testing" icon="flask" href="./ab-testing">
    Test subject lines, content, and send times to optimize engagement.
  </Card>
</Columns>


# Design emails with HTML
Source: https://documentation.onesignal.com/docs/en/design-emails-with-html

Send fully custom branded emails using OneSignal's HTML Editor. Covers supported HTML rules, inline CSS, dark mode, unsubscribe handling, and client limitations.

## Overview

The HTML Editor lets you send fully custom, branded emails using your own HTML.

You should use the HTML Editor when you:

* Need complete control over layout, spacing, and styling
* Already have production-ready HTML email templates
* Are comfortable working within email client limitations

<Info>
  HTML emails are not the same as web pages. Many HTML and CSS features are unsupported or inconsistently rendered across email clients.
</Info>

### Prerequisites

Before using the HTML Editor, make sure you:

* Have experience building responsive HTML emails
* Host all images on publicly accessible URLs (your site, CDN, S3, etc.)

#### Expected outcome

After setup, your email:

* Renders consistently across major clients (Gmail, Outlook, Apple Mail)
* Tracks link clicks correctly
* Includes a working unsubscribe mechanism
* Passes spam and deliverability checks

### Import your own templates

If you already have HTML email templates, you can add them to OneSignal in any of the following ways:

1. Use [Email Template forwarding](./email-template-forwarding)
2. Create templates programmatically using the [Create Template API](/reference/create-template)
3. Copy-paste your HTML into the HTML Editor

<Tip> Start with a proven template rather than writing HTML from scratch. </Tip>

### Design in Figma and export to OneSignal

If your email designs live in Figma, there are two ways to get them into OneSignal as HTML:

* **[Email Love](https://emaillove.com/figma-plugin)**: A Figma plugin that converts your design into production-ready HTML email and uploads it directly to your OneSignal templates. Enter your OneSignal App ID and API key in the plugin's export panel and click upload.
* **[Figma MCP server](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server)**: Connect Figma to an AI coding tool via the MCP server. Point it at your email design frame and ask it to generate HTML email code, then paste the output into the HTML Editor.

<Warning>
  **Common mistakes that cause rendering or deliverability issues:**

  * **Missing unsubscribe link**: Required for marketing emails. Without one, inbox providers are more likely to flag your email as spam.
  * **Using `<style>` blocks instead of inline CSS**: Most email clients strip `<style>` tags. Always inline your styles.
  * **No fallback fonts**: Custom web fonts only load in a few clients. Always declare system font fallbacks.
  * **Oversized images**: Emails over 1 MB load slowly and may be blocked. Individual images should be under 200 KB.
  * **Unsupported HTML**: JavaScript, `<iframe>`, forms, and embedded media are stripped by email clients.
</Warning>

***

## Use the HTML Editor

When creating an email message, select **HTML Editor** as the editor type.

1. Paste or write your HTML in the editor.
2. Use **Send Test Email** to preview rendering across clients and devices.
3. Fix layout issues before scheduling or sending.

<Frame>
  <img alt="HTML editor with code input and live preview" />
</Frame>

### Links & tracking

Link tracking is enabled by default for HTML emails. Multi-link tracking is supported, and clicks appear in message reports.

<Columns>
  <Card title="Links" icon="link" href="./links#email">
    Configure link tracking, multi-link tracking, and click analytics for email.
  </Card>

  <Card title="Deep linking" icon="arrow-up-right-from-square" href="./deep-linking">
    Route recipients to specific screens in your app from email links.
  </Card>
</Columns>

#### Unsubscribe links

All marketing emails must include an unsubscribe link.

Emails without a valid unsubscribe option are more likely to:

* Be marked as spam
* Hurt sender reputation
* Be blocked by inbox providers

<Tabs>
  <Tab title="OneSignal's default unsubscribe link">
    Include the following placeholder anywhere in your HTML (usually in the footer):

    ```html HTML theme={null}
    <a href="[unsubscribe_url]">Unsubscribe</a>
    ```

    When clicked, this link unsubscribes the recipient's email [Subscription](./subscriptions) in OneSignal.
  </Tab>

  <Tab title="Use a custom unsubscribe page (optional)">
    You can link to your own unsubscribe page, but you must:

    * Capture the unsubscribe action
    * Update the recipient’s email Subscription status

    See [Create a custom unsubscribe page](./create-custom-unsubscribe-page) for more details.

    <Warning> If you use a custom unsubscribe URL and do not update the Subscription, users will continue receiving emails. </Warning>
  </Tab>
</Tabs>

***

## HTML email best practices

### Always use inline CSS

Most email clients strip `<style>` blocks and external stylesheets.

Try this tool: [Responsive Email CSS Inliner](https://htmlemail.io/inline/)

### Dark mode styling

Many email clients apply automatic color inversion when dark mode is enabled. This can cause unpredictable results: buttons may appear with a black background and black text, or logos may disappear. Explicitly define how your email should look in both light and dark modes to prevent these issues.

#### How email clients handle dark mode

| Client                       | Behavior                                                        | Respects `prefers-color-scheme` CSS? |
| ---------------------------- | --------------------------------------------------------------- | ------------------------------------ |
| **Apple Mail** (iOS/macOS)   | Full color inversion                                            | Yes                                  |
| **Gmail** (iOS/Android apps) | Partial inversion; changes light backgrounds but not all colors | No                                   |
| **Gmail** (Web)              | No dark mode rendering                                          | N/A                                  |
| **Outlook** (Windows)        | Full inversion using Word rendering engine                      | No; ignores most CSS overrides       |
| **Outlook** (Mac/iOS)        | Partial inversion                                               | Yes                                  |
| **Yahoo Mail**               | Partial inversion                                               | No                                   |
| **Samsung Mail**             | Full inversion                                                  | No                                   |

#### Best practices

* **Define base styles inline.** Always set background and text colors directly on elements instead of relying on defaults or transparency.
* **Use media queries for dark mode.** Clients that support `@media (prefers-color-scheme: dark)` (Apple Mail, Outlook Mac/iOS) allow you to override styles for dark mode.
* **Apply `!important` sparingly.** Adding `!important` to dark mode overrides helps prevent inboxes from stacking inversion rules on top of your custom styles.
* **Signal theme support.** Include the following meta tags in your HTML `<head>` to reduce auto-inversion:

```html theme={null}
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">
```

* **Avoid pure white and pure black.** Use off-whites and dark grays to reduce the impact of full-inversion clients.
* **Use transparent PNGs with care.** Dark logos on transparent backgrounds become invisible on dark backgrounds. Add a light outline or use a version with a built-in background.

<Note>
  For a step-by-step walkthrough of adding dark mode CSS using the Drag and Drop Editor, see [Dark mode styling with drag-and-drop](./design-emails-with-drag-and-drop#dark-mode-styling-with-drag-and-drop).
</Note>

### Recommended image sizes for email

<AccordionGroup>
  <Accordion title="Aspect ratios">
    * Header/Banner images: `3:1` or `4:1` (e.g., `600×200` or `600×150`)
    * Hero images: `16:9` or `2:1` (e.g., `600×338` or `600×300`)
    * Square images: `1:1` (e.g., `300×300`); good for product grids
    * Thumbnails: `1:1` or `4:3`
    * Max width: `600–700px` is standard (most email clients)
    * Design at `2x` for retina displays (e.g., `1200px` wide, displayed at `600px`)
  </Accordion>

  <Accordion title="File size">
    * Keep individual images under `100–200 KB`
    * Total email size (including images) under `1 MB`
    * Smaller images mean faster load times and better deliverability
  </Accordion>

  <Accordion title="File formats">
    * **JPG**: best for photos
    * **PNG**: best for graphics, logos, and images with transparency
    * **GIF**: for simple animations (keep file size small)
    * **WebP**: not widely supported in email yet; avoid
  </Accordion>

  <Accordion title="General tips">
    * Always include alt text for accessibility and for when images do not load
    * Use inline CSS for styling (many clients strip `<style>` tags)
    * Avoid background images (inconsistent client support)
    * Test across clients, as Gmail, Outlook, and Apple Mail all render differently
    * Outlook often ignores image dimensions, so set both `width` and `height` attributes in HTML
  </Accordion>
</AccordionGroup>

### Add alt text to images

Alt text improves accessibility and ensures information is conveyed even when images are blocked or fail to load. Most major email clients display and style alt text:

| Email Client | Blocks Images? | Shows Alt Text | Styles Alt Text |
| ------------ | -------------- | -------------- | --------------- |
| AOL          | Yes            | Yes            | Yes             |
| Gmail        | Yes            | Yes            | Yes             |
| Yahoo        | Yes            | Yes            | Yes             |
| Outlook      | Sometimes      | Yes            | Yes             |

### Use supported HTML only

Email clients **do not** support:

* JavaScript
* `<iframe>`
* HTML forms
* Embedded audio or video
* CSS positioning or layering tricks

Use links to external pages for interactive or multimedia content.

### Validate before sending

Before sending, check the following:

* All links work (broken links hurt deliverability and can trigger spam filters)
* Unsubscribe link functions correctly
* Test emails render in Gmail, Outlook, and Apple Mail
* Dark mode rendering is acceptable
* HTML uses semantic tags and proper indentation for accessibility and maintainability

<Check> If your email renders correctly in major clients and unsubscribe works, it is ready to send. </Check>

### Personalization

Use Liquid templating to insert subscriber-specific content like names, tags, or fallback values directly in your HTML. Example: `{{ first_name | default: "there" }}`

<Columns>
  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Available personalization variables and how to use them.
  </Card>

  <Card title="Using Liquid syntax" icon="code" href="./using-liquid-syntax">
    Conditionals, filters, loops, and advanced Liquid patterns.
  </Card>
</Columns>

***

## FAQ

### Can I reuse my existing email templates?

Yes. Forward them to OneSignal via [Email Template forwarding](./email-template-forwarding), upload them with the [Create Template API](/reference/create-template), or copy-paste the HTML directly into the editor.

### Can I use custom fonts?

Yes, but support varies. Declare custom fonts with `@font-face` and always include system font fallbacks. Outlook on Windows ignores web fonts entirely and falls back to system defaults.

### Why does my email look different in dark mode?

Each email client applies dark mode differently. Some fully invert colors, some partially invert, and Gmail web does not apply dark mode at all. See the [client behavior table](#how-email-clients-handle-dark-mode) above for specifics. Define explicit light and dark mode styles to control rendering.

### What HTML and CSS features are not supported in email?

JavaScript, `<iframe>`, HTML forms, embedded audio/video, and CSS positioning are not supported. Use inline CSS for all styling, as most clients strip `<style>` blocks and external stylesheets.

### Can I add a "view in browser" link to my emails?

OneSignal does not generate a hosted web version of your email. To provide a "view in browser" experience, host the email content on your own website and add a standard HTML link pointing to that hosted page.

### What is the maximum email size?

Keep total email size (HTML + images) under 1 MB. Emails over 102 KB of HTML are clipped by Gmail, which hides content below the fold behind a "View entire message" link.

## Related pages

<Columns>
  <Card title="Design emails with drag-and-drop" icon="paintbrush" href="./design-emails-with-drag-and-drop">
    Visual email builder for designing emails without writing full HTML.
  </Card>

  <Card title="Email overview" icon="envelope" href="./email-messaging">
    End-to-end guide to sending email with OneSignal.
  </Card>

  <Card title="Email templates" icon="copy" href="./templates">
    Save and reuse email designs across campaigns.
  </Card>

  <Card title="Unsubscribe links" icon="link-slash" href="./unsubscribe-links-email-subscriptions">
    Add default or custom unsubscribe links for compliance.
  </Card>

  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Personalize emails with tags, Liquid syntax, and dynamic content.
  </Card>

  <Card title="Email template forwarding" icon="envelope-open-text" href="./email-template-forwarding">
    Import existing HTML email templates into OneSignal.
  </Card>
</Columns>


# Design in-app messages with drag-and-drop
Source: https://documentation.onesignal.com/docs/en/design-your-in-app-message

Use OneSignal's visual composer to build high-converting in-app messages with blocks, layouts, carousels, and personalization.

OneSignal's drag-and-drop editor lets you build in-app messages using modular blocks—no coding required. If you prefer markup, see [Design In-App Messages with HTML](./design-your-in-app-message-with-html).

<Frame>
  <img alt="Creating an in-app message using the drag-and-drop editor" />
</Frame>

## Prerequisites

* You installed and initialized the OneSignal SDK in your app.
* You're on recommended SDKs for the latest editor features:
  * iOS 5.1.5+
  * Android 5.1.9+
* If not uploading images to OneSignal, then your images should be hosted on a fast, publicly accessible URL (CDN recommended) and sized appropriately for mobile screens.

<Warning>
  Make sure to use the latest version of the OneSignal SDK in your app.
  Older versions may still display the message, but with fallback styling (for example, default margins or default overlays). Use **Preview** and **device testing** to confirm behavior on your minimum supported SDK versions.
</Warning>

***

## Start from a pre-built template

Pre-built templates help you launch quickly with layouts that are designed for conversion (including permission prompts). Choose a template, then update the copy, colors, and actions to match your brand.

<Note>
  **Device testing:** Pre-built designs have been tested on Pixel 6+, iPhone (iOS 14+), Huawei Nova 9, Huawei P50 Foldable, and iPad (10th gen+). These templates are optimized for portrait orientation and may not display as intended in landscape mode.
</Note>

***

## Choose a message layout

Message layout controls how the in-app appears on screen.

| Message type | Best for                                       | How it behaves                                         |
| ------------ | ---------------------------------------------- | ------------------------------------------------------ |
| **Top**      | Slim announcements and confirmations           | Slides down from the top                               |
| **Center**   | Most marketing and product prompts             | Expands from the center and partially fills the screen |
| **Bottom**   | Snackbars, consent prompts                     | Slides up from the bottom                              |
| **Full**     | Onboarding flows, multi-step offers, carousels | Expands to fill the screen (with optional margins)     |

<Frame>
  <img alt="Top, Center, Bottom, and Full in-app message layouts" />
</Frame>

### Build multi-screen flows with carousels

Carousels let you create multi-screen in-app experiences like onboarding, feature tours, or multi-step offers.

1. Select the **Full** message type.
2. Click **Create Carousel**.
3. Add up to 10 cards (screens).
4. Customize each card with any combination of blocks.

<Frame>
  <img alt="Example carousel with multiple in-app message cards" />
</Frame>

### Orientation support

In-app messages support portrait and landscape, but layouts (especially templates) may need adjustments to look great in both.

<Frame>
  <img alt="In-app message displayed in portrait and landscape orientations" />
</Frame>

<Note> If you expect frequent landscape usage (tablets, games, video apps), test your message in landscape before publishing. Wide layouts often need smaller text sizes, tighter spacing, or fewer stacked blocks. </Note>

***

## Use blocks and spacing for clean layouts

Everything is placed on the Background block (your canvas). Use:

* **Padding** on the **Background** for space between your content and the message edges.
* **Margin** on individual blocks for space between elements (headline → image → button).

**Quick rules for consistent layouts**

1. Use **Padding** to control distance from the message edges.
2. Use **Margin** to separate blocks vertically.
3. Avoid stacking large padding and margins on the same side.
4. Prefer centered, flow-based layouts over tight/edge-aligned designs.
5. Always use **Preview** on multiple device sizes before publishing.

<Frame>
  <img alt="Background padding and block margin controls in the in-app editor" />
</Frame>

***

## Block reference

Use these blocks to build your message. Each block supports styling and (in most cases) an optional click action.

### Text block

Use for headlines, descriptions, disclaimers, or personalized copy.

**What you can customize**

* **Responsive sizing**: Width/height in percentages.
* **Fonts**: Google Fonts.
* **Formatting**: Bold, italic, underline.
* **Color**: Hex or RGBA (supports transparency).
* **Alignment**: Left, center, right.
* **Size**: Adjustable font size.

**Advanced**

* **Margins**: Space around the block.

**Tips**

* Localize with language-based segments or [using Liquid syntax](./using-liquid-syntax).
* Personalize with [Tags](./message-personalization).

<Frame>
  <img alt="Text block configuration options in the editor" />
</Frame>

### Image block

Use images to reinforce the offer, show a feature, or add branding.

**Supported formats and limits**

* `.jpg`, `.png`, `.gif`
* Maximum file size: 5MB

**Tips & recommendations**

* Use common aspect ratios like `16:9`, `4:3`, or `3:2`.
* You can dynamically swap links and image URLs using server-hosted paths. See [Dynamic URLs](./links#dynamic-urls).
  * Example: `https://example.com/images/{{ tag_key }}.png`

**What you can customize**

* **Image URL**: Hosted is recommended for performance.
* **Click action**: Optional (link, deep link, tag, outcome, prompt).

**Advanced**

* **Dismiss on click**
* **Margins**: Space around the block.

<Frame>
  <img alt="Image block configuration options in the editor" />
</Frame>

<Warning> If an image URL is slow, blocked, or returns an error, your message can render with broken or empty media. Host images on a reliable CDN and verify they load quickly on mobile networks. </Warning>

### Button block

Use buttons for primary actions like navigation, collecting feedback, or permission prompts.

**What you can customize**

* Button text and font styling
* Background color, size, and corner radius
* Optional icon/image
* Click action (tagging, outcomes, prompts, deep links)

**Advanced**

* Dismiss on click
* Margins
* Borders and shadows

**Tips**

* Personalize button text or destinations using tags.
* You can make an image-only button by setting the background opacity to 0.
* Use subtle shadows (low opacity, higher blur) to lift the primary CTA.

<Frame>
  <img alt="Button block configuration options in the editor" />
</Frame>

### Close button block

The close button controls whether users can dismiss the message using an "X" icon.

**What you can customize**

* Enable/disable visibility
* Custom icon (`.jpg`, `.png`, `.svg`, `.gif`)
* Recommended size: `10x10px`
* Optional click action

**Advanced**

* Margins

<Warning>
  If you disable the close button, make sure users still have a clear way to exit (for example, a **dismiss action** on a button or background, or a close timer if your experience uses one). Otherwise, you risk trapping users in the message.
</Warning>

<Frame>
  <img alt="Close button configuration options in the editor" />
</Frame>

### Background block

The background is the canvas that holds your layout.

**What you can customize**

* Background color (RGBA supported)
* Background image (`.jpg`, `.png`, `.gif`)
* Optional click action

**Advanced**

* Padding (default `24px`)
* Dismiss on click

<Frame>
  <img alt="Background block controls for color, image, padding, and actions" />
</Frame>

***

## Personalization & localization

You can personalize in-app messages using [Tags](./add-user-data-tags) including inside text, button labels, and URLs.

For localization, see [Multi-langauge messages](./multi-language-messaging#send-messages-in-different-languages).

<Check>
  A good personalization test is to send the message to a small internal segment with known tag values and confirm:

  * The text and images render with the expected substitutions
  * Links resolve correctly
  * Buttons fire the expected click outcomes/tags
</Check>

***

## FAQ

### Can I remove the gray overlay or drop shadow from top/bottom banner in-apps?

Yes—update your SDKs and add the config below.

**iOS 5.1.5+**

```xml iOS Info.plist theme={null}
<key>OneSignal_in_app_message_hide_drop_shadow</key>
<true/>
<key>OneSignal_in_app_message_hide_gray_overlay</key>
<true/>
```

**Android 5.1.9+**

```xml Android Manifest.xml theme={null}
<meta-data android:name="com.onesignal.inAppMessageHideGrayOverlay" android:value="true"/>
<meta-data android:name="com.onesignal.inAppMessageHideDropShadow" android:value="true"/>
```

***

## Next steps

* Learn about [In-App Click Actions](./iam-click-actions) to customize what happens when users click elements in your message.
* Try different [In-App Message Triggers](./iam-triggers) to control when messages appear.
* Need more customization? Try [Design In-App Messages with HTML](./design-your-in-app-message-with-html).

***


# Design in-app messages with HTML
Source: https://documentation.onesignal.com/docs/en/design-your-in-app-message-with-html

Design and customize in‑app messages using OneSignal's HTML Editor for maximum flexibility, responsiveness, and branding.

## Overview

OneSignal offers two in-app message editors:

* [Drag & Drop](./design-your-in-app-message) GUI for non‑technical creators
* HTML Editor for developers who want pixel‑perfect control over layout, behavior, and responsiveness.

<Frame>
  <img />
</Frame>

**What you can do with the HTML Editor:**

* **Layouts:** Build complex responsive layouts (e.g., side‑by‑side CTAs).
* **Forms:** Collect inputs inline (email, feedback, survey).
* **Fonts & Brand:** Use custom web fonts and CSS variables.
* **JS Actions:** Track clicks, tag users, send outcomes, and more.

### Requirements

* **iOS:** 3.9.0+
* **Android:** 4.6.3+
  * If your app uses an older SDK, in-app messages will render in a Center Modal layout instead.

***

## Create & preview an HTML In‑App

Go to **Messages > New In-App** to create, edit, test, pause, duplicate, or delete your in-app messages.

<Columns>
  <Card title="HTML Templates" href="./in-app-html-templates">
    Start quickly with pre-built templates.
  </Card>

  <Card title="In-app JavaScript Library" href="./in-app-message-api">
    Use our JavaScript library to track interactions and trigger in-app behaviors.
  </Card>
</Columns>

Enter your HTML code on the left-hand side and preview it live. Use **Send Test In-App** to test responsiveness and design.

<Frame>
  <img />
</Frame>

### Add trackable labels

Add `data-onesignal-unique-label` on interactive elements so clicks are tracked and actionable.

```html theme={null}
<button class="tag-user" data-onesignal-unique-label="my-tag-user-button">Tag User</button>
```

### Bind click actions with JavaScript

```js theme={null}
// Tag the user when they click a button
document.querySelector(".tag-user").onclick = (e) => {
  OneSignalIamApi.tagUser(e, { fiz: "baz" });
};
```

<Note>
  Learn more in the [In-App JS Library documentation](./in-app-message-api).
</Note>

### Asset support

Assets load at render time from the URLs you provide.

```html theme={null}
<img src="https://media.onesignal.com/iam/default_image_20200320.png" alt="Promo" />
```

### Personalization

Dynamically insert user data values [using Liquid syntax](./using-liquid-syntax):

```html theme={null}
<div>Hi there {{ name | default: 'you' }}!</div>
```

**Supported contexts:**

* Text inside elements like `div`, `p`, `li`
* Inside `<style>` blocks
* In attributes `href`, `src`, `action`, and `data`

**Not supported in:**

* Inside `<script>` tags
* Across complex nested content where parsing becomes ambiguous e.g.:

```html theme={null}
<div>
  Hi {{name}}
  <span>Here's your coupon!</span>
</div>
```

***

## Accessibility & responsive design

Use CSS media queries and platform typography to adapt to device size and OS text settings.

```css theme={null}
@media only screen and (max-width: 620px) {
  .btn-primary { width: 100% !important; }
}
/* Respect dynamic text sizes on iOS */
:root { font: -apple-system-body; }
```

### Safe areas (notches, home bars)

Modern devices have safe areas (like notches or home bars). Use `safe-area-inset-*` variables to pad your layout:

```css theme={null}
body {
  padding-top: var(--safe-area-inset-top);
  padding-right: var(--safe-area-inset-right);
  padding-bottom: calc(var(--safe-area-inset-bottom) + 20px);
  padding-left: var(--safe-area-inset-left);
  margin: 0;
}
```

## Dark mode styling

Mobile devices and apps often apply automatic dark mode adjustments based on the user’s system theme. This can cause in-app messages (IAMs) to appear differently than intended. For example, text may invert color or background images may look dimmed. To ensure your IAM looks consistent across light and dark themes, define explicit styles for both modes.

### Best practices

* **Set explicit colors.** Always define text, background, and button colors directly in your HTML or CSS. Avoid transparent or default colors that rely on system behavior.

* **Use `prefers-color-scheme` media queries.** You can include dark mode overrides with:

  ```css theme={null}
  @media (prefers-color-scheme: dark) {
    body {
      background-color: #000000;
      color: #ffffff;
    }
    .button {
      background-color: #ffffff;
      color: #000000;
    }
  }
  ```

* Optimize images for both modes. Use transparent PNGs or SVGs where possible. For background images, test readability in both light and dark themes.

* Avoid double inversions. Some Android and iOS versions may auto-adjust colors. Using explicit dark mode styles helps prevent your custom dark theme from being inverted again by the OS.

* Preview in both modes. Use your app’s dark and light themes to verify that text, buttons, and backgrounds have enough contrast and remain accessible.

<Note> Test across platforms. Android WebView, iOS WKWebView, and web builds handle dark mode differently. Always preview your in-app message in both themes before publishing. </Note>

***

### Embedding videos

You can embed videos (e.g., YouTube, Vimeo) directly in your in-app messages using `<iframe>`.\
This is useful for demos, promos, or onboarding flows.

Most browsers only allow **autoplay if the video starts muted**, so always include `&mute=1` in the embed URL.

<Note>
  Autoplaying video can impact performance. Keep videos short, and avoid multiple autoplay embeds in a single in-app.
</Note>

#### Example: Autoplay YouTube embed

The snippet below shows how to center a YouTube video in the middle of the in-app with a fixed size (560×315):

```html theme={null}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <style>
      body {
        margin: 0;
        height: 100vh;
        display: flex;
        justify-content: center; /* center horizontally */
        align-items: center;     /* center vertically */
        background: #f0f0f0;     /* optional background */
      }
      .video-box {
        width: 560px;  /* fixed width */
        height: 315px; /* fixed height (16:9 ratio) */
        box-shadow: 0 4px 12px rgba(0,0,0,0.2);
        border-radius: 8px;
        overflow: hidden;
        background: #000;
      }
      .video-box iframe {
        width: 100%;
        height: 100%;
        border: none;
      }
    </style>
  </head>
  <body>
    <div class="video-box">
      <iframe src="https://www.youtube.com/embed/bH60T1PZg1c?autoplay=1&mute=1"
        allow="autoplay; encrypted-media"
        allowfullscreen>
      </iframe>
    </div>
  </body>
</html>
```

#### Understanding autoplay behavior

* The embed URL (/embed/VIDEO\_ID) is required for autoplay — normal watch?v= links won’t work.

* Adding ?autoplay=1\&mute=1 ensures the video plays automatically and complies with browser autoplay rules.

* The allow="autoplay; encrypted-media" attribute grants permission for autoplay.

* The .video-box uses a fixed 560×315px size (YouTube’s default 16:9) so the video appears contained instead of stretching full screen.

* The body is set as a flex container with justify-content: center and align-items: center to position the video box in the exact middle of the screen.

***

## Performance tips

* Prefer inline critical CSS; defer heavy scripts.
* Optimize images (dimensioned `<img>` with `object-fit`), use modern formats when possible.
* Keep HTML payloads concise; avoid large base64 blobs.
* Use system fonts or host performant web fonts with `font-display: swap`.
* Reduce file sizes and use proper resolution:
  * [Apple image guidelines](https://developer.apple.com/design/human-interface-guidelines/ios/icons-and-images/image-size-and-resolution/)
  * [Android image overview](https://developer.android.com/guide/topics/graphics)
  * OneSignal has no affiliation with [imagekit.io](https://imagekit.io/), though it’s a helpful tool for optimization.

### Test across devices

Send test messages frequently to confirm behavior and layout across device types. See [Find & set Test Users](./test-users).

***

## FAQ

### Can I remove the gray background or drop shadow from banner-style in-apps?

Yes. For top/bottom banners, update your SDKs and set:

**iOS 5.1.5+**

```xml theme={null}
<key>OneSignal_in_app_message_hide_drop_shadow</key>
<true/>
<key>OneSignal_in_app_message_hide_gray_overlay</key>
<true/>
```

**Android 5.1.9+**

```xml theme={null}
<meta-data android:name="com.onesignal.inAppMessageHideGrayOverlay" android:value="true"/>
<meta-data android:name="com.onesignal.inAppMessageHideDropShadow" android:value="true"/>
```

### Can I reuse in-app templates from other providers?

Yes. Paste your HTML into the editor and replace analytics/actions with the OneSignal In‑App JS methods.

### I don’t have templates. How do I start?

Use the provided starter template or [browse available templates](./in-app-html-templates). Some HTML/CSS experience is recommended.

### What SDK version is required?

* **iOS:** 3.9.0+
* **Android:** 4.6.3+

Older SDKs will fall back to Center Modal rendering.

### Do in-app messages work offline?

No. Messages require an active internet connection to fetch and render content.

***


# Disabled apps & organizations
Source: https://documentation.onesignal.com/docs/en/disabled-apps

Reasons OneSignal disables Apps and Organizations, what disablement blocks, and how App Admins and Organization Admins can restore access.

## Overview

Read this guide if your OneSignal App or Organization has been disabled, or if you want to understand what triggers disablement, what it affects, and how to restore access. OneSignal disables Apps and Organizations to protect platform stability, enforce billing and compliance requirements, and prevent unintended messaging behavior.

This guide explains:

* How Apps and Organizations become disabled
* What happens when an App or Organization is disabled
* How to re-enable an App or Organization

Before continuing, review:

* [Apps, Organizations, & Accounts](./apps-organizations) to understand how ownership and billing are structured.
* [Team members](./manage-team-members) to understand how to manage team access.

<Note>
  An **App** holds user and messaging data for a single project, across multiple platforms (web, iOS, Android, email, etc.). An **Organization** is a container for managing multiple Apps, billing, and team permissions.
</Note>

***

## How Apps and Organizations become disabled

### App

An App may be disabled:

* Manually by an App or Organization Admin in the dashboard at **Settings > Manage App > Disable App**
* Automatically due to:
  * [API rate limits](/reference/rate-limits)
  * Violations of the [Acceptable Use Policy](https://onesignal.com/aup)

### Email channel

An App's Email channel can be disabled separately from the App itself due to violations of the [Acceptable Use Policy](https://onesignal.com/aup), most commonly high bounce and spam complaint rates. When this happens, the App cannot send emails until the channel is re-enabled. Follow the [Email reputation best practices](./email-reputation-best-practices) guide to resolve the underlying issues, then reach out to `support@onesignal.com` with details on which steps you followed including screenshots to verify the issue has been resolved.

### Organization

An Organization may be disabled due to:

* Overdue invoices on a paid plan. See [Billing FAQ](./billing-faq) for more details.
* Violations of the [Acceptable Use Policy](https://onesignal.com/aup)

When an Organization is disabled, all Apps within the Organization are disabled, and billing or compliance issues must be resolved first.

***

## What happens when an App or Organization is disabled

When an **App** is disabled:

**Blocked:**

* New messages cannot be sent.
* In-app messages are paused.
* Scheduled messages are cancelled.
* Journeys are stopped and archived.
* Data cannot be deleted or exported.

**Still active:**

* Existing data remains intact within normal retention periods.
* The SDK continues to collect new and update existing user data.
* Billing continues if the App is in an enabled Organization on a paid plan.
* The App can still be deleted or moved to another Organization.

<Warning>
  You will continue to be billed for the App if it is within an enabled Organization on a paid plan. To stop billing:

  * Delete the App, or
  * Move it to a Free Organization

  Contact `support@onesignal.com` for assistance.
</Warning>

When an **Organization** is disabled:

* All Apps in the Organization are disabled.
* Messaging, exports, and deletions are blocked.
* Apps cannot be removed or transferred.

<Note>
  Organization-level disablement is more restrictive than App-level disablement.
</Note>

***

## How to re-enable an App or Organization

You must be an **App or Organization Admin** to re-enable an App and an **Organization Admin** to re-enable an Organization. See [Team members](./manage-team-members) for details.

### Re-enable an App

* If you manually disabled the App, go back to **Settings > Manage App > Disable App** and click **Re-enable**.
* If the App was disabled due to rate limits, follow the in-dashboard prompt to re-enable it.
* If the App was disabled for any other reason, contact `support@onesignal.com` for assistance.

### Re-enable an Email channel

* Contact `support@onesignal.com`.
* Share which steps you followed from the [Email reputation best practices](./email-reputation-best-practices) guide to address the bounce and complaint rates.

### Re-enable an Organization

* If the Organization was disabled due to an overdue invoice, pay the invoice and the Organization will be re-enabled.
* If the Organization was disabled for any other reason, contact `support@onesignal.com` for assistance.

***

## FAQ

### Does disabling an App stop billing?

No. Disabled Apps still count toward monthly active user (MAU) billing.

### Does disabling an App stop new users?

No. You must remove the OneSignal SDK to prevent new subscriptions.

### Can I re-enable a disabled App?

Yes, in some cases. App or Organization Admins can re-enable manually disabled Apps and Organizations from the dashboard. Apps or Organizations disabled for policy violations require contacting support.

### How do I know why my App or Organization was disabled?

Check dashboard warnings, recent send activity, and billing status. If you are unsure, contact support with your App ID.

### How do I contact support about a disabled App?

Email `support@onesignal.com` with your App ID (found in **Settings > [Keys & IDs](./keys-and-ids)**). Include a description of the issue and whether the disablement was manual or automatic.

***

<Columns>
  <Card title="Apps, Organizations, & Accounts" icon="building" href="./apps-organizations">
    Understand how ownership, billing, and access are structured across apps and organizations.
  </Card>

  <Card title="Manage team members" icon="users" href="./manage-team-members">
    Invite users, assign roles, and manage access at the app or organization level.
  </Card>

  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    Find your App ID, REST API key, and other credentials.
  </Card>

  <Card title="Billing FAQ" icon="credit-card" href="./billing-faq">
    Manage plans, billing, and subscriptions across organizations.
  </Card>
</Columns>


# Duplicated notifications
Source: https://documentation.onesignal.com/docs/en/duplicated-notifications

Troubleshoot duplicate push notifications caused by SDK conflicts, server-side retries, multi-app environments, and platform-specific bugs.

Duplicate notifications occur when the same device receives the same message content more than once. This guide covers the most common causes and how to resolve them.

If the same user sees the notification on multiple devices (phone, tablet, desktop), that is expected behavior based on your targeting configuration (segments, external IDs, etc.). For duplicate in-app messages, see the [in-app message troubleshooting](./in-app-message-troubleshooting#duplicated-in-app-messages) guide instead.

<Info>
  Apple acknowledged a bug in iOS 17 that caused duplicates. This was fixed in iOS 17.3. [Read more](https://forums.developer.apple.com/forums/thread/747044).
</Info>

## Start here

Pick the section that best matches your situation:

* Your server retries failed API calls or your backend pipeline may double-send → [Same message sent multiple times](#same-message-sent-multiple-times)
* Your app uses Firebase or another push SDK alongside OneSignal → [Third-party notification handlers](#third-party-notification-handlers)
* Your Android app customizes notifications in code (service extension or foreground listener) → [Android notification handlers](#android-notification-handlers)
* Your iOS app implements its own `UNUserNotificationCenterDelegate` → [iOS foreground handler](#ios-foreground-handler)
* You only see duplicates on dev builds or with multiple installs → [Multiple app instances](#multiple-app-instances)

## Same message sent multiple times

The most common cause is sending the same notification payload more than once through the OneSignal API. Common reasons:

* Your server retries requests without checking if the first succeeded.
* Logic in your backend pipeline sends the same notification twice.
* You're migrating to OneSignal but still sending from a previous provider. Avoid sending from both systems at the same time.

<Card title="Idempotent API requests" icon="rotate" href="/reference/idempotent-notification-requests">
  Prevent duplicate messages by reusing idempotency keys on retries.
</Card>

## Third-party notification handlers

Duplicates can occur when other code in your app processes OneSignal's push payload and displays its own notification in addition to OneSignal's. This includes:

* Other remote push SDKs (for example, Firebase Cloud Messaging) that receive the same payload.
* Custom message handlers such as a `FirebaseMessagingService` on Android or a `UNUserNotificationCenterDelegate` on iOS that read the incoming payload and build a local notification from it.

OneSignal's SDK filters out OneSignal payloads automatically when it is the only handler. Third-party code does not know to filter them out unless you tell it to.

### Identifying OneSignal notifications

Every OneSignal notification includes a `custom` object with an `i` key containing the OneSignal notification UUID:

```json JSON theme={null}
{
  "custom": {
    "i": "the-notification-id"
  }
}
```

For the full payload reference, see [Custom OneSignal payload structure](./osnotification-payload#custom-onesignal-payload-structure).

### Filtering OneSignal notifications from third-party handlers

In any non-OneSignal handler, check for the `custom.i` key and return early when it is present. OneSignal then handles its own payloads while your other code continues to process its own.

<Tabs>
  <Tab title="Android">
    In a custom `FirebaseMessagingService` or other remote message handler:

    ```kotlin Kotlin theme={null}
    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        val customJson = remoteMessage.data["custom"]
        if (customJson != null) {
            try {
                val custom = JSONObject(customJson)
                if (custom.has("i")) {
                    // OneSignal notification — let the OneSignal SDK handle it
                    return
                }
            } catch (e: JSONException) {
                // Not a OneSignal payload, fall through
            }
        }

        // Handle your own notification here
    }
    ```
  </Tab>

  <Tab title="iOS">
    In your `UNUserNotificationCenterDelegate` or a custom notification handler:

    ```swift Swift theme={null}
    func userNotificationCenter(_ center: UNUserNotificationCenter,
                                willPresent notification: UNNotification,
                                withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        let userInfo = notification.request.content.userInfo

        if let custom = userInfo["custom"] as? [String: Any], custom["i"] != nil {
            // OneSignal notification — let the OneSignal SDK handle it
            completionHandler([])
            return
        }

        // Handle your own notification here
    }
    ```
  </Tab>
</Tabs>

<Tip>
  If you control the payload structure sent from your other provider, add a distinct marker key (for example, `my_app_notification: true`) and filter in both directions — only handle notifications containing your marker in your own code, and let OneSignal handle notifications containing the `custom.i` key.
</Tip>

## Android notification handlers

OneSignal exposes two Android callbacks that let you intercept and customize a notification before it displays:

* `onNotificationReceived` in a [notification service extension](./service-extensions) — runs for every push, including when the app is in the background.
* `onWillDisplay` in a [foreground lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) — runs only when the app is in the foreground.

Duplicates happen when these callbacks display the notification in addition to OneSignal's automatic display.

### The `preventDefault()` and `display()` rule

OneSignal displays each notification automatically unless you suppress it with `event.preventDefault()`. Two common mistakes cause duplicates:

* Calling `event.getNotification().display()` without first calling `event.preventDefault()` — shows the notification twice.
* Posting a separate notification with [`NotificationManagerCompat.notify()`](https://developer.android.com/reference/androidx/core/app/NotificationManagerCompat) while OneSignal also displays the original.

Only one display path should be active — either OneSignal's `display()` or your own `NotificationManagerCompat.notify()`, never both.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  override fun onNotificationReceived(event: INotificationReceivedEvent) {
      event.preventDefault()

      val notification = event.notification
      notification.setExtender { builder ->
          builder.setColor(0xFF0000FF.toInt())
      }
      notification.display()
  }
  ```

  ```java Java theme={null}
  @Override
  public void onNotificationReceived(INotificationReceivedEvent event) {
      event.preventDefault();

      IDisplayableMutableNotification notification = event.getNotification();
      notification.setExtender(builder ->
          builder.setColor(0xFF0000FF)
      );
      notification.display();
  }
  ```
</CodeGroup>

The same rule applies inside `onWillDisplay` in a foreground lifecycle listener:

```kotlin Kotlin theme={null}
OneSignal.Notifications.addForegroundLifecycleListener(object : INotificationLifecycleListener {
    override fun onWillDisplay(event: INotificationWillDisplayEvent) {
        event.preventDefault()

        // Render your own UI or call event.notification.display() to show the OneSignal notification
    }
})
```

<Warning>
  If you call `preventDefault()` but never call `display()`, the notification is silently dropped and the user does not see it. Every code path should either call `display()` once or intentionally suppress the notification.
</Warning>

<Warning>
  If you use both a notification service extension and a foreground lifecycle listener, make sure only one handler displays the notification for a given app state. Calling `display()` from both produces duplicates.
</Warning>

### Async work inside callbacks

When you do background work (network calls, database lookups) before displaying, call `preventDefault()` synchronously in the callback and call `display()` only after the async work completes. Returning from the callback without `preventDefault()` lets OneSignal display the notification, and a later `display()` call produces a duplicate.

## iOS foreground handler

OneSignal sets itself as the `UNUserNotificationCenterDelegate` during SDK initialization. If your app also implements foreground notification handling, the notification can display twice — once from OneSignal and once from your code.

Common patterns that cause duplicates:

* Implementing your own `UNUserNotificationCenterDelegate` without forwarding calls to OneSignal, then calling `completionHandler([.banner, .sound])` and showing a custom in-app alert from the same method.
* Scheduling a local notification (`UNUserNotificationCenter.current().add(...)`) in response to an incoming push that OneSignal is also displaying.

To control foreground display without causing duplicates, use OneSignal's [foreground lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) and call `event.preventDefault()` when you want to render the notification yourself:

```swift Swift theme={null}
OneSignal.Notifications.addForegroundLifecycleListener(self)

func onWillDisplay(event: OSNotificationWillDisplayEvent) {
    event.preventDefault()

    // Render your own UI or call event.notification.display() to show the OneSignal notification
}
```

## Multiple app instances

<Tabs>
  <Tab title="Android">
    Duplicates can happen when you have both production and development versions of your app installed. Each app has a unique package name and receives its own push token.

    Long-press the notification to confirm which app instance sent it.
  </Tab>

  <Tab title="iOS">
    If two device records in OneSignal share the same push token, the device may receive two notifications. This can happen when the same token is imported or registered multiple times. OneSignal includes checks to prevent this, but edge cases may bypass them.
  </Tab>

  <Tab title="Web">
    Web push duplicates are caused by subscribing to multiple origins using the same OneSignal App ID. An [origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) is the combination of scheme, host, and port that the browser uses to scope push subscriptions.

    For example, a user who subscribes to `https://example.com` and `https://sub.example.com` counts as two subscriptions, and a send using the same App ID reaches both.

    To fix:

    1. [Reset browser data and push permissions](./troubleshooting-web-push) per origin.
    2. If many users are affected, create a new OneSignal App and use the new App ID in your site's init code.
    3. Have users revisit the site and resubscribe.

    Subscribing on multiple browsers or browser profiles also leads to multiple notifications.
  </Tab>
</Tabs>

## Diagnostic tips

To debug duplicates faster, collect and send the following to OneSignal support:

* OneSignal Subscription ID of the device that received the duplicates
* OneSignal Message ID or a link to the message in the dashboard
* List of other libraries or plugins in your app
* [Debug log reproducing the issue](./capturing-a-debug-log)
* Detailed reproduction steps

## FAQ

### What happens if I have two notification SDKs in my app?

Both SDKs may independently process and display the same notification. OneSignal filters its own notifications automatically, but other SDKs do not. Filter OneSignal payloads out of your other SDK's handlers by checking for the `custom.i` key. See [Third-party notification handlers](#third-party-notification-handlers) for code examples.

### How do I send push from a previous provider and OneSignal at the same time?

You can transition gradually, but avoid sending the same message from both providers.

* **Android**: Remove old SDK notification handling code when integrating OneSignal and releasing the app. As users update, they stop receiving push from the old provider.
* **iOS**: You can continue sending from the old provider temporarily while users update. Once fully transitioned, send from OneSignal only to avoid duplicates.

### How do I prevent multiple notifications for rapidly-changing updates?

Use a [`collapse_id`](/reference/push-notification#body-parameters) in the [Create notification](/reference/push-notification) API to replace previous notifications instead of stacking them. When multiple notifications share the same `collapse_id`, each new one replaces the previous notification in the tray. This is useful for stock price updates, live scores, delivery ETAs, and similar frequent updates.

## Related pages

<Columns>
  <Card title="Mobile SDK troubleshooting" icon="mobile" href="./mobile-troubleshooting">
    Resolve common issues with push notification delivery on iOS and Android.
  </Card>

  <Card title="Web push troubleshooting" icon="browser" href="./troubleshooting-web-push">
    Debug web push subscription, service worker, and delivery issues.
  </Card>

  <Card title="In-app message troubleshooting" icon="message" href="./in-app-message-troubleshooting">
    Fix issues with in-app message display, triggers, and duplicates.
  </Card>

  <Card title="Mobile service extensions" icon="gear" href="./service-extensions">
    Intercept and customize push notifications before display on iOS and Android.
  </Card>

  <Card title="Notifications not shown (web)" icon="bell-slash" href="./notifications-not-shown-web-push">
    Troubleshoot web push notifications that are sent but not displayed.
  </Card>
</Columns>


# Dynamic Content with CSV
Source: https://documentation.onesignal.com/docs/en/dynamic-content

Personalize push, email, and SMS messages at scale using Dynamic Content with CSV uploads and Liquid syntax in OneSignal.

OneSignal provides several ways to [personalize message content](./message-personalization) at scale. This guide focuses on using the Dynamic Content with CSV upload feature in the OneSignal dashboard for push, email, and SMS.

**Key benefits:**

* **Use a CSV to personalize at scale** – One message, custom experiences for everyone
* **Dynamic personalization** – Content adapts to user properties (language, region, campaign ID)
* **HTML injection (email)** – Include HTML markup in CSV cells to dynamically build rich email content
* **Team collaboration** – Non-technical users edit content in CSV files
* **Cross-channel compatibility** – Reuse CSV logic across channels
* **Multi-language support** – Automatic language switching per user

**Common use cases:**

* Multi-language onboarding or marketing
* Region-specific promotions
* Event announcements per location
* Campaign-based personalization

***

## Dynamic Content with CSV setup steps

**Quick reference:**

1. Create a CSV file with your content variations.
2. Create a [template](./templates)
3. Map the CSV data to the message using the `dynamic_content` property in liquid syntax.
4. Select the **Dynamic Content** or **Personalization** button.
5. Upload the CSV file and send the message.

### CSV requirements & setup

* **File size:** Under 200 KB
* **Column headers:**
  * Reserve the first column header for the tag key or leave blank to reference sections
  * Alphanumeric characters and underscores only
  * Use underscores (`_`) instead of spaces
* **Encoding:** UTF-8

Start with a blank CSV or use a provided template. Templates are provided when selecting the **Dynamic Content** or **Personalization** button in the message and template editors.

<Frame>
  <img alt="Dynamic Content button in the OneSignal message editor" />
</Frame>

Templates are available for:

* **Multi-language** – Localize content by language
* **Content personalization** – Customize content by Tags

<Frame>
  <img alt="CSV template options showing multi-language and content personalization templates" />
</Frame>

#### Example CSVs

This guide will use the following example CSV data.

<Tabs>
  <Tab title="Multi-language Template Example">
    * Map the column headers to your [supported language codes](./multi-language-messaging#supported-languages).
    * Add your translations to each row for each language code.
    * If you have multiple sections (like in an email), designate the first column as the section name.

    This example includes:

    * 3 languages: English, Spanish, and French.
    * 2 sections: "section\_1" and "section\_2".

    <Frame>
      <img alt="Multi-language CSV with language codes as column headers and translated content in rows" />
    </Frame>
  </Tab>

  <Tab title="Content Personalization Template Example">
    * Map the first column header to the tag key and underlying rows to the values you want to reference. See [Tags](./add-user-data-tags) for more information on adding tags to users.
    * Map the remaining column headers to the sections or components you want to personalize.

    In this example:

    * The tag key is `campaign_id` with possible values of `A` and `B`.
    * There are 3 components: "title", "message", and "url".

    <Frame>
      <img alt="Content personalization CSV using campaign_id tag with title, message, and url columns" />
    </Frame>

    <Warning>
      **Important:** Remove spaces and non-alphanumeric characters from CSV headers
      or use hash notation in Liquid.
    </Warning>

    <Frame>
      <img alt="Detailed CSV example showing Liquid syntax references for tag-based personalization" />
    </Frame>
  </Tab>
</Tabs>

### Map CSV data to message content

Using [Liquid syntax](./using-liquid-syntax), reference the CSV data in your message using the `dynamic_content` property:

```liquid theme={null}
<!-- Option 1: access by component first -->
{{dynamic_content.file_name.message_component[user_property]}}

<!-- Option 2: access by user property first -->
{{dynamic_content.file_name[user_property].message_component}}
```

**Parameters:**

* `dynamic_content` – The property name used to reference the CSV data
* `file_name` – CSV file name (without `.csv` extension)
* `message_component` – The specific message component you want to personalize. This is the static text in the CSV column header or first row.
* `user_property` – The [user property](./message-personalization#properties) you want to reference.

**Fallback content:**

Always use hard-coded string `default` fallbacks to ensure messages render if the CSV lookup or Dynamic Content fails.

```liquid Liquid syntax for the fallback theme={null}
{{ dynamic_content.my_template.header[user.language] | default: "Welcome to our latest update" }}
```

This means if the CSV lookup or Dynamic Content fails, the message will render the fallback text `"Welcome to our latest update"`.

This ensures:

* Dynamic Content is used when available
* A hard-coded message appears if Dynamic Content fails
* Users never receive blank content

<Tabs>
  <Tab title="Multi-language Message Example">
    ```csv translations.csv theme={null}
    ,en,es,fr
    section_1,Hello,Hola,Bonjour
    section_2,Thanks for shopping with us...,Gracias por comprar con nosotros...,Merci pour votre achat avec nous...
    ```

    * The `file_name` is `translations.csv`.
    * The `message_component` is in the rows of the first column `section_1` and `section_2`.
    * The `user_property` is the column header matching language code. We can reference this on the user with the `user.language` [property](./message-personalization#properties).

    ```liquid Basic Liquid syntax for the multi-language message theme={null}
    {{dynamic_content.translations.section_1[user.language]}}
    {{dynamic_content.translations.section_2[user.language]}}
    ```

    ```liquid (Recommended) Liquid syntax with default fallback for the multi-language message theme={null}
    {% assign supported_langs = "en,es,fr,de" | split: "," %}
    {% assign lang = user.language | default: "en" %}

    {% unless supported_langs contains lang %}
      {% assign lang = "en" %}
    {% endunless %}

    {{ dynamic_content.translations.section_1[lang] | default: "Hello" }}
    {{ dynamic_content.translations.section_2[lang] | default: "Thanks for shopping with us..." }}
    ```

    <Frame>
      <img alt="OneSignal email editor with Liquid syntax for multi-language Dynamic Content" />
    </Frame>
  </Tab>

  <Tab title="Content Personalization Message Example">
    ```csv content_personalization_template.csv theme={null}
    campaign_id,title,message,url
    campaign_123,Flash deal for you,Tap to claim,https://example.com/flash
    campaign_456,Weekend picks are here,See what's trending,https://example.com/weekend
    default,Our latest offers,See what's new,https://example.com
    ```

    * The `file_name` is `content_personalization_template.csv`.
    * The `user_property` maps to the tag key: `campaign_id`.
    * The `message_component` is the column header mapped to the section of the message you want to personalize (title, message, or url).

    ```liquid Liquid syntax for the content personalization message theme={null}
    {{ dynamic_content.content_personalization_template[campaign_id].title }}
    {{ dynamic_content.content_personalization_template[campaign_id].message }}
    {{ dynamic_content.content_personalization_template[campaign_id].url }}
    ```

    ```liquid (Recommended) Liquid syntax with default fallback for the content personalization message theme={null}
    {% assign cid = campaign_id | default: "default" %}

    {% unless dynamic_content.content_personalization_template[cid] %}
      {% assign cid = "default" %}
    {% endunless %}

    {{ dynamic_content.content_personalization_template[cid].title | default: "Our latest offers" }}
    {{ dynamic_content.content_personalization_template[cid].message | default: "See what's new" }}
    {{ dynamic_content.content_personalization_template[cid].url | default: "https://example.com" }}
    ```

    <Frame>
      <img alt="Dynamic Content personalization Liquid example" />
    </Frame>
  </Tab>
</Tabs>

<Check>
  Use Liquid with `default` fallback to update subject lines, preheaders, button
  labels, and URLs.
</Check>

### Using HTML in CSV cells (email only)

You can include HTML markup directly in CSV cells to inject rich content into emails. This is useful for swapping entire sections of an email — such as banners, CTAs, or styled blocks — based on user properties.

```csv promo_banners.csv theme={null}
campaign_id,banner_html
spring_sale,<div style="background:#4CAF50;padding:16px;text-align:center;"><a href="https://example.com/spring" style="color:#fff;font-size:18px;">Shop the Spring Sale</a></div>
default,<div style="background:#333;padding:16px;text-align:center;"><a href="https://example.com" style="color:#fff;font-size:18px;">See What's New</a></div>
```

Reference the HTML cell in your email template:

```liquid theme={null}
{{ dynamic_content.promo_banners[campaign_id].banner_html | default: "<p>Check out our latest offers</p>" }}
```

The HTML renders directly in the email body, so you can use any inline styles and markup that email clients support.

<Warning>
  HTML from CSV cells is only supported in email. Push and SMS channels render content as plain text and do not interpret HTML markup.
</Warning>

***

## Reference

### Updating templates

Re-upload CSVs via the dashboard or use the [Update Template API](/reference/update-template) `dynamic_content` property.

### Special characters in keys

**Hash notation** (for non-alphanumeric keys):

```liquid theme={null}
{{ dynamic_content.file_name["!the_row!"]["&the_column&"] }}
```

**Dot notation** (for standard keys):

```liquid theme={null}
{{ dynamic_content.file_name.the_row.the_column }}
```

***

## FAQ

### How can I test Dynamic Content with CSV?

Use email to test multiple variations of the message.

* Use `+` addressing in emails to test multiple variations: `username+test@example.com`.
* Set tags following the multi-language and content personalization examples above.
* See [Import](./import) for more on uploading multiple users and tags.

### When should I use Dynamic Content with CSV vs. other personalization options?

Use **Dynamic Content with CSV** when sending messages from the dashboard and you have user data in a CSV file. For other ways to add dynamic content to messages, see [Message Personalization](./message-personalization) or [Multi-language Messaging](./multi-language-messaging).

***

## Related pages

<Columns>
  <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
    Overview of all personalization options available in OneSignal.
  </Card>

  <Card title="Using Liquid syntax" icon="code" href="./using-liquid-syntax">
    Complete Liquid syntax reference for OneSignal messages.
  </Card>

  <Card title="Import" icon="file-import" href="./import">
    Upload user data and segments to OneSignal.
  </Card>

  <Card title="Templates" icon="clone" href="./templates">
    Create and manage reusable message templates.
  </Card>
</Columns>


# Email address validation
Source: https://documentation.onesignal.com/docs/en/email-address-validation

Validate email addresses during CSV import and in bulk to reduce bounces and protect your sender reputation.

Email address validation detects common problems in email addresses before they reach your audience. It flags typos, invalid domains, role-based addresses, and disposable email services that could increase your bounce rate or hurt your sender reputation.

It runs automatically during CSV import and is also available as a bulk validation tool for your existing audience.

<Note>
  Email address validation checks addresses against OneSignal's validation criteria. It is not a live bounce verification check and does not guarantee deliverability.
</Note>

## Validation checks

Email address validation evaluates each address against the following checks:

| Check                  | What it detects                                                                         |
| ---------------------- | --------------------------------------------------------------------------------------- |
| **Syntax validation**  | Malformed addresses missing required components (e.g. missing `@`, invalid TLD)         |
| **Typo detection**     | Common domain misspellings like `gnail.com` or `gmail.con`                              |
| **MX record check**    | Domains with no valid mail exchange record; email sent here cannot be delivered         |
| **Role-based address** | Addresses like `sales@`, `info@`, `admin@` that are unlikely to belong to an individual |
| **Disposable email**   | Domains associated with temporary or throwaway email services                           |

<Note>
  **Free plans** include syntax validation and typo detection. **Paid plans** include all of the above plus MX record checks, role-based address detection, and disposable email filtering.
</Note>

If an address fails a check, email address validation returns a human-readable error explaining the specific problem. If an address fails multiple checks, all failure reasons are returned together so you can address everything at once.

***

## Validate addresses during CSV import

When importing a CSV, you can configure email address validation settings on the **Review** step before confirming the import.

<Steps>
  <Step title="Start a CSV import">
    Go to **Audience > Import** and upload your file. Complete the **Upload** and **Map Fields** steps. If any invalid email addresses are detected, a warning will appear on the **Map Fields** step.

    <Frame>
      <img alt="Import CSV Map Fields step showing an invalid emails detected warning" />
    </Frame>
  </Step>

  <Step title="Configure validation settings on the Review step">
    On the **Review** step, expand **Email address validation settings**. The following options are available:

    <Frame>
      <img alt="Import CSV Review step with Email address validation settings expanded" />
    </Frame>

    * **Validate email domains (MX records)**: confirm the domain can receive email
    * **Exclude disposable email addresses**: prevent temporary or one-time addresses that may reduce engagement
    * **Exclude role-based email addresses**: prevent shared addresses like `info@` or `support@` that often have lower engagement

    All three are enabled by default. Uncheck any you don't want applied to this import.

    <Note>
      If you need to import invalid email addresses (for example, to update suppression or subscription status), check **Allow invalid email addresses**. This bypasses validation and accepts any string as an email address.
    </Note>
  </Step>

  <Step title="Confirm and import">
    Click **Confirm and Import**. When the import is complete, you'll receive an email summarizing the results:

    * Subscriptions added
    * Subscriptions modified
    * Rows not imported, with a link to download the rejected rows
  </Step>
</Steps>

#### Result

Valid addresses are added to your audience. You receive an email when the import is complete. Addresses that failed validation are excluded and available to download from the link in the results email.

***

## Validate your existing audience in bulk

Use bulk validation to check email addresses already in your OneSignal audience. You receive results by email as a CSV export.

<Steps>
  <Step title="Open the Validate Email Addresses tool">
    Go to **Audience > Subscriptions** (or **Audience > Users**), click **Update/Import Users**, then select **Validate Email Addresses**.

    <Frame>
      <img alt="Update/Import Users dropdown with Validate Email Addresses option highlighted" />
    </Frame>
  </Step>

  <Step title="Start validation">
    In the modal, click **Start validation**. Email address validation runs against all email addresses for your app.

    <Frame>
      <img alt="Validate Email Addresses modal showing Start validation button" />
    </Frame>
  </Step>

  <Step title="Receive your results by email">
    When validation is complete, you'll receive an email from OneSignal with a **Download CSV Export** link. The link is active for 72 hours. The email summarizes how many addresses failed, broken down by:

    <Frame>
      <img alt="OneSignal results email showing validation summary and Download CSV Export button" />
    </Frame>

    * Typos
    * Role-based addresses
    * Disposable domains
    * Invalid MX records
  </Step>

  <Step title="Review and re-import">
    Download the CSV and review the flagged addresses. To clean up your audience, create a new CSV with the corrected or actioned addresses and re-import it using one of the following column formats:

    | Goal                             | Required columns      | Value                 |
    | -------------------------------- | --------------------- | --------------------- |
    | Re-subscribe corrected addresses | `email`, `subscribed` | `subscribed` = `yes`  |
    | Unsubscribe flagged addresses    | `email`, `subscribed` | `subscribed` = `no`   |
    | Suppress flagged addresses       | `email`, `suppressed` | `suppressed` = `true` |
  </Step>
</Steps>

#### Result

You receive an email with a CSV export of flagged addresses and a summary of validation results broken down by error type.

<Frame>
  <img alt="CSV export showing email, reason, suggested_email, created_at, last_opened, and last_clicked columns" />
</Frame>

***

## Validation error reference

The following errors may appear in validation results:

| Error                        | What it means                                                                                                                              | What to do                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| **Invalid input**            | The address is malformed and does not meet basic syntax requirements (e.g. missing `@`, invalid TLD).                                      | Correct or remove the address.                                                           |
| **Typo in email address**    | A likely misspelling was detected in the domain. A suggested correction appears in the adjacent column.                                    | Apply the suggested fix or remove the address.                                           |
| **MX record not found**      | The domain has no valid mail exchange record. Email cannot be delivered to this address.                                                   | Remove or suppress the address.                                                          |
| **Role-based email address** | The local part (before `@`) matches a known role-based pattern like `sales@` or `support@`. These are unlikely to belong to an individual. | Review whether the address is appropriate for your use case, then suppress or remove it. |
| **Disposable email address** | The domain is associated with a temporary or throwaway email service.                                                                      | Suppress or remove the address.                                                          |

***

## API error responses

Email address validation also applies to addresses submitted through the API. The sections below describe the error responses you may encounter.

<Note>
  API validation only checks that the email address is correctly formatted. It does not check for typos, MX records, role-based addresses, or disposable domains. Those checks are only available during CSV import and bulk validation.
</Note>

### Send email: Create Message

When you send to one or more invalid addresses via the [Create Message endpoint](/reference/create-message), invalid addresses are excluded from delivery and returned under `invalid_email_tokens`.

```json theme={null}
{
  "id": "",
  "errors": {
    "invalid_email_tokens": ["invalid@email"]
  }
}
```

### Add a user or subscription: User Model API

When you create a user or subscription with an invalid email via the [Create User](/reference/create-user) or [Create Subscription](/reference/create-subscription) endpoint:

```json theme={null}
{
  "errors": [
    {
      "title": "Invalid `token` format for device type email"
    }
  ]
}
```

### Add a device: Legacy Players API

When you add or edit a player record with an invalid email via the [legacy Players API](/reference/add-a-device):

```json theme={null}
{
  "success": false,
  "errors": ["[\"Identifier invalid format.\"]"]
}
```

<Warning>
  The Legacy Players API is deprecated. Migrate to the [User Model API](/reference/create-user) to receive more descriptive validation errors and access current features.
</Warning>


# BCC emails
Source: https://documentation.onesignal.com/docs/en/email-bcc

Send a hidden copy of an outgoing email to additional recipients for archiving, compliance, or third-party integrations.

Add BCC (blind carbon copy) recipients to a OneSignal email so the message is also delivered to one or more hidden addresses. BCC recipients receive the same content as the primary recipient and are not visible to anyone else on the send.

Common use cases:

* Archive customer-facing email to a shared inbox or compliance system.
* Forward sends to third-party services like Trustpilot Automatic Feedback Service (AFS).
* Keep internal stakeholders copied on transactional or high-value sends.

<Warning>
  Do not BCC password resets, magic links, two-factor codes, or any email containing sensitive data. The BCC recipient sees the full personalized message body. Treat BCC as a content disclosure and pick recipients deliberately.
</Warning>

***

## Prerequisites

* Complete [Email setup](./email-setup) and verify your sending domain.
* Confirm your billing plan accommodates additional volume. For every email sent, an additional email is sent to each BCC address. See [Billing and analytics](#billing-and-analytics).

***

## How BCC works in OneSignal

* BCC recipients are set per message at send time. There is no account-level default BCC.
* BCC sends count toward your billable email volume.
* Each BCC address adds one send per recipient to your email volume: OneSignal sends one email to your recipient and one email to each BCC address.
* BCC sends are excluded from engagement metrics (open rate, click rate, conversions) and included in your total send count so billing remains accurate.
* BCC addresses are validated for syntax only (the same check OneSignal applies to the **From** address). Deliverability, suppression status, and domain ownership are not verified.

<Info>
  Because BCC addresses are not validated for deliverability, a typo or bounced address fails silently with no retry and no notification. Send a test message to each BCC address before relying on it for compliance workflows.
</Info>

***

## Send a BCC email from the dashboard

1. In your OneSignal dashboard, go to **Messages > New Message > Email**.

2. Compose your email. Set the audience, subject, and content as usual.

3. In the **Sender** section, locate the **BCC** field.

4. Enter one or more email addresses, separated by commas:

   ```
   archive@yourdomain.com, compliance@yourdomain.com
   ```

5. Click **Review and Send** to deliver immediately, or **Save** to keep the message as a draft.

**Expected outcome:** Each BCC address receives a copy of the email at the same time as the primary recipient. The primary recipient cannot see the BCC list, and BCC recipients cannot see one another.

<Check>
  After sending, open **Delivery > Sent Messages** and select the message to confirm the BCC recipients appear on the message detail page.
</Check>

***

## Use BCC with a template

BCC addresses are configured directly on an email template and apply to every send that uses it.

1. Go to **Messages > Email > Templates** and open or create a template.
2. In the **Sender** section, locate the **BCC** field.
3. Enter up to 5 addresses, separated by commas.
4. Save the template.

***

## Use BCC in a Journey

When you select a template in a Journey's **Send Email** step, the BCC addresses from that template appear in the **Sender Settings** section of the step. They are read-only from here. To update them, select **Edit** next to the template name to modify the template directly.

<Note>
  Changes to a template's BCC addresses apply to all future sends using that template, including active Journeys.
</Note>

***

## Send a BCC email via the API

Pass an `email_bcc` array on the [Create message](/reference/create-message) endpoint. Each entry must be a syntactically valid email address.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.onesignal.com/notifications' \
    -H 'Authorization: Key YOUR_REST_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "app_id": "YOUR_APP_ID",
      "include_aliases": { "external_id": ["user-123"] },
      "target_channel": "email",
      "email_subject": "Your receipt",
      "email_body": "<p>Thanks for your purchase.</p>",
      "email_bcc": ["archive@yourdomain.com", "compliance@yourdomain.com"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onesignal.com/notifications', {
    method: 'POST',
    headers: {
      Authorization: `Key ${process.env.ONESIGNAL_REST_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      app_id: process.env.ONESIGNAL_APP_ID,
      include_aliases: { external_id: ['user-123'] },
      target_channel: 'email',
      email_subject: 'Your receipt',
      email_body: '<p>Thanks for your purchase.</p>',
      email_bcc: ['archive@yourdomain.com', 'compliance@yourdomain.com'],
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Send failed: ${error.errors?.join(', ')}`);
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.onesignal.com/notifications",
      headers={
          "Authorization": f"Key {os.environ['ONESIGNAL_REST_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "app_id": os.environ["ONESIGNAL_APP_ID"],
          "include_aliases": {"external_id": ["user-123"]},
          "target_channel": "email",
          "email_subject": "Your receipt",
          "email_body": "<p>Thanks for your purchase.</p>",
          "email_bcc": ["archive@yourdomain.com", "compliance@yourdomain.com"],
      },
  )
  response.raise_for_status()
  ```
</CodeGroup>

### Request fields

<ParamField type="string[]">
  An array of email addresses to receive a hidden copy of the message. Each address must pass basic syntax validation (the same check OneSignal applies to the **From** address). Deliverability, suppression status, and domain ownership are not verified. Invalid addresses fail silently and are not retried.
</ParamField>

### Errors

If any entry in `email_bcc` fails syntax validation, the API returns `400 Bad Request` with an `Invalid BCC address` error and the message is not sent. Fix or remove the offending entry and retry.

***

## Billing and analytics

| Metric                                 | Behavior                                                                                        |
| -------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Total email sends                      | Includes BCC recipients. For every email sent, an additional email is sent to each BCC address. |
| Open rate, click rate, conversions     | Excludes BCC recipients.                                                                        |
| Delivery, bounce, and complaint events | Excludes BCC recipients.                                                                        |
| Suppression list                       | Not enforced for BCC addresses. A suppressed address still receives the BCC copy.               |

Plan for the volume increase before enabling BCC at scale. Each BCC address adds one additional email per recipient to your billable volume.

<Note>
  For high-volume archive use cases, such as mirroring every send to a compliance store, evaluate whether [Event Streams](./event-streams) meets your requirements. Event Streams capture send and engagement data without adding to your email volume.
</Note>

***

## Best practices

* **Send a test before going live.** Add the BCC address to a one-off message and confirm receipt in the destination inbox before adding it to production sends.
* **Use a dedicated inbox with sufficient capacity.** Route BCC traffic to a purpose-built inbox like `archive@mail.yourdomain.com`, not a shared or personal account. Free-tier and shared mailboxes fill up quickly at scale: a 1 GB inbox can reach capacity after as few as 60,000 emails depending on message size. When the BCC inbox is full, all remaining BCC deliveries fail silently with no retry.
* **Keep the list short.** Each BCC recipient adds billable volume. A single archive address is usually sufficient for compliance.
* **Exclude transactional and security email.** Password resets, magic links, OTPs, and 2FA codes should never include a BCC.
* **Match BCC scope to the use case.** For Trustpilot AFS, only BCC the Trustpilot address on transactional sends that should generate review invitations, not on every marketing email.

***

## Common failure points

<AccordionGroup>
  <Accordion title="BCC address never receives the email">
    OneSignal does not retry BCC delivery failures. If a BCC address is misspelled, mailbox-full, or rejected by the receiving server, the message is dropped silently. Send a manual test to each address before relying on it.
  </Accordion>

  <Accordion title="Total sends rose but engagement metrics dropped">
    BCC sends count toward your total email volume but are excluded from open and click rates. If your total sends rose without a matching rise in engagement, the new volume is likely BCC traffic. Compare engagement against the primary recipient count, not the total send count.
  </Accordion>

  <Accordion title="API returns 'Invalid BCC address'">
    Each entry in the `email_bcc` array must be a bare, syntactically valid email address. Remove extra whitespace, stray punctuation, and display-name formatting like `Name <email@domain.com>`.
  </Accordion>

  <Accordion title="BCC inbox fills up mid-send">
    When sending to a large audience, a small or shared BCC inbox can reach capacity before the send completes. Once the inbox is full, remaining BCC deliveries fail silently with no retry or alert. Primary recipients are not affected. Use a dedicated inbox with adequate storage, or configure auto-archiving or auto-delete rules to keep the mailbox clear.
  </Accordion>

  <Accordion title="A suppressed address keeps receiving BCC copies">
    Suppression rules apply only to the primary audience. BCC bypasses the suppression list. Remove the address from your BCC list manually if it should no longer receive copies.
  </Accordion>
</AccordionGroup>

***

## FAQ

### Can I set a default BCC address for every email?

No. BCC must be set per message in the dashboard or per request in the API. There is no account- or app-level default.

### Are BCC recipients shown to the primary recipient?

No. BCC stands for "blind carbon copy." Each BCC recipient sees only their own address, and BCC recipients cannot see one another.

### Do BCC addresses respect my suppression list?

No. The suppression list applies to your primary audience. Do not add a suppressed address to BCC for compliance; the message will still be delivered.

### Are BCC sends included in analytics?

BCC sends count toward your total email volume so billing reflects the true volume. They are excluded from engagement metrics like open and click rates because BCC inboxes are typically archives, not engaged readers.

### What happens if a BCC address bounces?

The BCC delivery is dropped. OneSignal does not retry, does not surface a bounce event for the BCC recipient, and does not affect the primary recipient's delivery. Test BCC addresses before relying on them.

***

## Related pages

<Card title="Email overview" icon="envelope" href="./email-messaging">
  Full guide to sending, scheduling, and tracking email.
</Card>

<Card title="Create message API" icon="code" href="/reference/create-message">
  Reference for the email send endpoint and all available parameters.
</Card>

<Card title="Suppressions" icon="shield" href="./suppressions">
  Manage blocked and suppressed email addresses.
</Card>

<Card title="Event Streams" icon="bolt" href="./event-streams">
  Stream email events to your data warehouse for compliance archiving without adding billable sends.
</Card>


# Email deliverability
Source: https://documentation.onesignal.com/docs/en/email-deliverability

Improve inbox placement by managing sender reputation, reducing bounces and spam complaints, and following email hygiene best practices.

Email deliverability is the ability of your messages to reach recipients' inboxes instead of being blocked, sent to spam, or lost in transit. Deliverability depends on your sender reputation, email content, [domain alignment](./email-dns-configuration) (DKIM and SPF matching your From: domain), and recipient engagement. Internet service providers (ISPs) and mailbox providers (Gmail, Outlook, etc.) assess every incoming email to filter out unwanted or harmful messages.

<Frame>
  <iframe title="YouTube video player" />
</Frame>

<Warning>
  **Sending from a new domain, or planning to send 2,000+ emails per day?** Warm up your sending domain first. Sending large volumes from a cold domain triggers spam filters and damages your sender reputation, even with a clean list and proper authentication. Follow [Email warm-up](./email-warm-up) to ramp gradually using OneSignal's Auto Warm Up.
</Warning>

## Reputation

Your **email sending reputation**, assigned by inbox providers (Gmail, Outlook, Yahoo, Apple), is a key driver of deliverability. It determines how much email providers accept from you, whether your messages get blocked, and where they land. See [Inbox placement](#inbox-placement) for the difference between inbox, promotions, and spam.

Your reputation functions like a credit score: it goes up or down based on the performance of your past emails.

<Frame>
  <img alt="OneSignal Email Reputation dashboard showing bounce and spam complaint rates" />
</Frame>

### What helps reputation

* Proper [email authentication](./email-dns-configuration) (SPF, DKIM, DMARC)
* High engagement (e.g., [opens](#opened), [clicks](#clicked), replies)
* Clean, verified lists
* Consistent email sending patterns

### What hurts reputation

* High [spam complaint](#spam-complained) rates. See [Monitor spam reports](./email-reputation-best-practices#monitor-spam-reports-and-complaints).
* High [bounce](#bounced) rates. See [Avoid invalid emails](./email-reputation-best-practices#avoid-invalid-emails).
* Sending to [spam traps](#spam-traps). See [Set up a clear opt-in process](./email-reputation-best-practices#set-up-a-clear-opt-in-process).

<Warning>
  A bounce rate over **5%** or a complaint rate over **0.08%** may result in mail blocking by providers and violates the [Acceptable Use Policy & Code of Conduct](https://onesignal.com/aup). See [Google's Sender Guidelines](https://support.google.com/a/answer/14229414?hl=en) for more details.
</Warning>

If you're using OneSignal Email, view your stats at **Settings > Email > Reputation**. For third-party services (e.g., SendGrid, Mailchimp, Mailgun), use their dashboards to monitor complaints and bounces.

### How reputation metrics are calculated

* **Bounce rate** = permanent bounces ÷ total sent
* **Reported spam rate** (feedback loop providers only) = spam complaints received via feedback loop ÷ total sent

Complaint data depends on provider feedback availability. See [How spam rate is calculated](#how-spam-rate-is-calculated) for the Gmail caveat and feedback-loop details.

<Card title="Email reputation best practices" icon="shield-check" href="./email-reputation-best-practices">
  Actionable steps to build and maintain a healthy sending reputation: opt-in, monitoring, frequency, warm-up, and list hygiene.
</Card>

## Gmail and Yahoo bulk sender requirements

Gmail and Yahoo classify any domain sending **5,000 or more messages per day specifically to Gmail or Yahoo addresses** as a **bulk sender**. The classification is permanent and applies even if your daily volume later drops below 5,000.

Bulk senders must meet stricter requirements or face throttling and spam folder placement.

| Requirement                                              | Applies to   |
| -------------------------------------------------------- | ------------ |
| SPF authentication                                       | All senders  |
| DKIM authentication                                      | All senders  |
| DMARC published and aligned with SPF or DKIM             | Bulk senders |
| One-click unsubscribe in marketing email                 | Bulk senders |
| Spam complaint rate below **0.3%** (ideally below 0.08%) | All senders  |
| Valid forward and reverse DNS records (PTR / FCrDNS)     | All senders  |
| TLS-encrypted transmission                               | All senders  |
| RFC 5322 message formatting                              | All senders  |

OneSignal handles forward/reverse DNS, TLS, and message formatting for you. You're responsible for [SPF, DKIM, and DMARC](./email-dns-configuration), keeping your complaint rate low, and including a working unsubscribe link.

<Card title="Google and Yahoo email updates" icon="envelope-circle-check" href="./new-google-and-yahoo-email-updates">
  OneSignal-specific setup steps to meet the Gmail and Yahoo bulk sender requirements.
</Card>

## Key deliverability concepts

These terms appear in your email reports and reputation dashboard. Understanding them helps you diagnose and fix deliverability issues.

### Unsubscribed

Recipients who opt out via the unsubscribe link in your emails. These recipients are suppressed automatically to ensure compliance and protect your reputation.

Honor unsubscribe requests promptly. It's required by regulations like CAN-SPAM and protects your sender reputation.

<Columns>
  <Card title="Email unsubscribe links and headers" icon="link-slash" href="./unsubscribe-links-email-subscriptions">
    Manage unsubscribe links, List-Unsubscribe headers, suppression rules, and resubscription workflows.
  </Card>

  <Card title="Create a custom unsubscribe page" icon="paintbrush" href="./create-custom-unsubscribe-page">
    Replace the default unsubscribe link with a branded, multi-language preferences page.
  </Card>
</Columns>

### Bounced

Emails that fail to deliver due to invalid addresses (usually they do not exist or are spelled incorrectly). Bounce data is stored in your [suppression list](#suppression-list) and is also visible in [Event Streams](./event-streams).

### Failed

Emails that could not be delivered after retry attempts. Failed sends are not added to your suppression list, and the email may be retried on future sends.

Failures appear in [Email Message Reports > Audience Activity](./email-message-reports#audience-activity) and [Event Streams](./event-streams).

#### Common failure reasons

<AccordionGroup>
  <Accordion title="Too old">
    The email could not be delivered within the 8-hour retry window. This typically happens when the recipient's mail server issues repeated temporary 451 deferrals and never accepts the message before the retry window closes.

    Common causes:

    * Recipient-side email security gateways like Barracuda, Mimecast, and Proofpoint configured to defer or block mail from senders not on their allowlist
    * Recipient ISP applying greylisting or rate limiting
    * Recipient mailbox temporarily unavailable

    The fix is usually on the recipient side. If you see a pattern of "Too old" failures to a specific organization, the recipient's IT admin needs to allowlist your sending domain in their email security gateway.

    See [Too old failures](./email-troubleshooting#too-old-failures) for diagnostic steps.
  </Accordion>

  <Accordion title="Mailbox full">
    The recipient's mailbox has exceeded its storage quota and cannot accept new messages. There is no sender-side fix. The recipient must clear space in their inbox.
  </Accordion>

  <Accordion title="DNS or domain issues">
    The recipient domain does not exist, has no valid MX records, or failed DNS resolution. This often indicates typos in your recipient list, such as `gmial.com` instead of `gmail.com`. Clean these addresses from your list to protect your sender reputation.
  </Accordion>

  <Accordion title="ISP policy block">
    The recipient's ISP rejected the message based on content filtering, sender reputation, or authentication issues. Review your [sender reputation](#reputation) and [email DNS configuration](./email-dns-configuration) if you see a pattern of policy blocks from a specific ISP.
  </Accordion>

  <Accordion title="Authentication failure">
    The recipient's server rejected the message because SPF, DKIM, or DMARC validation failed. See [Email DNS configuration](./email-dns-configuration) to verify your setup.
  </Accordion>
</AccordionGroup>

<Frame>
  <img alt="Gmail deferral message showing 'Too Old' error due to poor sender reputation" />
</Frame>

### Spam complained

When recipients mark your email as spam, it triggers a spam complaint (also known as a "spam report").

<Frame>
  <img alt="Yahoo mail interface showing the Report Spam button" />
</Frame>

Common reasons for complaints:

* Irrelevant content
* Excessive frequency
* Recipients who did not opt in

<Note>
  Minimize complaint rates by analyzing feedback, adjusting content, and providing easy opt-out options. Follow the [email reputation best practices](./email-reputation-best-practices) to keep complaints low.
</Note>

Spam complaint events are available in [Event Streams](./event-streams).

#### How spam rate is calculated

A feedback loop is a reporting system where inbox providers notify senders when a recipient marks their email as spam. Not all providers offer this: Yahoo and Outlook do; Gmail does not.

The **Reported spam rate (feedback loop providers only)** metric reflects complaints received from mailbox providers that share per-recipient feedback loop data, such as Yahoo and Outlook. Gmail complaints are not included. This is an industry-wide limitation, not a OneSignal limitation.

<Card title="Google Postmaster Tools" icon="chart-line" href="./google-postmaster-tools">
  Connect Postmaster Tools to monitor Gmail-specific spam rates and domain reputation.
</Card>

### Suppression list

A blocklist within your OneSignal app that prevents sending to email addresses that have bounced or been marked as spam. Manage entries on the [Suppressions](./suppressions) page.

### Blocklists

External or ISP-managed lists of spammy or harmful IPs and domains. Being listed will cause deliverability problems. Use tools like [Spamhaus](https://www.spamhaus.org/) to check your domain or IP status.

### Spam traps

Spam traps are email addresses not used by real individuals, set up by ISPs or anti-spam organizations to identify spammers. Sending to spam traps indicates poor list hygiene or acquisition practices and can severely damage your sending reputation.

<Accordion title="Learn more about spam traps">
  <Frame>
    <iframe title="YouTube video player" />
  </Frame>

  Spam traps are email addresses not owned or operated by actual recipients. They are operated by inbox providers and third-party operators that report to, or are referenced by, inbox providers.

  Sending to spam traps can land your domain or IPs on a blocklist. Being on a blocklist means that some inboxes will reject your emails.

  Some common spam trap networks are [Spamhaus](https://www.spamhaus.org/), [Abusix](https://abusix.com/), and Microsoft's [SNDS](https://sendersupport.olc.protection.outlook.com/snds/).

  There are multiple types of spam traps, all of which can be prevented by following email best practices.

  **Pristine**

  Email addresses set up for the sole purpose of being monitored as spam traps. Found on public websites and purchased lists.

  **Recycled**

  Email addresses that used to belong to an actual recipient but have been repurposed as spam traps. Often abandoned inboxes or domains.

  **Typo**

  Email addresses set up with common typos, such as `gnail.com`, `tahoo.com`, `gmail.con`, `outlooj.com`, etc.

  **How to avoid spam traps**

  List cleaning tools will not remove spam traps. Focus on prevention and removal instead.

  **Prevent spam traps:** Implement a confirmed (double) opt-in process. When a new contact provides their email address, send an immediate confirmation email that verifies (a) the address is valid and (b) the address is actually operated by the recipient. Learn how to implement double opt-in using OneSignal's [Magic Link](./example-verification-magic-link-otp#setting-up-double-opt-in-with-onesignal).

  **Remove spam traps:** Remove unengaged email addresses. Spam traps don't bounce as invalid but don't engage with your emails either. If a recipient has received multiple emails without opening or clicking, remove them from your list. Use [Journeys](./journeys-overview) with [Wait Until branches](./journeys-actions#wait-until) to tag unengaged recipients, then exclude them from further sends.
</Accordion>

## Email address validation

Email address validation detects common problems in email addresses before they reach your audience. It flags typos, invalid domains, role-based addresses, and disposable email services that could increase your bounce rate or hurt your sender reputation.

<Card title="Email address validation" icon="circle-check" href="./email-address-validation">
  Validate email addresses during CSV import and in bulk to reduce bounces and protect your sender reputation.
</Card>

## Engagement metrics

### Opened

The number of times recipients open your email messages. Open rates indicate the effectiveness of your subject lines, targeting, and your From name and address. View open rates in [Email Message Reports](./email-message-reports).

<Note>
  Open rates are over-reported for Apple Mail recipients because Mail Privacy Protection prefetches images. Compare opens with clicks and [CTOR](./email-message-reports#open-rate) for a more reliable engagement signal.
</Note>

### Clicked

The number of times recipients click links within your email messages. Click-through rates measure the effectiveness of your email content and calls-to-action. Since recipients must open emails before clicking, clicks are a strong indicator of engagement. View click rates in [Email Message Reports](./email-message-reports).

## Inbox placement

Inbox placement refers to where your emails land within recipients' inboxes. Proper placement ensures your emails are seen in the right context and increases the likelihood of engagement.

<Frame>
  <img alt="Gmail inbox showing Primary, Social, and Promotions tabs" />
</Frame>

### Primary

The Primary tab is typically where important and personal communications are received. Achieving primary inbox placement indicates good sender reputation and email relevance.

### Promotions

The Promotions tab is a separate section within recipients' inboxes designated for promotional or marketing emails. Inbox providers use algorithms to categorize emails as promotions based on sender reputation and email content.

Landing in the Promotions tab is not an indicator of bad reputation and is not necessarily a bad outcome for marketing emails. If an email is inherently promotional, it may perform better in the context of the Promotions tab. Providers like Gmail actively draw recipient attention to their Promotions tab.

The Promotions tab has been found to reduce spam complaints and increase engagement, as it helps emails meet recipient expectations. When a recipient visits their Promotions tab, they are more receptive to deals and shopping.

To land more often in the Primary tab, avoid excessive promotional language, personalize content, and encourage recipients to move your emails to their Primary tab.

### Spam

Emails filtered by inbox providers into recipients' spam or junk folders. Emails land in spam due to suspicious content, triggered spam filters, or low sender reputation.

Landing in the spam folder usually indicates poor reputation. Check whether your complaint or bounce rate has been higher than acceptable. According to Google, senders should keep their spam rate below 0.1%.

Follow the [email reputation best practices](./email-reputation-best-practices) to lower bounce and complaint rates. If spam placement does not seem reputation-related, verify that your DMARC is properly aligned. [About My Email](https://aboutmy.email/) is a good testing tool to check for alignment.

## FAQ

### What is the difference between reputation and deliverability?

Reputation is the score inbox providers assign to your sending domain based on past email performance. Deliverability is the outcome: whether your emails reach the inbox, land in spam, or get blocked. A good reputation is the primary driver of good deliverability.

### What's the difference between a bounce and a failure?

A [bounce](#bounced) means the email address is permanently invalid (e.g., it doesn't exist). Bounced addresses are added to your [suppression list](./suppressions). A [failure](#failed) is a temporary delivery issue (e.g., full inbox, DKIM misconfiguration). Failures are not suppressed and the email may be retried.

### Why are my emails landing in Promotions instead of Primary?

Landing in [Promotions](#promotions) is not a sign of bad reputation. Gmail and other providers categorize emails based on content and past recipient behavior. To reach the Primary tab, reduce promotional language, personalize content, and encourage recipients to move your emails to Primary.

### What are spam traps and how do they affect me?

[Spam traps](#spam-traps) are email addresses set up by ISPs to catch senders with poor list hygiene. Sending to spam traps can land your domain on a [blocklist](#blocklists), causing inbox providers to reject your emails. Implement confirmed opt-in and remove unengaged recipients to avoid them. See [Set up a clear opt-in process](./email-reputation-best-practices#set-up-a-clear-opt-in-process).

### Why don't my Gmail spam complaints show up in OneSignal?

Gmail does not provide per-recipient spam complaint feedback to senders. This is an industry-wide limitation. The **Reported spam rate** metric only reflects complaints from feedback-loop providers like Yahoo and Outlook. To monitor Gmail-specific spam rates, connect [Google Postmaster Tools](./google-postmaster-tools).

### How do I improve my deliverability?

Follow the [email reputation best practices](./email-reputation-best-practices), which covers opt-in processes, monitoring spam reports, targeting engaged recipients, controlling send frequency, warming up your domain, and maintaining list hygiene. If you're sending from a new domain, start with [Email warm-up](./email-warm-up).

### Do I need to warm up before sending large volumes?

Yes, if you're using a new sending domain or plan to send 5,000+ emails per day to Gmail or Yahoo (the threshold at which both providers classify you as a [bulk sender](#gmail-and-yahoo-bulk-sender-requirements)). Sending large volumes from a cold domain triggers spam filters and damages your sender reputation, which is hard to recover. Follow [Email warm-up](./email-warm-up) to ramp gradually with OneSignal's Auto Warm Up feature.

## Related pages

<Columns>
  <Card title="Email reputation best practices" icon="shield-check" href="./email-reputation-best-practices">
    Actionable steps to build and maintain a healthy sending reputation.
  </Card>

  <Card title="Email warm-up" icon="envelope" href="./email-warm-up">
    Ramp volume on a new sending domain without hurting deliverability.
  </Card>

  <Card title="Email DNS configuration" icon="globe" href="./email-dns-configuration">
    Set up SPF, DKIM, and DMARC records for your sending domain.
  </Card>

  <Card title="Google Postmaster Tools" icon="chart-line" href="./google-postmaster-tools">
    Monitor Gmail-specific spam rates and domain reputation.
  </Card>

  <Card title="Suppressions" icon="ban" href="./suppressions">
    Manage your suppression list to prevent sending to invalid or unengaged addresses.
  </Card>

  <Card title="Email address validation" icon="circle-check" href="./email-address-validation">
    Validate addresses during import to reduce bounces.
  </Card>
</Columns>


# Email DNS configuration
Source: https://documentation.onesignal.com/docs/en/email-dns-configuration

Manually add DNS records (SPF, DKIM, DMARC, CNAME, MX) to authenticate your sending domain for OneSignal email delivery.

Configure DNS records provided by OneSignal to authenticate your sending domain. In most cases, DNS can be auto-configured from the OneSignal dashboard as described in the [Email setup](./email-setup) guide. Use this page when you need to add records manually.

## Requirements

To manually configure DNS records, you must:

* Own the sending domain.
* Have access to DNS settings via your provider.

If you don't own a domain, we recommend purchasing one via Cloudflare. This guide uses Cloudflare as an example, but most DNS providers work the same way.

<Accordion title="Registering your domain with Cloudflare" icon="circle-chevron-down">
  Create an account at [Cloudflare.com](https://www.cloudflare.com/).

  Go to **Domain Registration > Register Domains**.

  <Frame>
    <img alt="Cloudflare dashboard showing the Register Domains page" />
  </Frame>

  Search for an available name and purchase it.

  <Frame>
    <img alt="Cloudflare domain search results with purchase option" />
  </Frame>

  Once purchased, your domain will appear under **Domain Registration > Managed Domains**.

  <Frame>
    <img alt="Cloudflare managed domains list showing the active domain" />
  </Frame>
</Accordion>

***

## Add DNS records

Complete the [Email setup](./email-setup) steps until you're prompted to add DNS records, then return here or use the **Auto-Configure DNS** button.

From the OneSignal dashboard:

* ⚠️ means the current DNS record does not match
* ✅ means the current DNS record matches

Each DNS record needs to be added to your DNS provider. The exception is the MX record. You must have MX records configured, but they may point to a different mail server (e.g., Gmail).

<Frame>
  <img alt="OneSignal dashboard showing DNS records to copy into your provider" />
</Frame>

In your DNS provider's interface (e.g., Cloudflare), go to **DNS > Records** and add each record.

### TXT records

* **Type:** `TXT`
* **Name:** OneSignal "Hostname"
* **Content:** OneSignal "Value"
* **TTL:** Auto or lowest

<Warning>
  If you already have an SPF TXT record, do not create a second one. Append additional `include:` directives to the existing record:

  `v=spf1 include:spf.onesignal.email include:mailgun.org include:your-other-spf-records ~all`
</Warning>

<Frame>
  <img alt="Cloudflare interface for adding a TXT DNS record with hostname and value fields" />
</Frame>

#### SPF (Sender Policy Framework)

Verifies the sending IP is authorized to send emails on your domain's behalf.

#### DMARC

Adds policy enforcement for SPF and DKIM failures. **DMARC is required for any domain that sends 5,000 or more emails per day to Gmail or Yahoo** (the [bulk sender](./email-deliverability#gmail-and-yahoo-bulk-sender-requirements) threshold), and is strongly recommended for all senders. See [Google's Email Sender Guidelines](https://support.google.com/mail/answer/81126) and [Google and Yahoo email sender requirements](./new-google-and-yahoo-email-updates) for the OneSignal-specific setup.

<Warning>
  OneSignal uses the value `v=DMARC1; p=none;` for the DMARC record. If you already have a DMARC record, do not add a duplicate. Verify the existing record includes this policy or a stricter one (e.g., `p=quarantine` or `p=reject`).
</Warning>

### CNAME records

Used for open, click, and unsubscribe tracking.

* **Type:** `CNAME`
* **Name:** OneSignal "Hostname"
* **Target:** OneSignal "Value"
* **TTL:** Auto or lowest

<Note>
  If using Cloudflare, set **Proxy** to "DNS only" and **Flattening** to "Off" for CNAME records. Other DNS providers typically do not require these settings.
</Note>

<Frame>
  <img alt="Cloudflare interface for adding a CNAME record with hostname and target fields" />
</Frame>

#### DKIM (DomainKeys Identified Mail)

Verifies the message content was not altered and was sent by you. The public key is included in the CNAME DNS record provided by OneSignal.

### MX records

Receives email responses and bounces. Even if you're only sending, MX records help avoid domain verification errors.

<Warning>
  If you already use another email provider (e.g., Gmail), do not overwrite existing MX records.
</Warning>

* **Type:** `MX`
* **Name:** OneSignal "Hostname"
* **Mail server:** OneSignal "Value"
* **TTL:** Auto or lowest
* **Priority:** `10`

<Frame>
  <img alt="Cloudflare interface for adding an MX record with mail server and priority fields" />
</Frame>

***

## DNS verification & troubleshooting

After adding records:

1. Return to your OneSignal dashboard.
2. Click **Check Records** or the refresh button.

Verified records show ✅. All records should be verified except MX, which may show ⚠️ if it points to a different mail server (e.g., Google Workspace). This is expected and acceptable.

<Frame>
  <img alt="OneSignal dashboard showing DNS records with green checkmarks for verified status" />
</Frame>

<Warning>
  Verification typically takes a few minutes but can take up to 48 hours.
</Warning>

### Troubleshoot DNS propagation

1. Use [whatsmydns.net](https://www.whatsmydns.net/) to check propagation if any records are pending.
2. For records that show ⚠️, copy the hostname from the OneSignal dashboard into the search bar and set the DNS type.
3. Check the results: ✅ means the record is verified globally, ❌ means it has not propagated to that server yet.

If the value shown on whatsmydns.net differs from what OneSignal provides, check your DNS provider and update the record to match.

<Frame>
  <img alt="whatsmydns.net results showing global DNS propagation status with green and red indicators" />
</Frame>

#### Common errors & solutions

* **TXT SPF record isn't verified**
  * You likely have an existing SPF record. You should only have one SPF TXT record. Append additional `include:` directives to its value. See the [TXT records](#txt-records) section above.
* **DNS not fully propagated**
  * If [whatsmydns.net](https://www.whatsmydns.net/) shows a mix of ✅ and ❌, the records have not fully propagated. This can take up to 48 hours. Wait and check again, or contact your DNS provider.
* **DNS value not matching OneSignal**
  * If the values on [whatsmydns.net](https://www.whatsmydns.net/) don't match what OneSignal provides:
    * MX records pointing elsewhere (e.g., Google Mail) are expected. This is fine as long as they show ✅ on whatsmydns.net.
    * Verify the hostname is correct. `mail.yourdomain.com` is not the same as `yourdomain.com`.
    * Contact your DNS provider for help.

***

## FAQ

### How long does DNS verification take?

Verification typically completes within minutes, but DNS propagation can take up to 48 hours depending on your provider and TTL settings. Use [whatsmydns.net](https://www.whatsmydns.net/) to check progress.

### What if I already have SPF or DMARC records?

Do not create duplicate records. For SPF, append OneSignal's `include:spf.onesignal.email` to your existing SPF TXT record. For DMARC, verify your existing record includes `v=DMARC1; p=none;` or a stricter policy.

### Do I need MX records if I'm only sending emails?

MX records help avoid domain verification errors even for send-only configurations. If you already use a mail provider like Gmail or Google Workspace, keep your existing MX records. You do not need to overwrite them with OneSignal's values.

### My SPF record looks correct on external DNS checkers, but OneSignal still shows a warning. What should I check?

External DNS checkers confirm that a TXT record exists for your domain, but they do not verify that its value matches what OneSignal expects. A record can exist and still fail OneSignal's check if the value is wrong or incomplete.

To diagnose the mismatch:

1. In the OneSignal dashboard, find the SPF record showing a warning and note the exact **Hostname** and **Value** shown.
2. Open your DNS provider and locate the TXT record for that hostname.
3. Compare the record value character-for-character against what OneSignal shows.

If you send email exclusively through OneSignal with no other email providers, the minimal valid SPF value is:

`v=spf1 include:spf.onesignal.email ~all`

If you use other senders, append their `include:` directives to the same record rather than creating a second SPF record. See [What if I already have SPF or DMARC records?](#what-if-i-already-have-spf-or-dmarc-records) above.

***

<Check>
  Return to [Email setup](./email-setup) to complete configuration and begin sending emails.
</Check>

## Related pages

<Columns>
  <Card title="Email setup" icon="envelope" href="./email-setup">
    Complete email channel setup including provider selection and auto-DNS configuration.
  </Card>

  <Card title="Senders" icon="paper-plane" href="./senders">
    Manage sending domains, reply-to addresses, and sender identities.
  </Card>

  <Card title="Email warm-up" icon="temperature-arrow-up" href="./email-warm-up">
    Gradually increase email volume to build sender reputation and improve deliverability.
  </Card>

  <Card title="Email messaging" icon="envelopes-bulk" href="./email-messaging">
    Compose and send email campaigns with templates, personalization, and scheduling.
  </Card>
</Columns>


# Email message reports
Source: https://documentation.onesignal.com/docs/en/email-message-reports

Track email delivery, opens, clicks, bounces, suppressions, and spam reports in OneSignal email message reports.

Email message reports show delivery stats, open rate, click rate, and error diagnostics for each email. Reports update in real time as recipients interact with the message.

<Note>
  If the email is sent via a Journey or using Templates, see [Journey Analytics](./journeys-analytics) or [Template Analytics](./template-analytics) for additional details.
</Note>

<Frame>
  <img alt="Email message report showing delivery statistics and engagement metrics" />
</Frame>

## Delivery statistics

Audience Activity and data for messages sent via the API are retained for \~30 days. To retain historical performance, export data using the Dashboard or API. See [Exporting Data](./exporting-data).

### Delivered

Understand how many recipients received your message, and why others didn't.

| Metric               | Definition                                                                                                                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sent**             | The number of emails sent from OneSignal, including both those successfully sent to the email service provider and failures. This is a composite metric.                                                                              |
| **Audience**         | The number of Subscriptions in the targeted Segment(s).                                                                                                                                                                               |
| **Remaining**        | The number of Subscriptions in the target audience that haven't yet received the email (queued or in flight). Appears on the dashboard delivery report.                                                                               |
| **Delivered**        | The number of emails successfully delivered to the recipient's inbox server.                                                                                                                                                          |
| **Failed**           | The number of emails unable to be delivered to the inbox, excluding bounces. May include failures reported by the ESP or OneSignal delivery failures.                                                                                 |
| **Suppressed**       | The number of emails blocked due to prior bounces or spam reports to protect sender reputation. Only recorded for apps configured to use OneSignal email.                                                                             |
| **Bounced**          | The number of emails rejected due to invalid addresses, full inboxes, sender reputation, or DMARC issues. These addresses are added to a [Suppression List](/docs/en/suppressions), either managed by OneSignal or a third party ESP. |
| **Reported as Spam** | The number of recipients who marked the email as spam. These addresses are added to a [Suppression List](/docs/en/suppressions), either managed by OneSignal or a third party ESP.                                                    |
| **Unsubscribed**     | The number of recipients who opted out of receiving emails.                                                                                                                                                                           |
| **Total Opens**      | The total number of times the email was opened, including repeats.                                                                                                                                                                    |
| **Total Clicks**     | The total number of times a link in the email was clicked, including repeats.                                                                                                                                                         |
| **Unique Opens**     | The number of individual Subscriptions who opened the email. Used with Delivered to calculate the open rate.                                                                                                                          |
| **Unique Clicks**    | The number of individual Subscriptions who clicked a link in the email. Used with Delivered to calculate the click rate.                                                                                                              |

**Total vs Unique clicks and opens**

Unique clicks and opens are counted once per Subscription, regardless of how many times that user opens or clicks the same email. Total clicks and opens count every interaction, including repeats from the same user.

The following metrics are specific to email message reports:

| Name          | Description                                                                                                                                                                     |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Remaining** | Emails still queued for sending. May take up to 8 hours depending on your [Reputation](./email-deliverability) and the Inbox provider's policies (Gmail, Yahoo, Outlook, etc.). |

For detailed metric definitions across all channels, see the [Metrics Glossary](./analytics-metrics-glossary).

### Open rate

Open events are counted when the email is viewed, though privacy settings and inbox behavior may affect accuracy. See [Why are open events low?](#why-are-open-events-low)

| Name             | Description                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| **Unique Opens** | Count of individual recipients who opened the email.                                               |
| **Total Opens**  | Total number of times the email was opened, including repeats.                                     |
| **Open Rate**    | `(Unique Opens / Delivered) * 100%`. Measures how many delivered emails were opened at least once. |

<Info>
  **Unique vs. Total Opens**

  * **Open Rate** is always based on unique opens.
  * Use **Total Opens** to see repeat engagement from the same recipients.
</Info>

<Warning>
  Open rate accuracy can be affected by inbox privacy features (e.g., Apple Mail Privacy Protection), ad blockers, and image tracking being disabled. These factors may cause opens to be **over-reported** (due to automatic image prefetching) or **under-reported** (when tracking pixels are blocked).

  For more reliable engagement insights, compare Open Rate with **CTR** and **CTOR**.
</Warning>

### Click-through rate

Measure engagement through link clicks. Click tracking can be enabled or disabled per email send. For more on link behavior, see [URLs, links, and deep links](./links) and [Email unsubscribe links and headers](./unsubscribe-links-email-subscriptions).

| Name                          | Description                                                                                                                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Click-Through Rate (CTR)**  | `(Unique Clicks / Delivered) * 100%`. Measures how many delivered emails resulted in a click. Requires [Click Tracking to be enabled](./unsubscribe-links-email-subscriptions). |
| **Total Clicks**              | All link clicks, including repeat clicks from the same user. See [URLs, Links and Deep Links](./links).                                                                         |
| **Click to Open Rate (CTOR)** | `(Unique Clicks / Unique Opens) * 100%`. Measures how engaging the email was after being opened.                                                                                |

<Info>
  **CTR vs CTOR** — CTR measures clicks as a percentage of deliveries; CTOR measures clicks as a percentage of opens. Use both to evaluate message quality. Add UTM parameters to links for tracking in tools like Google Analytics.
</Info>

<Warning>
  If click tracking is enabled but click events are low, check for browser-level blocking (e.g., Brave or Firefox). Contact `support@onesignal.com` if the issue persists.
</Warning>

### Unsubscribed and reported as spam

Understand opt-outs and spam complaints so you can improve targeting and deliverability.

| Name                 | Description                                                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Unsubscribes**     | Number of recipients who opted out of receiving emails. Status is updated immediately.                                         |
| **Reported as Spam** | Recipients who marked your message as spam. These addresses are automatically added to the [Suppression List](./suppressions). |

<Warning>
  Monitor unsubscribe and spam rates closely. Rates that are too high can result in your app being disabled. Use segmentation and send-time optimization to reduce complaints. See [Email deliverability](./email-deliverability) and [Email reputation best practices](./email-reputation-best-practices).
</Warning>

***

## Conversions

<Info>
  **Coming soon** — [Conversion metrics](/docs/en/conversion-metrics) will be available on message reports. Once available, you will see attributed and influenced conversions for each message directly in its report. See [Conversion metrics](/docs/en/conversion-metrics) for details on the attribution model and setup instructions.
</Info>

***

## Message statistics

Analyze performance trends over time, including engagement and delivery issues.

<Frame>
  <img alt="Message statistics graph showing delivery and engagement trends over 24 hours" />
</Frame>

View metrics by:

* 30 days (default)
* 24 hours
* 60 minutes

You can toggle additional metrics like Bounced, ESP Failed, Sent, Spam, Suppressed, Total Clicks, and Total Opens.

Use the export icon in the top-right of the graph to download the data.

***

## Audience activity

The **Audience activity** report shows how each subscription interacted with a specific message. Results are grouped into categories so you can quickly see how recipients engaged.

<Frame>
  <img alt="Audience activity screenshot" />
</Frame>

<Tabs>
  <Tab title="Categories">
    | Category                     | Description                                                |
    | ---------------------------- | ---------------------------------------------------------- |
    | **Sent**                     | Message was sent to the device.                            |
    | **confirmed receipt**        | Delivery was confirmed by the device.                      |
    | **Did not confirm delivery** | Delivery confirmation was not received.                    |
    | **Clicked**                  | User clicked the notification.                             |
    | **Did not click**            | User did not click the notification.                       |
    | **Failed**                   | Delivery failed.                                           |
    | **Unsubscribed**             | The subscription unsubscribed after receiving the message. |

    Each tab displays the number of recipients in that category and lets you drill into the individual subscription records.
  </Tab>

  <Tab title="Table columns">
    | Column                  | Description                                                       |
    | ----------------------- | ----------------------------------------------------------------- |
    | **External ID**         | Your system identifier (if set).                                  |
    | **OneSignal ID**        | Unique OneSignal user ID.                                         |
    | **Subscription ID**     | Unique subscription instance (device + app/browser).              |
    | **Device**              | Browser or OS type. If you see `()`, the device has been deleted. |
    | **Subscription status** | Current status (for example, Subscribed, Unsubscribed).           |
    | **Sent**                | Time the message was sent.                                        |
    | **confirmed receipt**   | Time delivery was confirmed by the device.                        |
    | **Clicked**             | Timestamp if the user clicked, or `-` if not.                     |
    | **Failed**              | Indicates if delivery failed.                                     |
    | **Unsubscribed**        | Indicates if the user unsubscribed after receiving the message.   |
    | **Failure message**     | Error message if delivery failed (for example, “Invalid token”).  |
  </Tab>
</Tabs>

<Note>
  Audience activity data is only available for **30 days** from the time the message is sent. Export results if you need to retain them longer.
</Note>

***

### Why audience activity is helpful

Audience activity helps you go beyond delivery counts by showing which specific users fall into each outcome. Use it to:

* **Diagnose delivery issues** by reviewing failed or unconfirmed deliveries.
* **Measure engagement** by comparing clicks vs. non-clicks.
* **Track churn** by identifying unsubscribes tied to a message.
* **Segment audiences** for retargeting or export.

***

### Exporting results

You can download audience data with the **Export** menu:

* **Selected activity** – exports only the currently viewed tab (for example, all users who did not click).
* **All activities** – exports the full report across every category.

Exports let you analyze results offline, share with other teams, or merge with your CRM and analytics tools.

***

### Retargeting users

From any tab, click **Send a retargeted message** to act on that specific group.

You can send:

* **New push**
* **New SMS**

This allows you to follow up with only the users in the selected activity group.

#### Example use cases

* Send a retargeted push to users in **Did not click**.
* Send an SMS to users in **Did not confirm delivery** who may not be reachable via push.
* Follow up with **confirmed receipt** users to encourage further engagement.

***

### Example workflow

<Steps>
  <Step title="Open the Did not click tab">
    Navigate to the **Did not click** tab in Audience activity.
  </Step>

  <Step title="Review the list of subscriptions">
    Check which subscriptions received the notification but did not engage.
  </Step>

  <Step title="Send a retargeted message">
    Click **Send a retargeted message → New push** to follow up with this segment.
  </Step>

  <Step title="Export for deeper analysis">
    If needed, export the audience activity for offline analysis or multi-channel targeting in a journey.
  </Step>
</Steps>

***

## Click activity

The Click Activity section shows a per-link breakdown so you can see which links were clicked and how often. Metric definitions (Unique Clicks, Total Clicks, CTR) are the same as in [Click-through rate](#click-through-rate) above.

<Info>
  **Auto Warm Up campaigns:** Emails sent through [Auto Warm Up](./email-warm-up) after February 2, 2026 show individual click stats for each link. For warm-up campaigns sent before that date, all link clicks are grouped under "All other links."
</Info>

***

## FAQ

### Why are my email stats showing zero opens or clicks?

The most common cause is missing CNAME DNS records. Without CNAME records configured for your sending domain, OneSignal cannot track opens, clicks, or unsubscribes — these metrics stay at zero even though emails are being delivered.

To verify your DNS records are set up correctly:

1. Go to **Dashboard > Settings > Email > Senders**.
2. Select your sending domain and check for a green checkmark next to each DNS record, especially the CNAME records used for click and open tracking.
3. If any records show as missing or unverified, follow the [Email DNS configuration](./email-dns-configuration) guide to add them.

<Note>
  After adding or updating DNS records, allow up to 48 hours for propagation. Opens and clicks are only tracked for emails sent **after** the records are verified — previously sent emails are not retroactively updated.
</Note>

If your CNAME records are verified and you still see zero opens, check whether inbox privacy features are blocking tracking. See [Why are open events low?](#why-are-open-events-low) below.

### Why are my emails marked as failed?

Failure reasons are shown in the Audience Activity export. Common causes include:

* Misspelled or non-existent domains (e.g. `@gmial.com`)
* Email addresses already on your ESP’s suppression list
* Using [Custom Unsubscribe Links](./unsubscribe-links-email-subscriptions) without also unsubscribing via [Update User API](/reference/update-user) or [CSV Upload](./import#csv-upload)
* Previously bounced addresses
* Inboxes throttling un-warmed sender domains (see [Warm-up Guide](./email-warm-up))

### Why are open events low?

Inbox privacy features (e.g., Apple Mail Privacy Protection), ad blockers, and disabled image loading can prevent open events from being recorded. Open tracking is not 100% reliable — test on multiple devices and networks for comparison. See the [Open rate section](#open-rate) for details on how privacy features affect accuracy.

### Why do I see emails in Pending?

Two main reasons:

1. **Scheduled delivery:** Especially if auto warm-up is enabled, delivery is spread out.
2. **Pending confirmation:** Some inboxes delay event feedback up to 8 hours.

If the message stays in Pending, it's likely sent but not confirmed. Check **Sent at** in Audience Activity for clues.

### How do I export audience activity data?

In the email message report, scroll to **Audience Activity** and click **Export CSV**. The export includes per-recipient delivery status, timestamps, click events, and failure reasons.

### What is the difference between Bounced and Suppressed?

**Bounced** means the recipient's mail server rejected the email (e.g., invalid address or full inbox). **Suppressed** means OneSignal proactively blocked the send because the address was already on the [suppression list](./suppressions) — for example, from a previous bounce, spam complaint, or unsubscribe.

***

## Related pages

<Columns>
  <Card title="Email deliverability" icon="envelope-circle-check" href="./email-deliverability">
    Understand factors that affect inbox placement and how to improve them.
  </Card>

  <Card title="Email reputation best practices" icon="shield-check" href="./email-reputation-best-practices">
    Maintain strong sender reputation and avoid spam filters.
  </Card>

  <Card title="Suppressions" icon="ban" href="./suppressions">
    View and manage bounced, unsubscribed, and spam-reported addresses.
  </Card>

  <Card title="Template analytics" icon="chart-bar" href="./template-analytics">
    Review aggregate performance metrics across all sends of a template.
  </Card>

  <Card title="URLs, links, and deep links" icon="link" href="./links">
    Configure link behavior, click tracking, and deep linking in messages.
  </Card>

  <Card title="Email warm-up" icon="temperature-arrow-up" href="./email-warm-up">
    Gradually ramp sending volume to establish domain reputation.
  </Card>

  <Card title="Email DNS configuration" icon="server" href="./email-dns-configuration">
    Add SPF, DKIM, DMARC, and CNAME records to enable tracking and authentication.
  </Card>
</Columns>


# Email overview
Source: https://documentation.onesignal.com/docs/en/email-messaging

Send marketing and transactional emails with OneSignal using the dashboard, Journeys, or the API, with built-in personalization, analytics, and deliverability tools.

OneSignal Email lets you send **marketing** and **transactional** emails from the dashboard, Journeys, or the API.

* **Send marketing campaigns and transactional messages** from the dashboard or API
* **Build automated email and multi-channel flows** with Journeys
* **Design emails** using drag-and-drop or HTML
* **Personalize content** with dynamic fields, conditional logic, and language variants
* **Track performance and A/B test** with detailed analytics
* **Segment your audience** for precise targeting
* **Integrate with CRMs and tools** like HubSpot, Mixpanel, Amplitude, Zapier, and [more](./integrations)

***

## Email setup

Before sending emails, follow these setup guides:

<Note>
  Authenticate your domain (SPF, DKIM, DMARC) and enable [Auto warm-up](./email-warm-up) before sending at scale to protect your sender reputation and inbox placement.
</Note>

<Columns>
  <Card title="Email setup guide" icon="envelope" href="./email-setup">
    Verify your sending domain and enable email in OneSignal.
  </Card>

  <Card title="DNS configuration" icon="globe" href="./email-dns-configuration">
    Automatically configure DNS with one click or complete setup manually.
  </Card>

  <Card title="Senders" icon="at" href="./senders">
    Manage from names, from addresses, reply-to addresses, and multiple sending domains.
  </Card>

  <Card title="BCC emails" icon="copy" href="./email-bcc">
    Send hidden copies of outgoing emails for archiving, compliance, or third-party integrations.
  </Card>

  <Card title="Email template forwarding" icon="forward" href="./email-template-forwarding">
    Import existing email templates by forwarding them directly to OneSignal.
  </Card>

  <Card title="Transactional email setup" icon="bolt" href="./setup-transactional-emails">
    Trigger emails based on user actions or custom events.
  </Card>

  <Card title="Custom unsubscribe pages" icon="link-slash" href="./create-custom-unsubscribe-page">
    Replace the default unsubscribe page using OneSignal APIs.
  </Card>
</Columns>

***

## Deliverability, reputation, and analytics

Deliverability determines whether your emails reach the inbox or land in spam. OneSignal provides tools and guidance to help you build and maintain a healthy sending reputation.

<Columns>
  <Card title="Email deliverability" icon="inbox" href="./email-deliverability">
    Understand how inbox placement works and how OneSignal supports it.
  </Card>

  <Card title="Email reputation best practices" icon="shield" href="./email-reputation-best-practices">
    Warm domains, manage volume, and avoid spam filters.
  </Card>

  <Card title="Auto warm-up" icon="temperature-arrow-up" href="./email-warm-up">
    Automatically ramp sending volume for new domains.
  </Card>

  <Card title="Google Postmaster Tools" icon="google" href="./google-postmaster-tools">
    Monitor Gmail reputation and delivery signals.
  </Card>

  <Card title="Suppressions" icon="ban" href="./suppressions">
    Manage blocked and suppressed email addresses.
  </Card>

  <Card title="Email message reports" icon="chart-line" href="./email-message-reports">
    Track open, click, and conversion rates.
  </Card>

  <Card title="Email troubleshooting" icon="wrench" href="./email-troubleshooting">
    Diagnose and resolve common delivery issues.
  </Card>

  <Card title="Create a confirmed opt-in journey" icon="envelope-open" href="./double-opt-in-email">
    Use Tags, Segments, and Journeys to create a confirmed opt-in journey.
  </Card>

  <Card title="Add your own verification links" icon="link" href="./example-verification-magic-link-otp">
    Learn how to add your own verification links to your emails.
  </Card>
</Columns>

***

## Design your emails

OneSignal supports visual and code-based email creation. Use the drag-and-drop editor for quick campaigns or the HTML editor for full design control. You can also start from a template and customize from there.

<Columns>
  <Card title="Drag-and-drop editor" icon="palette" href="./design-emails-with-drag-and-drop">
    Build emails visually without writing code.
  </Card>

  <Card title="HTML editor" icon="code" href="./design-emails-with-html">
    Design fully custom emails using HTML.
  </Card>

  <Card title="Templates" icon="copy" href="./templates">
    Start from pre-built templates or create and save your own layouts.
  </Card>

  <Card title="Unsubscribe links and headers" icon="link-slash" href="./unsubscribe-links-email-subscriptions">
    Control unsubscribe behavior, headers, and compliance settings.
  </Card>

  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Personalize content using user data and conditional logic.
  </Card>

  <Card title="Multi-language messaging" icon="language" href="./multi-language-messaging">
    Send localized emails in multiple languages.
  </Card>

  <Card title="Email template forwarding" icon="forward" href="./email-template-forwarding">
    Import existing email templates by forwarding them directly to OneSignal.
  </Card>

  <Card title="Copy template to another app API" icon="clone" href="/reference/copy-template-to-another-app">
    Move templates between OneSignal apps.
  </Card>
</Columns>

***

## Send emails

Send messages from the dashboard, automate them with Journeys, or trigger them programmatically via the API.

<Columns>
  <Card title="Dashboard" icon="window-maximize" href="#send-from-the-dashboard">
    Compose a message quickly within the dashboard.
  </Card>

  <Card title="Send via API" icon="code" href="/reference/create-message">
    Send messages programmatically using the REST API.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build automated, multi-step, and multi-channel flows.
  </Card>

  <Card title="A/B testing" icon="flask" href="./ab-testing">
    Test up to 10 message variants to optimize performance.
  </Card>
</Columns>

### Send from the dashboard

<Steps>
  <Step title="Select the message channel" icon="window-maximize">
    Select **Create...** then choose your message channel. You can also navigate to **Messages** or **Templates** to view previous messages.

    <Frame>
      <img alt="OneSignal dashboard showing create message options" />
    </Frame>
  </Step>

  <Step title="Choose a composition method" icon="pencil">
    * Start from scratch with the [block editor](./design-emails-with-drag-and-drop) or [HTML editor](./design-emails-with-html)
    * Use a pre-built [template](./templates)
  </Step>

  <Step title="Set a name and label" icon="tag">
    Add internal metadata for tracking and reporting. API equivalent: `name`
  </Step>

  <Step title="Select your audience" icon="users">
    Choose which users receive the message. You can include and exclude [segments](./segmentation) to target specific groups. Defaults to all "Subscribed Users" if no segment is set.

    <Frame>
      <img alt="Dashboard fields for message name, label, and audience segment selection" />
    </Frame>

    | Targeting method                                    | Dashboard | API |
    | --------------------------------------------------- | :-------: | :-: |
    | [**Segments**](./segmentation)                      |    Yes    | Yes |
    | **Filters** ([API only](/reference/create-message)) |     No    | Yes |
    | **Aliases** ([API only](/reference/create-message)) |     No    | Yes |
  </Step>
</Steps>

#### Sender

Configure the sender details used for this email:

* From name
* From address
* Reply-to address
* Sending domain

<Note>
  Multi-domain sending is supported. See [Senders](./senders).
</Note>

API fields: `email_from_address`, `email_sender_domain`, `email_reply_to_address`

#### Subject and preheader

Set a required subject line and optional preheader text. Preheader display varies by inbox provider; not all inboxes show it.

* API fields: `email_subject` and `email_preheader`
* Supports [message personalization](./message-personalization) and [multi-language messaging](./multi-language-messaging)

#### Tracking and compliance

**Link tracking**: Enabled by default. Supports multi-link tracking. See [Links](./links#email) and [Deep linking](./deep-linking) for details.

* API field: `disable_email_click_tracking`

**Send to unsubscribed users**: Enable only for compliance or non-marketing messages.

* API field: `include_unsubscribed`

<Frame>
  <img alt="Email composition panel showing link tracking and unsubscribe send options" />
</Frame>

#### Delivery schedule and optimization

Choose when the message should start sending.

| Option                              | Description                                        | API field    |
| ----------------------------------- | -------------------------------------------------- | ------------ |
| **Send immediately**                | Deliver to all recipients now.                     |              |
| **Scheduled**                       | Send at a specific time, up to 30 days in advance. | `send_after` |
| **[Auto warm-up](./email-warm-up)** | Gradually ramp volume for new or cold domains.     |              |

<Warning>
  The "start sending" time determines the audience cutoff. OneSignal evaluates segment membership at that moment; anyone in the audience receives the message, regardless of per-user optimization settings.
</Warning>

**Per-user optimization:**

Set when users should receive the message.

| Option                        | Description                                                                                             | API field                                          |
| ----------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| **Everyone at the same time** | All recipients receive the email at once. Best for urgent messages.                                     |                                                    |
| **Intelligent Delivery**      | Sends at the optimal time for each user based on their open and click activity (excludes bot activity). | `delayed_option: last-active`                      |
| **Custom time per timezone**  | Sends at a set local time in each user's timezone.                                                      | `delayed_option: timezone`, `delivery_time_of_day` |

<Info>
  With Intelligent Delivery or Custom time per timezone, delivery spans a 24 hour period so every record in the audience can receive the message. If it is already 10am for a recipient when a 9am-local message sends, they receive it at 9am the following day.
</Info>

Click **Review and Send** to send immediately or on schedule, or **Save** as draft to edit later. Once sending begins, monitor performance under **Messages > Email** or in **Delivery > Sent Messages**. See [Email message reports](./email-message-reports) for details.

***

## Analytics

Track message performance and engagement.

<Columns>
  <Card title="Email message reports" icon="chart-line" href="./email-message-reports">
    Message-level delivery, open rate, and click-through reporting.
  </Card>

  <Card title="Analytics overview" icon="chart-bar" href="./analytics-overview">
    All analytics options available in OneSignal.
  </Card>

  <Card title="Event Streams" icon="signal-stream" href="./event-streams">
    Stream push events to your data warehouse or BI tools in real time.
  </Card>

  <Card title="View messages API" icon="code" href="/reference/view-messages">
    Pull message analytics programmatically via the REST API.
  </Card>
</Columns>

***

## FAQ

### What's the difference between marketing and transactional emails?

Marketing emails are campaigns sent to a segment of users, such as promotions or newsletters. Transactional emails are triggered by a user action or event, such as a password reset or order confirmation. See [Transactional email setup](./setup-transactional-emails) for configuration details.

### Why are my emails going to spam?

Common causes include missing DNS authentication (SPF, DKIM, DMARC), sending to unengaged users, or ramping volume too quickly on a new domain. See [Email deliverability](./email-deliverability) and [Email reputation best practices](./email-reputation-best-practices) for guidance.

### Can I send emails to users who unsubscribed?

Only for compliance or non-marketing messages, such as legal notices. Enable the **Send to unsubscribed users** option when composing or set `include_unsubscribed` via the API. Using this for marketing emails violates anti-spam regulations.

### How do I test emails before sending to Users?

Set up [Test Users](./test-users) to verify delivery, rendering, and deep links without affecting real Users. You can also send to a single-user segment for quick testing.


# Email reputation best practices
Source: https://documentation.onesignal.com/docs/en/email-reputation-best-practices

Build and maintain a healthy email sending reputation to improve deliverability and avoid spam complaints.

<Note>
  New to email deliverability? Read the [Email deliverability overview](./email-deliverability) first to understand key concepts like reputation, bounces, spam traps, and inbox placement.
</Note>

## Protect your reputation

### Monitor spam reports and complaints

A high volume of [spam reports](./email-deliverability#spam-complained) will quickly destroy your sending reputation. Monitor them closely, more often than open or click rates.

Most inbox providers (like Outlook, Hotmail, and Yahoo) report spam complaints and bounces back to OneSignal. Unfortunately Gmail does not. Gmail only surfaces this data through Google Postmaster Tools, which you must set up separately.

Currently, the OneSignal dashboard includes Gmail send volume when calculating [reputation rates](./email-deliverability#reputation) but because Google does not provide the complaint and bounced data for Gmail, the reported rates can appear lower than reality.

<Warning>
  Your dashboard spam rate may be underreported because Gmail complaints are not included. For example, 10 spam complaints across 1,000 emails shows as a 1% spam rate if those complaints come from Outlook or Yahoo, but 0% if they come from Gmail.
</Warning>

To monitor Gmail-specific spam rates and domain reputation (especially since Gmail is the largest mailbox provider), set up [Google Postmaster Tools](./google-postmaster-tools).

<Columns>
  <Card title="Google Postmaster Tools" icon="chart-line" href="./google-postmaster-tools">
    Track aggregate spam rates and domain reputation for Gmail recipients.
  </Card>

  <Card title="Reputation dashboard" icon="shield-check" href="./email-deliverability#reputation">
    Monitor spam and bounce rates for all providers except Gmail in your OneSignal dashboard.
  </Card>
</Columns>

<Frame>
  <img alt="Google Postmaster Tools dashboard showing domain reputation and spam rate" />
</Frame>

<Note>
  Consider why recipients might report your emails as spam:

  * Did they disengage over time?
  * Did they knowingly opt in?
  * Were they sent too many emails?
  * Was the content aligned with their expectations?
</Note>

#### What to monitor regularly

To maintain a healthy sending reputation, regularly review:

* **Reported spam rate**: [Reputation dashboard](./email-deliverability#reputation)
* **Gmail spam rate**: [Google Postmaster Tools](./google-postmaster-tools)
* **Bounce rate**: [Reputation dashboard](./email-deliverability#reputation)
* **Unsubscribe rate**: [Email message reports](./email-message-reports)
* **Open and click engagement trends**: [Email message reports](./email-message-reports)

<Note>
  If you send 5,000 or more emails per day to Gmail or Yahoo, your domain is permanently classified as a [bulk sender](./email-deliverability#gmail-and-yahoo-bulk-sender-requirements). Bulk senders must meet stricter authentication, unsubscribe, and spam-rate requirements. See [Google and Yahoo email sender requirements](./new-google-and-yahoo-email-updates) for the OneSignal-specific setup steps.
</Note>

### Set up a clear opt-in process

Sending emails to people who have not given clear permission often leads to spam reports. This negatively impacts your sending reputation and may result in all your emails going directly to spam.

At minimum, when collecting emails, include a checkbox asking for permission to send marketing emails. If the checkbox is unchecked when the form is submitted, do not add that address to your marketing list. You can either not send the email address to OneSignal or use a [Tag](./add-user-data-tags) like `opt_in_consent: false` to track opt-in status and exclude those recipients from campaigns.

<Warning>
  Collecting the email as part of your sign-up process or account creation is not enough. Consent needs to be explicitly given.
</Warning>

<Frame>
  <img alt="Animated example of an opt-in checkbox on a sign-up form" />
</Frame>

#### Implement confirmed opt-in (double opt-in)

A confirmed opt-in process requires the recipient to verify their interest by clicking a link in a confirmation email. This method:

* Increases engagement
* Verifies compliance (e.g., GDPR, CAN-SPAM)
* Filters out fake or mistyped addresses
* Reduces complaint and bounce rates
* Prevents abuse and list bombing

<Columns>
  <Card title="Create a confirmed opt-in journey" icon="envelope-open" href="./double-opt-in-email">
    Use Tags, Segments, and Journeys to create a confirmed opt-in journey.
  </Card>

  <Card title="Add your own verification links" icon="link" href="./example-verification-magic-link-otp">
    Learn how to add your own verification links to your emails.
  </Card>
</Columns>

#### Offer email preferences

Give recipients the option to choose what types of emails they receive: newsletters, rewards, deals, product updates, etc. Make it easy to adjust these preferences anytime via an email preference center.

<Frame>
  <img alt="Example email preference center with category toggles" />
</Frame>

<Columns>
  <Card title="Create a preference center" icon="sliders" href="./preference-center">
    Build a preference center so recipients can manage their email preferences.
  </Card>

  <Card title="Use Tags to manage email preferences" icon="tag" href="./add-user-data-tags">
    Use Tags to manage recipient preferences.
  </Card>
</Columns>

### Exclude or sunset unengaged recipients

Low open rates indicate poor engagement and hurt your reputation.

Implement a sunset policy to remove recipients who haven't opened or clicked emails in 2–3 months (depending on your send frequency). If you're using omni-channel messaging, you can also use last session date to identify inactive recipients across all channels.

<Card title="Message Event Filter Segments" icon="filter" href="./segmentation#message-event-filters">
  Track recipients who have not opened or clicked emails in more than 3 months, or filter by last session date for omni-channel inactivity, and exclude or delete them from further sends using Message Event Filters or Last Session Date.
</Card>

***

## Set up for success

### Authenticate your sending domain

Inbox providers check that your emails are authenticated before accepting them. Without proper DNS records (SPF, DKIM, DMARC), your emails may be rejected or sent to spam regardless of your content or engagement.

<Card title="Email DNS configuration" icon="globe" href="./email-dns-configuration">
  Set up SPF, DKIM, and DMARC records for your sending domain.
</Card>

### Warm up your sending domain

Inbox providers may block high-volume sends from domains with no sending history. A new domain starts with no [reputation](./email-deliverability#reputation), so you need to build trust gradually.

If you're sending large volumes, especially from a new domain or provider, gradually increase volume to build trust.

<Card title="Email warm-up" icon="sun" href="./email-warm-up">
  Use OneSignal's Auto Warm Up feature to automate the ramp-up process.
</Card>

### Avoid invalid emails

High [bounce](./email-deliverability#bounced) rates hurt your reputation. Validate your list before importing and use confirmed opt-in to prevent bad addresses from entering.

<Card title="Email address validation" icon="circle-check" href="./email-address-validation">
  Validate email addresses during CSV import and in bulk to reduce bounces and protect your sender reputation.
</Card>

***

## Improve deliverability

### Control send frequency

Sending too many emails increases the risk of unsubscribes and spam complaints. Evaluate frequency from the recipient's perspective. Daily emails may be too much for most audiences.

<Columns>
  <Card title="Wait steps" icon="clock" href="./journeys-actions#wait">
    Add delays between Journey messages to control send frequency.
  </Card>

  <Card title="Wait Until branches" icon="code-branch" href="./journeys-actions#wait-until">
    Send Journey follow-ups based on open/click behavior.
  </Card>
</Columns>

<Frame>
  <img alt="Journey example showing excessive email sends without wait nodes" />
</Frame>

### Target engaged recipients

Inbox providers reward high engagement. Recipients who open and click are more likely to receive future emails in their inbox.

<Note>
  Open rates are over-reported for Apple Mail recipients because Mail Privacy Protection prefetches images. When targeting engaged users, prefer **click** behavior over open behavior wherever possible, since clicks are not affected by MPP. See [how open rate is affected](./email-message-reports#open-rate).
</Note>

<Columns>
  <Card title="Wait Until branches" icon="code-branch" href="./journeys-actions#wait-until">
    Send Journey follow-ups based on open or click behavior.
  </Card>

  <Card title="Message Event Filter Segments" icon="filter" href="./segmentation#message-event-filters">
    When sending less-urgent emails, target more engaged recipients.
  </Card>
</Columns>

<Frame>
  <img alt="Journey with a Wait Until branch based on whether the email was opened" />
</Frame>

### Deliver value, not just promotions

Every email should provide real value: insights, tips, solutions, or relevant updates. A discount code alone does not equal value.

**Test your content for spam signals**

Before sending to your full audience, run your email through a spam content check to catch issues that could hurt deliverability.

* **Quick one-off test**: [mail-tester.com](https://www.mail-tester.com/) lets you send a test email to a generated address and scores it on content quality, authentication, blacklist status, and more. Free for a limited number of checks.
* **Ongoing testing**: Tools like GlockApps or Litmus run your email against multiple spam filters (SpamAssassin, Barracuda, etc.) and show inbox vs. spam placement across providers. Useful for regular sends or automated campaigns.
* **DIY content check**: Review your email for common red flags that trigger spam filters:
  * All-caps subject lines
  * Excessive exclamation marks
  * URL shorteners (e.g., bit.ly)
  * Image-heavy emails with very little text
  * Spam-trigger phrases like "act now," "free," or "limited time"
  * Mismatched display text and actual URL (e.g., link text says `yoursite.com` but the URL points somewhere else)

**Evaluate content performance**

Your audience expects specific content types. Make sure you're meeting those expectations.

<Columns>
  <Card title="Multi-link tracking" icon="link" href="./email-messaging#track-link-clicks">
    Identify which content and links recipients click most.
  </Card>

  <Card title="A/B testing" icon="flask" href="./ab-testing#email-a-b-testing">
    Test subject lines, content, and layouts to see what resonates.
  </Card>
</Columns>

**Use email to build relationships and get feedback**

Email is a conversation channel, not a billboard. Use it to build trust and invite responses. Replies improve your sending reputation.

<Note>
  Use a valid reply-to address. Avoid "no-reply" emails.
</Note>

***

## FAQ

### Why are my emails going to spam?

The most common causes are:

* DNS records are not properly configured
* A poor sending reputation
* High spam complaint rates
* Sending to recipients who did not explicitly opt in

Review your [Email Setup](./email-setup) for DNS records configuration, [Google Postmaster Tools](./google-postmaster-tools) for spam rate data, ensure you have a clear [opt-in process](#set-up-a-clear-opt-in-process), and [Exclude or sunset unengaged recipients](#exclude-or-sunset-unengaged-recipients).

### What spam complaint rate is too high?

Google recommends staying below 0.10% and never exceeding 0.30%. Use [Google Postmaster Tools](./google-postmaster-tools) to monitor your spam rate.

OneSignal's [Acceptable Use Policy & Code of Conduct](https://onesignal.com/aup) recommends keeping bounce rates below 5% and spam complaint rates below 0.08%.

### How do I check my domain reputation?

For Gmail, the largest email provider, set up [Google Postmaster Tools](./google-postmaster-tools) to view your domain reputation.

For other providers, you can monitor bounce rates and spam reports in your OneSignal dashboard via:

* [Reputation dashboard](./email-deliverability#reputation)
* [Suppression List](./suppressions)
* [Email Message Reports](./email-message-reports)

### How long does warm-up take?

Warm-up timelines depend on your target volume and current reputation. Typically, plan for 2–4 weeks of gradually increasing volume. See the [Warm Up guide](./email-warm-up) for details on using OneSignal's Auto Warm Up feature.

### Should I remove unengaged recipients from my list?

Yes. Implement a sunset policy to stop sending to recipients who haven't opened or clicked emails in 2–3 months. Low engagement signals to inbox providers that your emails are unwanted, which hurts deliverability for all recipients. Use [Message Event Filter Segments](./segmentation#message-event-filters) to target recipients based on open/click behavior.

***

## Related pages

<Columns>
  <Card title="Email deliverability" icon="inbox" href="./email-deliverability">
    Understand key concepts like reputation, bounces, spam traps, and inbox placement.
  </Card>

  <Card title="Email DNS configuration" icon="globe" href="./email-dns-configuration">
    Set up SPF, DKIM, and DMARC records for your sending domain.
  </Card>

  <Card title="Google Postmaster Tools" icon="chart-line" href="./google-postmaster-tools">
    Monitor Gmail-specific spam rates and domain reputation.
  </Card>

  <Card title="Email warm-up" icon="sun" href="./email-warm-up">
    Gradually increase sending volume to build trust with inbox providers.
  </Card>
</Columns>

***


# Email setup
Source: https://documentation.onesignal.com/docs/en/email-setup

Set up OneSignal Email by selecting a provider, creating a sender, configuring DNS authentication, and verifying your account.

Follow these steps to start sending authenticated emails with OneSignal. Dashboard configuration takes about 10–30 minutes.

<Frame>
  <img alt="Diagram showing the email setup steps: provider, sender, DNS, and verification" />
</Frame>

***

## Prerequisites

Before you start, make sure you have:

* A OneSignal account.
* A sender email address on a domain you own (e.g., `you@yourdomain.com`). Free mailbox providers like Gmail or Outlook are not supported as sending domains.
* Access to your domain's DNS settings, either directly or through someone on your team.

***

## Email setup steps

Follow each step to configure your email setup.

### Step 1: Select a provider

In your OneSignal dashboard, navigate to **Settings > Set up Email**.

To use OneSignal Email, click **Continue Setup**. To use a different provider, choose one from the **Optionally integrate with another email provider** section:

* [SendGrid](./sendgrid-setup)
* [Mailgun](./mailgun-setup)
* [Mailchimp Transactional](./mandrill-setup)

<Frame>
  <img alt="Email configuration page showing provider options" />
</Frame>

### Step 2: Create a sender

Configure the default sender identity for OneSignal to send authenticated email from your domain:

* **Default sender email** — The *from* email address used when no other sender is specified (multiple senders are supported).
* **Default sender name** — The display name shown in the recipient's inbox (e.g., `Acme Team`).
* **Default reply-to** — The email address users reply to. You can override this per email.
* **Sending domain** — Auto-generated based on the sender email's domain. Click **Customize** to use a different subdomain for DNS authentication.

<Tip>
  For optimal deliverability, use a [subdomain](#what-is-a-subdomain-and-why-should-i-use-one) (e.g., `mail.yourdomain.com`) rather than your root domain.
</Tip>

<Frame>
  <img alt="Form fields for default sender email, name, reply-to, and sending domain" />
</Frame>

<Card title="Senders" icon="at" href="./senders">
  Add and manage multiple senders, from addresses, reply-to addresses, and sending domains.
</Card>

### Step 3: Configure DNS

Configure DNS records to authenticate your sending domain. If your registrar is supported, you can **Auto-Configure** or add the records manually.

<Frame>
  <img alt="OneSignal dashboard showing required DNS records and their verification status" />
</Frame>

<Card title="Email DNS configuration" icon="globe" href="./email-dns-configuration">
  Step-by-step guide for auto-configuring or manually adding SPF, DKIM, and DMARC records.
</Card>

### Step 4: Verify your account

When finished with DNS configuration, click **Verify Account**.

OneSignal automatically reviews your domain health, sender reputation, blocklist status, and other deliverability signals to protect domain reputation and prevent abuse. Approval usually completes within a few minutes — you'll receive an email with the results.

<Frame>
  <img alt="OneSignal dashboard prompt to verify your email account" />
</Frame>

<Check>
  If approved, you can start sending emails to your full audience immediately!
</Check>

<Danger>
  If denied, you can review the [Email domain configuration best practices](./email-domain-configuration-best-practices) for help and try again in a week.
</Danger>

***

## FAQ

### What is a subdomain and why should I use one?

A subdomain is a prefix added to your domain name — for example, `mail.yourdomain.com` is a subdomain of `yourdomain.com`. While your "From Address" can still appear as `anything@yourdomain.com`, the subdomain is used for email authentication and delivery.

<Frame>
  <img alt="Diagram showing the difference between the from domain and from address" />
</Frame>

Using a subdomain isolates your email [sending reputation](./email-deliverability#reputation) from your root domain. If your marketing emails generate complaints, it won't affect your root domain's reputation for other services like corporate email. You can also maintain separate reputations for different mail streams:

* `mail.yourdomain.com` for marketing
* `receipts.yourdomain.com` for transactional

### How long does email setup take?

Dashboard configuration (Steps 1–4) typically takes 10–30 minutes. Assuming the account is approved, you can start sending emails to your full audience immediately!

### Can I send emails before I'm verified?

Before your account is approved, you can send test emails to your own email addresses. Sending to your full audience is enabled only after verification is complete.

### What if I don't have access to my DNS settings?

If your registrar is supported, you will see the option to **Auto-Configure** DNS records. If not, you will need someone with DNS access for your domain — typically a developer, IT admin, or whoever manages your domain registrar — to add the SPF, DKIM, and DMARC records manually. Share the exact values from the OneSignal dashboard with that person. Each record shows a check icon in the OneSignal dashboard once it's correctly configured.

### What DNS records are required?

OneSignal requires SPF, DKIM, and DMARC records to authenticate your sending domain. The exact values are shown in the OneSignal dashboard during setup. See [Email DNS configuration](./email-dns-configuration) for details.

### Can I use an external email provider instead of OneSignal Email?

Yes. OneSignal supports [SendGrid](./sendgrid-setup), [Mailgun](./mailgun-setup), and [Mandrill](./mandrill-setup) (Mailchimp Transactional) as external providers. Select your provider during the initial setup step. Features like multiple senders, suppression list management, and custom sending domains are only available with OneSignal Email.

### What happens if my DNS records don't match?

Emails sent from an unauthenticated domain are more likely to be rejected or filtered to spam by inbox providers. Verify your DNS records in the OneSignal dashboard — a warning icon indicates a mismatch that needs to be resolved.

***

## Related pages

<Columns>
  <Card title="Import email list" icon="users" href="./import">
    Import your email list from a CSV file or API.
  </Card>

  <Card title="Email overview" icon="envelope" href="./email-messaging">
    Create and send your first email from the dashboard, Journeys, or the API.
  </Card>

  <Card title="Email reputation best practices" icon="shield-check" href="./email-reputation-best-practices">
    Protect your sender reputation with warm-up strategies, list hygiene, and deliverability monitoring.
  </Card>
</Columns>


# Email template forwarding
Source: https://documentation.onesignal.com/docs/en/email-template-forwarding

Forward your email templates to create them quickly!

Add email templates to your app by simply sending any email to a unique address. After creating a new email template in this way you can immediately view it in the dashboard, edit any necessary links and resources, and start using it right away.

This could save you a lot of time migrating email templates to OneSignal. It is a great starting point for creating email templates from examples. You can always login to the dashboard **Messages > Templates** and update the new template to make sure its reusable with the correct images, links and general clean up.

<Warning>
  If you are using an email from an external source it is strongly recommended that you change any existing links and images to point to new resources you host instead.
</Warning>

<Info>
  Only HTML emails are currently accepted.

  Text-only emails should be created manually in the dashboard via copy and paste.
</Info>

Within your OneSignal dashboard, navigate to **Settings > Keys & IDs > Incoming Email Templates**.

Copy the full `@templates.onesignal.email` address.

<Frame>
  <img alt="" />
</Frame>

Within your email client, select the email you want to "template-ize".

Send the email to the `@templates.onesignal.email`

Navigate to **Messages > Templates > Email** to see your new template.

***


# Email troubleshooting
Source: https://documentation.onesignal.com/docs/en/email-troubleshooting

How to diagnose and fix common OneSignal email issues.

Use this guide to identify and resolve the most common OneSignal email issues, including setup problems, deliverability challenges, and design errors.

<Note>
  Before troubleshooting, review our [Email Setup](./email-setup) and [Email Deliverability](./email-deliverability) guides. These cover the most common causes of email issues.
</Note>

## Setup issues

Most setup problems come from incorrect DNS records or limitations from your Email Service Provider (ESP).

### Verify DNS records

1. Open your DNS provider.
2. Confirm that SPF, DKIM, and MX records match our [Email DNS Configuration](./email-dns-configuration) guide.
3. Allow up to 24 hours for DNS changes to propagate.

<Warning>
  If DNS records are misconfigured, emails may fail to send, bounce, or be marked as spam.
</Warning>

### Monthly send limits (non-OneSignal ESPs)

If you use SendGrid, Mailchimp, or Mailgun directly (not via OneSignal Email), your sending volume is limited by your ESP plan.\
Check your provider's logs:

* [SendGrid Activity Feed](https://www.twilio.com/docs/sendgrid/ui/analytics-and-reporting/email-activity-feed)
* [Mailchimp Activity & Reports](https://mailchimp.com/developer/transactional/docs/activity-reports/)
* [Mailgun Logs](https://www.mailgun.com/products/send/email-analytics/logs/)

### Too many DNS lookups

When testing SPF records with tools like [URI test](https://www.uriports.com/tools?method=spf\&domain=mail.daystrom-institute.com), you may see:

<Frame>
  <img alt="Too many DNS lookups" />
</Frame>

This is expected if you use the SPF record:

```
v=spf1 include:spf.onesignal.email include:mailgun.org ~all
```

OneSignal uses Mailgun "under the hood" as our Email Service Provider. This means the SPF lookups point to the same IP ranges and doesn't actually add any additional lookups. To remove the warning, you can simplify to:

```
v=spf1 include:mailgun.org ~all
```

This will prevent the error and not impact OneSignal email sending.

### Multiple TXT records for sender domain

You can only have **one** SPF record for your sending domain.\
Check with [WhatsMyDNS TXT lookup](https://www.whatsmydns.net/#TXT) to confirm you do not have multiple entries.

***

## Deliverability issues

Deliverability problems include slow sends, spam folder placement, and email bounces.

### Delayed emails

If your sending domain is new or has low reputation, ISPs (Gmail, Outlook, Yahoo) may delay delivery. This is called **rate limiting** or **greylisting**. When looking at your [Email Message Reports](./email-message-reports), you can check the details of how long it took us to send the message.

<Frame>
  <img alt="Email message report" />
</Frame>

In this example, we see the email was sent from OneSignal in under 3 seconds. We send it to the Email Service Provider, which then goes to the recipient's ISP. These email servers may delay the email up to several hours before it gets delivered to the recipient.

<Note>
  Follow our [Email Reputation Best Practices](./email-reputation-best-practices) to speed up delivery.
</Note>

### Too old failures

A "Too old" failure means the recipient's mail server did not accept the message within the 8-hour retry window. The most common cause is recipient-side email security policy, not your sending configuration.

If you see "Too old" failures in your [Email Message Reports](./email-message-reports), work through the steps below to identify the cause.

<Steps>
  <Step title="Group failures by recipient domain">
    Export your failure logs and group the "Too old" failures by recipient domain. A concentrated pattern (many failures across multiple recipients at the same company or using the same email security vendor) points to a recipient-side gateway policy rather than a sender-side issue.
  </Step>

  <Step title="Check for recipient-side email security gateways">
    Recipients using corporate email security gateways like Barracuda, Mimecast, Proofpoint, or Cisco IronPort may have policies that defer or block mail from senders not on their allowlist. These gateways issue repeated 451 deferrals, and after 8 hours of retries the message is marked "Too old."

    To confirm, check whether affected domains share a common email security vendor by looking up their MX records.
  </Step>

  <Step title="Verify your sender reputation">
    Confirm your sending IPs and domain are not on major blocklists:

    * Barracuda: [Barracuda Central reputation lookup](https://www.barracudacentral.org/lookups/lookup-reputation)
    * Spamhaus: [Spamhaus IP and domain lookup](https://check.spamhaus.org/)
    * General: [MXToolbox blacklist check](https://mxtoolbox.com/blacklists.aspx)

    A clean reputation confirms the deferrals are not caused by your sending infrastructure.
  </Step>

  <Step title="Verify authentication is passing">
    Send a test message to [About My Email](https://aboutmy.email/) to confirm SPF, DKIM, and DMARC are aligned. Authentication failures can cause some gateways to defer messages.
  </Step>

  <Step title="Identify invalid or typo domains">
    Filter your failure logs for domains that do not exist in DNS, such as `gmial.com` or `yaho.com`. These failures count against your sender reputation. Remove invalid addresses from your list and add [email address validation](./email-address-validation) to prevent future typos from entering your audience.
  </Step>
</Steps>

<Check>
  If your IPs and domain pass reputation checks and authentication is aligned, the failures are originating on the recipient side.
</Check>

#### Resolving recipient-side blocks

When the cause is a recipient-side email security gateway, the fix is a policy change in the recipient's environment. You can either:

* Ask the affected recipient's IT admin to allowlist your sending domain, such as `mail.yourdomain.com`, in their email security gateway.
* Remove the affected addresses from your list if allowlisting is not possible.

<Note>
  Recipient-side policy blocks are not caused by your ESP and will behave the same way across any email service. OneSignal uses Mailgun to deliver email, and the underlying SMTP retry behavior follows standard industry conventions.
</Note>

### Emails landing in spam

The most common cause is poor sender reputation. Follow our [Email Deliverability](./email-deliverability) guide.

If you are using a third-party ESP, see:

* [SendGrid: Deny lists](https://docs.sendgrid.com/ui/sending-email/deny-lists)
* [Mailgun: Blacklist info](https://help.mailgun.com/hc/en-us/articles/115005365027-What-Is-a-Blacklist-)
* [Mailchimp: Reputation & rejections](https://mailchimp.com/developer/transactional/docs/reputation-rejections/#rejected-emails)

### Sending & receiving from the same domain

A single domain cannot use the same MX records for sending and receiving mail simultaneously. If you want to **send** from `@yourdomain.com` and also **receive** on the same domain:

* Keep your sending DNS with OneSignal.
* Point your MX records to your inbound email provider (e.g., [Google Workspace MX records](https://support.google.com/a/topic/2683820?hl=en\&ref_topic=9202)).

### Suppression lists

If an address unsubscribed or marked you as spam, your ESP will suppress sends to it.\
To resubscribe:

1. Go to **Audience > Subscriptions** in OneSignal.
2. Search for the email address.
3. Click **Unsubscribe from Email** (if subscribed) then **Resubscribe to Email**.
4. Send a test email to confirm.

### Apple Private Relay

If you send to `@privaterelay.appleid.com` addresses, you must verify your sending domain in your [Apple Developer account](https://developer.apple.com/help/account/configure-app-capabilities/configure-private-email-relay-service/).\
Unverified domains will result in dropped emails.

### API key too restrictive

If using SendGrid or Mailchimp, ensure your API key has the [minimum required permissions](./sendgrid-setup#what-are-the-minimum-api-restrictions-i-can-allow).

***

## Email design

These are problems inside the email content itself.

### Links not working

Usually caused by missing or incorrect CNAME configuration.\
If using a third-party ESP, follow their tracking domain setup.

### Buttons not clickable

* Ensure the URL is correct and starts with `https://`.
* Avoid testing from your spam folder—some email clients block links there.

### Adding images to preheader

Gmail supports promotional images in preheaders (deal annotations, product carousels).\
See [Gmail Developer Portal](https://developers.google.com/gmail/promotab/overview) for setup.

***

## Email Service Providers (ESPs)

Common questions or issues related to using our integrations with SendGrid, Mailchimp, or Mailgun.

### Do I have to pay another provider for email?

If you use the [OneSignal Email Setup](./email-setup) then we will manage your email accounts and you do not need to use another email provider. If you plan to use Sendgrid, Mailchimp, or Mailgun, then you will need to continue to pay your email service provider directly.

## What is OneSignal's email throughput?

OneSignal generally sends messages at a rate of 1,000 to 5,000 per second to the Email Service Provider. It is up to your ESP to deliver the emails to your users.

OneSignal uses Mailgun for OneSignal Email and Mailgun advertises that they can support up to [15 million emails per hour](https://www.mailgun.com/blog/product/how-quickly-can-mailgun-process-my-messages-introducing-the-rapid-fire-throughput-sla/).

***


# Email warm-up
Source: https://documentation.onesignal.com/docs/en/email-warm-up

Build sender reputation with inbox providers by gradually scaling email volume to your most engaged recipients. Covers warm-up triggers, ramp schedule, Auto Warm Up, and FAQ.

Warm up your sending to prove to inbox providers (Gmail, Outlook, Yahoo, Apple) that your mail is wanted. Send small volumes to your most engaged recipients first, then scale gradually while keeping spam complaints, bounces, and unsubscribes low.

<Warning>
  **Warm up to your most engaged recipients only.** Never include dormant, inactive, or unverified addresses. High bounces, low opens, and spam complaints from these users will damage the very reputation you're trying to build.
</Warning>

## Prerequisites

Before you start warming up:

* OneSignal Email is enabled on your app.
* Your sending domain is configured with SPF, DKIM, and DMARC. See [Email DNS configuration](./email-dns-configuration).
* Recommended: connect [Google Postmaster Tools](./google-postmaster-tools) so you have a baseline for Gmail spam rate and domain reputation before volume starts ramping.

## What warm-up is (and isn't)

Warm-up is about **building sender reputation** with inbox providers. Each provider treats new sending domains and IPs cautiously by default; warm-up earns their trust by demonstrating consistent, high-quality behavior over time.

Warm-up is **not**:

* **A list hygiene check.** Clean your list *before* warming up, not by warming up.
* **A deliverability test.** Use throwaway addresses to test, not your real audience.
* **A way to validate addresses.** Sending to dormant addresses to see what bounces actively damages your reputation.

<Card title="Email reputation best practices" icon="shield-check" href="./email-reputation-best-practices">
  Protect your sender reputation with list hygiene, engagement, and compliance strategies.
</Card>

## When you need to warm up

Warm up your sending if any of the following apply:

* You send more than 2,000 emails per day
* You're new to OneSignal Email
* You're using a new sending domain or subdomain
* You're increasing daily volume by more than 20%
* You haven't sent high volumes in the past 30 days

OneSignal's shared IPs are pre-warmed, but new domains and subdomains always need to build trust independently.

<Note>
  If your warm-up will cross **5,000 emails per day to Gmail or Yahoo**, your domain is permanently classified as a [bulk sender](./email-deliverability#gmail-and-yahoo-bulk-sender-requirements) by both providers. From that day on you must meet stricter requirements (DMARC alignment, one-click unsubscribe, spam rate below 0.3%). Plan for these before you cross the threshold.
</Note>

## How to warm up

### Build your audience

Your warm-up audience must be users who have **recently engaged** with your messages. Use signals such as:

* Opened or clicked an email in the **last 30 days** (strongest signal)
* Active app or website session in the **last 60 days**
* Purchase, sign-in, or other meaningful action in the **last 90 days**

Exclude any address that is dormant, has bounced, or hasn't engaged in 90+ days. The smaller, more engaged your starting audience, the faster reputation builds.

<Card title="Build a segment" icon="users" href="./segmentation">
  Filter for engaged users by tag, activity, or recent session data.
</Card>

### Ramp volume gradually

Start small and increase by \~20% per day. Senders with strong existing reputation can ramp at 30% daily, but only if engagement stays high.

| Target daily volume | Days to reach (from 300/day baseline) |
| ------------------- | ------------------------------------- |
| 50,000              | 29                                    |
| 100,000             | 33                                    |
| 150,000             | 35                                    |
| 200,000             | 37                                    |
| 300,000             | 39                                    |
| 500,000             | 42                                    |
| 1,000,000           | 46                                    |

<Accordion title="Full stage-by-stage volume table (300/day baseline, 20% growth)">
  | Stage | Daily sends        |
  | ----- | ------------------ |
  | 1     | 300                |
  | 2     | 360                |
  | 3     | 432                |
  | 4     | 518                |
  | 5     | 622                |
  | 6     | 727                |
  | 7     | 896                |
  | 8     | 1,075              |
  | 9     | 1,548              |
  | 10    | 2,229              |
  | 11    | 2,675              |
  | 12    | 3,210              |
  | 13    | 3,852              |
  | 14    | 4,622              |
  | 15    | 5,547              |
  | 16+   | Continue 20% daily |
</Accordion>

<Danger>
  If your spam rate spikes or engagement drops during warm-up, **stop scaling**. Pause sending, review [Email reputation best practices](./email-reputation-best-practices), and resume at a lower volume.
</Danger>

### Choose a sending method

Pick the method that fits your message type. You can mix all three.

#### OneSignal Auto Warm Up (recommended)

OneSignal's Auto Warm Up feature sends a single campaign to your audience gradually over several days, so you don't have to pace sends manually. Best for non-urgent, delay-tolerant content:

* Newsletters
* Evergreen content
* Onboarding flows

Specify your audience and OneSignal handles the pacing. Run multiple Auto Warm Up emails sequentially to reach your target daily volume.

<Frame>
  <img alt="Graph showing Auto Warm Up recommended sending schedule over time" />
</Frame>

<Accordion title="How to use Auto Warm Up">
  ##### Select Auto Warm Up

  1. Compose your email as usual.
  2. In the **Delivery Schedule** section, select **Send with Auto Warm Up**.

  OneSignal generates a sending schedule based on your past delivery volumes, scheduled Auto Warm Up emails, and the size of your current audience.

  <Frame>
    <img alt="Auto Warm Up option in the delivery schedule section" />
  </Frame>

  <Warning>
    The schedule uses sending activity from the last 3 weeks. If there's a gap in sending, the system may assume a lower baseline volume, which affects the recommended ramp.
  </Warning>

  ##### Monitor progress

  Track scheduled and sent counts in the [Email message report](./email-message-reports).

  <Frame>
    <img alt="Auto Warm Up message report showing scheduled and sent counts" />
  </Frame>

  ##### Adjust the start date

  To set a different start date (default is the next day at 9am), make sure **Send with Auto Warm Up** is selected, then:

  1. Click **Edit Auto Warm Up**.
  2. Select **Start Date & Time** and change the date.

  To change the start time on a recommended schedule, select **Custom Schedule** first.

  <Frame>
    <img alt="Auto Warm Up start date and time configuration" />
  </Frame>

  <Info>
    Recipients are selected at random from your audience and sends are distributed across the day. Each audience member receives the email only once per Auto Warm Up campaign.
  </Info>

  ##### Customize your warm-up schedule

  To make the schedule more aggressive or conservative:

  1. Click **Edit Auto Warm Up** to open all schedules.
  2. Adjust the number of emails sent each day or the duration of the warm-up period.
  3. Save your schedule.

  <Frame>
    <img alt="Custom warm-up schedule editor with adjustable daily volumes" />
  </Frame>

  If you customize part of the schedule, OneSignal can auto-fill the remainder using the default 20% daily increase.

  <Frame>
    <img alt="Auto-complete schedule filling remaining warm-up days" />
  </Frame>

  ##### Sending multiple Auto Warm Up emails

  Reaching your target daily volume usually takes more than one Auto Warm Up email. OneSignal automatically schedules each new send for the next available time slot, typically after the previous email's warm-up cycle completes. You don't need to manually adjust the date.

  <Frame>
    <img alt="Multiple auto warm-up emails scheduled sequentially" />
  </Frame>

  <Info>
    You can move the start date and customize the schedule of any Auto Warm Up email. Make sure the total volume across emails meets the recommended warm-up schedule. Reach out to `support@onesignal.com` with questions.
  </Info>

  ##### Cancel an active warm-up

  1. Go to the **Email** page in your OneSignal dashboard.
  2. Find the email you want to cancel.
  3. Click the three-dot menu on the right.
  4. Select **Cancel**.

  <Frame>
    <img alt="Cancel option in the email actions menu" />
  </Frame>
</Accordion>

#### Low-volume behavior-triggered campaigns

Welcome emails and loyalty or rewards emails are naturally low-volume and consistent. They're ideal for early-stage warm-up before you start large broadcasts.

#### Journeys with Split Branches and Wait nodes

For Journey-based sends, combine [Split Branches](./journeys-actions#split-branch) with [Wait nodes](./journeys-actions#wait) to control volume across multi-step flows while preserving Journey logic and timing.

<Frame>
  <img alt="Journey split branch with wait nodes for warm-up volume control" />
</Frame>

## Monitor and adjust

Watch the following signals throughout the warm-up:

* **Spam rate**: should stay below 0.1% (Gmail's threshold). Above 0.3% is critical.
* **Engagement**: open and click rates should stay strong; sustained drops mean your audience isn't as engaged as expected.
* **Bounces**: hard bounces above 2% indicate list quality issues; pause and clean before continuing.
* **Domain reputation**: use [Google Postmaster Tools](./google-postmaster-tools) to monitor Gmail specifically.

<Tip>
  Google Postmaster Tools is the only way to monitor Gmail spam rates and domain reputation directly. Set it up before you start warming up so you have a clean baseline.
</Tip>

If any signal degrades, pause scaling and pull back to your last healthy volume. Resume at +20% only once metrics recover.

## FAQ

### Do I need to warm my subdomain if my domain is already warm?

Yes. Each subdomain is treated separately by inbox providers, so warm each one independently even if the main domain has a good reputation.

### Why do I need to send more than one Auto Warm Up email?

A single Auto Warm Up email reaches only a fraction of your target daily volume because delivery is spread across many days. Multiple sequential emails build sender reputation steadily without triggering spam filters.

### What's the difference between domain and IP warm-up?

**Domain warm-up** is required whenever you migrate to a new email platform. It builds trust for your sending domain with inbox providers. OneSignal automates this through Auto Warm Up.

**IP warm-up** builds reputation for the sending IP address itself. OneSignal automates IP warm-up in the background for dedicated IP customers; shared IP customers don't need to do this separately.

### How does this differ from bringing my own ESP?

With third-party ESPs (SendGrid, Mailchimp, Mailgun), you manage both IP and domain reputation. With OneSignal Email, OneSignal manages IP reputation; maintaining a warm domain with a good reputation is your responsibility.

### What should high-volume senders consider?

Senders ramping toward high daily volumes should plan for a few additional concerns:

* **Bulk sender requirements.** Crossing 5,000 emails per day to Gmail or Yahoo permanently classifies your domain as a [bulk sender](./email-deliverability#gmail-and-yahoo-bulk-sender-requirements). Set up DMARC alignment and one-click unsubscribe before you reach the threshold.
* **Dedicated IPs.** Above \~100,000 emails per month, a dedicated IP gives you full control over volume and reputation but requires you to warm the IP yourself. Contact `support@onesignal.com` to discuss.
* **Subdomain isolation.** Use a fresh subdomain when moving to a new platform. Reusing the same subdomain across different providers can create DNS issues, and starting clean is usually simpler than transferring an established domain.
* **Monitoring cadence.** Connect [Google Postmaster Tools](./google-postmaster-tools) before warm-up starts, and check it daily once you cross 1,000 emails per day to Gmail.

### Why are only some of my emails failing?

This usually means your volume is too high for your domain's current reputation with one or more inbox providers. Look for a `602 (too old)` error in [Audience Activity](/reference/export-csv-of-events). Failures often appear with specific providers like Gmail or Outlook first. Pull back to the volume that was previously delivering successfully and ramp up more slowly.

### Can I edit an Auto Warm Up email after it starts?

No. Once a warm-up send has started, the email cannot be edited. To stop it, navigate to the email index, click the three-dot menu, and select **Cancel**.

### How do I A/B test an Auto Warm Up email?

Create two separate emails targeting equal-sized segments. Select Auto Warm Up for each, then customize the start date and per-stage volume so the combined daily totals across both emails match the [ramp schedule above](#ramp-volume-gradually).

### What's the difference between dedicated and shared IPs?

By default, emails send from a shared IP, which OneSignal maintains. You only need to warm your domain. A dedicated IP is used exclusively by your account, giving you full control over volume and reputation but requiring you to warm the IP yourself. Contact `support@onesignal.com` for details on dedicated IPs.

## Related pages

<Columns>
  <Card title="Google Postmaster Tools" icon="chart-line" href="./google-postmaster-tools">
    Monitor spam rate and domain reputation with Google Postmaster Tools.
  </Card>

  <Card title="Email reputation best practices" icon="shield" href="./email-reputation-best-practices">
    Protect your sender reputation with list hygiene, engagement, and compliance strategies.
  </Card>
</Columns>


# FCM expired token FAQ
Source: https://documentation.onesignal.com/docs/en/fcm-expired-token-faq

Why Android and Chrome push subscriptions get unsubscribed due to FCM token expiry, Google spam suppression, and how to troubleshoot unsubscribe spikes.

Firebase Cloud Messaging (FCM) delivers push notifications to Android devices and Chrome browsers. FCM [expires tokens for devices](https://firebase.google.com/docs/cloud-messaging/manage-tokens#stale-and-expired-tokens) that have been inactive for more than 270 days. These devices may be lost, destroyed, or put into storage and are considered no longer reachable.

When FCM expires a token, OneSignal marks the subscription as **Unsubscribed** the next time you send a push notification to that device.

This is a cleanup exercise from Google — your expected clicks, sessions, and the value you get from OneSignal do not change. You may also see benefits:

* **More accurate analytics** — your CTR reflects your actual reachable audience
* **Faster delivery** — smaller audiences mean campaigns finish delivering faster
* **Less manual work** — no need to manually manage inactive audiences

## Recent changes driving unsubscribe spikes

Seeing sudden spikes in unsubscribes has become more common due to a series of aggressive updates Google has implemented for Chrome and FCM aimed at curbing notification spam and cleaning up inactive data.

These updates include:

* **AI-driven spam suppression (Chrome 143+)** — Chrome actively identifies and suppresses notifications from sites with low engagement.
* **Automatic unsubscription for inactive users** — Introduced in 2024 and ramped up aggressively in late 2025 and early 2026, Chrome's "Safety Check" feature automatically unsubscribes users from sites that send a high volume of notifications but receive very low user engagement.
* **FCM data policy enforcement** — A major FCM policy update on token removal due to data retention has caused peaks in unsubscribes for campaigns targeting all users. Profiles inactive for roughly a year are archived and marked as unsubscribed to keep subscriber bases deliverable.

## Troubleshooting unsubscribe spikes

If you notice a sudden increase in unsubscribes for Android or Chrome subscriptions, follow these steps:

<Steps>
  <Step title="Verify your SDK version">
    Check your site or app to confirm OneSignal is on the latest SDK version and that you have not removed the SDK or made any recent changes to your integration.
  </Step>

  <Step title="Review your engagement trends">
    Navigate to **Dashboard > Analytics > Engagement Trends** to check your send, delivery, and unsubscribe patterns over time. See [Aggregate trends](./analytics-overview#aggregate-trends) for details on reading these charts.
  </Step>

  <Step title="Check your send frequency">
    Due to the way push works, if users uninstall the app, clear browser data, or unsubscribe from notifications in their device settings and never return to the app or site, it takes 2 or more push notifications to detect the unsubscribe. See [When do push subscription statuses update?](./subscriptions#when-do-push-subscription-statuses-update) for more details.

    If you go long periods without sending messages to all your users, you will see spikes in unsubscribes when you resume sending. Send messages to all users at least once or twice a month to detect unsubscribes gradually rather than in large batches.
  </Step>

  <Step title="Evaluate your delivery metrics">
    If you regularly send messages to all users and your confirmed receipt and click metrics are normal, the unsubscribes are likely FCM cleaning up invalid tokens for your app. This does not affect your reachable audience.
  </Step>
</Steps>

## FAQ

### Why did I see a sudden increase in Android and/or Chrome unsubscribes?

FCM expires tokens for devices inactive for more than 270 days. When you send a push notification to those devices, their push subscriptions are marked as unsubscribed. You will see this reflected as increased unsubscribe counts in your dashboard and delivery reports.

Google has also introduced [additional changes](#recent-changes-driving-unsubscribe-spikes) that more aggressively remove inactive or low-engagement subscriptions.

### What happens after a device token is expired?

The expired token is permanently invalid. The subscription is marked as **Unsubscribed** in OneSignal after attempting to send a push notification to the device.

### Does inactivity on my app specifically trigger token expiry?

No. FCM measures inactivity at the **device level**, not per Firebase project. Even if a device has not opened your app in 270+ days, the token remains valid as long as the device itself is active. You will not know a token is expired until you send a notification and see the subscription marked as unsubscribed.

### What if an inactive device comes back online?

When the user opens your app again, the OneSignal SDK automatically retrieves a new push token and updates the existing subscription record. The user keeps their subscribed status and does not need to opt in to push again — push permissions are stored on the device for a given app.

### Can I tell the difference between an active unsubscribe and an FCM token expiry?

No. FCM does not differentiate between these types of unsubscribes, so OneSignal cannot distinguish them either.

***


# Push frequency capping
Source: https://documentation.onesignal.com/docs/en/frequency-capping

Push frequency capping limits how many push notifications a single user can receive in a rolling minute, hour, day, or week window — useful when multiple teams, Journeys, or automated triggers risk over-messaging the same user.

Frequency capping limits how many push notifications a single user can receive in a rolling time window (per minute, hour, day, or week). Use it to prevent over-messaging when multiple teams, Journeys, or automated triggers send to the same user.

<Note>
  Frequency capping is available on select [paid plans](https://onesignal.com/pricing).
</Note>

***

## How frequency capping works

Each delivered push "ages out" of the user's rolling window when the configured time period has elapsed since that push was sent. Once the user has received the maximum number of notifications inside the window, OneSignal drops any additional sends until older notifications age out.

**Example:** Frequency cap of **3 notifications per 24 hours**.

| Time            | Action                                | Notifications in window | Delivered? |
| --------------- | ------------------------------------- | ----------------------- | ---------- |
| Day 1, 9:00 AM  | Send Notification 1                   | 1                       | Yes        |
| Day 1, 1:00 PM  | Send Notification 2                   | 2                       | Yes        |
| Day 1, 5:00 PM  | Send Notification 3                   | 3                       | Yes        |
| Day 2, 8:00 AM  | Send Notification 4                   | 3 (cap reached)         | No         |
| Day 2, 9:00 AM  | Notification 1 ages out (24h elapsed) | 2                       | —          |
| Day 2, 9:01 AM  | Send Notification 5                   | 3                       | Yes        |
| Day 2, 10:00 AM | Send Notification 6                   | 3 (cap reached)         | No         |
| Day 2, 11:00 AM | Send Notification 7                   | 3 (cap reached)         | No         |
| Day 2, 1:00 PM  | Notification 2 ages out (24h elapsed) | 2                       | —          |
| Day 2, 2:00 PM  | Send Notification 8                   | 3                       | Yes        |

Notifications 4, 6, and 7 are dropped because the user's rolling 24-hour window already holds three notifications at the moment each is sent.

<Note>
  "Per day" refers to a rolling 24-hour window, not a calendar day. If a user receives a message at 6:45 PM, that notification stays in their window until 6:45 PM the next day. Sends in that interval count toward the cap and may be dropped.
</Note>

***

## When to use frequency capping

Frequency capping is most useful when messaging volume can grow without coordination:

* **Complex campaign environments** — large organizations with multiple teams or overlapping marketing campaigns.
* **High-frequency triggers** — systems that send notifications from frequent events (stock price updates, automated news alerts, etc.).

***

## What gets capped

* Frequency capping applies to **push notifications only**. It does not apply to email, SMS, or in-app messages.
* It applies to all push sources — Create notification API, [Journeys](./journeys-overview), and manual dashboard sends.
* Messages blocked by the cap are **dropped**, not queued. They are never retried.

For example, with a cap of 2 per day, if a user has already received two API pushes, a Journey push later that day is dropped unless the sender explicitly overrides the cap (see [Override frequency capping](#override-frequency-capping)).

***

## How to enable frequency capping

Configure frequency capping at the app level from the OneSignal dashboard.

<Steps>
  <Step>
    Navigate to **Settings > Push & In-app > Frequency Capping**.
  </Step>

  <Step>
    Set the maximum number of messages a user can receive in your chosen time window (per minute, hour, day, or week).

    <Frame>
      <img alt="Frequency capping settings in the OneSignal dashboard, with fields for maximum messages and a selectable time window." />
    </Frame>
  </Step>
</Steps>

***

## Override frequency capping

Override frequency capping on a per-message basis when a send must reach the user even if the cap is reached.

<Tabs>
  <Tab title="Dashboard">
    In the message's **Delivery Schedule**, select **Override frequency capping settings**.

    <Frame>
      <img alt="Delivery Schedule section of the push composer with the 'Override frequency capping settings' option selected." />
    </Frame>
  </Tab>

  <Tab title="API">
    Using the [Create push notification API](/reference/push-notification), set `enable_frequency_cap` to `false` to bypass the cap for that message. Omit it or set to `true` to apply normal capping.

    ```json theme={null}
    {
      "enable_frequency_cap": false
    }
    ```
  </Tab>
</Tabs>

### Notes on overriding

* Frequency capping must be enabled in the dashboard for this override to have any effect.
* Overridden messages still **count toward the cap**, so they affect whether future messages are delivered to the same user.

***

## Reporting

When frequency capping is enabled, you can monitor its impact in two places:

* **Dashboard message reports** — each message's delivery stats show the number of users skipped because of the cap.
* **[View message API](/reference/view-message)** — returns the same per-message capped and overridden counts.

Each message has one of two related statuses:

* **Capped** — frequency capping was applied; the response includes the number of users skipped.
* **Overridden** — frequency capping is enabled for the app but was overridden for this message.

***

## FAQ

### What time windows are supported?

Per minute, per hour, per day (rolling 24 hours), and per week (rolling 7 days). All windows are rolling — they don't reset on calendar boundaries.

### Does frequency capping apply to email, SMS, or in-app messages?

No. The cap configured under **Settings > Push & In-app > Frequency Capping** only limits push notifications. Email, SMS, and in-app messages have their own delivery controls and aren't affected.

### What happens to messages that exceed the cap?

They are dropped, not queued. A push that would put the user past the cap is silently skipped for that subscription and never retried.

### Do overridden messages count toward future caps?

Yes. Setting `enable_frequency_cap` to `false` (or selecting the dashboard override) lets that message reach the user, but it still counts in the rolling window and can push later messages past the cap.

### Why is the parameter named `enable_frequency_cap` if I set it to `false` to deliver?

The parameter controls whether the cap **applies** to the message. Setting it to `false` means "do not apply the cap to this message" — the cap is disabled for that one send. The user-level cap configured in the dashboard remains active for every other send.

### Where can I see how many sends were capped?

In any message's delivery report (dashboard) or in the [View message API](/reference/view-message) response. Both surface the same per-message **Capped** and **Overridden** totals.

***

## Related pages

<Columns>
  <Card title="Throttling" icon="gauge-high" href="./throttling">
    Smooth out the rate at which notifications go out across your audience — separate from per-user capping.
  </Card>

  <Card title="Journeys overview" icon="route" href="./journeys-overview">
    Multi-step automated messaging. Journey sends respect frequency capping unless they explicitly override it.
  </Card>

  <Card title="Create push notification" icon="paper-plane" href="/reference/push-notification">
    REST API for sending pushes. Set `enable_frequency_cap` to `false` to override the cap per message.
  </Card>

  <Card title="View message" icon="chart-simple" href="/reference/view-message">
    Retrieve per-message stats, including the number of users capped or overridden.
  </Card>
</Columns>


# Google Postmaster Tools
Source: https://documentation.onesignal.com/docs/en/google-postmaster-tools

Set up Google Postmaster Tools to monitor Gmail spam rates and domain reputation. Gmail does not share this data directly with email senders.

Google Postmaster Tools is the only way to see your spam rate and domain reputation with Gmail. Unlike other inbox providers, Gmail does not report per-user spam complaints or bounces back to email senders like OneSignal. Instead, Google Postmaster Tools provides aggregate data you can use to monitor and improve your [email deliverability](./email-deliverability).

Gmail is the largest inbox provider in the world, making this data essential for understanding how your emails perform.

<Note>
  If you send 5,000 or more emails per day to Gmail, your domain is permanently classified as a [bulk sender](./email-deliverability#gmail-and-yahoo-bulk-sender-requirements) and you must keep your spam rate below 0.3%. Postmaster Tools is the only place to monitor this for Gmail. Connect it before you reach the threshold so you have a baseline.
</Note>

## How to connect Google Postmaster Tools

<Steps>
  <Step>
    Go to [https://gmail.com/postmaster/](https://gmail.com/postmaster/) and **click "Get Started"**.
  </Step>

  <Step>
    **Input the *subdomain*** that you have set up with OneSignal.

    <Frame>
      <img alt="Google Postmaster Tools domain input showing subdomain vs root domain" />
    </Frame>
  </Step>

  <Step>
    **Click "Next"** and Google will provide a TXT record for you to create in your DNS records.

    * Create this record in your DNS registrar to verify ownership of the domain.
  </Step>

  <Step>
    Once you have created the provided TXT record in your DNS records, **click "Verify"**.
  </Step>

  <Step>
    Lastly, add `mailmonitor@onesignal.com` as a **"managed user"**.

    * This gives OneSignal view-only access to help monitor your reputation on your behalf.

    <Frame>
      <img alt="Google Postmaster Tools interface showing the Managed Users option" />
    </Frame>

    <Frame>
      <img alt="Adding mailmonitor@onesignal.com as a managed user in Google Postmaster Tools" />
    </Frame>
  </Step>
</Steps>

***

## Monitor spam rate

This Gmail spam rate is separate from the spam metrics shown in your OneSignal dashboard.

If your emails are landing in Gmail spam folders, Google Postmaster Tools may offer insight.

The spam rate represents the percentage of your mail volume that Gmail recipients actively reported as spam on a given day.

This data is aggregated by Google and does not identify individual recipients who reported spam.

Google states: *"Keep spam rates reported in Postmaster Tools below 0.10% and avoid ever reaching a spam rate of 0.30% or higher."* See [Google's Email Sender Guidelines](https://support.google.com/a/answer/81126?hl=en#spam-rate).

<Frame>
  <img alt="Google Postmaster Tools chart showing a healthy Gmail spam rate" />
</Frame>

The following example shows a consistently high spam rate, with peaks regularly exceeding Google's recommended thresholds.

<Frame>
  <img alt="Google Postmaster Tools chart showing a dangerously high Gmail spam rate" />
</Frame>

<Card title="Email reputation best practices" icon="shield-check" href="./email-reputation-best-practices">
  Follow these best practices to lower spam complaint rates and improve deliverability.
</Card>

***

## FAQ

### Why does Google Postmaster Tools show 0% or no data for my domain?

Google Postmaster Tools requires a minimum daily email volume to Gmail before it displays data. If you're sending low volumes, you may not see any metrics.

If you do have sufficient volume, check that you added the correct domain. Data appears for the domain used in the visible "From" address header of your email, not necessarily your return-path or SMTP sending domain. Although you send from your "sending domain," the *from* address in the header may be different, causing the sending domain to show 0%.

<Frame>
  <img alt="Google Postmaster Tools Authentication Dashboard showing domain details" />
</Frame>

### How often is Google Postmaster Tools data updated?

Google Postmaster Tools updates data daily, typically with a 1–2 day delay. You will not see same-day data.

### What do the domain reputation levels mean?

Google Postmaster Tools rates your domain as **High**, **Medium**, **Low**, or **Bad** based on your sending history and spam rates:

* **High**: good sending history with a very low spam rate.
* **Medium**: good sending history, but has occasionally generated spam.
* **Low**: known to send a considerable volume of spam regularly.
* **Bad**: history of sending a high volume of spam. Emails from this domain will almost always be rejected or filtered to spam.

If your reputation drops to Low or Bad, review the [email reputation best practices](./email-reputation-best-practices) to identify the cause. See [Google's domain reputation documentation](https://support.google.com/a/answer/9981691) for more details.

### What should I do if my spam rate is above 0.10%?

Review the [email reputation best practices](./email-reputation-best-practices) to identify and fix the cause. Common steps include verifying your [opt-in process](./email-reputation-best-practices#set-up-a-clear-opt-in-process), [sunsetting unengaged recipients](./email-reputation-best-practices#exclude-or-sunset-unengaged-recipients), and [controlling send frequency](./email-reputation-best-practices#control-send-frequency).

***


# OneSignal Documentation
Source: https://documentation.onesignal.com/docs/en/home

Start building faster with OneSignal. Explore quickstarts, SDKs, messaging channels, API references, and advanced features like Journeys and Live Activities.

<HomepageBanner title="OneSignal Documentation" description="Start building faster with comprehensive guides, example code, and platform overviews for omnichannel messaging." />

<div>
  <Columns>
    <Card href="./quickstart-guide">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Dashboard setup
          </div>

          <div>
            Set up your OneSignal project, configure platforms, and start sending notifications quickly.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./developers">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            SDK setup
          </div>

          <div>
            Install and integrate the OneSignal SDK with your app to enable messaging capabilities.
          </div>
        </div>
      </div>
    </Card>

    <Card href="/reference/rest-api-overview">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            API reference
          </div>

          <div>
            Explore our full API reference to automate messaging, manage users, and track delivery.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./push">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Push
          </div>

          <div>
            Set up and send mobile and web push notifications with advanced targeting and automation.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./email-messaging">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Email
          </div>

          <div>
            Build, personalize, and send transactional and marketing emails using OneSignal.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./sms-messaging">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            SMS & RCS
          </div>

          <div>
            Send time-sensitive SMS and RCS messages using OneSignal's powerful messaging engine.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./in-app-messages-setup">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            In-app messages
          </div>

          <div>
            Create in-app messages to engage users while they're active in your app.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./live-activities">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Live Activities
          </div>

          <div>
            Deliver real-time updates to iOS Live Activities using OneSignal's SDK and API.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./journeys-overview">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Journeys
          </div>

          <div>
            Design no-code messaging journeys across channels to onboard, retain, and re-engage users.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./ab-testing">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            A/B Testing
          </div>

          <div>
            Optimize your messaging with A/B tests to improve engagement and conversion rates.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./analytics-overview">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Analytics
          </div>

          <div>
            Track the success of your messaging campaigns with detailed analytics.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./integrations">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Integrations
          </div>

          <div>
            Connect OneSignal to 3rd party tools, CRMs, data pipelines, and more via SDKs or webhooks.
          </div>
        </div>
      </div>
    </Card>
  </Columns>

  <div>
    <div>
      Essential Concepts
    </div>

    <p>Master these fundamental concepts to build effective messaging campaigns and understand OneSignal's core capabilities.</p>
  </div>

  <Columns>
    <Card href="./add-user-data-tags">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Tags
          </div>

          <div>
            Custom metadata attached to users to store preferences, behaviors, and properties for targeting.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./segmentation">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Segmentation
          </div>

          <div>
            Dynamic groups of users based on criteria like behavior, location, tags, and subscription status.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./users">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Users
          </div>

          <div>
            A User represents an individual with one or more subscriptions to messaging channels like push, email, and SMS.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./subscriptions">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Subscriptions
          </div>

          <div>
            A subscription in OneSignal represents the specific channel or device through which a user can receive messages.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./users#external-id">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            External ID
          </div>

          <div>
            A unique identifier you assign to link a OneSignal user with your own user system or database.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./users#onesignal-id">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            OneSignal ID
          </div>

          <div>
            A unique UUID automatically generated by OneSignal to identify each user in the system.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./message-personalization">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Personalization
          </div>

          <div>
            The ability to customize message content using user data, tags, and dynamic content for relevant experiences.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./deep-linking">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Deep Linking
          </div>

          <div>
            Direct users to specific app screens or web pages with custom deep links and URLs.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./multi-language-messaging">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Multi-Language
          </div>

          <div>
            Send messages in multiple languages to reach global audiences effectively.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./confirmed-delivery">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            confirmed receipt
          </div>

          <div>
            Verification that a push notification was successfully delivered to and displayed on a user's device.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./custom-outcomes">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Custom Outcomes
          </div>

          <div>
            Track custom conversion events and measure the impact of your messaging campaigns.
          </div>
        </div>
      </div>
    </Card>

    <Card href="./event-streams">
      <div>
        <div>
          <img />
        </div>

        <div>
          <div>
            Event Streams
          </div>

          <div>
            Stream real-time messaging events to external systems for advanced analytics and automation.
          </div>
        </div>
      </div>
    </Card>
  </Columns>
</div>


# In-app click actions
Source: https://documentation.onesignal.com/docs/en/iam-click-actions

Configure click actions on in-app message elements to open URLs, prompt for push or location permissions, track outcomes, tag users, or trigger custom logic.

Click actions are interactive events you attach to elements in an in-app message — buttons, images, or backgrounds. Add them using the drag-and-drop editor or the HTML editor via the [In-app JavaScript API](./in-app-message-api).

<Frame>
  <img alt="Diagram showing how in-app message click actions trigger location and push permission prompts on iOS" />
</Frame>

## Click action types

### URL

Opens the specified URL in the device's default browser. Maps to `openUrl` in the [In-App JS API](./in-app-message-api). For deep linking within the app, use a **Custom Action ID** instead.

### Push permission prompt

Shows the native iOS or Android push permission prompt. If the device is already subscribed, the in-app message does not display. If the device was previously prompted and declined, a native alert asks the user to enable push notifications in app settings. Maps to `triggerPushPrompt` in the [In-App JS API](./in-app-message-api).

### Location permission prompt

Shows the native operating system prompt to request location tracking permission. Your app must include [location tracking permissions](./mobile-sdk-reference#location) — see [Location Opt-In Prompt](./location-opt-in-prompt) for setup. Maps to `triggerLocationPrompt` in the [In-App JS API](./in-app-message-api).

### Send outcome

Tracks a user interaction for analytics. Outcomes sent through in-app messages appear as "Unattributed" and set a [tag](./add-user-data-tags) on the user in the format `outcome_name : true`. See [Custom Outcomes](./custom-outcomes) for details. Maps to `sendOutcome` in the [In-App JS API](./in-app-message-api).

### Tag user

Adds a [tag](./add-user-data-tags) to the user based on their response, which you can use to segment them for more targeted messaging. Maps to `tagUser` in the [In-App JS API](./in-app-message-api).

### Custom action ID

Passes a custom value that your app reads through the [SDK IAM Click Listener](./mobile-sdk-reference#addclicklistener-in-app) when the element is clicked. Use this for:

* Sending interaction data to your own server or analytics vendor.
* [Deep linking within the app](./deep-linking) to navigate to specific screens.

Maps to `addClickName` in the [In-App JS API](./in-app-message-api).

#### Collecting custom click actions

Set a **Custom Action ID** on any image or button block to identify which element was clicked. Your app detects the click through the [SDK IAM Click Listener](./mobile-sdk-reference#addclicklistener-in-app) and can send the data to your server, database, or analytics vendor.

<Accordion title="Example: create a poll" icon="square-poll-vertical">
  Set a unique Action ID on each button in a multiple-choice in-app message. When a user clicks an option, your app detects it through the [SDK IAM Click Listener](./mobile-sdk-reference#addclicklistener-in-app), sends the response to your server, and can display aggregated results back to the user later.

  Instead of an Action ID, you can also use a **Tag** to identify the clicked element and segment users based on their response.
</Accordion>

***

## Related guides

<Columns>
  <Card title="Deep Linking" icon="link" href="./deep-linking">
    Set up custom URL schemes and app-specific routing for push and in-app messages.
  </Card>

  <Card title="In-app JavaScript API" icon="code" href="./in-app-message-api">
    Reference for click action methods in the HTML in-app message editor.
  </Card>

  <Card title="App Store rating example" icon="star" href="./example-app-store-review">
    Step-by-step tutorial for prompting app store reviews from in-app messages.
  </Card>

  <Card title="Target outdated app versions" icon="rotate" href="./app-version-update">
    Prompt users to update their app.
  </Card>

  <Card title="Onboard users with banner in-app messages" icon="hand-wave" href="./example-create-a-tutorial">
    Guide users with contextual top and bottom banner in-app messages that don't block your app UI.
  </Card>
</Columns>

***

## FAQ

### Can I add multiple click actions to a single element?

No. Each element (button, image, or background) supports one click action. To trigger multiple behaviors, use a **Custom Action ID** and handle the logic in your app through the [SDK IAM Click Listener](./mobile-sdk-reference#addclicklistener-in-app).

### How do I deep link to a screen in my app?

Use the **Custom Action ID** click action and handle routing in your app via the [SDK IAM Click Listener](./mobile-sdk-reference#addclicklistener-in-app). The **URL** action opens links in the browser, not inside the app. See [Deep Linking](./deep-linking) for full setup.

### Why doesn't the push permission prompt appear?

If the device is already subscribed to push notifications, the in-app message with a push permission prompt click action does not display. Verify the user's push subscription status in the OneSignal dashboard before testing.


# In-app triggers
Source: https://documentation.onesignal.com/docs/en/iam-triggers

Options for displaying in-app messages to users.

## Overview

Use triggers to display in-app messages to users within the audience at a time of your choosing. Unlike push, email, and SMS that just send the message at a specific time, in-app messages require a trigger to determine when to show the message to users while in your app.

<Note>
  Triggers determine when to display the message. To set how often the message should be displayed, see [Schedule and frequency](./in-app-messages-setup#schedule-%26-frequency).
</Note>

<Frame>
  <img />
</Frame>

### Requirements

* Review the [In-app message overview](./in-app-messages-setup) for additional setup and requirements.
* Some triggers (documented below) are programmatic and require code to be added to your app before the message can be displayed.
* **Users must be within the audience before a new session starts for the trigger to display the message.** A new session starts when the app is out of focus for at least 30 seconds. See [How in-app messages are shown](./in-app-messages-setup#how-in-app-messages-are-shown).

***

## Trigger types

There are four types of triggers. Each can be combined with **AND** and **OR** operators to only show under very specific conditions.

### On app open

**No code required.** Show message upon next app open. Users within the audience will be eligible to receive the message when they open the app.

* For audience segments that require tags or specific actions that a user joins during a session, they will need to start a new session for the message to be displayed on the next app open.
* For audience segments that target all users or app version filters, the message will be displayed when the user opens the app. Even if a brand new user.

### In-app trigger

**Code required.** Show message when user performs certain actions. Requires a `key` and `value` to be passed into the [`addTrigger` method](./mobile-sdk-reference#in-app-messages) within your app.

<Frame>
  <img />
</Frame>

Example will display the in-app message when your app calls the method `addTrigger('trigger', '1')`. Keep in mind the user must be within the audience before a new session starts for the trigger to display the message. See above [Requirements](#requirements) for more details.

#### Important in-app trigger requirements

* `keys` and `values` are space and case sensitive. Check for accidental spaces or casing when setting the trigger.
* You can require multiple `keys` and `values` to be present for the message to display.
  * Each key-value pair using an `AND` condition must be satisfied for the trigger to display the message.
  * Key-value pairs using an `OR` condition will display the message if any of the key-value pairs are satisfied.
* When requiring multiple triggers, you can use the [`removeTrigger` method](./mobile-sdk-reference#in-app-messages#remove-trigger) to remove a trigger if needed.
* `Greater than` and `less than` conditions work for number values even though they are set as strings in the code.
  * If you want to display a message when a user reaches level 5. You would set the audience as all users, but would set your trigger to be "level is 5". Each time a user grows a level, you would call `addTrigger("level", "x")` where "x" is the level they reached. This continues to increment until `addTrigger("level", "5");` is called, then the In-App Message will show to the user.

### Session duration

**No code required.** Show message after a specific number of seconds within the current app session. The user must be within the audience before a new session starts for the trigger to display the message. See above [Requirements](#requirements) for more details.

### Duration since last in-app

**No code required.** Show message after a specific number of seconds since the most recent in-app message. The user must be within the audience before a new session starts for the trigger to display the message. See above [Requirements](#requirements) for more details.

This is helpful to include in less urgent or lower priority messages so they do not display too closely to more important messages.

***

## When should this message dismiss?

This option allows you to control how long the message should stay on the screen.

* **Show until dismissed**: The message will show until physically acted upon. Either a close button is clicked or the message is swiped away.
* **Dismiss after certain amount of time**: Set the number of seconds in which the message will be displayed before it is automatically removed from screen. This is helpful if the message is informative and doesn't require user action.

***

## How often do you want to show this message?

While triggers determine when to display the message, this option allows you to control how often the message should be displayed. See [Schedule and frequency](./in-app-messages-setup#schedule-%26-frequency) for more details.

<Frame>
  <img />
</Frame>

### Set when and how many times the message shows

**Only once** is default. The in-app message will only show 1 time to the Subscription.

**Every time trigger conditions are satisfied** will show this message each time the Trigger conditions are met.

* For in-app triggers, this may be multiple times a session. For other triggers, it is only once per session.

**Multiple times** allows you to set the specific amount of times this message can be shown and how long to wait in between each display.

* If you set: "`2` times with a gap of `1` **hour** in between" - The message will be allowed to trigger a total of `2` times. The first time when the triggers are met, then the 2nd time when the triggers are met and `1` hour has passed.
* If you set "`12` times with a gap of `30` **days** in between" - The message will show roughly once a month for a year.

***

## FAQ

### Are triggers tags?

Triggers are not tags. Triggers are key-value pairs set within the [Trigger methods of our SDK](./mobile-sdk-reference#in-app-messages). [Tags](./add-user-data-tags) are user data that you can set and use to target users in your audience.

Set tags for segments to use in the audience and use triggers to display the message.

### Can I use multiple triggers?

Yes, you can use multiple triggers. See [Important in-app trigger requirements](#important-in-app-trigger-requirements) for more details.

***


# In-app message templates & quickstarts
Source: https://documentation.onesignal.com/docs/en/in-app-html-templates

OneSignal quickstart designs and copy/paste HTML templates for In-App Messages, plus required setup and common gotchas.

OneSignal offers two ways to get started quickly with in-app messages: **quickstart designs** built into the dashboard, and **copy/paste HTML templates** for the HTML editor.

<Note>
  All templates and quickstarts run inside an in-app message webview. To close messages, open URLs, tag users, and capture clicks, use the [In-App Message JS API](./in-app-message-api).
</Note>

## Prerequisites

Before you start, we recommend you review:

* The [In-app Message Overview](./in-app-messages-setup) page.
* The [Design your In-App Message with the HTML Editor](./design-your-in-app-message-with-html) page.

<Warning>
  Do not put secrets (API keys, tokens) in template code. Treat all in-app message input as untrusted and validate it in your app or backend.
</Warning>

***

## Quickstart designs

OneSignal now includes a library of ready-to-use quickstart designs directly in the dashboard. These cover common use cases like push permission prompts, onboarding flows, and feature announcements — available in both the Block Editor and HTML Editor.

**To access the quickstart library:**

1. In OneSignal, go to **Messages > In-App > New In-App**.
2. Under **Start from a pre-built design**, select the **OneSignal quickstart designs** tab.
3. Choose a design, then customize it to match your brand.

### Tested devices

These quickstart designs have been tested on:

* **iPhone 13+** (iOS)
* **Pixel 8+** (Android)

<Warning>
  Quickstart designs are not optimized for landscape mode and may not render correctly when a device is rotated. We recommend restricting your app to portrait-only orientation to ensure a consistent experience.
</Warning>

***

## HTML editor templates

Our HTML Editor lets you fully control your in-app message layout and behavior using HTML, CSS, and JavaScript. Use the copy/paste templates below to get started faster.

### How to use the templates

1. In OneSignal, go to **Messages > In-App > New In-App**.
2. Select the **HTML editor**.
3. Find a template below.
4. Copy the full HTML from the code block and paste it into the editor.
5. Update the placeholders (URLs, endpoints, dates, and copy).
6. Test on a real device, then publish.

### Available templates

<Card title="Collect Email Form" href="#email-form">
  Ask for the user's email and send it to your app via click name.
</Card>

<Card title="Collect Phone Numbers Form" href="#sms-form">
  Ask for and get consent to send SMS. Includes phone number in E.164 format and send it to your app via click name.
</Card>

<Card title="Checklist Survey" href="#checklist-survey">
  Multi-select survey you can send to your backend or convert to tags.
</Card>

<Card title="Countdown" href="#countdown">
  Countdown timer for time-sensitive promotions.
</Card>

<Card title="Promo Wheel" href="#promo-wheel">
  Spin-to-win promo experience (customize promo handling).
</Card>

<Card title="Quiz Modal" href="#quiz-modal">
  Quiz experience that can tag users with their score.
</Card>

<Card title="Ranking Survey" href="#ranking-survey">
  1–5 rating survey (send to your endpoint or tag user).
</Card>

<Card title="Audio/Video Player" href="#audio/video-player">
  Simple audio preview UI for a direct MP3 file.
</Card>

<Card title="Vertical Swiping" href="#vertical-swiping">
  Multi-slide vertical swipe onboarding or feature tour.
</Card>

***

### Email form

Gather Email [Subscriptions](./subscriptions) through an in-app message.

How this form works:

1. The user enters an email address and checks a consent box.
2. On submit, OneSignal's Create User API is called to create the email Subscription in your app.
3. Also, the template calls `OneSignalIamApi.addClickName(e, email)` which passes the email address to our SDK's In-app Message Click Listener.
4. Within your app, you can add the In-App Message Click Listener to read the click name and pass the email into our SDK's `addEmail` method.

You may notice that steps 2 and 4 both involve creating the email Subscription.

* Step 2 doesn't require adding code directly into the app while but also, doesn't add the email Subscription to the user if you called the `login` method.
* Step 4 requires additional code (the In-App Message Click Listener) but also adds the email Subscription to the user if you called the `login` method.

<Accordion title="Email Form HTML Code">
  \*\*Replace `YOUR_APP_ID` with your OneSignal App ID found in [Settings > Keys & IDs](./keys-and-ids).

  ```html theme={null}
  <!DOCTYPE html>
  <html lang="en">
  <head>
      <meta charset="UTF-8">
      <!-- Prevent iOS zoom on input focus -->
      <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
      <style>
          /* ===== RESET ===== */
          * {
              box-sizing: border-box;
              margin: 0;
              padding: 0;
          }
          
          /* ===== BASE ===== */
          body {
              font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
              background: transparent;
              display: flex;
              justify-content: center;
              align-items: center;
              min-height: 100vh;
              padding: 20px;
          }
          
          /* ===== CARD ===== */
          .container {
              position: relative;
              background: #ffffff;
              border-radius: 16px;
              padding: 32px 24px;
              max-width: 340px;
              width: 100%;
              box-shadow: 0 4px 24px rgba(0, 0, 0, 0.15);
              text-align: center;
          }
          
          /* ===== CLOSE BUTTON ===== */
          .close-btn {
              position: absolute;
              top: 12px;
              right: 12px;
              background: none;
              border: none;
              font-size: 24px;
              color: #999;
              cursor: pointer;
              padding: 4px 8px;
              line-height: 1;
          }
          
          .close-btn:hover {
              color: #333;
          }
          
          /* ===== TYPOGRAPHY ===== */
          h1 {
              font-size: 22px;
              font-weight: 600;
              color: #333;
              margin-bottom: 8px;
          }
          
          p {
              font-size: 14px;
              color: #666;
              margin-bottom: 24px;
              line-height: 1.5;
          }
          
          /* ===== EMAIL INPUT ===== */
          .email-input {
              width: 100%;
              padding: 14px 16px;
              font-size: 16px; /* 16px prevents iOS auto-zoom */
              border: 2px solid #e0e0e0;
              border-radius: 10px;
              margin-bottom: 16px;
              outline: none;
              transition: border-color 0.2s;
              touch-action: manipulation;
          }
          
          .email-input:focus {
              border-color: #007AFF;
          }
          
          .email-input::placeholder {
              color: #aaa;
          }
          
          /* ===== CONSENT CHECKBOX ===== */
          .consent-wrapper {
              display: flex;
              align-items: flex-start;
              gap: 10px;
              text-align: left;
              margin-bottom: 16px;
          }
          
          .consent-wrapper input[type="checkbox"] {
              width: 18px;
              height: 18px;
              margin-top: 2px;
              cursor: pointer;
              flex-shrink: 0;
          }
          
          .consent-wrapper label {
              font-size: 13px;
              color: #666;
              line-height: 1.4;
              cursor: pointer;
          }
          
          /* ===== SUBMIT BUTTON ===== */
          .submit-btn {
              width: 100%;
              padding: 14px 24px;
              font-size: 16px;
              font-weight: 600;
              color: #fff;
              background: #007AFF;
              border: none;
              border-radius: 10px;
              cursor: pointer;
              transition: background 0.2s, opacity 0.2s;
          }
          
          .submit-btn:hover {
              background: #0056b3;
          }
          
          .submit-btn:disabled {
              background: #ccc;
              cursor: not-allowed;
              opacity: 0.7;
          }
          
          /* ===== STATUS MESSAGES ===== */
          .error-msg,
          .success-msg {
              font-size: 12px;
              margin-top: -12px;
              margin-bottom: 12px;
              display: none;
          }
          
          .error-msg {
              color: #e53935;
          }

          .success-msg {
              color: #4CAF50;
              font-size: 14px;
          }
          
          /* ===== LOADING STATE ===== */
          .loading {
              pointer-events: none;
              opacity: 0.7;
          }
      </style>
  </head>
  <body>
      <div class="container">
          <!-- Close Button -->
          <button id="close-btn" class="close-btn" data-onesignal-unique-label="close-button">×</button>
          
          <!-- Header -->
          <h1>Stay Connected!</h1>
          <p>Enter your email to receive updates and exclusive offers. You can unsubscribe anytime!</p>
          
          <!-- Email Input -->
          <input 
              type="email" 
              id="email-input" 
              class="email-input" 
              placeholder="you@example.com"
              autocomplete="email"
              autocapitalize="off"
          >
          
          <!-- Status Messages -->
          <p id="error-msg" class="error-msg">Please enter a valid email address</p>
          <p id="success-msg" class="success-msg">Thanks for subscribing!</p>
          
          <!-- Consent Checkbox -->
          <div class="consent-wrapper">
              <input type="checkbox" id="consent-checkbox" name="consent">
              <label for="consent-checkbox">I agree to receive marketing emails</label>
          </div>
          
          <!-- Submit Button -->
          <button id="submit-btn" class="submit-btn" data-onesignal-unique-label="submit-email" disabled>
              Subscribe
          </button>
      </div>

      <script>
          document.addEventListener("DOMContentLoaded", function() {
              
              // ===== DOM REFERENCES =====
              var emailInput = document.getElementById("email-input");
              var submitBtn = document.getElementById("submit-btn");
              var closeBtn = document.getElementById("close-btn");
              var errorMsg = document.getElementById("error-msg");
              var successMsg = document.getElementById("success-msg");
              var consentCheckbox = document.getElementById("consent-checkbox");
              
              // ===== HELPER FUNCTIONS =====
              
              // Validate email format
              function isValidEmail(email) {
                  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
              }
              
              // Enable submit button only when email is valid AND consent is checked
              function updateSubmitState() {
                  var email = emailInput.value.trim();
                  submitBtn.disabled = !(isValidEmail(email) && consentCheckbox.checked);
              }
              
              // Create email subscription via OneSignal API
              async function createOneSignalUser(email) {
                  // ⚠️ Replace with your OneSignal App ID
                  var appId = "YOUR_APP_ID";
                  var url = "https://api.onesignal.com/apps/" + appId + "/users";
                  
                  var payload = {
                      properties: {
                          tags: { email_created_from: "iam" },
                          language: "en"
                      },
                      subscriptions: [{
                          type: "Email",
                          token: email,
                          enabled: true
                      }]
                  };
                  
                  var response = await fetch(url, {
                      method: "POST",
                      headers: { "Content-Type": "application/json" },
                      body: JSON.stringify(payload)
                  });
                  
                  if (!response.ok) throw new Error("API request failed");
                  return response.json();
              }
              
              // ===== EVENT LISTENERS =====
              
              // Close button - dismiss IAM
              closeBtn.addEventListener("click", function(e) {
                  OneSignalIamApi.close(e);
              });
              
              // Checkbox - update button state
              consentCheckbox.addEventListener("change", updateSubmitState);
              
              // Email input - update button state and hide errors
              emailInput.addEventListener("input", function() {
                  errorMsg.style.display = "none";
                  updateSubmitState();
              });
              
              // Email input - submit on Enter key
              emailInput.addEventListener("keypress", function(e) {
                  if (e.key === "Enter" && !submitBtn.disabled) {
                      submitBtn.click();
                  }
              });
              
              // Submit button - handle subscription
              submitBtn.addEventListener("click", async function(e) {
                  var email = emailInput.value.trim();
                  
                  if (!isValidEmail(email) || !consentCheckbox.checked) {
                      errorMsg.textContent = "Please enter a valid email address";
                      errorMsg.style.display = "block";
                      return;
                  }
                  
                  // Pass email to OneSignal click handler (must be called synchronously)
                  OneSignalIamApi.addClickName(e, email);
                  
                  // Show loading state
                  errorMsg.style.display = "none";
                  submitBtn.textContent = "Subscribing...";
                  submitBtn.classList.add("loading");
                  
                  try {
                      await createOneSignalUser(email);
                      
                      // Success - show message and auto-close
                      successMsg.style.display = "block";
                      submitBtn.textContent = "Subscribed!";
                      
                      setTimeout(function() {
                          closeBtn.click();
                      }, 1500);
                      
                  } catch (error) {
                      // Error - reset and show message
                      submitBtn.textContent = "Subscribe";
                      submitBtn.classList.remove("loading");
                      errorMsg.textContent = "Something went wrong. Please try again.";
                      errorMsg.style.display = "block";
                  }
              });
          });
      </script>
  </body>
  </html>
  ```
</Accordion>

**Required for step 4:**

1. Keep the [addClickName](./in-app-message-api#click-name) call in your HTML submit handler.
2. Read the input with our SDK's [In-app Message Click Listener](./mobile-sdk-reference#addclicklistener-in-app)
3. When the click name looks like an email, call the [addEmail](./mobile-sdk-reference#addemail-,-removeemail) method within the in-app message click listener.

**Example using the in-app message click listener and addEmail method:**

```swift theme={null}
// Example In-App Message Click Handler to capture email and phone from HTML in-app messages
class InAppMessageClickHandler: NSObject, OSInAppMessageClickListener {
    func onClick(event: OSInAppMessageClickEvent) {
        // Get the click name (action ID) from the event
        let clickName = event.result.actionId
        print("In-App Message clicked with actionId: \(clickName ?? "nil")")
        
        guard let value = clickName else { return }
        
        // Check if the click name looks like an email address
        if value.contains("@") && value.contains(".") {
            OneSignal.User.addEmail(value)
            print("Email added to OneSignal: \(value)")
        }
        // Check if the click name looks like a phone number in E.164 format (+1XXXXXXXXXX)
        else if value.hasPrefix("+") && value.count >= 11 {
            OneSignal.User.addSms(value)
            print("SMS added to OneSignal: \(value)")
        }
    }
}
```

***

### SMS form

Gather SMS [Subscriptions](./subscriptions) through an in-app message.

How this form works:

1. The user selects their country code, enters a 10-digit number, and checks a consent box.
2. On submit, OneSignal's Create User API is called to create the SMS Subscription in your app.
3. Also, the template calls `OneSignalIamApi.addClickName(e, e164Phone)` which passes the phone number to our SDK's In-app Message Click Listener.
4. Within your app, you can add the In-App Message Click Listener to read the click name and pass the phone number into our SDK's `addSms` method.

You may notice that steps 2 and 4 both involve creating the SMS Subscription.

* Step 2 doesn't require adding code directly into the app but also, doesn't add the SMS Subscription to the user if you called the `login` method.
* Step 4 requires additional code (the In-App Message Click Listener) but also adds the SMS Subscription to the user if you called the `login` method.

<Accordion title="SMS Form HTML Code">
  \*\*Replace `YOUR_APP_ID` with your OneSignal App ID found in [Settings > Keys & IDs](./keys-and-ids).

  ```html theme={null}
  <!DOCTYPE html>
  <html lang="en">
  <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
      <style>
          /* ===== RESET ===== */
          * {
              box-sizing: border-box;
              margin: 0;
              padding: 0;
          }
          
          /* ===== BASE ===== */
          body {
              font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
              background: transparent;
              display: flex;
              justify-content: center;
              align-items: center;
              min-height: 100vh;
              padding: 20px;
          }
          
          /* ===== CARD ===== */
          .container {
              position: relative;
              background: #ffffff;
              border-radius: 16px;
              padding: 32px 24px;
              max-width: 340px;
              width: 100%;
              box-shadow: 0 4px 24px rgba(0, 0, 0, 0.15);
              text-align: center;
              overflow: hidden;
          }
          
          /* ===== CLOSE BUTTON ===== */
          .close-btn {
              position: absolute;
              top: 12px;
              right: 12px;
              background: none;
              border: none;
              font-size: 24px;
              color: #999;
              cursor: pointer;
              padding: 4px 8px;
              line-height: 1;
          }
          
          .close-btn:hover {
              color: #333;
          }
          
          /* ===== TYPOGRAPHY ===== */
          h1 {
              font-size: 22px;
              font-weight: 600;
              color: #333;
              margin-bottom: 8px;
          }
          
          p {
              font-size: 14px;
              color: #666;
              margin-bottom: 24px;
              line-height: 1.5;
          }
          
          /* ===== PHONE INPUT ===== */
          .phone-input-wrapper {
              display: flex;
              align-items: center;
              gap: 8px;
              margin-bottom: 16px;
              width: 100%;
          }
          
          .country-select {
              display: flex;
              align-items: center;
              padding: 14px 8px;
              background: #f5f5f5;
              border: 2px solid #e0e0e0;
              border-radius: 10px;
              font-size: 14px;
              color: #333;
              flex-shrink: 0;
              cursor: pointer;
              outline: none;
              appearance: none;
              -webkit-appearance: none;
              background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'%3E%3Cpath fill='%23666' d='M6 8L1 3h10z'/%3E%3C/svg%3E");
              background-repeat: no-repeat;
              background-position: right 8px center;
              padding-right: 24px;
          }
          
          .country-select:focus {
              border-color: #007AFF;
          }
          
          .phone-input {
              flex: 1;
              min-width: 0;
              padding: 14px 12px;
              font-size: 16px;
              border: 2px solid #e0e0e0;
              border-radius: 10px;
              outline: none;
              transition: border-color 0.2s;
              width: 100%;
              touch-action: manipulation;
          }
          
          .phone-input:focus {
              border-color: #007AFF;
          }
          
          .phone-input::placeholder {
              color: #aaa;
          }
          
          /* ===== CONSENT CHECKBOX ===== */
          .consent-wrapper {
              display: flex;
              align-items: flex-start;
              gap: 10px;
              text-align: left;
              margin-bottom: 16px;
          }
          
          .consent-wrapper input[type="checkbox"] {
              width: 18px;
              height: 18px;
              margin-top: 2px;
              cursor: pointer;
              flex-shrink: 0;
          }
          
          .consent-wrapper label {
              font-size: 13px;
              color: #666;
              line-height: 1.4;
              cursor: pointer;
          }
          
          /* ===== SUBMIT BUTTON ===== */
          .submit-btn {
              width: 100%;
              padding: 14px 24px;
              font-size: 16px;
              font-weight: 600;
              color: #fff;
              background: #007AFF;
              border: none;
              border-radius: 10px;
              cursor: pointer;
              transition: background 0.2s, opacity 0.2s;
          }
          
          .submit-btn:hover {
              background: #0056b3;
          }
          
          .submit-btn:disabled {
              background: #ccc;
              cursor: not-allowed;
              opacity: 0.7;
          }
          
          /* ===== STATUS MESSAGES ===== */
          .error-msg,
          .success-msg {
              font-size: 12px;
              margin-top: -12px;
              margin-bottom: 12px;
              display: none;
          }
          
          .error-msg {
              color: #e53935;
          }

          .success-msg {
              color: #4CAF50;
              font-size: 14px;
          }
          
          /* ===== LOADING STATE ===== */
          .loading {
              pointer-events: none;
              opacity: 0.7;
          }
      </style>
  </head>
  <body>
      <div class="container">
          <!-- Close Button -->
          <button id="close-btn" class="close-btn" data-onesignal-unique-label="close-button">×</button>
          
          <!-- Header -->
          <h1>Stay Connected</h1>
          <p>Enter your phone number to receive updates and exclusive offers via SMS.</p>
          
          <!-- Phone Input with Country Selector -->
          <div class="phone-input-wrapper">
              <select id="country-select" class="country-select">
                  <option value="+1" data-length="10">🇺🇸 +1</option>
                  <option value="+1" data-length="10">🇨🇦 +1</option>
                  <option value="+44" data-length="10">🇬🇧 +44</option>
                  <option value="+61" data-length="9">🇦🇺 +61</option>
                  <option value="+49" data-length="11">🇩🇪 +49</option>
                  <option value="+33" data-length="9">🇫🇷 +33</option>
                  <option value="+34" data-length="9">🇪🇸 +34</option>
                  <option value="+39" data-length="10">🇮🇹 +39</option>
                  <option value="+81" data-length="10">🇯🇵 +81</option>
                  <option value="+86" data-length="11">🇨🇳 +86</option>
                  <option value="+91" data-length="10">🇮🇳 +91</option>
                  <option value="+52" data-length="10">🇲🇽 +52</option>
                  <option value="+55" data-length="11">🇧🇷 +55</option>
              </select>
              <input 
                  type="tel" 
                  id="phone-input" 
                  class="phone-input" 
                  placeholder="(555) 867-5309"
                  autocomplete="tel"
                  inputmode="numeric"
              >
          </div>
          
          <!-- Status Messages -->
          <p id="error-msg" class="error-msg">Please enter a valid phone number</p>
          <p id="success-msg" class="success-msg">Thanks for subscribing!</p>
          
          <!-- Consent Checkbox -->
          <div class="consent-wrapper">
              <input type="checkbox" id="consent-checkbox" name="consent">
              <label for="consent-checkbox">I agree to receive marketing text messages from [COMPANY NAME]. Message frequency varies. Message & data rates may apply. Reply STOP to unsubscribe. View our Privacy Policy and Terms of Service.</label>
          </div>
          
          <!-- Submit Button -->
          <button id="submit-btn" class="submit-btn" data-onesignal-unique-label="submit-phone" disabled>
              Subscribe
          </button>
      </div>

      <script>
          document.addEventListener("DOMContentLoaded", function() {
              
              // ===== DOM REFERENCES =====
              var phoneInput = document.getElementById("phone-input");
              var countrySelect = document.getElementById("country-select");
              var submitBtn = document.getElementById("submit-btn");
              var closeBtn = document.getElementById("close-btn");
              var errorMsg = document.getElementById("error-msg");
              var successMsg = document.getElementById("success-msg");
              var consentCheckbox = document.getElementById("consent-checkbox");
              
              // ===== HELPER FUNCTIONS =====
              
              // Get expected phone length for selected country
              function getExpectedLength() {
                  var selected = countrySelect.options[countrySelect.selectedIndex];
                  return parseInt(selected.getAttribute("data-length")) || 10;
              }
              
              // Extract digits only from input
              function getDigitsOnly(value) {
                  return value.replace(/\D/g, "");
              }
              
              // Format phone number as user types (US format for +1, generic for others)
              function formatPhoneNumber(value) {
                  var digits = getDigitsOnly(value);
                  var countryCode = countrySelect.value;
                  var maxLength = getExpectedLength();
                  
                  digits = digits.substring(0, maxLength);
                  
                  // US/Canada formatting
                  if (countryCode === "+1") {
                      if (digits.length === 0) return "";
                      if (digits.length <= 3) return digits;
                      if (digits.length <= 6) return "(" + digits.substring(0, 3) + ") " + digits.substring(3);
                      return "(" + digits.substring(0, 3) + ") " + digits.substring(3, 6) + "-" + digits.substring(6);
                  }
                  
                  // Generic formatting for other countries (groups of 3-4)
                  if (digits.length === 0) return "";
                  if (digits.length <= 4) return digits;
                  if (digits.length <= 7) return digits.substring(0, 4) + " " + digits.substring(4);
                  return digits.substring(0, 4) + " " + digits.substring(4, 7) + " " + digits.substring(7);
              }
              
              // Convert to E.164 format
              function toE164(value) {
                  var digits = getDigitsOnly(value);
                  var countryCode = countrySelect.value;
                  return countryCode + digits;
              }
              
              // Validate phone number
              function isValidPhone(value) {
                  var digits = getDigitsOnly(value);
                  var expectedLength = getExpectedLength();
                  return digits.length === expectedLength;
              }
              
              // Enable submit only when phone is valid AND consent is checked
              function updateSubmitState() {
                  var phone = phoneInput.value.trim();
                  submitBtn.disabled = !(isValidPhone(phone) && consentCheckbox.checked);
              }
              
              // Create SMS subscription via OneSignal API
              async function createOneSignalUser(phone) {
                  // ⚠️ Replace with your OneSignal App ID
                  var appId = "YOUR_APP_ID";
                  var url = "https://api.onesignal.com/apps/" + appId + "/users";
                  
                  var payload = {
                      properties: {
                          tags: { sms_created_from: "iam" },
                          language: "en"
                      },
                      subscriptions: [{
                          type: "SMS",
                          token: phone,
                          enabled: true
                      }]
                  };
                  
                  var response = await fetch(url, {
                      method: "POST",
                      headers: { "Content-Type": "application/json" },
                      body: JSON.stringify(payload)
                  });
                  
                  if (!response.ok) throw new Error("API request failed");
                  return response.json();
              }
              
              // ===== EVENT LISTENERS =====
              
              // Close button - dismiss IAM
              closeBtn.addEventListener("click", function(e) {
                  OneSignalIamApi.close(e);
              });
              
              // Country selector - update placeholder and reformat input
              countrySelect.addEventListener("change", function() {
                  var countryCode = countrySelect.value;
                  
                  // Update placeholder based on country
                  if (countryCode === "+1") {
                      phoneInput.placeholder = "(555) 867-5309";
                  } else {
                      phoneInput.placeholder = "Enter phone number";
                  }
                  
                  // Reformat existing input
                  phoneInput.value = formatPhoneNumber(phoneInput.value);
                  updateSubmitState();
              });
              
              // Phone input - format as user types
              phoneInput.addEventListener("input", function() {
                  var cursorPosition = phoneInput.selectionStart;
                  var oldLength = phoneInput.value.length;
                  
                  phoneInput.value = formatPhoneNumber(phoneInput.value);
                  
                  // Adjust cursor position
                  var newLength = phoneInput.value.length;
                  var newPosition = cursorPosition + (newLength - oldLength);
                  phoneInput.setSelectionRange(newPosition, newPosition);
                  
                  errorMsg.style.display = "none";
                  updateSubmitState();
              });
              
              // Checkbox - update button state
              consentCheckbox.addEventListener("change", updateSubmitState);
              
              // Phone input - submit on Enter key
              phoneInput.addEventListener("keypress", function(e) {
                  if (e.key === "Enter" && !submitBtn.disabled) {
                      submitBtn.click();
                  }
              });
              
              // Submit button - handle subscription
              submitBtn.addEventListener("click", async function(e) {
                  var phone = phoneInput.value.trim();
                  
                  if (!isValidPhone(phone) || !consentCheckbox.checked) {
                      errorMsg.textContent = "Please enter a valid phone number";
                      errorMsg.style.display = "block";
                      return;
                  }
                  
                  // Convert to E.164 and pass to OneSignal click handler (must be synchronous)
                  var e164Phone = toE164(phone);
                  OneSignalIamApi.addClickName(e, e164Phone);
                  
                  // Show loading state
                  errorMsg.style.display = "none";
                  submitBtn.textContent = "Subscribing...";
                  submitBtn.classList.add("loading");
                  
                  try {
                      await createOneSignalUser(e164Phone);
                      
                      // Success - show message and auto-close
                      successMsg.style.display = "block";
                      submitBtn.textContent = "Subscribed!";
                      
                      setTimeout(function() {
                          closeBtn.click();
                      }, 1500);
                      
                  } catch (error) {
                      // Error - reset and show message
                      submitBtn.textContent = "Subscribe";
                      submitBtn.classList.remove("loading");
                      errorMsg.textContent = "Something went wrong. Please try again.";
                      errorMsg.style.display = "block";
                  }
              });
          });
      </script>
  </body>
  </html>
  ```
</Accordion>

**Required for step 4:**

1. Keep the [addClickName](./in-app-message-api#click-name) call in your HTML submit handler.
2. Read the input with our SDK's [In-app Message Click Listener](./mobile-sdk-reference#addclicklistener-in-app)
3. When the click name is an E.164 number, call the [addSms](./mobile-sdk-reference#addsms-,-removesms) method within the in-app message click listener.

**Example using the in-app message click listener and addSms method:**

```swift theme={null}
// In-App Message Click Handler to capture email and phone from HTML in-app messages
class InAppMessageClickHandler: NSObject, OSInAppMessageClickListener {
    func onClick(event: OSInAppMessageClickEvent) {
        // Get the click name (action ID) from the event
        let clickName = event.result.actionId
        print("In-App Message clicked with actionId: \(clickName ?? "nil")")
        
        guard let value = clickName else { return }
        
        // Check if the click name looks like an email address
        if value.contains("@") && value.contains(".") {
            OneSignal.User.addEmail(value)
            print("Email added to OneSignal: \(value)")
        }
        // Check if the click name looks like a phone number in E.164 format (+1XXXXXXXXXX)
        else if value.hasPrefix("+") && value.count >= 11 {
            OneSignal.User.addSms(value)
            print("SMS added to OneSignal: \(value)")
        }
    }
}
```

***

### Checklist survey

Multi-select survey that posts results to your backend.

* Set your endpoint in `handleSurveyAnswer()`.
* Update checkbox `name` values and labels to match your question.

<Note>
  If you leave `var url = ""`, the request will fail. Set a real endpoint or replace `fetch()` with tagging (example below).
</Note>

<Accordion title="HTML Code">
  ```html theme={null}
  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta http-equiv="X-UA-Compatible" content="ie=edge" />
      <title>Onesignal In-App Message</title>
      <!-- Google Fonts -->
      <link rel="preconnect" href="https://fonts.googleapis.com" />
      <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
      <link
        href="https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@500;700&family=Raleway:wght@500;700&display=swap"
        rel="stylesheet"
      />
      <style>
        * {
          box-sizing: border-box;
        }

        body {
          margin: 0;
          padding-top: var(--safe-area-inset-top);
          padding-right: var(--safe-area-inset-right);
          padding-bottom: calc(var(--safe-area-inset-bottom) + 20px);
          padding-left: var(--safe-area-inset-left);
          font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
            Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
          display: flex;
          align-items: center;
        }

        .center-modal {
          position: relative;
          background: #fae8cd;
          margin: 18px;
          border-radius: 8px;

          display: flex;
          flex-direction: column;
          justify-content: center;
          height: 85%;
          max-height: 640px;
          width: 100%;
          box-shadow: rgb(0 0 0 / 30%) 0px 0px 12.5px,
            rgb(0 0 0 / 15%) 0px 0px 2.5px;
        }

        .center-modal .close-button {
          position: absolute;
          top: 10;
          right: 10;
          background: rgba(255, 255, 255, 0.5);
          border: none;
          z-index: 1;
          display: flex;
          justify-content: center;
          flex-direction: column;
          align-items: center;
          /* Tip: Make your close-button relatively large so it's easy to click */
          min-width: 36px;
          min-height: 36px;
          border-radius: 50%;
        }

        .center-modal .headings {
          padding: 24px 24px 0 24px;
        }

        .center-modal h1 {
          margin: 32px 0 0 0;
          color: #222;
          text-decoration: none;
          font-family: Raleway;
          font-size: 24px;
          font-weight: 700;
          line-height: 28px;
          letter-spacing: 0px;
          text-align: left;
        }

        .center-modal h2 {
          font-family: Raleway;
          font-size: 16px;
          font-weight: 500;
          line-height: 24px;
          letter-spacing: 0px;
          text-align: left;
          color: #73777b;
        }

        form {
          overflow: auto;
          padding-bottom: 53px;
        }

        form div {
          display: flex;
          justify-content: flex-start;
          align-items: center;
          padding: 12px;
          gap: 8px;
          background: #ffffff;
          border-radius: 8px;
          border: none;
          margin: 12px 24px;
        }

        form input[type="checkbox"] {
          /* Add if not using autoprefixer */
          -webkit-appearance: none;
          outline: none !important;
          appearance: none;
          /* For iOS < 15 to remove gradient background */
          background-color: #fff;
          /* Not removed via appearance */
          margin-right: 6px;
          font: inherit;
          color: currentColor;
          width: 1.15em;
          height: 1.15em;
          border: 0.15em solid #cbd1d7;
          border-radius: 0.15em;
          transform: translateY(-0.075em);
          display: grid;
          place-content: center;
        }

        input[type="checkbox"]::before {
          content: "";
          width: 0.65em;
          height: 0.65em;
          transform: scale(0);
          transition: 120ms transform ease-in-out;
          box-shadow: inset 1em 1em #33717a;
          transform-origin: bottom left;
          clip-path: polygon(14% 44%, 0 65%, 50% 100%, 100% 16%, 80% 0%, 43% 62%);
        }

        input[type="checkbox"]:checked::before {
          transform: scale(1);
        }

        form input[type="submit"] {
          color: #fff;
          position: absolute;
          bottom: 0;
          width: 100%;
          left: 0;
          height: 70px;
          border: none;
          background: #28333e;

          font-family: "Raleway";
          font-style: normal;
          font-weight: 500;
          font-size: 18px;
          line-height: 21px;
        }

        .flex-container {
          display: flex;
          flex-direction: column;
        }

        @media screen and (min-width: 480px) {
          .flex-container {
            flex-direction: row;
            grid-gap: 12px;
            width: 100%;
          }
        }
      </style>
    </head>

    <body>
      <div class="center-modal">
        <div class="close-button" data-onesignal-unique-label="close-button">
          <svg
            width="10"
            height="10"
            preserveAspectRatio="none"
            viewBox="0 0 8 8"
            fill="none"
            xmlns="http://www.w3.org/2000/svg"
          >
            <path
              d="M7.80309 1.14768C8.06564 0.885137 8.06564 0.459453 7.80309 0.196909C7.54055 -0.0656362 7.11486 -0.0656362 6.85232 0.196909L4 3.04923L1.14768 0.196909C0.885137 -0.0656362 0.459453 -0.0656362 0.196909 0.196909C-0.0656362 0.459453 -0.0656362 0.885137 0.196909 1.14768L3.04923 4L0.196909 6.85232C-0.0656362 7.11486 -0.0656362 7.54055 0.196909 7.80309C0.459453 8.06564 0.885137 8.06564 1.14768 7.80309L4 4.95077L6.85232 7.80309C7.11486 8.06564 7.54055 8.06564 7.80309 7.80309C8.06564 7.54055 8.06564 7.11486 7.80309 6.85232L4.95077 4L7.80309 1.14768Z"
              fill="#111111"
            />
          </svg>
        </div>
        <div class="headings">
          <h1>Any allergies?</h1>
          <h2>Get better recommendations and other customized experience</h2>
        </div>
        <form>
          <div>
            <input type="checkbox" name="dairy" />
            <label for="dairy">Dairy</label>
          </div>
          <div>
            <input type="checkbox" name="eggs" />
            <label for="eggs">Eggs</label>
          </div>
          <div>
            <input type="checkbox" name="treeNuts"/>
            <label for="treeNuts">Tree Nuts</label>
          </div>
          <div>
            <input type="checkbox" name="shellfish" />
            <label for="shellfish">Shellfish</label>
          </div>
          <div>
            <input type="checkbox" name="wheat" />
            <label for="wheat">Wheat</label>
          </div>
          <div>
            <input type="checkbox" name="peanuts" />
            <label for="peanuts">Peanuts</label>
          </div>
          <div>
            <input type="checkbox" name="soy" />
            <label for="soy">Soy</label>
          </div>
          <div>
            <input type="checkbox" name="seafood" />
            <label for="seafood">Seafood</label>
          </div>
          <div>
            <input type="checkbox" name="sesame" />
            <label for="sesame">Sesame</label>
          </div>
          <div>
            <input type="checkbox" name="gluten" />
            <label for="gluten">Gluten</label>
          </div>
          <input type="submit" data-onesignal-unique-label="submit-button" />
        </form>
      </div>
      <script>
        if (iamInfo) {
          iamInfo.shouldVerticalDragDismissMessage = false;
        }
        // Your code here
        document
          .querySelector(".close-button")
          .addEventListener("click", function (e) {
            OneSignalIamApi.close(e);
          });

        document.querySelectorAll("input[type=checkbox").forEach(function (node) {
          node.addEventListener("click", function (e) {
            if (e.target.checked) {
              e.target.parentElement.style["background-color"] = "#33717A";
              e.target.parentElement.style["color"] = "#FFF";
              e.target.style["border"] = "none";
            } else {
              e.target.removeAttribute("style");
              e.target.parentElement.removeAttribute("style");
            }
          });
        });

        function handleSurveyAnswer(answers) {
          // Add your own survey api endpoint url here
          var url = "";
          var options = {
            method: "POST",
            headers: {
              Accept: "application/json",
              "Content-Type": "application/json",
            },
            body: JSON.stringify({
              value: answers,
            }),
          };
          fetch(url, options)
            .then((response) => response.json())
            .then((response) => console.log(response))
            .catch((err) => console.error(err));
        }

        document.querySelector("form").addEventListener("submit", function (e) {
          e.preventDefault();
          e.stopPropagation();
          var answers = {
            dairy: e.target.dairy.checked,
            eggs: e.target.eggs.checked,
            treeNuts: e.target.treeNuts.checked,
            shellfish: e.target.shellfish.checked,
            wheat: e.target.wheat.checked,
            peanuts: e.target.peanuts.checked,
            soy: e.target.soy.checked,
            seafood: e.target.seafood.checked,
            sesame: e.target.sesame.checked,
            gluten: e.target.gluten.checked,
          };
          handleSurveyAnswer(answers);
          OneSignalIamApi.close(e);
        });
      </script>
    </body>
  </html>
  ```
</Accordion>

**Optional: tag users instead of calling your backend**

Replace the `handleSurveyAnswer(answers)` call in the submit handler with:

```javascript theme={null}
OneSignalIamApi.tagUser(e, {
  allergies: JSON.stringify(answers)
});
```

***

### Countdown

Create urgency with a countdown timer for limited-time offers and promotions. Customize the end date and redirect URL to match your campaign.

* Update `endtime` to a future date/time.
* Update `openUrl` destination URL.

<Warning>
  The sample `endtime` in this template is in the past (`Mar 25, 2025`). If you don’t update it, users will immediately hit the “ended” logic.
</Warning>

<Accordion title="HTML Code">
  ```html theme={null}
  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <link
        rel="stylesheet"
        href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"
      />

      <meta http-equiv="X-UA-Compatible" content="ie=edge" />
      <title>Onesignal In-App Message</title>
      <style>
    body {
      margin: 0;
      padding-top: var(--safe-area-inset-top);
      padding-right: var(--safe-area-inset-right);
      padding-bottom: calc(var(--safe-area-inset-bottom) + 20px);
      padding-left: var(--safe-area-inset-left);
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
      display: flex;
      align-items: center;
    }

    .container {
      color: red;
      text-align: center;
      padding-right: 10%;
    }

    li {
      display: inline-block;
      font-size: 12px;
      list-style-type: none;
      text-transform: uppercase;
    }

    li span {
      display: block;
      font-size: 20px;
    }

    .center-modal {
      position: relative;
      background: #FFF;
      margin: 18px;
      padding: 24px;
      border-radius: 8px;
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      height: 45%;
      width: 100%;
      box-shadow: rgb(0 0 0 / 30%) 0px 0px 12.5px, rgb(0 0 0 / 15%) 0px 0px 2.5px;
    }

    .center-modal .close-button {
      position: absolute;
      top: 0;
      right: 0;
      background: rgba(0, 0, 0, 0);
      border: none;
      z-index: 1;
      display: flex;
      justify-content: center;
      flex-direction: column;
      align-items: center;
      /* Tip: Make your close-button relatively large so it's easy to click */
      min-width: 48px;
      min-height: 48px;
    }

    .center-modal h1 {
      margin: 0;
      margin-bottom: 12px;
      color: #222;
      font-size: 24px;
      font-style: normal;
      font-weight: normal;
      text-align: center;
      text-decoration: none;
    }

    .center-modal button {
      font-size: 16px;
      color: #fff;
      background-color: #1F8FEB;
      width: 100%;
      padding: 12px;
      border-radius: 4px;
      border: none;
      margin-bottom: 12px;
    }

    .button-container {
      display: flex;
      flex-direction: column;
    }

    @media screen and (min-width: 480px) {
      .button-container {
        flex-direction: row;
        grid-gap: 12px;
        padding-left: 20%;
        width: 40%;
      }

      .button-column {
        width: 50%;
      }

      .center-modal {
        height: 80%;
      }
    }
  </style>
    </head>

    <body>
      <div class="center-modal">
        <div class="close-button" data-onesignal-unique-label="close-button">
          <svg
            width="10"
            height="10"
            preserveAspectRatio="none"
            viewBox="0 0 8 8"
            fill="none"
            xmlns="http://www.w3.org/2000/svg"
          >
            <path
              d="M7.80309 1.14768C8.06564 0.885137 8.06564 0.459453 7.80309 0.196909C7.54055 -0.0656362 7.11486 -0.0656362 6.85232 0.196909L4 3.04923L1.14768 0.196909C0.885137 -0.0656362 0.459453 -0.0656362 0.196909 0.196909C-0.0656362 0.459453 -0.0656362 0.885137 0.196909 1.14768L3.04923 4L0.196909 6.85232C-0.0656362 7.11486 -0.0656362 7.54055 0.196909 7.80309C0.459453 8.06564 0.885137 8.06564 1.14768 7.80309L4 4.95077L6.85232 7.80309C7.11486 8.06564 7.54055 8.06564 7.80309 7.80309C8.06564 7.54055 8.06564 7.11486 7.80309 6.85232L4.95077 4L7.80309 1.14768Z"
              fill="#111111"
            />
          </svg>
        </div>

        <!-- Add notification details below -->


        <h2>Offer Ends Soon!</h2>
        <h1>50% OFF</h1>

        <div class="container">
          <div id="countdown">
            <ul>
              <li><span id="days"></span>Days</li>
              <li><span id="hours"></span>Hours</li>
              <li><span id="minutes"></span>Minutes</li>
              <li><span id="seconds"></span>Seconds</li>
            </ul>
          </div>
        </div>

        <br />

        <div class="button-container">
          <div class="button-column">
            <button
              class="open-url"
              data-onesignal-unique-label="my-open-url-button"
            >
              Register Today!
            </button>
          </div>
        </div>
      </div>

      <script>
    (function() {
      const second = 1000,
        minute = second * 60,
        hour = minute * 60,
        day = hour * 24;

      // Set the date and time below to which the in-app should countdown towards
      let endtime = "Mar 25, 2025 00:00:00";
      let countDown = new Date(endtime).getTime();

      const x = setInterval(function() {
        const now = new Date().getTime();
        const distance = countDown - now;

        document.getElementById("days").innerText = Math.floor(distance / day);
        document.getElementById("hours").innerText = Math.floor((distance % day) / hour);
        document.getElementById("minutes").innerText = Math.floor((distance % hour) / minute);
        document.getElementById("seconds").innerText = Math.floor((distance % minute) / second);

        // Action when end date/time is reached
        if (distance < 0) {
          const headline = document.getElementById("headline");
          const countdown = document.getElementById("countdown");
          const content = document.getElementById("content");

          headline.innerText = "This offer has ended..";
          countdown.style.display = "none";
          content.style.display = "block";

          clearInterval(x);
        }
      }, 1000);

      // Close the in-app message
      document.querySelector(".close-button").addEventListener("click", function(e) {
        OneSignalIamApi.close(e);
      });

      // Change the URL below to the URL which you would like to redirect users to
      document.querySelector(".open-url").addEventListener("click", function(e) {
        OneSignalIamApi.openUrl(e, "https://documentation.onesignal.com/docs/in-app-js-library");
      });
    })();
  </script>

    </body>
  </html>
  ```
</Accordion>

***

### Promo wheel

Spin-to-win promotion with a random outcome.

* Replace hardcoded promo codes with server-generated or validated codes.
* Add your “Shop Now” URL or action.

<Warning> Client-side randomness and hardcoded codes are easy to abuse. If a promo has value, generate/validate it server-side. </Warning>

<Accordion title="HTML Code">
  ```html theme={null}
  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta http-equiv="X-UA-Compatible" content="ie=edge" />
      <title>Onesignal In-App Message</title>
      <!-- Google Fonts -->
      <link rel="preconnect" href="https://fonts.googleapis.com" />
      <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
      <link
        href="https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@400;700&family=Raleway:wght@500;600&display=swap"
        rel="stylesheet"
      />
      <!-- CSS Reset -->
      <link
        href="https://cdnjs.cloudflare.com/ajax/libs/meyer-reset/2.0/reset.min.css"
        rel="stylesheet"
      />
      <!-- Google Fonts -->
      <link rel="preconnect" href="https://fonts.googleapis.com" />
      <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
      <link
        href="https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@500;700&family=Raleway:wght@500;700&display=swap"
        rel="stylesheet"
      />
      <style>
        body {
          margin: 0;
          font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
            Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
          display: flex;
          align-items: center;
          background: #e5e8eb;
          padding-top: var(--safe-area-inset-top);
          padding-right: var(--safe-area-inset-right);
          padding-bottom: calc(var(--safe-area-inset-bottom) + 20px);
          padding-left: var(--safe-area-inset-left);
          background: #f1eee9;
        }

        .close-button {
          position: absolute;
          top: 30;
          right: 15;
          background: rgba(0, 0, 0, 0);
          border: none;
          z-index: 1;
          display: flex;
          justify-content: center;
          flex-direction: column;
          align-items: center;
          /* Tip: Make your close-button relatively large so it's easy to click */
          min-width: 48px;
          min-height: 48px;
        }

        .flex-container {
          width: 100%;
          display: flex;
          flex-direction: column;
          align-items: center;
          justify-content: center;
          gap: 12px;
        }

        h1 {
          font-family: "Raleway";
          font-style: normal;
          font-weight: 700;
          font-size: 36px;
          line-height: 42px;
          display: flex;
          align-items: center;
          text-align: center;
          color: #051b2c;
        }

        h2 {
          font-family: "Raleway";
          font-style: normal;
          font-weight: 500;
          font-size: 16px;
          line-height: 24px;
          display: flex;
          align-items: center;
          text-align: center;
          color: #28333e;
          max-width: 270px;
          margin-bottom: 36px;
        }

        .wheel-container {
          position: relative;
          margin-bottom: 48px;
          height: calc(286px + (2 * 6px));
        }

        .stopper {
          position: absolute;
          top: 8px;
          z-index: 1;
          left: 62px;
          transform: rotate(323deg);
        }

        .wheel-container .promo-code-code-message {
          display: none;
          position: relative;
          top: calc(-286px - (2 * 6px));
          z-index: 1;
          /* display flex will be applied via javascript */
          flex-direction: column;
          justify-content: center;
          align-items: center;
        }

        .promo-code-code-message h1,
        .promo-code-code-message h2 {
          color: #fff;
          width: auto;
          margin: 12px;
        }

        .promo-code-code-message h2 {
          font-family: Raleway;
          font-size: 24px;
          font-weight: 700;
          line-height: 24px;
          letter-spacing: 0px;
        }

        .wheel {
          height: 286px;
          width: 286px;
          position: relative;
          border-radius: 50%;
          overflow: hidden;
          box-shadow: 0 0 10px gray;
          transition: 3s all;
          border: 6px solid #fff;
          background: #000;
          color: #fff;
        }

        .wheel div {
          height: 50%;
          width: 166px;
          clip-path: polygon(100% 0, 50% 100%, 0 0);
          transform: translateX(-50%);
          transform-origin: bottom;
          position: absolute;
          left: 21%;
          display: flex;
          align-items: center;
          justify-content: center;
          font-size: 20px;
          font-family: monospace;
          font-weight: 1000;
          writing-mode: vertical-rl;
        }

        .wheel > div:nth-child(odd) {
          background: #000;
          color: #ee8107;
        }

        .wheel > div:nth-child(even) {
          color: #000;
          background: #ee8107;
        }

        .wheel .one {
          transform: rotate(30deg);
        }
        .wheel .two {
          transform: rotate(90deg);
        }
        .wheel .three {
          transform: rotate(150deg);
        }
        .wheel .four {
          transform: rotate(210deg);
        }
        .wheel .five {
          transform: rotate(270deg);
        }
        .wheel .six {
          transform: rotate(330deg);
        }

        form {
          width: 286px;
        }

        input[type="email"] {
          background: #ffffff;
          border: 1px solid #cbd1d7;
          border-radius: 4px;
          width: 100%;
          height: 48px;
          padding: 12px;
          margin-bottom: 24px;
          border: none;
          box-shadow: 0px 1px 1px rgba(5, 27, 44, 0.16),
            inset 0px 2px 0px rgba(255, 255, 255, 0.05);
        }

        input[type="submit"] {
          background: #ee8107;
          color: #ffffff;
          border-radius: 4px;
          width: 100%;
          height: 48px;
          padding: 12px;
          border: none;
          box-shadow: 0px 1px 1px rgba(5, 27, 44, 0.16),
            inset 0px 2px 0px rgba(255, 255, 255, 0.05);
          font-family: "Raleway";
          font-weight: 500;
          font-size: 16px;
          line-height: 19px;
        }

        .shop-now-button {
          display: none;
          background: #ee8107;
          color: #ffffff;
          border-radius: 4px;
          width: 286px;
          height: 48px;
          padding: 12px;
          border: none;
          font-family: "Raleway";
          font-weight: 500;
          font-size: 16px;
          line-height: 19px;
          box-shadow: 0px 1px 1px rgba(5, 27, 44, 0.16),
            inset 0px 2px 0px rgba(255, 255, 255, 0.05);
          margin-top: 48px;
        }

        h2.deal {
          font-size: 36px;
        }

        @media screen and (min-width: 480px) {
        }
      </style>
    </head>

    <body>
      <div class="close-button" data-onesignal-unique-label="close-button">
        <svg
          width="16"
          height="16"
          preserveAspectRatio="none"
          viewBox="0 0 8 8"
          fill="none"
          xmlns="http://www.w3.org/2000/svg"
        >
          <path
            d="M7.80309 1.14768C8.06564 0.885137 8.06564 0.459453 7.80309 0.196909C7.54055 -0.0656362 7.11486 -0.0656362 6.85232 0.196909L4 3.04923L1.14768 0.196909C0.885137 -0.0656362 0.459453 -0.0656362 0.196909 0.196909C-0.0656362 0.459453 -0.0656362 0.885137 0.196909 1.14768L3.04923 4L0.196909 6.85232C-0.0656362 7.11486 -0.0656362 7.54055 0.196909 7.80309C0.459453 8.06564 0.885137 8.06564 1.14768 7.80309L4 4.95077L6.85232 7.80309C7.11486 8.06564 7.54055 8.06564 7.80309 7.80309C8.06564 7.54055 8.06564 7.11486 7.80309 6.85232L4.95077 4L7.80309 1.14768Z"
            fill="#111111"
          />
        </svg>
      </div>
      <div class="flex-container">
        <h1 class="primary-header">Cyber Monday</h1>
        <h2 class="secondary-header">
          Add your email address and spin the wheel!
        </h2>
        <div class="wheel-container">
          <div class="stopper">
            <svg
              width="23"
              height="29"
              viewBox="0 0 23 29"
              fill="none"
              xmlns="http://www.w3.org/2000/svg"
            >
              <path
                d="M11.6741 0.767822C8.69151 0.771461 5.83213 1.9579 3.72313 4.06688C1.61415 6.17588 0.42771 9.03526 0.424072 12.0178C0.424072 21.3541 10.5791 27.8078 11.0116 28.0778L11.6741 28.4928L12.3366 28.0778C12.7691 27.8078 22.9241 21.3541 22.9241 12.0178C22.9204 9.03526 21.7339 6.17588 19.6249 4.06688C17.5159 1.9579 14.6567 0.771461 11.6741 0.767822ZM11.6741 18.2678C10.4379 18.2678 9.22957 17.9013 8.20176 17.2144C7.17395 16.5277 6.37287 15.5516 5.89982 14.4096C5.42677 13.2676 5.30301 12.0109 5.54416 10.7985C5.78532 9.58612 6.38057 8.47249 7.25466 7.59841C8.12873 6.72432 9.24232 6.12907 10.4547 5.88791C11.6672 5.64676 12.9238 5.77052 14.0658 6.24357C15.2078 6.71662 16.1839 7.5177 16.8707 8.54551C17.5576 9.57331 17.9241 10.7817 17.9241 12.0178C17.9221 13.6748 17.2629 15.2633 16.0913 16.4351C14.9196 17.6067 13.3311 18.2658 11.6741 18.2678Z"
                fill="#E54B4D"
              />
              <path
                fill-rule="evenodd"
                clip-rule="evenodd"
                d="M12.3366 28.0778C12.7691 27.8078 22.9241 21.3541 22.9241 12.0178C22.9204 9.03526 21.7339 6.17588 19.6249 4.06688C17.5159 1.9579 14.6567 0.771461 11.6741 0.767822C8.69151 0.771461 5.83213 1.9579 3.72313 4.06688C1.61415 6.17588 0.42771 9.03526 0.424072 12.0178C0.424072 21.3541 10.5791 27.8078 11.0116 28.0778L11.6741 28.4928L12.3366 28.0778ZM11.6741 27.3128L11.807 27.2295C11.986 27.1178 14.5496 25.4917 17.0571 22.7701C19.5773 20.0346 21.9236 16.3213 21.9241 12.019C21.9208 9.30129 20.8396 6.69576 18.9178 4.77399C16.9964 2.85252 14.3915 1.77146 11.6741 1.76782C8.95675 1.77146 6.35172 2.85253 4.43024 4.77399M4.43024 4.77399C2.50863 6.69561 1.42754 9.3009 1.42407 12.0185C1.4243 16.3209 3.77074 20.0345 6.29108 22.7701C8.79858 25.4917 11.3621 27.1178 11.5411 27.2295L11.5424 27.2304L11.6741 27.3128M11.6741 18.2678C10.4379 18.2678 9.22957 17.9013 8.20176 17.2144C7.17395 16.5277 6.37287 15.5516 5.89982 14.4096C5.42677 13.2676 5.30301 12.0109 5.54416 10.7985C5.78532 9.58612 6.38057 8.47249 7.25466 7.59841C8.12873 6.72432 9.24232 6.12907 10.4547 5.88791C11.6672 5.64676 12.9238 5.77052 14.0658 6.24357C15.2078 6.71662 16.1839 7.5177 16.8707 8.54551C17.5576 9.57331 17.9241 10.7817 17.9241 12.0178C17.9221 13.6748 17.2629 15.2633 16.0913 16.4351C14.9196 17.6067 13.3311 18.2658 11.6741 18.2678ZM6.54755 6.89131C5.53361 7.90524 4.84312 9.19706 4.56337 10.6034C4.28364 12.0098 4.4272 13.4675 4.97595 14.7923C5.52468 16.117 6.45393 17.2493 7.6462 18.0459C8.8385 18.8427 10.2402 19.2678 11.6741 19.2678H11.6753C13.5971 19.2655 15.4394 18.501 16.7984 17.1422C18.1572 15.7832 18.9218 13.9408 18.9241 12.019V12.0178C18.9241 10.584 18.499 9.18224 17.7022 7.98995M6.54755 6.89131C7.56147 5.87738 8.85324 5.18688 10.2596 4.90713C11.6661 4.6274 13.1238 4.77095 14.4485 5.3197C15.7732 5.86842 16.9055 6.79771 17.7022 7.98995"
                fill="white"
              />
            </svg>
          </div>
          <div class="wheel">
            <div class="one">15% OFF</div>
            <div class="two">10% OFF</div>
            <div class="three">30% OFF</div>
            <div class="four">20% OFF</div>
            <div class="five">25% OFF</div>
            <div class="six">Try Again</div>
          </div>
          <div class="wheel promo-code-code-message">
            <h2 class="deal"></h2>
            <p>your next order</p>
            <p>Use Code</p>
            <h1 class="promo-code"></h1>
          </div>
        </div>
        <button class="shop-now-button">Shop Now</button>
        <form>
          <input
            type="email"
            name="email-address"
            placeholder="Enter your Email"
            required
          />
          <input
            type="submit"
            value="Try My Luck!"
            data-onesignal-unique-label="submit-button"
          />
        </form>
      </div>
      <script type="text/javascript">
        window.deal = "";
        window.promoCode = "";
        window.addEventListener("load", (event) => {
          document
            .querySelector(".close-button")
            .addEventListener("click", function (e) {
              OneSignalIamApi.close(e);
            });

          document
            .querySelector(".shop-now-button")
            .addEventListener("click", function (e) {
              // Redirect to shopping page
              OneSignalIamApi.close(e);
            });

          document.querySelector("form").addEventListener("submit", function (e) {
            e.preventDefault();
            e.stopPropagation();
            var emailAddress = e.target["email-address"].value;
            var wheel = document.querySelector(".wheel");
            var number = Math.ceil(Math.random() * 10000);
            var edges = [30, 90, 150, 210, 270, 330];
            if (edges.includes(number)) {
              // Add one so that the wheel never lands on an edge 🤫
              number += 1;
            }
            wheel.style.transform = "rotate(" + number + "deg)";
            var results = handlePromoReceived(number);
            var isPromoReceived = results.isPromoReceived;
            var shouldTryAgain = results.shouldTryAgain;

            var resultTimeout = 5000;

            if (isPromoReceived) {
              setTimeout(function () {
                document.querySelector(".shop-now-button").style["display"] =
                  "block";
                document.querySelector(
                  ".promo-code-code-message"
                ).style["display"] = "flex";
                document.querySelector(
                  ".deal"
                ).innerText = window.deal;
                document.querySelector(
                  ".promo-code"
                ).innerText = window.promoCode;
                document.querySelector(".wheel-container .stopper").style[
                  "display"
                ] = "none";
                document.querySelector("form").style["display"] = "none";
                document.querySelector(".primary-header").innerText =
                  "Congratulations";
                document.querySelector(".secondary-header").innerText =
                  "You unlocked a good discount";
              }, resultTimeout);
            }

            if (shouldTryAgain) {
              setTimeout(function () {
                document.querySelector('input[type="submit"]').value = "Try Again!";
              }, resultTimeout)
            }
          });

          function handlePromoReceived(number) {
            var finalRotation = number % 360;
            var isPromoReceived;
            var shouldTryAgain;
            if (finalRotation < 30) {
              isPromoReceived = false;
              shouldTryAgain = true;
            }
            if (finalRotation >= 30 && finalRotation < 90) {
              window.deal = "25% Off!";
              window.promoCode = "58UYGD";
              isPromoReceived = true;
              shouldTryAgain = false;
            }
            if (finalRotation >= 90 && finalRotation < 150) {
              window.deal = "20% Off!";
              window.promoCode = "18RYBQ";
              isPromoReceived = true;
              shouldTryAgain = false;
            }
            if (finalRotation >= 150 && finalRotation < 210) {
              window.deal = "30% Off!";
              window.promoCode = "48YTGA";
              isPromoReceived = true;
              shouldTryAgain = false;
            }
            if (finalRotation >= 210 && finalRotation < 270) {
              window.deal = "10% Off!";
              window.promoCode = "78UUWL";
              isPromoReceived = true;
              shouldTryAgain = false;
            }
            if (finalRotation >= 270 && finalRotation < 330) {
              window.deal = "15% Off!";
              window.promoCode = "01RLPW";
              isPromoReceived = true;
              shouldTryAgain = false;
            }
            if (finalRotation >= 330) {
              isPromoReceived = false;
              shouldTryAgain = true;
            }

            return {
              isPromoReceived: isPromoReceived,
              shouldTryAgain: shouldTryAgain,
            }
          }
        });
      </script>
    </body>
  </html>
  ```
</Accordion>

***

### Quiz modal

Interactive quiz that tracks score.

* Update the questions array with real content.
* Decide when to tag users:
  * current behavior tags on close
  * you can tag immediately when the quiz ends

<Accordion title="HTML Code">
  ```html theme={null}
  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <link
        rel="stylesheet"
        href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"
      />

      <meta http-equiv="X-UA-Compatible" content="ie=edge" />
      <title>Onesignal In-App Message</title>
      <style>

        body {
          margin: 0;
          padding-top: var(--safe-area-inset-top);
          padding-right: var(--safe-area-inset-right);
          padding-bottom: calc(var(--safe-area-inset-bottom) + 20px);
          padding-left: var(--safe-area-inset-left);
          font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
          display: flex;
          align-items: center;
        }

        .center-modal {
          position: relative;
          background: #FFF;
          margin: 18px;
          padding: 24px;
          border-radius: 8px;

          display: flex;
          flex-direction: column;
          justify-content: center;
          align-items: center;
          height:80%;
          width: 100%;
          box-shadow: rgb(0 0 0 / 30%) 0px 0px 12.5px, rgb(0 0 0 / 15%) 0px 0px 2.5px;
        }

        .center-modal .close-button {
          position: absolute;
          top: 0;
          right: 0;
          background: rgba(0, 0, 0, 0);
          border: none;
          z-index: 1;
          display: flex;
          justify-content: center;
          flex-direction: column;
          align-items: center;
          /* Tip: Make your close-button relatively large so it's easy to click */
          min-width: 48px;
          min-height: 48px;
        }


        .center-modal h1 {
          margin: 0px;
          margin-bottom: 12px;
          color: #222;
          font-size: 24;
          font-style: normal;
          font-weight: normal;
          text-align: center;
          text-decoration: none;
        }

        .center-modal button {
          font-size: 16px;
          color: #fff;
          background-color: #1F8FEB;
          width: 100%;
          padding: 12px;
          border-radius: 4px;
          border: none;
          margin-bottom: 12px;
        }

        .button-container {
          display: flex;
          flex-direction: column;
        }

        @media screen and (min-width: 480px) {
          .button-container {
            flex-direction: row;
            grid-gap: 12px;
            width: 100%;
          }

          .button-column {
            width: 50%;
          }

          .center-modal {
            height: 80%;
          }
        }
      </style>
    </head>

    <body>
      <div class="center-modal">
        <div class="close-button" data-onesignal-unique-label="close-button">
          <svg
            width="10"
            height="10"
            preserveAspectRatio="none"
            viewBox="0 0 8 8"
            fill="none"
            xmlns="http://www.w3.org/2000/svg"
          >
            <path
              d="M7.80309 1.14768C8.06564 0.885137 8.06564 0.459453 7.80309 0.196909C7.54055 -0.0656362 7.11486 -0.0656362 6.85232 0.196909L4 3.04923L1.14768 0.196909C0.885137 -0.0656362 0.459453 -0.0656362 0.196909 0.196909C-0.0656362 0.459453 -0.0656362 0.885137 0.196909 1.14768L3.04923 4L0.196909 6.85232C-0.0656362 7.11486 -0.0656362 7.54055 0.196909 7.80309C0.459453 8.06564 0.885137 8.06564 1.14768 7.80309L4 4.95077L6.85232 7.80309C7.11486 8.06564 7.54055 8.06564 7.80309 7.80309C8.06564 7.54055 8.06564 7.11486 7.80309 6.85232L4.95077 4L7.80309 1.14768Z"
              fill="#111111"
            />
          </svg>
        </div>

        <!-- Add notification details below -->

        <div id="quiz">
          <h1>Quiz Time!</h1>
          <h3>Score 100%, and get 50% off</h3>

          <hr style="margin-bottom: 20px" />

          <p id="question"></p>

          <div class="button-grp">
    <button id="btn0">
      <span id="choice0"></span>
    </button>
    <button id="btn1">
      <span id="choice1"></span>
    </button>
    <button id="btn2">
      <span id="choice2"></span>
    </button>
    <button id="btn3">
      <span id="choice3"></span>
    </button>
  </div>

          <hr style="margin-top: 40px" />

          <footer>
            <p id="Qnumber">Question x of y</p>
          </footer>
        </div>
      </div>

      <script>
  class Quiz {
    constructor(questions) {
      this.score = 0;
      this.questions = questions;
      this.questionIndex = 0;
    }

    isEnded() {
      return this.questions.length === this.questionIndex;
    }

    getQuestionIndex() {
      return this.questions[this.questionIndex];
    }

    guess(answer) {
      if (this.getQuestionIndex().correctAnswer(answer)) {
        this.score++;
      }
      this.questionIndex++;
    }
  }

  class Question {
    constructor(text, choices, answer) {
      this.text = text;
      this.choices = choices;
      this.answer = answer;
    }

    correctAnswer(choice) {
      return choice === this.answer;
    }
  }

  function populate() {
    if (quiz.isEnded()) {
      showScores();
      return;
    }

    const questionElement = document.getElementById('question');
    questionElement.textContent = quiz.getQuestionIndex().text;

    // Show choices
    const choices = quiz.getQuestionIndex().choices;
    for (let i = 0; i < choices.length; i++) {
      const choiceElement = document.getElementById(`choice${i}`);
      choiceElement.textContent = choices[i];

      guess(`btn${i}`, choices[i]);
    }

    showQnumber();
  }

  function guess(id, guess) {
    const button = document.getElementById(id);
    button.onclick = function () {
      quiz.guess(guess);
      populate();
    };
  }

  function showQnumber() {
    const currentQuestionNumber = quiz.questionIndex + 1;
    const element = document.getElementById('Qnumber');
    element.innerHTML = `Questions ${currentQuestionNumber} of ${quiz.questions.length}`;
  }

  function showScores() {
    const gameOverHTML = "<h1>Result</h1>";
    const scoreHTML = `<h2 id='score'> Here's Your final Score: ${quiz.score}/${quiz.questions.length}</h2>`;
    const element = document.getElementById('quiz');
    element.innerHTML = gameOverHTML + scoreHTML;
  }

  // First set the questions, then set 4 potential answers for each question, lastly set the correct answer on the last column.
  const questions = [
    new Question('Question 1?', ['Answer1', 'Answer2', 'Correct Answer', 'Answer4'], 'Correct Answer'),
    new Question('Question 2?', ['Answer1', 'Correct Answer', 'Answer3', 'Answer4'], 'Correct Answer'),
    new Question('Question 3?', ['Answer1', 'Answer2', 'Answer3', 'Correct Answer'], 'Correct Answer'),
    new Question('Question 4?', ['Correct Answer', 'Answer2', 'Answer3', 'Answer4'], 'Correct Answer'),
  ];

  const quiz = new Quiz(questions);

  populate();

  //tags user with their score once they close the in-app notification
  document.querySelector('.close-button').addEventListener('click', function (e) {
    OneSignalIamApi.tagUser(e, { score: quiz.score });
    OneSignalIamApi.close(e);
  });

      </script>
    </body>
  </html>
  ```
</Accordion>

***

### Ranking survey

1–5 rating survey.

* Set your url in `handleSurveyAnswer()`.
* Update question text and labels.

<Accordion title="HTML Code">
  ```html theme={null}
  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta http-equiv="X-UA-Compatible" content="ie=edge" />
      <title>Onesignal In-App Message</title>
      <!-- Google Fonts -->
      <link rel="preconnect" href="https://fonts.googleapis.com" />
      <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
      <link
        href="https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@500;700&family=Raleway:wght@500;700&display=swap"
        rel="stylesheet"
      />
      <!-- CSS Reset -->
      <link
        href="https://cdnjs.cloudflare.com/ajax/libs/meyer-reset/2.0/reset.min.css"
        rel="stylesheet"
      />
      <style>
        body {
          margin: 0;
          padding-top: var(--safe-area-inset-top);
          padding-right: var(--safe-area-inset-right);
          padding-bottom: calc(var(--safe-area-inset-bottom) + 20px);
          padding-left: var(--safe-area-inset-left);
          font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
            Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
          display: flex;
          align-items: center;
        }

        .center-modal {
          position: relative;
          background: #fff;
          margin: 18px;
          padding: 72px 24px 40px;
          border-radius: 8px;
          height: min-content;
          width: 100%;
          box-shadow: rgb(0 0 0 / 30%) 0px 0px 12.5px,
            rgb(0 0 0 / 15%) 0px 0px 2.5px;
        }

        .center-modal .close-button {
          position: absolute;
          top: 0;
          right: 0;
          background: rgba(0, 0, 0, 0);
          border: none;
          z-index: 1;
          display: flex;
          justify-content: center;
          flex-direction: column;
          align-items: center;
          /* Tip: Make your close-button relatively large so it's easy to click */
          min-width: 48px;
          min-height: 48px;
        }

        h1 {
          font-family: Raleway;
          font-size: 24px;
          font-weight: 700;
          line-height: 28px;
          letter-spacing: 0px;
          text-align: left;
          color: #051b2c;
        }

        h2 {
          font-family: Raleway;
          font-size: 16px;
          font-weight: 500;
          line-height: 24px;
          letter-spacing: 0px;
          text-align: left;
          color: #28333e;
          margin-bottom: 22px;
        }

        @media screen and (min-width: 480px) {
          .center-modal {
            height: 80%;
          }
        }

        .survey-form ul {
          display: grid;
          grid-auto-flow: column;
          margin-bottom: 14px;
        }

        .survey-form li button {
          background: #cae4fa;
          border: 1px solid #aad4f7;
          border-radius: 4px;
          width: 45px;
          height: 35px;
        }

        .legend {
          display: flex;
          justify-content: space-between;
          color: #74808b;
          font-family: "Raleway";
          font-style: normal;
          font-weight: 500;
          font-size: 14px;
          line-height: 24px;
        }
      </style>
    </head>

    <body>
      <div class="center-modal">
        <div class="close-button" data-onesignal-unique-label="close-button">
          <svg
            width="10"
            height="10"
            preserveAspectRatio="none"
            viewBox="0 0 8 8"
            fill="none"
            xmlns="http://www.w3.org/2000/svg"
          >
            <path
              d="M7.80309 1.14768C8.06564 0.885137 8.06564 0.459453 7.80309 0.196909C7.54055 -0.0656362 7.11486 -0.0656362 6.85232 0.196909L4 3.04923L1.14768 0.196909C0.885137 -0.0656362 0.459453 -0.0656362 0.196909 0.196909C-0.0656362 0.459453 -0.0656362 0.885137 0.196909 1.14768L3.04923 4L0.196909 6.85232C-0.0656362 7.11486 -0.0656362 7.54055 0.196909 7.80309C0.459453 8.06564 0.885137 8.06564 1.14768 7.80309L4 4.95077L6.85232 7.80309C7.11486 8.06564 7.54055 8.06564 7.80309 7.80309C8.06564 7.54055 8.06564 7.11486 7.80309 6.85232L4.95077 4L7.80309 1.14768Z"
              fill="#111111"
            />
          </svg>
        </div>
        <h1>Hi, Olivia</h1>
        <h2>How likely are you to recommend us to a friend or family?</h2>
        <div class="survey-form">
          <ul>
            <li>
              <button id="option_1">1</button>
            </li>
            <li>
              <button id="option_2">2</button>
            </li>
            <li>
              <button id="option_3">3</button>
            </li>
            <li>
              <button id="option_4">4</button>
            </li>
            <li>
              <button id="option_5">5</button>
            </li>
          </ul>
          <div class="legend">
            <div>Very unlikely</div>
            <div>Very likely</div>
          </div>
        </div>
      </div>
      <script>
        function handleSurveyAnswer(answer) {
          // Add your own survey api endpoint url here
          var url = "https://example.com/survey";
          var options = {
            method: "POST",
            headers: {
              Accept: "application/json",
              "Content-Type": "application/json",
            },
            body: JSON.stringify({
              value: answer,
            }),
          };
          fetch(url, options)
            .then((response) => response.json())
            .then((response) => console.log(response))
            .catch((err) => console.error(err));
        }

        window.addEventListener("load", (event) => {
          document
            .querySelector(".close-button")
            .addEventListener("click", function (e) {
              OneSignalIamApi.close(e);
            });

          document
            .querySelector("#option_1")
            .addEventListener("click", function (e) {
              handleSurveyAnswer(1);
              OneSignalIamApi.close(e);
            });

          document
            .querySelector("#option_2")
            .addEventListener("click", function (e) {
              handleSurveyAnswer(2);
              OneSignalIamApi.close(e);
            });

          document
            .querySelector("#option_3")
            .addEventListener("click", function (e) {
              handleSurveyAnswer(3);
              OneSignalIamApi.close(e);
            });

          document
            .querySelector("#option_4")
            .addEventListener("click", function (e) {
              handleSurveyAnswer(4);
              OneSignalIamApi.close(e);
            });

          document
            .querySelector("#option_5")
            .addEventListener("click", function (e) {
              handleSurveyAnswer(5);
              OneSignalIamApi.close(e);
            });
        });
      </script>
    </body>
  </html>
  ```
</Accordion>

***

### Audio/video player

Audio preview UI. For video details, see the HTML Design guide for [embedding videos](./design-your-in-app-message-with-html#embedding-videos).

* Replace the `<audio> src` with a direct MP3 URL.
* Update the CTA `openUrl` destination URL.

<Warning> Do not use a streaming page URL in `<audio>`. The `<audio>` element requires a direct audio file URL (like `.mp3`). </Warning>

<Accordion title="HTML Code">
  ```html theme={null}
  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <link
        rel="stylesheet"
        href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"
      />

      <meta http-equiv="X-UA-Compatible" content="ie=edge" />
      <title>Onesignal In-App Message</title>
      <style>
        body {
          margin: 0;
          padding-top: var(--safe-area-inset-top);
          padding-right: var(--safe-area-inset-right);
          padding-bottom: calc(var(--safe-area-inset-bottom) + 20px);
          padding-left: var(--safe-area-inset-left);
          font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
          display: flex;
          align-items: center;
        }

        .center-modal {
          position: relative;
          background: #FFF;
          margin: 18px;
          padding: 24px;
          border-radius: 8px;

          display: flex;
          flex-direction: column;
          justify-content: center;
          align-items: center;
          height:45%;
          width: 100%;
          box-shadow: rgb(0 0 0 / 30%) 0px 0px 12.5px, rgb(0 0 0 / 15%) 0px 0px 2.5px;
        }

        .center-modal .close-button {
          position: absolute;
          top: 0;
          right: 0;
          background: rgba(0, 0, 0, 0);
          border: none;
          z-index: 1;
          display: flex;
          justify-content: center;
          flex-direction: column;
          align-items: center;
          /* Tip: Make your close-button relatively large so it's easy to click */
          min-width: 48px;
          min-height: 48px;
        }

        .center-modal img {
          min-height: 10px;
          margin-bottom: 12px;
          width: 100%;
          height: 100%;
          object-fit: contain;
        }

        .center-modal h1 {
          margin: 0px;
          margin-bottom: 12px;
          color: #222;
          font-size: 24;
          font-style: normal;
          font-weight: normal;
          text-align: center;
          text-decoration: none;
        }

        .center-modal button {
          font-size: 16px;
          color: #fff;
          background-color: #1F8FEB;
          width: 100%;
          padding: 12px;
          border-radius: 4px;
          border: none;
          margin-bottom: 12px;
        }

        .button-container {
          display: flex;
          flex-direction: column;
        }

        @media screen and (min-width: 480px) {
          .button-container {
            flex-direction: row;
            grid-gap: 12px;
            padding-left: 20%;
            width: 40%;
          }

          .button-column {
            width: 50%;
          }

          .center-modal {
            height: 80%;
          }
        }
      </style>
    </head>

    <body>
      <div class="center-modal">
        <div class="close-button" data-onesignal-unique-label="close-button">
          <svg
            width="10"
            height="10"
            preserveAspectRatio="none"
            viewBox="0 0 8 8"
            fill="none"
            xmlns="http://www.w3.org/2000/svg"
          >
            <path
              d="M7.80309 1.14768C8.06564 0.885137 8.06564 0.459453 7.80309 0.196909C7.54055 -0.0656362 7.11486 -0.0656362 6.85232 0.196909L4 3.04923L1.14768 0.196909C0.885137 -0.0656362 0.459453 -0.0656362 0.196909 0.196909C-0.0656362 0.459453 -0.0656362 0.885137 0.196909 1.14768L3.04923 4L0.196909 6.85232C-0.0656362 7.11486 -0.0656362 7.54055 0.196909 7.80309C0.459453 8.06564 0.885137 8.06564 1.14768 7.80309L4 4.95077L6.85232 7.80309C7.11486 8.06564 7.54055 8.06564 7.80309 7.80309C8.06564 7.54055 8.06564 7.11486 7.80309 6.85232L4.95077 4L7.80309 1.14768Z"
              fill="#111111"
            />
          </svg>
        </div>
        <h2>Why Stop Drinking Coffee</h2>
        <h1>Podcast Preview</h1>

        <br />

        <div>
          <i
            onclick="pauseaudio()"
            class="fa fa-pause-circle"
            style="font-size:48px;color:grey"
          ></i>
          <i
            onclick="playaudio()"
            class="fa fa-play-circle"
            style="font-size:48px;color:blue"
          ></i>
          <i
            onclick="stopaudio()"
            class="fa fa-stop-circle"
            style="font-size:48px;color:grey"
          ></i>
        </div>

        <br />
        <br />

        <div class="button-container">
          <div class="button-column">
            <button
              class="open-url"
              data-onesignal-unique-label="my-open-url-button"
            >
              Listen to the Full Podcast
            </button>
          </div>
        </div>
      </div>

      <!--Update the Audio file source below. Please make sure that you're linking to a direct file and not to a streaming service. -->

      <audio id="idAudio">
        <source
          src="https://SiteURL.com/YOUR_AUDIO_FILE_HERE.mp3"
          type="audio/ogg"
        />
        <source
          src="https://SiteURL.com/YOUR_AUDIO_FILE_HERE.mp3"
          type="audio/mpeg"
        />
        Audio file not supported..
      </audio>

      <script>

             var a = document.getElementById("idAudio");
        	function playaudio() {
        		a.play();
        	}
        	function pauseaudio() {
        		a.pause();
        	}
        	function stopaudio() {
        		a.pause();
        		a.currentTime = 0;
        	}

             document.querySelector(".close-button").addEventListener("click", function(e) {
               stopaudio();
               OneSignalIamApi.close(e);
             });

        // Change the URL below to the URL which you would like to re-direct users


             document.querySelector(".open-url").addEventListener("click", function(e) {
               OneSignalIamApi.openUrl(e, "https://documentation.onesignal.com/docs/in-app-js-library");
             });
      </script>
    </body>
  </html>
  ```
</Accordion>

***

### Vertical swiping

Multi-slide vertical onboarding or feature tour.

**Why this template works well on mobile:**

* Uses a hidden OneSignal-labeled close button for reliable dismissal.
* Places the visible close button in the safe area and uses a large tap target.
* Disables swipe when interacting with buttons/inputs.

<Accordion title="HTML Code">
  ```html theme={null}
  <!doctype html>
  <html lang="en">
  <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>OneSignal Vertical Carousel</title>

  <style>
    * { box-sizing: border-box; }
    html, body {
      height: 100%;
      margin: 0;
      overflow: hidden;
      background: #0b1220;
      font-family: system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial;
      color: #fff;
    }

    .carousel{
      position: relative;
      width: 100%;
      height: 100%;
      overflow: hidden;
      background: #0b1220;
      touch-action: none;
      -webkit-user-select: none;
      user-select: none;

      /* optional: avoids content underlapping system bars on some webviews */
      padding-top: env(safe-area-inset-top, 0px);
      padding-right: env(safe-area-inset-right, 0px);
    }

    .track{
      height: 100%;
      width: 100%;
      display: flex;
      flex-direction: column;
      transform: translate3d(0,0,0);
      transition: transform 320ms cubic-bezier(.2,.9,.2,1);
      will-change: transform;
    }

    .slide{
      flex: 0 0 100%;
      height: 100%;
      width: 100%;
      padding: 24px;
      display: flex;
      align-items: center;
      justify-content: center;
    }

    .card{
      width: 100%;
      max-width: 520px;
      background: rgba(255,255,255,0.06);
      border: 1px solid rgba(255,255,255,0.12);
      border-radius: 20px;
      padding: 24px;
    }

    h2 { margin: 0 0 10px; font-size: 22px; }
    p  { margin: 0 0 16px; color: rgba(255,255,255,0.75); line-height: 1.5; }

    .actions{
      display: flex;
      gap: 10px;
      flex-wrap: wrap;
    }

    button{
      border-radius: 12px;
      border: 1px solid rgba(255,255,255,0.2);
      background: rgba(255,255,255,0.08);
      color: #fff;
      padding: 10px 14px;
      font-weight: 600;
      cursor: pointer;
    }

    .primary{
      background: rgba(82,97,255,.6);
      border-color: rgba(82,97,255,.8);
    }

    /* Bigger, safer tap target for Android */
    .close{
      position: absolute;
      z-index: 10;

      /* SAFE AREA + extra padding so it’s never “too high” */
      top: calc(env(safe-area-inset-top, 0px) + 12px);
      right: calc(env(safe-area-inset-right, 0px) + 12px);

      width: 48px;
      height: 48px;
      padding: 0;

      display: grid;
      place-items: center;

      border-radius: 14px;
      border: 1px solid rgba(255,255,255,0.2);
      background: rgba(255,255,255,0.10);
      font-size: 18px;
      line-height: 1;
    }

    .nav{
      position: absolute;
      right: calc(env(safe-area-inset-right, 0px) + 16px);
      top: 50%;
      transform: translateY(-50%);
      display: flex;
      flex-direction: column;
      gap: 10px;
      z-index: 10;
    }

    .dot{
      width: 10px;
      height: 10px;
      border-radius: 999px;
      background: rgba(255,255,255,0.3);
      border: none;
      padding: 0;
      cursor: pointer;
    }

    .dot[aria-current="true"]{
      height: 26px;
      background: rgba(82,97,255,.8);
    }

    /* Hidden but real OneSignal close button */
    #close-button {
      position: absolute;
      width: 1px;
      height: 1px;
      padding: 0;
      margin: -1px;
      overflow: hidden;
      clip: rect(0,0,0,0);
      white-space: nowrap;
      border: 0;
    }
  </style>
  </head>

  <body>
  <div class="carousel" id="carousel">

    <!-- Real OneSignal close button (Android-safe) -->
    <button id="close-button" data-onesignal-unique-label="iam-close">Close</button>

    <!-- Visible X (safe-area positioned, big tap target) -->
    <button class="close" id="closeBtn" type="button" aria-label="Close">✕</button>

    <div class="track" id="track">
      <section class="slide">
        <div class="card">
          <h2>Welcome 👋</h2>
          <p>Swipe up to continue. Each slide is a custom HTML section.</p>
          <div class="actions">
            <button class="primary" type="button" data-next>Continue</button>
          </div>
        </div>
      </section>

      <section class="slide">
        <div class="card">
          <h2>Feature Highlight ✨</h2>
          <p>Vertical swipe + dots + buttons.</p>
          <div class="actions">
            <button class="primary" type="button" data-next>Next</button>
            <button type="button" data-prev>Back</button>
          </div>
        </div>
      </section>

      <section class="slide">
        <div class="card">
          <h2>All Set ✅</h2>
          <p>Done / X will dismiss the IAM properly.</p>
          <div class="actions">
            <button class="primary" type="button" id="doneBtn">Done</button>
            <button type="button" data-prev>Back</button>
          </div>
        </div>
      </section>
    </div>

    <div class="nav" id="dots" aria-label="Slide dots"></div>
  </div>

  <script>
  (function () {
    const carousel = document.getElementById('carousel');
    const track = document.getElementById('track');
    const slides = Array.from(track.querySelectorAll('.slide'));
    const dots = document.getElementById('dots');

    let index = 0;
    let height = 1;
    const clamp = (n, min, max) => Math.max(min, Math.min(max, n));

    function measure() {
      height = carousel.getBoundingClientRect().height || 1;
      snap(index, false);
    }

    function snap(i, animate = true) {
      index = clamp(i, 0, slides.length - 1);
      track.style.transition = animate ? '' : 'none';
      track.style.transform = `translate3d(0, ${-index * height}px, 0)`;
      updateDots();
      if (!animate) requestAnimationFrame(() => (track.style.transition = ''));
    }

    function next() { snap(index + 1); }
    function prev() { snap(index - 1); }

    slides.forEach((_, i) => {
      const d = document.createElement('button');
      d.className = 'dot';
      d.type = 'button';
      d.setAttribute('aria-label', `Go to slide ${i + 1}`);
      d.onclick = () => snap(i);
      dots.appendChild(d);
    });

    function updateDots() {
      Array.from(dots.children).forEach((d, i) => {
        d.setAttribute('aria-current', i === index ? 'true' : 'false');
      });
    }

    document.addEventListener('click', (e) => {
      if (e.target.matches('[data-next]')) next();
      if (e.target.matches('[data-prev]')) prev();
    });

    // Swipe (Pointer + Touch fallback)
    let startY = 0, currentY = 0, dragging = false, startTranslate = 0;

    function getTranslateY() {
      const m = (track.style.transform || '').match(/translate3d\(0,\s*([-0-9.]+)px/);
      return m ? parseFloat(m[1]) : 0;
    }

    function beginDrag(y) {
      dragging = true;
      startY = y;
      currentY = y;
      startTranslate = getTranslateY();
      track.style.transition = 'none';
    }

    function moveDrag(y) {
      if (!dragging) return;
      currentY = y;
      const dy = currentY - startY;

      const atStart = index === 0 && dy > 0;
      const atEnd = index === slides.length - 1 && dy < 0;
      const resistance = (atStart || atEnd) ? 0.35 : 1;

      track.style.transform = `translate3d(0, ${startTranslate + dy * resistance}px, 0)`;
    }

    function endDrag() {
      if (!dragging) return;
      dragging = false;

      const dy = currentY - startY;
      const threshold = Math.min(90, height * 0.22);

      track.style.transition = '';
      if (dy < -threshold) return next();
      if (dy > threshold) return prev();
      snap(index);
    }

    carousel.addEventListener('pointerdown', (e) => {
      if (e.target.closest('button, a, input, textarea, select, label')) return;
      beginDrag(e.clientY);
      carousel.setPointerCapture?.(e.pointerId);
    });
    carousel.addEventListener('pointermove', (e) => moveDrag(e.clientY));
    carousel.addEventListener('pointerup', endDrag);
    carousel.addEventListener('pointercancel', endDrag);

    carousel.addEventListener('touchstart', (e) => {
      if (e.target.closest('button, a, input, textarea, select, label')) return;
      if (e.touches && e.touches.length) beginDrag(e.touches[0].clientY);
    }, { passive: true });

    carousel.addEventListener('touchmove', (e) => {
      if (!dragging) return;
      e.preventDefault();
      if (e.touches && e.touches.length) moveDrag(e.touches[0].clientY);
    }, { passive: false });

    carousel.addEventListener('touchend', endDrag, { passive: true });
    carousel.addEventListener('touchcancel', endDrag, { passive: true });

    new ResizeObserver(measure).observe(carousel);

    // OneSignal close: bind to the real OneSignal-labeled button
    const closeButton = document.getElementById("close-button");
    closeButton.addEventListener("click", function(e) {
      const api = window.OneSignalIamApi || (typeof OneSignalIamApi !== "undefined" ? OneSignalIamApi : null);
      if (api && typeof api.close === "function") api.close(e);
      else carousel.style.display = "none"; // preview fallback
    });

    // X and Done trigger the OneSignal close button click (Android-safe)
    document.getElementById("closeBtn").addEventListener("click", () => closeButton.click());
    document.getElementById("doneBtn").addEventListener("click", () => closeButton.click());

    // Init
    measure();
    updateDots();
  })();
  </script>
  </body>
  </html>

  ```
</Accordion>

***


# In-app message JavaScript API reference
Source: https://documentation.onesignal.com/docs/en/in-app-message-api

JavaScript methods for interactive HTML in-app messages in OneSignal.

This guide covers the **JavaScript API** for HTML in-app messages created with the [OneSignal HTML Editor](./design-your-in-app-message-with-html).

If you are looking for **SDK methods** to set triggers, handle in-app click events, or manage the in-app lifecycle, see the [Mobile SDK Reference](./mobile-sdk-reference#in-app-messages).

***

## Requirements

### Use the `data-onesignal-unique-label` attribute for click tracking

All clickable elements must have a `data-onesignal-unique-label` attribute with a **unique** value. This enables OneSignal to:

* Track click analytics
* Correctly trigger associated actions

```html HTML theme={null}
<button id="unique-button-id" data-onesignal-unique-label="unique-label-for-onesignal">
  Tag User
</button>
```

<Warning> If two elements share the same `data-onesignal-unique-label`, clicks may be logged incorrectly or actions may not fire. </Warning>

### Attach event listeners

You must explicitly attach JavaScript event listeners to trigger OneSignal in-app actions.

```javascript JavaScript  theme={null}
document.getElementById("unique-button-id")
  .addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
```

**Example:**

```html HTML  theme={null}
<button id="buy-now-button" data-onesignal-unique-label="buy-now-button-for-onesignal">
  Buy Now
</button>
<script>
  document.getElementById("buy-now-button").addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { coupon: "10OFF" });
  });
</script>
```

***

## Handling click tracking in sandboxed HTML in-app messages

Because HTML in-app messages run in a sandboxed WebView, click tracking and navigation must occur inside the same frame.
Standard anchors (`<a href="...">`) and `window.open()` calls are not tracked and can trigger console warnings such as:

```
SOAuthorizationCoordinator::tryAuthorize (2): Attempting to perform subframe navigation.
```

### Correct: use a button and OneSignal APIs

```html HTML  theme={null}
<button id="shop-now" data-onesignal-unique-label="your-unique-label-for-this-button">
  Shop Now
</button>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    const btn = document.getElementById("shop-now");
    btn.addEventListener("click", function(e) {
      OneSignalIamApi.trackClick(e);
      OneSignalIamApi.openUrl(e, "https://shop.example.com/");
    });
  });
</script>
```

### Incorrect: using `<a>` or `window.open()`

```html HTML  theme={null}
<a href="https://shop.example.com" target="_blank">
  Shop Now
</a>
```

This navigation occurs outside the in-app sandbox, preventing OneSignal from logging the click event.

<Note>
  * Each clickable element must have a **unique** `data-onesignal-unique-label`.
  * Always call `OneSignalIamApi.trackClick(e)` **before** `openUrl()` or any other OneSignal API method.
  * Bind event listeners after `DOMContentLoaded` to ensure that the elements exist.
  * OneSignal automatically tracks clicks only for methods listed in this reference; any custom navigation must call `trackClick()` manually.
</Note>

### Common issues

* **Clicks not recorded:** `trackClick()` was not called or the element is missing a `data-onesignal-unique-label`.
  * Call `trackClick(e)` and ensure each element has a unique label.
* **Console shows “Attempting to perform subframe navigation”:**\
  The code uses `window.open()` or an `<a>` link instead of `OneSignalIamApi.openUrl()`.
  * Use `OneSignalIamApi.openUrl(e, "https://example.com/")` inside the same click handler.
* **Wrong label appears in analytics:**\
  Multiple elements share the same `data-onesignal-unique-label`.
  * Give each clickable element a unique label.

***

## Available functions

All [click actions](./iam-click-actions) from the [Block Editor](./design-your-in-app-message) are also available for HTML in-app messages.

### Push permission prompt

Shows the native push notification permission prompt. Click events are automatically tracked.

See [Prompt for push permissions](./prompt-for-push-permissions).

```html HTML  theme={null}
<button id="push-prompt-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Enable Push
</button>
<script>
  document.getElementById("push-prompt-button").addEventListener("click", function(e) {
    OneSignalIamApi.triggerPushPrompt(e);
  });
</script>
```

### Location permission prompt

Shows the native location permission prompt. Click events are automatically tracked.

See [Location permission prompts](./location-opt-in-prompt).

```html HTML  theme={null}
<button id="location-prompt-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Enable Location
</button>
<script>
  document.getElementById("location-prompt-button").addEventListener("click", function(e) {
    OneSignalIamApi.triggerLocationPrompt(e);
  });
</script>
```

### Close in-app message

Dismisses the current in-app message. Click events are automatically tracked.

```html HTML theme={null}
<button id="close-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Close
</button>
<script>
  document.getElementById("close-button").addEventListener("click", function(e) {
    OneSignalIamApi.close(e);
  });
</script>
```

### Tag user

Sets a [Tag](./add-user-data-tags). Click events are automatically tracked.

```html HTML theme={null}
<button id="tag-user-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Tag User
</button>
<script>
  document.getElementById("tag-user-button").addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
</script>
```

### Open URL

Opens a URL in the device's browser and closes the in-app message. Click events are automatically tracked.

Supports [Deep Linking](./deep-linking).

```html HTML  theme={null}
<button id="open-url-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Visit Site
</button>
<script>
  document.getElementById("open-url-button").addEventListener("click", function(e) {
    OneSignalIamApi.openUrl(e, "https://example.com");
  });
</script>
```

### Click name

Assigns a click name that can be read in the [in-app message click listener](./mobile-sdk-reference#addclicklistener-in-app). Click events are automatically tracked.

Supports [Deep Linking](./deep-linking).

```html HTML theme={null}
<button id="click-name-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Click Me
</button>
<script>
  document.getElementById("click-name-button").addEventListener("click", function(e) {
    OneSignalIamApi.addClickName(e, "test_click_name");
  });
</script>
```

### Track click

Tracks a click event when you’re not using other clickable API methods.

```html HTML  theme={null}
<button id="track-click-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Track Click
</button>
<script>
  document.getElementById("track-click-button").addEventListener("click", function(e) {
    OneSignalIamApi.trackClick(e);
  });
</script>
```

### Send Outcome

Tracks an unattributed [Custom Outcome](./custom-outcomes) and sets a [Tag](./add-user-data-tags) on the user in format `outcome name : true`. Click events are automatically tracked.

```html HTML theme={null}
<button id="send-outcome-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Claim Bonus
</button>
<script>
  document.getElementById("send-outcome-button").addEventListener("click", function(e) {
    OneSignalIamApi.sendOutcome(e, "bonus_claimed");
  });
</script>
```

***

## Personalizing HTML in-app messages

You can use tag substitution in HTML in-app messages just like in the Block Editor.

<Warning> Tag substitution **does not work** inside `<script>` tags.</Warning>

Tag substitution works for:

* Inline text (`<h1>`, `<p>`, `<li>`, etc.)

* `<style>` rules:

  ```css CSS  theme={null}
  body { background-color: "{{ favorite_color | default: '#fff' }}"; }
  ```

* Attributes with URLs:
  * `href`
  * `src`
  * `<form action>`
  * `<object data>`

### Using tags in `openUrl()` and `addClickName()`

Since `<script>` tags don’t support substitution, use one of these methods:

**1. Access all tags with `liquidPlayerTags`**

This global object becomes available after `DOMContentLoaded`.

<Note>
  Before using liquidPlayerTags in your custom HTML, ensure the In-App Message itself includes at least one Liquid tag in a supported field (e.g. setting a title to "Hello \{\{first\_name}}"). If no Liquid syntax is present in the message, liquidPlayerTags will not be available.
</Note>

```html HTML theme={null}
<h1>Hello {{ first_name | default: "friend" }}!</h1>
<ul class="interests"></ul>
<button id="open-url-button" data-onesignal-unique-label="promo-link">
  Personalized Offer
</button>
<script>
  //Displaying the tags as a list
  document.addEventListener("DOMContentLoaded", function([key, value]) {
    const list = document.querySelector(".interests");
    Object.entries(liquidPlayerTags).forEach(([key, value]) => {
      const li = document.createElement("li");
      li.textContent = key + ": " + value;
      list.appendChild(li);
    });
  })
  //Using a tag in openUrl()
  document.addEventListener("DOMContentLoaded", function() {
    document.getElementById("open-url-button").addEventListener("click", function(e) {
      OneSignalIamApi.openUrl(e, "https://shop.com?coupon=" + liquidPlayerTags["coupon"]);
    });
  });
</script>
```

**2. Store a tag in the `href` attribute**

```html HTML theme={null}
<a
  id="open-url-button"
  href="app://deeplink?code={{ coupon | default: '10OFF' }}"
  data-onesignal-unique-label="promo-link"
>
  Redeem Offer
</a>
<script>
  document.getElementById("open-url-button").addEventListener("click", function(e) {
    e.preventDefault();
    OneSignalIamApi.openUrl(e, e.currentTarget.href);
  });
</script>
```

***

## Next steps

* Learn more about [using liquid syntax for tag substitution](./using-liquid-syntax)
* Explore [Deep Linking](./deep-linking) for URL handling
* [Design in-app messages with HTML](./design-your-in-app-message-with-html)

***


# In-app message reports
Source: https://documentation.onesignal.com/docs/en/in-app-message-reports

OneSignal In-App Message delivery and statistics

When opening an in-app message report, you will see the high-level statistics for how the in-app message is performing. You can find In-App Message Reports Stats by going to **Messages > In-App** and selecting a message.

<Frame>
  <img />
</Frame>

## Message Statistics

A graph of message events by block over a 30 day, 24 hour, or 1 hour period. This can be filtered by platform and exported via the dashboard.

<Frame>
  <img />
</Frame>

This data is presented on a per-card, per-block basis. Displaying how many times a block was clicked per card and the click-through rate (CTR).

<Frame>
  <img />
</Frame>

### Metric definitions

| Metric               | Definition                                                                                                                                                                                    |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Impression**       | The number of times an in-app message successfully displayed to a Subscription. Depending on your in-app settings, a single Subscription may register multiple impressions.                   |
| **Card Impressions** | The number of times a card within a carousel was displayed on a device. A carousel message will have multiple cards, but not all cards may be viewed by each user. Only applies to carousels. |
| **Total Clicks**     | The number of times a button block, image block, or background was clicked. It does not include the "Close Button" clicks.                                                                    |
| **Unique Clicks**    | The number of unique clicks across all buttons, images, and backgrounds in the message. Counted once per Subscription.                                                                        |

For detailed metric definitions across all channels, see the [Metrics Glossary](./analytics-metrics-glossary).

<Card title="Card"> Card is the view or page of the message. Important when using carousels.</Card>
<Card title="Block"> Block is the element of the message.</Card>
<Card title="CTR"> Click-Through Rate is measured by ((Clicks of all blocks - Close Button)/Impressions) \* 100% </Card>

## Conversions

<Info>
  **Coming soon** — [Conversion metrics](/docs/en/conversion-metrics) will be available on message reports. Once available, you will see attributed and influenced conversions for each message directly in its report. See [Conversion metrics](/docs/en/conversion-metrics) for details on the attribution model and setup instructions.
</Info>

***

## Audience activity

The **Audience activity** report shows how each subscription interacted with a specific message. Results are grouped into categories so you can quickly see how recipients engaged.

<Frame>
  <img alt="Audience activity screenshot" />
</Frame>

<Tabs>
  <Tab title="Categories">
    | Category          | Description                              |
    | ----------------- | ---------------------------------------- |
    | **Impression**    | The message was displayed on the device. |
    | **Clicked**       | User clicked the notification.           |
    | **Did Not Click** | User did not click the notification.     |

    Each tab displays the number of recipients in that category and lets you drill into the individual subscription records.
  </Tab>

  <Tab title="Table columns">
    | Column              | Description                                                       |
    | ------------------- | ----------------------------------------------------------------- |
    | **External ID**     | Your system identifier (if set).                                  |
    | **OneSignal ID**    | Unique OneSignal user ID.                                         |
    | **Subscription ID** | Unique subscription instance (device + app/browser).              |
    | **Device**          | Browser or OS type. If you see `()`, the device has been deleted. |
    | **Impression**      | Timestamp when the notification was displayed on the device.      |
    | **Clicked**         | Timestamp if the user clicked, or `-` if not.                     |
  </Tab>
</Tabs>

<Note>
  Audience activity data is only available for **30 days** from the time the message is displayed. Export results if you need to retain them longer.
</Note>

***

### Why audience activity is helpful

Audience activity helps you go beyond delivery counts by showing which specific users fall into each outcome. Use it to:

* **Measure engagement** by comparing clicks vs. non-clicks.
* **Diagnose notification visibility** by confirming impressions.
* **Segment audiences** for retargeting or export.

***

### Exporting results

You can download audience data with the **Export** menu:

* **Selected activity** – exports only the currently viewed tab (for example, all users who did not click).
* **All activities** – exports the full report across every category.

Exports let you analyze results offline, share with other teams, or merge with your CRM and analytics tools.

## FAQ

### Why are there fewer clicks than impressions?

* In-App Messages can be "swiped away" or automatically dismissed after a certain amount of time has passed. See [Advanced Settings](./in-app-messages-setup).

### Why are there more clicks than impressions?

* Multiple blocks can be clicked on the same impression of an In-App Message.

### Why do I see "Deleted" blocks?

* If you add/remove/update a card or block of an In-App Message, it will delete the old blocks and add new ones. The old blocks will be labeled with "Deleted" and keep their current impression and click data.

* For example, a "Deleted body", "Deleted Element" and/or "Deleted close\_button" means a change occurred in the IAMs body/text and close blocks.

***


# In-app troubleshooting
Source: https://documentation.onesignal.com/docs/en/in-app-message-troubleshooting

Common questions and troubleshooting steps about in-app messages.

This guide covers common questions and troubleshooting steps about in-app messages.

## Advanced design troubleshooting

How to check the in-app design across different devices while using the browser. These steps use Chrome version 138 on macOS.

1. Open the in-app message block editor.
2. In the preview, right click any in-app message block and select "Inspect".
3. In the Elements tab, go up the DOM tree to find the `#document` element.

<Frame>
  <img alt="The #document element in the Elements tab of the in-app message block editor" />
</Frame>

4. Right click the link in the `#document` element and select "Open in new tab".
5. You will see the in-app message design in a new tab.
6. Right click the new tab's in-app message design and select "Inspect" again.
7. In the Elements tab, select the "Toggle device toolbar" button.

<Frame>
  <img alt="The Toggle device toolbar button in the Elements tab of the in-app message block editor" />
</Frame>

8. Update the dimensions to see how it would look on different devices. We recommend testing on the `iPhone SE` (375x667) and `iPad Pro` (1024x1366).

<Frame>
  <img alt="Test different device dimensions from within Chrome DevTools" />
</Frame>

## What are the minimum Android and iOS versions that can receive in-app messages?

The minimum Android version that can receive in-app messages is 4.4. If a device is under this version the in-app message will not show.

The minimum iOS version that can receive in-app messages is 10.0. If a device is under this version the in-app message will not show.

## What are the recommended image dimensions?

We show In-App messages based on the dimensions of the phone currently being displayed on. There are a few common aspect ratios for devices and resolutions (especially for Android) which could all affect the viewing of the In-App messages.

A `16:9` aspect ratio is the most common for devices, but `4:3` and `3:2` aspect ratios are close compromises.

## Can I create an in-app via the API?

Currently all In-App messages need to be created through the OneSignal dashboard.

On each page of your app, you can set our `addTrigger` method and through your own API requests to your app, feed in the trigger `key:value` set within the dashboard to trigger the IAM based on your own network requests.

## I've updated my in-app, when do in-app changes take effect?

Once you update an In-App messages from the dashboard. The changes will go into effect immediately and end-users will see the updated message after the app has been closed for 30 seconds before re-opened.

More details, see: [Why is IAM Data Not Updating?](#why-are-in-app-messages-data-not-updating).

## Is tag substitution or message personalization available?

Yes, Tag Substitution will be supported only on iOS SDK version 2.16.4+ and Android SDK version 3.16.0+

You can use Tags to personalize the content and click action behavior of your users.

## How do I send in-apps with message localization?

Currently, you can set up different in-app messages for different languages and target a [Segment](./segmentation) based on the device language filter.

## Why are my in-app messages showing blank or all white?

In-app messages use webviews to display the content. If you are sending content within the message but it shows blank, then you may be changing the layout constraints. Check your app's custom webview settings. A common example to check on Android is the `WindowManager.LayoutParams`.

## Why are in-app messages' data not updating?

### Design updates

Changes made to the In-App Message within the OneSignal dashboard will reflect in the app once the app has been closed for 30 seconds. Make sure after you save any changes to the IAM, you have the app closed or put into the background for 30 seconds, then when you open it, you will see the changes upon the next time it is triggered.

Using the **Send to Test Device** button does not reflect any Tag Substitutions. You must trigger the IAM normally to see Tag Substitution Personalizations.

### Analytics, clicks, impressions updates

Using the **Send to Test Device** button does not contribute to the IAM analytics. You must trigger the IAM without using this button to see stats updates.

If you are not using the **Send to Test Device** button then you can troubleshoot the issue following this guide on [Capturing a Debug Log](./capturing-a-debug-log). If you still need assistance, share the full logs from app start till the end of reproduction as a .txt file with our support team at `support@onesignal.com`.

## Duplicated in-app messages

Common reasons In-App Messages may appear duplicated on the device are:

* Multiple IAMs that look the same are active.
* The message is being triggered too frequently. Check the [How to add Triggers](./iam-triggers) and [How often do you want to show this message?](./in-app-messages-setup) options.

If you are seeing this on Android only, then this can happen when clicking the back button or transitioning Activity's while the IAM is showing. Both will cause the IAM to appear again.

This is being caused by the IAM `View` being a child of the current `Activity`. Whenever intents between activities occur, the IAM will mimic the life-cycle of the current `Activity` and in some cases will cause flickering. The most common case is the IAM will hide itself and then reshow once in the new Activity.

Unfortunately this functionality is the closest available without needing any permissions to show the IAM on an `Application` level. More details in this open [GitHub issue](https://github.com/OneSignal/OneSignal-Android-SDK/issues/952). Feel free to respond to our Engineers directly on the Github issue. Also, our SDKs are Open Source, so if you had some ideas for a fix or other solution, we would gladly look into any PRs submitted!

If you are still having this issue and it is not one of the reasons above, please share the following details with our support team:

* Version of the OneSignal SDK(s) used
* Device OS version(s)
* Xcode log or Android Studio logcat from the app starting and the problem point
* Any other libraries or plugins in your app
* Details on reproducing your problem.

***


# In-app overview
Source: https://documentation.onesignal.com/docs/en/in-app-messages-setup

Display targeted, customizable messages inside your mobile app to drive engagement, collect feedback, and prompt actions like push opt-in.

In-app messages (IAM) are customizable, targeted messages that display within your mobile app. They enable you to:

* Prompt User actions like subscribing to push notifications or updating their location
* Promote new or underutilized features to targeted Users
* Display announcements and news in real time without releasing an app update
* Create surveys and carousels
* Help with onboarding and educational content

<Frame>
  <img alt="Examples of in-app messages including promotions, surveys, and feature announcements" />
</Frame>

***

## In-app setup

You must have the OneSignal SDK installed in your app to use in-app messages. Once the SDK is integrated, you can create and send in-app messages from the OneSignal dashboard without writing any code. The SDK also provides methods for advanced use cases like:

* Triggering the message at specific times
* Click handling and deep linking
* Pausing the message
* Lifecycle management

<Columns>
  <Card title="Mobile SDK setup" icon="mobile" href="./mobile-sdk-setup">
    Add OneSignal to your mobile app codebase.
  </Card>

  <Card title="In-app message SDK methods" icon="code" href="./mobile-sdk-reference#in-app-messages">
    Access trigger, click handler, and lifecycle APIs.
  </Card>

  <Card title="In-app triggers" icon="bolt" href="./iam-triggers">
    Control when messages appear based on User behavior or app activity.
  </Card>

  <Card title="In-app click actions" icon="hand-pointer" href="./iam-click-actions">
    Define what happens when Users interact with your message.
  </Card>
</Columns>

***

## Send in-app messages

You can send in-app messages from the OneSignal dashboard and within Journeys.

<Frame>
  <iframe title="YouTube video player" />
</Frame>

<Columns>
  <Card title="Dashboard" icon="window-maximize" href="#send-from-the-dashboard">
    Compose and send in-app messages from the OneSignal dashboard.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build automated, multi-step, and multi-channel flows.
  </Card>
</Columns>

### Send from the dashboard

<Steps>
  <Step title="Select the message channel" icon="window-maximize">
    Select **Create...** then choose your message channel. You can also navigate to **Messages** or **Templates** to view previous messages.

    <Frame>
      <img alt="OneSignal dashboard showing create message options" />
    </Frame>
  </Step>

  <Step title="Choose a composition method" icon="pencil">
    * Start from scratch with the [Block Editor](./design-your-in-app-message) or [HTML Editor](./design-your-in-app-message-with-html)
    * Use a pre-built [template](./templates)
  </Step>

  <Step title="Set a name and label" icon="tag">
    Add internal metadata for tracking and reporting. API equivalent: `name`
  </Step>

  <Step title="Select your audience" icon="users">
    Choose which users receive the message. You can include and exclude [segments](./segmentation) to target specific groups. Defaults to all "Subscribed Users" if no segment is set.

    <Frame>
      <img alt="Dashboard fields for message name, label, and audience segment selection" />
    </Frame>

    <Note>
      In-app messages are delivered to all [mobile Subscriptions](./subscriptions) in the Segment, regardless of push opt-in status. However, if your message contains a push prompt [click action](#click-actions), it will not show to subscribed (opted-in) mobile Subscriptions.
    </Note>
  </Step>
</Steps>

### Message design

Use the visual drag-and-drop editor or the HTML editor for more control.

<Frame>
  <img alt="OneSignal in-app message block editor showing drag-and-drop design interface" />
</Frame>

<Columns>
  <Card title="Design your in-app message" icon="pen-ruler" href="./design-your-in-app-message">
    Full reference for the in-app message editor, blocks, and Carousel.
  </Card>

  <Card title="Design with HTML" icon="code" href="./design-your-in-app-message-with-html">
    Full control for developers to customize messages.
  </Card>

  <Card title="Pre-built HTML templates" icon="clone" href="./in-app-html-templates">
    Start from tested layouts and campaigns.
  </Card>

  <Card title="In-app JavaScript APIs for HTML" icon="brackets-curly" href="./in-app-message-api">
    Add OneSignal click actions to your HTML messages.
  </Card>

  <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
    Add dynamic content to personalize messages for each User.
  </Card>

  <Card title="Multi-language messaging" icon="language" href="./multi-language-messaging">
    Localize your content for global audiences.
  </Card>
</Columns>

### Click actions

Customize what happens when Users click elements in your message.

<Frame>
  <img alt="OneSignal in-app message editor showing click action dropdown options" />
</Frame>

<Columns>
  <Card title="Click actions" icon="hand-pointer" href="./iam-click-actions">
    Configure what happens when Users click elements in your message.
  </Card>

  <Card title="Event Streams" icon="signal-stream" href="./event-streams">
    Track interactions with the message.
  </Card>

  <Card title="SDK click handler" icon="code" href="./mobile-sdk-reference#addclicklistener-in-app">
    React to click events with the mobile SDK.
  </Card>

  <Card title="Deep linking" icon="arrow-up-right-from-square" href="./deep-linking">
    Navigate Users to specific screens on click.
  </Card>
</Columns>

### Triggers

Define when messages should appear during app sessions.

<Frame>
  <img alt="OneSignal dashboard showing in-app message trigger configuration options" />
</Frame>

Four trigger types are available:

* **On app open**: Display when the User launches the app.
* **Session duration**: Delay a set number of seconds after app open.
* **Since last message**: Delay a set time after the last in-app message was shown.
* **[Custom triggers](./iam-triggers)**: Controlled via the SDK `addTrigger(s)` method for precise timing based on User behavior.

### Dismiss behavior

Messages can dismiss:

* On User interaction (click, swipe)
* After a set time (auto-dismiss)

<Frame>
  <img alt="OneSignal dashboard showing in-app message auto-dismiss timer set to 90 seconds" />
</Frame>

### Schedule and frequency

* **Start showing**: When the message becomes eligible to display
* **Stop showing**: Set an end date/time or "Show forever"

#### Display frequency

* **Only once** (default)
* **Every time** trigger conditions are met
* **Multiple times** with custom repeat logic

Examples:

* Show **2 times** with a **1 hour** gap
* Show **12 times** with a **30 day** gap

<Frame>
  <img alt="OneSignal dashboard showing in-app message frequency set to 12 times every 30 days" />
</Frame>

***

## How in-app messages are shown

In-app messages are not actively pushed. Instead, they're pulled at app start based on audience, then displayed based on trigger logic.

<Frame>
  <img alt="Flowchart showing the lifecycle of an in-app message from audience check to display" />
</Frame>

The message displays if:

1. The User meets audience criteria **before** a new session starts.
   * A new session starts when the User opens your app after it has been in the background or closed for at least 30 seconds.
   * If the User has the app open when the message goes live or enters the Segment during the same session, they must close or background the app for at least 30 seconds to be eligible.
2. The trigger conditions are met.
3. The scheduled time and frequency are valid.

If Segment criteria change mid-session, the User must reopen the app to see the message.

### Testing

<Steps>
  <Step title="Add verbose logging to your app">
    Add the [`setLogLevel` method set to `Verbose`](./mobile-sdk-reference#setloglevel) in your app to get more detailed logs.
  </Step>

  <Step title="Make sure your Subscription is in the Segment">
    As explained in [How in-app messages are shown](#how-in-app-messages-are-shown), the User must match the audience criteria **before a new session starts**.

    * See [Find devices and set test Users](./test-users) if you don't know your device's Subscription ID.
    * Make sure your device's Subscription is in the included Segment(s) and not in the excluded Segment(s).

    <Tip>
      Add your device as a test user and create or update the Segment to include the **Test Users** filter.
    </Tip>
  </Step>

  <Step title="Close or background the app for at least 30 seconds">
    This ensures you open the app to create a new session and become eligible for the message.
  </Step>

  <Step title="Check trigger conditions">
    Make sure you satisfy the [triggers](#triggers) for the message to be shown.
  </Step>

  <Step title="Check the schedule and frequency">
    * Make sure the "Start showing" and "Stop showing" dates are set correctly.
    * Set [display frequency](#display-frequency) to "Every time trigger conditions are satisfied" while testing.
  </Step>

  <Step title="Update the message and make sure it is active">
    Once the message is active, open the app on your device. You should see the message display based on your trigger conditions.
  </Step>
</Steps>

### Test and preview

The **Test & Preview** button sends a push notification to your selected test device. When you click the push to open the app, the in-app message displays.

Requirements and notes:

* Your device must be a [test User](./test-users)
* Your device must be subscribed to push — test in-app messages are triggered via push notification (this is not required for normal in-app messages)
* Push is only sent for testing purposes and will not be sent when the message is live
* If you are not seeing the message, follow the [testing steps](#testing) above
  <Warning>Tag substitution does not work for test in-app messages.</Warning>

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***

## Tutorials and use cases

<Columns>
  <Card title="Personalize in-app messages" icon="wand-magic-sparkles" href="./personalization-properties-and-tags">
    Personalize your in-app message content with Tags.
  </Card>

  <Card title="Target outdated app versions" icon="mobile" href="./app-version-update">
    Prompt Users to update their app.
  </Card>

  <Card title="App store review prompts" icon="star" href="./example-app-store-review">
    Increase your ratings with timely review requests.
  </Card>

  <Card title="Create User surveys" icon="square-poll-vertical" href="./example-create-a-survey">
    Collect feedback inside your app.
  </Card>

  <Card title="Push permission prompts" icon="bell" href="./prompt-for-push-permissions">
    Improve push opt-in rates with pre-permission prompts.
  </Card>

  <Card title="Location permission prompts" icon="location-dot" href="./location-opt-in-prompt">
    Ask Users to enable location tracking.
  </Card>

  <Card title="Set up a tutorial" icon="graduation-cap" href="./example-create-a-tutorial">
    Guide Users through new features of your app.
  </Card>
</Columns>

***

## Analytics

Track message performance and engagement.

<Columns>
  <Card title="In-app message reports" icon="chart-line" href="./in-app-message-reports">
    Impressions, clicks, dismissals, and conversion metrics for in-app messages.
  </Card>

  <Card title="Analytics overview" icon="chart-bar" href="./analytics-overview">
    All analytics options available in OneSignal.
  </Card>

  <Card title="Event Streams" icon="signal-stream" href="./event-streams">
    Stream push events to your data warehouse or BI tools in real time.
  </Card>
</Columns>

***

## FAQ

### Do in-app messages require push notification permission?

No. In-app messages are delivered to all mobile Subscriptions in the target Segment, regardless of push opt-in status. They display inside the app during an active session.

### Why isn't my in-app message showing?

The most common cause is that the User's session didn't refresh. The User must close or background the app for at least 30 seconds, then reopen it to start a new session. Also verify the User is in the target Segment and that trigger conditions are met. See [Testing](#testing) for a full checklist.

### Can I send in-app messages via the API?

You must create in-app messages within the OneSignal dashboard.

You can include the in-app message within [Journeys](./journeys-overview) and enter the user into the Journey via [Custom Events](./custom-events) triggered from the API.

### How are in-app messages different from push notifications?

In-app messages display inside your app while the User is actively using it. Push notifications appear on the device's notification tray and can reach Users even when the app is closed. In-app messages do not require push permission and are pulled at session start rather than pushed from the server.

### Can I use in-app messages on web?

No. In-app messages are only available for mobile apps with the OneSignal mobile SDK installed. For web, consider using [web push notifications](./web-push-setup) instead.


# iOS: Focus modes and interruption levels
Source: https://documentation.onesignal.com/docs/en/ios-focus-modes-and-interruption-levels

Understanding device settings and how they interact with push

Focus modes help iOS users control when and how they receive notifications by allowing separate modes like Work, Sleep, and Personal. Each mode adjusts notification visibility and delivery behavior.

To support important use cases like emergency alerts or account security, Apple introduced **Interruption Levels** to control how and when notifications appear—even when Focus modes are active.

## Interruption levels

Interruption levels determine the urgency and delivery behavior of notifications. There are four levels:

<Columns>
  <Card title="Active (default)" icon="play">
    Standard priority notifications. These include sound, vibration, and screen wake behavior. They do not bypass Focus modes.
  </Card>

  <Card title="Time Sensitive" icon="hourglass">
    Behaves like Active but includes a special banner. Time Sensitive notifications can break through Focus modes and scheduled delivery. Use only when urgent user attention is required.
  </Card>

  <Card title="Passive" icon="paper-plane">
    Low-priority notifications. No sound or vibration. They do not interrupt the user and do not break through Focus modes.
  </Card>

  <Card title="Critical" icon="triangle-exclamation">
    Highest priority notifications. Bypass all device controls and Focus modes. Used for emergencies like severe weather or health alerts. Requires prior approval from Apple to enable. See [Critical alerts setup](#critical-alerts-setup) for more details.
  </Card>
</Columns>

<Frame>
  <img />
</Frame>

***

## How to set interruption level in OneSignal

When sending a push from the OneSignal Dashboard, you'll find **Notification Interruption Level** under **Apple iOS Settings**. The default is **Active**.

If using the [Create notification API](/reference/create-message), use these parameters:

* `ios_interruption_level`: Set to `"active"`, `"time-sensitive"`, `"passive"`, or `"critical"`
* `ios_relevance_score`: Optional numeric value from 0 to 1 to indicate importance for delivery ordering.

***

## Critical alerts setup

**Critical Alerts:**

* Ignore Do Not Disturb and silent switch.
* Are reserved for high-priority cases (e.g., health, security).
* Require explicit approval from Apple, and users must opt in separately even if they’ve enabled normal push notifications.

### Request Apple entitlement for critical alerts

1. Review [Apple's documentation](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.usernotifications.critical-alerts/) and click **fill out the request form**.
2. Choose the Critical Alerts Entitlement request.
3. Fill out the form and submit the request.
4. Wait for Apple’s review and approval.

### Add the Critical Alerts entitlement to your app

Once Apple approves your request:

1. Open your `.entitlements` file in Xcode (or create one if you don't have it).
2. Add:

```xml theme={null}
<key>com.apple.developer.usernotifications.critical-alerts</key>
<true/>
```

3. Ensure your provisioning profile includes this entitlement:

* Regenerate your provisioning profile in the Apple Developer portal if needed.
* Download and re-add it to Xcode.

### Request Critical Alert permission in your app code

Critical Alert permission is separate from standard push permission and must be requested like this (using Swift):

```swift theme={null}
import UserNotifications

UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge, .criticalAlert]) { granted, error in
    if let error = error {
        print("Authorization error: \(error)")
    } else {
        print("Critical alert permission granted: \(granted)")
    }
}
```

<Warning>
  You should request this after getting standard push permission, ideally in your onboarding flow.
</Warning>

### Test Critical Alerts

1. Build and run your app.
2. Send a test push following the steps above in [How to set interruption level in OneSignal](#how-to-set-interruption-level-in-onesignal).

***

## Related docs

* [iOS: Relevance score](./ios-relevance-score)
* [Push overview](./push)

***


# iOS provisional push notifications
Source: https://documentation.onesignal.com/docs/en/ios-provisional-push-notifications

Provisional push notifications on iOS let your app send notifications without an upfront permission prompt, but with reduced visibility.

Provisional push notifications (also known as Direct-to-History) are an iOS 12+ feature that lets your app send push notifications without first requesting explicit permission. Users receive these notifications silently in the Notification Center, giving them a chance to decide whether to keep or turn off notifications from your app.

Because these notifications are provisional, they have reduced visibility compared to standard push notifications:

* No banner displayed
* No sound played
* No lock-screen alert
* Delivered directly to the Notification Center

<Frame>
  <img alt="iOS provisional push notification with Keep and Turn Off options" />
</Frame>

## How users interact with provisional notifications

When a user receives a provisional notification, they can select **Keep...** to see these options:

* **Deliver Quietly** — Keeps notifications silent and only visible in the Notification Center. This also removes the "Keep..." and "Turn Off..." prompts from future notifications.
* **Turn Off** — Unsubscribes the user from all notifications from your app.

<Frame>
  <img alt="iOS prompt showing Deliver Quietly, Turn Off, and Settings options" />
</Frame>

You can still prompt users for standard push permission even after they choose Deliver Quietly or Turn Off. However, if you prompt for regular push permission and the user denies it, they will not receive any further push notifications — including provisional ones.

***

## Enable or disable provisional authorization

To toggle provisional authorization, go to your OneSignal dashboard: **Settings > Apple iOS > Advanced Configuration** and check or uncheck the **Enable iOS 12 direct to history** option. This is unchecked by default.

<Note>
  Provisional authorization requires OneSignal SDK 2.9.0 or newer.
</Note>

<Frame>
  <img alt="OneSignal Advanced Configuration panel with the iOS 12 direct to history checkbox" />
</Frame>

***

## FAQ

### What is the difference between provisional and normal authorization?

With provisional authorization enabled, iOS 12+ subscribers automatically receive push notification permissions the next time they open your app — no permission prompt is shown. Your app can still request standard push permissions separately, which displays the native iOS permission prompt. If the user denies that standard prompt, provisional notifications are also turned off.

For details on configuring your permission prompting flow, see [Prompt for push permissions](./prompt-for-push-permissions).

### What happens if a user denies the regular push prompt?

Denying the standard iOS push permission prompt turns off all push notifications for your app, including provisional notifications. The user would need to re-enable notifications manually through iOS Settings.

***

<Card title="Prompt for push permissions" icon="bell" href="./prompt-for-push-permissions">
  Configure when and how your app requests standard push notification permissions from users.
</Card>


# iOS: Relevance score
Source: https://documentation.onesignal.com/docs/en/ios-relevance-score

How you can set a relevance score

<Frame>
  <img />
</Frame>

Apple’s Relevance Score allows you to indicate the importance of each push notification or Live Activity update. This score helps iOS determine how prominently to display your notifications in the Notification Summary (for push) or Dynamic Island/Lock Screen (for Live Activities).

<Frame>
  <img />
</Frame>

***

## Relevance Score for push notifications

The relevance score is a value from `0.0` to `1.0` that signals to the system the importance of a notification. Notifications with higher relevance scores are shown more prominently in the user’s Notification Summary, which you can configure for scheduled delivery times.

1. Make sure you followed our [Mobile SDK setup](./mobile-sdk-setup) docs for iOS that implement the Notification Service Extension. This extension allows you to customize payloads, including relevance score.

2. When creating a [Push](./push) message, under iOS options, specify the **Relevance Score** from 0.0 (least important) to 1.0 (most important).

<Warning>
  Reserve a score of `1.0` for the most critical messages. Overusing high scores will cause the system to ignore the distinction, making them all blend together in summary.
</Warning>

Example use cases:

* New Direct Messages set to `1.0`
* Promotional alerts set to `0.2`
* Daily reminders set to `0.6`

<Tabs>
  <Tab title="Dashboard">
    When creating a message from the dashboard, you can select the **Relevance Score** under the Apple iOS platform settings:

    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="API">
    <ParamField type="double">
      [ios\_relevance\_score](/reference/push-notification#body-ios-relevance-score) is a value between 0 and 1, to sort the notifications from your app. The highest score gets featured in the notification summary.
    </ParamField>

    ```bash Request theme={null}
    curl --request POST \
     --url 'https://api.onesignal.com/notifications?c=push' \
     --header 'Authorization: <authorization>' \
     --header 'Content-Type: application/json' \
     --data '{
         "app_id": "YOUR_APP_ID",
             "include_aliases": {
                 "external_id": ["EXTERNAL_ID"],
             },
             "contents": {
                 "en": "English Message"
             },
             "ios_relevance_score": 0.5
     }'
    ```
  </Tab>
</Tabs>

***

## Relevance Score for Live Activities

If your app starts multiple Live Activities, the one with the highest relevanceScore is prioritized for display in the Dynamic Island. If two or more Live Activities share the same score, the system will show the earliest-started activity. On the Lock Screen, the relevanceScore also determines the display order of your app's Live Activities.

When using our [Update Live Activity API](/reference/update-live-activity-api), set the `ios_relevance_score` to any *`double`* data type value between `0.0` and `1.0`.

***


# Journeys overview
Source: https://documentation.onesignal.com/docs/en/journeys-overview

Automated multichannel messaging flows that send email, push, SMS, and in-app messages based on user behavior, time delays, or profile attributes.

OneSignal Journeys let you build personalized, automated messaging flows across **email**, **push notifications**, **SMS**, **in-app messaging**, and **web push**—all without writing a single line of code.

<Frame>
  <iframe title="Introduction to OneSignal Journeys" />
</Frame>

***

## What you can do with Journeys

Journeys allow you to automate lifecycle messaging based on user behavior, time delays, or profile attributes. Common use cases include:

* **Onboarding sequences** to guide new users to their "aha" moment and ensure early success.
* **Re-engagement campaigns** that target users who haven’t returned after a certain period.
* **Abandoned cart flows** that remind users to complete purchases and recover lost revenue.
* **Upsells, cross-sells, and announcements** to increase feature adoption and promote new offerings.
* **Behavioral followups** that trigger messages when users perform specific actions or meet criteria.

<Frame>
  <img alt="Journey canvas showing entry, wait, branching, and message steps" />
</Frame>

***

## Best practices for multichannel journeys

Journeys work best when you combine multiple channels so each message reaches the user through the most effective format.

### Mix channels for maximum engagement

Use different messaging types strategically:

* Start with a **welcome email**
* Follow up with a **push notification**
* Announce promotions via **in-app message**
* Send time-sensitive reminders through **SMS**

Mixing channels improves visibility, reduces fatigue, and ensures messages are relevant in context.

### Use External IDs to unify your users

To avoid sending confusing or duplicate messages across channels, assign an **External ID** to every user.

If an External ID is **not set**:

* Each subscription (email, device, SMS number) is treated as a **separate user**
* You may **over-message or confuse** your users

With an External ID:

* OneSignal links all subscriptions to a **single user profile**
* You get accurate targeting and smoother Journeys

<Columns>
  <Card title="Users" icon="user" href="./users">
    Define and manage users, assign External IDs, and track engagement across channels.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    How OneSignal tracks activity across devices and channels and ties it to unified user profiles.
  </Card>
</Columns>

***

## Journey components

Journeys are made up of modular components that give you complete control over who enters, what they receive, and when.

<Columns>
  <Card title="Journey settings" icon="gear" href="./journeys-settings">
    Configure entry and exit rules, re-entry logic, and scheduling for your Journey.
  </Card>

  <Card title="Journey messages" icon="paper-plane" href="./journeys-messages">
    Add push, email, SMS, and in-app message steps with personalized content.
  </Card>

  <Card title="Journey actions" icon="code-branch" href="./journeys-actions">
    Add branching logic, wait steps, split paths, and delays to build conditional flows.
  </Card>

  <Card title="Journey webhooks" icon="webhook" href="./journeys-webhook">
    Send real-time updates to CRMs, analytics platforms, and other external tools.
  </Card>
</Columns>

***

## Journey analytics and management

Understand how your Journeys are performing and keep them optimized over time.

<Columns>
  <Card title="Journey analytics" icon="chart-line" href="./journeys-analytics">
    Monitor completion rates, conversions, drop-offs, and per-message performance.
  </Card>

  <Card title="Managing Journeys" icon="list-check" href="./managing-journeys">
    Pause, edit, duplicate, archive, and version-control your Journeys.
  </Card>
</Columns>

***

## Journeys examples

Need inspiration or a quick-start template? These examples walk through common Journey flows you can adapt for your use case.

<Card title="Journeys examples" icon="lightbulb" href="./journeys-examples">
  Step-by-step walkthroughs for onboarding, re-engagement, abandoned carts, and more.
</Card>

<Info>
  If you previously used Automated Messages, Journeys replace that feature with more powerful cross-channel orchestration. Migrate your existing automations to Journeys for branching logic, multichannel support, and analytics.
</Info>

***

## FAQ

### How many Journeys can I have active at once?

The number of active Journeys depends on your plan. See [pricing](https://onesignal.com/pricing) for your plan's limit.

### Can a user be in multiple Journeys at the same time?

Yes. A user can be active in multiple Journeys simultaneously. Use [Journey settings](./journeys-settings) to control re-entry rules and prevent duplicate messages.

### What channels do Journeys support?

Journeys support **email**, **push notifications** (mobile and web), **SMS**, and **in-app messages**. You can combine all of these in a single Journey.

### What happens if a user unsubscribes from one channel mid-Journey?

The user continues through the Journey, but message steps for that channel are skipped. For example, if a user unsubscribes from email, they still receive push and SMS steps.

### Do I need External IDs for Journeys to work?

External IDs are strongly recommended. Without them, each subscription (email address, device, phone number) is treated as a separate user, which can lead to duplicate or conflicting messages. See [Users](./users) for setup details.


# Journey settings
Source: https://documentation.onesignal.com/docs/en/journeys-settings

Configure your Journey including who enters, exits, re-enters, and when it starts or stops.

Journey settings control who enters, when they exit, whether they can re-enter, and when the Journey starts or stops.

## Naming and describing your Journey

When you click **Create Journey**, a modal appears (only once per new Journey) prompting you to:

* Enter a **Journey Name** (required)
* Enter a **Description** (optional)

**Validation rules:**

* Journey name is required.
* Name maximum length: **300 characters**
* Description maximum length: **255 characters**

Click **Continue** to save the Journey and open the Settings panel.

If you click **Cancel**, OneSignal creates the Journey with a default auto-generated name (for example, `New Journey YYYY-MM-DD`) and an empty description.

<Note>
  The initialization modal does not appear when duplicating a Journey or creating one from a template.
</Note>

### Editing name and description

After creation, the **Journey Name** and **Description** appear at the top of the page and can be edited inline. The description field supports multi-line text.

Start by giving your Journey a name and description that clearly communicate its purpose to your team. Common examples include:

* Abandoned Cart
* Welcome Campaign
* Inactive User Reach Out

<Frame>
  <img alt="Journey Settings screen" />
</Frame>

<Accordion title="Goals (Beta)" description="Set success metrics for Journeys and supported message steps to measure performance over time.">
  <Note>
    **Beta feature:** Journey and Message Goals are currently in **Beta** and available in early access. Functionality may change before general availability.
  </Note>

  Goals help you measure whether your Journey or a specific message inside it is performing the way you expect.

  A goal is a metric threshold like “more than 1 user entered the Journey” or “CTR is greater than 20%”—that OneSignal continuously evaluates as your Journey runs.

  You can configure goals in two places:

  * **Journey Goal** (overall Journey performance)
  * **Message Goal** (for individual message action steps that support goals)

  Goals are not currently supported for Journey action steps.

  ### Journey Goal

  A Journey Goal tracks a single success metric for the entire Journey, for example whether users are entering, exiting, or completing it.

  <Frame>
    <img alt="Journey Settings with a Journey Goal configured" />
  </Frame>

  To set a Journey Goal:

  1. Open your Journey and click **Settings**.
  2. Select **Goals**.
  3. Enable **Set a Journey Goal**.
  4. Enter a **Name** (required) and optional **Description**.
  5. Choose a **Metric** and condition, then set the **Value** threshold.
  6. Click **Save**.

  Once configured, your Journey Goal appears at the top of the Journey report with its current value.

  <Frame>
    <img alt="Journey report showing the Journey Goal and current progress" />
  </Frame>

  #### Journey Goal metrics

  Journey Goals support Journey-level engagement metrics such as:

  * **Entered Journey** (users who started the Journey)
  * **Completed** (users who reached the end)
  * **Exited Early** (users who left due to exit rules)

  Use Journey Goals when you want a quick health check like:

  * “Did at least 100 users enter this Journey?”
  * “Are most users completing it?”
  * “Are too many users exiting early?”

  ***

  ### Message Goals (Push + other supported message steps)

  Message steps support their own **Message Goal**, which measures performance for that specific message. For example, a Push Notification step can track CTR, confirmations, or clicks.

  <Frame>
    <img alt="Push step settings showing Message Goal configuration" />
  </Frame>

  To set a Message Goal:

  1. Click the message action step in your Journey (for example, **Push Notification**).
  2. In the editor, enable **Set a Push Goal** (or equivalent goal toggle).
  3. Enter a **Name** and optional **Description**.
  4. Select a **Metric**, condition, and **Value**.
  5. Click **Save**.

  When the message is sent, the goal appears in the message-level report so you can monitor whether that message is meeting your benchmark.

  <Frame>
    <img alt="Message report showing goal status and delivery metrics" />
  </Frame>

  #### Message Goal metrics (Push)

  Push goals support delivery and engagement metrics such as:

  * **Sent**
  * **Delivered**
  * **Confirmed**
  * **Clicked**
  * **CTR**
  * **Failed**
  * **Unsubscribed**
  * **Capped**

  Some metrics may allow you to track either:

  * **Rate** (percentage-based), like CTR
  * **Count** (total number), like clicks
</Accordion>

## Entry rules

Entry rules define how users can enter your Journey based on their segment membership or custom events.

Entry rules cannot combine Segments and Custom Events. You must choose one type per Journey. You can still use Custom Events to continue users through a Journey via the [Wait until step](./journeys-actions#wait-until).

Once a Journey is set live, you cannot switch between Segment-based and Custom Event-based entry rules. To change the entry type, stop and archive the Journey, duplicate it, then configure the new entry rules.

<Frame>
  <img alt="Segment-based Journey entry rule configuration" />
</Frame>

### Audience segment

Use **Include Segment** and **Exclude Segment** to control who qualifies for your Journey. Users who match the defined Audience will enter the journey. If re-entry rules are set, a user who matches the Audience but have exited the journey will continue to re-enter the journey each time those rules are met. In segment-driven journeys, a user can only be active in the journey once at a time. They can re-enter after exiting, as long as they meet the journey's [re-entry](#re-entry-rules) conditions.

Segment checks are done at the Subscription level and consider all of a user's Subscriptions. See [Exit rules](#exit-rules) for what happens when a user matches both entry and exit rules.

If a Journey is active, the segments used in its entry rules cannot be edited. To modify the segments, archive the Journey or remove the segment from the entry rules first.

#### How inclusion and exclusion logic works

* ✅ If **any Subscription** is in an **Included Segment(s)** → the user enters the Journey.
* ❌ If **any Subscription** is in an **Excluded Segment(s)** → the user is blocked entirely.

<Warning>
  Journeys evaluate audience qualification using all of a user's Subscriptions. To avoid unexpected behavior, always define both **Included** and **Excluded** Segments explicitly.

  **Example:**
  You're targeting users inactive for 60+ hours (`last_session > 60hrs`).

  * **Include**: Segment where `last_session > 60hrs`
  * **Exclude**: Segment where `last_session ≤ 60hrs`
    This prevents users with one inactive and one active Subscription from mistakenly qualifying.
</Warning>

#### Future additions only

When this option is checked, the Journey ignores all users who are already in the included or excluded segments at the time it goes live. Only users who **join the segment after launch** can enter.

This applies permanently — even if an existing user leaves the segment and re-enters later, they are still excluded.

Use this for one-time campaigns (e.g., onboarding) where current users should not receive the Journey.

<Warning>
  Once a Journey with "Future additions only" is set live, the included and excluded segments are locked and cannot be edited. If you need to change the target audience, you must **duplicate the Journey**, edit the included and/or excluded segments, and launch the new Journey.
</Warning>

### Custom events

Users enter the Journey when a [Custom Event](./custom-events) matches the entry rule. Each entry stores the event that triggered it, which you can [reference in Liquid syntax](./message-personalization#custom-events) for message personalization and use for [Event Matching](./journeys-actions#event-matching) in action steps.

* **Custom Event Name:** The event name to match, sent via SDK or API.
* **Filter by property:** Optional property conditions to further restrict which events trigger entry.

<Frame>
  <img alt="Journey custom event property filters" />
</Frame>

<Warning>
  Custom Event entry rules allow the same user to enter the Journey multiple times simultaneously. Each entry carries its own event properties.

  To limit concurrent entries, either add a property filter so only events with specific properties trigger entry, or add an [Exit rule](#exit-when-custom-event-condition-occurs) that matches the same event name used in the entry rule — this exits the current instance before the new one begins.
</Warning>

Custom events can also be used for:

* [Exit rules](#exit-when-custom-event-condition-occurs)
* [Wait Until steps](./journeys-actions#wait-until)
* [Personalization](./message-personalization)

***

## Exit rules

Exit rules define when users automatically leave the Journey. They may re-enter later based on your re-entry settings.

<Warning>
  If a user matches the entry rules and exit rules, they enter the Journey and complete the first step before exiting. You can prevent this in two ways:

  * Add a **Wait step** as the first step of the Journey.
  * Add an **Excluded Segment** to the entry rules that explicitly filters out users who should not enter. See [Audience segment](#audience-segment) for details.
</Warning>

<Frame>
  <img alt="Exit rules configuration panel in Journey settings" />
</Frame>

### Exit when user becomes active in your app/website

As soon as the user returns to your app or website with the OneSignal SDK, their "last session" updates, making them *active* again and exiting them from the Journey.

Useful for re-engagement or reactivation Journeys.

### Exit when custom event condition occurs

Send a [Custom Event](./custom-events) to exit the user from the Journey immediately.

**Using the same Custom Event for Entry and Exit Rules:** When the Exit Rule Custom Event name matches the Entry Rule Custom Event name, each occurrence of that event exits the user from the Journey and immediately enters them again. The new entry carries the latest event properties, so message personalization always reflects the most recent data.

This pattern is common for Journeys where the triggering action can repeat — like [abandoned cart](./abandoned-cart) reminders. Each cart update restarts the wait timer and refreshes the product data used in messages.

### Exit when user no longer matches the audience conditions

Automatically remove users if they stop matching the original entry rule audience segments.

### Exit when a user enters a segment

If a user enters a selected segment at any point, they are removed from the Journey and stop receiving messages.

#### Tag users when they exit early

Apply or remove a tag when users exit early.

* Leave the value blank to remove an existing tag.
* If the app is at the tag limit, no tag will be applied.

**Common use cases:**

* **Trigger another Journey:**
  Tag users (e.g. `exited-journey-1:true`), then use that tag to define a segment for your next Journey.

* **Limit concurrent Journeys:**
  Tag users when they enter (`in-journey:true`), and remove the tag when they finish or exit. This allows you to exclude them from other Journeys using that tag.

***

## Re-entry rules

Re-entry rules determine if and when users can enter the Journey again after exiting. The re-entry timer starts when the user **exits** the Journey — not when they entered.

Re-entry rules apply only to Journeys with Audience Segment [entry rules](#entry-rules). Custom Event-based Journeys always allow re-entry.

<Frame>
  <img alt="Re-entry configuration for a Journey" />
</Frame>

Use re-entry for recurring campaigns like cart abandonment or inactivity re-engagement.

<Warning>
  If your Journey uses a [time window](./journeys-actions#time-window) node for recurring sends, set the re-entry duration **longer than the time window duration** to prevent users from re-entering and receiving a second message within the same window. See [Using time windows for recurring sends](./journeys-actions#using-time-windows-for-recurring-sends) for details.

  When editing re-entry rules, the updated settings only apply to users who exit **after** the change. Earlier exits follow the original re-entry configuration.
</Warning>

***

## Schedule

Set when the Journey should start and end.

* Start the Journey immediately or at some point in the future.
  * The Journey will appear as **Scheduled** in the dashboard until the start time.
  * It automatically becomes **Active** at the configured start time.
* Allow the Journey to run indefinitely until you stop it or set a future end time.
  * If an end date is set, the Journey will be **Stopped and Archived** automatically once the end time is reached.
  * All messages immediately stop for users currently in the Journey.
  * These users will **not** trigger exit or early exit events.

### Let current users finish the Journey

To stop new users from entering but let current ones finish:

1. Update the Entry Rules Audience Segment to only **include** an empty segment (e.g. a [Test Users](./test-users) segment).
2. Update the Exit Rules to **Uncheck** "Exit when a user no longer matches the audience conditions".

This ensures existing users continue through to the end.

<Warning>
  If your account has reached its Journey limit:

  * Scheduled Journeys will **not** launch.
  * The most recent scheduler will be notified.

  To resolve, archive an active Journey, then try again.
</Warning>

***

## FAQ

### Can I change entry rules after a Journey goes live?

You cannot switch between Segment-based and Custom Event-based entry rules on a live Journey. To change the entry type, stop and archive the Journey, duplicate it, and configure new entry rules on the copy.

### Can I edit the segments used in a live Journey's entry rules?

No. Segments referenced in a live Journey's entry rules are locked. To modify them, archive the Journey or remove the segment from the entry rules first.

### How does "Future additions only" work?

When enabled, all users currently in the included or excluded segments at launch are permanently excluded from the Journey — even if they leave and re-enter the segment later. Only users who join the segment after launch can enter.

### Can a user re-enter a Journey triggered by Custom Events?

Yes. Custom Event-based Journeys always allow re-entry. Each time a matching event fires, the user enters a new instance of the Journey with that event's properties.

### What happens when the exit rule uses the same Custom Event as the entry rule?

Each occurrence of that event exits the user from the Journey and immediately starts again. The new entry carries the latest event properties, so message personalization always reflects the most recent data. This pattern is common for Journeys where the triggering action repeats, like [abandoned cart](./abandoned-cart) reminders.

## Related pages

<Columns>
  <Card title="Journeys overview" icon="route" href="./journeys-overview">
    Introduction to Journeys and what you can build with them.
  </Card>

  <Card title="Journey actions" icon="code-branch" href="./journeys-actions">
    Add branching logic, wait steps, split paths, and delays.
  </Card>

  <Card title="Journey messages" icon="paper-plane" href="./journeys-messages">
    Configure push, email, SMS, and in-app message steps.
  </Card>

  <Card title="Custom events" icon="bolt" href="./custom-events">
    Send events from your app or API to trigger Journey entry and exit.
  </Card>
</Columns>


# Keys & IDs
Source: https://documentation.onesignal.com/docs/en/keys-and-ids

Find and manage your OneSignal App ID, Organization ID, and API keys. Learn how to create, rotate, secure, and migrate keys safely.

Your OneSignal account includes **public IDs** like App ID and Organization ID and **private API keys** like App API Key and Organization API Key.

* **App ID** and **Organization ID** are public identifiers — safe to use in client-side code and SDK initialization.
* **App API Keys** and **Organization API Keys** are private secrets — store them securely and never expose them in client-side code.

This guide explains what each key does, where to find it, and how to manage it securely.

<Tip>
  **Where to find your keys:** From any app in the OneSignal dashboard, go to **Settings > Keys & IDs**. For Organization-level keys, go to **Organizations > Your Organization > Keys & IDs**.
</Tip>

***

## App ID

The **App ID** is a public UUID (v4) that identifies your OneSignal app.

You use it for:

* Initializing the SDK (Mobile SDK setup, Web SDK setup)
* Making API requests such as Create message and Create user

Find your App ID in the dashboard under **Settings > Keys & IDs** or via the [View apps](/reference/view-apps) API.

<Frame>
  <img alt="OneSignal dashboard Keys & IDs page showing App ID location" />
</Frame>

<Frame>
  <img alt="App ID value highlighted in the Keys & IDs settings page" />
</Frame>

<Check>
  Your App ID is safe to use in client-side SDK initialization. It is not a secret.
</Check>

***

## Organization ID

The **Organization ID (Org ID)** is a UUID (v4) that groups all apps under your billing plan.

You need it for Organization-level APIs such as:

* [Create an app](/reference/create-an-app)
* [Update an app](/reference/update-an-app)

Find it in **Organizations > Your Organization > Keys & IDs** or via the [View an app](/reference/view-an-app) API.

<Frame>
  <img alt="OneSignal dashboard showing Organization ID under Keys & IDs." />
</Frame>

***

## API keys overview

OneSignal supports two types of API keys:

| Key Type                 | Scope               | Used For                                                  |
| ------------------------ | ------------------- | --------------------------------------------------------- |
| **App API Key**          | Single app          | Sending messages, creating users, app-level operations    |
| **Organization API Key** | Entire organization | Creating apps, managing API keys, org-level configuration |

You can create up to 16 API keys and configure IP allowlisting.

<Warning>
  Both are **private secrets** and must be stored securely.
</Warning>

### App API key

Use an **App API Key** for most REST API requests related to a specific app.

**Authentication format:**

Include the key in the `Authorization` header with the `key` authentication scheme:

```http theme={null}
Authorization: key YOUR_REST_API_KEY
```

You can create App API Keys in **App Settings > Keys & IDs** or via the [Create API key](/reference/create-api-key) API.

<Warning>
  Treat App API Keys like passwords.

  * Never expose them in mobile or web client code.
  * Never commit them to public repositories (like GitHub).
  * Store them in a secure backend or secret manager.
</Warning>

### Organization API key

Use an **Organization API Key** for:

* **App management**: [Creating apps](/reference/create-an-app), [Viewing apps](/reference/view-apps)
* **App API key management**: [Create API key](/reference/create-api-key), [Delete API key](/reference/delete-api-key), [Rotate API key](/reference/rotate-api-key)

Create Organization API Keys in the OneSignal dashboard under **Organizations > Your Organization > Keys & IDs**.

<Frame>
  <img alt="Organization API key section in the Keys & IDs dashboard" />
</Frame>

As with app API keys, you can configure up to 16 org keys and include IP allowlisting configuration.

***

## Create API keys

You can create both App and Organization API keys from the dashboard.

* App API keys can also be created via the [Create API key](/reference/create-api-key) API.
* Organization API keys can only be created via dashboard.

**Create a key:**

1. Go to Keys & IDs (App or Organization level).
2. Click **Add Key**.
3. Enter a descriptive name (example: CRM Sync Service).
4. (Optional) Configure IP allowlisting.
5. Click **Create**.
6. Copy and securely store the key immediately.

<Frame>
  <img alt="Modal for creating a new API key in OneSignal dashboard" />
</Frame>

<Frame>
  <img alt="Generated API key displayed after creation" />
</Frame>

<Warning>
  API keys are shown only once. If you lose the key, you must rotate it.
</Warning>

### IP allowlist (optional but recommended)

You can restrict API key usage to specific IP addresses.

* Enter space-separated CIDR blocks
  * Example: `192.0.2.0/24 192.0.2.123/32`
* Requests from non-allowed IPs will be denied.

Use IP allowlisting for:

* Backend services with static IPs
* High-security production environments

<Frame>
  <img alt="IP allowlist configuration field in API key creation modal" />
</Frame>

***

## Key management

After creating a key, you can manage it via the key list interface:

<Frame>
  <img alt="API key list in OneSignal dashboard showing key names and IDs" />
</Frame>

<Info>
  The **Key ID** is a label for reference. It is not the secret API key.
</Info>

### Edit API keys

You can:

* Update the key name
* Modify IP allowlist settings

Editing does not change the secret value. No integration changes are required.

* App API keys can be updated via dashboard or the [Update API key](/reference/update-api-key) API.
* Organization API keys can only be updated via dashboard.

### Rotate API keys

Rotating a key:

* Generates a new secret
* Keeps the same name and configuration
* Immediately invalidates the old secret

**When to rotate:**

* The key was exposed
* A team member with access leaves
* Routine security rotation

<Warning>
  After rotating a key, update all services using it. Requests with the old key will fail.
</Warning>

* App API keys can be rotated via dashboard or the [Rotate API key](/reference/rotate-api-key) API.
* Organization API keys can only be rotated via dashboard.

### Delete API keys

Deleting a key:

* Permanently removes it
* Immediately blocks API access using that key

Use deletion when a key is no longer needed.

* App API keys can be deleted via dashboard or the [Delete API key](/reference/delete-api-key) API.
* Organization API keys can only be deleted via dashboard.

***

## Migrating from legacy API keys

We introduced rich API key management on November 14, 2024.

**Migration Steps**

1. Create a new App or Organization API key.
2. Replace the legacy key in your code.
3. Update your API base URL from `https://onesignal.com/api/v1/` to `https://api.onesignal.com`.
4. Disable or delete the legacy key in Keys & IDs.

<Check>
  Test API requests in a staging environment before disabling your legacy key in production.
</Check>

***

## Disabling your app

**Block API access:**

* Delete or rotate API keys to immediately block REST API usage.

**Disable message sending:**

* Go to **Settings > Manage App > Disable App**.

See [Disabled Apps & Organizations](./disabled-apps) for details.

<Warning>
  Disabling an app does not stop billing. Monthly Active Users (MAU) for disabled apps still count toward billing.

  To stop billing, delete the app or move it to a Free Organization.

  Contact `support@onesignal.com` for assistance.
</Warning>

***

## Security best practices

* Store API keys in a secure backend (never client-side).
* Use environment variables or a secrets manager.
* Enable IP allowlisting when possible.
* Rotate keys periodically.
* Use separate keys for staging and production.

***

## FAQ

### How do I find my API key?

Go to **Settings > Keys & IDs** in the OneSignal dashboard. Copy the **App API Key** (app-level) or go to **Organizations > Your Organization > Keys & IDs** for the **Organization API Key**.

The key is only displayed once after creation. If you lose the key, you must rotate it.

### Can I retrieve a legacy App API key?

No. OneSignal does not display legacy App API keys anymore. If you cannot find this key in your codebase, then you will need to generate and use a new API key.

### What is the difference between an App ID, App API key, and Organization API key?

* **App ID**: A public identifier for your app. Used in SDK setup and API requests to specify the app.
* **App API Key**: A secret key used to send messages and manage users for one app.
* **Organization API Key**: A secret key used to manage apps and organization-level settings across your entire account.

***

## Related pages

<Columns>
  <Card title="Disabled Apps & Organizations" icon="ban" href="./disabled-apps">
    Manage disabled apps and understand billing implications.
  </Card>

  <Card title="Users" icon="user" href="./users">
    Understand the OneSignal user model and External IDs.
  </Card>
</Columns>


# SMS keywords
Source: https://documentation.onesignal.com/docs/en/keywords

Use SMS keywords in OneSignal for two-way engagement campaigns, preference centers, and audience segmentation. Covers keyword setup, reply templates, data tags, and measuring keyword engagement.

SMS keywords let subscribers text a specific word or phrase to your sender and receive an automated reply. You can use keywords for two things: **two-way engagement campaigns** (polls, content unlocks, preference collection) and **preference centers** (letting subscribers manage which types of messages they receive).

<Note>
  Alphanumeric sender IDs cannot receive replies and do not support keyword functionality. Reply syncing must be enabled for each sender. Go to **Settings > Platforms > SMS Settings > Senders > Setup Replies**. Without this, OneSignal cannot receive inbound keywords and tags will not be applied.
</Note>

***

## Two-way keyword campaigns

SMS campaigns don't have to be one-directional. You can run keyword-based campaigns where subscribers reply to interact, including polls, surveys, preference collection, and content unlocks.

Include a CTA in your message asking subscribers to reply with a keyword (e.g., "Reply EA for early access"). When OneSignal receives a message that matches the keyword, it triggers an automated reply and optionally applies a data tag to the subscriber's profile.

### Setting up a keyword

<Steps>
  <Step title="Go to SMS Keywords">
    Navigate to **Settings > Platforms > SMS Settings > Keywords** and click **Add a keyword**.
  </Step>

  <Step title="Enter the keyword">
    Enter the keyword text subscribers will send.

    <Note>
      Keyword matching is case-insensitive and follows these rules:

      * **Single-word keywords** match when the keyword is the first word, the last word, or appears inside parentheses anywhere in the message. Example: keyword `STOP` matches "STOP" and "Reply STOP please" but not "Please stop now".
      * **Multi-word keywords** match only when the full phrase appears inside parentheses. Example: keyword `summer sale` matches "Tell me more (summer sale)".
    </Note>
  </Step>

  <Step title="Choose the audience behavior">
    * **Anyone:** Sends the same reply to all users, regardless of subscription status.
    * **Segment by subscription status:** Sends different replies to subscribed and unsubscribed users.
  </Step>

  <Step title="Select a reply template">
    Choose the template subscribers receive when they text the keyword.
  </Step>

  <Step title="Assign a data tag (optional)">
    Assign a tag to apply when a user sends the keyword (e.g., `early_access = true`). Use this tag to build segments for future campaigns.
  </Step>
</Steps>

### Measuring keyword engagement

To track how many times a keyword is triggered:

1. Go to **Templates**.
2. Check the analytics for the template tied to your keyword reply.

For example, if the `early_access` template shows 300 sends, the `EA` keyword was triggered 300 times.

For this count to equal keyword triggers, use a dedicated reply template per keyword. If the template is reused by another keyword or campaign, the send count includes those uses too.

### Building a segment from keyword engagement

Create targeted campaigns based on users who responded with specific keywords:

1. Go to **Segments**.
2. Use the **User Tag** filter.
3. Enter the tag you assigned when setting up the keyword (e.g., `early_access = true`).
4. Save and use this segment in your campaigns and Journeys.

***

## Preference centers

A preference center lets subscribers self-select the types of messages they want to receive. Rather than a single all-or-nothing opt-out, subscribers can opt in or out of specific lists, such as seasonal promotions, product categories, restock alerts, and VIP offers, by texting a keyword. OneSignal tracks these preferences as data tags on each subscriber's profile.

<Note>
  This approach is for managing preferences within a single use case (e.g., Fall promotions vs. Spring promotions, all under a marketing program). It is not intended for separating promotional opt-outs from transactional opt-outs on a shared sender. See [Consent keyword management](./sms-consent-keyword-management#managing-opt-outs-for-shared-senders) for that.
</Note>

### How it works

1. A subscriber texts a keyword to your sender (e.g., FALL).
2. OneSignal applies a data tag to that subscriber's profile (e.g., `fall = true`).
3. When you send a campaign, you filter your audience to subscribers who have that tag.

Subscribers who haven't texted any preference keyword have no tag set and won't appear in a `fall = true` segment. Plan your preference center as opt-in by default, and use your welcome message or website to seed initial preferences.

### Setting up a preference center

Go to **Settings > Platforms > SMS Settings > Keywords** and create a keyword pair for each subscription list, one to subscribe and one to unsubscribe.

**Subscribe keyword (e.g., FALL):**

1. Enter the keyword text (e.g., FALL).
2. Select or create a reply template (e.g., *"You're subscribed to Fall promotions! Text NOFALL to unsubscribe anytime."*).
3. Assign a data tag: `fall = true`.

**Unsubscribe keyword (e.g., NOFALL):**

1. Enter the keyword text (e.g., NOFALL).
2. Select or create a reply template (e.g., *"You've been unsubscribed from Fall promotions. Text FALL to resubscribe anytime."*).
3. Assign a data tag: `fall = false`.

Repeat this pair for each list. For a Spring list, create SPRING (`spring = true`) and NOSPRING (`spring = false`).

### Targeting subscribers by preference

When building a campaign or Journey, use the **User Tag** filter in Segments. Choose the model that fits your program:

* **Opt-in only:** Filter on `fall = true`. Reaches only subscribers who actively texted FALL. Subscribers with no `fall` tag are excluded.
* **Opt-out:** Exclude `fall = false`. Reaches every subscriber on the sender except those who texted NOFALL, including subscribers who have never used the preference center.

These produce different audiences. Pick one model per program and apply it consistently.

### Promoting your preference center

Tell subscribers which keywords are available in your welcome message (e.g., *"Text FALL for Fall deals, SPRING for Spring deals, or STOP to unsubscribe from all."*) or on your website or app with a checklist that adds a data tag when a subscriber toggles on specific preferences.

***

## FAQ

### Can I use keywords with alphanumeric sender IDs?

No. Alphanumeric sender IDs are one-way only and cannot receive inbound messages, which means keywords are not available. You'll need a sender resource type that supports inbound replies (long code, short code, toll-free, or RCS).

### How do I know if reply syncing is enabled?

Go to **Settings > Platforms > SMS Settings > Senders** and check **Setup Replies** for each sender. Without reply syncing, OneSignal cannot receive inbound keywords and data tags will not be applied.

### If I'm integrating with Twilio, does syncing keywords to OneSignal break my existing Twilio replies?

Yes. Syncing keywords to OneSignal will break any Twilio replies you have currently set up. If you rely on Twilio-side keyword handling, evaluate whether to migrate that logic to OneSignal or keep it in Twilio before enabling sync.

### How many keywords can I create?

There is no documented limit, but keep your keyword list manageable. Every keyword you create should be promoted somewhere subscribers can find it, or it won't be used.

### Can I trigger a Journey from a keyword reply?

Yes. Assign a data tag to the keyword, then use a **User Tag** filter as the entry condition for a Journey. When the tag is set, eligible subscribers enter the Journey.

### Can I use numbers as keywords for multiple-choice polls?

Yes, but with caution. Keywords are global to a sender, so `1`, `2`, and `3` will match for every campaign using that sender. If two concurrent campaigns both use `1`, replies will trigger whichever keyword's tag and template are configured — not the campaign the subscriber thought they were replying to. Prefer short letter mnemonics (e.g., `EA`, `VIP`, `FALL`) for poll responses.

***

## Related pages

<Columns>
  <Card title="Consent keyword management" icon="shield" href="./sms-consent-keyword-management">
    Manage STOP, HELP, START, and custom opt-out keywords for regulatory compliance.
  </Card>

  <Card title="Composing messages" icon="pencil" href="./sms-composing-messages">
    Build the reply templates that keywords trigger, including character limits and trackable links.
  </Card>

  <Card title="Opt-in and collection" icon="user-plus" href="./sms-opt-in-and-collection">
    Collect valid consent before subscribers can text in keywords.
  </Card>

  <Card title="Journeys" icon="map" href="./journeys-overview">
    Use keyword-applied tags as entry conditions for automated messaging flows.
  </Card>
</Columns>


# Labels
Source: https://documentation.onesignal.com/docs/en/labels

Organize and manage messages across push, email, SMS, and in-app channels with Labels in OneSignal. Easily filter, categorize, and streamline your campaign workflow.

## Overview

Labels in OneSignal help you categorize and organize messages across push, email, SMS, and in-app channels. Labels make it easier to filter messages, locate templates, and collaborate across teams.

Once a label is applied, it can be used to filter and group content, improving visibility and navigation within your dashboard.

<Frame>
  <img />
</Frame>

### Suggested use cases

Organize your messages by:

* Team or message creator
* Status or priority
* Campaign topic or goal
* Language or geography
* Event or seasonal theme
* Message type (promo, transactional, etc.)
* Top Performers

To get the most value out of Labels, we recommend:

1. Defining clear criteria for when and why to use labels.
2. Establishing consistent naming conventions.
3. Brainstorming and planning label types before applying them.
4. Aligning with team members and cross-functional partners.
5. Reviewing and adjusting labels periodically to keep your dashboard clean and useful.

***

## Add or edit a Label

You can apply up to **five labels** per message or template. Each label can be up to **100 characters** long and must be unique. Labels are **shared across all channels**, enabling you to group related content across push, email, SMS, and in-app messages.

### When sending a message

Use the **Labels dropdown** when composing a new message. Select existing labels or start typing to create new ones.

<Frame>
  <img />
</Frame>

### On an existing message

To label an existing message:

<Steps>
  <Step title="Go to the Messages and select the channel." />

  <Step title="Find the message you want to label.">
    Click the **three dots** on the right side of the message and select **Edit Labels**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Choose existing labels or start typing to make a new one.">
    <img />
  </Step>

  <Step title="Click Update to save." />
</Steps>

***

## Filter by label

Apply filters to show only messages with selected labels. You can use up to **five label filters** at once. Filters use **AND logic**, meaning only messages that match *all* selected labels will appear.

Example: Filtering by `Label A` and `Label B` will only show messages tagged with *both*.

<Frame>
  <img />
</Frame>

### Rename or delete a Label across all messages

To change or remove a label globally:

1. Use **Add Filter > Label** to find messages with a specific label.
2. Click **Manage Labels** in the top right corner.
3. Choose **Rename Labels** or **Delete Labels**.
4. Confirm your changes:
   * **Rename**: Enter a new name and click **Rename**.
   * **Delete**: Confirm removal to delete the label from all messages.

<Frame>
  <img />
</Frame>

***

## FAQ

### If I use the same label across different channels, will it group those messages together?

Yes. Labels are shared across all messaging channels. For example, the label "Super Bowl 2023" can be used on push, email or any other channel and will appear consistently in filters.

### Can I see labels when I export my messages?

Yes. When exporting your messages from **Delivery > Sent Messages** the labels for these messages will be included in the exported CSV.

***


# URLs, links, & deep links
Source: https://documentation.onesignal.com/docs/en/links

Set up launch URLs, deep links, dynamic URLs, UTM tracking, and click tracking across push, email, in-app, SMS, and RCS messages.

## How links work

Every OneSignal message — push, email, in-app, SMS, or RCS — can include a URL that takes the User to a destination when clicked. That destination can be a web page that opens in a browser or a [deep link](#deep-links) that opens directly in your app.

The way you set the URL depends on the channel:

* **Push**: Use the **Launch URL** field in the dashboard or the `url` parameter in the API.
* **Email**: Add links using the email editor or HTML. OneSignal automatically tracks clicks.
* **In-app**: Configure [Click Actions](./iam-click-actions) on buttons, images, or backgrounds.
* **SMS/RCS**: Add links inline. Use **Insert Trackable Link** in the dashboard for automatic shortening and tracking. See [SMS/RCS trackable links](#sms%2Frcs-trackable-links).

### Deep links

To open content inside your app instead of a browser, use a deep link. Deep link support varies by channel:

* **Push and in-app**: Support custom URL schemes like `your-app://product/123` and `https://` universal links / App Links.
* **Email and SMS**: Only `https://` universal links / App Links are supported. Custom URL schemes do not work because email clients and SMS apps don't handle them.

<Card title="Deep Linking" icon="link" href="./deep-linking">
  Full setup guide for custom URL schemes, universal links, and app-specific routing.
</Card>

### Push

#### Launch URL

The Launch URL opens when the User clicks a push notification. It should start with `https://`.

<Info>
  To use `http://` URLs on Apple devices, configure the [NSAppTransportSecurity](https://developer.apple.com/documentation/bundleresources/information_property_list/nsapptransportsecurity) property in your app's `Info.plist` file.
</Info>

If you send a single message to both web and mobile Users, use platform-specific URL fields:

* `url` — targets all platforms
* `web_url` — targets web push Subscriptions only
* `app_url` — targets mobile Subscriptions only

<Frame>
  <img alt="OneSignal dashboard showing the Launch URL input field for push notifications" />
</Frame>

<Tip>
  To dismiss a web push notification without opening any page, append `?_osp=do_not_open` to the launch URL, e.g., `https://yoursite.com/page?_osp=do_not_open`. This only works for web push.
</Tip>

#### Additional data

Instead of a Launch URL, you can send custom key-value pairs using the **Additional Data** field (`data` in the API). Your app reads this data through the [SDK's Notification Click Listener](./mobile-sdk-reference#push-notification-events) via the `additionalData` property — useful when you need more flexibility than a single URL.

<Frame>
  <img alt="OneSignal dashboard showing the Additional Data field with a custom key-value pair" />
</Frame>

### Email link tracking

OneSignal automatically tracks link clicks within emails when **Track link clicks** is enabled for the email or template (on by default). OneSignal tracks total and unique clicks per email and per individual link (up to 30 links per email). View these statistics in [Email Message Reports](./email-message-reports).

<Note>
  For unsubscribe links, see [Unsubscribe Links & Email Subscriptions](./unsubscribe-links-email-subscriptions).
</Note>

<Frame>
  <img
    alt="OneSignal email message report showing click activity with total and 
unique click counts per link"
  />
</Frame>

<Accordion title="How email click tracking rewrites URLs">
  Tracking works by rewriting URLs to capture the click event, then redirecting the User to the original destination. This happens almost instantly but may cause unexpected behavior with [deep links](./deep-linking). For example:

  `https://some-domain.com/the-page`

  becomes something like:

  `https://some-domain/c/eJxU0D2uGzEMBODTrDoZJPW3...`

  The User is immediately redirected to the intended URL.
</Accordion>

If you construct links with Liquid syntax, OneSignal may not detect them automatically. Explicitly mark a link as trackable:

```liquid theme={null}
{{ 'https://some-domain.com/the-page' | track_link }}
```

To disable tracking for an entire email, uncheck **Track link clicks** in the dashboard email editor or set `disable_email_click_tracking: true` in the API.

<Frame>
  <img alt="OneSignal dashboard email settings with Track link clicks unchecked" />
</Frame>

To disable tracking for a specific link while keeping it enabled for the rest, add the `disable-tracking=true` attribute to its anchor tag:

```html theme={null}
<a href="https://some-domain.com/the-page" disable-tracking=true>View the page</a>
```

<Warning>
  Disabling tracking for an entire email means no click data is collected — CTR shows "N/A" in [Email Message Reports](./email-message-reports).
</Warning>

### SMS/RCS trackable links

OneSignal provides trackable shortened links for SMS/RCS messages using the `1sgnl.co` domain. Just wrap your URL in `{{ "https://your-url.com" | track_link }}` and the link will be replaced with a trackable link when the message is sent. For API usage, see the [SMS/RCS create message API reference](/reference/sms).

Only 1 trackable link is allowed per SMS/RCS message.

When using the dashboard, you can also click the **Insert Trackable Link** button beneath the message input box and enter your URL:

<Frame>
  <img alt="OneSignal dashboard modal for inserting a trackable shortened link into an SMS message" />
</Frame>

Click **Insert trackable link** to add the short link to your message:

```liquid theme={null}
Your order is on its way! 
Track it here: {{ "https://your-url.com" | track_link }}
```

When the message is sent, the double curly braces and everything inside will be replaced with a `1sgnl.co/XXXX` trackable link:

<Frame>
  <img alt="SMS notification on a mobile device showing a trackable shortened link" />
</Frame>

***

## Dynamic URLs

You can build personalized, user-specific URLs with [Liquid syntax](./using-liquid-syntax). For example, include a User's ID in the URL so each person lands on their own profile page, or insert a product ID from a recent event to link directly to a relevant item.

Dynamic URLs can pull data from:

* User properties (e.g., `external_id`, `email`)
* Tags stored in OneSignal
* `custom_data` sent via the API
* Custom Events (in Journeys)

<Tabs>
  <Tab title="User properties">
    Inject values like `external_id` or `email` directly into URLs.

    ```text theme={null}
    https://yourdomain.com/profile/user={{subscription.external_id}}
    ```

    If the User's `external_id` is `12345`, the final URL is:

    ```text theme={null}
    https://yourdomain.com/profile/user=12345
    ```

    Similarly:

    ```text theme={null}
    https://yourdomain.com/profile/email={{subscription.email}}
    ```

    If the User's email is `john@example.com`, the final URL is:

    ```text theme={null}
    https://yourdomain.com/profile/email=john@example.com
    ```
  </Tab>

  <Tab title="Tags">
    Reference Tags stored in OneSignal.

    ```text theme={null}
    https://yourdomain.com/topic/{{tag_key}}
    ```

    If the User has a tag `tag_key` with value `technology`, the final URL is:

    ```text theme={null}
    https://yourdomain.com/topic/technology
    ```

    If `tag_key` is not set, the URL becomes:

    ```text theme={null}
    https://yourdomain.com/topic/
    ```

    Use the `default` filter to set a fallback:

    ```text theme={null}
    https://yourdomain.com/topic/{{tag_key | default: 'unknown'}}
    ```
  </Tab>

  <Tab title="custom_data">
    Use the Create message API with Templates. Set the URL in the template with Liquid syntax that references the `custom_data` object.

    Template URL:

    ```text theme={null}
    https://yourdomain.com/invoice={{message.custom_data.invoice_number}}
    ```

    API request with `custom_data`:

    ```json theme={null}
    {
        "template_id": "YOUR_TEMPLATE_ID",
        "custom_data": {
            "invoice_number": "12345"
        }
    }
    ```

    Final URL:

    ```text theme={null}
    https://yourdomain.com/invoice=12345
    ```
  </Tab>

  <Tab title="Custom Events">
    Personalize URLs using Custom Events captured in Journeys. Reference event properties directly or assign the event to a variable for cleaner syntax.

    **Reference event properties directly:**

    ```text theme={null}
    https://yourdomain.com/order/{{ journey.event.purchase.properties.order_id }}
    ```

    If the most recent `purchase` event included `"order_id": "98765"`, the final URL is:

    ```text theme={null}
    https://yourdomain.com/order/98765
    ```

    **Assign the event for readability:**

    ```liquid theme={null}
    {% assign event = journey.event.purchase %}
    https://yourdomain.com/order/{{ event.properties.order_id }}
    ```

    **Access the most recent stored event:**

    ```text theme={null}
    https://yourdomain.com/product/{{ journey.last_event.properties.product_id | default: 'unknown' }}
    ```

    **Event names with spaces or special characters (hash notation):**

    ```text theme={null}
    https://yourdomain.com/status/{{ journey.event["order status"].properties.current_status }}
    ```

    <Note>
      Custom Events can only be referenced in Templates used within Journeys. Use `journey.first_event`, `journey.last_event`, or `journey.event.<name>` to access event data in Liquid.
    </Note>
  </Tab>
</Tabs>

<Tip>
  Only substitute data into parts of the URL — keep the protocol (`https://`) and domain as static text. Use the `default` filter to set a fallback if a value is not present.
</Tip>

***

## UTM parameters

UTM parameters track campaign performance by appending `source`, `medium`, and `campaign` details to URLs. Add UTM parameters directly to the URLs in your messages.

For push notifications sent from the dashboard, OneSignal can add UTMs automatically.

<Accordion title="Automatic UTMs for push notifications" icon="circle-chevron-down">
  Navigate to **Settings > Push & In-app > UTM Settings** and enable **Turn on automated UTM tagging**.

  Once enabled, OneSignal appends these values (editable):

  * **Source** = `utm_source` — defaults to `onesignal`
  * **Medium** = `utm_medium` — defaults to `push`
  * **Campaign** = `utm_campaign` — defaults to `{{ sendDate }}-{{ title }}`
    * `sendDate`: Date sent
    * `title`: First 15 alphanumeric characters, underscores, or hyphens from the message title

  Example:

  ```text theme={null}
  https://test.com?utm_source=onesignal&utm_medium=push&utm_campaign=2020-06-03-sale-today
  ```

  <Warning>
    Automatic UTM tagging only applies to push notifications sent from the dashboard. It does not work with:

    * Emails, SMS, or in-app messages
    * Journeys, Templates, or automated messages
    * API requests
    * The "Send Test Message" button
    * Additional data fields

    For these cases, add UTM parameters manually in your templates or API payloads.
  </Warning>

  #### URL handling and overrides

  If you manually add UTM parameters to a launch URL while automatic tagging is enabled, your manual UTMs override the automatic values.
</Accordion>

***

## FAQ

### How do I link to the app store?

Use the store URL as the launch URL:

* **Android**: Use the Google Play link, e.g., `https://play.google.com/store/apps/details?id=com.example.app`. See [Linking to Google Play](https://developer.android.com/distribute/marketing-tools/linking-to-google-play.html).
* **iOS**: Use the App Store link but replace `https://` with `itms-apps://` to open the App Store app directly, e.g., `itms-apps://apps.apple.com/app/id123456789`.

### Can I link to another app?

For push and in-app messages, you can use a URL scheme to deep link into another app. For example, to [deep link into WhatsApp](https://faq.whatsapp.com/425247423114725): `whatsapp://wa.me/15551234567`.

For email and SMS, use `https://` links instead — custom URL schemes are not supported.

### Why is my launch URL not working?

Common causes:

* **URL mismatch**: The URL must start with `https://`. If you're using `http://` on Apple devices, you need [NSAppTransportSecurity](https://developer.apple.com/documentation/bundleresources/information_property_list/nsapptransportsecurity) configured.
* **Custom schemes on mobile**: Deep links like `your-app://path` may not work as a launch URL on all platforms. Use the **Additional Data** field or see [Deep Linking](./deep-linking) for reliable app routing.
* **Web push default**: If no launch URL is set, web push opens your homepage. Set a launch URL explicitly to control the destination.
* **Click tracking interference**: In email, link rewriting for click tracking can break deep links. Try [disabling click tracking](#email-link-tracking) for that specific link.

### Do UTM parameters work with email and SMS?

No. Automatic UTM tagging only applies to push notifications sent from the dashboard. For email and SMS, add UTM parameters manually to the URLs in your templates or API payloads. See [UTM parameters](#utm-parameters) for the full list of limitations.

### Can I prevent a push notification from opening a URL?

On mobile, clicking a push notification always opens the app.

On web, append `?_osp=do_not_open` to the launch URL to dismiss the notification without opening any page. See the [Launch URL tip](#launch-url) for an example.

***

<Columns>
  <Card title="Deep Linking" icon="link" href="./deep-linking">
    Set up custom URL schemes and app-specific routing for push and in-app messages.
  </Card>

  <Card title="Personalization" icon="wand-magic-sparkles" href="./message-personalization">
    Insert dynamic user data into messages using Liquid syntax and tags.
  </Card>

  <Card title="Using Liquid syntax" icon="code" href="./using-liquid-syntax">
    Reference guide for Liquid filters, tags, and variables in OneSignal templates.
  </Card>

  <Card title="Email message reports" icon="chart-line" href="./email-message-reports">
    View delivery, open, and click-through metrics for email campaigns.
  </Card>

  <Card title="Action buttons" icon="hand-pointer" href="./action-buttons">
    Add call-to-action buttons to push notifications with custom URLs.
  </Card>
</Columns>


# Live Activities
Source: https://documentation.onesignal.com/docs/en/live-activities

Deliver real-time updates to the iOS Lock Screen and Dynamic Island with OneSignal Live Activities. Use for time-bound events like delivery tracking, sports scores, ride status, and live game updates.

Live Activities deliver real-time updates to the iOS and iPadOS Lock Screen and Dynamic Island, keeping users informed without opening your app. Use them for time-bound events like delivery tracking, sports scores, ride status, and live game updates. Introduced in iOS 16.1 and expanded in iOS 17.

<Note>
  Live Activities are an iOS feature. For similar capability on Android, see [Android Live Notifications](./android-live-notifications).
</Note>

<Frame>
  <img alt="Examples of iOS Live Activities on the Lock Screen and Dynamic Island showing delivery tracking, sports scores, and ride status" />
</Frame>

## When to use Live Activities

Live Activities work best for transactional, time-bound updates with a clear beginning and end. They are visible for up to 8 hours of active updates, do not require push permission for the first activity (they are provisional), and render on premium iOS surfaces like the Lock Screen and Dynamic Island. OneSignal manages the underlying update tokens, scales a single API call across all Subscriptions, and records delivery and engagement analytics for each send.

<Note>
  For use cases and examples, see the [OneSignal Live Activities blog post](https://onesignal.com/blog/new-live-activities-support-to-help-you-drive-loyalty-faster).
</Note>

## Get started

### Requirements

* iOS 16.1+ or iPadOS 17+.
* OneSignal [Mobile SDK](./mobile-sdk-setup) integrated.
* Setup completed per the [Live Activities Developer Setup](./live-activities-developer-setup).
* Click tracking and confirmed receipt require iOS SDK **5.2.15 or higher**.

### How Live Activities work

* **Active updates**: Up to 8 hours from when the activity starts.
* **Stale period**: After the last update or a call to end the activity, iOS keeps the activity visible for up to 4 more hours before removing it automatically.
* **Limit**: Up to 5 simultaneous Live Activities per app.
* **Permissions**: The first activity is provisional — no push permission required. Future activities depend on user settings.
* **Remote start**: Supported on iOS 17.2+ via push-to-start.
* **Content policy**: Must provide user value. Not for ads or purely promotional content.

### Create, update, and end a Live Activity

<Steps>
  <Step title="Start a Live Activity">
    Start an activity in one of two ways:

    1. The [Start Live Activity API](/reference/start-live-activity) (push-to-start).
    2. In-app, by calling ActivityKit from your iOS code. See the [Live Activities Developer Setup](./live-activities-developer-setup).
  </Step>

  <Step title="Update a Live Activity">
    Call the [Update Live Activity API](/reference/update-live-activity-api) with the `activity_id`. OneSignal delivers the update to every Subscription associated with that activity.
  </Step>

  <Step title="End a Live Activity">
    End an activity in one of three ways:

    <Tabs>
      <Tab title="OneSignal SDK (`exitLiveActivity`)">
        * Tells OneSignal to stop sending updates for the given `activityId`.
        * Does **not** remove the activity from the screen. iOS removes it automatically after the 4-hour stale period or when the user dismisses it.
      </Tab>

      <Tab title="Update Live Activity API">
        Call the [Update Live Activity API](/reference/update-live-activity-api) with `event: end` to stop further updates. Include a `dismissal_date` to control when iOS removes the activity from the screen:

        * Omit `dismissal_date` and iOS removes the activity after the 4-hour stale period or when the user dismisses it.
        * Set a **future** `dismissal_date` within the next 4 hours to remove it sooner.
        * Set a **past** `dismissal_date` to remove it immediately. The user must have tapped **Allow** on the first Live Activity for programmatic dismissal to take effect.
      </Tab>

      <Tab title="User action">
        * The user swipes the activity away or otherwise dismisses it.
        * The user revokes Live Activity permission in iOS Settings.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Analytics and reporting

Track delivery, confirmed receipt, clicks, failures, and unsubscribes on every Live Activity send. Metrics follow the same definitions used across channels — see the [Metrics glossary](./analytics-metrics-glossary) for canonical definitions, and [Live Activities analytics](./live-activities-analytics) for message reports, Audience Activity exports, and rate calculations.

<Card title="Live Activities analytics" icon="chart-mixed" href="./live-activities-analytics">
  Measure delivery, confirmed receipt, clicks, and unsubscribes. Export Audience Activity and compute engagement rates.
</Card>

## Best practices

### Functionality

* Use Live Activities for transactional or contextual updates with a defined beginning and end — for example, ETA, score, or timer.
* Keep each activity shorter than 8 hours of active updates, and only as long as the content remains useful.
* Avoid excessive updates. Frequent updates drain device battery and can trigger throttling.
* Do not use Live Activities for ads or purely promotional content.

### UI and UX

* Support every presentation: Compact, Minimal, Expanded, and Lock Screen.
* Apply your brand, spacing, and dark/light themes consistently.
* Prioritize clarity and tap targets. Do not try to draw attention to the Dynamic Island itself.
* Do not display sensitive information in a Live Activity.

<Note>
  See Apple's [Live Activities Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/live-activities) for more detail.
</Note>

### Targeting at scale

Target users based on the event:

* Use segments for broad events like sports games, concerts, or launches.
* Target individual users for personal or transactional events such as orders and deliveries.

For targeting syntax, see [Create message](/reference/create-message).

### Set update priority

Apple uses the `priority` field on each update to decide how urgent it is. Sending too many high-priority updates in a short window triggers throttling, where iOS delays or drops updates.

* Use a mix of `priority: 5` (standard) and `priority: 10` (high). Reserve `priority: 10` for time-sensitive updates.
* If your use case requires frequent high-priority updates, add `NSSupportsLiveActivitiesFrequentUpdates` to your app's `Info.plist` as a Boolean set to `YES`. See [Apple's guidance on update frequency](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency).
* When the budget is exceeded, iOS may prompt the user to allow additional updates. If the user allows, Apple expands the budget for that app.

For the `priority` field, see the [Update Live Activity API](/reference/update-live-activity-api).

## FAQ

### Do I have access to Live Activities in my plan?

Live Activities are available on all plans except Free plans with more than 10,000 opted-in subscribers. Upgrade from the Free plan to use Live Activities. [See pricing](https://onesignal.com/pricing) or contact `support@onesignal.com`.

### What is the budget for high-priority updates?

Apple does not publish a fixed limit. iOS enforces a dynamic, device-level budget based on recent `priority: 10` usage, and throttles or drops updates when the budget is exceeded. Mix `priority: 5` with `priority: 10`, and reserve high priority for time-sensitive updates. See [Apple's guidance](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency).

### Where can I see Live Activities in the OneSignal dashboard?

Live Activities are sent only through the Live Activity APIs, but you can review historically sent activities in **Sent Messages** filtered to Live Activities for up to 30 days. For aggregate trends, see [Engagement Trends](./engagement-analytics).

### What devices support Live Activities?

Apple maintains the compatibility list for [iOS 16+](https://support.apple.com/guide/iphone/supported-models-iphe3fa5df43/16.0/ios/16.0) and [iPadOS 17+](https://support.apple.com/guide/ipad/ipad-models-compatible-with-ipados-17-ipad213a25b2/ipados).

### What's the difference between Delivered and Confirmed Receipt?

**Delivered** means APNs accepted the Live Activity update for delivery. **Confirmed Receipt** means the OneSignal SDK on the device confirmed that the update actually arrived. Confirmed Receipt requires iOS SDK 5.2.15+ and completed [Confirmed receipt](./confirmed-delivery) setup. See the [Metrics glossary](./analytics-metrics-glossary) for the full definitions.

## Related

<Columns>
  <Card title="Live Activities Developer Setup" icon="wrench" href="./live-activities-developer-setup">
    Integrate the OneSignal iOS SDK and configure your app for Live Activities.
  </Card>

  <Card title="Live Activities analytics" icon="chart-mixed" href="./live-activities-analytics">
    Message reports, Audience Activity, and CSV export for Live Activities.
  </Card>

  <Card title="Update Live Activity API" icon="code" href="/reference/update-live-activity-api">
    Send, update, and end Live Activities at scale with the REST API.
  </Card>

  <Card title="Confirmed receipt" icon="circle-check" href="./confirmed-delivery">
    Requirements for device-side receipt confirmation on iOS.
  </Card>

  <Card title="Android Live Notifications" icon="android" href="./android-live-notifications">
    Deliver similar real-time experiences on Android devices.
  </Card>

  <Card title="Metrics glossary" icon="book" href="./analytics-metrics-glossary">
    Canonical definitions for every metric across dashboard, API, CSV, and Event Streams.
  </Card>
</Columns>


# Live Activities analytics
Source: https://documentation.onesignal.com/docs/en/live-activities-analytics

Measure delivery, confirmed receipt, clicks, and unsubscribes for iOS Live Activities with OneSignal. Covers Key metrics, individual message reports, Audience Activity, and CSV export.

Measure how your Live Activities perform with per-message reports, aggregate trends, and Audience Activity exports. This page covers the metrics OneSignal records for Live Activities, where to find them in the dashboard, and how to export them for further analysis.

<Note>
  This page assumes you've already set up [Live Activities](./live-activities). For canonical metric definitions across every channel, see the [Metrics glossary](./analytics-metrics-glossary).
</Note>

## Overview

Live Activities analytics help you:

* Measure how many Subscriptions receive your updates.
* Track whether users engage with your Live Activities.
* Identify delivery failures and their causes.
* Monitor subscription health over time.

## Key metrics

Live Activities record the following metrics. These are the same definitions used in individual message reports, [Audience Activity](#audience-activity), and [Engagement Trends](./engagement-analytics).

| Metric                | Definition                                                                                                                                                                                                                                                                                            |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sent**              | The number of Live Activity updates sent from OneSignal, including those successfully sent to APNs and failures. This is a composite metric that includes push-to-start and push-to-update notifications.                                                                                             |
| **Delivered**         | The number of Live Activity updates successfully sent to and accepted by APNs.                                                                                                                                                                                                                        |
| **Confirmed Receipt** | The number of Live Activity updates confirmed as received by the device, verified by the OneSignal SDK. Requires iOS SDK **5.2.15 or higher**. See [Confirmed receipt](./confirmed-delivery) for platform requirements.                                                                               |
| **Failed**            | The number of push Subscriptions that did not receive the Live Activity update because of an error. OneSignal retries these Subscriptions on subsequent updates.                                                                                                                                      |
| **Unsubscribed**      | The number of push Subscriptions marked unsubscribed for Live Activity updates. Triggered when a user dismisses the Live Activity, disables Live Activities in device settings, uninstalls the app, or opts out of push. OneSignal does not send future Live Activity updates to these Subscriptions. |
| **Clicked**           | The total number of clicks on Live Activity updates, including repeat clicks from the same user.                                                                                                                                                                                                      |

## Message reports

Individual message reports show the delivery breakdown for a single Live Activity send.

<Frame>
  <img alt="Live Activity message report showing delivery, confirmed receipt, failure, and click counts" />
</Frame>

To open a Live Activity message report:

<Steps>
  <Step title="Open Sent Messages">
    Go to **Sent Messages** in your OneSignal dashboard.
  </Step>

  <Step title="Filter by Live Activities">
    Filter the list to show only Live Activity messages.
  </Step>

  <Step title="Open the report">
    Click any Live Activity to view its detailed report.
  </Step>
</Steps>

Individual message reports are retained for **30 days**. For longer-term analysis, use [Engagement Trends](./engagement-analytics) (retained up to 2 years depending on your pricing plan) or export the data.

## Audience activity

The Audience Activity panel on a Live Activity message report lists the Subscriptions that contributed to each metric, so you can investigate individual outcomes.

To view Audience Activity:

<Steps>
  <Step title="Open a message report">
    Open any Live Activity message report from **Sent Messages**.
  </Step>

  <Step title="Locate the Audience Activity panel">
    Scroll to the **Audience Activity** panel on the report.
  </Step>

  <Step title="Select a statistic type">
    Choose which Subscriptions to list:

    * **Deliveries** — Subscriptions counted as **Delivered** (accepted by APNs).
    * **Clicks** — Subscriptions counted as **Clicked**.
    * **Failures** — Subscriptions counted as **Failed**.
    * **Unsubscribes** — Subscriptions counted as **Unsubscribed**.
  </Step>
</Steps>

Use Audience Activity to troubleshoot delivery issues for specific Subscriptions, identify segments with elevated failure or unsubscribe rates, and correlate engagement with content or timing.

## Export Audience Activity

Click the **Export** button above the Audience Activity panel to export the data. OneSignal emails the CSV to the email address on your current OneSignal user account.

Export options:

* **Single statistic** — Only the currently selected activity type (for example, just Clicks or just Failures).
* **All statistics** — All Audience Activity data for the message.

The export includes user identifiers, activity timestamp, activity type, and device and platform information where available.

<Note>
  Large exports may take several minutes to process. OneSignal sends an email notification when the export is ready.
</Note>

## Compute delivery and engagement rates

Live Activity message reports show raw counts. Derive rates to compare performance across sends or time periods.

**Confirmed Receipt Rate** — the percentage of delivered updates that the device confirmed receiving:

```
Confirmed Receipt Rate = (Confirmed Receipt / Delivered) × 100
```

Use this to detect SDK or device-side delivery issues. A low rate usually indicates Subscriptions on iOS SDK versions earlier than 5.2.15, devices offline long enough for APNs to drop queued updates, or users who disabled Live Activities.

**Click-Through Rate (CTR)** — the percentage of delivered updates that were clicked:

```
Click-Through Rate = (Clicked / Delivered) × 100
```

**Confirmed Click-Through Rate** — the percentage of device-confirmed updates that were clicked. Filters out deliveries where the device never actually received the update:

```
Confirmed Click-Through Rate = (Clicked / Confirmed Receipt) × 100
```

## Troubleshooting

### High Failed rate

1. **Check update token validity.** Live Activity update tokens expire when the activity ends, is dismissed, or the app is uninstalled. OneSignal stops sending to invalidated tokens.
2. **Verify APNs configuration.** Make sure your APNs authentication key or certificate is current in the OneSignal dashboard.
3. **Review failure reasons on the message report.** Individual failures include an error code from APNs.

### Low Confirmed Receipt

1. **Verify iOS SDK version** is 5.2.15 or higher.
2. **Complete the confirmed receipt setup.** Confirmed Receipt for push and Live Activities requires the [Notification Service Extension and App Group](./confirmed-delivery) setup in your iOS app.
3. **Account for device conditions.** Devices offline long enough for APNs to drop Live Activity updates will not produce a Confirmed Receipt.

### Declining Click-Through Rate

* Review content relevance and timing on the individual message reports where CTR dropped.
* Compare against historical CTR from [Engagement Trends](./engagement-analytics) to distinguish a one-off dip from a trend.

## FAQ

### How long is Live Activity data retained?

Individual message reports in **Sent Messages** are retained for 30 days. Aggregate data in [Engagement Trends](./engagement-analytics) is retained for up to 2 years depending on your pricing plan.

### Why is my Confirmed Receipt count lower than Delivered?

Confirmed Receipt requires iOS SDK 5.2.15 or higher and completed [Confirmed receipt](./confirmed-delivery) setup. Subscriptions on older SDK versions, devices that were offline long enough for APNs to drop queued updates, and users who disabled Live Activities all reduce Confirmed Receipt relative to Delivered.

### Why is Unsubscribed counted when a user dismisses the activity?

Once a user dismisses a Live Activity or disables Live Activities in device settings, APNs reports the activity token as invalid. OneSignal counts these Subscriptions as unsubscribed for Live Activity updates and stops sending further updates.

### Can I track individual user journeys?

Yes. Use the Audience Activity panel on a message report to list the Subscriptions behind each metric, then export the CSV for deeper analysis or join against your own data warehouse.

### Can I stream Live Activity events to my own analytics stack?

Yes. Use [Event Streams](./event-streams) to forward `message.live_activity.*` events (sent, delivered, failed, unsubscribed, clicked) to your warehouse in real time. See the [Metrics glossary](./analytics-metrics-glossary) for the full event name mapping.

## Related

<Columns>
  <Card title="Live Activities setup" icon="bolt" href="./live-activities">
    Set up Live Activities with the OneSignal iOS SDK.
  </Card>

  <Card title="Confirmed receipt" icon="circle-check" href="./confirmed-delivery">
    Platform requirements and SDK setup for the Confirmed Receipt metric.
  </Card>

  <Card title="Engagement trends" icon="chart-mixed" href="./engagement-analytics">
    Aggregate delivery and engagement trends across all channels, including Live Activities.
  </Card>

  <Card title="Metrics glossary" icon="book" href="./analytics-metrics-glossary">
    Canonical definitions for every metric across the dashboard, API, CSV, and Event Streams.
  </Card>
</Columns>


# Team members
Source: https://documentation.onesignal.com/docs/en/manage-team-members

Manage OneSignal user access by adding, removing, or updating team member roles at the app or organization level. Learn role permissions and plan availability.

OneSignal allows you to manage user access either at the **Organization level** (all apps) or at the **App level** (specific apps). Each user can be assigned a role based on their needs and responsibilities.

For example:

* An **analyst** who needs to review messaging performance across apps could be an **Organization Viewer**.
* A **developer** or **marketer** working on one app can be assigned as an **App Admin**.
* A **content writer** who builds messages but should not send them could be an **Organization Composer**.
* A **finance team member** who only needs billing access could be an **Organization Finance** role.
* A **contractor** who only needs access to a single app can start as an **Organization Team Member** with an app-level role layered on.

<Note>For details on how Apps and Organizations work together, see [Apps, Organizations, and Accounts](./apps-organizations).</Note>

***

## Managing team access

You can grant access at either the **Organization** level (all apps) or **App** level (specific apps).

### Invite a team member to an Organization

**Organization Admins** can invite users and assign them roles that apply to all apps in the Organization.

<Steps>
  <Step title="Navigate to your Organization">
    Go to **Organizations > \[Your Organization] > Team Members**.
  </Step>

  <Step title="Invite a team member">
    Click **Invite to Organization**.
  </Step>

  <Step title="Assign a role">
    Choose a role: Admin, Finance, Operations, Editor, Composer, Viewer, or Team Member.
  </Step>
</Steps>

<Check>The invited user receives an email to accept the invitation. Once accepted, they appear in the Team Members list with the assigned role.</Check>

<Frame>
  <img alt="OneSignal dashboard showing the organization Team Members page with invite button and role assignment" />
</Frame>

### Invite a team member to an App

App-level roles let you grant **additional permissions** on a specific App beyond what the user's Organization role provides.

<Warning>
  App-level roles can only **add** permissions on top of the user's Organization role — they cannot restrict or reduce access. For example, an Organization Viewer can be elevated to an App Editor on a specific App, but an Organization Editor cannot be downgraded to an App Viewer. See [valid app-level role assignments](#valid-app-level-role-assignments) for the full mapping.
</Warning>

<Steps>
  <Step title="Navigate to your App">
    Go to your App's **Settings > Team Members**.
  </Step>

  <Step title="Invite a team member">
    Click **Invite to App**.
  </Step>

  <Step title="Assign a role">
    Choose a role for that app: Admin, Operations, Editor, Composer, or Viewer.
  </Step>
</Steps>

#### Valid App-level role assignments

When you assign an App-level role, it must be equal to or more permissive than the user's Organization role. Both the client and server enforce these rules.

| Org Role      | Valid App Roles                         |
| ------------- | --------------------------------------- |
| `admin`       | None (already has full access)          |
| `editor`      | `admin` only                            |
| `composer`    | `editor`, `admin`                       |
| `viewer`      | `composer`, `editor`, `admin`           |
| `team_member` | `viewer`, `composer`, `editor`, `admin` |

### Update or remove user access

<Steps>
  <Step title="Navigate to Team Members">
    Go to the **Team Members** page for the Organization or App.
  </Step>

  <Step title="Open the options menu">
    Click the **Options** menu (⋮) next to the user's email address.
  </Step>

  <Step title="Update or remove">
    Select **Update Role** or **Remove**.
  </Step>
</Steps>

<Frame>
  <img alt="OneSignal dashboard showing the options menu for a team member with Update Role and Remove actions" />
</Frame>

***

## Roles and permissions

Organization roles take priority over App roles. If a user is an Organization Admin, they automatically have all App Admin privileges across every App in the Organization. No additional App-level role assignment is needed.

### Role types

OneSignal offers the following roles at the **Organization** level:

| Role        | Best for                   | Access summary                                                                                                                                                                |
| ----------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Admin       | Developers, Owners         | Full control over all org settings, billing, and messaging. Automatically includes all App Admin privileges across every app in the org                                       |
| Finance     | Finance teams              | View org settings, apps, members, and billing. Edit billing. No app-level permissions                                                                                         |
| Operations  | Ops teams                  | View access across all apps plus manage suppressions and sender identities                                                                                                    |
| Editor      | Marketers, PMs             | Full messaging workflow: create segments, build and send messages, manage webhooks and imports. Cannot modify underlying user or subscription records, or change app settings |
| Composer    | Content writers, Designers | Create and edit messages, templates, segments, and journeys. Cannot send, activate, or delete most content. No export access                                                  |
| Viewer      | Analysts, Read-only users  | View-only access across all apps. Cannot edit, send, or export                                                                                                                |
| Team Member | Minimal access users       | Can view the org and its apps list. No app-level permissions on its own. Access is layered on through app-level role assignments                                              |

The following roles are available at the **App** level:

| Role       | Best for                    | Access summary                                                                                                       |
| ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Admin      | App owners, Lead developers | Full control over the app including settings, keys, integrations, and team management                                |
| Operations | Ops teams                   | View access across app features plus manage suppressions and sender identities                                       |
| Editor     | Marketers, PMs              | Create, edit, send, and delete messages and related content. Manage webhooks and imports. Cannot change app settings |
| Composer   | Content writers             | Create and edit messages, templates, and segments. Cannot send or activate. No export access                         |
| Viewer     | Read-only users             | View-only access to app data. Cannot edit, send, or export                                                           |

<Note>
  **Editor scope:** Editors control *what to send and to whom*. They can view audience data, build segments from it, and run the full messaging workflow, but they cannot modify the underlying user or subscription records (tags, imports, deletions, subscription status).
</Note>

#### About the Team Member role

The `team_member` role is an org-level role that grants no app permissions on its own. Access is layered on explicitly through app-level role assignments, making it a clean least-privilege starting point.

`team_member` is automatically assigned in two situations:

* When a new user is invited to an App for the first time and has no existing Organization role
* When a user logs in through SSO for the first time and their identity provider has not yet been mapped to a specific OneSignal role

### Permission details by role

Select a role below to see its full permissions.

<Tabs>
  <Tab title="Admin">
    **Scope:** Organization and App

    Full control over everything. Organization Admins automatically have all App Admin privileges across every app in the org. Admin is the only role that can manage app and org settings, API keys, team members, integrations, billing, SSO, and 2FA enforcement.

    | Area                          | Permissions                                                                                                                                 |
    | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
    | Messaging                     | Create, edit, send, cancel, delete, and export all message types. Send test notifications                                                   |
    | Journeys                      | Create, edit, activate, delete, and export journeys and goals                                                                               |
    | Segments                      | Full control including setting defaults and deleting users from segments                                                                    |
    | Templates and dynamic content | Create, edit, and delete templates, dynamic content, and saved rows                                                                         |
    | In-app messages               | Create, edit, activate, and delete                                                                                                          |
    | Users and subscriptions       | View, edit, delete, import, and export. Full test user management                                                                           |
    | Webhooks and event streams    | Create, edit, activate, test, and delete                                                                                                    |
    | Custom events and outcomes    | View analytics, set retention, set tracking, and export                                                                                     |
    | Labels                        | Create, edit, and delete                                                                                                                    |
    | Suppressions                  | Create, delete, and export                                                                                                                  |
    | Integrations                  | Activate and edit                                                                                                                           |
    | App settings                  | Edit settings, manage API keys, manage team members, view and export audit logs, toggle app status, delete app                              |
    | Org settings                  | Edit settings, create and manage apps, manage members, manage billing, manage API keys, manage SSO, enforce 2FA, view and export audit logs |
    | Account                       | 2FA, email, and password (own account)                                                                                                      |

    <Info>Org Settings access is limited to users with the **Organization Admin** role. App-level-only Admins do not have permission to modify organization-level settings such as billing, plan upgrades, SSO, or org-wide 2FA.</Info>
  </Tab>

  <Tab title="Editor">
    **Scope:** Organization and App

    Editors can create, edit, send, and delete messages and most content. They can manage webhooks and handle imports. They cannot change app or org settings, manage team members, or access API keys.

    | Area                          | Permissions                                                                               |
    | ----------------------------- | ----------------------------------------------------------------------------------------- |
    | Messaging                     | Create, edit, send, cancel, delete, and export all message types. Send test notifications |
    | Journeys                      | Create, edit, activate, and delete                                                        |
    | Segments                      | Create, edit, activate, set default, and delete                                           |
    | Templates and dynamic content | Create, edit, and delete                                                                  |
    | In-app messages               | Create, edit, activate, and delete                                                        |
    | Users and subscriptions       | View, import users and subscriptions, add and remove test users                           |
    | Webhooks and event streams    | Create, edit, activate, test, and delete                                                  |
    | Custom events and outcomes    | View analytics and export                                                                 |
    | Labels                        | Create, edit, and delete                                                                  |
    | Suppressions                  | View only                                                                                 |
    | Integrations                  | View only                                                                                 |
    | App settings                  | View app and analytics, export analytics, view VAPID keys                                 |
    | Org settings                  | View org and apps                                                                         |
    | Account                       | 2FA, email, and password (own account)                                                    |

    **Cannot:** Edit or delete users and subscriptions directly. Export users. Change app or org settings. Manage API keys. Manage team members. Access billing. Delete users from a segment.
  </Tab>

  <Tab title="Composer">
    **Scope:** Organization and App

    Composers can create and edit messages, templates, segments, and journeys, but they cannot send, activate, or delete most content. They have no export access.

    | Area                          | Permissions                                       |
    | ----------------------------- | ------------------------------------------------- |
    | Messaging                     | Create and edit messages. Send test notifications |
    | Journeys                      | Create and edit                                   |
    | Segments                      | Create and edit                                   |
    | Templates and dynamic content | Create and edit                                   |
    | In-app messages               | Create and edit                                   |
    | Users and subscriptions       | View. Add test users                              |
    | Webhooks and event streams    | View only                                         |
    | Custom events and outcomes    | View analytics                                    |
    | Labels                        | Create and edit                                   |
    | Suppressions                  | No access                                         |
    | Integrations                  | View only                                         |
    | App settings                  | View app and analytics                            |
    | Org settings                  | View org and apps                                 |
    | Account                       | 2FA, email, and password (own account)            |

    **Cannot:** Send or activate messages, journeys, automations, or in-app messages. Delete any content. Export anything. Import users. Remove test users. Manage webhooks. Access app or org settings. Delete labels.

    <Warning>Composer can edit dynamic content only when it is not tied to live published messages or active journeys.</Warning>
  </Tab>

  <Tab title="Viewer">
    **Scope:** Organization and App

    View-only access. Viewers can see messages, analytics, segments, templates, and most app data, but cannot create, edit, send, or export anything.

    | Area                          | Permissions                            |
    | ----------------------------- | -------------------------------------- |
    | Messaging                     | View messages and analytics            |
    | Journeys                      | View journeys and analytics            |
    | Segments                      | View segments and analytics            |
    | Templates and dynamic content | View only                              |
    | In-app messages               | View messages and analytics            |
    | Users and subscriptions       | View only                              |
    | Webhooks and event streams    | View webhooks and results              |
    | Custom events and outcomes    | View analytics                         |
    | Labels                        | View only                              |
    | Suppressions                  | View only                              |
    | Integrations                  | View only                              |
    | App settings                  | View app and analytics                 |
    | Org settings                  | View org and apps                      |
    | Account                       | 2FA, email, and password (own account) |

    **Cannot:** Create, edit, send, activate, or delete anything. Export any data. Import users. Access API keys or manage settings.
  </Tab>

  <Tab title="Team Member">
    **Scope:** Organization only

    The `team_member` role grants no app permissions on its own. It provides minimal org-level visibility while app access is layered on through app-level role assignments.

    | Area            | Permissions                                   |
    | --------------- | --------------------------------------------- |
    | Org settings    | View org and apps list                        |
    | Account         | 2FA, email, and password (own account)        |
    | Everything else | No access until an app-level role is assigned |

    `team_member` is automatically assigned in two situations:

    * When a new user is invited to an App for the first time and has no existing Organization role
    * When a user logs in through SSO for the first time and their identity provider has not yet been mapped to a specific OneSignal role
  </Tab>

  <Tab title="Operations">
    **Scope:** Organization and App

    Operations has view access across all features plus write access to suppressions and sender identities. This role is designed for operational tasks like managing suppression lists without granting broader messaging or settings permissions.

    | Area                          | Permissions                            |
    | ----------------------------- | -------------------------------------- |
    | Messaging                     | View messages and analytics            |
    | Journeys                      | View journeys and analytics            |
    | Segments                      | View segments and analytics            |
    | Templates and dynamic content | View only                              |
    | In-app messages               | View messages and analytics            |
    | Users and subscriptions       | View only                              |
    | Webhooks and event streams    | View webhooks and results              |
    | Custom events and outcomes    | View analytics                         |
    | Labels                        | View only                              |
    | Suppressions                  | Create, delete, and export             |
    | Sender identities             | Create and edit                        |
    | Integrations                  | View only                              |
    | App settings                  | View app, analytics, and team members  |
    | Org settings                  | View org, apps, and members            |
    | Account                       | 2FA, email, and password (own account) |

    **Cannot:** Create, send, or edit messages. Manage journeys, segments, or templates. Import or export users. Manage API keys. Edit app or org settings.
  </Tab>

  <Tab title="Finance">
    **Scope:** Organization only

    Finance is an org-level role focused on billing access. It does not include any app-level permissions.

    | Area            | Permissions                                        |
    | --------------- | -------------------------------------------------- |
    | Org settings    | View org, view apps, view members, view audit logs |
    | Billing         | View and edit billing                              |
    | Account         | 2FA, email, and password (own account)             |
    | Everything else | No access                                          |

    **Cannot:** View or interact with any app-level features. Send messages. Manage team members. Access API keys.
  </Tab>
</Tabs>

### Role availability by plan

Role availability differs between Organization-level and App-level roles. Team Member and Finance are Organization-only roles. All other roles have both an Organization and App equivalent.

#### Organization roles

| Role        | Free Plan | Growth Plan | Professional Plan | Enterprise |
| ----------- | :-------: | :---------: | :---------------: | :--------: |
| Admin       |     ✅     |      ✅      |         ✅         |      ✅     |
| Team Member |     ✅     |      ✅      |         ✅         |      ✅     |
| Viewer      |     ❌     |      ✅      |         ✅         |      ✅     |
| Editor      |     ❌     |      ❌      |         ✅         |      ✅     |
| Composer    |     ❌     |      ❌      |         ✅         |      ✅     |
| Finance     |     ❌     |      ❌      |         ❌         |      ✅     |
| Operations  |     ❌     |      ❌      |         ❌         |      ✅     |

#### App-level roles

| Role       | Free Plan | Growth Plan | Professional Plan | Enterprise |
| ---------- | :-------: | :---------: | :---------------: | :--------: |
| Admin      |     ✅     |      ✅      |         ✅         |      ✅     |
| Viewer     |     ❌     |      ✅      |         ✅         |      ✅     |
| Editor     |     ❌     |      ❌      |         ✅         |      ✅     |
| Composer   |     ❌     |      ❌      |         ✅         |      ✅     |
| Operations |     ❌     |      ❌      |         ❌         |      ✅     |

***

## Best practices

* **Assign the minimum role needed.** Don't give full Admin access if Composer or Viewer is enough.
* **Use Organization roles** for users who need access across many Apps, like analysts or leadership.
* **Use the Team Member role** with App-level assignments for users who only need access to specific Apps.
* **Limit API key access** to trusted technical users with Admin roles.
* **Upgrade your plan** to unlock additional roles beyond Admin and Team Member.


# Personalization
Source: https://documentation.onesignal.com/docs/en/message-personalization

Choose the right personalization method in OneSignal. Compare Properties, Custom Events, API custom_data, Data Feeds, and CSV uploads to send dynamic messages using Liquid syntax.

<Frame>
  <iframe title="YouTube video player" />
</Frame>

Personalization lets you send messages that include dynamic data — such as a user's name, cart items, account balance, booking details, or a one-time password.

This guide helps you choose the right personalization method based on:

* Where your data lives
* Whether it should persist
* How the message is triggered

***

## How personalization works

Personalization in OneSignal has two parts:

1. **Liquid syntax** – defines how values render in your message
2. **A data source** – determines where the value comes from

At send time, OneSignal resolves your Liquid variables using the selected data source.

<Info>
  Liquid controls formatting and logic (variables, loops, conditionals). The data source determines what values are available.
</Info>

**Example:**

```liquid Liquid theme={null}
Hi {{ user.tags.first_name }},

Your verification code is {{ message.custom_data.otp }}.
```

* `user.tags.first_name` is a stored property
* `message.custom_data.otp` is passed via the API `custom_data` field

***

## Supported fields by message type

<Tabs>
  <Tab title="Email">
    * Subject, Reply-to, and Pre-header
    * Message Body
    * Image substitution in HTML blocks. Example: `<img src="{{image_url}}"/>`
    * Button block actions like URLs, Mail to, and other fields.
  </Tab>

  <Tab title="Push">
    * Title (`headings`), Subtitle, Body (`contents`)
    * Image URL
    * Launch URL. Example: `https://example.com/{{last_category_viewed}}`
    * Additional `data` doesn't support Liquid syntax.
  </Tab>

  <Tab title="SMS">
    * Message Body (`contents`)
  </Tab>

  <Tab title="In-App Messages">
    <Warning>
      Only Tag substitution is supported at this time.

      The tag must be set before the user opens the app to start a new session. The tags available are in the [`getTags` method](./mobile-sdk-reference#gettags).
    </Warning>

    **Block editor:**

    * Tag substitution works in Text, Button, Image Blocks.

    **HTML editor:**

    * Tag substitution works in:
      * Header `<h*>` and `<p>` tags. Example: `<h2>Hello {{first_name}}!</h2>`
      * Element attributes: `["src", "href", "action", "data"]`. Example: `<img src="{{image_url}}"/>`

    <Note>
      See [In-app message JavaScript APIs](./in-app-message-api) for more details and examples.
    </Note>
  </Tab>

  <Tab title="Live Activities">
    * Within the `event_updates`, `contents` and `headings` properties.
  </Tab>
</Tabs>

***

## Data sources

OneSignal supports five data sources for personalization. Use the table below to identify which source fits your use case, then read the detailed section for implementation guidance.

| Data source                                     | What it is                                               | When to use                                                         | Persisted | Available in Journeys |
| ----------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------- | --------- | --------------------- |
| [**Properties**](#properties)                   | Tags, External ID, subscription data, app fields         | Reusable values stored in OneSignal (name, plan, preferences)       | Yes       | Yes                   |
| [**Custom Events**](#custom-events)             | Event properties captured at Journey entry or Wait Until | Behavioral personalization inside Journeys                          | Per event | Journey only          |
| [**API `custom_data`**](#api-custom_data)       | Key-value pairs passed in the Create Message API         | One-time or sensitive values (OTP, secure links, cart items)        | No        | No                    |
| [**Data Feeds**](#data-feeds)                   | Live API call made at send time                          | Values that change frequently (pricing, inventory, account balance) | No        | Yes                   |
| [**Dynamic Content CSV**](#dynamic-content-csv) | CSV uploaded in the dashboard                            | Bulk campaigns with per-recipient content                           | Per send  | No                    |

<Warning>
  **Common mistakes to avoid**

  * Using Properties (Tags) for one-time values like OTPs or verification codes — use `custom_data` instead
  * Expecting `custom_data` to be available in Journeys or future messages — it exists only for the current API request
  * Assuming Custom Event properties are available outside of the event-triggered Journey entry or a Wait Until step
  * Using Data Feeds for static data that rarely changes — use Properties instead
</Warning>

### Properties

Properties include Tags, External ID, subscription data, and app-level fields.

They are:

* Persistent
* Reusable
* Available across messages, templates, [Journey webhooks](./journeys-webhook), and [Event Streams](./event-streams).

**Use Properties when:**

* The value exists in OneSignal
* The value is persistent
* You reuse it across campaigns

<Card title="Personalize with Properties" icon="tag" href="./personalization-properties-and-tags">
  Learn how to reference stored persistent property data.
</Card>

***

### Custom Events

[Custom Events](./custom-events) can personalize messages inside [Journeys](./journeys-overview) using event properties.

When an event **starts a Journey** or **matches a Wait Until condition**, OneSignal stores that event so its properties can be referenced in message templates using Liquid.

**When to use Custom Events:**

* Event triggered messages with Journeys
* The message should reflect event-specific data

<Warning> Only events that trigger Journey entry or a Wait Until step are stored for personalization. Events sent outside those moments are not available to Journey messages. </Warning>

<Card title="Custom Event personalization" icon="bolt" href="./personalization-custom-event">
  Complete guide to using event properties to personalize Journeys.
</Card>

***

### API `custom_data`

The `custom_data` field in the [Create Message API](/reference/create-message) lets you send message-specific values from your backend.

This data:

* Exists only for the current request
* Is not stored in OneSignal
* Is not available in Journeys

**Use `custom_data` when:**

* Sending one-time or sensitive values (OTP, secure links)
* Passing arrays (cart items, order lines, leaderboard scores)
* Sending transactional or API-triggered messages

<Card title="Personalize with API custom_data" icon="code" href="./personalization-api-custom-data">
  Learn how to pass transient personalization data.
</Card>

***

### Data Feeds

[Data Feeds](./data-feeds) call your API at send time and inject the response into your message.

**When to use Data Feeds:**

* You need the latest value at delivery
* The data lives in your backend
* The value may change between sends

<Card title="Data Feeds" icon="cloud-arrow-up" href="./data-feeds">
  Pull real-time backend data into messages at send time.
</Card>

***

### Dynamic Content CSV

Upload a CSV file into the OneSignal dashboard and reference its values using Liquid.

**Use CSV when:**

* Customizing different sections of a bulk campaign for each recipient
* Translations or custom data for each recipient is exportable to a CSV file
* You do not want to use the API

<Card title="Dynamic Content CSV" icon="file-csv" href="./dynamic-content">
  Personalize dashboard campaigns using CSV uploads.
</Card>

***

## Detailed guides

Use the guides below for step-by-step implementation details and advanced examples.

<Columns>
  <Card title="Using Liquid syntax" icon="droplet" href="./using-liquid-syntax">
    Learn how to insert dynamic data into messages using Liquid. Covers variables, conditionals, loops, filters, formatting, and common personalization patterns.
  </Card>

  <Card title="Data Feeds" icon="cloud-arrow-up" href="./data-feeds">
    Pull real-time data from your own APIs at send time. Use Data Feeds when message content depends on live backend values like balances, availability, or pricing.
  </Card>

  <Card title="Custom Events personalization" icon="bolt" href="./personalization-custom-event">
    Personalize Journey messages using event properties captured when users enter or progress through a Journey. Ideal for behavioral and event-driven workflows.
  </Card>

  <Card title="Properties & Tags" icon="tag" href="./personalization-properties-and-tags">
    Use stored user, subscription, message, and app properties to personalize content across messages, templates, Journey webhooks, and Event Streams.
  </Card>

  <Card title="API custom_data" icon="code" href="./personalization-api-custom-data">
    Pass per-message and transient data from your backend using the Create Message API. Best for OTPs, carts, arrays, and bulk transactional personalization.
  </Card>

  <Card title="Dynamic Content CSV" icon="file-csv" href="./dynamic-content">
    Upload CSV files in the dashboard to personalize campaigns at scale. Each row maps to a recipient and can be referenced using Liquid.
  </Card>
</Columns>

### Tutorials

These guides show how to implement personalization in practice.

<Columns>
  <Card title="Verification, Magic Link, & OTP" icon="key" href="./example-verification-magic-link-otp">
    Send secure verification messages using one-time passwords, magic links, or custom URLs with API-driven personalization.
  </Card>

  <Card title="Abandoned cart Journey" icon="cart-shopping" href="./abandoned-cart">
    Build an automated Journey that detects cart activity, waits for inactivity, sends a personalized reminder, and exits users immediately after purchase.
  </Card>

  <Card title="Booking confirmations" icon="calendar" href="./booking-confirmations">
    Send booking confirmation and recovery messages using Custom Events, Journeys, and Data Feeds based on real-time reservation status.
  </Card>

  <Card title="Transactional messages" icon="receipt" href="./transactional-messages">
    Learn how to send receipts, alerts, confirmations, and other transactional messages across channels using APIs and automation.
  </Card>
</Columns>


# Migrating to OneSignal
Source: https://documentation.onesignal.com/docs/en/migrating-to-onesignal

Migrate to OneSignal from another messaging provider with SDK integration, user import, phased rollout, and testing guidance.

This guide covers how to migrate from your current messaging platform to OneSignal with minimal disruption.

It’s designed for:

* **Developers** implementing the OneSignal SDK
* **Marketers** managing campaigns and analytics

***

## Prerequisites

Before you begin:

* Set up an account at [OneSignal](https://onesignal.com)
* [Invite your team](./manage-team-members)

***

## Migration steps

### 1. Audit your current messaging setup

Before migration, take inventory of your current implementation:

**For developers:**

* The platforms you support: iOS, Android, Web, email, SMS, etc.
* The code handling push and in-app message events:
  * Foreground displaying and click handling
  * Deep link usage for push, email, etc.
  * Push token and payload handling
* How you are collecting email addresses, phone numbers, push tokens, etc.
* Email domains and DNS ownership
* SMS senders and opt-in mechanisms

**For marketers:**

* The types of messages you send (transactional, marketing, etc.) and the templates for each
* How you segment and target users
* The analytics or conversion metrics you track

### 2. Map your terminology to OneSignal

Most messaging platforms share similar concepts under different names. Here's how OneSignal's terms map to what you're likely already using:

| Your platform                           | OneSignal term                  | Details                                                                                  |
| --------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------- |
| User / contact / profile                | [User](./users)                 | Identified by an External ID. Contains properties and subscriptions.                     |
| Push token, email address, phone number | [Subscription](./subscriptions) | A channel through which a user can receive messages (mobile push, web push, email, SMS). |
| Audience, cohort, list                  | [Segment](./segmentation)       | A dynamic group of users based on shared properties or behavior.                         |
| Custom attribute, user property         | [Tag](./add-user-data-tags)     | A key-value pair attached to a user for targeting and personalization.                   |
| Tracked action, analytics event         | [Custom Event](./custom-events) | An action a user takes, used for segmentation and triggering messages.                   |

### 3. Add the OneSignal SDK (developers)

Set up the OneSignal SDK in your mobile app and/or website:

<Columns>
  <Card title="Mobile SDK setup" icon="mobile" href="./mobile-sdk-setup">
    Required for in-app messages and recommended for push notifications on iOS and Android.
  </Card>

  <Card title="Web SDK setup" icon="globe" href="./web-sdk-setup">
    Required for web push notifications.
  </Card>
</Columns>

After integrating the SDK, use the following methods to identify users and collect subscription data:

* **`login`** — Set the [External ID](./users#external-id) to identify a user across devices and channels.
* **`addEmail`** — Create an email subscription from an address collected in your app or site.
* **`addSms`** — Create an SMS subscription from a phone number collected in your app or site.

See the SDK references for implementation details:

<Columns>
  <Card title="Mobile SDK reference" icon="mobile" href="./mobile-sdk-reference">
    Methods for `login`, `addEmail`, `addSms`, push token access, and notification listeners.
  </Card>

  <Card title="Web SDK reference" icon="globe" href="./web-sdk-reference">
    Methods for `login`, `addEmail`, `addSms`, and web push event handling.
  </Card>
</Columns>

### 4. Remove your legacy implementation

There are two migration paths:

* **Clean migration** — Remove your old SDK entirely and replace it with OneSignal in a single app release. This is the recommended approach.
* **Phased migration** — Keep both SDKs temporarily, sending from each provider to different user groups based on app version. Use this only if you cannot remove the old SDK in one release.

In either case, remove legacy methods and APIs for collecting push tokens, email addresses, and phone numbers. Push token collection in particular can create conflicts with the OneSignal SDK.

#### Push token conflicts & format

Remove all legacy code generating push tokens. Only allow OneSignal to generate the push token which happens automatically when the SDK is initialized.

If needed, use our SDK to get the token and send it to your other provider or backend. Methods for doing so:

* Get device's push token identifier using our [Frontend Mobile SDK](./mobile-sdk-reference#user-pushsubscription-token)
* Get device's identifier using our [View user](/reference/view-user) API

<Note>
  Push token formats differ by platform (iOS APNS vs. Android FCM). See [Push token formats](./osnotification-payload#push-token-formats) for details.
</Note>

#### Firebase Messaging SDK conflict

If your app includes the Firebase Messaging SDK (`firebase_messaging` or a custom `FirebaseMessagingService`), it can intercept FCM messages before OneSignal processes them. This causes notifications to show as "Delivered" in OneSignal but never appear on the device.

To resolve this:

* Remove legacy Firebase receivers from `AndroidManifest.xml`.
* Do not call `FirebaseMessaging.getToken()` or `FirebaseMessaging.deleteToken()`.
* Ensure OneSignal is the only SDK managing the push token lifecycle.

See [Firebase Messaging SDK conflict](./notifications-show-successful-but-are-not-being-shown#firebase-messaging-sdk-conflict) for full troubleshooting steps.

#### Push payload handling

If using OneSignal and another push provider in parallel, you'll need to prevent your other SDK from processing OneSignal notifications to avoid duplicates.

OneSignal's push payload contains a `"custom"` key in the `rawPayload` that distinguishes it from other providers. If running both SDKs, update your notification handler to check this key so your legacy SDK doesn't process OneSignal notifications. See the [OSNotification payload](./osnotification-payload) reference for details.

#### Phased migration (mobile apps only)

A common approach is to continue sending from your old provider to users on the older app version and from OneSignal to users on the newer version. However, if you must keep both SDKs for a limited time:

* Let OneSignal manage push tokens exclusively. Share the token with your old system if needed (see [Push token conflicts](#push-token-conflicts--format) above).
* Update payload filters so your legacy SDK ignores OneSignal pushes (see [Push payload handling](#push-payload-handling) above).
* Send from your old provider to users on the older app version and from OneSignal to users on the newer version.
* Set a clear cutoff date and phase-out plan.

### 5. Web push migration

If you're using the same HTTPS site [origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy), subscribers are silently added to OneSignal on their next visit — no prompt is shown and they can receive push immediately. Web push subscriptions cannot be imported due to browser security limits.

Before OneSignal can take over, you must unregister your old push service workers:

1. Remove the legacy SDK code and Service Worker files from your website.
2. Add the following snippet to unregister the old Service Worker. Replace `sw.js` with the filename of your legacy provider's Service Worker.

```javascript theme={null}
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.getRegistrations().then(function(registrations) {
    for (let registration of registrations) {
      if (registration.active.scriptURL.includes("sw.js")) {
        registration.unregister();
      }
    }
  });
}
```

#### Migrating between OneSignal apps

If you are moving subscribers from one OneSignal app (App A) to another (App B):

* Web push subscriptions cannot be transferred directly between apps. Each subscription is tied to both your site’s domain (origin) and the OneSignal App ID.

* To migrate, update your site’s OneSignal initialization code to use App B’s appId:

```javascript theme={null}
OneSignal.init({
  appId: "YOUR_APP_B_ID",
});
```

* When a user revisits your site, the browser’s existing push permission will allow OneSignal to silently register them in App B.

* No new permission prompt will appear, but users must visit your site at least once for the subscription to be created in App B.

* Subscribers will continue to appear in App A until they become inactive.

<Info>
  **Best practice:** Stop sending from App A once you confirm enough users have migrated. Monitor subscriber counts in both apps to validate migration progress.
</Info>

### 6. Email and SMS setup

If you are sending emails and/or SMS with OneSignal, you will need to follow our [Email setup](./email-setup) and [SMS setup](./sms-setup) guides.

Migrating your current email sending domain to OneSignal requires updating the DNS records. You can set up multiple email senders in OneSignal if needed.

Migrating SMS senders may take time. Contact `support@onesignal.com` if you need assistance.

### 7. Import existing users (optional)

Importing subscribed users that have been active in your app within the past 270 days will help minimize disruption during migration.

We recommend you start by importing known test users, then import the remaining users before app launch.

#### Platform considerations

* Email addresses must be from active and valid users. Do not import email addresses that have never clicked or opened emails before.
* Phone numbers must be in a specific format and users must have consented to receive SMS.
* iOS subscriptions can start receiving push notifications immediately after import. Features like notification click tracking and confirmed deliveries require our SDK to be active on the device.
* Android/Huawei/Amazon subscriptions must have our SDK active on the device to receive notifications, either through an auto-update or manual update.
* Web subscriptions cannot be imported. If you follow the above in [Web push migration](#5-web-push-migration), the web push subscription will be created and push token fetched via our SDK when the user returns to the site.

#### Import steps

1. Review the [Users](./users) and [Subscriptions](./subscriptions) docs.
2. Export test user data from your old system.
3. Format data for OneSignal's [Create user](/reference/create-user) API.
4. Import test users first. Once verified, repeat the process for remaining users before release.

Each user needs an `external_id` (identity) and at least one subscription with a `type` and `token` (or `email`/`phone_number`). See the [Create user API reference](/reference/create-user) for required fields, supported subscription types, and example payloads.

### 8. Test the migration

Thorough testing is crucial for a smooth transition.

1. Enable [Debug Logging](./capturing-a-debug-log) in the OneSignal SDK.
2. Test on real devices for all platforms (Android, iOS, Web, etc.).
3. Verify both foreground and background notification handling.

**Test scenarios for development and marketing teams:**

* Send test notifications from OneSignal to imported users **before adding the OneSignal SDK**.
  * You should receive the push on iOS but will not get confirmed receipt or click analytics.
  * You may receive the push on Android if you have another push SDK and did not implement the [Payload handling](#push-payload-handling) requirements yet. The notification is likely missing data and doesn't work as expected when clicked.

* Send test notifications from OneSignal to imported users **after adding the OneSignal SDK**.
  * You should receive the push on both Android and iOS along with confirmed receipt and click analytics.

* Test notification behavior with app in different states.

* Verify deep links and custom actions work correctly.

**If using multiple providers:**

* Send from both your current provider and OneSignal.
* Check for duplicate notifications.
* Verify each provider's notifications display correctly.
* Test user login/logout scenarios.

***

## Pre-release checklist

**For marketers:**

* Build a messaging plan to prompt app updates
* Consider using push and in-app messages from your old system to gently remind users to update.

**For developers:**

* Verify that push and in-app message analytics are working as expected.
  * Click events and confirmed receipt are tracked across Android and iOS.
* Verify click events and foreground received events are handled correctly for messages sent from both providers.
* If importing users, export Android and iOS users that have been active in your app within the past 270 days to prevent importing expired tokens. See [FCM Expired Token FAQ](./fcm-expired-token-faq) for details.

***

## Release your app/site

* Most users will have their apps automatically update to the latest version.
* When users open your updated app, they will not be prompted to subscribe to push notifications if permissions were already granted—either through the required permission prompts or the app’s notification settings.

**If you did not import users:**

* Users will be created automatically in OneSignal when they open the updated version of the app. They will not be prompted for push if previously subscribed.
* You will need to wait for them to open the updated app before you can send them messages.
* Continue sending notifications and in-app messages from the previous push provider for a couple days until enough users show up in OneSignal. Send additional alerts asking them to update the app to the latest version.

***

## Monitor results

**For developers:**

* Monitor error rates and crashes after deployment.
* Watch for unexpected token invalidations.
* Check SDK integration analytics.

**For marketers:**

* Mark the date of app release and confirm with your developers which migration path was taken ([clean or phased](#4-remove-your-legacy-implementation)) and whether users were imported.
* In your previous platform, create a segment of users who have not yet updated to the new app version. Continue sending from your old provider to this group, nudging them to update.
* Stop sending from the previous provider once subscriber counts stabilize in OneSignal.
* If following a **phased migration**, remove the old provider's SDK in your next app release after the cutoff date.

***

## FAQ

### Can I run OneSignal alongside my current push provider?

Yes, but only temporarily. Running two push SDKs in parallel can cause token conflicts and duplicate notifications. If you need a phased migration, follow the [Phased migration](#phased-migration-mobile-apps-only) guidance to prevent conflicts and set a clear cutoff date.

### Can I import web push subscribers?

No. Browser security restrictions prevent transferring web push subscriptions between providers. When you integrate OneSignal on your site, existing subscribers are silently re-registered on their next visit — no new prompt is shown. See [Web push migration](#5-web-push-migration).

### Do I need to re-prompt users for push permission after migrating?

No. If users already granted push permission to your app or site, OneSignal uses the existing permission. No new prompt is displayed.

### Is email warm-up required?

Not if your sending domain already has an established sending reputation. Warm-up is only required if you are using a dedicated IP address.

### Can I get a dedicated IP address?

Yes, depending on your plan type and sending volume. Contact your account manager for details.

### How long should I keep sending from my old provider?

Continue sending from your old provider until most users have opened the updated app with the OneSignal SDK. Monitor subscriber counts in both systems and stop sending from the old provider once the numbers stabilize.

***

<Check>
  You have successfully migrated to OneSignal! For strategy questions about migration planning, contact our customer success team for personalized guidance.
</Check>

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# Mobile push setup
Source: https://documentation.onesignal.com/docs/en/mobile-push-setup

End-to-end checklist for setting up mobile push notifications with OneSignal across iOS, Android, Huawei, and Amazon.

Push notifications re-engage Users when they're not actively using your app. They can display text and rich content like images, buttons, and sounds.

<Frame>
  <img alt="iOS and Android mobile push notification examples showing rich content" />
</Frame>

For push to work on mobile:

* Users must have your mobile app installed
* You must configure the correct platform credentials (FCM for Android, APNs for iOS, HMS for Huawei, ADM for Amazon)
* Users must grant permission to receive notifications

This guide walks through every step from SDK setup to sending personalized push messages.

***

## SDK setup and migration

Integrate the OneSignal SDK into your app to register devices and enable push messaging. If you're migrating from another provider, OneSignal supports migration from Firebase, Airship, Braze, and others.

<Columns>
  <Card title="Mobile SDK setup" icon="mobile" href="./mobile-sdk-setup">
    Integrate the OneSignal SDK into your app to register devices and enable push messaging.
  </Card>

  <Card title="Migration from another provider" icon="arrow-right-arrow-left" href="./migrating-to-onesignal">
    Migrate from Firebase, Airship, Braze, or other push providers.
  </Card>
</Columns>

***

## Push permission prompts

Mobile platforms require Users to opt in before they can receive push notifications. Apple's [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/ios/system-capabilities/notifications) recommend describing what types of information you want to send and giving Users a clear way to opt in or out.

You can build a pre-permission prompt using OneSignal's in-app messages to explain the value before triggering the system prompt.

<Frame>
  <img alt="OneSignal in-app message used as a pre-permission prompt for push notifications" />
</Frame>

<Columns>
  <Card title="Prompt for push permissions" icon="bell" href="./prompt-for-push-permissions">
    Build a custom pre-permission prompt using in-app messages.
  </Card>

  <Card title="Mobile SDK reference" icon="code" href="./mobile-sdk-reference">
    Programmatically trigger permission requests in the SDK.
  </Card>

  <Card title="iOS provisional push" icon="apple" href="./ios-provisional-push-notifications">
    Show silent notifications in the notification center before prompting.
  </Card>
</Columns>

***

## Users and Subscriptions

Once the SDK is active, OneSignal automatically creates User and Subscription records as people open your app.

Mobile Subscriptions are created when Users:

* Open the app for the first time on a device
* Uninstall and reinstall the app, then open it again

Each device creates a separate Subscription. Subscriptions remain anonymous until you assign them an [External ID](./users#external-id) via `OneSignal.login`.

<Frame>
  <img alt="OneSignal dashboard Users page showing a list of Users with Subscription details" />
</Frame>

<Columns>
  <Card title="Users" icon="users" href="./users">
    Manage Users, assign External IDs, and understand anonymous vs. identified Users.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    How Subscriptions are created and managed across devices and channels.
  </Card>

  <Card title="Segments" icon="chart-pie" href="./segmentation">
    Group Users into dynamic segments for targeted messaging.
  </Card>
</Columns>

***

## Design push notifications

Crafting effective push notifications involves more than text. Watch how to make every push notification count, then explore the design elements below.

<Frame>
  <iframe title="YouTube video player" />
</Frame>

<Frame>
  <img alt="Annotated diagram showing the anatomy of iOS and Android push notifications" />
</Frame>

1. [Title](./push#title): Attention-grabbing headline (recommended: under 50 characters)
2. [Message](./push#message): Main notification content (recommended: under 120 characters)
3. [Icons](./notification-icons): Your brand icon or notification-specific image
4. [Large image](./push#image): Eye-catching visual content
5. [Action buttons](./action-buttons): Call-to-action buttons
6. Timestamp when push was received
7. [App name](./push#app-name): The name of your app

<Columns>
  <Card title="Push overview" icon="bell" href="./push">
    Full overview of push notification creation, options, and delivery behavior.
  </Card>

  <Card title="Templates" icon="clone" href="./templates">
    Save time with reusable templates for consistent messaging.
  </Card>
</Columns>

### Personalization and localization

Watch how to turn generic push notifications into high-performing messages, then explore the personalization options below.

<Frame>
  <iframe title="YouTube video player" />
</Frame>

<Columns>
  <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
    Insert dynamic variables like name or preferences to tailor messages.
  </Card>

  <Card title="Multi-language messaging" icon="language" href="./multi-language-messaging">
    Automatically deliver messages in each User's preferred language.
  </Card>
</Columns>

***

## Configure push behavior

Control how notifications behave after delivery, including timing, display settings, and User interactions.

### Delivery, display, and dismiss settings

<Columns>
  <Card title="Throttling" icon="gauge-high" href="./throttling">
    Control notification delivery speed for large audiences.
  </Card>

  <Card title="Frequency capping" icon="hand" href="./frequency-capping">
    Set limits to prevent over-sending notifications to the same User.
  </Card>

  <Card title="Time to live (TTL)" icon="clock" href="./push#time-to-live-ttl">
    Define how long push services retain messages when the device is offline.
  </Card>

  <Card title="Collapse ID" icon="layer-group" href="./push#collapse-id-mobile-push">
    Replace previous messages with newer ones to reduce notification clutter.
  </Card>

  <Card title="Android notification categories" icon="android" href="./android-notification-categories">
    Control importance level (banner, silent) and other display aspects.
  </Card>

  <Card title="iOS focus modes and interruption levels" icon="apple" href="./ios-focus-modes-and-interruption-levels">
    Control priority level (passive, time-sensitive) for iOS.
  </Card>

  <Card title="Notification sounds" icon="volume-high" href="./notification-sounds">
    Configure notification audio for each platform.
  </Card>

  <Card title="Badges" icon="circle-1" href="./badges">
    Manage app icon badge count behavior on iOS.
  </Card>
</Columns>

### Data and background notifications

Include custom data in push payloads that your app can handle without displaying a visible notification.

<Columns>
  <Card title="Data and background notifications" icon="database" href="./data-notifications">
    Send custom payloads without a visual notification.
  </Card>

  <Card title="Additional data" icon="brackets-curly" href="./push#additional-data">
    Attach key-value data to push payloads for in-app handling.
  </Card>
</Columns>

### Click behavior and deep linking

Control what happens when a User taps a notification.

<Columns>
  <Card title="URLs, links, and deep linking" icon="link" href="./links">
    Route Users to relevant content or pages using deep links and tracking URLs.
  </Card>

  <Card title="Deep linking" icon="arrow-up-right-from-square" href="./deep-linking">
    Platform-specific deep linking implementation details.
  </Card>

  <Card title="Action buttons" icon="hand-pointer" href="./action-buttons">
    Let Users take immediate actions from your notification.
  </Card>

  <Card title="Notification event observers" icon="code" href="./mobile-sdk-reference#push-notification-events">
    Listen for click events and trigger in-app behavior with custom code.
  </Card>
</Columns>

***

## Analytics and troubleshooting

Measure notification performance and resolve common delivery issues.

<Columns>
  <Card title="Push message reports" icon="chart-line" href="./push-notification-message-reports">
    View delivery, open rate, and click-through metrics for each message.
  </Card>

  <Card title="Analytics overview" icon="chart-bar" href="./analytics-overview">
    Explore engagement and User behavior metrics across channels.
  </Card>

  <Card title="Notifications not shown or delayed" icon="circle-exclamation" href="./notifications-show-successful-but-are-not-being-shown">
    Troubleshooting checklist if messages aren't appearing on devices.
  </Card>

  <Card title="Notification images not showing" icon="image" href="./notification-images-not-showing">
    Fix image rendering issues across platforms.
  </Card>

  <Card title="Duplicate notifications" icon="copy" href="./duplicated-notifications">
    Troubleshoot why duplicate notifications are being displayed.
  </Card>
</Columns>

***

## Next steps

<Columns>
  <Card title="A/B testing" icon="flask" href="./ab-testing">
    Optimize messages with experiments to find what drives engagement.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build automated, multi-step messaging flows triggered by User behavior.
  </Card>

  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Add User-level data for personalization and targeting.
  </Card>

  <Card title="In-app messages" icon="window-maximize" href="./in-app-messages-setup">
    Reach Users with rich, interactive messages inside your app.
  </Card>
</Columns>

***

## FAQ

### Do Users need to opt in for push notifications?

Yes. Both iOS and Android require Users to grant permission before they can receive push notifications. On iOS, you must show the system prompt. On Android 13+, the `POST_NOTIFICATIONS` permission is required. Use a [pre-permission prompt](./prompt-for-push-permissions) to explain the value before triggering the system dialog.

### What are FCM, APNs, HMS, and ADM?

These are platform-specific push delivery services. **FCM** (Firebase Cloud Messaging) delivers to Android and web. **APNs** (Apple Push Notification service) delivers to iOS and macOS. **HMS** (Huawei Mobile Services) delivers to Huawei devices. **ADM** (Amazon Device Messaging) delivers to Amazon Fire devices. You configure credentials for each in the OneSignal dashboard during [SDK setup](./mobile-sdk-setup).

### Why aren't my push notifications showing?

Common causes include missing or expired platform credentials, Users not granting permission, or device-level settings like Do Not Disturb or Focus modes. See [Notifications not shown or delayed](./notifications-show-successful-but-are-not-being-shown) for a full troubleshooting checklist.

### Can I send push notifications without a visible notification?

Yes. Use [data and background notifications](./data-notifications) to send custom payloads that your app handles silently. These are useful for triggering background syncs, updating local data, or refreshing content without interrupting the User.


# Multi-language messaging
Source: https://documentation.onesignal.com/docs/en/multi-language-messaging

Send personalized messages in multiple languages across push, email, and in-app messaging using OneSignal's dashboard or API.

This guide explains how to set a user's language in OneSignal and send messages in their preferred language across push notifications, emails, and in-app messages.

## Set user's language

OneSignal automatically sets the `language` property from the device’s language when a user is first created using the web or mobile SDKs.

You can also manually set or update the user's language using the [ISO 639-1](#supported-languages) 2-letter language code with:

1. The SDK’s `setLanguage` method.
2. The `language` field in the [Create user](/reference/create-user) or [Update user](/reference/update-user) APIs.
3. The `language` column in the [CSV Importer](./import).

<Note>
  See [Supported languages](#supported-languages) for a list of valid language codes.
</Note>

***

## Send messages in different languages

Use tabs below to view localization options by messaging channel.

<Tabs>
  <Tab title="Push Notifications">
    ### Dashboard sending

    From **Messages > Push > New Message** or [Templates](./templates), click **Add Languages**. Choose from:

    #### Option 1: Checkboxes

    Select languages you support. Any language not selected will fall back to Any/English.

    <Frame>
      <img />
    </Frame>

    #### Option 2: Import language content

    Use the provided template to format the message in each language.

    <Frame>
      <img />
    </Frame>

    Copy and paste the content back into the "Add Languages" field.

    <Frame>
      <img />
    </Frame>

    Preview content to double-check, insert content, and new tabs will appear in the editor with the designated content filled out.

    <Frame>
      <img />
    </Frame>

    #### Option 3: Dynamic Content

    Use [Dynamic Content](./dynamic-content) which involves creating and uploading a CSV file with the languages you support.

    #### Troubleshooting

    * **English required**: Include a row for `en` as default.
    * **Use correct headers**: `language_code`, `title`, `subtitle`, `message`
    * **Comma-separated values**: Ensure proper CSV formatting.
    * **Unsupported language**: If not listed in the UI or template, it’s not supported. Use the next best option and contact `support@onesignal.com`.

    <Info>
      The dashboard editor uses a standard HTML field. Special characters like `%` may cause display issues in RTL languages. Add [RLM marks](https://en.wikipedia.org/wiki/Right-to-left_mark) after such characters to fix formatting problems.
    </Info>

    ***

    ### API sending

    The `contents` and `headings` fields support multiple languages:

    ```json theme={null}
      {
        "contents": {
          "en": "English content",
          "fr": "French content"
        },
        "headings": {
          "en": "English heading",
          "fr": "French heading"
        }
      }
    ```
  </Tab>

  <Tab title="Email">
    ### Dashboard sending

    From **Messages > Email > New Message** or [Templates](./templates), choose from:

    #### Option 1: Segments

    1. Create a segment for each language.
    2. Create a template per language.
    3. Send each to its corresponding segment.

    #### Option 2: Liquid syntax

    Use [Liquid syntax](./using-liquid-syntax) and [property or tag substitution](./message-personalization) to create conditional statements in the message and render the appropriate content based on the user's language.

    ```text Liquid theme={null}
    {% assign language = subscription.language %}
    {% if language == 'fr' %}
      Bonjour {{ name }}!
    {% elsif language == 'es' %}
      Hola {{ name }}!
    {% else %}
      Hi {{ name }}!
    {% endif %}
    ```

    <Frame>
      <img />
    </Frame>

    #### Option 3: Dynamic Content

    Use [Dynamic Content](./dynamic-content) which involves creating and uploading a CSV file with the languages you support.

    ***

    ### API sending

    Using the [Create message API](/reference/create-message), you can:

    * Target language segments or filters like you would with the dashboard.
    * Create message Templates with Liquid syntax utilizing `custom_data`, property or tag substitution. See [Message Personalization](./message-personalization) for more details on these options.

    `custom_data` bulk personalization example:

    ```liquid Template theme={null}
    {% assign eid = message.custom_data.users[subscription.external_id] %}
    Hi {{ eid.first_name }}, you have {{ eid.points }} points. Your level is {{ eid.level }}.
    ```

    ```json API Request theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user123", "user456"]
      },
      "custom_data": {
        "users": {
          "user123": { "first_name": "John", "points": "150", "level": "Gold" },
          "user456": { "first_name": "Sarah", "points": "200", "level": "Platinum" }
        }
      }
    }
    ```

    <Check>
      Customer sees:

      * "Hi John, you have 150 points. Your level is Gold."
      * "Hi Sarah, you have 200 points. Your level is Platinum."
    </Check>
  </Tab>

  <Tab title="In-app messages">
    ### Dashboard - Segments

    To send a language-specific In-App Message to each language you need to support:

    1. Create a segment for each language.
    2. Create an in-app message per language.
    3. Send each to its corresponding segment.

    ### Tag substitution

    Use [Liquid syntax](./using-liquid-syntax) and [tag substitution](./message-personalization) to create conditional statements in the message and render the appropriate content based on tags.

    <Warning>
      Only Tag substitution is supported for in-app messages.
    </Warning>

    ```Text Tags theme={null}
    language : german
    first_name : Jon
    ```

    ```Text Template theme={null}
    {% assign lang = language%}
      {% if lang == "english" %}
        Good day {{first_name}}!
      {%- elsif lang == 'german' -%}
        Guten Tag {{first_name}}!
      {%- elsif lang == 'spanish' -%}
        Buenos Dias {{first_name}}!
      {%- elsif lang == 'french' -%}
        Bonjour {{first_name}}!
      {% else %}
        Hello {{first_name}}!
    {% endif %}
    ```

    ```Text Result theme={null}
    Guten Tag Jon!
    ```
  </Tab>

  <Tab title="SMS">
    ### Dashboard sending

    From **Messages > SMS > New Message** or [Templates](./templates), choose from:

    #### Option 1: Segments

    1. Create a segment for each language.
    2. Create a template per language.
    3. Send each to its corresponding segment.

    #### Option 2: Dynamic Content

    Use [Dynamic Content](./dynamic-content) which involves creating and uploading a CSV file with the languages you support.

    ***

    ### API sending

    The `contents` and `headings` fields support multiple languages:

    ```json theme={null}
      {
        "contents": {
          "en": "English content",
          "fr": "French content"
        },
        "headings": {
          "en": "English heading",
          "fr": "French heading"
        }
      }
    ```
  </Tab>
</Tabs>

***

## Supported languages

Language code maps to the `language` user property in the ISO 639-1 code 2-letter format. We support the following language codes.

<Note>
  If the language code is not included in the pop-up and CSV template, then this language is not supported. We recommend using the next best language and sending us a product request to `support@onesignal.com`
</Note>

| Language              | Language Code |
| --------------------- | ------------- |
| English               | en            |
| Arabic                | ar            |
| Azerbaijani           | az            |
| Bosnian               | bs            |
| Catalan               | ca            |
| Chinese (Simplified)  | zh-Hans       |
| Chinese (Traditional) | zh-Hant       |
| Croatian              | hr            |
| Czech                 | cs            |
| Danish                | da            |
| Dutch                 | nl            |
| Estonian              | et            |
| Finnish               | fi            |
| French                | fr            |
| Georgian              | ka            |
| Bulgarian             | bg            |
| German                | de            |
| Greek                 | el            |
| Hindi                 | hi            |
| Hebrew                | he            |
| Hungarian             | hu            |
| Indonesian            | id            |
| Italian               | it            |
| Japanese              | ja            |
| Korean                | ko            |
| Latvian               | lv            |
| Lithuanian            | lt            |
| Malay                 | ms            |
| Norwegian             | nb            |
| Persian               | fa            |
| Polish                | pl            |
| Portuguese            | pt            |
| Punjabi               | pa            |
| Romanian              | ro            |
| Russian               | ru            |
| Serbian               | sr            |
| Slovak                | sk            |
| Spanish               | es            |
| Swedish               | sv            |
| Thai                  | th            |
| Turkish               | tr            |
| Ukrainian             | uk            |
| Vietnamese            | vi            |

***


# Notification click-through rate (CTR)
Source: https://documentation.onesignal.com/docs/en/notification-ctr

Troubleshoot and improve push notification click-through rate (CTR) in OneSignal. Covers how CTR is calculated, common causes of drops, reporting methodology, and tactics to improve engagement.

Click-through rate (CTR) measures how many push notifications users clicked, divided by how many were successfully delivered to the push provider (APNs, FCM). OneSignal calculates CTR as:

```
CTR = (Clicks / Delivered) × 100
```

For canonical metric definitions, see the [Metrics glossary](./analytics-metrics-glossary). To view CTR across channels over time, see [Engagement Trends](./engagement-analytics).

A click is the user tapping the notification to open your app or a landing page. CTR does **not** count:

* Swiping the notification away
* Tapping **Dismiss**
* Clearing the notification tray or Notification Center

## Troubleshoot low CTR

Work through these causes in order. Each one can change either the numerator (clicks) or the denominator (delivered) and produce what looks like a CTR drop.

<AccordionGroup>
  <Accordion title="When did the drop start?">
    Identify the exact date the drop began and the window you're comparing against. CTR is not comparable when you send at a different volume, to different segments, or to a different subscriber count. Pick two windows with similar send volume and targeting before drawing conclusions.
  </Accordion>

  <Accordion title="What are you measuring?">
    Marketing, transactional, and API-triggered messages typically have very different CTR baselines. Compare like with like:

    * Segment your reports by message type or label before comparing.
    * Confirm you are comparing CTR across the same channels (Push only, vs Push + Email blended).
    * Confirm you are using the same denominator across reports — [Delivered](./analytics-metrics-glossary), not Sent.
  </Accordion>

  <Accordion title="Who are you targeting?">
    Over time, users acquire new devices and your Subscription list grows. Old, unreachable Subscriptions continue to count in Sent and Delivered but never click.

    * Clean up stale records using [Delete users](./delete-users).
    * Review the segments used around the date of the drop. A broader segment usually lowers CTR; a narrower one usually raises it.

    <Note>
      Free plans can target up to 10,000 Web Push subscribers. No limit on mobile app Subscriptions. If you have more than 10,000 web push subscribers on a Free plan, you may be sending to older devices. [See pricing](https://onesignal.com/pricing).
    </Note>
  </Accordion>

  <Accordion title="Did your sending patterns change?">
    Changes in send volume, cadence, or audience affect CTR:

    * Sending more API-triggered messages and fewer campaign messages typically lowers CTR because transactional content has different click behavior.
    * Expanding the target segment lowers CTR; tightening it usually raises CTR.
    * Increasing frequency without a content reason often lowers CTR. Users may perceive frequent, unrelated content as spam.

    A common remedy is to target users by topic. On Web, use the [Category Slidedown prompt](./permission-requests) and group users into [Segments](./segmentation) by interest.
  </Accordion>

  <Accordion title="What are you sending?">
    Content quality drives clicks more than any other lever. Review:

    * [Notification appearance](./push) — icons, images, and large media.
    * [Message personalization](./message-personalization) — per-user content with Liquid and Data Tags.
    * [Multi-language messaging](./multi-language-messaging) — localize for every language your audience speaks.
    * [Using emojis in push notifications](https://onesignal.com/blog/how-to-use-emojis-push-notifications/).
  </Accordion>

  <Accordion title="How many notifications are you sending?">
    Excessive sends drive opt-outs and lower CTR. There is no universal limit — frequency tolerance varies by platform, vertical, and content type. If you send multiple notifications per day with content unrelated to the user's interests, expect CTR to decline. Use segmentation and frequency capping to keep the cadence aligned with user expectations.
  </Accordion>

  <Accordion title="How are you gathering the data?">
    Confirm the reporting source. OneSignal reports CTR in the [Dashboard](./analytics-overview), on individual [Push message reports](./push-notification-message-reports), and aggregated in [Engagement Trends](./engagement-analytics). You can also export [Audience Activity](./push-notification-message-reports#audience-activity) to see which Subscriptions registered a click. If you compare OneSignal CTR to a third-party analytics tool, the numbers will differ because click attribution models differ.
  </Accordion>

  <Accordion title="Did anything change in your app or site?">
    Code-level changes can silently suppress click tracking.

    * **OneSignal is not active on every page (Web).** Include OneSignal on all or most pages of the site so the SDK can register clicks after a redirect or navigation.
    * **Multiple service workers (Web).** Additional service workers (for example, a PWA service worker) can interfere with push delivery and click tracking. See [OneSignal service worker](./onesignal-service-worker). After consolidating, users must return to the site for the OneSignal service worker to register.
    * **Android Notification Service Extension calling `complete(null)`.** This suppresses the OneSignal-managed notification. If you display your own notification with the Android API, OneSignal cannot record the click. See [Mobile service extensions](./service-extensions). iOS does not allow apps to suppress remote notifications this way, so this cause is Android-only.
    * **Mobile SDK initialization.** Confirm OneSignal initializes per the [Mobile SDK setup](./mobile-sdk-setup) guide for your platform.
  </Accordion>
</AccordionGroup>

## Improve CTR

Push CTR varies widely by platform (Android, iOS, Web), vertical (news, games, travel, ecommerce), message type, and country. Rather than chasing an industry average, compare your sends to your own historical baseline. Focus on three levers:

* **Relevance.** Send content that matches what the user opted in for. On Web, use the [Category Slidedown prompt](./permission-requests) to capture interest at opt-in. On mobile, use [Data Tags](./add-user-data-tags) and [Segments](./segmentation) to target by behavior.
* **Timing.** Use [Intelligent Delivery](https://onesignal.com/blog/increase-open-rates-by-up-to-23-percent-with-intelligent-delivery) to send at each user's most active hour.
* **Content.** Add visual and contextual flair with images, emojis, and per-user [personalization](./message-personalization).

Additional reading:

* [6 best practices for push notifications](https://onesignal.com/blog/6-best-practices-for-push-notifications)
* [Best practices for news publications: push notification frequency and content](https://onesignal.com/blog/news-publishers-5-best-practices-for-sending-push-notifications)

## FAQ

### Why is my CTR different in OneSignal than in my analytics tool?

OneSignal calculates CTR against **Delivered** (notifications accepted by APNs or FCM). Third-party analytics tools typically attribute based on session starts, deep link clicks, or app opens within a window, which can produce higher or lower numbers. Compare the same event definition across tools before concluding the numbers conflict.

### Does CTR count dismissals or swipes?

No. CTR counts only explicit taps on the notification that launch your app or landing page. Swipes, **Dismiss** taps, and clearing the notification tray are not counted.

### Why did my Delivered count drop without a Sent drop?

Delivered decreases when push providers (APNs, FCM) reject more notifications, when more Subscriptions are frequency capped, or when more Subscriptions became unreachable since the last send. A lower Delivered count increases CTR if clicks stay constant — a "CTR increase" here can actually mean your audience shrank.

### Do iOS Focus modes affect CTR?

Yes, indirectly. Focus modes hide notifications from the user but do not prevent delivery. The notification is counted as Delivered but the user may never see it, which lowers CTR. The same applies when Android users mute a [notification channel](./android-notification-categories).

### How do I see CTR on a specific message?

Open the message in **Sent Messages** and review the [Push message report](./push-notification-message-reports). For trend comparisons across sends, use [Engagement Trends](./engagement-analytics).

### How do I measure CTR for data-only notifications?

Data-only (silent) notifications have no UI, so they do not generate clicks. Exclude them from CTR reporting, or label them distinctly so they don't skew your overall CTR.

## Related

<Columns>
  <Card title="Metrics glossary" icon="book" href="./analytics-metrics-glossary">
    Canonical definitions for Sent, Delivered, Clicked, and every other metric.
  </Card>

  <Card title="Engagement Trends" icon="chart-mixed" href="./engagement-analytics">
    Aggregate CTR and delivery trends across channels.
  </Card>

  <Card title="Push message reports" icon="file-chart-column" href="./push-notification-message-reports">
    Per-send delivery, confirmed receipt, and click breakdowns.
  </Card>

  <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
    Increase relevance with Liquid, Data Tags, and user properties.
  </Card>

  <Card title="Segmentation" icon="filter" href="./segmentation">
    Target users by behavior and interest to raise CTR.
  </Card>

  <Card title="Mobile service extensions" icon="mobile" href="./service-extensions">
    Avoid common click-tracking pitfalls on iOS and Android.
  </Card>
</Columns>


# Notification icons
Source: https://documentation.onesignal.com/docs/en/notification-icons

Push notification icon requirements, sizes, and best practices for Web Push, Android, and iOS, including how to configure default and per-message icons in OneSignal.

Push notification icons are small images that appear alongside your notifications. They help users quickly recognize your brand, understand context, and distinguish your messages from others. Each platform handles icons differently, so following platform-specific standards is critical to ensure your notifications display correctly.

For large images attached to notifications, see [Images & Rich Media](./rich-media).

<Frame>
  <img alt="Push notification icons" />
</Frame>

***

## Best practices for push notification icons

* Use **PNG images with transparency** whenever possible.
* Keep icons **simple and recognizable** at very small sizes.
* Avoid text or fine details that may become illegible.
* Follow **platform-specific rules** for size, color, and transparency.
* Test notifications on real devices across platforms and OS versions.

***

## Web notification icons

Web push notifications display an icon provided at send time or defined as a default in your site settings. If no icon is provided, a default bell icon is used.

* Supported formats: PNG, JPG, GIF (non-animated)
* Icon must be square. Recommended size is `256x256` pixels.

<Info>
  Different browsers (Chrome, Edge, Safari, Firefox) may crop or scale icons differently depending on device and OS. A square `256x256` icon is recommended to ensure consistent display across all browsers.
</Info>

Set the default icon in your [Dashboard Settings > Push & In-App > Web Settings](./web-push-setup).

You can also override the icon per notification using the dashboard or REST API. See [Send notifications with non-default icons](#send-notifications-with-non-default-icons) for details.

### Android web push badge icon

On Android devices, Web Push notifications may display a smaller **badge icon** defined by the Web App Manifest `badge` property. The badge icon is used in limited UI contexts (such as the Android status bar) and may not appear on all Android devices. If no badge icon is provided, the default is the browser icon.

While badge icons are not subject to the same strict alpha-only rules as Android app small notification icons, they are still rendered in system-controlled UI.

**Best practices:**

* Use a **square PNG** with a **transparent background**
* Keep the design **simple and high-contrast**
* Avoid text or fine detail
* Use monochrome or minimal color for best consistency

A minimum size of `72×72 pixels` is recommended. Larger images are acceptable and will be downscaled as needed.

Example small badge icon: `https://i.imgur.com/9QFB20F.png`

<Frame>
  <img alt="Example of how the badge icon is displayed in the Android status bar using the example badge icon." />
</Frame>

<Note>
  Unlike Android app small notification icons, Web Push badge icons may preserve color on some devices. However, full-color or complex icons may render inconsistently depending on Android version, browser, and device manufacturer.
</Note>

See [Send notifications with non-default icons](#send-notifications-with-non-default-icons) for details.

***

## iOS notification icons

iOS notifications always use your **app icon**.

* The notification icon is automatically derived from your app's icon asset
* You cannot change the notification icon per message
* Changing the icon requires updating your app icon and shipping a new app version

<Note>
  There is no APNs payload field that allows you to specify a custom notification icon on iOS.

  This behavior is enforced by iOS and applies to standard push notifications, Critical Alerts, and Live Activities.
</Note>

### Communication Notifications

On iOS 15 and newer, Apple supports [Communication Notifications](https://developer.apple.com/documentation/usernotifications/implementing-communication-notifications).

When properly implemented, communication-style notifications (such as messaging or calling apps) may display a **contact or sender image** instead of the app icon in supported system views.

<Note>
  Communication Notifications are limited to specific use cases and require explicit adoption of Apple’s communication notification APIs. They are not available for general-purpose notifications.
</Note>

***

## Android notification icons

Android (including Amazon and Huawei devices) supports **Small** and **Large** notification icons.

Android also supports [Conversation Notifications](https://developer.android.com/develop/ui/views/notifications/conversations) that allow you to change the icon to the user's profile image.

<Note>
  On Android 8.0+ (API 26+), notification appearance is heavily influenced by system UI, [notification channels](./android-notification-categories), and device manufacturer customizations.
</Note>

<Frame>
  <img alt="Android notification icon placement" />
</Frame>

### Small notification icons

The small notification icon appears in the status bar and the top-left of the notification. If no custom small icon is provided, OneSignal displays a default bell icon.

Android renders small notification icons using the **icon's alpha channel**, not its color data. The system applies its own tint (or your configured accent color) when displaying the icon.

**Requirements and best practices:**

* Use a **monochrome silhouette icon** on a **transparent background**
* Design the icon so the **shape is defined by transparency**, not color
* Avoid gradients, shadows, or multi-color artwork
* Keep the design simple and recognizable at very small sizes

A common and recommended approach is to design the icon as **white artwork on a transparent background**, but technically Android uses the **alpha mask**, not the white color itself.

<Warning>
  Icons with solid backgrounds or full-color artwork may render incorrectly — often appearing as a white square, clipped shape, or unexpected silhouette — depending on the device manufacturer and Android version.

  Android often ignores color information in small notification icons and derives the final appearance from the alpha channel and system or app-defined tinting.
</Warning>

#### Small icon accent color

You can change the color shown around the small icon of the notification.

<Frame>
  <img alt="Android notification showing small icon accent color" />
</Frame>

To set a default color, add the following line to your `res/values/strings.xml` file in your project.

If you want a different color for dark mode, add the key to your `res/values-night/strings.xml` as well.

Use a HEX value (e.g., `FF00FF00`). You can use [Android Asset Studio](https://romannurik.github.io/AndroidAssetStudio/icons-generic.html#source.type=clipart\&source.clipart=ac_unit\&source.space.trim=1\&source.space.pad=0\&size=32\&padding=8\&color=rgb\(139%2C%20195%2C%2074\)\&name=ic_ac_unit) to preview color values.

```xml theme={null}
<resources>
    <string name="onesignal_notification_accent_color">FF00FF00</string>
</resources>
```

To set the color on a per-notification basis, set `android_accent_color` in the [Create notification](/reference/create-message) API call or enter a value in the **Accent color** field under **Messages > New Push > Platform Settings > Google Android Options**.

<Warning>
  If you've very recently added an icon resource to your app, you may want to wait a few days before sending notifications using the icon. This is because it can take many days or even weeks for the majority of your users to update their apps to the latest version which contain your new icons.
</Warning>

#### Custom non-alpha channel small icon images

Some device manufacturers display the image as-is (ignoring the alpha channel rule). You can set up a [custom notification layout based on Android's documentation](https://developer.android.com/training/notify-user/custom-notification) if you need non-alpha channel images across all devices.

Following the alpha rule is strongly recommended. Icons may not render consistently across all devices, and Google enforces the single-color approach because the icon is too small for meaningful detail — a clear silhouette is easier to recognize at a glance.

### Large notification icons

The large icon appears on the right side of the Android notification.

* Recommended size: **256×256 pixels**
* Format: PNG or JPG
* If not set, Android may reuse the small icon

***

## How to add Android default icons

Configuring default notification icons is strongly recommended for every Android-based app (Google Play, Amazon, Huawei). Missing or incorrectly configured icons are the most common cause of broken notification rendering.

<Note>
  Default icons are **bundled inside your app**, not uploaded to the OneSignal dashboard. You add them to your project's resource directories (or use a plugin config for Expo), and the OneSignal SDK uses them automatically.
</Note>

Android supports two default icons:

* **Small notification icon** (required)
* **Large notification icon** (optional but recommended)

<Steps>
  <Step title="Generate the small notification icon">
    The small notification icon appears in the status bar and notification header.

    **Requirements:**

    * Monochrome silhouette icon
    * Transparent background (alpha channel required)
    * No colors, gradients, or shadows

    A common and recommended approach is a **white icon on a transparent background**, but Android uses the **alpha channel**, not the white color itself.

    <Note>
      The fastest and safest way to generate compliant small icons is using [Android Asset Studio – Notification Icons](http://romannurik.github.io/AndroidAssetStudio/icons-notification.html#source.space.trim=1\&source.space.pad=0\&name=ic_stat_onesignal_default).
    </Note>

    **Name the icon:** `ic_stat_onesignal_default`
  </Step>

  <Step title="Create required small icon sizes">
    **Required**: You must include **all density variants** for the small icon. Missing any size can cause Android to fall back to a system default icon.

    | Icon name                   | Density (dp) | Size (px) |
    | --------------------------- | ------------ | --------- |
    | `ic_stat_onesignal_default` | MDPI         | 24x24     |
    | `ic_stat_onesignal_default` | HDPI         | 36x36     |
    | `ic_stat_onesignal_default` | XHDPI        | 48x48     |
    | `ic_stat_onesignal_default` | XXHDPI       | 72x72     |
    | `ic_stat_onesignal_default` | XXXHDPI      | 96x96     |
  </Step>

  <Step title="Generate the large notification icon (optional)">
    **Best practices:**

    * Square image
    * PNG or JPG
    * Transparent background recommended
    * Recommended size: **256×256 px**

    Unlike small icons:

    * Color is allowed
    * Alpha-only is **not required**
    * Only one size is needed

    **Required file name:** `ic_onesignal_large_icon_default.png`
  </Step>

  <Step title="Place icons in the correct project paths">
    Each icon must be placed in the correct resource directory for your framework. Make sure the following paths exist; create any folders you are missing.

    **Required**: Each image must be present in the following paths:

    <Tabs>
      <Tab title="Android Native">
        * `res/drawable-mdpi/` (24x24)
        * `res/drawable-hdpi/` (36x36)
        * `res/drawable-xhdpi/` (48x48)
        * `res/drawable-xxhdpi/` (72x72)
        * `res/drawable-xxxhdpi/` (96x96)
        * `res/drawable-xxxhdpi/` (256x256) (Large Icon)
      </Tab>

      <Tab title="Unity">
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-mdpi/` (24x24)
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-hdpi/` (36x36)
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xhdpi/` (48x48)
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xxhdpi/` (72x72)
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xxxhdpi/` (96x96)
        * `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xxxhdpi/` (256x256) (Large Icon)
      </Tab>

      <Tab title="Cordova/Ionic">
        * `<project-root>/platforms/android/app/src/main/res/drawable-mdpi/` (24x24)
        * `<project-root>/platforms/android/app/src/main/res/drawable-hdpi/` (36x36)
        * `<project-root>/platforms/android/app/src/main/res/drawable-xhdpi/` (48x48)
        * `<project-root>/platforms/android/app/src/main/res/drawable-xxhdpi/` (72x72)
        * `<project-root>/platforms/android/app/src/main/res/drawable-xxxhdpi/` (96x96)
        * `<project-root>/platforms/android/app/src/main/res/drawable-xxxhdpi/` (256x256) (Large Icon)

        <Warning>
          With versions of Cordova before 7.0, you will need to use `<project-root>/platforms/android/res/drawable-{size}/` instead of the path shown above when adding the icon resource to `config.xml`
        </Warning>
      </Tab>

      <Tab title="React Native / Expo">
        * `android/app/src/main/res/drawable-mdpi/` (24x24)
        * `android/app/src/main/res/drawable-hdpi/` (36x36)
        * `android/app/src/main/res/drawable-xhdpi/` (48x48)
        * `android/app/src/main/res/drawable-xxhdpi/` (72x72)
        * `android/app/src/main/res/drawable-xxxhdpi/` (96x96)
        * `android/app/src/main/res/drawable-xxxhdpi/` (256x256) (Large Icon)

        **Expo shortcut:** If you use the `onesignal-expo-plugin`, you can provide a single 96x96 source PNG and the plugin generates all density variants automatically. Add it to your `app.json` or `app.config.js`:

        ```json theme={null}
        {
          "plugins": [
            ["onesignal-expo-plugin", {
              "mode": "production",
              "smallIcons": ["./assets/ic_stat_onesignal_default.png"],
              "largeIcons": ["./assets/ic_onesignal_large_icon_default.png"]
            }]
          ]
        }
        ```

        You do not need to manually create the `android/` subdirectories — the plugin places the generated files in the correct drawable folders at build time. See [React Native / Expo SDK setup](./react-native-expo-sdk-setup) for full plugin configuration.
      </Tab>

      <Tab title=".NET Maui">
        * `Resources/Images/drawable-mdpi/` (24x24)
        * `Resources/Images/drawable-hdpi/` (36x36)
        * `Resources/Images/drawable-xhdpi/` (48x48)
        * `Resources/Images/drawable-xxhdpi/` (72x72)
        * `Resources/Images/drawable-xxxhdpi/` (96x96)
        * `Resources/Images/drawable-xxxhdpi/` (256x256) (Large Icon)
      </Tab>

      <Tab title="Flutter">
        * `android/app/src/main/res/drawable-mdpi/` (24x24)
        * `android/app/src/main/res/drawable-hdpi/` (36x36)
        * `android/app/src/main/res/drawable-xhdpi/` (48x48)
        * `android/app/src/main/res/drawable-xxhdpi/` (72x72)
        * `android/app/src/main/res/drawable-xxxhdpi/` (96x96)
        * `android/app/src/main/res/drawable-xxxhdpi/` (256x256) (Large Icon)
      </Tab>
    </Tabs>
  </Step>
</Steps>

Your project should look similar to this (depending on your SDK):

<Frame>
  <img alt="Android project directory structure showing icon files in drawable folders" />
</Frame>

<Warning>
  **Troubleshooting icon display issues:**

  * If you see a **solid square** instead of your icon, the image does not have proper transparency.
  * If you see the **OneSignal bell icon**, one or more required small icon sizes are missing or placed in the wrong directory.
</Warning>

<Check>
  Your Android app is now correctly configured with default notification icons.
</Check>

***

## Send notifications with non-default icons

When sending push notifications from the OneSignal dashboard or REST API, you can override the default icons with custom icons for Android, Amazon, Huawei, and Web Push notifications. You cannot override the icon for iOS notifications.

### REST API parameters

**Android, Amazon, and Huawei REST API parameters:**

<ParamField type="string">
  Amazon: `adm_small_icon` Huawei: `huawei_small_icon`

  For the small icon, the image must exist within the same project path as the default small icon. It cannot use a remote URL. See [How to add Android default icons](#how-to-add-android-default-icons) for details on where to add your custom icons.

  Set the icon name **without** the file extension in the REST API parameters.

  Example: `"small_icon": "my_custom_icon_name_without_extension"`
</ParamField>

<ParamField type="string">
  Amazon: `adm_large_icon` Huawei: `huawei_large_icon`

  For the large icon, the image can exist within the same project path as the default large icon or as a remote URL. See [How to add Android default icons](#how-to-add-android-default-icons) for details on where to add your custom icons.

  Set the icon name **without** the file extension in the REST API parameters.

  Example: `"large_icon": "my_custom_icon_name_without_extension"`
</ParamField>

**Web Push REST API parameter:**

<ParamField type="string">
  Firefox: `firefox_icon`

  The URL to the image resource. Must be the direct URL to the image resource.

  Example: `"chrome_web_icon": "https://example.com/my_custom_icon.png"`
</ParamField>

<ParamField type="string">
  The URL to the image resource. Must be the direct URL to the image resource.

  Example: `"chrome_web_badge": "https://i.imgur.com/9QFB20F.png"`
</ParamField>

### Dashboard

In the OneSignal dashboard, using the **Messages > Push > New Push** form or **Templates**, navigate to the platform-specific options.

For Android, Amazon, and Huawei, if the file exists within the same project path as the default icon, set the icon names **without** the file extension. With Large Notification Icons, you can also supply a direct URL where the icon will be displayed from.

<Frame>
  <img alt="OneSignal dashboard showing icon override fields in Android platform settings" />
</Frame>

***

## FAQ

### Why does my Android small icon show as a white or grey square?

The image does not have proper transparency. Android renders small notification icons using the alpha channel only — any fully opaque pixels with a solid background appear as a filled square. Regenerate the icon as a monochrome silhouette on a transparent background using [Android Asset Studio](http://romannurik.github.io/AndroidAssetStudio/icons-notification.html#source.space.trim=1\&source.space.pad=0\&name=ic_stat_onesignal_default).

### Why does the OneSignal bell icon appear instead of my custom icon?

One or more required density variants of the small icon are missing or placed in the wrong drawable directory. You must include all five sizes (MDPI through XXXHDPI) with the exact file name `ic_stat_onesignal_default`. See [How to add Android default icons](#how-to-add-android-default-icons) for the correct paths.

### Can I change the iOS notification icon per message?

No. iOS always uses your app icon for push notifications. There is no APNs payload field to override it. Changing the icon requires updating your app icon asset and releasing a new app version.

### What size should my web push icon be?

Use a square PNG image at `256x256` pixels. Different browsers and operating systems may crop or scale the icon, but `256x256` provides the best consistency across Chrome, Firefox, Edge, and Safari.

### Can I use a URL for the Android small icon?

No. The Android small icon must be a local resource file bundled with your app. Only the large icon supports remote URLs.

### How do I add notification icons in Expo?

With the `onesignal-expo-plugin`, you provide a single source PNG (96x96 for small icons, 256x256 for large icons) and reference it in `app.json` or `app.config.js` under the `smallIcons` and `largeIcons` arrays. The plugin automatically generates all density variants and places them in the correct `android/` directories at build time. You do not need to create drawable folders manually. See the [Expo tab under "Place icons in the correct project paths"](#how-to-add-android-default-icons) for an example config.

### Do I upload default icons to the OneSignal dashboard?

No. Default notification icons are bundled inside your app binary, not uploaded to OneSignal. You add them to your project's resource directories (or plugin config for Expo), and the OneSignal SDK uses them automatically. The OneSignal dashboard only lets you override icons on a per-message basis for Android and Web Push.

***

## Related pages

<Columns>
  <Card title="Images & rich media" icon="image" href="./rich-media">
    Attach large images, GIFs, and videos to push notifications.
  </Card>

  <Card title="Android notification categories" icon="bell" href="./android-notification-categories">
    Create and manage Android notification channels for custom sound, vibration, and importance.
  </Card>

  <Card title="Web push setup" icon="globe" href="./web-push-setup">
    Configure your site for web push notifications including default icon settings.
  </Card>

  <Card title="Create message API" icon="code" href="/reference/create-message">
    Send push notifications with custom icons using the REST API.
  </Card>
</Columns>


# Notification Images Not Showing
Source: https://documentation.onesignal.com/docs/en/notification-images-not-showing

Notifications images not appearing.

When sending push notifications that include images, the OneSignal SDK tries to get the external image URLs from the [OSNotification Payload](./osnotification-payload) and display it within the notification. It doesn't matter if the app is closed during this process. The SDK waits for the image to be downloaded, but if it takes longer than \~25 seconds (enforced by Apple), the notification is displayed without the image. OneSignal's SDK does not retry to get the image again if it fails to download.

This guide will cover the most common reasons for images not showing and how to fix them. For details on image specs, see [Images & Rich Media](./rich-media).

## Image configuration

Check these items first to make sure the image is properly configured.

### Image size

The image must be less than 5MB in size. The smaller the image, the faster it will download. More details found in [Images & Rich Media](./rich-media).

### Image URL

* Image URLs need a direct link to the image resource. No redirects and no links to pages that show the image but not the actual image resource.
  * Usually this means the image URL starts with `https://` and ends with a file extension like `.png` or `.jpg`.

Example:

* This will not work: `https://pixabay.com/en/architecture-travel-sky-building-3095716/`
* But if you right click the image and open in a new tab, this will work: `https://cdn.pixabay.com/photo/2018/01/21/01/46/architecture-3095716_960_720.jpg`

### Image host

If you uploaded the image to OneSignal, it will be hosted on our servers for \~33 days. If you need the image for longer, you can use templates or store the image on your own servers and reference the resource URL directly in the template.

If you are self-hosting the image, you need to make sure the server is able to handle the amount of downloads. Each device that receives the notification will need to download the image. Around 30 seconds is how long the device has to download all notification resources, including images. If it takes longer, it will not show on that device.

***

## Device configuration

Check the internet connection on the device. Unstable network connections may cause the image to not show.

* Test on different WiFi networks.
* Test on different cellular networks.
* Test on different devices.

***

## Platform configuration

Check the sections below based on the platform not receiving the image.

### Web push images

* **Only Chrome supports large images in push notifications on Windows and Android**.
  * Chrome for macOS does not support large images.
* Firefox, Safari and Edge do not support big images.
* On Android, when you get the notification, you will need to tap on the notification to expand it and see the image.

<Warning>
  If your mobile browser app has many unread push notifications and/or many tabs open, this can cause notifications to not show.
</Warning>

### Android push images

When you get the notification in the Android notification center, you will need to expand the notification to see the image.

Android does not require any additional configuration to receive images in push notifications.

### iOS push images

iOS notifications require the Notification Service Extension to be setup correctly. The Notification Service Extension setup is covered in our [Mobile SDK setup](./mobile-sdk-setup) guides for the version of our SDK you are using.

If your image URLs are HTTP and you insist on hosting them yourself using an HTTP URL, you will need to set `NSAppTransportSecurity` to `NSAllowsArbitraryLoads` in your Xcode .plist.

<Warning>
  Apple may reject your app if `NSAllowsArbitraryLoads` is enabled when releasing your app to the App Store, as this can create a security vulnerability. For more information, please read Apple's [Security Overview](https://www.apple.com/business/resources/docs/iOS_Security_Overview.pdf).
</Warning>

***

## Technical troubleshooting

If you checked the above items and the image still fails to be shown, use our SDK's [`setLogLevel` method](./mobile-sdk-reference#setloglevel) with `VERBOSE` logging to check for specific errors related to image downloading.

For a detailed guide on generating logs, see our [Capturing a Debug Log](./capturing-a-debug-log) guide.

Common errors include:

* `Could not download image!`
* `Encountered an error while attempting to download file with URL:`
* `OneSignal encountered an exception while downloading file`

### iOS Notification Service Extension Troubleshooting

If images are not showing on iOS, please follow our [Troubleshooting the iOS Notification Service Extension](./service-extensions#troubleshooting-the-ios-notification-service-extension) guide.

This guide will help review your Notification Service Extension setup and identify any issues.

***


# Notification sounds
Source: https://documentation.onesignal.com/docs/en/notification-sounds

Add custom notification sounds to iOS, Android, Huawei, and Amazon apps — including file formats, SDK setup, and API parameters.

Custom sounds let you provide a more unique, branded experience in your app. You can add a custom sound to every notification or only to certain types. For example, a social app might play a distinct sound only for direct messages to differentiate them from system notifications.

<Warning>
  For mobile apps only. Custom sounds are not supported on web push.
</Warning>

## Setup

### Create sound files

Create sound files following the platform requirements below. If the device cannot find the specified file or the file format is unsupported, it falls back to the default system notification sound.

<Note>
  Keep sound filenames lowercase since some platforms ignore uppercase letters for sound files. Instead of `AwesomeSound.wav` use `awesomesound.wav` or `awesome_sound.wav`.
</Note>

| Platform | Extensions            | Notes                                                                                                    |
| -------- | --------------------- | -------------------------------------------------------------------------------------------------------- |
| iOS      | `.wav` `.aiff` `.caf` | Sounds must be encoded as Linear PCM, MA4 (IMA/ADPCM), µLaw, or aLaw. Must be less than 30 seconds.      |
| Android  | `.wav` `.mp3` `.ogg`  | Recommended length less than 30 seconds. Keep file size small, large files may not play on some devices. |
| Huawei   | `.wav` `.mp3` `.wma`  | Recommended length less than 30 seconds. Keep file size small, large files may not play on some devices. |
| Amazon   | `.wav` `.mp3` `.ogg`  | Recommended length less than 30 seconds. Keep file size small, large files may not play on some devices. |

### Add sound files to your app

Sound files must be included as resources within your app. External URLs are not supported.

<Tabs>
  <Tab title="iOS">
    Add sound files to the appropriate location in your Xcode project depending on your SDK.

    | SDK            | Folder                                                                                                                                                   |
    | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | iOS Native     | Add files to the Xcode project root. Make sure **Add to targets** is selected when adding files so they are automatically added to the bundle resources. |
    | Cordova, Ionic | Add files to `Resources` directory within the Xcode project in `<project-root>/platforms/ios/project-name.xcodeproj`.                                    |
    | Unity          | Add sounds anywhere in your Unity project, build your project, and then move those sounds to the Xcode project root.                                     |
  </Tab>

  <Tab title="Android, Huawei, and Amazon">
    Add sound files to the appropriate folder in your project depending on your SDK. **If the folder does not exist, create it.**

    | SDK                            | Folder                                                                                                                                                                    |
    | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Android, Huawei, Amazon Native | `res/raw`                                                                                                                                                                 |
    | React Native                   | `<project-root>/android/app/src/main/res/raw`                                                                                                                             |
    | Cordova                        | `<project-root>/platforms/android/res/raw/`                                                                                                                               |
    | Ionic                          | `/android/app/src/main/res/raw/`                                                                                                                                          |
    | Unity                          | `Assets/Plugins/Android/OneSignalConfig/res/raw` *NOTE: Your sound and icon file names must be lowercase and can't contain anything else except underscores and numbers.* |
    | Flutter                        | `main/res/raw`                                                                                                                                                            |
    | .NET                           | `<project-root>/Platforms/Android/Resources/raw/`                                                                                                                         |
  </Tab>
</Tabs>

### Send notifications

<Tabs>
  <Tab title="iOS">
    Include the file extension when referencing the sound resource (e.g., `explode_sound.wav`). Set the sound in the dashboard when sending push messages or use the [Create Notification](/reference/create-message) API `ios_sound` property.

    For no sound, pass `nil` to the **Sound** field.

    <Frame>
      <img alt="OneSignal dashboard push composer showing the iOS Sound field" />
    </Frame>
  </Tab>

  <Tab title="Android, Huawei, and Amazon">
    Android 8+ introduced [Notification Categories](./android-notification-categories) which must be set up to customize notification sounds. OneSignal uses the sound configured in the Notification Channel for all versions of Android.

    In **Settings > Push & In-App > Android Notification Channels**, create the group and channel.

    <Frame>
      <img alt="OneSignal dashboard showing the notification channel creation form" />
    </Frame>

    * Set **Importance** to "Urgent" or "High" to play sound.
    * Set **Sound** to "Default" or "Custom" based on your needs. **Do not** add the file extension when referencing the sound resource (e.g., `cat_meow_sound`).
    * For no sound, set **Importance** to "Urgent" or "High" and **Sound** to "Off". Or set **Importance** to "Medium" or "Low" for no sound.

    <Frame>
      <img alt="OneSignal notification channel settings showing sound configuration options" />
    </Frame>

    You can then set the category name in the dashboard when sending push messages or use the [Create Notification](/reference/create-message) API `android_channel_id` and `huawei_channel_id` properties. The sound set in the category works for all Android versions.

    <Frame>
      <img alt="OneSignal push composer showing the notification category dropdown" />
    </Frame>
  </Tab>

  <Tab title="REST API">
    You can send notifications with sounds via the REST API using the appropriate parameter for each platform. See the [Create Notification API reference](/reference/push-notification) for full details.

    | Platform | API Parameter                                                                                                                                                                                                                | Details                                                                                        |
    | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
    | iOS      | `ios_sound`                                                                                                                                                                                                                  | Include file extension. Example: `"ios_sound": "explode_sound.wav"`. For no sound, pass `nil`. |
    | Android  | `android_channel_id` — Use if you created the channel in the OneSignal dashboard via [Notification Categories](./android-notification-categories). `existing_android_channel_id` — Use if you created the channel elsewhere. | Using [Notification Categories](./android-notification-categories) is recommended.             |
    | Huawei   | `huawei_channel_id` — Use if you created the channel in the OneSignal dashboard via [Notification Categories](./android-notification-categories). `huawei_existing_channel_id` — Use if you created the channel elsewhere.   | Using [Notification Categories](./android-notification-categories) is recommended.             |
    | Amazon   | `adm_sound`                                                                                                                                                                                                                  | Do not include file extension. Example: `"adm_sound": "explode_sound"`.                        |
  </Tab>
</Tabs>

<Warning>
  If you recently added a sound resource to your app, consider waiting a few days before sending notifications that use it. It can take days or weeks for most users to update to the latest app version containing the new sound file.

  If a user has an older version without the sound resource and receives a notification referencing it, they hear only the default system notification sound.
</Warning>

***

## FAQ

### Can I set a default sound?

Use a [Template](./templates) that references the sound and/or Android Notification Channel. Every notification sent with that template uses the configured sound automatically.

### Can I send different notification sounds to different users?

The `ios_sound` and `android_channel_id` parameters are request-level — they apply to **all** recipients of that API call. You cannot specify different sounds for different users in a single request.

To deliver different sounds to different users, use a **fan-out pattern**: make separate API calls for each sound variant, targeting users by tag or segment. For example, store each user's preferred sound in a [tag](./add-user-data-tags) like `preferred_sound`, then send one request per sound value.

<CodeGroup>
  ```json Request 1 — "chime" users theme={null}
  {
    "app_id": "YOUR_APP_ID",
    "contents": {"en": "You have a new message!"},
    "ios_sound": "chime.wav",
    "android_channel_id": "CHIME_CHANNEL_ID",
    "include_filters": [
      {"field": "tag", "key": "preferred_sound", "relation": "=", "value": "chime"}
    ]
  }
  ```

  ```json Request 2 — "bell" users theme={null}
  {
    "app_id": "YOUR_APP_ID",
    "contents": {"en": "You have a new message!"},
    "ios_sound": "bell.wav",
    "android_channel_id": "BELL_CHANNEL_ID",
    "include_filters": [
      {"field": "tag", "key": "preferred_sound", "relation": "=", "value": "bell"}
    ]
  }
  ```
</CodeGroup>

Each request targets only the users whose `preferred_sound` tag matches, so each group hears its own sound. Add as many variants as you need — one API call per sound.

### Why is my notification not playing the custom sound file?

There are a few common causes:

* Sound file has an incorrect file extension
* Sound file is not encoded in a supported format
* Sound file is in the wrong location in the project
* Sound file is longer than 30 seconds

**iOS** — Read more in [Apple's documentation](https://developer.apple.com/documentation/usernotifications/unnotificationsound?language=objc) for encoding and testing guidance.

**Android** — Verify the sound file is included in your APK by extracting it and confirming it exists in `res/raw/`.

If resource shrinking is enabled, protect sound files from being removed by creating `keep.xml` in `res/raw/`:

```xml theme={null}
<resources xmlns:tools="http://schemas.android.com/tools"
  tools:keep="@raw/sound_file"/>
```

### Why is my notification playing the default sound file?

Make sure you followed the setup instructions and the sound file is in the correct location for your SDK. Double-check the filename casing — some platforms ignore uppercase letters.

### Why is the wrong sound playing?

On Android, notifications are grouped together after a certain number are received without being opened. Grouped notifications play a default sound. You can set the sound with the [group key](https://developer.android.com/training/notify-user/group) for all your notifications.

***

## Related pages

<Columns>
  <Card title="Notification categories" icon="layer-group" href="./android-notification-categories">
    Set up Android notification channels to control sound, vibration, and importance.
  </Card>

  <Card title="Templates" icon="file-lines" href="./templates">
    Create reusable notification templates with predefined sounds.
  </Card>

  <Card title="Create Notification API" icon="code" href="/reference/push-notification">
    API reference for the ios\_sound, android\_channel\_id, and adm\_sound parameters.
  </Card>

  <Card title="Notification icons" icon="image" href="./notification-icons">
    Customize notification icons for your mobile app.
  </Card>
</Columns>


# Web push: Notifications not shown
Source: https://documentation.onesignal.com/docs/en/notifications-not-shown-web-push

Troubleshoot web push notifications that show as Delivered in OneSignal but don't appear on a subscriber's device.

When a notification shows as "Delivered" in OneSignal, it means we have successfully sent the notification to the FCM (Google) / APNs (Apple) / WNS (Microsoft) servers which then distribute the notifications to your subscribers. The following are reasons why notifications may show as "Delivered", but are not visible on your device.

## Device settings

Device Notification Settings are the **most common cause** of web push not appearing on a device. Check the following settings including Focus modes (Do Not Disturb, Low Battery, etc.) before looking elsewhere.

<Warning>
  Select the correct operating system from the tabs below. You should see Windows, macOS, Android, and iOS.
</Warning>

<Tabs>
  <Tab title="Windows">
    <Accordion title="Windows 10 Notification Settings">
      1. Select **Start > Settings > Notifications & Actions > Get notifications from apps and other senders**

      2. **Make sure your site and browser are also enabled.**

      <Frame>
        <img />
      </Frame>
    </Accordion>

    **Windows 11 Notification Settings:**

    1. Select **Start > Settings > System > Notifications**

    <Frame>
      <img />
    </Frame>

    2. Turn On **Notifications**

    3. Turn Off **Do not disturb** (while testing, push will show when this is disabled)

    4. Scroll down to **Notifications from apps and other senders**

    <Frame>
      <img alt="Windows 11 Settings showing the Notifications from apps and other senders list" />
    </Frame>

    5. Make sure your browsers are turned **On**.

    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="macOS">
    1. Navigate to **System Settings > Notifications**
    2. Make sure **Notifications** is enabled in Notification Center.

    <Info>
      You may need to select **Allow notifications when mirroring or sharing the display**.
    </Info>

    <Frame>
      <img />
    </Frame>

    3. Scroll down to **Application Notifications** list and make sure your browser is turned on.

    <Warning>
      Some browsers like Chrome and Edge show 2 different application entries.

      1. Standard web push notifications
      2. Internal alerts e.g Google calendar

      Make sure both are enabled.
    </Warning>

    <Frame>
      <img />
    </Frame>

    4. Select the Application and toggle on the settings. Select how you want notifications to be displayed.

    <Frame>
      <img />
    </Frame>

    <Warning>
      Some older versions of Safari may show the website in your Application Notifications list. Make sure to check the website is turned on in this case.
    </Warning>

    5. Navigate to **System Settings > Focus** and make sure no Focus modes are active while testing.

    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="Android">
    1. Navigate to **Settings > Notifications > your browser of choice**.
    2. Make sure **"Show notifications"** and your website are checked.

    <Frame>
      <img />
    </Frame>

    <Note>
      Android uses per-app notification channels. If your browser's notification channel is set to silent or turned off, push notifications won't appear even if the top-level toggle is on. In Settings, tap the browser entry and check that each notification channel is enabled and set to a visible alert style.
    </Note>
  </Tab>

  <Tab title="iOS">
    <Warning>
      iOS requires you to add your site to the Home Screen before subscribers can receive push notifications on iPhones and iPads. Complete the [iOS web push setup](/docs/en/web-push-for-ios) before troubleshooting.
    </Warning>

    1. Click the browser's **Share** button and select **Add to Home Screen**.
    2. Open your site from the Home Screen and allow notifications when the permission prompt appears.
    3. Go to device's **Settings > Notifications > your site** and make sure **Allow Notifications** is toggled on.
  </Tab>
</Tabs>

### Network issues - no internet

Devices must be online to receive push notifications. If the device is turned off, in airplane mode, has unstable or no internet connection, the push will not show until a proper connection is made. You can set the timeframe FCM and APNs will wait for a connection with the Time To Live (TTL) Parameter (the default is 3 days).

If the device is on a WiFi network with a firewall or VPN, that network may be blocking the connection to Apple or Google servers. Test by switching to cellular data.

If you are managing network traffic through a firewall, configure it to allow the following:

* **FCM (Chrome, Android):** outbound TCP ports 5228, 5229, and 5230. See [FCM documentation](https://firebase.google.com/docs/cloud-messaging/concept-options) for full requirements.
* **APNS (Safari, iOS):** outbound TCP port 5223 and TCP port 443 or 2197. See [Apple's documentation](https://support.apple.com/en-us/HT203609) for full requirements.

***

## Browser settings

Your browser has its own notification permission settings separate from your OS settings. A site can be blocked at the browser level even if OS notifications are enabled for the browser.

* **Chrome**: Go to `chrome://settings/content/notifications` and confirm your site is listed under "Allowed to send notifications", not "Not allowed to send notifications".
* **Firefox**: Go to `about:preferences#privacy`, scroll to **Permissions > Notifications**, and click **Settings** to check your site's status.
* **Edge**: Go to `edge://settings/content/notifications` and verify your site is allowed.
* **Safari**: Go to **Safari > Settings > Websites > Notifications** and check that your site is set to **Allow**.

### Browser is closed

Browsers won't show push notifications unless they are running. If you open the browser before the [Time To Live (TTL)](./push#time-to-live) expires on a sent notification, it will pop up.

### Unsupported browser

Users must subscribe to notifications on their desktop or mobile device to receive notifications and it must be a browser that supports push notifications. Please see [Web Push FAQ](./web-push-setup-faq) for Supported Web Platforms.

### Mobile browser app data full

If your mobile browser app has reached its data limit or its data is full, you will need to clear the data on the app.

If your mobile browser app has many unread push notifications and/or many tabs open, this can cause notifications to not show.

***

## User subscription

Make sure your device is still subscribed and targeted for push notifications.

### Subscription eligibility

Check the message audience to verify that your web push Subscription is included:

* **[Segments](./segmentation)**: Verify your Subscription meets all audience filter conditions.
* **Direct send**: Confirm the ID you are targeting is correct:
  * The Subscription is still subscribed to push.
  * It has a recent last session date — you may be sending to an old or inactive Subscription.

Use the [troubleshooting steps](#troubleshooting-web-push-notifications) below to look up your Subscription ID and confirm it is subscribed and active.

***

## Website codebase

### Unregistering service worker or adding pwa

Check your site's codebase for the `.unregister()` method. Calling this method will delete Service Workers. See [this guide](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration/unregister) for details on this method.

If you have another service worker like for your PWA you will need to follow our [Service Worker guide on integrating multiple service workers](./onesignal-service-worker).

***

## Troubleshooting web push notifications

Follow these steps to get a clean web push Subscription and confirm web push is working end-to-end.

<Steps>
  <Step title="Open your site in browser">
    These steps use Chrome but Edge, Firefox, and others follow the same pattern. Do not use Incognito or Guest Browser mode, and close any other tabs open to your site.

    <Accordion title="Mobile device debugging">
      **Android**

      Plug your Android device into your desktop with a USB cable.

      * **Chrome**: Open `chrome://inspect/#devices` on desktop, then follow the steps below on your mobile device.
      * **Firefox**: See [about:debugging](https://developer.mozilla.org/en-US/docs/Tools/about:debugging).

      **iOS** (Mac only)

      iOS web push is only supported in Safari via a site added to the Home Screen. To inspect it:

      1. On your iPhone or iPad, go to **Settings > Safari > Advanced** and enable **Web Inspector**.
      2. Connect your device to your Mac with a USB cable.
      3. Open Safari on your Mac, then go to **Develop > \[your device name] > \[your site's page]**.
      4. Follow the steps below using your mobile device.
    </Accordion>
  </Step>

  <Step title="Reset browser permissions and clear site data">
    This resets the site to simulate a first-time visitor state.

    1. Click the **site information icon** next to your URL.
    2. If you see **Notifications**, select **Reset permission** (you want to see "Can ask to send notifications").
    3. Click **Cookies and site data**.

    <Frame>
      <img alt="Chrome site settings panel showing Notifications reset permission and Cookies options" />
    </Frame>

    4. Click **Manage on-device site data**.

    <Frame>
      <img alt="Chrome Cookies and site data panel with Manage cookies and site data button" />
    </Frame>

    5. Click the **Trash Icon** next to:

    * Your site URL
    * `onesignal.com`

    Then click **Done**.

    <Frame>
      <img alt="Chrome cookies list with trash icon to remove site data" />
    </Frame>

    6. Close the tab and open your site again in a new tab.
  </Step>

  <Step title="Open the Console and subscribe to push notifications">
    1. When you return to your site in a new tab, right click the page and select **Inspect** to open the Console.
    2. Follow the steps you set up to trigger the native browser permission prompt and allow notifications. See [Web permission prompts](./permission-requests) for more details.

    <Frame>
      <img alt="Browser notification permission prompt asking to allow or block notifications" />
    </Frame>

    3. Click **Allow** to subscribe to push notifications.
    4. Check the **Console** for any errors. If you see anything in red related to OneSignal, see our [Web SDK troubleshooting](./troubleshooting-web-push) docs.
  </Step>

  <Step title="Get your Subscription ID and set as a test user">
    1. In the **Console**, run the following code to get your Subscription ID:

    ```javascript JavaScript theme={null}
    OneSignal.User.PushSubscription.id
    ```

    <Frame>
      <img alt="JavaScript Console showing OneSignal.User.PushSubscription.id returning a subscription ID" />
    </Frame>

    2. Copy the ID without quotes.

    3. In the OneSignal dashboard, navigate to **Audience > Subscriptions**, paste the Subscription ID (without quotes) in the search bar, click the **Options** button, and select **Add as test user**.

    <Frame>
      <img alt="OneSignal dashboard showing Subscriptions search bar with Subscription ID pasted" />
    </Frame>
  </Step>

  <Step title="Send a test message to yourself">
    1. Navigate to **Messages > New Push** and write a message in the **Message** field.
    2. Under **Test & Preview**, select your test user and send the push to yourself.

    <Frame>
      <img alt="OneSignal dashboard showing New Push message form with test user selected" />
    </Frame>

    <Check>
      Success! You should receive the push you tested.

      If you did not receive the push, review this entire guide one more time and try again.
    </Check>
  </Step>
</Steps>

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Your OneSignal App ID
  * The Subscription ID or External ID
  * The URL to the message you tested in the OneSignal Dashboard
  * The URL to your site with the OneSignal web SDK code

  We're happy to help!
</Info>


# Mobile push: Notifications not shown or delayed
Source: https://documentation.onesignal.com/docs/en/notifications-show-successful-but-are-not-being-shown

Troubleshoot mobile push notifications that show as Delivered in OneSignal but don't appear or are delayed on Android and iOS devices.

This page covers the most common reasons a push notification shows as Delivered in OneSignal but does not appear on the device — or appears significantly delayed.

In your OneSignal dashboard [Push message reports](./push-notification-message-reports):

* **Delivered** means OneSignal successfully handed the notification off to the push service (FCM, APNs, or HMS) and received a success response.
* **Confirmed** means the OneSignal SDK on the device received the notification.

If your notification is Delivered but not Confirmed, and it did not appear on the device, start below.

***

## Before you begin

Gather the following to help troubleshoot. You will need these to identify the correct Subscription and check delivery status.

* Your [OneSignal App ID](./keys-and-ids)
* The [Message ID](./push-notification-message-reports) of the notification that didn't show
* The affected user's [Subscription ID](./subscriptions#finding-subscriptions)

<Note>
  If you only have the External ID, find the Subscription in **Audience > Subscriptions** by filtering on Device Type, Last Session, or IP Address.
</Note>

***

## Device settings

This section applies to all platforms. Check these first before investigating platform-specific or code-level causes.

### Permission and subscription status

On the device:

1. Navigate to **Settings > Notifications** and open the app's notification settings.
2. Confirm that notification permission is enabled.
3. Then open the app. If our SDK initializes, it will sync the subscription status back to OneSignal.

In your OneSignal dashboard:

1. Navigate to **Audience > Subscriptions**.
2. Search for the Subscription ID or External ID or sort by Device Type, Last Session, or IP Address.
3. Confirm the push status shows **Subscribed**. If it shows unsubscribed or does not appear, the device will not receive notifications regardless of what you send. If the status is unexpected, see [Troubleshooting](#troubleshooting) below.

### Do not disturb and focus modes

Do Not Disturb and Focus modes on both Android and iOS can suppress notifications entirely or group them in ways that make them appear invisible until the mode is cleared.

Disable these modes before testing:

* **iOS:** Settings > Focus > Do Not Disturb > turn off
* **Android:** Settings > Notifications > Do Not Disturb > turn off

Send a test notification after disabling. If the notification appears, the mode was the cause.

<Note>
  On iOS, if a notification arrives during Focus mode and the user swipes away the grouped notification summary, those notifications will not reappear individually later.
</Note>

### Low power mode and battery optimization

**iOS**: Disable Low Power Mode in Settings > Battery before testing.

**Android devices**: In Battery Settings, set the app to "Unrestricted" or "Not Optimized". If you don't see that option, search for **Battery Optimization**, **Power Saving Mode**, **Energy Saving**, **Background usage limits**, or **Adaptive Battery Settings** and disable for the app.

### Network and connectivity

Devices must be online to receive push notifications. If the device is turned off, in airplane mode, has unstable or no internet connection, the push will not show until a proper connection is made. You can set the timeframe FCM and APNs will wait for a connection with the Time To Live (TTL) Parameter (the default is 3 days).

If the device is on a WiFi network with a firewall or VPN, that network may be blocking the connection to Apple or Google servers. Test by switching to cellular data.

If you are managing network traffic through a firewall, configure it to allow the following:

* **FCM (Android):** outbound TCP ports 5228, 5229, and 5230. See [FCM documentation](https://firebase.google.com/docs/cloud-messaging/concept-options) for full requirements.
* **APNs (iOS):** outbound TCP port 5223 and TCP port 443 or 2197. See [Apple's documentation](https://support.apple.com/en-us/HT203609) for full requirements.

### Notification grouping behavior

Different versions of Android and iOS have their own notification grouping behavior. Notification grouping is when several notifications for the same app or multiple apps are grouped together in the notification center. It's common for grouped notifications to be dismissed together, causing users to miss individual notifications.

***

## Android issues

This section applies only to Android devices. If you are troubleshooting iOS, skip to [iOS issues](#ios-issues).

### Android Force Stop

When an Android app is Force Stopped, the operating system prevents it from receiving push notifications until the user manually reopens it. This is one of the most common causes of missed notifications on Android.

Some manufacturers — including Samsung, Xiaomi, and Huawei — aggressively Force Stop apps when the user swipes them away from the recent apps list, while exempting large apps like Gmail and WhatsApp. See [dontkillmyapp.com](https://dontkillmyapp.com/) for device-specific behavior.

To reduce Force Stop behavior on the affected device, try the following steps in order:

1. **Allow background activity**: Settings > Apps > Your App > Battery > Allow background activity.
2. **Disable sleeping apps**: Settings > Battery and Device Care > Battery > Background Usage Limits > Sleeping Apps > remove your app from this list.
3. **Lock the app in Recent Apps**: Open your app, tap the Recent Apps button, then tap and hold on the app window and select **Lock this app** (available on some Samsung models).
4. **Enable auto-start** (some devices): Settings > Apps > Your App > Permissions > Auto-Start > Enable.
5. **Disable adaptive battery optimization**: Settings > Battery and Device Care > Battery > More Battery Settings > Adaptive Battery > toggle off (or exclude your app).

To check whether your app has been Force Stopped, run the following command. Replace `com.company.appname` with your package name:

```bash theme={null}
adb shell dumpsys package com.company.appname | grep stopped
```

`stopped=false` means the app is not Force Stopped. `stopped=true` means it is.

You can also send a few notifications and check logcat for this entry:

```text theme={null}
W/GCM-DMM: broadcast intent callback: result=CANCELLED forIntent {
   act=com.google.android.c2dm.intent.RECEIVE pkg=com.onesignal.example (has extras)
}
```

If you see this cancelled intent, the app could not be started to process the notification.

<Note>
  FCM provides an API to check the last time a device connected to FCM servers. This can confirm whether the device is reachable at all. See [Google's documentation on app instance info](https://developers.google.com/instance-id/reference/server#get_information_about_app_instances) for details.

  To help users fix this themselves, use an in-app message to target known Android devices users with instructions to enable background activity. See [Example: Target certain Android manufacturers and devices](./example-target-certain-android-manufacturers-and-devices).
</Note>

### Android notification categories disabled

Android notification categories (also called channels) allow users to disable specific types of notifications from your app. If a category is disabled, notifications sent with that category will not appear on the device — even if the app has notification permission.

Check the category state on the device: **Settings > Notifications > Your App**. Confirm that "Show notifications" is enabled and that all categories are toggled on.

<Frame>
  <img alt="Android app notification settings showing the Abandoned Cart - Urgent category toggled off, which prevents notifications from that category from appearing on the device." />
</Frame>

If no category is set on the notification, OneSignal uses a default Miscellaneous category. Verify this category is enabled if you are not using custom categories. See [Android Notification Categories](./android-notification-categories) for setup details.

<Warning>
  Samsung One UI 6.1 automatically disables notification categories for many apps. If your users are on Samsung devices and recently stopped receiving certain notifications, this is a likely cause. See coverage from [Android Police](https://www.androidpolice.com/one-ui-61-disables-notification-channels/) for details.
</Warning>

<Note>
  You can use in-app messages to target Samsung users with instructions to re-enable categories. See [Example: Target certain Android manufacturers and devices](./example-target-certain-android-manufacturers-and-devices).
</Note>

### Android Doze mode, priority, and deprioritized messages

Android's [Doze mode](https://developer.android.com/training/monitoring-device-state/doze-standby) and [App Standby](https://developer.android.com/training/monitoring-device-state/doze-standby#understand_app_standby) features delay background processes — including push delivery — when the device is unplugged and stationary. These modes activate automatically and are not visible to the user.

Sending [high priority](./push#priority) messages will wake the device and bypass Doze mode. However, if you send too many high priority messages that do not result in visible notifications, FCM may automatically downgrade your messages to normal priority. From [FCM documentation](https://firebase.google.com/docs/cloud-messaging/android/message-priority):

> High priority messages on Android are meant for time sensitive, user visible content. If FCM detects a pattern in which messages do not result in user-facing notifications, your messages may be deprioritized to normal priority.

If you suspect deprioritization, reduce high priority usage to time-sensitive messages only.

### Android emulator setup

Push notifications on Android emulators require Google Play Services. If you are testing on an emulator and not receiving notifications, verify the following:

1. The emulator image includes the Google Play Store
2. The emulator is configured to use a Cold Boot

To set Cold Boot: open Android Studio Device Manager > select your device > Edit > Additional Settings > set Boot option to Cold Boot > save and restart.

***

## iOS issues

This section applies only to iOS devices. If you are troubleshooting Android, see [Android issues](#android-issues).

### APNs notification coalescing

If multiple notifications were sent while an iOS device was offline or unreachable, only the most recent one may appear when the device reconnects. APNs stores one notification per app while the device is offline and discards earlier ones. This is expected [APNs behavior](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns) and cannot be changed by OneSignal or your app.

### iOS foreground blocking

If you set up the [iOS UNUserNotificationCenterDelegate](https://developer.apple.com/documentation/usernotifications/unusernotificationcenterdelegate), you may have code blocking the notification from showing while the app is in the foreground.

Remove this custom code and use our SDK's [Foreground Event Listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) instead.

### iOS badge clearing

When an app clears its badge count, iOS removes all of that app's notifications from the Notification Center. The OneSignal SDK clears badges automatically when the app opens, which means previously delivered notifications may disappear when the user next opens the app.

If this is causing confusion during testing, see [Badges](./badges) for how to control this behavior.

***

## Message configuration

This section covers issues caused by how the notification was configured in OneSignal, not by the device.

### Subscription not in the target audience

Check the message audience to verify that your mobile Subscription is included:

* **[Segments](./segmentation)**: Verify your Subscription meets all audience filter conditions.
* **Direct send**: Confirm the ID you are targeting is correct:
  * The Subscription is still subscribed to push.
  * It has a recent last session date — you may be sending to an old or inactive Subscription.

### Collapse ID replacing notifications

If you are setting a Collapse ID on your messages, a new notification with the same Collapse ID will silently replace any unread notification with that ID. If the user has not opened the earlier notification, they will only see the newest one. See [Remove notifications and TTL](./push) for details on how Collapse ID works.

***

## Code-level causes

This section requires access to the app's source code. If you do not have code access, share these checks with your development team.

### OneSignal foreground notification prevention

The OneSignal SDK's [Foreground Event Listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) includes an `event.preventDefault()` method that suppresses a notification while the app is in the foreground. If this method is called unconditionally in your code, all foreground notifications will be silently blocked.

While testing, keep the app in the background or fully closed to rule out foreground suppression as the cause.

### Android Notification Service Extension

If you have implemented the [Android Notification Service Extension](./service-extensions), this is the first entry point for an incoming notification in your app. If `event.preventDefault()` is called inside this extension, the notification will be blocked regardless of app state. Review the extension code and confirm this method is only called intentionally.

### Firebase Messaging SDK conflict

If your app also includes the Firebase Messaging SDK, verify it is not intercepting FCM messages before OneSignal can process them.

This issue commonly occurs when:

* Notifications show as **Delivered** in OneSignal but never appear on the device.
* The app includes both OneSignal and `firebase_messaging` (or a custom `FirebaseMessagingService`).
* Push works when Firebase Messaging is removed, but fails when both SDKs are present.

1. Check your `AndroidManifest.xml` for legacy Firebase receivers such as `com.google.firebase.iid.FirebaseInstanceIdReceiver` and remove/conditionally exclude them if OneSignal is responsible for push delivery.

2. Check for custom `FirebaseMessagingService` implementations (or libraries such as `firebase_messaging` in Flutter) that override `onMessageReceived`. If another service fully processes or suppresses messages, it may consume the FCM payload before OneSignal can display the notification.

3. Avoid calling Firebase token management APIs such as: `FirebaseMessaging.getToken()` or `FirebaseMessaging.deleteToken()`.

If OneSignal is responsible for push delivery, it should be the only SDK managing the push token lifecycle. Fetching or managing the FCM token directly can lead to token ownership conflicts and inconsistent delivery behavior.

If you need the device push token for other systems, read it from OneSignal (for example, `User.pushSubscription.token`) and listen for subscription/token changes using the [SDK's observer APIs](./mobile-sdk-reference#addobserver-push-subscription-changes).

***

## Troubleshooting

If you have worked through the sections above and the issue is not resolved, capture a debug log. This is the fastest way to identify exactly where delivery is failing.

Follow [Getting a Debug Log](./capturing-a-debug-log) to enable verbose logging in your app. Then:

1. Put the app in the background
2. Send a test notification to the affected device
3. Check the log for any errors. Make sure you see OneSignal initialized and the `subscription-id` in the log is subscribed to push and the same as the one you are sending the message to.

***

<Info>
  Need help?

  Contact our Support team at `support@onesignal.com`

  Please include:

  * Your OneSignal App ID
  * The Subscription ID or External ID
  * The URL to the message you tested in the OneSignal Dashboard
  * The full debug log from [Getting a Debug Log](./capturing-a-debug-log)

  We're happy to help!
</Info>


# Web permission prompts
Source: https://documentation.onesignal.com/docs/en/permission-requests

Configure OneSignal's web push permission prompts to maximize opt-ins. Covers slidedown prompts, native browser prompts, category selection, email/phone collection, subscription bell, and custom link prompts.

<Frame>
  <iframe title="YouTube video player" />
</Frame>

***

## Overview

"Prompting" refers to the process of asking users for permission to send them messages. Prompts are pop-up messages presented in the browser or mobile app and require the user to click "Allow" to be subscribed and receive messages. This guide covers the different types of web prompts and how to configure them.

Web push works on desktop, Android, and iOS, but [web push for iOS requires additional steps](./web-push-for-ios). If you have a mobile app, see [how to prompt for Push Permissions with In-App Messages](./prompt-for-push-permissions).

Browsers provide their own native, system-level permission prompt, which is required to be both shown and clicked "Allow" for the user to subscribe to push notifications on your website. Browsers now [highly recommend websites be more selective](https://onesignal.com/blog/changes-to-chrome-and-firefox-permission-prompting) when it comes to showing the native permission prompt. This is why using OneSignal Prompts or your own custom "soft prompts" before the native prompt is encouraged.

### OneSignal prompts (soft prompts)

OneSignal soft prompts are user-friendly, customizable prompts that appear before the browser’s native permission prompt. These prompts do not subscribe users to messages by themselves; instead, they help:

1. Explain the value of subscribing to messages (push, email, or SMS).
2. Prevent browsers from automatically blocking permission requests.
3. Launch the native browser prompt only after the user expresses interest.

<Note>
  Soft prompts are [recommended by browsers](https://onesignal.com/blog/changes-to-chrome-and-firefox-permission-prompting) and help maximize engagement rates while protecting your domain reputation.
</Note>

***

## Prompt icon

To customize the icon shown in your web push notifications, go to your OneSignal dashboard: **Settings > Push & In-App > Web Settings**.

In the **Site Setup** section, configure the **Default Icon URL**. This icon appears in all your notifications unless otherwise specified.

* Accepted formats: `.png` or `.jpg`
* Recommended size: `256x256` pixels (to meet Safari's requirements)
* If left unset, OneSignal will use a generic bell icon

This setting can be changed at any time.

<Frame>
  <img alt="Site setup section showing site name, URL, and default icon fields" />
</Frame>

***

## Permission prompt setup

Configure the prompts you want to display on your site. In your OneSignal dashboard, navigate to: **Settings > Push & In-App > Web Settings > Permission Prompt Setup**.

From there, click **Add Prompt** to choose from OneSignal’s available prompt types. You can also edit any existing prompts already shown in the list.

<Frame>
  <img alt="Permission prompt setup page with Add Prompt button" />
</Frame>

Each prompt type has different use cases and display behaviors. You can use them individually or in combination to guide users through the subscription process in a way that fits your website's UX.

Available prompts are:

* [Slidedown](#slidedown-%26-category): A visually prominent prompt used for push notifications and optional category selection.
* [Email/Phone prompt](#email-%26-phone-number-prompt): Used to collect user email addresses, phone numbers, or both.
* [Subscription bell prompt](#subscription-bell-prompt): A persistent floating widget for push subscriptions, typically placed in the bottom corner of your site.
* [Custom link prompt](#custom-link-prompt): A customizable button or link embedded in your site that triggers the native browser prompt.
* [Native permission prompt](#native-permission-prompt): The required browser-level prompt that must be accepted for users to receive push notifications.

***

### Slidedown & category

The Slide and Category prompts appear prominently at the top center of the screen on desktop and bottom center on mobile. These are high-visibility, soft prompts shown before the required [native permission prompt](#native-permission-prompt). They do not subscribe the user on their own but help initiate the subscription flow and capture user interest.

<Frame>
  <img alt="Animated slide prompt with category tags on Chrome desktop" />
</Frame>

To add a Slide Prompt, follow the steps below:

**Typical Site & WordPress Setup:**

1. Go to **Settings > Push & In-App > Web Settings > Permission Prompt Setup**
2. Select **Add Prompt > Push Prompt > Push Slide Prompt**

**Custom Code Setup:**

Use the `slidedown` property in your OneSignal `init` code's `promptOptions` object. See [Web SDK Reference](./web-sdk-reference) for more details.

<Frame>
  <img alt="Push slide prompt configuration options in the dashboard" />
</Frame>

<Note>
  For details on triggering the prompt, see [Auto prompt & display settings](#auto-prompt-%26-display-settings).
</Note>

#### Slide prompt text

You can customize the text displayed in the slide prompt:

* Action message: up to 90 characters
* Button labels: up to 15 characters each
* Customization of font, size, or colors is not currently supported

Enable the text customization option in the dashboard. If no text is entered, default text will be used.

<Frame>
  <img alt="Slide prompt text customization fields" />
</Frame>

When finished, click **Done** and **Save** again on the next page to see this go into effect.

<Info>
  For Custom Code setup, use the `text` properties within your OneSignal `init` code's `promptOptions` object. See [Web SDK Reference](./web-sdk-reference) for more details.
</Info>

#### Categories

You can enhance the Slidedown prompt by adding categories—checkboxes that let users indicate interest in specific message topics (e.g., News, Sales, Updates).

* Up to 10 categories allowed
* Each category is stored as a Data Tag with a `1` (selected) or `0` (not selected)
* Useful for segmentation and targeting messages by user preferences

You may display the category prompt again later to let users update their preferences. Previously selected values will be retained unless overwritten.

* **Label**: what the user sees in the prompt. Recommended to capitalize the first letter.
* **Tag Key**: what the tag in OneSignal will be. Use the `cat_<category>` naming convention (lower case, underscores for spaces) — for example `cat_breaking_news`, `cat_sports`, `cat_apparel`. This matches the convention used across OneSignal industry guides and lets the same Tag namespace be populated automatically from page-visit behavior. See [Tag users by page topic](./auto-segment-users-by-page-visit#tag-by-page-topic-every-visit) for the auto-tag pattern.
* **Update Instructions, Positive and Negative Buttons**: if you choose to display the category prompt again after the user is already subscribed to push, the update instructions will be shown instead of the action message. This allows you to inform the user they can update their categories.

<Frame>
  <img alt="Category configuration showing label and tag key fields" />
</Frame>

When finished, click **Done** and **Save** again on the next page to see this go into effect.

<Info>
  For Custom Code setup, use the `categories` properties within your OneSignal `init` code's `promptOptions` object. See [Web SDK Reference](./web-sdk-reference) for more details.
</Info>

<Note>
  For details on triggering the prompt, see [Auto prompt & display settings](#auto-prompt-%26-display-settings).
</Note>

***

### Email & phone number prompt

The Email & Phone Prompt collects optional user contact information directly within a Slidedown. Each field has built-in validation to ensure correct formatting.

Once submitted:

* New Email and/or SMS subscriptions are created for the user
* You can start messaging them across these channels

To add this prompt:

* Navigate to **Settings > Push & In-App > Web Settings > Permission Prompt Setup > Add Prompt > Email/Phone Prompt**.

<Frame>
  <img alt="Email and phone number prompt setup options" />
</Frame>

Customize which input fields are shown, the text labels, and the auto-prompt delay.

<Frame>
  <img alt="Email and phone number prompt field and label options" />
</Frame>

When finished, press **Done** and **Save** again on the next page to see this go into effect.

<Info>
  For Custom Code setup, within your OneSignal `init` code's `promptOptions` object add the `type` to be either `email`, `sms`, or `smsAndEmail`. See [Web SDK Reference](./web-sdk-reference) for more details.
</Info>

<Note>
  For details on triggering the prompt, see [Auto prompt & display settings](#auto-prompt-%26-display-settings).
</Note>

***

### Subscription bell prompt

The Subscription Bell Prompt is a small, persistent widget that appears in the bottom corner of your website. When clicked by an unsubscribed user, it triggers the [Native Browser Prompt](./permission-requests).

Because of its minimal footprint, the bell can be left visible at all times, making it a passive yet effective option for ongoing opt-in opportunities. It does not require dismissal and provides users with control over when to subscribe.

<Frame>
  <img alt="Subscription bell widget in the bottom corner of a webpage" />
</Frame>

You can customize the OneSignal Bell Prompt's color, size, bottom position, text, and more.

<Warning>
  You cannot currently change the icon image or place the bell in the top corners.
</Warning>

<AccordionGroup>
  <Accordion title="Typical Site & WordPress Setup: Subscription Bell Prompt">
    Navigate to: **Settings > Push & In-App > Web Settings > Permission Prompt Setup > Add Prompt > Subscription Bell Prompt**

    You can customize the bell’s:

    * Color
    * Size
    * Bottom position (left or right)
    * Text and labels

    After setup, click **Done**, then **Save** to apply changes.

    <Frame>
      <img alt="Subscription bell configuration in the dashboard" />
    </Frame>
  </Accordion>

  <Accordion title="Custom Code Setup: Subscription Bell Prompt">
    Use the `notifyButton` parameter in your web SDK initialization options. You may toggle between different examples for Bell Prompt customizations.

    **Hiding:** To hide the subscription bell after a user subscribes or only show it on certain pages, be sure to return the value `false` *or* a `Promise` that resolves to the value `false` in the `displayPredicate` function during initialization. This function is evaluated before the subscription bell is shown. You may return any other value to show the subscription bell.

    <CodeGroup>
      ```javascript Text & Basic Options theme={null}
      // Your other init options here
      notifyButton: {
          enable: true, /* Required to use the Subscription Bell */
          size: 'medium', /* One of 'small', 'medium', or 'large' */
          theme: 'default', /* One of 'default' (red-white) or 'inverse" (white-red) */
          position: 'bottom-right', /* Either 'bottom-left' or 'bottom-right' */
          offset: {
              bottom: '0px',
              left: '0px', /* Only applied if bottom-left */
              right: '0px' /* Only applied if bottom-right */
          },
          showCredit: false, /* Hide the OneSignal logo */
          text: {
              'tip.state.unsubscribed': 'Subscribe to notifications',
              'tip.state.subscribed': "You're subscribed to notifications",
              'tip.state.blocked': "You've blocked notifications",
              'message.prenotify': 'Click to subscribe to notifications',
              'message.action.subscribed': "Thanks for subscribing!",
              'message.action.resubscribed': "You're subscribed to notifications",
              'message.action.unsubscribed': "You won't receive notifications again",
              'dialog.main.title': 'Manage Site Notifications',
              'dialog.main.button.subscribe': 'SUBSCRIBE',
              'dialog.main.button.unsubscribe': 'UNSUBSCRIBE',
              'dialog.blocked.title': 'Unblock Notifications',
              'dialog.blocked.message': "Follow these instructions to allow notifications:"
          }
      }
      ```

      ```javascript Colors theme={null}
      // Your other init options here
      notifyButton: {
        enable: true, // Required to use the Subscription Bell
        // Your other Subscription Bell settings here
        colors: { // Customize the colors of the main button and dialog popup button
          'circle.background': 'rgb(84,110,123)',
          'circle.foreground': 'white',
          'badge.background': 'rgb(84,110,123)',
          'badge.foreground': 'white',
          'badge.bordercolor': 'white',
          'pulse.color': 'white',
          'dialog.button.background.hovering': 'rgb(77, 101, 113)',
          'dialog.button.background.active': 'rgb(70, 92, 103)',
          'dialog.button.background': 'rgb(84,110,123)',
          'dialog.button.foreground': 'white'
        },
      }
      ```

      ```javascript Hiding theme={null}
      // Your other init options here
      notifyButton: {
          /* Your other Subscription Bell settings here ... */
          enable: true,
          displayPredicate: function() {
            /* The user is subscribed, so we want to return "false" to hide the Subscription Bell */
            return !OneSignal.Notifications.permission
          },
      }
      ```

      ```html Full example theme={null}
      <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
      <script>
        window.OneSignalDeferred = window.OneSignalDeferred || [];
        OneSignalDeferred.push(function(OneSignal) {
          OneSignal.init({
            appId: "YOUR_APP_ID",
            notifyButton: {
              enable: true,
              size: 'medium',
              theme: 'default',
              position: 'bottom-right',
              offset: {
                bottom: '0px',
                left: '0px',
                right: '0px'
              },
              showCredit: false,
              text: {
                'tip.state.unsubscribed': 'Subscribe to notifications',
                'tip.state.subscribed': "You're subscribed to notifications",
                'tip.state.blocked': "You've blocked notifications",
                'message.prenotify': 'Click to subscribe to notifications',
                'message.action.subscribed': "Thanks for subscribing!",
                'message.action.resubscribed': "You're subscribed to notifications",
                'message.action.unsubscribed': "You won't receive notifications again",
                'dialog.main.title': 'Manage Site Notifications',
                'dialog.main.button.subscribe': 'SUBSCRIBE',
                'dialog.main.button.unsubscribe': 'UNSUBSCRIBE',
                'dialog.blocked.title': 'Unblock Notifications',
                'dialog.blocked.message': "Follow these instructions to allow notifications:"
              },
              colors: {
                'circle.background': 'rgb(84,110,123)',
                'circle.foreground': 'white',
                'badge.background': 'rgb(84,110,123)',
                'badge.foreground': 'white',
                'badge.bordercolor': 'white',
                'pulse.color': 'white',
                'dialog.button.background.hovering': 'rgb(77, 101, 113)',
                'dialog.button.background.active': 'rgb(70, 92, 103)',
                'dialog.button.background': 'rgb(84,110,123)',
                'dialog.button.foreground': 'white'
              },
              displayPredicate: function() {
                return !OneSignal.Notifications.permission;
              }
            }
          });
        });
      </script>
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

### Custom link prompt

The Custom Link Prompt is a user-triggered button or link you can embed anywhere on your website. When clicked, it displays the [Native Browser Prompt](./permission-requests) for push notifications.

<Frame>
  <img alt="Custom link prompt with subscribe button and explanation text" />
</Frame>

Common use cases:

* Below a blog post: “Like this article? Get updates as soon as we post!”
* In your site footer
* In a sticky header or floating toolbar

<AccordionGroup>
  <Accordion title="Typical Site & WordPress Setup: Custom Link Prompt">
    Navigate to: **Settings > Push & In-App > Web Settings > Permission Prompt Setup > Add Prompt > Custom Link**.

    Add the provided HTML on your page where you want the widget to render.

    Configure your options, then click **Done** and **Save** to activate.

    <Frame>
      <img alt="Custom link prompt setup in the dashboard" />
    </Frame>
  </Accordion>

  <Accordion title="Custom Code Setup: Custom Link">
    Within your OneSignal `init` code's `promptOptions` object, add the `customlink` object and its available properties.

    <CodeGroup>
      ```javascript theme={null}
      // Your other init options here
      promptOptions: {
        customlink: {
          enabled: true, /* Required to use the Custom Link */
          style: "button", /* Has value of 'button' or 'link' */
          size: "medium", /* One of 'small', 'medium', or 'large' */
          color: {
            button: '#E12D30', /* Color of the button background if style = "button" */
            text: '#FFFFFF', /* Color of the prompt's text */
          },
          text: {
            subscribe: "Subscribe to push notifications", /* Prompt's text when not subscribed */
            unsubscribe: "Unsubscribe from push notifications", /* Prompt's text when subscribed */
            explanation: "Get updates from all sorts of things that matter to you", /* Optional text appearing before the prompt button */
          },
          unsubscribeEnabled: true, /* Controls whether the prompt is visible after subscription */
        }
      }
      ```
    </CodeGroup>

    To render the prompt on your site, insert the following HTML where you want the widget to appear:

    ```html html theme={null}
    <div class='onesignal-customlink-container'></div>
    ```
  </Accordion>

  <Accordion title="Typical & Custom Code Setup: Additional Styling">
    To change the appearance of the widget at any time all elements have a special class `onesignal-reset` that removes any prior styling from the element to make sure there are no conflict with our internal styles and that it looks exactly as you've defined it in the dashboard.

    If you ever find yourself in need to redefine any OneSignal styles, here is a short reference of the classes used in the Custom Link widget

    | Class Name                       | Applies to                                                                          |
    | -------------------------------- | ----------------------------------------------------------------------------------- |
    | onesignal-customlink-container   | Main container                                                                      |
    | onesignal-customlink-subscribe   | Action button                                                                       |
    | onesignal-customlink-explanation | Paragraph with a custom explanation text                                            |
    | state-subscribed                 | All components internal to the main container                                       |
    | state-unsubscribed               | All components internal to the main container                                       |
    | button                           | Action button if in button mode                                                     |
    | link                             | Action button if in link mode                                                       |
    | small                            | All components internal to the main container                                       |
    | medium                           | All components internal to the main container                                       |
    | large                            | All components internal to the main container                                       |
    | hide                             | All components internal to the main container if unsubscribeEnabled is set to false |

    To override any of them you have to create a CSS rule with higher specificity, combining the class name with the parent element id should be enough. But beware of the conflicts, our internal styles may change.
  </Accordion>
</AccordionGroup>

***

## Native permission prompt

The native permission prompt is the browser-controlled dialog that users must accept to subscribe to push notifications from your website. This prompt is:

* Required for subscription
* Automatically triggered after OneSignal soft prompts
* Not customizable in appearance, text, or behavior

<Frame>
  <img alt="Native browser permission prompt on Chrome" />
</Frame>

### Browser native prompt behavior

Different browsers impose unique behaviors and restrictions to reduce spammy permission requests. In an effort to combat spam and poor user experience, OneSignal will automatically default to the Slide Prompt in certain cases listed below.

**If you do not want to show the Slide Prompt and would like to use the native permission prompt directly, you must turn off the Auto Prompt options and use our [Web SDK `requestPermission()` method](./web-sdk-reference#requestpermission).** Displaying the native permission prompt directly may not work in all browsers as described below.

#### Chrome

[Chrome 80+](https://blog.chromium.org/2020/01/introducing-quieter-permission-ui-for.html?m=1) may display a quieter UI instead of the full prompt:

* Automatically applies to users who frequently deny prompts
* Also applies to sites with a high rate of denials

<Frame>
  <img alt="Chrome quieter notification permission UI" />
</Frame>

Chrome implements back-off logic if the user clicks the "X" on the native prompt:

* You have 3 attempts to prompt
* After the 3rd dismissal, the prompt is suppressed for 7 days ([source](https://chromestatus.com/feature/6443143280984064)).

<Warning>
  Using the Typical Site & WordPress Setup to configure the native permission prompt will automatically show the Slide Prompt on Chrome for mobile devices.

  We deliberately added the double prompt on Android because the native Permission Prompt on Chrome for Android is a very user-unfriendly pop-up that takes over the entire screen of your site and this prevents your users from having a bad experience while visiting your site.

  If you do not want to show the Slide Prompt, you must turn off the Auto Prompt switch in the Prompt Editor (don't forget to press the **Save** button), then use the [Web SDK `requestPermission()` method](./web-sdk-reference#requestpermission).
</Warning>

#### Firefox

[Firefox 72+](https://blog.mozilla.org/futurereleases/2019/11/04/restricting-notification-permission-prompts-in-firefox/) started requiring a user gesture to trigger the native permission prompt. If you try to automatically show the native permission prompt on Firefox, you will see an icon within the browser like this, requiring the user to click the icon to show the native permission prompt.

<Frame>
  <img alt="Firefox notification permission icon in the address bar" />
</Frame>

<Warning>
  Using the Typical Site & WordPress Setup to configure the native permission prompt will automatically show the Slide Prompt on Firefox.

  We deliberately added the double prompt on Firefox because it requires a 2-step opt-in in either case and the Slide prompt is a more eye-catching way to increase engagement.

  If you do not want to show the Slide Prompt, you must turn off the Auto Prompt switch in the Prompt Editor (don't forget to press the **Save** button), then use the [Web SDK `requestPermission()` method](./web-sdk-reference#requestpermission).
</Warning>

#### Safari

[Safari 12.1+](https://developer.apple.com/documentation/safari_release_notes/safari_12_1_release_notes) started requiring a user gesture to trigger the native permission prompt.

<Warning>
  Using the Typical Site & WordPress Setup to configure the native permission prompt will not work for Safari because of this user gesture requirement.

  We deliberately added the Slide Prompt on Safari because it requires a 2-step opt-in.
</Warning>

#### Edge

[Edge](https://blogs.windows.com/msedgedev/2023/07/06/fighting-notification-spam-microsoft-edge/) uses a trust-based model:

* If the site is untrusted, the prompt is suppressed and replaced by a bell icon in the browser bar:

<Frame>
  <img alt="Edge bell icon shown for untrusted sites" />
</Frame>

* If the site is trusted, the native prompt appears normally:

<Frame>
  <img alt="Edge native permission prompt for trusted sites" />
</Frame>

***

## Auto prompt & display settings

To maximize engagement and avoid disrupting your users, it’s best to delay showing prompts until after they've spent some time on your site. OneSignal allows you to automatically display prompts based on user behavior using two delay conditions:

* **Page Views:** Number of times the user loads any page on your site
* **Seconds on Page:** Amount of time the user must spend on the page

These delays are applied using an **AND** condition, meaning both must be satisfied before the prompt appears.

**Example:** If you set the delay to 3 page views and 30 seconds, the prompt will display on the third page load, after 30 seconds have passed. If the user doesn't interact with the prompt, it will continue showing on each page load (after 30 seconds) until it’s clicked or dismissed.

<AccordionGroup>
  <Accordion title="Typical Site & WordPress Setup: Auto Prompt">
    * Navigate to: **Settings > Push & In-App > Web Settings > Permission Prompt Setup**
    * Choose a prompt or create a new one
    * Enable Auto Prompt
    * Set your delay preferences (page views and time delay)

    <Frame>
      <img alt="Auto prompt delay settings for page views and seconds" />
    </Frame>

    * Click Done, then Save

    <Info>
      If you want to trigger the prompt programmatically, keep Auto Prompt disabled and use the [Web SDK Prompt prompt methods](./web-sdk-reference).
    </Info>
  </Accordion>

  <Accordion title="Custom Code Setup: Auto Prompt">
    Within your OneSignal `init` code's `promptOptions` object use the `autoPrompt` and `delay` options. There are also methods to trigger the desired slidedown or native prompts directly. See [Web SDK Reference](./web-sdk-reference) for more details.
  </Accordion>

  <Accordion title="Manual Triggering (Instead of Auto Prompt)">
    If you want more control over when prompts are shown—for example, only on specific pages or after specific actions:

    1. Disable Auto Prompt
    2. Use the SDK's Slidedown or Native Prompt methods to show the prompt via code
  </Accordion>
</AccordionGroup>

### Slidedown prompt back-off logic

Once a Slidedown (Push, Category, or Email/Phone) prompt is shown and dismissed (via Allow, Cancel, or closing the dialog), it will back off and reappear on a defined schedule:

|             Interaction Outcome             | Next Prompt Timing |
| :-----------------------------------------: | :----------------: |
|               First Dismissal               |     Wait 3 days    |
|               Second Dismissal              |     Wait 7 days    |
| Third and later dismissals (not subscribed) |    Wait 30 days    |

For example, if the user clicks "Allow" on the Slidedown but then clicks "X" on the browser's native prompt (without subscribing), the Slidedown will follow the back-off cycle above.

<Warning>
  This logic applies to Push, Category, and Email/Phone Slidedown prompts. You can bypass the backoff logic using our [Web SDK Slidedown prompt methods](./web-sdk-reference#slidedown-prompts).

  For native prompt back-off logic, see [Browser native prompt behavior](#browser-native-prompt-behavior). You cannot bypass the backoff logic for the native prompt because this is controlled by the browser.
</Warning>

If the user clears cookies or browser data, the back-off cycle resets and the prompt may appear again as if for the first time.

***

## Best practices for requesting web push permissions

Getting users to grant web push permissions requires timing, trust, and user-friendly design. Follow these best practices to maximize opt-in rates while maintaining a positive on-site experience.

### Be strategic with when you ask

Timing matters more than frequency. Display permission prompts when users are already engaged or showing intent. For example:

* After they add an item to their cart or engage on a post or comment
* When they update their profile or sign in to their account
* Upon completing an action that shows commitment to your brand

Prompting users at these moments increases acceptance rates because they’re more invested in your content and value.

If your site has a profile or preference center, include push (and other channel) opt-in controls there. This reinforces transparency and gives users more control over how they receive updates. See our [Preference Center](./preference-center) guide for more details.

### Use the Subscription Bell Prompt

The [Bell Prompt](#subscription-bell-prompt) is a persistent, non-intrusive way for users to subscribe at any time. This floating bell icon is ideal for long-term engagement because it:

* Keeps the subscription option visible without disrupting browsing.
* Allows users to subscribe when they choose.
* Builds trust by not forcing immediate permission requests.

<Note>
  The Bell Prompt is especially effective for returning visitors and users who initially dismissed permission requests.
</Note>

### Let users personalize their subscriptions with Categories

The [Category Prompt](#categories) lets users choose which topics or message types they want—like "Sales", "Product Updates", or "Blog Posts". This approach:

* Makes the prompt feel less intrusive and more relevant
* Improves engagement and message click-through rates
* Reduces opt-outs later by setting expectations early

<Note>
  Personalized opt-ins lead to higher long-term retention because users feel in control of the experience.
</Note>

### Test and optimize over time

Don’t rely on a single strategy. Test different prompt types, messages, and timings to see what resonates with your audience.

Try this approach:

* Start with the native browser prompt for a few months to measure your baseline opt-in rate.
* After gathering data, experiment with the slidedown prompt or custom prompt flows to improve conversions across browsers and audience segments.
* Track performance using our SDK's [`permissionPromptDisplay` and `permissionChange` events](./web-sdk-reference#addeventlistener-notifications) and [`slidedown` events](./web-sdk-reference#addeventlistener-slidedown).

<Info>
  Opt-in behavior can vary by season, device type, and region—so test regularly to find the right balance between engagement and user comfort.
</Info>

***

## FAQ

### Prompt display issues

A browser's native permission prompt may not show if any of the following conditions are true:

**1. The browser blocked the prompt from showing.**

Navigate to your browser's settings and check the "Notifications" permission setting. Chrome example: `chrome://settings/content/notifications`

<Frame>
  <img alt="Chrome browser notification permission settings page" />
</Frame>

In this example:

* The user has selected "Don't allow sites to send notifications" which will prevent the native permission prompt from showing. This must show "Sites can ask to send notifications" to allow the native permission prompt to show.
* The user has added `https://yoursite.com` to the "Not allowed to send notifications" list, which will prevent the native permission prompt from showing. This must be removed from the list to allow the native permission prompt to show.

**Browser specific documentation:**

* [Chrome](https://support.google.com/chrome/answer/3220216) - This page explains how to manage notifications in Chrome by going to Settings > Privacy and security > Site Settings > Notifications, where you can control default behavior and manage permissions for individual websites.
* [Firefox](https://support.mozilla.org/en-US/kb/push-notifications-firefox) - This guide covers Firefox's Web Push notifications, explaining how to manage notification permissions through Settings > Privacy & Security > Notifications, and how to control permissions for specific sites through the address bar's site information icon.
* [Safari](https://support.apple.com/guide/safari/customize-website-notifications-sfri40734/mac) - This Apple guide explains how to customize Safari notifications on Mac through Safari > Preferences > Websites > Notifications, where you can manage which sites can send notifications and control notification behavior through System Preferences.
* [Edge](https://support.microsoft.com/en-us/microsoft-edge/manage-website-notifications-in-microsoft-edge-0c555609-5bf2-479d-a59d-fb30a0b80b2b) - This article details how to manage Edge notifications by navigating to Settings > Privacy, search, and services > Site permissions > Notifications, or by clicking the site information icon in the address bar.

**2. The user has already allowed notifications or already subscribed.**

In the browser's settings, check if your site URL is listed in the "Allowed to send notifications" list.

**3. You are in Incognito Mode, Private Browser mode or Guest Browser mode.**

The native Permission Prompt will not show while in Incognito Mode, Private Browser mode or Guest Browser mode. Users cannot subscribe to notifications in these modes.

**4. You are using a browser and device that does not support web push notifications.**

Make sure you are [using a browser and device that supports web push](./web-push-setup-faq#browser-support-by-operating-system).

**5. iOS/iPadOS requirements are not met.**

For iOS, there are some additional requirements to prompt users for their subscription. More information can be seen in the [Mobile Web Push for iOS/iPadOS](./web-push-for-ios) guide.

<Warning>
  If you are still having trouble, see our [Web push troubleshooting guide](./troubleshooting-web-push).
</Warning>

### How do I show prompts in a social media app webview?

Webviews used by social media apps (Instagram, TikTok, Facebook, etc.) do not support web push notifications. The app must open your website in a full browser that supports web push.

### Why does the slide prompt keep showing up?

There are two common causes:

1. You are in incognito mode, private browser mode, or guest browser mode.
2. You are triggering the prompt programmatically without using the Auto Prompt option. See the [Web SDK Reference](./web-sdk-reference) and check the prompting methods you are using.

### After dismissing a prompt, when does it show again?

For OneSignal prompts, see [Slidedown prompt back-off logic](#slidedown-prompt-back-off-logic). For the native permission prompt, see [Browser native prompt behavior](#browser-native-prompt-behavior).

### Why do I see the slide prompt instead of the native browser prompt?

Certain browsers require a user gesture before showing the native prompt. OneSignal automatically shows a slide prompt first in these cases. See [Browser native prompt behavior](#browser-native-prompt-behavior) for details.

### How do I translate or localize the prompt?

Use the [Custom Code Setup](./web-push-custom-code-setup) to programmatically detect the user's browser language and initialize the OneSignal SDK with different text. The native permission prompt automatically translates to the browser's set language.

### Can I A/B test prompts?

Yes. Using the [Custom Code Setup](./web-push-custom-code-setup), you can initialize OneSignal with different prompting options. You need to set up your own method to trigger the A/B tests. Use the [Subscription Change](./web-sdk-reference#addeventlistener-push-subscription) event to detect when a user subscribes and add [Tags](./add-user-data-tags) based on which variant won.

### Can I segment subscriptions based on the page they subscribed?

Yes. See the [Auto-Segment By Subscription Page](./auto-segment-users-by-page-visit#tag-at-subscription-one-time-web-only) guide.

### Can I change the bell icon?

No. You cannot change the bell image, but you can customize the colors, text, and position (bottom-left or bottom-right).

### Can I change the categories based on page?

Yes, in two ways. To show different category checkboxes on different pages, use [Custom Code Setup](./web-push-custom-code-setup) and configure the `categories` `promptOptions` per page. To automatically apply `cat_<category>` Tags as readers browse (without showing a prompt), see [Tag users by page topic](./auto-segment-users-by-page-visit#tag-by-page-topic-every-visit) — the auto-tag pattern uses the same Tag namespace as the Category Prompt, so the two approaches combine cleanly.

### How do I track slide prompt events?

The OneSignal Web SDK provides [Slide Prompt Event Methods](./web-sdk-reference#addeventlistener-slidedown) to detect when the prompt shows, closes, or receives an "Allow" or "Cancel" action.

### How can I show the prompt on only certain pages?

[Disable **Auto Prompt**](#auto-prompt-%26-display-settings), then use the [Slidedown prompt](./web-sdk-reference#slidedown-prompts) SDK method on the specific pages where you want prompts to appear. The Bell prompt cannot be disabled on a per-page basis.

### Why do I see the slide prompt on mobile instead of the native prompt?

Chrome for Android displays a full-screen native prompt that disrupts the browsing experience. OneSignal shows a slide prompt first to provide a better user experience. To bypass this, turn off Auto Prompt in the Prompt Editor and use the [Web SDK `requestPermission()` method](./web-sdk-reference#requestpermission).

***

## Related pages

<Columns>
  <Card title="Web SDK reference" icon="code" href="./web-sdk-reference">
    Full API reference for prompt methods, events, and initialization options.
  </Card>

  <Card title="Web push for iOS" icon="apple" href="./web-push-for-ios">
    Additional setup steps required for iOS and iPadOS web push support.
  </Card>

  <Card title="Web push troubleshooting" icon="wrench" href="./troubleshooting-web-push">
    Diagnose and resolve common web push notification issues.
  </Card>

  <Card title="Preference center" icon="sliders" href="./preference-center">
    Let users manage their notification preferences and channel opt-ins.
  </Card>
</Columns>


# Personalize messages with API custom_data
Source: https://documentation.onesignal.com/docs/en/personalization-api-custom-data

Send dynamic, message-specific data through the Create Message API using custom_data. Reference values in templates with Liquid syntax for real-time personalization.

Use the `custom_data` field in the [Create Message API](/reference/create-message) to send dynamic data from your backend and render it inside templates using [Liquid syntax](./using-liquid-syntax).

`custom_data`:

* Is **message-specific**
* Is **not stored**
* Exists only during the API request
* Must be used with a `template_id`

Reference values in templates with:

```liquid Liquid theme={null}
{{ message.custom_data.key_name }}
```

<Warning>
  `custom_data` is ephemeral. Data is not saved to user profiles and cannot be reused in future messages. If you need persistent data, see [Message personalization](./message-personalization).
</Warning>

***

## When to use `custom_data`

Use `custom_data` when you need:

* Data changes per message (order totals, cart items, balances)
* You need arrays (product lists, line items, recommendations)
* Data should not persist (one-time codes, temporary URLs)
* You send backend-triggered messages
* You want bulk personalization in one API request

***

## How `custom_data` personalization works

Adding `custom_data` to messages requires a few steps:

<Steps>
  <Step title="Create a template">
    Create a Push, Email, or SMS [Template](./templates) in the dashboard or via [Create Template API](/reference/create-template).
  </Step>

  <Step title="Add Liquid placeholders">
    Insert references using the required prefix:

    ```liquid Liquid theme={null}
    Hi {{ message.custom_data.first_name }},
    Order {{ message.custom_data.order_id }} is confirmed.
    ```
  </Step>

  <Step title="Send custom_data in your API request">
    Call the [Create Message API](/reference/create-message) with:

    * `template_id` - The ID of the template
    * `custom_data` - The data object
    * Audience targeting (`include_player_ids`, `include_aliases`, or segments)

    OneSignal renders the template at send time using your data.

    If Liquid syntax is invalid or keys don't exist, those fields render as empty strings, but the message still sends.
  </Step>
</Steps>

***

## Data patterns

Common examples of data patterns you can use with `custom_data`.

### Flat JSON example

Use simple key-value pairs for basic personalization like names, IDs, URLs, or any single-value data.

**Use case:** Transactional messages (invoices, receipts, confirmations) where each field contains a single value.

**Template:**

```liquid Liquid theme={null}
Invoice {{ message.custom_data.invoice_id }} for {{ message.custom_data.product_name }} is ready.
```

**API request:**

```json JSON theme={null}
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_email_tokens": ["user@example.com"],
  "custom_data": {
    "invoice_id": "463246732",
    "product_name": "Widget"
  }
}
```

**What the customer sees:**

```liquid Text theme={null}
Invoice 463246732 for Widget is ready.
```

***

### Array data example

Pass arrays of objects to work with multiple items like cart products, order line items, or recommendations. Arrays enable both direct access (indexing) and iteration (loops).

**Use case:** Displaying product lists, leaderboards, order summaries, or any multi-item data.

**Indexing template (accessing first item):**

```liquid Liquid theme={null}
Your {{message.custom_data.cart_items[0].item_name}} is waiting for you!
Image: {{message.custom_data.cart_items[0].img_url}}
```

<Warning>
  **Array indexing starts at 0**, not 1. The first item is `[0]`, second is `[1]`, etc. Accessing an index that doesn't exist returns empty (no error thrown).
</Warning>

**Looping template (accessing all items):**

```liquid Liquid theme={null}
{% for item in message.custom_data.cart_items %}
- {{ item.item_name }} — {{ item.img_url }}
{% endfor %}
```

**API request:**

```json JSON theme={null}
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_email_tokens": ["user@example.com"],
  "custom_data": {
    "cart_items": [
      {
        "item_name": "sweater",
        "img_url": "https://.../sweater.png"
      },
      {
        "item_name": "socks",
        "img_url": "https://.../socks.png"
      }
    ]
  }
}
```

**What the customer sees:**

```liquid Text theme={null}
Your sweater is waiting for you!
Image: https://.../sweater.png

- sweater — https://.../sweater.png
- socks — https://.../socks.png
```

**Useful array properties:**

* `{{message.custom_data.cart_items.size}}` — Number of items in array (returns `2` in this example)
* `{{message.custom_data.cart_items.first.item_name}}` — First item's name (equivalent to `[0]`)
* `{{message.custom_data.cart_items.last.item_name}}` — Last item's name

***

### Bulk personalization example

Send a single API request to multiple users where each recipient sees personalized content based on their `external_id`.

**How it works:**

1. Structure `custom_data` as an object where **keys are external\_ids** and **values are user-specific data**
2. In the template, use `subscription.external_id` to look up the current recipient's data
3. OneSignal renders the template once per recipient with their specific data

**Template:**

```liquid Liquid theme={null}
{% assign user = message.custom_data.users[subscription.external_id] %}
Hi {{ user.first_name }}, you have {{ user.points }} points. Your level is {{ user.level }}.
```

**What's happening:**

* `subscription.external_id` contains the current recipient's external\_id (e.g., "user123")
* `message.custom_data.users[subscription.external_id]` looks up that user's data from the custom\_data object
* `user` becomes a shorthand variable for that user's data
* Each recipient only sees their own personalized content

**API request:**

```json JSON theme={null}
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user123", "user456"]
  },
  "custom_data": {
    "users": {
      "user123": { "first_name": "John", "points": "150", "level": "Gold" },
      "user456": { "first_name": "Sarah", "points": "200", "level": "Platinum" }
    }
  }
}
```

**What each user sees:**

<Check>
  * **John** (user123): "Hi John, you have 150 points. Your level is Gold."
  * **Sarah** (user456): "Hi Sarah, you have 200 points. Your level is Platinum."
</Check>

<Info>
  **Requirements for bulk personalization:**

  * All recipients must have an `external_id` set in OneSignal
  * Each `external_id` in `include_aliases` must have a matching key in `custom_data.users`
  * If a recipient's external\_id is missing from `custom_data`, their message will have empty fields
</Info>

***

## Example: Abandoned cart with custom\_data

How to build abandoned cart messages for both email and push using `custom_data`.

**When to use this approach:**

* Your server detects cart abandonment (e.g., 1 hour after last activity)
* Real-time cart data is in your database
* You want to display multiple products with images, names, prices
* Each user may have different items and quantities
* You want to orchestrate the message from your backend.

### Example `custom_data` payload

This is the [Create Message API](/reference/create-message) request for this example.

```json JSON theme={null}
{
  "custom_data": {
    "cart_url": "https://yourdomain.com/cart",
    "cart": [
      {
        "product_name": "24 Pack of Acorns",
        "product_image": "https://i.imgur.com/ssPCfbC.png",
        "product_price": "$12.99",
        "product_quantity": "1"
      },
      {
        "product_name": "Fancy Sweater",
        "product_image": "https://i.imgur.com/8QWTfV4.png",
        "product_price": "$9.99",
        "product_quantity": "1"
      }
    ]
  },
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["YOUR_EXTERNAL_ID"]
  }
}
```

**Field explanations:**

| Field              | Type   | Purpose                                                         |
| ------------------ | ------ | --------------------------------------------------------------- |
| `cart_url`         | string | Customer's unique cart link (for buttons/launch URLs)           |
| `cart`             | array  | List of products—supports counting, looping, and detail display |
| `product_image`    | string | Product image (per item in array)                               |
| `product_name`     | string | Product name (per item)                                         |
| `product_quantity` | string | Quantity (per item)                                             |
| `product_price`    | string | Price with formatting (per item)                                |

<Note>
  You can name fields anything you want—just ensure your template's Liquid syntax matches.
</Note>

<Warning>
  **Stay under 2KB:** If you have large carts, consider limiting to the first 3-5 items or sending only essential fields to avoid exceeding the size limit.
</Warning>

### Email template

This example shows how to build an email template that displays:

* The cart item count
* Each product with image, name, quantity, and price using a for-loop
* A button that links to the customer's unique cart URL

<Frame>
  <img />
</Frame>

<Steps>
  <Step title="Create the email template">
    Navigate to **Messages > Templates > New Email Template** and open the Drag & Drop Editor.
  </Step>

  <Step title="Add the layout structure">
    Create five rows:

    * Rows 1, 2, and 4: one column with a **Paragraph** block
    * Row 3: four columns with **HTML | Paragraph | Paragraph | Paragraph**
    * Row 5: one column with a **Button** block

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Display the item count">
    In row 1, add:

    ```liquid Liquid theme={null}
    We're holding onto {{message.custom_data.cart.size}} items in your cart, but don't wait too long, other squirrels are getting ahead!
    ```

    For better grammar, you could use a conditional to say "1 item" vs "2 items", but for abandoned cart emails, plural is usually acceptable.

    ```liquid Liquid theme={null}
    {% assign cart = message.custom_data.cart %}
    {% assign item_count = cart.size | plus: 0 %}
    {% if item_count == 1 %}
    We're holding onto {{item_count}} item in your cart, but don't wait too long, other squirrels are getting ahead!
    {% endif %}
    {% if item_count > 1 %}
    We're holding onto {{item_count}} items in your cart, but don't wait too long, other squirrels are getting ahead!
    {% endif %}
    ```
  </Step>

  <Step title="Start the for-loop">
    Use a [for-loop](./using-liquid-syntax#for-loops) to repeat the product display row for each cart item.

    In row 2 (loop start), add:

    ```liquid Text theme={null}
    {% for product in message.custom_data.cart %}
    ```

    **What this does:**

    * Begins a loop that iterates over each object in the `cart` array
    * Creates a temporary variable called `product` that represents the current item
    * Everything between `{% for %}` and `{% endfor %}` repeats once per cart item
    * You can name `product` anything (e.g., `item`, `cartItem`)—just stay consistent

    <Warning>
      For-loop placement: Make sure the `{% for %}` syntax is in its own Text block row. Don't put it inside a multi-column row with other content, as this can break email rendering in some clients.
    </Warning>
  </Step>

  <Step title="Display product details">
    This 4-column row shows image, name, quantity, and price. Because it's inside the loop, it repeats for every cart item.

    In row 3 (product details), configure:

    **Column 1 - HTML block** (product image):

    ```html HTML theme={null}
    <img src="{{product.product_image}}" alt="Product image" style="max-width:100%;" />
    ```

    **Columns 2–4 - Text blocks** (product name, quantity, price):

    * Column 2: `{{product.product_name}}`
    * Column 3: `{{product.product_quantity}}`
    * Column 4: `{{product.product_price}}`

    **How the loop works:**

    * On the first iteration, `product` = first object in the cart array
    * `{{product.product_image}}` gets the first item's image URL
    * On the second iteration, `product` = second object
    * Row repeats automatically for all cart items

    <Warning>
      **Field name matching:** Keys like `product_image` must exactly match your event payload (case-sensitive). Mismatches render as empty strings.
    </Warning>
  </Step>

  <Step title="End the for-loop">
    Close the loop to mark where repetition stops.

    In row 4 (loop end), add:

    ```liquid Liquid theme={null}
    {% endfor %}
    ```

    <Note>
      Every `{% for %}` must have a matching `{% endfor %}`. Missing this will break email rendering.
    </Note>
  </Step>

  <Step title="Add a cart link button">
    In the row 5 **Button** block, set the Action URL to:

    ```liquid Text theme={null}
    {{message.custom_data.cart_url}}
    ```

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Test the template">
    * Setup your API request using the [Example `custom_data` payload](#example-custom-data-payload)
    * Send yourself the email.
    * Verify the data displays correctly.

    <Check>Success! Now you can apply your own styling to the template. See [Design emails with drag-and-drop](./design-emails-with-drag-and-drop).</Check>
  </Step>
</Steps>

### Push template

Push notifications have character limits and operating system restrictions, so instead of showing all items, display the first product and indicate the total count with proper grammar.

Here is an example push notification we will build:

<Frame>
  <img />
</Frame>

**Message field:**

```liquid Liquid theme={null}
{% assign cart = message.custom_data.cart %}
{% assign item_count = cart.size | plus: 0 %}
{% if item_count == 1 %}
You left {{cart.first.product_name}} in your cart.
{% endif %}
{% if item_count == 2 %}
You left {{cart.first.product_name}} and {{item_count | minus: 1}} more item in your cart.
{% endif %}
{% if item_count > 2 %}
You left {{cart.first.product_name}} and {{item_count | minus: 1}} more items in your cart.
{% endif %}
```

<Info>
  See [Using Liquid syntax](./using-liquid-syntax#if-elsif-else) for more information.
</Info>

**Image field:**

```liquid Liquid theme={null}
{{message.custom_data.cart.first.product_image | default: "https://i.imgur.com/ssPCfbC.png"}}
```

<Info>
  See [Notification images & rich media](./rich-media) for more information.
</Info>

**Launch URL field:**

```liquid Liquid theme={null}
{{cart_url | default: "https://yourdomain.com/cart"}}
```

<Check>
  Success! Save the template and use its `template_id` in your [Create message](/reference/create-message) API request with the `custom_data` property to test.
</Check>

***

## Troubleshooting & best practices

* **Keep it simple**: Only include data you'll actually use in the template
* **Stay under 2KB**: Monitor your payload size, especially with arrays
* **Use consistent naming**: Stick to `snake_case` or `camelCase` throughout
* **Validate before sending**: Check for null values, empty arrays, and required fields

**Template design:**

* **Always use default filters** for optional fields:
  ```liquid Liquid theme={null}
  {{message.custom_data.user_name | default: "there"}}
  ```
* **Check array size before looping**:
  ```liquid Liquid theme={null}
  {% if message.custom_data.items.size > 0 %}
    {% for item in message.custom_data.items %}
      {{item.name}}
    {% endfor %}
  {% endif %}
  ```
* **Test with edge cases**: empty arrays, missing fields, maximum item counts

**Error handling:**

* Log API responses server-side to catch validation errors
* Monitor message delivery rates—sudden drops may indicate Liquid errors
* Keep fallback templates ready for critical transactional messages

**Performance:**

* **Pre-format complex data** in your backend rather than using complex Liquid logic
* **Cache templates** and reuse them across many API calls
* Consider separating high-volume transactional messages from marketing campaigns

<Accordion title="Message sends but content is blank">
  **Cause:** Liquid syntax errors or mismatched field names

  **Solutions:**

  * Verify field names match exactly between `custom_data` and template (case-sensitive)
  * Check for typos: `{{message.custom_data.name}}` not `{{message.custm_data.name}}`
  * Use [default filters](./using-liquid-syntax#default) to catch missing fields
  * Test templates with the actual `custom_data` structure before production
</Accordion>

<Accordion title="API Error: Request body too large">
  **Cause:** `custom_data` exceeds 2KB limit

  **Solutions:**

  * Remove unnecessary fields from your payload
  * Shorten field names and values where possible
  * Limit arrays to first 3-5 items
  * Move large static content (like full HTML) to your template instead
</Accordion>

***

## Related pages

<Columns>
  <Card title="Message personalization" href="./message-personalization" icon="sparkles">
    Overview of all personalization options in OneSignal, including Tags, user attributes, and segmentation.
  </Card>

  <Card title="Create Message API" href="/reference/create-message" icon="code">
    Complete API reference for sending messages with custom\_data, targeting options, and all available fields.
  </Card>

  <Card title="Using Liquid syntax" href="./using-liquid-syntax" icon="droplet">
    Full Liquid syntax reference including filters, conditionals, loops, and string manipulation.
  </Card>

  <Card title="Templates" href="./templates" icon="file">
    Create and manage reusable message templates for Push, Email, SMS, and In-App channels.
  </Card>
</Columns>

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Personalize with Custom Events
Source: https://documentation.onesignal.com/docs/en/personalization-custom-event

Use Custom Event properties to personalize Journey messages with Liquid syntax. Learn how events are stored, accessed, and rendered in push, email, and SMS templates.

[Custom Events](./custom-events) let you personalize Journey messages using event properties (product names, prices, URLs, arrays, etc.).

Event properties become available in templates only if the event:

* Triggers Journey entry, or
* Matches a **Wait Until** condition inside the Journey

Stored event properties can be accessed using [Liquid syntax](./using-liquid-syntax).

***

## How Custom Event personalization works

Add event properties to your Journey messages following these steps:

<Steps>
  <Step title="Send a Custom Event with properties">
    Example [Custom Events](./custom-events) payload:

    ```json JSON theme={null}
    {
      "name": "purchase",
      "properties": {
        "item": "Blue Sweater",
        "price": "29.99",
        "order status": "pending",
        "details": [
          {
            "manufacturer": "Company A",
            "model": "1234567890"
          },
          {
            "manufacturer": "Company B",
            "model": "9876543210"
          }
        ]
      },
      "external_id": "user_12345",
      "timestamp": "2025-10-21T19:09:32.263Z",
    }
    ```
  </Step>

  <Step title="Reference event properties in your Journey message templates">
    Use [Liquid syntax](./using-liquid-syntax) to access event properties.

    ### Common Liquid access patterns

    | What you want                    | Liquid                                                                | Output                         |
    | -------------------------------- | --------------------------------------------------------------------- | ------------------------------ |
    | Event name                       | `{{ journey.first_event.name }}`                                      | `purchase`                     |
    | Property                         | `{{ journey.first_event.properties.item }}`                           | `Blue Sweater`                 |
    | Nested properties                | `{{ journey.first_event.properties.details.first.manufacturer }}`     | `Company A`                    |
    | Property with special characters | `{{ journey.last_event.properties["order status"] }}`                 | `pending`                      |
    | Timestamp                        | `{{ journey.last_event.timestamp \| date: "%B %d, %Y at %I:%M %p" }}` | `October 21, 2025 at 07:09 PM` |

    #### Nested Liquid access patterns

    You can also access nested properties using dot and bracket notation:

    ```liquid Liquid theme={null}
    {{ journey.first_event.properties.details.first.manufacturer }} = Company A
    {{ journey.first_event.properties.details.last.manufacturer }} = Company B
    {{ journey.first_event.properties.details[0].manufacturer }} = Company A
    {{ journey.first_event.properties.details[1].manufacturer }} = Company B
    ```

    <Warning>
      Invalid Liquid or missing properties render as empty strings. Messages still send. Use [default filters](./using-liquid-syntax#default) to set a fallback.
    </Warning>
  </Step>

  <Step title="Create a Journey">
    Setup the Journey to use the Custom Event as the entry rule and/or Wait Until condition.

    * See [Journeys settings](./journeys-settings) for Entry rules.
    * See [Journeys actions](./journeys-actions) for Wait Until conditions.

    Add message nodes with the templates.
  </Step>
</Steps>

### Event property storage rules

* You can use multiple events in your Journey by combining entry rules and Wait Until steps.
* Maximum: **100 stored event properties per user per Journey instance** (oldest dropped).
* Event properties are stored **per user, per Journey instance**.
* Events sent before entry are not accessible.
* Event properties are cleared when the user exits the Journey.

<Warning>
  Events stored in one Journey cannot be accessed in another Journey.
</Warning>

***

## Custom Event Liquid reference

Use these objects to access stored events inside the Journey.

<ParamField>
  The first stored event for this Journey instance.

  * If using a **Custom Event Entry Rule**, than this is the event that caused Journey entry.
  * If not using a Custom Event Entry Rule, then this is the first event stored by matching a Wait Until condition.

  ```liquid Liquid theme={null}
  Thanks for purchasing {{ journey.first_event.properties.item | default: "your item" }}!
  ```
</ParamField>

<ParamField>
  The most recent stored event for this Journey instance.

  * If only one event is stored, `first_event` and `last_event` return the same thing.

  ```liquid Liquid theme={null}
  Your most recent purchase was {{ journey.last_event.properties.item | default: "made" }}!
  ```
</ParamField>

<ParamField>
  The most recent stored event with a specific name.

  * Replace `EVENT_NAME` with your event name (e.g., `purchase`).
  * If the same event name is used multiple times, this returns the most recent instance.

  ```liquid Liquid theme={null}
  {% assign event = journey.event.purchase %}
  ```

  If your event name includes spaces or special characters, use [bracket notation](https://shopify.dev/docs/api/liquid/basics#referencing-handles).

  **Example Event:** `"name": "order status"`

  ```liquid Liquid theme={null}
  {% assign event = journey.event["order status"] %}
  ```
</ParamField>

<ParamField type="array">
  All stored events for this Journey instance, in the order they were stored.

  * Use [for loops](./using-liquid-syntax#for-loops) to iterate over them.

  ```liquid Liquid theme={null}
  {% for event in journey.all_events %}
  • {{ event.properties.item | default: "Item" }} — ${{ event.properties.price | default: "0.00" }}
  {% endfor %}
  ```

  * `journey.first_event` is shorthand for `journey.all_events[0]`.
  * `journey.last_event` is shorthand for the most recent event in the array.
</ParamField>

***

## Example: Abandoned cart templates using Custom Events

This example shows how to personalize abandoned cart messages using Custom Events. It builds on the [Abandoned Cart tutorial](./abandoned-cart).

**Example Custom Event set:**

```json JSON theme={null}
{
  "events": [
    {
      "name": "cart_abandoned",
      "properties": {
        "cart_url": "https://yourdomain.com/username/cart",
        "cart": [
          {
            "product_name": "24 Pack of Acorns",
            "product_image": "https://i.imgur.com/ssPCfbC.png",
            "product_price": "$12.99",
            "product_quantity": "1"
          },
          {
            "product_name": "Fancy Sweater",
            "product_image": "https://i.imgur.com/8QWTfV4.png",
            "product_price": "$9.99",
            "product_quantity": "1"
          }
        ]
      },
      "external_id": "ID_OF_THE_USER"
    }
  ]
}
```

### Email template

This example shows how to build an email template that displays:

* The cart item count
* Each product with image, name, quantity, and price using a for-loop
* A button that links to the customer's unique cart URL

<Frame>
  <img />
</Frame>

<Steps>
  <Step title="Create the email template">
    Navigate to **Messages > Templates > New Email Template** and open the Drag & Drop Editor.
  </Step>

  <Step title="Add the layout structure">
    Create five rows:

    * Rows 1, 2, and 4: one column with a **Paragraph** block
    * Row 3: four columns with **HTML | Paragraph | Paragraph | Paragraph**
    * Row 5: one column with a **Button** block

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Display the item count">
    In row 1, add:

    ```liquid Liquid theme={null}
    We're holding onto {{journey.first_event.properties.cart.size}} items in your cart, but don't wait too long!
    ```

    For better grammar, you could use a conditional to say "1 item" vs "2 items", but for abandoned cart emails, plural is usually acceptable.

    ```liquid Liquid theme={null}
    {% assign cart = message.custom_data.cart %}
    {% assign item_count = cart.size | plus: 0 %}
    {% if item_count == 1 %}
    We're holding onto {{item_count}} item in your cart, but don't wait too long, other squirrels are getting ahead!
    {% endif %}
    {% if item_count > 1 %}
    We're holding onto {{item_count}} items in your cart, but don't wait too long, other squirrels are getting ahead!
    {% endif %}
    ```
  </Step>

  <Step title="Start the for-loop">
    Use a [for-loop](./using-liquid-syntax#for-loops) to repeat the product display row for each cart item.

    In row 2 (loop start), add:

    ```liquid Liquid theme={null}
    {% for product in journey.first_event.properties.cart %}
    ```

    **What this does:**

    * Begins a loop that iterates over each object in the `cart` array
    * Creates a temporary variable `product` representing the current item
    * Everything between `{% for %}` and `{% endfor %}` repeats once per cart item
    * You can name `product` anything (e.g., `item`, `cartItem`)—just stay consistent

    <Warning>
      For-loop placement: Make sure the `{% for %}` syntax is in its own Text block row. Don't put it inside a multi-column row with other content, as this can break email rendering in some clients.
    </Warning>
  </Step>

  <Step title="Display product details">
    This 4-column row shows image, name, quantity, and price. Because it's inside the loop, it repeats for every cart item.

    In row 3 (product details), configure:

    **Column 1 - HTML block** (product image):

    ```html theme={null}
    <img src="{{product.product_image}}" alt="Product image" style="max-width:100%;" />
    ```

    **Columns 2–4 - Text blocks** (product name, quantity, price):

    * Column 2: `{{product.product_name}}`
    * Column 3: `{{product.product_quantity}}`
    * Column 4: `{{product.product_price}}`

    **How the loop works:**

    * On first iteration, `product` = first object in cart array
    * `{{product.product_image}}` gets the first item's image
    * On second iteration, `product` = second object
    * Row repeats automatically for all cart items

    <Warning>
      **Field name matching:** Keys like `product_image` must exactly match your event payload (case-sensitive). Mismatches render as empty strings.
    </Warning>
  </Step>

  <Step title="End the for-loop">
    Close the loop to mark where repetition stops.

    In row 4 (loop end), add:

    ```liquid Liquid theme={null}
    {% endfor %}
    ```

    <Note>
      Every `{% for %}` must have a matching `{% endfor %}`. Missing this will break email rendering.
    </Note>
  </Step>

  <Step title="Add the cart URL button">
    In the row 5 **Button** block, set the Action URL to:

    ```liquid Liquid theme={null}
    {{journey.first_event.properties.cart_url}}
    ```

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Test the template">
    * Add the template to a blank Journey and set the entry rule to a Custom Event.
    * Enabling the Journey and entering yourself into it via the Custom Event API.
    * Verify the data displays correctly.

    <Check>Success! Now you can apply your own styling to the template. See [Design emails with drag-and-drop](./design-emails-with-drag-and-drop).</Check>
  </Step>
</Steps>

### Push template

Push notifications have limited space, so display one item and mention the total count.

**Message field:**

Display item and count with correct grammar using [conditional statements](./using-liquid-syntax#if-elsif-else).

```liquid Liquid theme={null}
{% assign cart = journey.first_event.properties.cart %}
{% assign item_count = cart.size | plus: 0 %}
{% if item_count == 1 %}
You left {{cart.first.product_name}} in your cart.
{% endif %}
{% if item_count == 2 %}
You left {{cart.first.product_name}} and {{item_count | minus: 1}} more item in your cart.
{% endif %}
{% if item_count > 2 %}
You left {{cart.first.product_name}} and {{item_count | minus: 1}} more items in your cart.
{% endif %}
```

**Image field:**

```liquid Liquid theme={null}
{{journey.first_event.properties.cart.first.product_image | default: "https://i.imgur.com/ssPCfbC.png"}}
```

**Launch URL field:**

```liquid Liquid theme={null}
{{journey.first_event.properties.cart_url | default: "https://yourdomain.com/cart"}}
```

Send yourself a test push notification by adding it to the test Journey and entering yourself into it via another Custom Event API call. You should see a notification similar to this appear:

<Frame>
  <img />
</Frame>

<Check>Success! You can now create more templates and use them in the [Abandoned Cart Journey](./abandoned-cart).</Check>

***

## Troubleshooting & best practices

**Common mistakes:**

| Mistake                                     | Why it fails                  | Correct syntax                                 |
| ------------------------------------------- | ----------------------------- | ---------------------------------------------- |
| `{{ journey.first_event.item }}`            | Missing `.properties`         | `{{ journey.first_event.properties.item }}`    |
| `{{ journey.event.purchase.item }}`         | Missing `.properties`         | `{{ journey.event.purchase.properties.item }}` |
| `{{ journey.first_event.properties.Item }}` | Wrong case (should be `item`) | `{{ journey.first_event.properties.item }}`    |
| `{{ event.properties.item }}`               | Missing `journey.` prefix     | `{{ journey.first_event.properties.item }}`    |

**Best practices:**

* Always test templates before going live
* Use [default filters](./using-liquid-syntax#default) for optional properties
* Validate event schema matches template expectations

***

## Related pages

<Columns>
  <Card title="Message personalization" href="./message-personalization" icon="sparkles">
    Overview of all personalization options in OneSignal, including when to use Custom Events vs other methods.
  </Card>

  <Card title="Custom Events" href="./custom-events" icon="bolt">
    Complete guide to implementing and sending Custom Events via SDK or API.
  </Card>

  <Card title="Journeys overview" href="./journeys-overview" icon="route">
    Learn how to build automated messaging workflows with triggers, conditions, and actions.
  </Card>

  <Card title="Journey settings" href="./journeys-settings" icon="gear">
    Configure event-triggered entry rules and Journey behavior.
  </Card>

  <Card title="Wait Until actions" href="./journeys-actions#wait-until" icon="clock">
    Use Wait Until nodes to store additional events during Journey progression.
  </Card>

  <Card title="Using Liquid syntax" href="./using-liquid-syntax" icon="droplet">
    Complete Liquid reference with filters, conditionals, loops, and string manipulation.
  </Card>

  <Card title="Templates" href="./templates" icon="file">
    Create and manage reusable message templates for use in Journeys.
  </Card>
</Columns>

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Personalize with properties
Source: https://documentation.onesignal.com/docs/en/personalization-properties-and-tags

Personalize OneSignal messages using predefined properties and custom Tags. Access user, subscription, journey, message, template, and app-level data with Liquid syntax across email, push, SMS, and webhooks.

Use properties (such as Tags and identifiers like External ID) to personalize messages and delivery payloads with [Liquid syntax](./using-liquid-syntax).

OneSignal renders Liquid placeholders **at send time**, using data already stored on the user, subscription, Journey, message, template, app, or organization. You can use this data to personalize messages, [Journey webhooks](./journeys-webhook), and [Event Streams](./event-streams).

***

## When to use property personalization

Use property personalization to render content at send time using data that already exists in OneSignal—most commonly Tags, External ID, and subscription fields like email or phone number.

This is the right approach when:

* The data is already stored in OneSignal
* You want Liquid placeholders replaced automatically when the message sends
* You don't need to fetch or compute fresh data at delivery time

<Note>
  If the value must be fetched or computed at send time (for example, live pricing or inventory), use [Data Feeds](./data-feeds) or our [API with `custom_data`](./personalization-api-custom-data).

  If the value comes from the event that caused a user to enter or progress through a Journey, use [Custom Event personalization](./personalization-custom-event).
</Note>

### Channel support

Each channel supports specific property types and fields.

<Tabs>
  <Tab title="Email">
    Supports [User & Subscription properties](#user-&-subscription-properties) in:

    * Subject, Reply-to, and Pre-header
    * Message body
    * HTML attributes (for example: `<img src="{{ image_url }}" />`)
    * Button actions (URLs, mailto, etc.)
  </Tab>

  <Tab title="Push">
    Supports [User & Subscription properties](#user-&-subscription-properties) in:

    * Title (`headings`), Subtitle, Body (`contents`)
    * Image URL
    * Launch URL: `https://example.com/{{last_category_viewed}}`

    <Warning>
      The `data` (additional data) field does not support Liquid syntax.
    </Warning>
  </Tab>

  <Tab title="SMS">
    Supports [User & Subscription properties](#user-&-subscription-properties) in:

    * Message body (`contents`)
  </Tab>

  <Tab title="In-app messages">
    Only support Tag substitution. Properties, Custom Events, and other data sources are not available at this time.

    * Tags must be set before the user starts a new app session.
    * Tag substitution may not appear when using test-send flows.

    **Block editor:** Text, Button, and Image blocks\
    **HTML editor:** Text elements and attributes (`src`, `href`, `action`, `data`)
  </Tab>

  <Tab title="Live Activities">
    Supports [User & Subscription properties](#user-&-subscription-properties) in:

    * `event_updates`
    * `contents`
    * `headings`
  </Tab>
</Tabs>

***

## How property personalization works

OneSignal replaces Liquid placeholders with the corresponding property values for the user and subscription being messaged.

```liquid Liquid theme={null}
Hi {{ first_name | default: "friend" }}!
Congrats on reaching level {{ level | default: "1" }}!
```

If a user has tags `first_name: Jon` and `level: 5`, they see:

```liquid Text theme={null}
Hi Jon! 
Congrats on reaching level 5!
```

If a user has no tags set, they see the default values instead.

***

## Property Liquid reference

Use this section to look up the exact object and field names available in Liquid.

### User & Subscription properties

Use `user` for user-level data. Use `subscription` when you need channel-specific values like email address or phone number.

<ParamField>
  The [Tags](./add-user-data-tags) of the User. You can reference the tags in several ways:

  * Use the `key` directly or place the key after `tags`
  * Example tags set: `first_name: Jon, level: 5`

  ```liquid Liquid theme={null}
  Your first name is {{ first_name }}.
  Your first name is {{ user.tags.first_name }}.
  Your level is {{ level }}.
  Your level is {{ user.tags.level }}.
  ```

  * Iterate over tags with for-loop syntax. This example outputs key:value pairs separated by commas.

  ```liquid Liquid theme={null}
  {% for tag in user.tags %}
  {{ tag[0] }}: {{ tag[1] }}
  {% unless forloop.last %}, 
  {% endunless %}{% endfor %}
  ```
</ParamField>

<ParamField>
  The language code of the user.

  ```liquid Liquid theme={null}
  Current language set: {{ user.language }}
  ```
</ParamField>

<ParamField>
  The country code of the user.

  ```liquid Liquid theme={null}
  Current country set: {{ user.country }}
  ```
</ParamField>

<ParamField>
  The [External ID](./users#external-id) of the User.

  ```liquid Liquid theme={null}
  Your user ID is {{ user.external_id }}.
  Your user ID is {{ subscription.external_id }}.
  ```
</ParamField>

<ParamField>
  The [OneSignal ID](./users) of the User.

  ```liquid Liquid theme={null}
  Your OneSignal user ID is {{ user.onesignal_id }}.
  ```
</ParamField>

<ParamField>
  The email address of the email Subscription being messaged.

  ```liquid Liquid theme={null}
  Thanks for subscribing with email {{ subscription.email }}.
  ```
</ParamField>

<ParamField>
  The phone number of the SMS Subscription being messaged.

  ```liquid Liquid theme={null}
  Thanks for subscribing with phone number {{ subscription.phone_number }}.
  ```
</ParamField>

<ParamField>
  The [Subscriptions](./subscriptions) of the User.

  * Iterate over subscriptions with for-loop syntax.
  * This example outputs each subscription's token and ID separated by commas.

  ```json JSON theme={null}
  {
    "subscriptions": "{% for subscription in user.subscriptions %}{% if subscription.subscription_token %}{{ subscription.subscription_token }}: {{ subscription.id }}{% unless forloop.last %}, {% endunless %}{% endif %}{% endfor %}"
  }
  ```
</ParamField>

<ParamField>
  The token used with the [Unsubscribe email with token API](/reference/unsubscribe-with-token).

  ```liquid Liquid theme={null}
  Unsubscribe: https://your-domain.com/unsubscribe?token={{ subscription.unsubscribe_token }}
  ```
</ParamField>

### Journey properties

The `journey` object lets you reference the Journey name or access [Custom Event Personalization](./personalization-custom-event) for the Journey.

<ParamField>
  The name of the Journey.

  ```json JSON theme={null}
  {
    "journey_name": "{{ journey.name }}"
  }
  ```
</ParamField>

### Message properties

The `message` object provides access to the message ID, name, and template ID that can be helpful for [Event Streams](./event-streams) along with access to [custom\_data](./personalization-api-custom-data) for personalizing messages sent from your backend.

<ParamField>
  The ID of the message set by OneSignal.

  ```json JSON theme={null}
  {
    "message_id": "{{ message.id }}"
  }
  ```
</ParamField>

<ParamField>
  The name of the message set by you, the sender.

  ```json JSON theme={null}
  {
    "message_name": "{{ message.name }}"
  }
  ```
</ParamField>

<ParamField>
  The ID of the template set by OneSignal.

  ```json JSON theme={null}
  {
    "template_id": "{{ message.template_id }}"
  }
  ```
</ParamField>

### Template properties

The `template` object provides access to the template ID and name about the [Template](./templates) used to send the message. This can be helpful for [Event Streams](./event-streams).

<ParamField>
  The ID of the template set by OneSignal.

  ```json JSON theme={null}
  {
    "template_id": "{{ template.id }}"
  }
  ```
</ParamField>

<ParamField>
  The name of the template set by you, the sender.

  ```json JSON theme={null}
  {
    "template_name": "{{ template.name }}"
  }
  ```
</ParamField>

***

### App and organization properties

The `app` and `org` objects provide details about the [App and Organization](./apps-organizations) that sent the message. This can be helpful for [Event Streams](./event-streams).

<ParamField>
  The ID of the app set by OneSignal.

  ```json JSON theme={null}
  {
    "app_id": "{{ app.id }}"
  }
  ```
</ParamField>

<ParamField>
  The name of the app set by you, the owner of the app.

  ```json JSON theme={null}
  {
    "app_name": "{{ app.name }}"
  }
  ```
</ParamField>

<ParamField>
  The ID of the Organization set by OneSignal.

  ```json JSON theme={null}
  {
    "org_id": "{{ org.id }}"
  }
  ```
</ParamField>

<ParamField>
  The name of the Organization set by you, the owner of the Organization.

  ```json JSON theme={null}
  {
    "org_name": "{{ org.name }}"
  }
  ```
</ParamField>

***

## Example: Abandoned cart templates using tags

This example shows how to personalize abandoned cart messages using Tags. It builds on the [Abandoned Cart tutorial](./abandoned-cart).

**Example tags set:**

```json JSON theme={null}
{
  "cart_updated": "unix_timestamp_seconds",
  "product_image": "https://i.imgur.com/ssPCfbC.png",
  "product_name": "24 Pack of Acorns",
  "product_quantity": "1",
  "product_price": "$12.99",
  "cart_items_count": "4",
  "cart_url": "https://yourdomain.com/cart"
}
```

### Email template

<Steps>
  <Step title="Create a new email template">
    Navigate to **Messages > Templates > New Email Template** and open the Drag & Drop Editor.
  </Step>

  <Step title="Add the layout structure">
    Create five rows:

    * Rows 1, 2, and 4: one column with a **Paragraph** block
    * Row 3: four columns with **HTML | Paragraph | Paragraph | Paragraph**
    * Row 5: one column with a **Button** block

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Add liquid to paragraph blocks">
    In row 1, add:

    ```liquid Liquid theme={null}
    We're holding onto {{cart_items_count}} items in your cart, but don't wait too long, other squirrels are getting ahead!
    ```

    In row 2, add a description of what the user is looking at:

    ```liquid Text theme={null}
    Currently in your cart:
    ```

    In row 4, add another CTA:

    ```liquid Text theme={null}
    Checkout now while supplies last!
    ```
  </Step>

  <Step title="Display the most recent item">
    In row 3, configure the four columns:

    **Column 1 (HTML block):**

    ```html HTML theme={null}
    <img src="{{product_image}}" alt="Image" style="max-width:100%;" />
    ```

    **Columns 2–4 (Text blocks):**

    * Column 2: `{{product_name}}`
    * Column 3: `{{product_quantity}}`
    * Column 4: `{{product_price}}`
  </Step>

  <Step title="Add the cart URL to the button">
    In the row 5 **Button** block, set the Action URL to:

    ```liquid theme={null}
    {{cart_url}}
    ```

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Test & preview the template">
    Send a test email to yourself using the **Test & preview** button.

    * Make sure the tags are set on your email Subscription.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Style the template">
    <Check>Success! Now you can apply your own styling to the template. See [Design emails with drag-and-drop](./design-emails-with-drag-and-drop).</Check>
  </Step>
</Steps>

### Push template

Push notifications have limited space, so display one item and mention the total count.

**Message field:**

Display item and count with correct grammar using [conditional statements](./using-liquid-syntax#if-elsif-else).

```liquid Liquid theme={null}
{% assign item_count = cart_items_count | plus: 0 %}
{% if item_count == 1 %}
You left {{product_name}} in your cart.
{% endif %}
{% if item_count == 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more item in your cart.
{% endif %}
{% if item_count > 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more items in your cart.
{% endif %}
```

**Image field:**

```liquid Liquid theme={null}
{{product_image | default: "https://i.imgur.com/ssPCfbC.png"}}
```

**Launch URL field:**

```liquid Liquid theme={null}
{{cart_url | default: "https://yourdomain.com/cart"}}
```

<Frame>
  <img />
</Frame>

<Check>Success! You can now create more templates and use them in the [Abandoned Cart Journey](./abandoned-cart).</Check>

***

## Example: Personalize an in-app message with tags

This example shows a reward in-app message personalized with Tags. The IAM substitutes Tag values into multiple block types.

In the configured message:

* **Text block** — displays the completed level and the reward for that level
* **Image block** — displays the image for that reward, with a default image as fallback
* **Button 2 text** — displays the reward value, with a default of `100`
* **Background image** — set from a Tag value

<Frame>
  <img />
</Frame>

The message renders at session start using the user's current Tag values:

<Frame>
  <img />
</Frame>

<Note>
  See the **In-app messages** tab in [Channel support](#channel-support) above for the supported blocks, attributes, and timing rules. Two reminders worth restating from there:

  * **Tags must be set before the user starts a new app session.** Tags updated mid-session don't render in IAMs shown in that session.
  * **Tag substitution doesn't render in "Send Test Message" test-sends.** Trigger the message from a real session to verify substitution.
  * [Property substitution](./using-liquid-syntax#property-include) is not supported in in-app messages.
</Note>

***

## Related pages

<Columns>
  <Card title="Message personalization" href="./message-personalization" icon="sparkles">
    Overview of all personalization options in OneSignal, including when to use Custom Events vs other methods.
  </Card>

  <Card title="Tags" href="./add-user-data-tags" icon="tag">
    Learn how to set tags on users via SDK, API, or CSV import.
  </Card>

  <Card title="Using Liquid syntax" href="./using-liquid-syntax" icon="droplet">
    Complete Liquid reference with filters, conditionals, loops, and string manipulation.
  </Card>

  <Card title="Templates" href="./templates" icon="file">
    Create and manage reusable message templates for use in Journeys.
  </Card>

  <Card title="Abandoned cart tutorial" href="./abandoned-cart" icon="cart-shopping">
    Build an abandoned cart Journey using Tags and Properties.
  </Card>
</Columns>

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Prompt for push permissions
Source: https://documentation.onesignal.com/docs/en/prompt-for-push-permissions

Ask users for push notification permission at the right moment using in-app soft prompts and the native system prompt on iOS and Android.

## Overview

A push permission prompt is the operating system dialog shown when asking users whether your app can send notifications. The user's answer determines whether your app can deliver push notifications that appear as banners, show on the lock screen, and play sounds.

<Frame>
  <img alt="iOS and Android system permission prompts side by side" />
</Frame>

The system permission prompt can only be shown a limited number of times. iOS allows it **once**; Android allows it **twice**. If the user declines all attempts, they must manually enable notifications in system settings — a poorly timed prompt can permanently cost you a subscriber!

Both [Apple](https://developer.apple.com/design/human-interface-guidelines/managing-notifications) and [Google](https://developer.android.com/training/permissions/requesting) recommend explaining the value of your notifications before requesting permission. Without context, users are more likely to decline — and on iOS, a declined prompt cannot be shown again.

### Two ways to trigger the system prompt

You have two options for showing the system permission prompt with the OneSignal SDK. Most apps should start with the in-app message approach.

| Option                             | How it works                                                                                                                                                                                                                                          | When to use                                                                                                                     |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **In-app message (recommended)**   | Configure a OneSignal in-app message — a "soft prompt" — with a **Push Permission Prompt** click action. If the user taps the button, the system prompt appears. If they dismiss the in-app message, nothing is consumed and you can ask again later. | The default choice. Lets you design, schedule, target, and re-show the prompt without a code release.                           |
| **Programmatically from your app** | Call [`requestPermission()`](./mobile-sdk-reference#requestpermission-fallbacktosettings-push) or [`optIn()`](./mobile-sdk-reference#optout-optin-optedin) directly from your code. The system prompt appears immediately.                            | Custom flows where the trigger is owned by your app — preference centers, profile screens, in-app events that warrant a prompt. |

Both options end with the same system prompt; they only differ in what the user sees first. You can also combine them — for example, use a soft prompt at onboarding and a programmatic call from a preference center.

<Frame>
  <img alt="In-app message leading to system push permission prompt" />
</Frame>

<Tip>
  On iOS, you can also use [provisional notifications](./ios-provisional-push-notifications), which deliver quietly to the Notification Center without any prompt — ideal for testing or low-friction onboarding.
</Tip>

This guide covers mobile app push. For web push, see [Web push permission prompts](./permission-requests).

***

## Prerequisites

* A [OneSignal account](https://dashboard.onesignal.com).
* A mobile app with the [OneSignal SDK installed](./mobile-sdk-setup) and the `OneSignalInAppMessages` package enabled.

***

## Set up an in-app push permission prompt

<Steps>
  <Step title="Remove any automatic permission prompts">
    Before you begin, make sure your app isn't already triggering the system permission prompt automatically:

    * Remove any `requestPermission()` or `optIn()` calls invoked on app start.
    * Remove native iOS calls to `requestAuthorizationWithOptions` and any code that generates push tokens directly.
    * Remove Android calls to `requestPermissions` and any code that generates push tokens directly.
  </Step>

  <Step title="Create or edit the in-app message">
    Go to **Messages > In-App**, then either:

    * Edit the default **Push Permission Prompt** template, or
    * Click **New Message** to create your own.

    <Frame>
      <img alt="OneSignal in-app messages list showing the Push Permission Prompt template" />
    </Frame>

    Set the audience to **Show to all users**. OneSignal automatically filters this message to only users who haven't subscribed to push, based on the **Push Permission Prompt** click action.

    <Frame>
      <img alt="Audience setting configured to show to all users" />
    </Frame>
  </Step>

  <Step title="Customize the message design">
    Personalize the look, feel, and wording to fit your app. Tell users what kind of notifications they'll get and why they're valuable.

    See [Design in-app messages with drag and drop](./design-your-in-app-message) or [Design in-app messages with HTML](./design-your-in-app-message-with-html) for details.

    <Frame>
      <img alt="In-app message block editor with a push opt-in prompt" />
    </Frame>
  </Step>

  <Step title="Add the Push Permission Prompt click action">
    Add a **Push Permission Prompt** click action to any button or image in your message. When tapped, the system permission prompt appears.

    <Frame>
      <img alt="Click action dropdown with Push Permission Prompt selected" />
    </Frame>

    <Frame>
      <img alt="iOS native push notification permission prompt" />
    </Frame>

    If the user has already declined the system permission prompt the maximum number of times (once on iOS, twice on Android), the click action instead sends them to your app's notification settings. This is equivalent to calling `requestPermission(fallbackToSettings: true)` from the SDK.

    <Info>
      In-app messages with a **Push Permission Prompt** click action are not shown to users who have already allowed notifications.
    </Info>
  </Step>

  <Step title="Choose a trigger">
    The audience controls *who* is eligible to see the message. Triggers control *when* it appears.

    <Frame>
      <img alt="In-app message trigger configuration panel" />
    </Frame>

    You can trigger the message:

    * On app open.
    * After a set amount of session time.
    * On a specific user event.
    * Programmatically, using the [in-app message trigger SDK methods](./mobile-sdk-reference#addtrigger-addtriggers) for full control over timing and context.

    For example, to wait until the user has spent at least 5 minutes in the app:

    <Frame>
      <img alt="Session duration trigger set to 5 minutes" />
    </Frame>
  </Step>

  <Step title="Schedule and frequency">
    Control how often the message appears:

    * **Only once** — Low chance of converting users who weren't ready the first time.
    * **Every time conditions are met** — Too aggressive and may annoy users.
    * **Multiple times (recommended)** — Set a high max per user (for example, the maximum value of `9999`) with a gap between views (for example, `2 weeks`). This re-prompts unsubscribed users periodically without being intrusive. Adjust the gap based on your use case.

    <Frame>
      <img alt="Schedule configuration showing max displays and gap between views" />
    </Frame>

    <Tip>
      Set the message live, monitor your prompt-to-opt-in conversion in the message report, and adjust the gap between displays as needed.
    </Tip>
  </Step>
</Steps>

***

## Programmatically show the permission prompt

You can trigger the system permission prompt manually using the [`requestPermission()`](./mobile-sdk-reference#requestpermission-fallbacktosettings-push) or [`optIn()`](./mobile-sdk-reference#optout-optin-optedin) SDK methods. This is useful for custom flows such as:

* A [preference center](./preference-center).
* A user profile screen.
* Specific in-app events.

Pass `fallbackToSettings: true` to `requestPermission()` so that users who have already declined are redirected to the app's notification settings instead of silently doing nothing.

<Note>
  If a subscription has been opted out at the SDK level via `optOut()` (shown as `notification_types: -2` on the subscription record), `requestPermission()` alone will not change the subscription status. Use `optIn()` instead — it requests permission **and** clears the opt-out state.
</Note>

***

## Track push permissions and prompt results

* Track which button the user tapped in the soft prompt with the [in-app message click listener](./mobile-sdk-reference#addclicklistener-in-app).
* Track impressions and dismissals (when the user sees but doesn't tap the soft prompt) with the [in-app message lifecycle listener](./mobile-sdk-reference#addlifecyclelistener).
* Track the result of the system permission prompt itself with the [push permission observer](./mobile-sdk-reference#addpermissionobserver-push).

<Info>
  You can forward these SDK events to your backend or analytics tool of choice.
</Info>

***

## FAQ

### What happens if a user denies the system permission prompt?

On iOS, denying the system permission prompt permanently disables push notifications for your app — the prompt cannot be shown again. On Android, the user gets one more chance (two total). After all attempts are used, the user must re-enable notifications manually in **Settings > Notifications** on their device. The [`Push Permission Prompt` click action](#add-the-push-permission-prompt-click-action) and [`requestPermission(fallbackToSettings: true)`](./mobile-sdk-reference#requestpermission-fallbacktosettings-push) both handle this by sending the user directly to their notification settings.

### Can I customize the native system permission prompt?

No. The system permission prompt on iOS and Android is controlled by the operating system and cannot be customized. You can only customize the soft prompt (the in-app message shown before it). Use the soft prompt to explain the value of your notifications, set expectations, and increase the chance of an "Allow" on the system prompt.

### Can I still prompt users who have provisional notifications?

Yes. If you use [iOS provisional push notifications](./ios-provisional-push-notifications), you can still show a soft prompt to convert those users to full push subscribers. Time the prompt for a moment when the user has just seen value from a provisional notification — for example, right after they open a notification or act on it.

### How do I re-prompt users who previously denied push?

Once the system permission prompt has been exhausted (once on iOS, twice on Android), you cannot show it again. Instead, use the [`requestPermission(fallbackToSettings: true)`](./mobile-sdk-reference#requestpermission-fallbacktosettings-push) SDK method or the **Push Permission Prompt** click action on an in-app message — both open your app's notification settings so the user can enable notifications manually. Pair this with an in-app message explaining why notifications are valuable.

### Do all Android versions require a system permission prompt?

No — only Android 13 (API level 33) and later. Android 13 introduced the runtime notification permission, requiring explicit user consent for push notifications.

* **Released:** August 2022 (Pixel devices).
* **Required for target SDK:** As of August 31, 2023, all new apps and updates on Google Play must target API level 33 or higher.
* **Source:** [Google's developer guide on notification permissions](https://developer.android.com/develop/ui/views/notifications/notification-permission).

On Android 12 and lower, the app is granted notification permission automatically on install.

***

<Columns>
  <Card title="iOS provisional push notifications" icon="apple" href="./ios-provisional-push-notifications">
    Send notifications to the Notification Center without an upfront permission prompt on iOS 12+.
  </Card>

  <Card title="Mobile SDK reference" icon="code" href="./mobile-sdk-reference#requestpermission-fallbacktosettings-push">
    `requestPermission`, `optIn`, permission observer, and in-app click listener APIs.
  </Card>

  <Card title="Web push permission prompts" icon="globe" href="./permission-requests">
    Configure soft-prompt, slide-down, and native web push permission requests.
  </Card>

  <Card title="In-app messages setup" icon="message" href="./in-app-messages-setup">
    Enable in-app messaging in your app so you can run soft prompts.
  </Card>
</Columns>


# Push overview
Source: https://documentation.onesignal.com/docs/en/push

Send and manage mobile and web push notifications with OneSignal using the dashboard or API, with targeting, personalization, and scheduling.

Push notifications re-engage Users with timely, personalized content across devices — even when they're not actively using your app or website.

Watch how push notifications drive the highest engagement, or skip ahead to get started.

<Frame>
  <iframe title="YouTube video player" />
</Frame>

OneSignal provides a complete platform to manage push notifications across mobile, web, and desktop:

* **Send campaigns and transactional messages** from the [dashboard](#send-push-notifications) or [API](/reference/create-message)
* **Automate multi-channel flows** with [Journeys](./journeys-overview)
* **Target Users precisely** using [Segments](./segmentation), filters, or User data
* **[A/B test](./ab-testing) and optimize** message performance
* **Personalize content** with User attributes and [dynamic content](./message-personalization)
* **Integrate with your stack** — HubSpot, Mixpanel, Amplitude, Zapier, and [more](./integrations)

***

## Push setup

Before sending push notifications, complete the platform setup, configure permission prompts, and enable the features you need.

### Platform setup guides

<Columns>
  <Card title="Mobile push setup" icon="mobile" href="./mobile-push-setup">
    End-to-end setup for iOS, Android, Huawei, and Amazon push notifications.
  </Card>

  <Card title="Web push setup" icon="globe" href="./web-push-setup">
    Enable push for Chrome, Firefox, Safari, and Edge.
  </Card>

  <Card title="Mobile SDK setup" icon="code" href="./mobile-sdk-setup">
    Integrate the OneSignal SDK into your mobile app.
  </Card>

  <Card title="Web SDK setup" icon="browsers" href="./web-sdk-setup">
    Integrate the OneSignal SDK into your website.
  </Card>

  <Card title="Migrating to OneSignal" icon="arrow-right-arrow-left" href="./migrating-to-onesignal">
    Migration steps from Firebase, Airship, Braze, and other providers.
  </Card>

  <Card title="macOS app support" icon="desktop" href="./macos-app-setup">
    Configure OneSignal for macOS apps.
  </Card>

  <Card title="Windows app support" icon="desktop" href="./windows-app-setup">
    Configure OneSignal for Windows desktop apps.
  </Card>

  <Card title="watchOS and Wear OS support" icon="clock" href="./watchos-and-wear-os-support">
    Add OneSignal to Apple Watch and Wear OS devices.
  </Card>
</Columns>

### Permissions

A well-designed opt-in experience maximizes your push audience.

<Columns>
  <Card title="Mobile push prompts" icon="bell" href="./prompt-for-push-permissions">
    Build pre-permission prompts and best practices for mobile apps.
  </Card>

  <Card title="Web push prompts" icon="bell-on" href="./permission-requests">
    Customize prompt timing and messaging for web push.
  </Card>

  <Card title="iOS provisional push" icon="apple" href="./ios-provisional-push-notifications">
    Deliver silent notifications to the notification center before prompting for full permission.
  </Card>

  <Card title="Android notification categories" icon="android" href="./android-notification-categories">
    Let Android Users customize how they receive notifications from your app.
  </Card>
</Columns>

### Features and advanced use cases

<Columns>
  <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
    Add dynamic content to personalize messages for each User.
  </Card>

  <Card title="Multi-language messaging" icon="language" href="./multi-language-messaging">
    Send push notifications in each User's preferred language.
  </Card>

  <Card title="Throttling" icon="gauge-high" href="./throttling">
    Control notification delivery speed for large audiences.
  </Card>

  <Card title="Frequency capping" icon="hand" href="./frequency-capping">
    Limit the number of push notifications per User.
  </Card>

  <Card title="Data and background notifications" icon="database" href="./data-notifications">
    Send data-only notifications for background tasks.
  </Card>

  <Card title="VoIP notifications" icon="phone" href="./voip-notifications">
    Send VoIP-specific push notifications for calling apps.
  </Card>
</Columns>

***

## Send push notifications

You can send messages in several ways. The best option depends on your use cases.

<Columns>
  <Card title="Dashboard" icon="window-maximize" href="#send-from-the-dashboard">
    Compose a message quickly within the dashboard.
  </Card>

  <Card title="Send via API" icon="code" href="/reference/create-message">
    Send messages programmatically using the REST API.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build automated, multi-step, and multi-channel flows.
  </Card>

  <Card title="A/B testing" icon="flask" href="./ab-testing">
    Test up to 10 message variants to optimize performance.
  </Card>
</Columns>

### Send from the dashboard

<Steps>
  <Step title="Select the message channel" icon="window-maximize">
    Select **Create...** then choose your message channel. You can also navigate to **Messages** or **Templates** to view previous messages.

    <Frame>
      <img alt="OneSignal dashboard showing create message options" />
    </Frame>
  </Step>

  <Step title="Choose a composition method" icon="pencil">
    * Start from scratch or use the [AI message composer](./ai-message-composer).
    * Use a pre-built [template](./templates)
  </Step>

  <Step title="Set a name and label" icon="tag">
    Add internal metadata for tracking and reporting. API equivalent: `name`
  </Step>

  <Step title="Select your audience" icon="users">
    Choose which users receive the message. You can include and exclude [segments](./segmentation) to target specific groups. Defaults to all "Subscribed Users" if no segment is set.

    <Frame>
      <img alt="Dashboard fields for message name, label, and audience segment selection" />
    </Frame>

    | Targeting method                                    | Dashboard | API |
    | --------------------------------------------------- | :-------: | :-: |
    | [**Segments**](./segmentation)                      |    Yes    | Yes |
    | **Filters** ([API only](/reference/create-message)) |     No    | Yes |
    | **Aliases** ([API only](/reference/create-message)) |     No    | Yes |
  </Step>
</Steps>

### Delivery schedule and optimization

See how timing impacts push notification performance.

<Frame>
  <iframe title="YouTube video player" />
</Frame>

Choose when the message should "start sending" to the audience. This is the moment when OneSignal evaluates audience membership.

| Option               | Description                                        | API field    |
| -------------------- | -------------------------------------------------- | ------------ |
| **Send immediately** | Start sending to all users in the audience now.    | —            |
| **Scheduled**        | Send at a specific time, up to 30 days in advance. | `send_after` |

<Warning>
  The "start sending" time determines the audience cutoff. OneSignal evaluates audience membership at that moment; anyone in the audience receives the message, regardless of per-user optimization settings.
</Warning>

**Per-user optimization:**

Set when users should receive the message.

| Option                                                | Description                                                              | API field                                          |
| ----------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------- |
| **Everyone at the same time**                         | All recipients receive the email at once. Best for urgent messages.      | —                                                  |
| **Intelligent Delivery**                              | Sends at the optimal time for each user based on their session activity. | `delayed_option: last-active`                      |
| **Custom time per timezone**                          | Sends at a set local time in each user's timezone.                       | `delayed_option: timezone`, `delivery_time_of_day` |
| **Override [Throttling](./throttling)**               | Change the throttle rate.                                                | `throttle_rate_per_minute`                         |
| **Override [Frequency capping](./frequency-capping)** | Disable frequency capping for this message.                              | `enable_frequency_cap`                             |

<Info>
  With Intelligent Delivery or Custom time per timezone, delivery spans a 24 hour period so every record in the audience can receive the message. If it is already 10am for a recipient when a 9am-local message sends, they receive it at 9am the following day.
</Info>

### Design properties

Push messages can either display User-facing content or perform background operations.

* **Display notifications**: Require a [message](#message) and may include a title, image, action buttons, and other visual elements.
* **Background/data-only notifications**: Omit the message, include [content\_available](./data-notifications), and optionally [additional data](#additional-data).

<Frame>
  <img alt="Annotated diagram showing the anatomy of web and mobile push notifications" />
</Frame>

<Tip>
  Use the [AI message composer](./ai-message-composer) to quickly generate notification titles and body text. Adjust tone and content to match your brand in a few clicks.
</Tip>

#### Title

Top-most customizable text of the notification. Text appearance is controlled by the operating system.

* Required for **web push** and **Huawei**
* Defaults to site name on web if not set
* Recommended limit: 25–50 characters (mobile), 60–80 (web)
* Supports: [AI message composer](./ai-message-composer), emojis, [message personalization](./message-personalization), [multi-language messaging](./multi-language-messaging)
* API: `headings`

#### Subtitle

Secondary text supported on iOS and macOS only (via APNs). Not available on Android or web.

* Recommended limit: 25–50 characters
* Supports: emojis, [message personalization](./message-personalization), [multi-language messaging](./multi-language-messaging)
* API: `subtitle`

#### Message

Main content of the notification. Does not support custom fonts or styling. Style is set by the operating system.

* Required unless sending a background notification
* Supports: [AI message composer](./ai-message-composer), emojis, [message personalization](./message-personalization), [multi-language messaging](./multi-language-messaging)
* Recommended limit: \~150 characters
* API: `contents`

#### Icons

Customize small and large icons on Android and web. iOS always uses the app icon.

* See [Notification icons](./notification-icons)

#### Image

Add a large image to notifications on Android, iOS, and Chrome for Windows/Android.

* Recommended size: `1024×512px` (2:1 aspect ratio)
* Max size: 1 MB, max width: 2000 px
* Not supported on Safari (macOS/iOS) or macOS Notification Center
* Must be tapped or expanded on mobile to view
* Supported formats: `PNG`, `JPG`, `GIF` (animated only on iOS)
* API: `ios_attachments` (iOS), `big_picture` (Android), `chrome_web_image` (Chrome web)
* See [Images and rich media](./rich-media)

#### App name

The name of the app displaying the notification.

* **iOS**: Set in Xcode under *Display Name*; requires device restart to update
* **Android/Amazon/Huawei**: Set in `AndroidManifest.xml` under `<application android:label="YOUR APP NAME">`
* **Web**: Shows the site name and/or browser

### Feature properties

#### Action buttons

Add interactive buttons to the push notification.

* Supported on Android 4.1+ and iOS 8.0+
* See [Action buttons](./action-buttons)

#### Launch URL

Control where Users go when tapping the notification.

* API: `url` (single universal URL), `app_url` (deep link, e.g. `your-app://screen`), `web_url` (http/https web link)
* See [URLs, links, and deep links](./links)

#### Badges

Show dots or badge numbers on app icons.

* **iOS**: Red numeric badge; can set, increment, or clear. API: `ios_badgeType`, `ios_badgeCount`
* **Android**: Requires [notification categories](./android-notification-categories)
* **Huawei**: Badge displayed as a number or dot. API: `huawei_badge_class`, `huawei_badge_set_num`, `huawei_badge_add_num`
* **Web (Chrome/Android)**: Icon shown in Android status bar; must be a 72×72 alpha PNG. API: `chrome_web_badge`
* See [Badges](./badges)

#### Sound

Play a sound when the push is delivered.

* **iOS**: Set with `sound`
* **Android**: Set via [notification categories](./android-notification-categories)
* **Web**: Not available

#### Additional data

Add custom key-value pairs to the payload for SDK handling.

* Used by [mobile service extensions](./service-extensions) and click listeners in the [mobile SDK](./mobile-sdk-reference) and [web SDK](./web-sdk-reference)
* Dashboard supports only simple key-value data; use the API with `data` to send nested JSON
* Max total payload: \~4 KB; `data` field: up to 2048 bytes
* See [Notification payload reference](./osnotification-payload)

#### Collapse ID (mobile push)

Replace earlier notifications with a newer one if they share the same `collapse_id`. Max length: 64 characters. API: `collapse_id`

For example, a weather app sends three alerts. If the User opens their device after all three, only the last message displays.

#### Web push topic (web push)

Avoid replacing older web notifications by using unique `web_push_topic` values. Notifications with different topics remain visible independently. Max length: 64 characters. API: `web_push_topic`

#### Priority

Set the urgency of the push, especially in battery-saving modes.

* **High** (recommended): Immediate, alert-based messages
* **Normal**: Used for background/data notifications
* API: `priority`
* Platform docs: [APNs priority](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns), [FCM priority](https://firebase.google.com/docs/cloud-messaging/android/message-priority)

#### Time to live (TTL)

How long to keep a message if the device is offline. Default: 3 days. Range: 0–2,419,200 seconds (28 days). API: `ttl`

If a User is offline and the TTL expires, the message is discarded. Set `ttl: 0` for messages that should never be delivered late.

<Note>
  **iOS limitation**: APNs stores only the most recent notification while the device is offline. Earlier notifications are dropped. [Learn more](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html#//apple_ref/doc/uid/TP40008194-CH8-SW5).
</Note>

#### Notification grouping

Android and iOS automatically group notifications after a device receives 4 or more from your app.

* **iOS**: Use `thread_id` in the API to group messages together.
* **Android**: Use `android_group` in the API, or set the "Group Key" in the dashboard. For advanced customization, see [Android NotificationExtenderService](./service-extensions#android-notification-extender-service) and [Android's group notify guide](https://developer.android.com/training/notify-user/group).

<Frame>
  <img alt="Android device showing grouped push notifications from the same app" />
</Frame>

***

## Cancel push notifications

Cancel a message if it has not been **Delivered** yet. OneSignal stops sending the message to all Subscriptions not already in the queue. This does not remove the message from devices that already received it.

In the [Message Report](./push-notification-message-reports), select **Actions > Cancel**, or use the [Cancel Message API](/reference/cancel-message).

### Remove a push notification from a device

Once delivered, you can only replace a push notification if you set a [Collapse ID](#collapse-id-mobile-push) or [Web push topic](#web-push-topic-web-push). Without one of these, the notification cannot be replaced or removed.

***

## Analytics

Track message performance and engagement.

<Columns>
  <Card title="Push message reports" icon="chart-line" href="./push-notification-message-reports">
    Message-level delivery, open rate, and click-through reporting.
  </Card>

  <Card title="Analytics overview" icon="chart-bar" href="./analytics-overview">
    All analytics options available in OneSignal.
  </Card>

  <Card title="Event Streams" icon="signal-stream" href="./event-streams">
    Stream push events to your data warehouse or BI tools in real time.
  </Card>

  <Card title="View messages API" icon="code" href="/reference/view-messages">
    Pull message analytics programmatically via the REST API.
  </Card>
</Columns>

***

## FAQ

### What platforms does OneSignal push support?

OneSignal supports push on iOS (APNs), Android (FCM), Huawei (HMS), Amazon (ADM), web browsers (Chrome, Firefox, Safari, Edge), macOS, and Windows. See the [platform setup guides](#platform-setup-guides) above.

### How do I test push notifications before sending to Users?

Set up [Test Users](./test-users) to verify delivery, rendering, and deep links without affecting real Users. You can also send to a single-user segment for quick testing.

### Why are my push notifications not showing?

Common causes include missing or expired platform credentials, Users not granting permission, or device-level settings like Do Not Disturb. See [Notifications not shown or delayed](./notifications-show-successful-but-are-not-being-shown) for a full troubleshooting checklist.

### What is the maximum push notification payload size?

The total payload size is approximately 4 KB across all platforms. The `data` field supports up to 2048 bytes. Exceeding these limits may cause notifications to be truncated or rejected.


# Push message reports
Source: https://documentation.onesignal.com/docs/en/push-notification-message-reports

Push message reports show delivery outcomes, confirmed receipt, failure diagnostics, click-through rates, and per-subscription audience activity for each push send.

Push message reports help you track the performance of individual push message sends, including delivery outcomes, user engagement (CTR), device-level confirmations, and error diagnostics.

<Frame>
  <img alt="Push message report showing delivered, clicked, and CTR metrics" />
</Frame>

***

## Delivery metrics

OneSignal sends push notifications to **push services** (Google FCM, Apple APNs, Huawei HMS) which deliver them to your users' devices (Subscriptions). The Delivered, Unsubscribed, and Failed metrics come from these push services. The [Confirmed receipt](./confirmed-delivery) and Clicked metrics come from the OneSignal SDK on the device.

| Metric                | Definition                                                                                                                                                                                                                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Sent**              | The number of push notifications sent from OneSignal, including both those successfully sent to the push provider and failures. This is a composite metric.                                                                                                                                            |
| **Audience**          | The number of Subscriptions in the targeted Segment(s).                                                                                                                                                                                                                                                |
| **Remaining**         | The number of Subscriptions in the target audience that haven't yet received the push notification (queued or in flight). Appears on the dashboard delivery report.                                                                                                                                    |
| **Delivered**         | The number of push notifications successfully sent to and accepted by the push provider (FCM, APNs, HMS).                                                                                                                                                                                              |
| **Confirmed Receipt** | The number of push notifications confirmed as received by the device, verified by the OneSignal SDK. See [Confirmed receipt](/docs/en/confirmed-delivery) for platform-specific details and requirements.                                                                                              |
| **Unsubscribed**      | The number of push Subscriptions that did not receive the push notification because they uninstalled the app, cleared browser data, or opted out of push and have not opened the app since. OneSignal will **not** attempt to send to these Subscriptions in future messages unless they re-subscribe. |
| **Failed**            | The number of push Subscriptions that did not receive the push notification because of an error. OneSignal will attempt to send to these Subscriptions in future messages.                                                                                                                             |
| **Clicked**           | The number of push Subscriptions that clicked the push notification. Push notifications can only be clicked once.                                                                                                                                                                                      |
| **Frequency Capped**  | The number of push Subscriptions that did not receive the push notification due to frequency cap settings.                                                                                                                                                                                             |

The following metrics are specific to push message reports:

| Metric                 | Definition                                                                                                                                                             |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Confirmed Receipt**  | The number of push Subscriptions that confirmed receiving the message.                                                                                                 |
| **Remaining**          | The number of notifications still queued on the OneSignal side for sending.                                                                                            |
| **Click-Through Rate** | Calculated as `(Clicks / Delivered) * 100%`.                                                                                                                           |
| **Confirmed CTR**      | Calculated as `(Clicks / Confirmed Delivered) * 100%`.                                                                                                                 |
| **Influenced Opens**   | The number of app opens that occurred after receiving the notification, without clicking. Based on time window set in **Settings > Push & In-App > Influenced Opens**. |

<Note>
  For detailed metric definitions across all channels, see the [Metrics Glossary](./analytics-metrics-glossary).
</Note>

### Failure message troubleshooting

These errors prevented OneSignal from delivering the message to the push provider:

| Error                                                                                                                                                                  | Type | Troubleshooting Steps                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **401 Unauthorized**                                                                                                                                                   | Web  | Web push server gave an unclear 401 error. Retry cautiously — it may cause duplicate sends.                                                                                       |
| **404 Not Found**                                                                                                                                                      | Web  | Invalid push subscription endpoint (bad token).                                                                                                                                   |
| **Authentication Error**                                                                                                                                               | FCM  | Check your [FCM credentials](./android-firebase-credentials), re-upload the service account file, and try again.                                                                  |
| **[DeviceTokenNotForTopic](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html)** | APNs | Token’s Bundle ID does not match your APNs key or certificate. Fix in [p8 token](./ios-p8-token-based-connection-to-apns) or [p12 setup](./ios-p12-generate-certificates).        |
| **Expired Certificate**                                                                                                                                                | APNs | Your p12 certificate has expired. See [certificate setup](./ios-p12-generate-certificates).                                                                                       |
| **FcmV1InvalidToken / Not Found**                                                                                                                                      | FCM  | Invalid push token. Check [Firebase credentials](./android-firebase-credentials). Devices must reopen app to refresh tokens.                                                      |
| **None / Missing**                                                                                                                                                     | FCM  | Firebase Cloud Messaging API may not be enabled in your project. Activate in the Firebase Console and retry.                                                                      |
| **Permission Denied**                                                                                                                                                  | FCM  | Check the full error message for which permission is missing. [Update the permission for the Service Account file](./android-firebase-credentials) and re-upload it to OneSignal. |
| **SenderIdMismatch**                                                                                                                                                   | FCM  | FCM v1 Sender ID mismatch. Verify [Firebase credentials](./android-firebase-credentials). Users must reopen the app for updated tokens.                                           |
| **[TopicDisallowed](https://developer.apple.com/documentation/usernotifications/handling-notification-responses-from-apns)**                                           | APNs | APNs token mismatch. Check your Team ID, Key ID, and Bundle ID in [p8 config](./ios-p8-token-based-connection-to-apns).                                                           |

***

## Delivery status

| Status            | Description                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| **Delivered**     | Push service has reported delivery of the message to recipients.                                  |
| **Scheduled**     | Message is scheduled for future delivery.                                                         |
| **Sending**       | Message is actively being sent.                                                                   |
| **Queued**        | Message is waiting to be sent.                                                                    |
| **Canceled**      | Message was manually canceled. See [Cancel push notifications](./push#cancel-push-notifications). |
| **No Recipients** | No valid audience at send time (e.g. unsubscribed or out of segment).                             |
| **Failed**        | OneSignal could not send the message due to errors.                                               |

***

## Conversions

<Info>
  **Coming soon** — [Conversion metrics](/docs/en/conversion-metrics) will be available on message reports. Once available, you will see attributed and influenced conversions for each message directly in its report. See [Conversion metrics](/docs/en/conversion-metrics) for details on the attribution model and setup instructions.
</Info>

## Message statistics

The message statistics graph tracks clicks, sessions, and [custom outcomes](./custom-outcomes) (legacy, being replaced by Conversion metrics) over the 30 days following a send. Use it to see whether engagement occurred immediately after delivery or continued over time.

<Frame>
  <img alt="Message statistics graph showing clicks, sessions, and custom outcomes over a 30-day period" />
</Frame>

<Warning>
  Messages sent via the OneSignal API are only retained for 30 days. Use [Template Analytics](./template-analytics) to track performance over time, or [export your data](./exporting-data) for offline analysis.
</Warning>

***

## Audience activity

The **Audience activity** report shows how each Subscription interacted with a specific message. Results are grouped into categories so you can diagnose delivery issues, measure engagement, identify unsubscribes tied to a specific message, and segment audiences for retargeting or export.

<Frame>
  <img alt="Audience activity screenshot" />
</Frame>

<Tabs>
  <Tab title="Categories">
    | Category                    | Description                                                                                                                                                                                                                                                                                                                    |
    | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **Sent**                    | Message was sent to the device.                                                                                                                                                                                                                                                                                                |
    | **Confirmed Receipt**       | Delivery was confirmed by the device.                                                                                                                                                                                                                                                                                          |
    | **Did Not Confirm Receipt** | Delivery confirmation was not received.                                                                                                                                                                                                                                                                                        |
    | **Clicked**                 | User clicked the notification.                                                                                                                                                                                                                                                                                                 |
    | **Did Not Click**           | User did not click the notification.                                                                                                                                                                                                                                                                                           |
    | **Failed**                  | Delivery failed.                                                                                                                                                                                                                                                                                                               |
    | **Unsubscribed**            | The number of push Subscriptions that did not receive the message because they uninstalled the app, cleared browser data, or opted out of push and have not opened the app since. We will not attempt to send to these Subscriptions in future messages unless the user resubscribes to push notifications on the same device. |

    Each tab displays the number of recipients in that category and lets you drill into the individual subscription records.
  </Tab>

  <Tab title="Table columns">
    | Column                  | Description                                                                                                                                                                    |
    | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **External ID**         | Your system identifier (if set).                                                                                                                                               |
    | **OneSignal ID**        | Unique OneSignal user ID.                                                                                                                                                      |
    | **Subscription ID**     | Unique subscription instance (device + app/browser).                                                                                                                           |
    | **Device**              | Browser or OS type. If you see `()`, the device has been deleted.                                                                                                              |
    | **Subscription Status** | Current status (for example, Subscribed, Unsubscribed).                                                                                                                        |
    | **Sent**                | Time the message was sent.                                                                                                                                                     |
    | **Confirmed Receipt**   | Time delivery was confirmed by the device, or `-` if not.                                                                                                                      |
    | **Clicked**             | Timestamp if the user clicked, or `-` if not.                                                                                                                                  |
    | **Failed**              | Indicates if delivery failed.                                                                                                                                                  |
    | **Unsubscribed**        | Indicates the push Subscription did not receive the message because the user uninstalled the app, cleared browser data, or opted out of push and has not opened the app since. |
    | **Failure message**     | Error message if delivery failed (for example, "Invalid token").                                                                                                               |
  </Tab>
</Tabs>

<Warning>
  Audience activity data is only available for **30 days** from the time the message is sent. Export results if you need to retain them longer.
</Warning>

### Retargeting audiences

From the **Audience activity** view, you can send a **Retargeted Message** directly to any category (for example, all users who did not click).

This makes it easy to follow up with users who didn't engage, re-engage those who churned, or reinforce success with users who confirmed receipt.

***

### Exporting results

You can download audience data with the **Export** menu:

* **Selected activity** – exports only the currently viewed tab (for example, all users who failed delivery).
* **All activities** – exports the full report across every category.

Exports let you analyze results offline, share with other teams, or merge with your CRM and analytics tools.

<Card title="Exporting data" icon="file-export" href="./exporting-data">
  Export message and user data to CSV for offline analysis.
</Card>

***

## Message settings

The message settings panel displays the configuration used for the send.

* **Audience** - Details of the audience including:
  * Total number of recipients - How many Subscriptions were sent the message
  * How the message was sent: Targeting filters or segments used
* **Schedule** - When the message started sending and per-user delivery options selected, if any.
* **Throttling** - Any throttling, frequency caps, or channel overrides
* **Message** - The message content.
  * Platforms targeted (Android, iOS, specific browsers)
* **Advanced Settings** - Like Priority, Time to live, and Collapse ID.
* **Additional Data** - Any custom data added to the message.

***

## FAQ

### When do push subscription statuses update?

Push subscription statuses update through two mechanisms:

**1. When the user opens your app or site**

The OneSignal SDK checks whether the push token is valid and whether notification permissions are still granted, then updates the subscription status immediately.

For example, if a user disables push notifications in their device settings and then reopens your app, the SDK detects the change and marks the subscription as **Unsubscribed** right away.

You can capture these changes with the SDK's Subscription Observer ([mobile](./mobile-sdk-reference#addobserver-push-subscription-changes) | [web](./web-sdk-reference#addeventlistener-push-subscription-changes)) to sync status to your own database.

**2. When you send push notifications**

If a user uninstalls your app, clears browser data, or disables push **and never returns**, OneSignal cannot detect the change until you send a notification. The push service (FCM, APNs, HMS) reports the token as invalid, and OneSignal marks the subscription as **Unsubscribed**.

This detection typically takes 2 or more messages because the push service does not immediately reject an invalid token:

| Send       | What happens                                                                                                                                                |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Message 1  | Delivered to device. User then unsubscribes in device settings or uninstalls the app.                                                                       |
| Message 2  | Push service accepts the message but the device does not receive it. OneSignal reports "Delivered" because the push service has not rejected the token yet. |
| Message 3  | Push service rejects the token. OneSignal marks the subscription as **Unsubscribed**.                                                                       |
| Message 4+ | OneSignal does not attempt delivery to this subscription.                                                                                                   |

Use [Event Streams](./event-streams) to detect unsubscribes in real time when sending messages.

<Warning>
  If you go long periods without sending to all users, unsubscribes accumulate silently and appear as a large spike when you resume sending. Send to all users at least once or twice a month to detect unsubscribes gradually. See [FCM expired token FAQ](./fcm-expired-token-faq) for more on unsubscribe spikes.

  Apple delays unsubscribe reporting by 14+ days. To protect user privacy, Apple does not immediately report uninstalls or permission revocations. If a user opens your app after disabling push, OneSignal detects the change instantly via the SDK. If the user never opens the app again, it may take several weeks for Apple to report the invalid token. See [Apple Forum](https://developer.apple.com/forums/thread/670868) and [Technical Note](https://developer.apple.com/library/archive/technotes/tn2265/_index.html#//apple_ref/doc/uid/DTS40010376-CH1-TNTAG34) for details.

  Use the dashboard or API to [delete old subscriptions](./delete-users) to keep your audience clean.
</Warning>

### Why don't my Delivered numbers match Confirmed Receipt?

Delivered reflects what the push service (FCM, APNs) reported — it accepted the message for delivery. Confirmed Receipt requires the OneSignal SDK on the device to report back, which only happens if the device is online and the app processes the notification. Devices that are offline, have the app force-closed, or lack the SDK will show as Delivered but not Confirmed.

### How long is audience activity data available?

Audience activity data is retained for 30 days from the time the message is sent. Export your results before this window closes if you need to keep them longer.

***

## Related pages

<Columns>
  <Card title="Confirmed receipt" icon="check-double" href="./confirmed-delivery">
    How device-level delivery confirmation works and what affects confirmation rates.
  </Card>

  <Card title="Metrics Glossary" icon="book" href="./analytics-metrics-glossary">
    Definitions for all delivery, engagement, and conversion metrics across channels.
  </Card>

  <Card title="Template Analytics" icon="chart-line" href="./template-analytics">
    Track push notification performance across sends using templates.
  </Card>

  <Card title="Push throttling" icon="gauge" href="./throttling">
    Control delivery rate to manage server load during high-volume sends.
  </Card>
</Columns>


# Getting started with OneSignal
Source: https://documentation.onesignal.com/docs/en/quickstart-guide

Set up your OneSignal account, configure push, in-app messages, email, and SMS/RCS, organize Users with tags and segments, and send your first message or Journey.

This guide walks through getting up and running with OneSignal. If you haven't already, [create your account](https://onesignal.com) to get started.

1. [**Set up your account and messaging channels**](#set-up-your-account-and-messaging-channels) — create your app and configure at least one channel.
2. [**Add and organize your Users**](#add-and-organize-your-users) — model Users, Subscriptions, tags, and segments.
3. [**Send messages**](#send-messages) — compose campaigns, personalize content, and build automated Journeys.
4. [**Measure impact with analytics**](#measure-impact-with-analytics) — track delivery, engagement, and conversions.

Prefer video? Watch the walkthrough below.

<Frame>
  <iframe title="OneSignal quickstart video walkthrough" />
</Frame>

## Which channel should I start with?

Pick the channel that matches your immediate goal — you can add more to the same OneSignal App at any time.

| Your goal                                          | Start with                                                                     | Why                                                                   |
| :------------------------------------------------- | :----------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| Send transactional or marketing email today        | [Email](./email-setup)                                                         | No SDK required. Configure DNS and start sending the same day.        |
| Reach a mobile app's existing user base            | [Mobile push](./mobile-sdk-setup) + [in-app messages](./in-app-messages-setup) | Mobile SDKs cover both channels with one integration.                 |
| Engage website visitors                            | [Web push](./web-sdk-setup)                                                    | No app build needed; works in modern browsers.                        |
| Send time-sensitive alerts (OTPs, shipping)        | [SMS](./sms-messaging)                                                         | Fastest channel for high-priority transactional messages.             |
| Send rich, branded text messages                   | [RCS](./rcs-messaging)                                                         | Branded sender, read receipts, and rich media for Android recipients. |
| Stream live event data (sports, deliveries, rides) | [Live Activities](./live-activities)                                           | Ongoing iOS Lock Screen and Dynamic Island updates.                   |

## Set up your account and messaging channels

Your OneSignal App is where user and messaging data is stored. You can have multiple Apps in a single Organization for different projects, environments, or billing needs.

### Account and workspace setup

<Columns>
  <Card title="Apps, Organizations, and accounts" icon="building" href="./apps-organizations">
    Your OneSignal App, Organization structure, and account settings.
  </Card>

  <Card title="Add team members" icon="user-plus" href="./manage-team-members">
    Invite collaborators and assign roles within your Organization.
  </Card>

  <Card title="Keys and IDs" icon="key" href="./keys-and-ids">
    Find your OneSignal App ID, Organization ID, and API keys.
  </Card>

  <Card title="Usage and billing" icon="credit-card" href="./billing-faq">
    Billing, invoices, and usage details.
  </Card>
</Columns>

### Messaging channels

OneSignal supports push notifications, in-app messages, email, SMS/MMS/RCS, and more! Choose your first channel and follow its setup guide — you can add more channels to the same app at any time.

<Note>
  Email and SMS can be configured without writing code. Push notifications and in-app messages require SDK integration — [invite a developer](./manage-team-members) to your team if needed.
</Note>

<Frame>
  <img alt="OneSignal dashboard showing messaging channel setup options including push, email, SMS, and in-app" />
</Frame>

<Columns>
  <Card title="Email" icon="envelope" href="./email-setup">
    Transactional and marketing email configuration.
  </Card>

  <Card title="Mobile push" icon="mobile" href="./mobile-sdk-setup">
    iOS, Android, Huawei, and Amazon push setup.
  </Card>

  <Card title="Web push" icon="globe" href="./web-sdk-setup">
    Browser-based push notification setup.
  </Card>

  <Card title="In-app messages" icon="window-maximize" href="./in-app-messages-setup">
    Rich, interactive messages displayed within your app.
  </Card>

  <Card title="SMS" icon="comment-sms" href="./sms-messaging">
    Text messaging for time-sensitive alerts.
  </Card>

  <Card title="RCS" icon="message" href="./rcs-messaging">
    Rich messaging with branded content and read receipts on Android.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="./live-activities">
    Ongoing iOS Lock Screen and Dynamic Island updates for live events.
  </Card>
</Columns>

## Add and organize your users

As users interact with your mobile app or website, OneSignal assigns each a **OneSignal ID** (the OneSignal User ID) and **Subscription IDs** for each device, email address, or phone number. A single User can have multiple Subscriptions across channels.

Users stay anonymous until you identify them with an [External ID](./users#external-id). This is a stable identifier from your system — typically your internal user ID — that lets OneSignal merge a User across devices, app reinstalls, and channels. Setting an External ID may change the User's OneSignal ID if that user already exists in the OneSignal app.

<Frame>
  <img alt="OneSignal dashboard Users page showing a list of users with subscription details" />
</Frame>

<Columns>
  <Card title="Users" icon="users" href="./users">
    Identified by External ID. One User can have multiple Subscriptions across channels.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    Email addresses, phone numbers, and devices that receive your messages.
  </Card>
</Columns>

### User properties

Store user data as **tags** (key-value pairs) and **custom events** (user actions). Both power message personalization and segmentation.

<Columns>
  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Add custom properties to users for personalization and segmentation.
  </Card>

  <Card title="Custom events" icon="bolt" href="./custom-events">
    Trigger Journeys or wait-until actions based on User behavior.
  </Card>
</Columns>

### Segments and integrations

Segments are dynamic groups of users defined by tags, behavior data, or message interactions. They update automatically as data changes — for example, "Last session greater than a week" or "Added item to cart." Connect external platforms to enrich your data in real time.

<Frame>
  <img alt="OneSignal segment builder showing a User Tag filter configuration" />
</Frame>

<Columns>
  <Card title="Segments" icon="chart-pie" href="./segmentation">
    Create dynamic audience groups using tags and behavior data.
  </Card>

  <Card title="Integrations" icon="plug" href="./integrations">
    Import User data from external platforms to power segments and Journeys.
  </Card>
</Columns>

## Send messages

Design and send single-message campaigns or automated multi-step Journeys from the OneSignal dashboard. Each channel has its own composer with preview, targeting, and scheduling options.

<Frame>
  <img alt="OneSignal push notification editor showing message content fields and preview" />
</Frame>

<Columns>
  <Card title="Push notifications" icon="bell" href="./push">
    Send to web, iOS, Android, Huawei, and Amazon devices.
  </Card>

  <Card title="Email" icon="envelope" href="./email-messaging">
    Compose and send transactional or marketing emails.
  </Card>

  <Card title="In-app messages" icon="window-maximize" href="./in-app-messages-setup#triggers">
    Trigger rich, interactive messages based on User behavior within your app.
  </Card>

  <Card title="SMS, MMS, RCS" icon="comment-sms" href="./sms-composing-messages">
    Send text messages for time-sensitive alerts and updates.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="./live-activities">
    Ongoing iOS Lock Screen and Dynamic Island updates for live events.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build automated, multi-step campaigns triggered by user behavior.
  </Card>
</Columns>

### Personalize your messages

Use tags, custom events, and dynamic data to tailor message content for each recipient. OneSignal uses **Liquid syntax** to inject tag values, custom event properties, and Data Feed content into message bodies and email subject lines (e.g., `Hi {{ first_name | default: 'there' }}`). Create reusable templates to maintain consistency across campaigns.

<Columns>
  <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
    Personalize content with Liquid syntax, tags, Data Feeds, and custom data.
  </Card>

  <Card title="Templates" icon="clone" href="./templates">
    Create reusable message templates for push, email, and SMS.
  </Card>
</Columns>

### Journeys

Journeys are automated, multi-step campaigns that respond to User behavior — such as onboarding sequences, abandoned cart reminders, and re-engagement flows.

<Frame>
  <img alt="OneSignal Journey builder showing an abandoned cart automation flow" />
</Frame>

<Columns>
  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build automated, multi-step campaigns triggered by User behavior.
  </Card>

  <Card title="Journey examples" icon="book-open" href="./journeys-examples">
    Common patterns like onboarding, abandoned carts, and re-engagement.
  </Card>
</Columns>

### Send via API

Send messages programmatically for transactional use cases like order confirmations, OTPs, and billing alerts.

<Columns>
  <Card title="Developer guides" icon="code" href="./developers">
    SDK and REST API documentation for engineering teams.
  </Card>

  <Card title="Transactional messages" icon="paper-plane" href="./transactional-messages">
    Send time-sensitive messages like OTPs, receipts, and shipping updates via API.
  </Card>
</Columns>

## Measure impact with analytics

Track message performance — including delivery, opens, clicks, and conversions — to understand what drives engagement and refine your strategy.

<Columns>
  <Card title="Analytics overview" icon="chart-line" href="./analytics-overview">
    Review all analytics options available in OneSignal.
  </Card>

  <Card title="Event streams" icon="signal-stream" href="./event-streams">
    Stream message events like clicks, opens, and receives to your data warehouse in real time.
  </Card>

  <Card title="Export data" icon="file-export" href="./exporting-data">
    Export User and message data in CSV or API format.
  </Card>

  <Card title="Integrations" icon="plug" href="./integrations">
    Connect analytics platforms like Amplitude, Mixpanel, Segment, and more to OneSignal.
  </Card>

  <Card title="Conversion metrics" icon="arrow-trend-up" href="./conversion-metrics">
    Measure business impact like revenue and sign-ups with cross-channel last-touch attribution.
  </Card>

  <Card title="Goals" icon="bullseye" href="./goals">
    Set a target metric on a Journey and track progress on the Journey report.
  </Card>
</Columns>

## Next steps

Once you've sent your first message, deepen your setup with these guides.

<Columns>
  <Card title="Journeys overview" icon="route" href="./journeys-overview">
    Move from one-off campaigns to automated, multi-step lifecycle messaging.
  </Card>

  <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
    Use Liquid, tags, custom events, and Data Feeds to personalize at scale.
  </Card>

  <Card title="Segmentation" icon="chart-pie" href="./segmentation">
    Build dynamic audiences from tags, behavior, and message interactions.
  </Card>

  <Card title="Mobile-first strategy" icon="mobile" href="./mobile-first">
    Lifecycle data model, Journeys, and patterns built for mobile apps.
  </Card>
</Columns>

## FAQ

### Do I need a developer to get started?

Not necessarily. Email and SMS channels can be configured without code. Push notifications and in-app messages require SDK integration, which may need a developer or AI assistant. You can [invite team members](./manage-team-members) with different roles at any time.

### Can I add more messaging channels later?

Yes. Add any combination of channels to the same OneSignal App. Each channel has its own setup guide — return to the [messaging channels](#messaging-channels) section to add a new one.

### What is the difference between a User and a Subscription?

A **User** represents one person, identified by an [External ID](./users#external-id). A **Subscription** is a specific channel endpoint — such as a device, email address, or phone number. One User can have multiple Subscriptions across different channels and devices.

### How long does initial setup take?

Email setup typically takes under 30 minutes if you have access to your domain DNS settings. SMS requires carrier registration, which can take a few days. Push notification setup depends on your app's platform and build process — plan for a few hours of developer time.

### Where do I find my API key and App ID?

In the OneSignal dashboard, go to **Settings → Keys & IDs**. Each app has its own App ID and REST API Key — never expose the REST API Key in client-side code. See [Keys and IDs](./keys-and-ids) for the full breakdown of which key to use where.

### How do I test my setup before sending to real users?

Configure [Test Users](./test-users) — devices, email addresses, or phone numbers flagged as internal — then use the **Send to Test Users** option in any composer. Test sends bypass segments and exclusions so you can preview rendering, deep links, and personalization on your own devices first.

### Can I migrate from another messaging platform?

Yes. The fastest path is to (1) install the OneSignal SDK alongside your existing provider, (2) call the External ID and Tag setters with the user IDs and attributes from your current system so identities map cleanly, and (3) once Subscriptions are flowing in, sunset the old provider. For email and SMS lists, you can also import historical Subscriptions via CSV — see [Users](./users) and [Subscriptions](./subscriptions) for the import patterns.

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# Rich Communication Services (RCS)
Source: https://documentation.onesignal.com/docs/en/rcs-messaging

Send branded, app-like messages with RCS in OneSignal. Covers rich content types, sender setup, image requirements, SMS fallback, and country availability.

RCS (Rich Communication Services) is the next evolution of text messaging. It delivers branded, app-like experiences natively in the recipient's default messaging app — including your business name and logo as the sender identity, read receipts, carousels, action buttons, and keyword replies.

RCS requires a premium RCS sender resource and a separate approval process. SMS is used as an automatic fallback when the recipient's device or carrier does not support RCS.

<Frame>
  <img alt="Example RCS message with branded sender, image card, and action buttons" />
</Frame>

***

## How RCS compares to SMS

|                     | SMS                                  | RCS                                                         |
| ------------------- | ------------------------------------ | ----------------------------------------------------------- |
| **Sender identity** | Phone number                         | Your brand name, logo, and color                            |
| **Read receipts**   | No                                   | Yes                                                         |
| **Rich media**      | MMS only (images, video)             | Cards and carousels with embedded media                     |
| **Interactivity**   | Keywords (inbound text)              | Tappable action buttons (link, keyword reply, phone number) |
| **Fallback**        | N/A                                  | Automatically falls back to SMS                             |
| **Approval**        | Standard sender resource application | Additional brand assets and carrier review                  |
| **Price**           | Included / standard                  | Premium                                                     |

***

## Rich content types

If your sender includes an RCS sender resource, the message editor unlocks these capabilities:

* **Text only:** Plain branded RCS text with no media or actions. Links in the body remain tappable. Text-only messages always use their own RCS text as the fallback and do not use the SMS fallback field.
* **Cards:** Standalone rich messages with an image, title, description, and up to three actions.
* **Carousels:** Horizontally scrollable sets of rich cards. Useful for showcasing multiple products, locations, or options in a single message.
* **Actions:** Tappable buttons attached to cards. Three types are supported:
  * **Link buttons:** Open any http or https URL. Supports iOS Universal Links and Android App Links, which deep link into your app when it's installed.
  * **Keyword replies:** Send a keyword back as the subscriber's response without requiring them to type.
  * **Phone number:** Initiates a phone call directly from the message.

<Card title="Composing messages" icon="pencil" href="./sms-composing-messages#rcs-content">
  Full RCS editor reference, including image aspect ratios, action configuration, and billing categories.
</Card>

***

## SMS fallback

OneSignal automatically sends an SMS fallback when RCS fails to deliver — for example, when the recipient's device or carrier doesn't support RCS.

<Card title="SMS fallback" icon="message-arrow-down" href="./sms-composing-messages#sms-fallback">
  Configure the fallback message and review the rules for text-only RCS messages.
</Card>

***

## Setup

RCS requires a premium RCS sender resource in addition to an SMS sender resource. The RCS sender resource must be approved separately. **Approval timelines are typically 8–16 weeks.**

During the application process, you will need to provide additional brand assets beyond the standard sender resource application:

* **Brand logo:** The image carriers display as your sender identity.
* **Brand color:** The accent color used alongside your brand in the messaging app.
* **Agent description:** A short paragraph carriers display alongside your brand identity, describing what subscribers should expect from your messages. "Agent" is the carrier term for the business identity that sends RCS messages.
* **Launch URL:** Your business homepage or marketing page for your messaging program.

For country-specific RCS availability, approval processes, and reviewer requirements, see [Sender resource applications](./sms-registration-requirements). Once you submit an application, you can track each sender resource's carrier approval status at **Settings > SMS > Senders**.

<Note>
  In the U.S., carriers currently prioritize notable brands (Fortune 1000), high-quality rich content experiences, and established SMS sending volume (100K+ SMS messages/month through OneSignal) for RCS approval.
</Note>

To get started with RCS, [contact our team](https://onesignal.com/rcs#contact) or reach out to your account manager.

***

## Analytics

RCS messages include all standard SMS metrics plus:

* **Read:** The number of subscribers who read the RCS message (available because RCS supports read receipts).

<Card title="SMS message reports" icon="chart-bar" href="./sms-message-reports">
  Full metrics reference for delivery, click, and read events across SMS, MMS, and RCS.
</Card>

***

## FAQ

### Does RCS work on all devices?

No. RCS requires the recipient's device and carrier to support it. OneSignal automatically falls back to SMS when RCS is not supported, so every recipient gets a message regardless of device capability.

### Can I send RCS messages internationally?

RCS availability varies by country. Not all countries where OneSignal supports SMS also support RCS. See [Sender resource applications](./sms-registration-requirements) for per-country RCS availability.

### Does an RCS sender resource replace my SMS sender resource?

No. You need both. The RCS sender resource is used when the recipient supports RCS; the SMS sender resource is used as the fallback. OneSignal handles the routing automatically within the same sender.

### Which editor do I get in Templates?

In Templates, you select a sender, and the editor adapts to it: you get the RCS editor when the selected sender has an RCS sender resource, and the SMS editor otherwise. When a sender has an approved RCS resource, OneSignal automatically prefers RCS for existing automations using that sender. See [Upgrading existing automations to RCS](./sms-composing-messages#upgrading-existing-automations-to-rcs) for how existing SMS content maps to RCS.


# Retargeting messages
Source: https://documentation.onesignal.com/docs/en/retargeting

Send follow-up push messages in OneSignal based on how Subscriptions interacted with a previous send — clicked, didn't click, failed delivery, or unsubscribed. Retargeting is available from any push message report within 30 days of the original send.

Retargeting sends a follow-up push message to the Subscriptions that reached a specific outcome on a previous send — for example, Subscriptions that clicked, didn't click, or failed delivery. Start retargeting from the [Audience activity](./push-notification-message-reports#audience-activity) section of any push message report.

<Note>
  Retargeting is available for push messages sent within the last **30 days**. Audience activity data is retained for 30 days from the time the original message was sent.
</Note>

## How to retarget users

<Steps>
  <Step title="Open a sent message">
    Go to the **Messages** or **Delivery** tab in the OneSignal dashboard and select the message whose audience you want to retarget.

    <Frame>
      <img alt="Messages list in the OneSignal dashboard showing sent notifications" />
    </Frame>
  </Step>

  <Step title="Open Audience activity">
    Scroll to the **Audience activity** section of the message report. The available retargeting categories are:

    * **Sent** — message was sent to the device.
    * **Confirmed Receipt** — delivery was confirmed by the device.
    * **Did Not Confirm Receipt** — delivery confirmation was not received.
    * **Clicked** — user clicked the notification.
    * **Did Not Click** — user did not click the notification.
    * **Failed** — delivery failed.
    * **Unsubscribed** — Subscriptions that became unreachable (uninstalled, cleared browser data, or opted out) since the original send.
  </Step>

  <Step title="Start retargeting">
    Click **Send a Retargeted Message** next to the category you want to target.

    <Frame>
      <img alt="Audience activity section with the Send a Retargeted Message button" />
    </Frame>
  </Step>

  <Step title="Compose and send">
    Enter a **Message Name** so you can find it later. The **Audience** is pre-filled with the Subscriptions in the category you selected. Compose your follow-up content with the standard message editor and send.

    <Frame>
      <img alt="Retargeting message setup showing the pre-filled audience" />
    </Frame>
  </Step>
</Steps>

<Warning>
  Retargeted messages must be scheduled within **30 days** of the original message's send date. After 30 days, audience activity data is purged and the original message is no longer eligible for retargeting.
</Warning>

## FAQ

### Which channels support retargeting?

Retargeting is available for **push** messages. It is not currently available for email, SMS, or in-app messages. To build a similar flow for other channels, use [Segments](./segmentation) and [Journeys](./journeys-overview).

### Why don't I see my previously sent notifications?

Notifications sent via the **API** or as **Automated Messages** are automatically deleted after approximately **30 days**. Once deleted, they no longer appear in your message history and cannot be used for retargeting. Dashboard-composed messages follow the same 30-day retention window for audience activity.

### Why can't I retarget older messages?

Audience activity data is retained for 30 days. After that, the interaction data needed to rebuild the retargeting audience is purged and the original message becomes ineligible.

If you recently upgraded to a plan that includes retargeting, messages sent **before** the upgrade are **not** retroactively stored. Retargeting data collection begins only after your account gains access to the feature.

### Can I retarget a retargeting message?

Yes. A retargeted send creates a new push message report with its own Audience activity, so you can retarget from it like any other message, as long as you do so within 30 days of that follow-up send.

### Does retargeting use the Create message API?

No. Retargeting is a dashboard feature that builds the audience from the original message's Audience activity. To reach a similar audience through the API, capture the outcome as a [Data Tag](./add-user-data-tags) or user property on each Subscription, then target a [Segment](./segmentation) built from that tag in the [Create message](/reference/create-message) API.

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

## Related

<Columns>
  <Card title="Push message reports" icon="file-chart-column" href="./push-notification-message-reports">
    Delivery outcomes, engagement metrics, and per-Subscription audience activity for each push send.
  </Card>

  <Card title="Segmentation" icon="filter" href="./segmentation">
    Build reusable audiences from Data Tags and user behavior.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Automate multi-step follow-ups across channels based on user events.
  </Card>

  <Card title="Exporting data" icon="file-export" href="./exporting-data">
    Export message and user data to CSV for offline analysis.
  </Card>
</Columns>


# Notification images & rich media
Source: https://documentation.onesignal.com/docs/en/rich-media

Learn how to add images, gifs, and multimedia to mobile push notifications using OneSignal's Dashboard and API, including recommended formats, device-specific behavior, and rich media customization options.

This guide explains how to enhance mobile push notifications using **images and rich media**, including platform support, technical limitations, and customization options in OneSignal.

Image guides for other channels:

<Columns>
  <Card title="Web Push" icon="globe" href="./push#image">
    Add images to web push notifications.
  </Card>

  <Card title="Design your in-app message" icon="pen-ruler" href="./design-your-in-app-message">
    Full reference for the in-app message editor, blocks, and Carousel.
  </Card>

  <Card title="Email" icon="envelope" href="./design-emails-with-drag-and-drop">
    Add images to emails.
  </Card>

  <Card title="SMS" icon="sms" href="./sms-messaging">
    Add images to make MMS messages.
  </Card>
</Columns>

***

## Mobile app images

You can add images to push notifications via the OneSignal Dashboard or API. There are two main types:

### Notification icons

* **iOS**: Automatically uses the app icon.
* **Android**: Allows custom large and small icons.
* See [Notification icons](./notification-icons) for setup instructions.

### Big Picture image (large format)

* **Android**: Shows expanded by default on most devices.
* **iOS**: Requires user to swipe down or long press.

To add images:

* In Dashboard: **Messages > New Push > "Upload" to image field**
* Or use API parameters: `big_picture` (Android) and `ios_attachments` (iOS)

<Frame>
  <img />
</Frame>

***

## Image specifications

Use landscape-oriented images with a 2:1 aspect ratio.

|                   | iOS                                                                                                                             | Android                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Filetypes**     | `jpg`, `jpeg`, `png`, `gif`                                                                                                     | `jpg`, `jpeg`, `png`, `gif`\*                                                              |
| **Resolution**    | 1:1 aspect ratio or 2:1 aspect ratio (e.g., `1038x1038px` or `1024×512px`)<br />**Max Width:** 2000px<br />**Min Width:** 300px | 2:1 aspect ratio (e.g., `1024×512px`)<br />**Max Width:** 2000px<br />**Min Width:** 300px |
| **API Parameter** | `ios_attachments`                                                                                                               | `big_picture`                                                                              |

* \*Android does **not** support animated GIFs.
* Adding [Action Buttons](./action-buttons) may reduce image display area.
* See [Notification Images Not Showing](./notification-images-not-showing) if images don't appear.

<Warning>
  OneSignal enforces a 5MB upload limit and does not support audio or video uploads. Hosted images expire after 33 days. For long-term use, upload to your own static URL or use Templates.
</Warning>

***

## Rich notification customization

OneSignal supports deeper visual and interactive customization using native platform features.

### Android custom notification layout

Android 12+ enforces system templates for custom notifications. However, you can still customize your layout using Android’s standard notification styles. See [behavior changes](https://developer.android.com/about/versions/12/behavior-changes-12#custom-notifications) for details.

To customize your layout:

* Follow [Android's custom notification guide](https://developer.android.com/develop/ui/views/notifications/custom-notification)
* Apply changes via the [Notification Service Extension](./service-extensions)
* See [Notification.DecoratedCustomViewStyle](https://developer.android.com/reference/android/app/Notification.DecoratedCustomViewStyle) for available customizations.

### iOS content extensions

iOS uses [`UNNotificationContentExtension`](https://developer.apple.com/documentation/usernotificationsui/unnotificationcontentextension?language=objc) to enable rich media and interactivity in notifications.

Supported features:

* Image carousels
* Embedded video playback
* Custom views like calendars or chat previews

See our [iOS Carousel Guide](./ios-image-carousel-push-notifications) for setup instructions.

***

## Supported media attachments

Rich media can be added via URLs to externally hosted content. This works with `UNNotificationContentExtension` on iOS.

<Warning>
  * Ensure your URLs are direct links to the file and end in the correct extension. If not, append a query (e.g., `?file=video.mp4`) so the SDK can detect the media type.
  * OneSignal has a 5MB limit on uploaded images. Video and audio must be hosted externally. Link directly to the media file, not a webpage.
</Warning>

| Attachment | File Type                              | Max Size | Requirements                                                                                                                                   |
| ---------- | -------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Audio**  | `aif`, `aiff`, `wav`, `mp3`            | 5MB      | None                                                                                                                                           |
| **Video**  | `mp4`, `mpeg`, `mpeg2`, `mpeg4`, `avi` | 50MB     | [`UNNotificationContentExtension`](https://developer.apple.com/documentation/usernotificationsui/unnotificationcontentextension?language=objc) |
| **Image**  | `jpg`, `jpeg`, `png`, `gif`            | 10MB     | [OneSignalNotificationServiceExtension](./service-extensions)                                                                                  |

<Note>
  The [OneSignalNotificationServiceExtension](./service-extensions) is included in the OneSignal SDK and required for image support, delivery tracking, and badge updates.
</Note>

***

## Testing tips

Make sure your media displays correctly across devices:

* Always test on real devices (not emulators).
* iOS requires long press or swipe-down to reveal rich media.
* Android rendering varies by device, OS version, and presence of action buttons.
* Use the **"Send Test"** button in OneSignal before launching a campaign.

### Example use cases

* Show a product photo in an abandoned cart reminder
* Promote a new movie trailer with a video preview (iOS only)
* Send an animated banner for a flash sale

***

## Troubleshooting

If your images aren’t appearing as expected, consult the [Notification Images Not Showing](./notification-images-not-showing) guide for common causes and fixes.

***


# Senders
Source: https://documentation.onesignal.com/docs/en/senders

Learn how to manage sender identities and domains to improve email deliverability and maintain a strong sender reputation.

**Senders** identify where emails are being sent *from*. Managing your senders is critical to ensuring your emails reach the inbox and reflect your brand. Each sender is made up of two key parts:

1. **From Address** – The sender name and email address your recipients see in their inbox.
2. **Sending Domain** – The authenticated domain used to send your emails and build your sending reputation.

Sender identities must be verified (via DNS records) to ensure deliverability and prevent bad actors from sending emails on your behalf. Every email sent through OneSignal must come from a verified sender identity that you control.

<Warning>
  If you're using an integration with SendGrid, Mailchimp, or Mailgun, you must manage senders directly through your ESP’s platform.
</Warning>

***

## Create a sender

When you first [set up email](./email-setup), you’ll be prompted to create a **default sender**.

### Default sender email

This is the email address used to send messages when no other sender is specified. You must have one default sender at all times.

To change the default, click the action menu next to a sender and select **Set as Default**.

<Frame>
  <img />
</Frame>

### Default sender name

This is the display name that appears in the recipient's inbox (e.g. `Acme Team`, `Maggie’s Newsletter`).

### Default reply-to address

The email address users will reply to. You can override this per email if needed.

### Sending domain

This is the domain used to send and authenticate your emails. You must [configure your DNS records](./email-dns-configuration) to verify ownership and improve deliverability.

We strongly recommend using a subdomain (e.g. `mail.yourdomain.com`) to keep email reputation isolated from your main domain.

***

## Add additional senders

You can register up to 100 senders to support different teams, brands, or message types. Each sender is tied to one domain but a single domain can support multiple senders (e.g. `rewards@yourdomain.com`, `support@yourdomain.com`, `marketing@yourdomain.com`, etc.).

<Frame>
  <img />
</Frame>

To create a new sender:

1. Go to **Settings** > **Email** > **Senders**
2. Click **Add Sender**
3. Enter the sender name and sender email
4. Enter your sending domain and configure DNS. It may take a few minutes to auto-detect and verify DNS records.
5. Once verified, use this sender in **Messages** > **New Email** by selecting it from the **Sender** dropdown

***

## From addresses vs. senders

<Frame>
  <img />
</Frame>

* **From addresses**: These are the sender name and email shown in the recipient’s inbox. You can create multiple from addresses under the same sender, as long as they share the same domain.

  **Example** under `mail.yourdomain.com`:

  * `news@yourdomain.com` (Newsletter)
  * `promos@yourdomain.com` (Promotions)

* **Senders**: Each sender has its own unique sending domain. This is helpful when you want to isolate deliverability between message types.

  **Example**:

  * `mail.yourdomain.com` (Marketing)
  * `notify.yourdomain.com` (Transactional)

***

## Deactivate a sender or delete from address

You may deactivate senders or delete individual from addresses, as long as they are not your defaults. This prevents that from address or sender from being selected or used in emails going forward.

<Tabs>
  <Tab title="Deactivate secondary sender or from address">
    <p>When a sender and its from addresses are not set as the default, both can be removed.</p>

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Default from address">
    <p>The default from address cannot be deleted, nor can its parent sender be deactivated.</p>

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Delete secondary from address">
    <p>A secondary from address for your default sender can be deleted.</p>

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>
</Tabs>

For best results, you should ensure a sender is not in use before deactivating it. However, if it is:

* **Email templates**: All email templates using that sender be updated to use your default sender and from address. In some cases, if you have a very large number of templates, this may take a few minutes to complete.

* **Scheduled sends**: Any emails scheduled to be sent in the future, including warm-ups, will be updated to use your default sender and from address.

* **In-progress sends**: Any emails currently mid-send, including regular, intelligent delivery, and timezone delivery sends, must either be allowed to complete or canceled. You will be shown a list of these sends and can choose to wait or cancel them according to your preferences.

***

## Best practices

To protect your sender reputation and ensure high deliverability:

* Use separate senders and subdomains for different message types:
  * `mail.yourdomain.com` for transactional emails
  * `info.yourdomain.com` for marketing emails

* Avoid using your root domain (e.g. `yourdomain.com`) to send email. Always use a subdomain.

* Monitor domain reputation and avoid mixing high-risk marketing sends with critical transactional messages.

***

## Next steps

* [Email setup](./email-setup)
* [Email DNS configuration](./email-dns-configuration)
* [Email deliverability](./email-deliverability)
* [BCC emails](./email-bcc)

***


# Transactional emails
Source: https://documentation.onesignal.com/docs/en/setup-transactional-emails

Send transactional emails like purchase confirmations, password resets, and welcome messages through OneSignal with delivery, click, and open tracking.

Transactional emails are messages triggered by a specific action — purchase confirmations, password resets, welcome emails, or other service-related notifications. Unlike marketing emails, transactional emails are considered necessary for delivering your service.

Sending transactional emails through OneSignal lets you:

* **Track delivery, clicks, and opens** from the OneSignal dashboard alongside push notifications and marketing emails
* **Manage all communications in one place** instead of maintaining a separate transactional email provider
* **Automate with Journeys** — combine transactional and marketing messages in visual workflows

***

## Transactional vs. marketing

**Transactional emails** are sent in response to an action the recipient has taken (e.g., making a purchase, requesting a password reset). An unsubscribe link is not required because the message is necessary for delivering your service.

**Marketing emails** are all other messages that are not required as part of your service. Marketing emails require recipient consent and must include an unsubscribe link. See [Email Regulatory Compliance](./email-compliance) for details.

***

## Sending transactional emails

Transactional emails can be sent to all recipients — including those who have unsubscribed from marketing emails — by enabling the **include unsubscribed** option.

### From the dashboard or a template

1. Open your email message or [template](./templates).
2. Toggle open **Advanced Settings**.
3. Check **Include sending to unsubscribed users**.

<Frame>
  <img alt="Advanced Settings with include sending to unsubscribed users checkbox" />
</Frame>

You can also remove the [unsubscribe link](./unsubscribe-links-email-subscriptions) since the email is sent to every recipient in the segment regardless of subscription status.

<Note>
  When sending from the dashboard, you can only target [Segments](./segmentation). To create a segment for specific recipients, set [Tags](./add-user-data-tags) using the [Import](./import) feature, then build a segment based on those tags.
</Note>

<Info>
  If you send transactional emails via a third-party ESP like Mandrill, Mailgun, or SendGrid, you may need to clear unsubscribed addresses from your suppression list to enable delivery.
</Info>

### From the API

Send transactional emails programmatically using the [Create message](/reference/email) API. Set `include_unsubscribed` to `true` to deliver to unsubscribed email Subscriptions.

```json theme={null}
{
  "app_id": "YOUR_ONESIGNAL_APP_ID",
  "include_email_tokens": ["email1@address.com", "email2@address.com"],
  "email_subject": "Your Email Subject",
  "template_id": "e59b3a5e-ccc4-44ff-b39e-aa4c668fe6c1",
  "include_unsubscribed": true
}
```

This example uses a [template](./templates) that excludes the unsubscribe link. You can also omit the unsubscribe link directly in the `email_body` HTML.

See [Transactional Messages](./transactional-messages) for more details on transactional messaging across all channels.

***

## Migrate existing transactional emails

Import your existing email templates into OneSignal using:

1. [Email Template Forwarding](./email-template-forwarding) — forward an email to OneSignal to convert it into a template
2. [Create template API](/reference/create-template) — upload templates programmatically
3. The `email_body` parameter on the [Create message API](/reference/email) — inject HTML directly per message

***

## FAQ

### Do transactional emails require an unsubscribe link?

No. Transactional emails are service-related messages triggered by a recipient's action (e.g., a purchase or password reset). They are not subject to the same unsubscribe requirements as marketing emails. However, you should never use transactional emails to send marketing content.

### Can I send transactional emails to unsubscribed users?

Yes. Set `include_unsubscribed` to `true` in the API, or check **Include sending to unsubscribed users** in the dashboard's Advanced Settings. This delivers the email regardless of the recipient's subscription status.

### What is the difference between transactional and marketing emails?

Transactional emails are triggered by a specific user action and are necessary for delivering your service (e.g., order confirmations, password resets). Marketing emails promote your product or service and require recipient consent and an unsubscribe link. See [Email Regulatory Compliance](./email-compliance) for detailed guidelines.

## Related pages

<Columns>
  <Card title="Transactional messages" icon="paper-plane" href="./transactional-messages">
    Send transactional messages across all channels — email, push, SMS.
  </Card>

  <Card title="Email overview" icon="envelope" href="./email-messaging">
    End-to-end guide to sending email with OneSignal.
  </Card>

  <Card title="Email templates" icon="copy" href="./templates">
    Save and reuse email designs across campaigns.
  </Card>

  <Card title="Email compliance" icon="shield-check" href="./email-compliance">
    Regulatory requirements for email messaging.
  </Card>
</Columns>


# Shopify
Source: https://documentation.onesignal.com/docs/en/shopify

Connect Shopify to OneSignal through the Vendo integration for web push notifications, customer tags, commerce events, and behavioral targeting.

OneSignal has partnered with Vendo to create a seamless Shopify integration. Vendo deploys the OneSignal SDK on your Shopify storefront with one click — no manual theme code editing required. It syncs customer tags, client-side browsing events, and server-side commerce events to OneSignal so you can build segments and trigger push campaigns from real behavior and purchase history.

For Vendo's documentation, see [Vendo OneSignal Destination](https://docs.vendodata.com/destinations/onesignal/overview).

## Prerequisites

Before you begin, make sure you have:

* A Shopify store with the [Vendo app](https://apps.shopify.com/) installed
* A OneSignal account and app (Web platform)
* Your OneSignal **App ID** (required)
* Your OneSignal **REST API Key** (required for server-side events like order syncing and user tagging)
* Vendo app embed enabled in your Shopify theme settings

## OneSignal setup

<Steps>
  <Step title="Create a OneSignal app">
    Log in to [onesignal.com](https://onesignal.com) and create or select an app. Choose **Web** as the platform and select **Custom Code** as the integration type.

    <Warning>
      You must select **Custom Code**. The **Typical Site** option does not expose the service worker path settings, so the SDK will try to load `/OneSignalSDKWorker.js` from your store root — Shopify blocks this and push subscriptions will silently fail. If you already created the app under Typical Site, switch to Custom Code in **Settings > Platforms > Web**, or delete and recreate the app.
    </Warning>
  </Step>

  <Step title="Configure web push settings">
    In your OneSignal app, navigate to **Settings > Push & In-App > Web Settings** or follow the [Web push setup](./web-push-setup) guide.

    **Site setup**

    * **Site Name**: Your store name, used as the default notification title.
    * **Site URL**: Your Shopify store's publicly accessible URL (e.g., `https://yourstore.com`).
      * Must be the exact [origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) of your site.
      * Do not use `https://your-site.myshopify.com/` if customers access your site through a custom domain like `https://your-site.com/`.
    * **Default Icon URL**: Upload a square 256x256px PNG image for notification prompts and messages. If not set, a bell icon is used.
  </Step>

  <Step title="Configure the service worker path">
    Shopify does not allow serving files from the site root, so you must tell OneSignal where Vendo serves the service worker file.

    In OneSignal, go to **Settings > Push & In-App > Web Settings**, scroll to **Advanced Push Settings**, and toggle on **Customize service worker paths and filenames**, then configure:

    | Setting                           | Value                   |
    | --------------------------------- | ----------------------- |
    | Path to service worker files      | `/apps/vendo/`          |
    | Main service worker filename      | `OneSignalSDKWorker.js` |
    | Updater service worker filename   | `OneSignalSDKWorker.js` |
    | Service worker registration scope | `/apps/vendo/`          |

    <Frame>
      <img alt="OneSignal Advanced Push Settings showing service worker paths configured for Vendo" />
    </Frame>

    Vendo automatically serves the required `OneSignalSDKWorker.js` file at `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js` — no manual file uploads needed.

    <Note>
      The Vendo app's **OneSignal > Push Settings** page displays these exact values with click-to-copy, so you don't need to retype them.

      The Updater Filename and Main Service Worker Filename are the same file. OneSignal v16+ uses a single service worker for both purposes.
    </Note>
  </Step>

  <Step title="Copy your credentials">
    In OneSignal, go to [**Settings > Keys & IDs**](./keys-and-ids) and copy your **App ID** and **REST API Key**. You will enter these in Vendo.
  </Step>
</Steps>

## Vendo setup

<Steps>
  <Step title="Install the Vendo app">
    Install the Vendo app from the Shopify App Store.
  </Step>

  <Step title="Add the OneSignal integration">
    In Vendo, navigate to **Destinations > OneSignal**.

    <Frame>
      <img alt="Vendo Integrations page showing the OneSignal integration option" />
    </Frame>
  </Step>

  <Step title="Enter your OneSignal credentials">
    Enter your OneSignal **App ID** and **REST API Key** from the previous section, then click **Save**.
  </Step>

  <Step title="Enable the Vendo theme block">
    The Vendo theme block loads the OneSignal SDK on your storefront. Without it, the push prompt will not appear and client-side tracking will not work.

    1. In your Shopify admin, go to **Online Store > Themes > Customize**.
    2. Click **App embeds** (puzzle piece icon in the left sidebar).
    3. Toggle **Vendo** on.
    4. Click **Save**.

    The theme block handles SDK initialization, service worker registration, push prompt display, user identification (push subscription, login, newsletter signup), and tag syncing for identified users.
  </Step>

  <Step title="Select events to sync">
    In the Vendo app under **OneSignal > Events**, enable the client-side and server-side events you want to send to OneSignal. See [Tracking](#tracking) below for the full event list.
  </Step>

  <Step title="Configure push prompts">
    Whether each prompt appears on your storefront — and when — is controlled from the Vendo app, not the OneSignal dashboard. In the Vendo app, open **OneSignal > Push Settings**. You will see four sections, each with its own toggle:

    | Section                   | What it does                                                   |
    | ------------------------- | -------------------------------------------------------------- |
    | **Subscription Bell**     | Floating bell icon visitors can click to subscribe at any time |
    | **Push Slide Prompt**     | Branded slide-in banner asking for push permission             |
    | **Native Browser Prompt** | Triggers the browser's built-in permission dialog directly     |
    | **Welcome Notification**  | Push notification sent automatically when a visitor subscribes |

    For Push Slide and Native prompts, you also set **triggers** — how many page views and how many seconds to wait before the prompt fires. Sensible defaults are pre-filled.

    All four prompts are **off by default** — enable only the ones you want. Save once at the bottom of the page; changes take effect on the next storefront load without a theme redeploy.

    <Note>
      Prompt button copy, action message text, icons, and advanced options like A/B tests and localization are configured in the OneSignal dashboard. From Vendo's Push Settings, click **Open OneSignal Dashboard** to jump directly to the Permission Prompt Setup page. If a prompt is configured in OneSignal's dashboard but its Vendo toggle is off, it will not render — Vendo's toggle is the source of truth for visibility.
    </Note>
  </Step>

  <Step title="Historical data sync (optional)">
    Vendo can backfill existing customers and recent order history to OneSignal. This happens automatically in the background after you save your credentials.

    <Frame>
      <img alt="Vendo historical data settings showing sync options for Shopify data" />
    </Frame>
  </Step>
</Steps>

## Tracking

### User identification

Vendo uses an **identified-only** approach — anonymous visitors are not tracked in OneSignal. Users must be identified through one of four methods before events are sent. This prevents duplicate users and ensures clean, actionable data.

| Method                    | How it works                                                                                                               | Identifier used              |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| **Web push subscription** | Visitor clicks "Allow" on the push prompt. OneSignal creates a user automatically and Vendo captures the OneSignal ID.     | OneSignal ID                 |
| **Newsletter signup**     | Visitor submits a newsletter or email form. Vendo captures the email and calls `OneSignal.login(email)`.                   | Email                        |
| **Customer login**        | Customer logs into their Shopify account. Vendo detects this and calls `OneSignal.login()` with the configured identifier. | Shopify Customer ID or Email |
| **Checkout completed**    | Customer completes a purchase. Vendo stores the identifier and calls `OneSignal.login()`.                                  | Shopify Customer ID or Email |

<Warning>
  If you have a mobile app or third-party connections, select the identifier (Shopify Customer ID vs. Email) that matches your other tools so user profiles stay consistent across platforms. Configure this in the Vendo app under **Settings > Customer Identifier**.
</Warning>

#### Identity merging

If a push subscriber (identified by OneSignal ID) later logs in or completes a purchase, Vendo calls `OneSignal.login()` with their Shopify Customer ID or email. OneSignal links the push subscription to the identified user — no duplicate users are created. All past push subscriptions are preserved, and server-side events (orders, fulfillments) reach the correct user profile.

### Customer tags

Vendo syncs customer properties as [tags](./add-user-data-tags) in OneSignal for segmentation. All values are stored as strings (OneSignal's native format).

#### Identity & profile

| Tag                   | Description                                     |
| --------------------- | ----------------------------------------------- |
| `email`               | Customer email                                  |
| `first_name`          | First name                                      |
| `last_name`           | Last name                                       |
| `phone`               | Customer phone number                           |
| `shopify_customer_id` | Shopify customer ID                             |
| `verified_email`      | `"true"` or `"false"`                           |
| `tax_exempt`          | `"true"` or `"false"`                           |
| `customer_tags`       | Comma-separated Shopify tags                    |
| `customer_created_at` | Customer creation date (ISO 8601)               |
| `first_seen`          | ISO timestamp of the first identification event |

#### Marketing consent

| Tag                       | Description                     |
| ------------------------- | ------------------------------- |
| `marketing_state`         | Overall marketing consent state |
| `email_marketing_consent` | Email marketing consent state   |

#### Commerce stats

| Tag                | Description                       |
| ------------------ | --------------------------------- |
| `total_spent`      | Lifetime spend                    |
| `order_count`      | Total orders                      |
| `first_order_date` | First order date (ISO 8601)       |
| `last_order_date`  | Most recent order date (ISO 8601) |

#### Attribution tags

Vendo captures UTM parameters and click IDs at checkout and syncs them as tags. Last-touch values are overwritten on each checkout; first-touch values (`initial_utm_*`) are written only once.

| Tag                    | Description                         |
| ---------------------- | ----------------------------------- |
| `utm_source`           | Last-touch UTM source               |
| `utm_medium`           | Last-touch UTM medium               |
| `utm_campaign`         | Last-touch UTM campaign             |
| `utm_content`          | Last-touch UTM content              |
| `utm_term`             | Last-touch UTM term                 |
| `initial_utm_source`   | First-touch UTM source (set once)   |
| `initial_utm_medium`   | First-touch UTM medium (set once)   |
| `initial_utm_campaign` | First-touch UTM campaign (set once) |
| `gclid`                | Google Ads click ID                 |
| `fbclid`               | Meta (Facebook/Instagram) click ID  |
| `ttclid`               | TikTok click ID                     |
| `msclkid`              | Microsoft Ads click ID              |

#### Segment membership

Vendo can sync Shopify segment membership as tags in the format `shopify_segment_{segment_id}` with a value of `"true"`. See [Vendo's Events & Properties reference](https://docs.vendodata.com/destinations/onesignal/events-and-properties) for details on running the sync.

### Client-side events

Vendo tracks client-side [custom events](./custom-events) on your storefront via the Shopify Web Pixel and sends them to OneSignal. These events are only sent after a user is identified.

| Event                              | Description                                                    |
| ---------------------------------- | -------------------------------------------------------------- |
| `page_viewed`                      | Customer visits a page (storefront, checkout, or order status) |
| `product_viewed`                   | Customer views a product details page                          |
| `collection_viewed`                | Customer views a product collection page                       |
| `search_submitted`                 | Customer performs a storefront search                          |
| `product_added_to_cart`            | Product is added to cart                                       |
| `product_removed_from_cart`        | Product is removed from cart                                   |
| `cart_viewed`                      | Customer views the cart page                                   |
| `checkout_started`                 | Customer starts checkout                                       |
| `checkout_contact_info_submitted`  | Contact info step submitted                                    |
| `checkout_address_info_submitted`  | Address info step submitted                                    |
| `checkout_shipping_info_submitted` | Shipping method selected                                       |
| `payment_info_submitted`           | Payment details submitted                                      |
| `checkout_completed`               | Checkout completed successfully                                |
| `alert_displayed`                  | Checkout alert or warning displayed                            |
| `ui_extension_errored`             | Checkout UI extension runtime error                            |
| `all_custom_events`                | Custom Shopify customer events                                 |

<Frame>
  <img alt="Vendo client-side events settings showing available custom events" />
</Frame>

### Server-side events

Shopify commerce events are exported and forwarded to OneSignal through the Vendo pipeline. These always use the Shopify Customer ID as the `external_id`.

| Event                      | Description                 |
| -------------------------- | --------------------------- |
| `order_received`           | New order is created        |
| `order_fulfilled`          | Order is fulfilled/shipped  |
| `order_delivered`          | Order is delivered          |
| `order_refunded`           | Order is fully refunded     |
| `order_partially_refunded` | Order is partially refunded |
| `cart_abandoned`           | Checkout is abandoned       |

<Frame>
  <img alt="Vendo server-side events settings showing available Shopify webhook events" />
</Frame>

## Platform details

| Setting       | Value                                       |
| ------------- | ------------------------------------------- |
| Sync method   | Client + server-side via Vendo              |
| Identity      | Shopify Customer ID, Email, or OneSignal ID |
| Deduplication | UUID v5 hashing per event                   |
| Batch size    | 1,000 events per request                    |
| Data format   | All values stored as strings                |

## Use cases

### Abandoned cart recovery

Create a [Journey](./journeys-overview) triggered by the `cart_abandoned` event. Wait 1 hour after abandonment, then send a push notification with the recovery link using the `checkout_url` property.

### Order status updates

Create Journeys for `order_fulfilled` and `order_delivered` to send immediate push notifications with tracking information when orders ship and arrive.

### VIP customer engagement

Create a [segment](./segmentation) where `total_spent` is greater than a threshold, then send exclusive offers personalized with the `first_name` tag.

### Re-engagement campaigns

Target inactive customers by creating a segment where `last_order_date` is more than 90 days ago and send win-back campaigns.

## Compatible sources

OneSignal works with the following Vendo data sources:

| Source    | Events      | User tags   | Audiences   |
| --------- | ----------- | ----------- | ----------- |
| Shopify   | Yes         | Yes         | Yes         |
| Stripe    | Coming Soon | Coming Soon | Coming Soon |
| Mixpanel  | Coming Soon | Coming Soon | Coming Soon |
| Amplitude | Coming Soon | Coming Soon | Coming Soon |

***

## Testing

<Steps>
  <Step title="Verify the service worker">
    Visit `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js` in your browser. You should see JavaScript code. If you get a 404, verify the Vendo app is installed and the theme block is enabled.

    You can also open browser DevTools (**F12**), go to **Application > Service Workers**, and confirm `OneSignalSDKWorker.js` is registered with a scope of `/apps/vendo/`.
  </Step>

  <Step title="Test the push prompt">
    Open your storefront in an incognito/private window. You should see the OneSignal notification permission prompt. Click **Allow** to subscribe.
  </Step>

  <Step title="Send a test notification">
    In the OneSignal dashboard, go to **Messages > New Push**. Send a test notification to your subscriber and verify it appears.
  </Step>

  <Step title="Verify user data in OneSignal">
    Go to **Audience > All Users** and confirm your test user appears. Check that user tags (email, name, etc.) are syncing for identified users.
  </Step>

  <Step title="Trigger a test event">
    Browse a product or complete a test checkout on your store. Confirm the event appears in the user's activity in the OneSignal dashboard.
  </Step>
</Steps>

***

## Troubleshooting

### Service worker returns 404

The service worker must be at `/apps/vendo/OneSignalSDKWorker.js`. If you see a 404 error at the root path (`/OneSignalSDKWorker.js`), the service worker path is not configured in OneSignal — follow the [service worker configuration step](#configure-the-service-worker-path). If the 404 is at the `/apps/vendo/` path, verify the Vendo app is installed and the theme block is enabled.

### "Typical Site" was selected during OneSignal setup

Vendo requires the **Custom Code** integration type. Typical Site does not expose the service worker path settings, so the SDK will try to load `/OneSignalSDKWorker.js` from your store root — Shopify blocks that and push subscriptions will silently fail.

Fix: in the OneSignal dashboard, either switch the app's integration type to Custom Code under **Settings > Platforms > Web**, or delete the app and recreate it using Custom Code from the start.

### Push prompt not appearing

* Check that the Vendo theme block is enabled in **App embeds**.
* In the Vendo app under **OneSignal > Push Settings**, confirm at least one prompt toggle (Subscription Bell, Push Slide Prompt, or Native Browser Prompt) is turned on — all four are off by default.
* Check the trigger delay — a Push Slide set to multiple page views won't fire on the first page load.
* Verify your browser allows notifications (click the lock icon in the address bar).
* Try an incognito/private window in case the prompt was previously dismissed.

### Tags not appearing in OneSignal

Tags only sync for identified users — anonymous visitors are not tracked. Ensure the user has been identified via push subscription, login, newsletter signup, or checkout. Initial tag syncs can take several hours.

### Events not triggering

Verify events are enabled in the Vendo app under **OneSignal > Events**. Client-side events require the Shopify Web Pixel to be active and the user to be identified. Server-side events require the REST API Key to be configured.

### Notifications show "Delivered" but don't appear

The integration is working — the issue is with your browser or OS notification settings. Check your OS notification settings for your browser, ensure Do Not Disturb / Focus mode is off, and verify browser-level notification permissions.

***

## FAQ

### Can I change the customer identifier after setup?

Yes. Update the setting in the Vendo app under **Settings > Customer Identifier**. Changing the identifier may create separate user profiles if existing users were already identified with the previous method.

### Does the Vendo integration support mobile apps?

The Vendo integration focuses on Shopify storefronts and web push. If you also have a mobile app, ensure the identifier you select in Vendo matches the one you use in your mobile app so user profiles stay consistent.

### What happens if a visitor is never identified?

Events from unidentified visitors are not sent to OneSignal. Once the visitor identifies themselves (by subscribing to push, logging in, signing up for a newsletter, or completing checkout), Vendo begins sending events. This identified-only approach prevents duplicate users and ensures clean data.

### Why does Vendo use an identified-only approach?

Tracking anonymous visitors creates duplicate OneSignal users that can never be properly merged, leading to inflated user counts and fragmented data. The identified-only approach ensures every OneSignal user is real and actionable.

***

## Related pages

<Columns>
  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    Find your OneSignal App ID and REST API key.
  </Card>

  <Card title="Custom events" icon="bolt" href="./custom-events">
    Track user behavior and trigger automations based on Shopify events.
  </Card>

  <Card title="Web push setup" icon="globe" href="./web-push-setup">
    Set up web push notifications for your Shopify store.
  </Card>

  <Card title="Web permission prompts" icon="bell" href="./permission-requests">
    Configure how and when to prompt visitors for web push permission.
  </Card>
</Columns>


# Composing messages
Source: https://documentation.onesignal.com/docs/en/sms-composing-messages

Compose SMS, MMS, and RCS messages in OneSignal. Covers the SMS and RCS editors, character limits and encoding, message segments, trackable links, personalization, and how content affects billing.

There are two places to compose a message in OneSignal: **Templates** and **Messages** (the Dashboard). Both use the same editor. The difference is that Templates let you save reusable messages you can reference in campaigns, Journeys, or API calls, while Messages is where you compose and send a one-time message directly.

When composing from Messages, the workflow is:

1. Select an audience.
2. Select the sender for your use case.
3. Compose your message.

In Templates, you select a sender while composing (the audience is chosen at send time, when the template is referenced in a campaign, Journey, or API call).

The editor you see depends on the sender you selected. If your sender uses SMS/MMS sender resources, you get the SMS editor. If your sender includes an RCS sender resource, you get the RCS editor. Templates work the same way: you select a sender, and the editor follows it.

***

## SMS and MMS

The SMS editor lets you write plain text and optionally attach media.

* **SMS:** Text-only. Character limits depend on encoding (see below).
* **MMS:** Triggered when you attach an image, GIF, video, or audio file. Key limits:
  * Up to 1,600 characters of text
  * Up to 10 media attachments per message (5MB total across all attachments)
  * Supported formats: JPEG, PNG, GIF, video, and audio
  * Available only in the US, Canada, and Australia
  * Billed at a flat per-message MMS rate (not by segment)

### Encoding and character limits

SMS messages use one of two encodings, determined automatically by the characters in your message:

| Encoding  | Characters per segment      | Used for                                           |
| --------- | --------------------------- | -------------------------------------------------- |
| **GSM-7** | 160 (153 for multi-segment) | Standard Latin characters and common symbols       |
| **UCS-2** | 70 (67 for multi-segment)   | Emojis, accented characters, and non-Latin scripts |

When a message exceeds the per-segment limit, it splits into multiple segments, each billed separately. Multi-segment messages reserve a small header per segment for reassembly, which is why the limit is slightly lower for longer messages.

The editor shows a live character count and segment estimate as you type. A single emoji can push a one-segment message to three segments, so check the counter before sending.

<Frame>
  <img alt="OneSignal SMS composer showing a GSM-7 encoded message with segment count" />
</Frame>

<Frame>
  <img alt="OneSignal SMS composer showing a UCS-2 encoded message with segment count" />
</Frame>

### Adding a trackable link

You can add trackable links to your messages to measure click-through rates and attribute conversions back to a specific campaign. When you insert a URL, OneSignal can automatically shorten and wrap it in a tracking link. Clicks are reported in your message analytics.

<Warning>
  Use a branded custom domain for any short links in SMS. Do not use free or public shortener domains like `bit.ly`, `tinyurl.com`, or `goo.gl` in production SMS — major US carriers actively filter or block messages containing these domains.
</Warning>

<Columns>
  <Card title="Create links in the Dashboard" icon="link" href="./links#sms%2Frcs-trackable-links">
    Generate carrier-safe, trackable shortened URLs from the dashboard.
  </Card>

  <Card title="Create links via the API" icon="code" href="/reference/sms">
    Shorten and track URLs programmatically using the OneSignal API.
  </Card>
</Columns>

### Tracking multiple or personalized links

OneSignal supports one trackable link per SMS message and does not support personalization in tracked links. If you need to track more than one link or a personalized link, use one of these options:

**Option 1: UTM parameters**

Append UTM parameters to your URLs to track each link individually in Google Analytics (GA4). Since the URL is plain text in the message body, Liquid tags work directly inside it. You can personalize the URL with subscriber-specific values like `{{ subscription_id }}` and OneSignal renders the actual value per recipient at send time.

```
https://example.com/sale?utm_source=onesignal&utm_medium=sms&utm_campaign=spring_sale&utm_content=cta
```

UTM-tagged URLs can be long (150+ characters), which may push your message into additional SMS segments and increase messaging costs.

**Option 2: Third-party link management tools**

Third-party tools (Rebrandly, Short.io, Branch.io, AppsFlyer) can track clicks, shorten URLs, and brand the link.

For personalized links (unique URL per recipient), look for tools that support **parameter passthrough**, forwarding query parameters through to the destination URL. With parameter passthrough, you can use Liquid tags directly in the short link (e.g., `https://go.yourbrand.com/offer?sub_id={{ subscription_id }}`).

**Option 3: Website-side click tracking**

Track SMS link clicks by instrumenting your website to send data back to OneSignal when a subscriber lands on your page from an SMS link.

1. Include a URL in your SMS that identifies the subscriber using Liquid tags (e.g., `https://yourbrand.com/offer?uid={{ onesignal_id }}`).
2. When the subscriber clicks the link and lands on your website, fire a call to the OneSignal API to record the engagement:
   * **Custom event:** Send a custom event (e.g., `sms_click`) tied to the subscriber. Use as a trigger in Journeys or as a segmentation filter.
   * **User tag:** Update the subscriber's profile with a tag (e.g., `last_sms_click = <unix_timestamp>`). Use to segment by recency of engagement.

***

## RCS content

If your sender includes an RCS sender resource, the editor unlocks rich content capabilities:

* **Text only:** Plain branded RCS text with no media or actions. Links in the body remain tappable.
* **Cards:** A standalone rich card with an image, title, description, and up to three actions.
* **Carousels:** A horizontally scrollable set of cards. Each card can have its own image, text, and buttons. Useful for showcasing multiple products, locations, or options in a single message.
* **Actions:** Tappable buttons attached to cards. Three types are supported:
  * **Link buttons:** Open any http or https URL. You can set whether it opens in the messaging app or a new tab. This includes iOS Universal Links and Android App Links, which open directly in your app when it is installed.
  * **Keyword replies:** When a subscriber taps a keyword reply action, it sends that text back as their response without requiring them to type. Simplifies two-way interactions.
  * **Phone number:** Initiates a phone call directly from the message.

### RCS image aspect ratios

When adding an image to a rich card, the recommended aspect ratios depend on the card layout:

* **Media on top** (vertical card): 2:1, 16:9, or 7:3
* **Media on the left** (horizontal card): 3:4

Keep text, logos, and key visual elements away from the edges and centered within the frame. Each device and screen size may crop and center-zoom your image slightly differently.

### SMS fallback

You can set an SMS fallback message for when RCS fails to deliver — for example, when the recipient's device or carrier does not support RCS. OneSignal automatically sends the fallback. Note that **text-only** RCS messages always use the text set by the RCS message and do not use the SMS fallback text.

### Upgrading existing automations to RCS

When a sender gains an approved RCS sending resource, OneSignal automatically prefers RCS for all existing automations using that sender, with no manual rework. Existing SMS content is mapped to RCS automatically:

| SMS content                 | RCS content                                   |
| --------------------------- | --------------------------------------------- |
| Text only                   | Sends as RCS text (links stay tappable)       |
| Text + image                | Sends as an RCS card                          |
| Text + image + link in body | Card with a non-tappable link (action needed) |

Because a link in the body of a card is not tappable, consider upgrading these automations to richer RCS content, such as cards, carousels, and action buttons, to take full advantage of RCS.

***

## Personalization

Promotional and transactional messages are most effective when they include individualized information, such as discount codes, a user's name, an appointment time, or an order number.

<Card title="Message personalization" icon="user" href="./message-personalization">
  Use Liquid tags to insert subscriber-specific data into SMS and RCS messages.
</Card>

***

## How content affects billing

The type of content you send directly affects your messaging costs.

### SMS segments

SMS messages are billed by the number of **segments** sent, not per message. The per-segment character limit depends on encoding — see [Encoding and character limits](#encoding-and-character-limits) above for the GSM-7 and UCS-2 math.

Example billing:

* 200-character GSM-7 message = 2 segments
* 500-character GSM-7 message = 4 segments
* 100-character message with an emoji = 2 segments (encoding switches to UCS-2)

### MMS

MMS is billed at a flat per-message rate regardless of text length. See [SMS and MMS](#sms-and-mms) above for media limits and supported regions.

### RCS

RCS messages are grouped into four billing categories based on content and length:

| Billing category | Audience      | Description                                                                                                                                                           |
| ---------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Rich**         | US            | Text-only messages, or a title with body text. Cannot include actions or media. Messages longer than 160 characters are broken into segments and charged per segment. |
| **Rich Media**   | US            | Messages that include any actions (quick replies, dials, or links), a title with actions, a title with media, standalone media, or carousel content.                  |
| **Basic**        | International | Text messages up to 160 UTF-8 characters. Does not include any actions, media, or carousels.                                                                          |
| **Single**       | International | Text messages greater than 160 UTF-8 characters, up to the max message length of 3,072 characters. Can also include actions, media, or carousels.                     |

<Note>
  The billing table uses carrier-invoice vocabulary: **quick replies** are keyword reply actions, **dials** are phone number actions, and **links** are link buttons in the OneSignal editor.
</Note>

***

## FAQ

### Why did my message become 2 segments when I added an emoji?

Emojis require UCS-2 encoding, which reduces the per-segment character limit from 160 to 70 characters (67 for multi-segment messages). A message that fits in one segment as plain text can easily become 2–3 segments with an emoji added. Monitor the segment count in the editor before sending.

### Can I use a public URL shortener like bit.ly?

No. Major US carriers actively filter or block messages containing public shortener domains. Use OneSignal's built-in link shortener, a branded custom domain, or leave the full URL in the message body.

### Does MMS support all media types?

MMS supports images (JPEG, PNG, GIF), video, and audio. Total media size must be under 5MB across up to 10 media URLs. For a full list of accepted MIME types, see [Twilio's documentation](https://www.twilio.com/docs/sms/accepted-mime-types#accepted-mime-types). Note that MMS is only supported in the US, Canada, and Australia.

### What is the maximum message length for RCS?

RCS supports up to 3,072 characters. Messages over 160 UTF-8 characters fall into the "Single" billing category for international recipients.

### How do I know if my sender uses the SMS or RCS editor?

The editor is determined by the sender you select when composing a message. If your sender includes an RCS sender resource, you get the RCS editor. If your sender uses SMS/MMS sender resources only, you get the SMS editor. Templates work the same way: you select a sender, and the editor follows it.


# SMS consent keyword management
Source: https://documentation.onesignal.com/docs/en/sms-consent-keyword-management

Manage SMS opt-out keywords, resubscribe flows, and auto-responders. Covers STOP/HELP/START behavior, web-based unsubscribe for alphanumeric senders, shared sender opt-out strategies, and viewing subscriber consent status.

Managing opt-outs correctly keeps your program compliant and protects subscribers who want to stop receiving messages. How you handle opt-outs depends on your sender type: whether it can receive inbound replies or not.

***

## Opt-out keywords

`STOP`, `HELP`, and `START` are the canonical carrier-mandated compliance keywords. Their default replies are protected and cannot be changed via the OneSignal dashboard or API:

* `STOP` opts the user out of SMS messages from a specific sender. Recognized aliases (`UNSUBSCRIBE`, `CANCEL`) share the same protected reply.
* `HELP` returns information about your messaging program.
* `START` lets the user opt back in after opting out. Recognized aliases (`UNSTOP`, `YES`) share the same protected reply.

To customize a default reply, contact `support@onesignal.com` with your App ID and the new response message.

By default, when a user texts STOP, OneSignal replies: *"You have successfully been unsubscribed. You will not receive any more messages from this number. Reply START to resubscribe."*

<Note>
  By default, an opt-out only prevents messages from the specific sender the subscriber texted. This ensures opt-outs are scoped to the use case. A subscriber who texts STOP to your promotional sender continues to receive transactional messages and OTPs from your other senders.
</Note>

***

## Managing opt-outs for alphanumeric senders

Alphanumeric sender IDs (e.g., "ACME" instead of a phone number) cannot receive inbound replies, which means subscribers can't text STOP to opt out. To stay compliant, you must provide a web-based unsubscribe page that processes the opt-out and updates the subscriber's status in OneSignal via the API.

<Steps>
  <Step title="Include an unsubscribe link in every message">
    Add a URL to a hosted unsubscribe page in each SMS you send. Use OneSignal Liquid tags to identify the subscriber in the URL:

    ```
    To opt out: https://yourbrand.com/sms-unsubscribe?uid={{ onesignal_id }}
    ```

    OneSignal renders `{{ onesignal_id }}` (or `{{ subscription_id }}`) into the subscriber's actual ID at send time, so each recipient gets a personalized unsubscribe link.
  </Step>

  <Step title="Build the unsubscribe page">
    Host a simple web page at that URL. When the page loads, it reads the subscriber ID from the query parameter. The page should:

    * Confirm to the subscriber what they're opting out of (e.g., "You will no longer receive promotional text messages from ACME.")
    * Display a confirmation button. Don't auto-unsubscribe on page load, since accidental clicks and link previews could trigger unintended opt-outs.
    * Optionally let the subscriber choose which message types to opt out of, if you send multiple types from the same sender.
  </Step>

  <Step title="Call the OneSignal API to process the opt-out">
    When the subscriber confirms, call the OneSignal API to update their subscription status. Two options depending on the scope:

    * **Full unsubscribe from the sender:** Use the [Update Subscription API](/reference/update-subscription) to set the subscription's status to unsubscribed.
    * **Opt out of a specific message type:** Use the [Edit Tags API](/reference/edit-tags-with-external-user-id) to set a tag (e.g., `promo = false`), then exclude subscribers with that tag when sending that message type.
  </Step>

  <Step title="Show a confirmation">
    After the API call succeeds, display a confirmation message (e.g., "You've been unsubscribed. You will no longer receive promotional texts from ACME.").
  </Step>
</Steps>

<Card title="SMS opt-in and collection" icon="user-plus" href="./sms-opt-in-and-collection">
  Collect valid consent before sending SMS, so subscribers reach this opt-out flow only after opting in.
</Card>

***

## Managing opt-outs for shared senders

<Warning>
  We don't recommend sharing senders across text programs (promotional, transactional, or OTP). When a subscriber texts STOP, they are unsubscribed from the entire sender, meaning opting out of promotional messages would also block transactional messages like order confirmations or account alerts. Use separate senders for each use case whenever possible.
</Warning>

If you do have a shared sender, you can use custom keywords to let subscribers opt out of specific message types without unsubscribing from everything. This works by tagging subscribers when they text an opt-out keyword, then excluding those subscribers when sending that type of message.

**How it works:**

1. A subscriber texts a custom opt-out keyword to your sender (e.g., NOPROMO).
2. OneSignal applies a data tag to that subscriber's profile (e.g., `promo = false`).
3. When you send a promotional campaign, you filter your audience to exclude subscribers where `promo = false`.

**Setting up custom opt-out keywords:**

Go to **Settings > Platforms > SMS Settings > Keywords** and create a keyword for each use case you want subscribers to be able to opt out of independently.

**Example: promotional opt-out keyword (NOPROMO):**

1. Enter the keyword text (e.g., NOPROMO).
2. Set audience scope to **Anyone**.
3. Select or create a reply template (e.g., *"You've been unsubscribed from promotional messages. You'll still receive order and account notifications. Text STOP to unsubscribe from all messages."*).
4. Assign a data tag: `promo = false`.

Repeat for each use case. For transactional messages, create NOTRANSACT with `transactional = false`.

**Excluding opted-out subscribers at send time:**

When building a campaign or Journey for a specific use case, use the **User Tag** filter in Segments to exclude subscribers who have opted out. For example, when sending a promotional message, exclude subscribers where `promo = false`.

**Important limitations:**

* Default compliance keywords (STOP, HELP, START) still apply to the entire sender and cannot be scoped to a use case.
* You must include the custom opt-out keyword in every message of that type (e.g., *"Reply NOPROMO to stop promotional texts"*).
* Alphanumeric sender IDs cannot receive replies and do not support keywords.
* Reply syncing must be enabled. Go to **Settings > Platforms > SMS Settings > Senders > Setup Replies**.

<Card title="SMS keywords" icon="message" href="./keywords">
  Full reference for setting up custom keywords, including two-way campaigns and preference centers.
</Card>

***

## Resubscribing

Once a user has opted out using a default opt-out keyword, they cannot be resubscribed through the OneSignal dashboard or API. The user must text a resubscribe keyword (`START`, `UNSTOP`, or `YES`) to the same sender number.

***

## HELP keyword

By default, when a user texts HELP, OneSignal replies: *"Reply STOP to unsubscribe. Msg\&Data Rates May Apply."*

***

## Auto-responder

Set an auto-reply for any incoming message that doesn't match a keyword. Use this to redirect users to customer support, collect their intent, or notify your team for follow-up.

<Steps>
  <Step title="Go to Auto-Responder settings">
    Navigate to **Settings > Platforms > SMS Settings > Auto-Responder**.
  </Step>

  <Step title="Add an auto-responder">
    Click **Add Auto-Responder** and select a reply template.
  </Step>

  <Step title="Optionally tag the user">
    Assign a data tag when the auto-responder fires to enable future segmentation or alerting.
  </Step>
</Steps>

***

## Viewing a subscriber's opt-out status

To see which senders a subscriber is opted out of:

1. Go to **Audience > Subscriptions** in the OneSignal dashboard.
2. Search for the subscriber by External ID, email, or phone number.
3. Open their SMS subscription and look under **Consent by Sender**.

This section shows the opt-in or opt-out status for each sender associated with that subscription.

***

## FAQ

### What happens when a user texts STOP to a shared sender?

They are opted out of all messages from that sender, including transactional messages and OTPs. This is why we strongly recommend using separate senders for each program type. Once opted out via STOP, the user must text START (or another resubscribe keyword) to the same sender to receive messages again.

### Can I change the STOP or HELP response messages?

Yes, but not via the dashboard or API. Contact `support@onesignal.com` with your App ID and the new response text.

### What opt-out mechanism do I use for alphanumeric sender IDs?

Alphanumeric sender IDs cannot receive replies, so you must include an unsubscribe link in every message and build a web-based unsubscribe page that calls the OneSignal API to process the opt-out. See the [Managing opt-outs for alphanumeric senders](#managing-opt-outs-for-alphanumeric-senders) section above.

### Can I re-subscribe a user who texted STOP?

You cannot re-subscribe a user through the dashboard or API. The user must text START, UNSTOP, or YES to the same sender number to opt back in.

### How do I prevent a single STOP from blocking all message types?

Use separate senders for each program type (promotional, transactional, OTP). If you must use a shared sender, set up custom opt-out keywords (e.g., NOPROMO) and exclude opted-out subscribers by tag at send time. Note that the default STOP keyword still unsubscribes from the entire sender.


# SMS message reports
Source: https://documentation.onesignal.com/docs/en/sms-message-reports

View SMS and RCS delivery statistics, click-through rates, and failure details in OneSignal. Covers all message metrics, error code troubleshooting, data retention, and how to export data.

SMS message reports give you delivery statistics, engagement metrics, and recipient-level detail for each message you send. Reports are available for both SMS/MMS and RCS messages.

***

## Metrics reference

### Message-level metrics

| Metric                   | Definition                                                                                                                                                                                                |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sent**                 | The number of messages sent from OneSignal, including both those successfully sent to the carrier and failures.                                                                                           |
| **Audience**             | The number of subscriptions in the targeted segment(s).                                                                                                                                                   |
| **Remaining**            | The number of subscriptions in the target audience that haven't yet received the message (queued or in flight). Appears on the dashboard delivery report.                                                 |
| **Delivered**            | The number of messages successfully delivered to the carrier. Shown separately for SMS/MMS and RCS in the report.                                                                                         |
| **Failed**               | The number of messages that failed to be sent to the carrier.                                                                                                                                             |
| **Suppressed**           | The number of messages not sent because the subscription has opted out of receiving messages from the sender.                                                                                             |
| **Rejected**             | The number of messages not delivered by the carrier due to number blockage, velocity blockage, or a recipient block list. This is a derived metric: the sum of Provider Errored and Provider Undelivered. |
| **Provider Errored**     | The number of subscriptions for which the carrier failed to send the message.                                                                                                                             |
| **Provider Undelivered** | The number of subscriptions for which the carrier sent the message but failed to deliver it.                                                                                                              |
| **Read** *(RCS only)*    | The number of subscriptions who read an RCS message. Available because RCS supports read receipts.                                                                                                        |
| **Total Clicks**         | The total number of times a link in the message was clicked, including repeat clicks.                                                                                                                     |
| **Unique Clicks**        | The number of unique link clicks. Counted once per subscription.                                                                                                                                          |
| **Replied**              | The number of inbound replies that matched a custom keyword. Excludes consent keywords (STOP, HELP, START).                                                                                               |
| **Unsubscribed**         | The number of inbound opt-out keyword replies received (e.g., STOP).                                                                                                                                      |

### Report-level metrics

| Metric                       | Description                                                                                                             |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Delivery rate**            | The percentage of messages successfully delivered.                                                                      |
| **Failure & rejection rate** | The percentage of messages not delivered or suppressed.                                                                 |
| **Click-through rate (CTR)** | The percentage of total recipients who clicked a link in this message. See [Links](./links) for more on click tracking. |

For metric definitions across all channels, see the [Metrics glossary](./analytics-metrics-glossary).

***

## Data retention

SMS messages and related report data are retained for approximately **30 days**. Export message or audience data if you need long-term records. See [Exporting data](./exporting-data).

***

## Conversions

<Note>
  Coming soon: [Conversion metrics](./conversion-metrics) on message reports. Once available, you will see attributed and influenced conversions for each message directly in its report.
</Note>

***

## Understanding SMS failures

When troubleshooting deliverability, look at the **exact error text** in Audience Activity.

| Error text                          | Error code                                            | What it usually means                                                                                                                                                                                    | What to do                                                                                                                                                                |
| ----------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Message blocked**                 | [30004](https://www.twilio.com/docs/api/errors/30004) | The carrier or a policy layer blocked the message. Common causes: carrier content filtering, sender reputation, 10DLC/registration issues, recipient opt-out state, or regional rules (e.g., India DLT). | Confirm opt-in and STOP handling. Align content with your registered use case. Complete 10DLC/brand registration where required. Avoid spam-like patterns.                |
| **Unknown destination handset**     | [30005](https://www.twilio.com/docs/api/errors/30005) | The number is unknown, invalid, or no longer active (wrong digits, disconnected line, or mistyped country code).                                                                                         | Validate and normalize numbers to E.164 before sending. Remove landlines and invalid numbers. See [Audience validation](./sms-opt-in-and-collection#audience-validation). |
| **Unreachable destination handset** | [30003](https://www.twilio.com/docs/api/errors/30003) | The number may be valid but the handset is off, out of coverage, or roaming in a way that blocks SMS.                                                                                                    | Retry later.                                                                                                                                                              |

Other numeric codes can appear. Search the [Twilio errors index](https://www.twilio.com/docs/api/errors) for the code shown in Audience Activity. OneSignal SMS uses Twilio infrastructure, so these codes apply to both setups.

### Messages with no error text

Some failures return no error text or an empty reason field when the carrier or provider does not supply a detailed code. In the dashboard, these often roll up under **Failed to Send**. Recommended steps:

1. Confirm the number is valid E.164 and the subscription is SMS-eligible and not opted out.
2. Retry after a delay in case of transient provider or carrier issues.
3. If the issue is widespread, collect example message or delivery SIDs and contact OneSignal support.

***

## Billing

### OneSignal SMS customers

View your usage under **Settings > Usage > SMS > See breakdown**. The breakdown shows segments (not messages) sent by message type, filterable by country. The breakdown is updated daily.

The count includes all outbound segments, including auto-replies sent in response to consent keywords (STOP, HELP, START) or other custom keyword replies. Failed messages are not included in the segment count.

### Twilio integration customers

You pay Twilio directly. For billing questions, see your Twilio dashboard.

***

## FAQ

### Why does my delivery rate show lower than expected?

Common causes include invalid phone numbers, opted-out subscribers (showing as Suppressed), carrier-side content filtering, or registration issues (showing as Rejected or Provider Errored). Check the error text in Audience Activity for the specific cause.

### What's the difference between Failed and Rejected?

Failed means OneSignal could not send the message to the carrier at all. Rejected means the carrier received the message but did not deliver it, typically due to number blockage, velocity limits, or the recipient being on a block list.

### How long are message reports available?

SMS message reports and audience activity data are retained for approximately 30 days. Export your data if you need longer retention.

### Can I see which individual subscribers received a message?

Yes. The Audience Activity section of each message report shows recipient-level delivery and engagement details, including any error codes for failed messages.

### Why do some messages have no error code?

Some carriers and providers do not return detailed error codes for failed deliveries. These show up as empty in Audience Activity. If you see widespread failures with no error detail, collect the message SIDs and contact OneSignal support.

***

## Related pages

<Columns>
  <Card title="Composing messages" icon="pencil" href="./sms-composing-messages">
    Encoding, segment math, MMS limits, and how content affects billing.
  </Card>

  <Card title="SMS opt-in and collection" icon="user-plus" href="./sms-opt-in-and-collection">
    Audience validation and phone number format requirements.
  </Card>

  <Card title="Exporting data" icon="file-export" href="./exporting-data">
    Export delivery and engagement data for long-term retention.
  </Card>

  <Card title="Links" icon="link" href="./links">
    How OneSignal tracks clicks in SMS, MMS, and RCS messages.
  </Card>
</Columns>


# SMS, MMS, and RCS overview
Source: https://documentation.onesignal.com/docs/en/sms-messaging

Send text messages with OneSignal. Covers SMS, MMS, and RCS formats, the three texting program types (promotional, transactional, OTP), and setup paths for each use case.

Text reaches subscribers on the phone number they use everywhere, making it one of the most direct channels available. OneSignal supports three message formats:

* **SMS:** text-only messages up to 160 characters. Supports plain text, numbers, and emojis.
* **MMS:** extends SMS with rich media: images, video, audio, and GIFs. Supports up to 1,600 characters of text alongside the attachment.
* **RCS** (Rich Communication Services): branded, app-like experiences with buttons, carousels, keyword replies, and read receipts. Requires a dedicated RCS sender resource.

***

## Types of texting programs

OneSignal supports three types of texting programs. Each has different consent requirements, sender configurations, and compliance rules.

<Columns>
  <Card title="Promotional messaging" icon="tag" href="./sms-promotional-messaging">
    Sales, flash offers, abandoned carts, product launches, and re-engagement campaigns.
  </Card>

  <Card title="Transactional messaging" icon="bell" href="./sms-transactional-messaging">
    Order confirmations, shipping updates, appointment reminders, and account alerts.
  </Card>

  <Card title="One-time passwords" icon="lock" href="./sms-verify">
    Verification codes, two-factor authentication, and account security messages.
  </Card>
</Columns>

<Warning>
  Each program type requires a **dedicated sender**. If a subscriber texts STOP to a shared sender, they are opted out of all messages from that sender, including transactional messages and OTPs they still want. Use separate senders per program.
</Warning>

***

## Set up SMS

Before sending, you need a brand, a sender, and at least one approved sender resource.

<Columns>
  <Card title="SMS setup" icon="gear" href="./sms-setup">
    Understand brands, senders, and sender resources. Choose between OneSignal SMS and Twilio integration.
  </Card>

  <Card title="Sender resource applications" icon="file-check" href="./sms-registration-requirements">
    Apply for sender resources by country and type. Includes per-country approval timelines and requirements.
  </Card>

  <Card title="Opt-in and collection" icon="user-plus" href="./sms-opt-in-and-collection">
    Collect valid consent for promotional, transactional, and OTP programs.
  </Card>

  <Card title="Consent keyword management" icon="shield" href="./sms-consent-keyword-management">
    Manage STOP, HELP, START, and custom opt-out keywords.
  </Card>
</Columns>

***

## Send messages

<Columns>
  <Card title="Composing messages" icon="pencil" href="./sms-composing-messages">
    SMS/MMS and RCS editors, character limits, segments, trackable links, and billing categories.
  </Card>

  <Card title="SMS keywords" icon="message" href="./keywords">
    Two-way keyword campaigns, preference centers, and auto-responders.
  </Card>

  <Card title="Journeys" icon="map" href="./journeys-overview">
    Automate multi-step messaging flows triggered by user actions.
  </Card>

  <Card title="API" icon="code" href="/reference/create-message">
    Send messages programmatically via the REST API.
  </Card>
</Columns>

***

## Analytics and compliance

<Columns>
  <Card title="SMS message reports" icon="chart-bar" href="./sms-message-reports">
    Delivery metrics, click-through rates, and failure troubleshooting.
  </Card>

  <Card title="Regulatory compliance" icon="scale" href="./sms-regulatory-compliance">
    Consent standards, quiet hours, prohibited content, and fraud prevention.
  </Card>
</Columns>

***

## Supported countries

OneSignal supports sending text messages to the following countries:

| Americas      | Europe         | Asia                 | Oceania     |
| ------------- | -------------- | -------------------- | ----------- |
| Argentina     | Austria        | Hong Kong            | Australia   |
| Brazil        | Belgium        | India                | New Zealand |
| Canada        | Denmark        | Japan                |             |
| Chile         | Finland        | Macao                |             |
| Mexico        | France         | Malaysia             |             |
| Peru          | Germany        | Philippines          |             |
| Puerto Rico   | Iceland        | Singapore            |             |
| United States | Ireland        | South Korea          |             |
|               | Italy          | Taiwan               |             |
|               | Luxembourg     | Thailand             |             |
|               | Netherlands    | Turkey               |             |
|               | Norway         | United Arab Emirates |             |
|               | Poland         |                      |             |
|               | Portugal       |                      |             |
|               | Spain          |                      |             |
|               | Sweden         |                      |             |
|               | Switzerland    |                      |             |
|               | United Kingdom |                      |             |

For country-specific sender resource types, approval timelines, and compliance requirements, see [Sender resource applications](./sms-registration-requirements).


# SMS opt-in and collection
Source: https://documentation.onesignal.com/docs/en/sms-opt-in-and-collection

Collect valid SMS consent for promotional, transactional, and OTP programs. Covers opt-in collection methods, disclosure requirements, audience validation, and phone number format requirements.

Collecting valid consent is the foundation of a compliant SMS program. The method and disclosure language you need depend on the type of program you are running: promotional, transactional, or OTP.

***

## Promotional opt-ins

Promotional messages require the highest standard of consent. The subscriber must take an affirmative action to opt in.

### Opt-in collection methods

#### Web sign-up form

A form on your website, landing page, or pop-up where subscribers enter their phone number. Requirements:

* The SMS opt-in checkbox must be **unchecked by default**.
* Disclosure language must appear **on the same form**, above the submit button, not linked away or buried.
* SMS consent must be **collected separately** from email consent.

#### Text-to-subscribe keyword

Subscribers text a keyword to your sender number to opt in (for example, "Text DISCOUNT to 58120"). You define the keyword and the confirmation message sent back.

<Tip>
  With iOS 26, messages from numbers not saved as contacts are filtered into a separate "Unknown Senders" folder. Because text-to-subscribe has the subscriber send the first message, your number appears in their message history before you respond, making it a known sender. This is one of the best collection methods for iOS inbox visibility.
</Tip>

#### QR code

A QR code that opens the subscriber's SMS app with your sender number and keyword pre-populated. Ideal for in-store signage, product packaging, receipts, and events.

To create one, use an SMS QR code generator that supports the `sms:` URL format (for example, [QR Code Dynamic](https://qrcodedynamic.com/qr/sms) or [QRKIT](https://useqrkit.com/sms-qr-code)). The underlying URL format is `sms:+[phone_number]?body=KEYWORD`. For an RCS agent, use `sms:+[phone_number]?service_id=[your_agent_id]%40rbm.goog&body=MESSAGE`. You can find your phone number and agent ID in **Settings > Senders**.

Wherever you share the QR code, include disclosure language on the same surface: program description, message frequency, "Msg & data rates may apply," and opt-out instructions.

<Tip>
  Like text-to-subscribe, QR codes establish your number as a known sender before you reply, giving them the same iOS 26 inbox visibility advantage.
</Tip>

#### Checkout and point-of-sale

Collect opt-ins at the moment of purchase. The opt-in must be a separate, unchecked checkbox and cannot be framed as required for order confirmations or delivery updates.

#### Physical sign-up form

Collect phone numbers on a printed form at retail locations, events, or service counters. Include the same disclosure language required for digital opt-ins. Import these subscribers via CSV or API. See [Importing subscribers](./import).

#### Email

An opt-in prompt in an existing email campaign asking subscribers to also join your SMS list. Having an email address does not imply SMS consent. The subscriber must actively opt in through a separate action.

For code examples, see the [OneSignal signup form examples](https://github.com/OneSignalDevelopers/signup-form-examples) and [email and SMS collection sample](https://github.com/OneSignalDevelopers/email-sms-collection-sample) on GitHub.

### Required disclosure language

Every promotional opt-in disclosure must cover:

* Your brand name
* That the subscriber will receive recurring automated **marketing** messages
* Message frequency (approximate)
* "Msg & data rates may apply"
* How to opt out (STOP)
* Links to your Terms of Service and Privacy Policy
* A statement that consent is not a condition of purchase

<Warning>
  The program description must **explicitly state the messages are for marketing.** Vague language like "updates" or "information" is not sufficient. Pre-checked checkboxes are non-compliant everywhere.
</Warning>

***

## Transactional opt-ins

Transactional messages have a lower consent bar than promotional messages. A user entering their phone number in a form that includes disclosure language is sufficient opt-in. No separate checkbox is required.

The disclosure must appear directly on or near the phone number field. It cannot be on a separate page or buried in terms of service.

### Common collection points by use case

| Use case                                         | Where to collect                      |
| ------------------------------------------------ | ------------------------------------- |
| Order confirmations and shipping updates         | Checkout, near the phone number field |
| Account notifications (security alerts, billing) | Account creation or sign-up form      |
| Appointment reminders                            | Booking or scheduling form            |
| Onboarding sequences                             | Account creation or profile setup     |
| Notification preferences                         | In-app or web preferences page        |

### Required disclosure language

Every transactional opt-in disclosure must include:

* Your **brand name**
* The **specific types of messages** the user will receive (for example, "order confirmation and shipping update text messages," rather than just "messages" or "updates")
* **"Msg & data rates may apply"**
* How to **opt out** (for example, "Reply STOP to opt out")

<Warning>
  **A phone number alone is not consent.** If your form collects a phone number but has no disclosure text, you don't have consent to send text messages.

  **Consent is scoped to the stated purpose.** If a user consented to receive shipping updates at checkout, that does not cover sending them appointment reminders from a different part of your business.
</Warning>

***

## OTP opt-ins

Consent for one-time password messages follows the same standard as transactional messages. A user entering their phone number in a form that includes disclosure language is sufficient.

Every OTP opt-in disclosure must include:

* Your **brand name**
* The **specific types of messages** the user will receive (for example, "verification codes and security alerts")
* **"Msg & data rates may apply"**
* How to **opt out** (for example, "Reply STOP to opt out")

***

## Audience validation

A clean subscriber list improves deliverability, reduces costs, and keeps your program compliant.

### Validate phone numbers with Lookup

Before adding a number to your subscriber list, use OneSignal's Lookup to verify it. Lookup checks whether a phone number is valid, active, and mobile, filtering out landlines, VoIP numbers, disconnected lines, and mistyped numbers before they ever receive a message.

Run Lookup at the point of collection (for example, on form submission) or as a batch operation on your existing subscribers.

### Only collect numbers for regions you can send to

Make sure you're only collecting phone numbers in geographies where you have a sender with an approved sender resource for that geography. If you don't have a sender with an approved sender resource for a given country, messages to numbers in that country will fail.

### Verify ownership with a one-time password

Lookup confirms a number is valid, but it doesn't confirm the person signing up actually owns that number. To close that gap, send a one-time password immediately after the subscriber enters their phone number. See [One-time passwords](./sms-verify) for how to set up OTPs with OneSignal Verify or your own backend.

### Collect numbers in E.164 format

Phone numbers should be stored in E.164 format: a country code followed by the subscriber number with no spaces, dashes, or parentheses (for example, `+14155551234`). This is the format carriers and messaging platforms expect.

If your sign-up form accepts free-text phone input, validate and normalize the number to E.164 before saving it. OneSignal's API and CSV import both expect E.164 format.

***

## Branding your sender with a contact card

A contact card (vCard) lets subscribers save your business as a contact on their phone. Once saved, your brand name and logo appear in place of an unknown phone number. This improves visibility, reduces the chance messages are ignored, and helps you avoid the iOS "Unknown Senders" inbox.

You deliver a contact card by sending a `.vcf` file as an MMS message.

### Create your vCard file

Create a `.vcf` file with your business contact information. You can use an online vCard generator or write it in a text editor. The format is plain text:

```
BEGIN:VCARD
VERSION:3.0
FN:Your Business Name
ORG:Your Business Name
TEL;TYPE=CELL:+15551234567
END:VCARD
```

Use the same phone number as your SMS sender identity. You can optionally include a `PHOTO` property with your brand logo to have it appear alongside the contact name.

### Host the file at a public URL

The `.vcf` file must be accessible via a direct, publicly reachable URL, not a download page or preview. Host it on your CDN, web server, or cloud storage (AWS S3, Google Cloud Storage) with public read access enabled.

### Send the contact card

<Steps>
  <Step title="Create a new SMS message">
    In the OneSignal dashboard, create a new SMS message.
  </Step>

  <Step title="Attach the vCard URL">
    In the **Media URL** field, paste the public URL to your hosted `.vcf` file.
  </Step>

  <Step title="Add the message body">
    Encourage the subscriber to save your contact, for example: *"Save our contact so you always know it's us! Tap the attachment to add us to your contacts."*
  </Step>

  <Step title="Send it as part of your welcome flow">
    Send it when a new subscriber opts in, so your number is recognized before any future messages arrive.
  </Step>
</Steps>

<Note>
  Sending a contact card uses the media URL field, which means the message is sent as MMS and billed at MMS rates.
</Note>

***

## FAQ

### What's the difference between promotional and transactional consent?

Promotional messages require express written consent, an affirmative action like checking an unchecked box or texting a keyword. Transactional messages have a lower bar: a user entering their phone number in a form where disclosure language is visible is sufficient. The disclosure must be present and specific about what types of messages they'll receive.

### Do I need double opt-in for all promotional programs?

Double opt-in is required for cart abandonment programs in the US. For other promotional programs it is optional, but strongly recommended — it reduces spam complaints, improves list quality, and provides stronger consent documentation.

### Can I collect SMS and email consent on the same form?

You can use the same form, but you must collect consent for each channel separately. Bundling SMS consent with email consent (for example, a single checkbox for both) is non-compliant for SMS.

### Can I import subscribers from another provider?

Yes, if they have already provided valid consent that meets the requirements for the program type you are running. See [Importing subscribers](./import) for how to transfer existing subscribers via CSV or API.

### What is E.164 format?

E.164 is the international standard phone number format: a plus sign, country code, and subscriber number with no spaces or punctuation (for example, `+14155551234` for a US number). OneSignal's API and CSV import require numbers in this format.

### Why should I use Lookup before adding subscribers?

Sending to invalid, landline, or disconnected numbers wastes spend and can hurt your sender reputation with carriers. Lookup filters these out before they reach your list, which improves deliverability and reduces costs.

***

## Related pages

<Columns>
  <Card title="Consent keyword management" icon="shield" href="./sms-consent-keyword-management">
    Manage STOP, HELP, START, and custom opt-out keywords after subscribers opt in.
  </Card>

  <Card title="Regulatory compliance" icon="scale" href="./sms-regulatory-compliance">
    Carrier rules, quiet hours, prohibited content, and the broader regulatory framework.
  </Card>

  <Card title="One-time passwords" icon="lock" href="./sms-verify">
    Set up OTPs with OneSignal Verify or your own backend to verify number ownership.
  </Card>

  <Card title="Promotional messaging" icon="tag" href="./sms-promotional-messaging">
    Promotional-specific patterns: double opt-in setup, preference centers, and sending guidance.
  </Card>
</Columns>


# Promotional messaging
Source: https://documentation.onesignal.com/docs/en/sms-promotional-messaging

Send SMS and MMS promotional campaigns with OneSignal. Covers double opt-in setup, preference centers, sender strategy, and sending via Dashboard, Journeys, or API.

Promotional messages include sales and discounts, abandoned cart reminders, new product launches, seasonal promotions, loyalty and reward programs, limited-time offers, referral programs, and re-engagement campaigns.

Texting requires explicit consent and an easy way for users to opt out. The people receiving your promotional messages have actively chosen to hear from you, which means they are often your most engaged audience.

***

## Collecting opt-ins

Promotional opt-in collection methods, required disclosure language, and audience validation are covered on the dedicated opt-in and collection page.

<Card title="SMS opt-in and collection" icon="user-plus" href="./sms-opt-in-and-collection">
  Web sign-up forms, text-to-subscribe, QR codes, checkout opt-ins, disclosure language requirements, and phone number validation.
</Card>

<Note>
  If you have multiple senders for different use cases (for example, promotional and transactional), collect which use case the subscriber is opting into as a data tag. This ensures you can route subscribers to the correct sender and keep opt-ins scoped to the right program.
</Note>

### Double opt-in

Double opt-in adds a confirmation step after initial sign-up: the subscriber receives a text asking them to reply with a keyword (for example, `Y` or `SUBSCRIBE`) to confirm.

* **Required for cart abandonment programs in the US.**
* Strongly recommended for any high-volume promotional program, as it reduces spam complaints, improves list quality, and provides stronger consent documentation.

<Frame>
  <img alt="OneSignal Consent Management screen with double opt-in toggle and Add Text-To-Subscribe Keyword modal" />
</Frame>

<Steps>
  <Step title="Go to SMS consent settings">
    Navigate to **Settings > Platforms > SMS Settings > Consent Management**.
  </Step>

  <Step title="Enable the confirmation prompt">
    Click **Edit** next to Double Opt-In and toggle on **Send Message Prompt**. Select or create an SMS template for the confirmation message (for example, *"Reply SUBSCRIBE to start receiving exclusive offers. Msg & data rates may apply. Reply STOP to opt out."*).
  </Step>

  <Step title="Create the confirmation keyword">
    Create a **Text to Subscribe keyword** (for example, `Y` or `SUBSCRIBE`) that marks the subscriber as active when they reply. Select a template for the reply message (for example, *"Brand Name: Thanks for subscribing! Reply STOP to opt out at any time."*).
  </Step>

  <Step title="Enable reply syncing">
    Make sure reply syncing is enabled under **SMS Settings > Senders > Setup Replies**. Without this, OneSignal cannot receive the subscriber's confirmation and update their status.
  </Step>
</Steps>

### Importing existing subscribers

If you have an existing list of subscribers who have already provided consent, from a prior SMS provider, a physical sign-up form, or another system, see [Importing subscribers](./import) to transfer consent into OneSignal via CSV or API.

**Re-subscribe behavior:** By default, when a user texts START, UNSTOP, or YES, OneSignal re-subscribes the user and replies with: *"You have successfully been re-subscribed to messages from this number. Reply HELP for help. Reply STOP to unsubscribe. Msg\&Data Rates May Apply."* OneSignal SMS users can update this reply by contacting support.

***

## Preference centers

A preference center lets subscribers self-select the types of messages they want to receive. Rather than a single all-or-nothing opt-out, subscribers can opt in or out of specific lists by texting a keyword. Common preference lists include seasonal promotions, product categories, restock alerts, and VIP offers.

OneSignal tracks these preferences as data tags on each subscriber's profile, which you then use to target the right audience at send time.

<Note>
  This preferences approach is for managing preferences within a single use case (for example, Fall discounts vs. Spring promotions, all under a marketing program). It is not intended for separating promotional opt-outs from transactional opt-outs. See [Consent keyword management](./sms-consent-keyword-management) for that.
</Note>

### How preference centers work

1. A subscriber texts a keyword to your sender (for example, `FALL`).
2. OneSignal applies a data tag to that subscriber's profile (for example, `fall = true`).
3. When you send a campaign, you filter your audience to subscribers who have that tag.

### Set up a preference center

Go to **Settings > Platforms > SMS Settings > Keywords** and create a keyword pair for each subscription list, one to subscribe and one to unsubscribe.

#### Subscribe keyword

For each list, create a subscribe keyword (for example, `FALL`):

1. Enter the keyword text (for example, `FALL`).
2. Set audience scope to **Anyone**.
3. Select or create a reply template (for example, *"You're subscribed to Fall promotions! Text NOFALL to unsubscribe anytime."*).
4. Assign a data tag: `fall = true`.

#### Unsubscribe keyword

Create the matching unsubscribe keyword (for example, `NOFALL`):

1. Enter the keyword text (for example, `NOFALL`).
2. Select or create a reply template (for example, *"You've been unsubscribed from Fall promotions. Text FALL to resubscribe anytime."*).
3. Assign a data tag: `fall = false`.

Repeat this pair for each list. For a Spring list, create `SPRING` (`spring = true`) and `NOSPRING` (`spring = false`).

### Requirements

* Reply syncing must be enabled. Go to **SMS Settings > Senders > Setup Replies**.
* Alphanumeric sender IDs cannot receive replies and do not support keywords.

### Target subscribers by preference

When building a campaign or Journey, use the **User Tag** filter in Segments:

* Send a Fall promotion to subscribers where `fall = true`.
* Exclude subscribers where `fall = false`.

### Promote your preference center

Tell subscribers which keywords are available in your welcome message (for example, *"Text FALL for Fall deals, SPRING for Spring deals, or STOP to unsubscribe from all."*).

For full keyword setup details, see [SMS keywords](./keywords).

***

## Sending

| Use case                         | Sending method      | Why                                                                                                   |
| -------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
| **Promotional blast**            | Dashboard: Messages | Best for one-time sends to a segment; schedule in advance or send immediately                         |
| **Cart abandonment**             | Journeys            | Trigger-based automation off a cart event; supports delays and conditional branching                  |
| **Upsell / re-engagement flows** | Journeys            | Multi-step sequences with time delays and audience conditions                                         |
| **API-triggered promotions**     | API                 | Best when your backend controls the trigger (for example, a personalized offer generated server-side) |

### Before you send

* **Quiet hours:** Promotional messages must respect local quiet hours. Use Journey time windows to ensure messages send within permitted hours. See [Regulatory compliance](./sms-regulatory-compliance#quiet-hours) for quiet hours by country.
* **Sender name:** Include your brand name in the message body so recipients know who is texting them.
* **Opt-out instruction:** Every promotional message must include a STOP instruction (for example, "Reply STOP to opt out").

### Composing your message

For guidance on composing your message, including character limits, segments, MMS, and trackable links, see [Composing messages](./sms-composing-messages).

If you have an RCS sender, you can also send rich content: branded cards, carousels, and action buttons. See [Composing messages](./sms-composing-messages#rcs-content) for what's available.

### Two-way keyword campaigns

Promotional SMS doesn't have to be one-directional. You can run keyword-based engagement campaigns where subscribers reply to interact, including polls, surveys, preference collection, and content unlocks.

Include a CTA in your message asking subscribers to reply with a keyword (for example, "Reply EA for early access"). When OneSignal receives the keyword, it triggers an automated reply and optionally applies a data tag for future segmentation.

See [SMS keywords](./keywords) for full setup instructions.

***

## FAQ

### Do I need double opt-in for all promotional programs?

Double opt-in is required for cart abandonment programs in the US. For other promotional programs it is optional, but strongly recommended, as it reduces spam complaints, improves list quality, and provides stronger consent documentation.

### Can I use the same sender for promotional and transactional messages?

Technically yes, but it is not recommended. If a subscriber texts STOP to a shared sender, they are opted out of all messages from that sender, including order confirmations or account alerts they still want. Use separate senders per program to keep opt-outs cleanly scoped.

### What disclosure language is required at opt-in?

Every promotional opt-in must include: your brand name, that the subscriber will receive recurring automated marketing messages, approximate message frequency, "Msg & data rates may apply," how to opt out (STOP), and links to your Terms of Service and Privacy Policy.

### Can I import subscribers from another provider?

Yes, if they have already provided valid consent. See [Importing subscribers](./import) for how to transfer existing subscribers via CSV or API.

***

## Related pages

<Columns>
  <Card title="SMS opt-in and collection" icon="user-plus" href="./sms-opt-in-and-collection">
    Collection methods, required disclosure language, and audience validation for all program types.
  </Card>

  <Card title="Consent keyword management" icon="shield" href="./sms-consent-keyword-management">
    Manage STOP, HELP, START, and custom opt-out keywords after subscribers opt in.
  </Card>

  <Card title="SMS keywords" icon="comment-dots" href="./keywords">
    Full setup details for keyword-triggered replies, tags, and two-way campaigns.
  </Card>

  <Card title="Composing messages" icon="pen-to-square" href="./sms-composing-messages">
    Character limits, MMS, trackable links, and RCS rich content.
  </Card>
</Columns>


# Sender resource applications and country requirements
Source: https://documentation.onesignal.com/docs/en/sms-registration-requirements

Apply for SMS and RCS sender resources by country. Covers brand and campaign approval processes, standard application requirements, sender resource type traits, and per-country approval tables for all supported geographies.

Every sender resource must be approved before you can send messages on it. The approval process verifies that your brand is legitimate and that your messaging program meets carrier and regulatory requirements for that country.

There are generally two steps to every sender resource application:

1. **Brand vetting:** Proves your organization is a legitimate business. You submit company information (legal name, address, tax ID, website) and a vetting body reviews it.
2. **Campaign approval:** Proves your specific messaging program is compliant. You submit sample messages, your opt-in and opt-out flows, and a description of the use case. A single brand can have multiple campaigns (for example, one for promotional, one for transactional, and one for OTP).

***

## Tracking approval status

Once you submit an application, you can track each sender resource's carrier approval status in the dashboard at **Settings > SMS > Senders**.

***

## Sender resource types

These traits apply universally across all countries. Country-specific requirements are listed in the sections below.

**Alphanumeric sender IDs:**

* One-way only: alphanumeric sender IDs **cannot receive inbound messages**. STOP keyword handling, double opt-in, tap-to-text, and two-way messaging are not available. Opt-out must be managed via an unsubscribe link in the message body. See [Consent keyword management](./sms-consent-keyword-management#managing-opt-outs-for-alphanumeric-senders) for how to build a web-based unsubscribe flow.

**Long codes:**

* Two-way: long codes **can receive inbound messages**, enabling STOP/HELP keywords, double opt-in, tap-to-text, and two-way messaging.
* MMS support varies by country.

**Short codes:**

* Two-way: short codes can receive inbound messages.
* Country-specific: a short code only works in the country where it is provisioned.
* Highest throughput of any SMS number type.
* Longest approval timelines (weeks to months) and typically require a premium monthly fee.
* Not available in every country.

**Toll-free numbers:**

* Two-way: toll-free numbers can receive inbound messages.
* Available in the US and Canada only. The same toll-free number covers both countries.

**RCS:**

* Two-way: RCS supports inbound messages, keyword replies, and action buttons.
* Branded sender: recipients see your business name, logo, and brand color instead of a phone number.
* Requires a separate RCS sender resource in addition to an SMS sender resource. SMS is used as an automatic fallback when the recipient's device or carrier does not support RCS.
* Not available in every country.

***

## Application management

**OneSignal SMS customers:** Our compliance team handles carrier and regulator interactions on your behalf. Whether the reviewer listed in the country tables below is "OneSignal" or a third-party body (like TCR in the US, ACMA in Australia, or ComReg in Ireland), OneSignal submits to those bodies on your behalf.

**Twilio integration customers:** You work with Twilio directly through their console or support team to manage sender resource applications, brand registration, and campaign approvals. Twilio submits to those bodies on your behalf.

***

## Standard information required for every application

Regardless of country or sender resource type, every application requires the following. Prepare this before starting:

**Brand information:**

* Legal company name
* Company address
* Tax ID or business registration number (format varies by country)
* Company website URL
* Vertical / industry

**Campaign information:**

* Use case type (promotional, transactional, OTP, or mixed)
* Sample messages (typically 2–5 examples of real message content)
* Opt-in flow description with screenshots or description of the collection point and disclosure language
* Opt-out flow description (for example, STOP keyword handling, confirmation reply, or unsubscribe link for alphanumeric sender IDs)
* HELP keyword response
* Message frequency (approximate volume per subscriber)
* Privacy policy URL
* Terms of service URL

Some countries require additional information beyond this standard set. Those are called out in each country section below.

***

## Americas

Sender resource types, reviewers, and approval timelines for markets across North, Central, and South America.

### United States

**Types:** Toll-free number, 10DLC, Short code, RCS

|                       | Toll-free         | 10DLC                           | Short code                                             | RCS                          |
| --------------------- | ----------------- | ------------------------------- | ------------------------------------------------------ | ---------------------------- |
| **Brand reviewer**    | ZipWhip           | The Campaign Registry (TCR)     | Aegis (CTIA) + individual carriers                     | Google + Individual carriers |
| **Campaign reviewer** | OneSignal         | Direct Connect Aggregator (DCA) | Common Short Code Administration + individual carriers | Google + Individual carriers |
| **Approval timeline** | 3–5 business days | 1–3 weeks                       | 8–12 weeks                                             | 8–16 weeks                   |

**Additional notes:**

* **RCS** requires additional brand assets: logo, brand color, agent description, and launch URL. Carriers currently prioritize notable brands (Fortune 1000), high-quality rich content experiences, and established messaging volume (100K+ msgs/month).
* 10DLC throughput is determined by your brand's trust score, assigned during TCR vetting. Enhanced vetting through Aegis and WMC Global can unlock higher tiers.
* Short code brand vetting through Aegis is non-transferable. Campaign approval goes through CSCA, then each carrier independently. Not all industries are eligible.

Governed by TCPA (federal) and CTIA Messaging Principles. Regulator: FCC.

#### State-specific SMS laws

Beyond the federal TCPA, 15+ states have their own SMS legislation that may impose stricter requirements. The state law applies based on the **recipient's location**, not your business location.

| State          | Law                                              | Key differences from federal TCPA                                                                                                                  |
| -------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Florida**    | Florida Telephone Solicitation Act (FTSA)        | Max **3 texts per 24 hours** on same topic. Sending window: **8 AM–8 PM** (narrower than federal 8 AM–9 PM). One of the most litigated SMS states. |
| **Oklahoma**   | Oklahoma Telephone Solicitation Act (OTSA, 2022) | Mirrors Florida: **3 texts per 24 hours** on same topic, **8 AM–8 PM** window.                                                                     |
| **Maryland**   | Stop the Spam Calls Act                          | **3 texts per 24 hours** limit. Express written consent required. Detailed consent logs mandatory.                                                 |
| **Washington** | Consumer Electronic Mail Act                     | Unsolicited commercial texts are illegal. Sending window: **8 AM–8 PM.**                                                                           |
| **Texas**      | SB 140 (2025)                                    | New telemarketing rules effective 2025. Expanding SMS-specific requirements.                                                                       |
| **California** | CCPA + state telemarketing laws                  | Broader privacy rights: right to know, delete, and opt out of personal data use. Must respond to opt-out requests within **15 business days**.     |
| **Virginia**   | TTPA amendment                                   | Business must identify themselves by full name and entity.                                                                                         |

***

### Canada

**Types:** Toll-free number (shared with US), Short code, RCS

|                       | Toll-free                               | Short code                                        | RCS                          |
| --------------------- | --------------------------------------- | ------------------------------------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal (shared with US)              | Canadian Telecommunications Association (CTA)     | Google + Individual carriers |
| **Campaign reviewer** | OneSignal                               | Short Code Council (SCC), carrier representatives | Google + Individual carriers |
| **Approval timeline** | Shared with US (no additional approval) | 8–12 weeks                                        | 8–16 weeks                   |

**Additional notes:**

* Toll-free uses the same number as the US. No separate application needed.
* Bilingual keywords required: STOP/ARRET, HELP/AIDE must be supported in both English and French.
* Short codes beginning with "4" are reserved. Max message length is 320 characters (vs. 160 in US).
* Quebec (Bill 96): Marketing SMS to Quebec recipients should be in French or bilingual.
* RCS: Uses the same toll-free number as SMS and US RCS. No separate application needed.

Governed by CASL (Canada's Anti-Spam Legislation), enforced by the CRTC.

***

### Argentina

**Types:** Short code

Short-code-only market. Alphanumeric sender IDs are overwritten with a random short code.

|                       | Short code          |
| --------------------- | ------------------- |
| **Brand reviewer**    | Individual carriers |
| **Campaign reviewer** | Individual carriers |
| **Approval timeline** | 6–15 weeks          |

Governed by Argentina's Personal Data Protection Law (Ley 25.326). Regulator: ENACOM.

***

### Brazil

**Types:** Alphanumeric sender ID, Short code, RCS

Short codes are the primary A2P method. Long codes are not available.

|                       | Alphanumeric sender ID                      | Short code          | RCS                          |
| --------------------- | ------------------------------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | Individual carriers (TIM, Claro, Vivo only) | Individual carriers | Google + Individual carriers |
| **Campaign reviewer** | OneSignal                                   | Individual carriers | Google + Individual carriers |
| **Approval timeline** | \~10 weeks                                  | 2–4 weeks           | 8–16 weeks                   |

**Additional notes:**

* Short code applications require opt-in/opt-out flows in Portuguese.
* Alphanumeric sender IDs require pre-registration and are only available on TIM, Claro, and Vivo. Other carriers do not deliver alphanumeric-originated messages. Allow \~10 weeks for provisioning.
* Marketing SMS **prohibited 9 PM–9 AM and all day Sundays.** Brazil spans 3 time zones.
* Prohibited content: adult, cannabis, controlled substances, contest/sweepstakes, telecom service promotions.
* Some carriers do not support unicode. Test before sending emojis or special characters.
* RCS: Requires creating a separate RCS sender specifically for Brazil (cannot reuse other countries' senders).

Governed by LGPD (Lei Geral de Proteção de Dados). Regulators: ANPD (data protection), ANATEL (telecom).

***

### Chile

**Types:** Long code

|                       | Long code           |
| --------------------- | ------------------- |
| **Brand reviewer**    | OneSignal           |
| **Campaign reviewer** | Individual carriers |
| **Approval timeline** | 1–3 weeks           |

**Additional notes:**

* **Marketing messages are not allowed:** transactional and OTP only.
* Political messages prohibited.
* Rate-limited: max 10 messages per 60 seconds from the same long code.
* **Concatenation not supported:** keep messages within a single segment (160 chars GSM-7).

Governed by Chile's Data Protection Law (Ley 19.628). Regulator: SUBTEL.

***

### Mexico

**Types:** Long code, RCS

|                       | Long code           | RCS                          |
| --------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal           | Google + Individual carriers |
| **Campaign reviewer** | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 weeks           | 8–16 weeks                   |

**Additional notes:**

* REVOE (Do Not Contact registry): do not send marketing to registered individuals.
* RCS: RCS sender info must be in Spanish.

Governed by LFPDPPP (Federal Data Protection Law). Regulators: INAI (data protection), IFT (telecom).

***

### Peru

**Types:** Long code

|                       | Long code           |
| --------------------- | ------------------- |
| **Brand reviewer**    | OneSignal           |
| **Campaign reviewer** | Individual carriers |
| **Approval timeline** | 1–3 weeks           |

**Additional notes:** Gracias No Insista (Do Not Contact registry): do not send marketing to registered individuals.

Governed by Peru's Personal Data Protection Law (Ley 29733). Regulator: OSIPTEL.

***

### Puerto Rico

**Types:** Same as United States (Toll-free, 10DLC, Short code, RCS)

Puerto Rico uses US phone numbers (+1 area codes) and falls under US regulations. See [United States](#united-states).

***

## Europe

Sender resource types, reviewers, and approval timelines for markets across the UK, EU, EEA, and Switzerland.

### United Kingdom

**Types:** Alphanumeric sender ID, Long code, Short code, RCS

|                       | Alphanumeric sender ID                             | Long code           | Short code          | RCS                          |
| --------------------- | -------------------------------------------------- | ------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | MEF SenderID Protection Registry                   | Ofcom (via KYC)     | Individual carriers | Google + Individual carriers |
| **Campaign reviewer** | OneSignal                                          | Individual carriers | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–5 business days; longer for Protected Sender IDs | 1–3 weeks           | 12–16 weeks         | 8–16 weeks                   |

**Additional notes:**

* Protected Sender IDs (MEF or BT protected brands) must be pre-registered.
* Non-compliant alphanumeric sender IDs may be blocked or penalized by carriers. Generic sender IDs (Verify, OTP, Alert, Info, etc.) are blocked by BT and other carriers.
* Short code carrier freeze: mid-December through early January. Age-restricted content (alcohol, gambling) evaluated case-by-case. Cannabis prohibited; CBD permissible.
* RCS: RCS sender profile may not contain international phone numbers. Only +44 UK numbers allowed.

Governed by UK-GDPR, PECR (2003), and Data Protection Act 2018. "Soft opt-in" exception applies for existing customers. Regulators: Ofcom (telecom), ICO (data protection).

***

### Austria

**Types:** Alphanumeric sender ID, Long code, RCS

|                       | Alphanumeric sender ID | Long code           | RCS                          |
| --------------------- | ---------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           | 8–16 weeks                   |

**Additional notes:** Delivery to M2M numbers is not supported over long codes.

Governed by GDPR and Austrian Telecommunications Act (TKG 2021). Regulator: RTR.

***

### Belgium

**Types:** Long code, RCS

Long-code-only market, one of the few European countries where alphanumeric sender IDs are not available. Include your brand name in the message body.

|                       | Long code           | RCS                          |
| --------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal           | Google + Individual carriers |
| **Campaign reviewer** | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 weeks           | 8–16 weeks                   |

**Additional notes:** Trilingual market (Dutch, French, German): support HELP/STOP in the end user's local language. Gambling/betting/casino permitted only for licensed companies.

Governed by GDPR and Belgian Electronic Communications Act. Regulator: BIPT.

***

### Denmark

**Types:** Alphanumeric sender ID, Long code, RCS

|                       | Alphanumeric sender ID | Long code           | RCS                          |
| --------------------- | ---------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           | 8–16 weeks                   |

**Additional notes:** Gambling/betting/casino permitted only for licensed companies. Robinson List (Robinsonlisten): do not send marketing to registered individuals.

Governed by GDPR and Danish Marketing Practices Act. Regulator: Danish Business Authority.

***

### Finland

**Types:** Alphanumeric sender ID, Long code, RCS

|                       | Alphanumeric sender ID                                           | Long code           | RCS                          |
| --------------------- | ---------------------------------------------------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | Traficom (Protected Sender IDs only); OneSignal (standard)       | OneSignal           | Google + Individual carriers |
| **Campaign reviewer** | OneSignal                                                        | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days (standard); 1–3 weeks for Protected Sender IDs | 1–3 weeks           | 8–16 weeks                   |

**Additional notes:**

* If your sender ID matches a name on [Traficom's protected list](https://www.traficom.fi/fi/viestinta/laajakaista-ja-puhelin/rekisteroidyt-sms-sender-id-tunnukset), you must provide an LOA and Numbering Decision.
* Gambling and lottery content is **strictly prohibited,** not just restricted to licensed companies.

Governed by GDPR and Finnish Information Society Code. Regulator: Traficom.

***

### France

**Types:** Alphanumeric sender ID, Short code, RCS

No long codes available in France.

|                       | Alphanumeric sender ID | Short code          | RCS                          |
| --------------------- | ---------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal              | ARCEP + AF2M        | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days      | 8–10 weeks          | 8–16 weeks                   |

**Additional notes:**

* Marketing SMS blocked on **Sundays, public holidays, and after 10 PM.** Messages sent outside permitted times are queued.
* Short codes: 3-month minimum term, 3-month notice to return. Inactive codes (30 days no traffic) risk withdrawal. Carrier freezes in August and December.
* URL shorteners (bit.ly, tinyurl) are **strictly forbidden**.
* CONTACT keyword must return company name + support contact. STOP must be in French.
* Housing energy marketing ban effective July 2025.

Governed by GDPR, French Data Protection Act, and ARCEP regulations. Regulators: CNIL (data protection), ARCEP (telecom), AF2M (industry code of conduct).

***

### Germany

**Types:** Alphanumeric sender ID, Long code, Short code, RCS

|                       | Alphanumeric sender ID | Long code           | Short code          | RCS                          |
| --------------------- | ---------------------- | ------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           | Bundesnetzagentur   | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           | 6–8 weeks           | 8–16 weeks                   |

**Additional notes:** Short code carrier freezes: November–mid-January and July–mid-September. Inactive short codes risk withdrawal. RCS: Only one RCS sender per name and per use case. Website, ToS, and privacy policy must be in German.

Governed by GDPR, German Unfair Competition Act (UWG), and TDDDG. Regulator: Bundesnetzagentur.

***

### Iceland

**Types:** Alphanumeric sender ID, Long code

|                       | Alphanumeric sender ID | Long code           |
| --------------------- | ---------------------- | ------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           |
| **Campaign reviewer** | OneSignal              | Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           |

**Additional notes:**

* **URL allow-listing required:** Icelandic carriers block SMS containing web URLs unless the URL (or domain) has been pre-approved. Contact your OneSignal account manager to submit the request. Allow-list your opt-out URL before sending any messages, since this is the only way to provide an unsubscribe mechanism in Iceland.
* **Two-way SMS is not supported:** long codes cannot receive replies. STOP keywords, two-way messaging, and keyword-based opt-out are unavailable. Opt-out must be managed via an unsubscribe link.
* Use alphanumeric sender IDs for messages containing URLs, as domestic long codes with URL content are filtered even after allow-listing.
* Gambling and lottery content is strictly prohibited.

Governed by GDPR via EEA Agreement (not EU). Regulator: Fjarskiptastofa.

***

### Ireland

**Types:** Alphanumeric sender ID, RCS

Alphanumeric-sender-ID-only market. Registration with ComReg is **mandatory**.

|                       | Alphanumeric sender ID                         | RCS                          |
| --------------------- | ---------------------------------------------- | ---------------------------- |
| **Brand reviewer**    | ComReg (via SMS Sender ID Protection Registry) | Google + Individual carriers |
| **Campaign reviewer** | OneSignal                                      | Google + Individual carriers |
| **Approval timeline** | \~2 weeks                                      | 8–16 weeks                   |

**Additional notes:**

* **ComReg Sender ID registration** is mandatory (via their Sender ID Protection Registry portal). MEF Protected Sender IDs also require an LOA.
* Since July 2025, unregistered sender IDs are stamped "Likely Scam." Since October 2025, unregistered sender IDs are **blocked entirely.**
* Generic sender IDs (Verify, OTP, Alert, Info, SMS, Notify, etc.) are blocked.
* Cannabis content strictly prohibited.

Governed by GDPR and ePrivacy Regulations. Regulators: DPC (data protection), ComReg (telecom + SMS Sender ID Registry).

***

### Italy

**Types:** Alphanumeric sender ID, Long code, Short code, RCS

|                       | Alphanumeric sender ID | Long code           | Short code          | RCS                          |
| --------------------- | ---------------------- | ------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           | AGCOM               | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           | 7–9 weeks           | 8–16 weeks                   |

**Additional notes:**

* Marketing SMS **prohibited 10 PM–8 AM and all day Sundays.**
* AGCOM Code of Conduct for Aliases (resolution 42/13/CIR) applies to alphanumeric sender IDs. This is a mandatory regulatory requirement.
* Cannabis content strictly prohibited.

Governed by GDPR and Italian Data Protection Code. Regulators: Garante (data protection), AGCOM (telecom).

***

### Luxembourg

**Types:** Alphanumeric sender ID

|                       | Alphanumeric sender ID |
| --------------------- | ---------------------- |
| **Brand reviewer**    | OneSignal              |
| **Campaign reviewer** | OneSignal              |
| **Approval timeline** | 1–3 business days      |

**Additional notes:**

* **No concatenation:** messages cannot exceed 160 characters (GSM-7) or 70 characters (Unicode).
* **No two-way SMS:** inbound messaging not supported. Opt-out via unsubscribe link only.
* Trilingual market (Luxembourgish, French, German): support HELP/STOP in local language.

Governed by GDPR. Regulators: CNPD (data protection), ILR (telecom).

***

### Netherlands

**Types:** Alphanumeric sender ID, Long code, RCS

|                       | Alphanumeric sender ID | Long code           | RCS                          |
| --------------------- | ---------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           | 8–16 weeks                   |

Governed by GDPR and Dutch Telecommunications Act. Regulators: AP (data protection), ACM (telecom).

***

### Norway

**Types:** Alphanumeric sender ID, Long code, RCS

|                       | Alphanumeric sender ID | Long code           | RCS                          |
| --------------------- | ---------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           | 8–16 weeks                   |

**Additional notes:** Gambling and lottery content strictly prohibited. Reservasjonsregisteret (Do Not Contact registry): do not send marketing to registered individuals.

Governed by GDPR via EEA Agreement (not EU). Regulator: Nkom.

***

### Poland

**Types:** Alphanumeric sender ID, Long code, RCS

|                       | Alphanumeric sender ID | Long code           | RCS                          |
| --------------------- | ---------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           | 8–16 weeks                   |

**Additional notes:**

* Generic alphanumeric sender IDs are actively filtered by Polish operators. Use a brand-specific sender ID.
* **URL shorteners strictly prohibited.** Full URLs in long SMS (>160 chars) may also trigger blocking. Test before sending at scale.

Governed by GDPR and Polish Telecommunications Law. Regulators: UODO (data protection), UKE (telecom).

***

### Portugal

**Types:** Alphanumeric sender ID, Long code, RCS

|                       | Alphanumeric sender ID | Long code           | RCS                          |
| --------------------- | ---------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           | 8–16 weeks                   |

**Additional notes:** RCS senders must be approved in Spain first before Portugal.

Governed by GDPR. Regulators: CNPD (data protection), ANACOM (telecom).

***

### Spain

**Types:** Alphanumeric sender ID, Long code, Short code, RCS

|                       | Alphanumeric sender ID | Long code           | Short code          | RCS                          |
| --------------------- | ---------------------- | ------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           | Individual carriers | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           | 12–14 weeks         | 8–16 weeks                   |

**Additional notes:** MEF Protected Sender IDs require an LOA. Cannabis content strictly prohibited. Lista Robinson: do not send marketing to registered individuals.

Governed by GDPR and LOPDGDD. Regulators: AEPD (data protection), CNMC (telecom).

***

### Sweden

**Types:** Alphanumeric sender ID, Long code, Short code, RCS

|                       | Alphanumeric sender ID | Long code           | Short code          | RCS                          |
| --------------------- | ---------------------- | ------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           | Individual carriers | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Individual carriers | Google + Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           | 6–8 weeks           | 8–16 weeks                   |

**Additional notes:** Gambling, lottery, and adult content restricted, may require case-by-case carrier approval. NIX-Telefon (Do Not Contact registry): do not send marketing to registered individuals.

Governed by GDPR and Swedish Electronic Communications Act (LEK). Regulators: IMY (data protection), PTS (telecom).

***

### Switzerland

**Types:** Alphanumeric sender ID, Long code

Not an EU member. GDPR does not apply directly.

|                       | Alphanumeric sender ID | Long code           |
| --------------------- | ---------------------- | ------------------- |
| **Brand reviewer**    | OneSignal              | OneSignal           |
| **Campaign reviewer** | OneSignal              | Individual carriers |
| **Approval timeline** | 1–3 business days      | 1–3 weeks           |

**Additional notes:**

* Cannabis content strictly prohibited.
* Multilingual market (German, French, Italian, Romansh): support HELP/STOP in local language.
* Asterisk-Eintrag (\*): individuals marked with an asterisk in the phone directory should not receive unsolicited commercial communications.

Governed by Swiss Federal Act on Data Protection (revDSG/nDSG). Regulator: FDPIC (data protection), OFCOM (telecom).

***

## Asia

Sender resource types, reviewers, and approval timelines for markets across Asia and the Middle East. Many countries in this region have mandatory sender ID registration.

### Hong Kong

**Types:** Alphanumeric sender ID, Long code

|                       | Alphanumeric sender ID | Long code |
| --------------------- | ---------------------- | --------- |
| **Brand reviewer**    | OFCA                   | OneSignal |
| **Campaign reviewer** | OneSignal              | OneSignal |
| **Approval timeline** | \~18 days              | 1–3 weeks |

**Additional notes:**

* OFCA registration mandatory since February 2024. Registered sender IDs display with a **#** prefix as a verification indicator (for example, "#ACME"). China Mobile Hong Kong blocks unregistered sender IDs entirely.
* Prohibited: firearms, gambling, adult, money/loan, political, religious, controlled substances, cannabis, alcohol.

Governed by Personal Data (Privacy) Ordinance (PDPO). Regulator: OFCA.

***

### India

**Types:** Alphanumeric sender ID (DLT registration required), Short code

|                       | Alphanumeric sender ID (domestic)     | Short code          |
| --------------------- | ------------------------------------- | ------------------- |
| **Brand reviewer**    | Mobile operator DLT portals           | Individual carriers |
| **Campaign reviewer** | DLT portals (message template review) | Individual carriers |
| **Approval timeline** | 10 business days                      | 4–6 weeks           |

**Additional notes:**

*DLT registration (domestic gateway):*

* DLT is India's sender registration system, operated by each major carrier (Jio, Airtel, Vodafone Idea, BSNL, MTNL). You must register on the DLT portal of the carrier(s) you want to reach.
* You register three things: (1) your **entity** (brand identity, verified with PAN card, GST number, etc.), (2) your **header** (6-character alphanumeric sender ID), and (3) your **content templates** (actual message templates with variable placeholders). Every message you send must match an approved template.
* Sender ID is preserved with a 2-letter carrier prefix indicating use case category (for example, "VM-TWILIO" where VM = transactional on Vodafone Idea).
* Use cases restricted to: **transactional, service implicit, and service explicit** only. Promotional messaging via DLT-approved 6-digit sender IDs is not yet supported by Twilio.
* India's Do-Not-Disturb (DND) registry is respected on the domestic gateway.

*International gateway (fallback):*

* No DLT registration required. Messages sent via random ILDO-approved short codes (format 5NNNN–5NNNNNNN).
* Sender ID is **not preserved.** It is overwritten with a random 5–9 digit number regardless of what you set.
* Bypasses India's DND database and has no time-of-day restrictions.
* Useful as a fallback delivery route, but not suitable for branded messaging.

*General:* Shortened URLs not allowed. Two-way SMS supported. MMS not supported. Prohibited: firearms, gambling, adult, money/loan, political, religious, controlled substances, cannabis, alcohol.

Governed by IT Act 2000 and TRAI Telecom Commercial Communications Customer Preference Regulations. Regulator: TRAI.

***

### Japan

**Types:** Alphanumeric sender ID

|                       | Alphanumeric sender ID |
| --------------------- | ---------------------- |
| **Brand reviewer**    | Individual carriers    |
| **Campaign reviewer** | Individual carriers    |
| **Approval timeline** | \~5 weeks              |

**Additional notes:**

* Phone numbers in message content not allowed.
* **KDDI network limitation:** Messages with 5 or more concatenated segments experience delivery delays on KDDI's platform. The message still delivers, but slower than normal. NTT Docomo and SoftBank are not affected.
* International numeric sender IDs are prepended with 010 per KDDI Japan policy.
* MMS not available.
* Prohibited: firearms, gambling, adult, money/loan, lead gen, Text2Pay, political, religious, controlled substances, cannabis, alcohol.

Governed by APPI and Telecommunications Business Act. Regulator: MIC.

***

### Macao

**Types:** Alphanumeric sender ID

|                       | Alphanumeric sender ID |
| --------------------- | ---------------------- |
| **Brand reviewer**    | OneSignal              |
| **Campaign reviewer** | Individual carriers    |
| **Approval timeline** | 1–3 business days      |

**Additional notes:** No pre-registration required. Two-way and MMS not supported.

Governed by Personal Data Protection Act (Law 8/2005). Regulator: DSRT.

***

### Malaysia

**Types:** Alphanumeric sender ID

|                       | Alphanumeric sender ID |
| --------------------- | ---------------------- |
| **Brand reviewer**    | MCMC + OneSignal       |
| **Campaign reviewer** | Individual carriers    |
| **Approval timeline** | \~2 weeks              |

**Additional notes:**

* "RM 0.00" header and brand name mandatory in all messages.
* URLs, phone numbers, PII requests blocked (MCMC Sept 2024).
* Sender IDs overwritten with operator short codes for A2P.
* Marketing hours 8 PM–8 AM prohibited.
* Banking SMS OTP restricted.
* Digi Malaysia: no concatenation support. Messages exceeding one segment are delivered as multiple separate texts, potentially out of order.

Governed by PDPA 2010 and Communications and Multimedia Act 1998. Regulator: MCMC.

***

### Philippines

**Types:** Alphanumeric sender ID, Long code

|                       | Alphanumeric sender ID | Long code |
| --------------------- | ---------------------- | --------- |
| **Brand reviewer**    | NTC                    | OneSignal |
| **Campaign reviewer** | OneSignal              | OneSignal |
| **Approval timeline** | \~2 weeks              | 1–3 weeks |

**Additional notes:**

* Registration mandatory since April 7, 2025; unregistered blocked.
* IDs cannot contain "TEST", "MESSAGE", "SMS", or carrier names ("SMART", "SUN").
* Shortened URLs prohibited. Banking URLs must be allow-listed.
* Phone numbers in content not allowed.
* URLs only via registered alphanumeric (not long codes).
* Prohibited: financial loans, real estate, political, adult, alcohol, drugs, tobacco. Gaming prohibited for offshore (ok for registered PIGO).

Governed by Data Privacy Act 2012 (RA 10173). Regulator: NTC.

***

### Singapore

**Types:** Alphanumeric sender ID, Long code, RCS

|                       | Alphanumeric sender ID | Long code           | RCS                          |
| --------------------- | ---------------------- | ------------------- | ---------------------------- |
| **Brand reviewer**    | SGNIC + OneSignal      | OneSignal           | Google + Individual carriers |
| **Campaign reviewer** | OneSignal              | Individual carriers | Google + Individual carriers |
| **Approval timeline** | \~5 business days      | 1–3 weeks           | 8–16 weeks                   |

**Additional notes:**

* SGNIC mandatory since Jan 30, 2023; unregistered = "Likely-SCAM".
* Register SGNIC first, then register with OneSignal with proof.
* De-register from SGNIC when releasing numbers.
* WhatsApp/LINE links not allowed.
* Prohibited: firearms, gambling, adult, money/loan, political, religious, controlled substances, cannabis, alcohol.
* RCS: RCS senders must follow the same SSIR Singapore registration process as A2P SMS sender IDs.

Governed by PDPA 2012 and Spam Control Act. Regulator: IMDA.

***

### South Korea

**Types:** International long code only

|                       | International long code |
| --------------------- | ----------------------- |
| **Brand reviewer**    | OneSignal               |
| **Campaign reviewer** | OneSignal               |
| **Approval timeline** | 1–3 business days       |

**Additional notes:**

* Numeric only; alphanumeric not supported.
* Auto-prefixed 009/006.
* Messages auto-appended \[Web 발신] or \[국제발신].
* EUC-KR encoding only.
* Concatenation not supported: messages exceeding one segment are delivered as separate texts, potentially out of order.
* Two-way not supported.
* Prohibited: adult, gambling.

Governed by PIPA. Regulators: KCC, PIPC.

***

### Taiwan

**Types:** Alphanumeric sender ID

|                       | Alphanumeric sender ID |
| --------------------- | ---------------------- |
| **Brand reviewer**    | OneSignal              |
| **Campaign reviewer** | Individual carriers    |
| **Approval timeline** | 1–3 weeks              |

**Additional notes:**

* Brand name required at the beginning of every message; must be registered.
* URLs strictly prohibited unless pre-registered/allowlisted. Shortened URLs never allowed.
* Marketing hours 12:30 PM–1:30 PM and 9 PM–9 AM prohibited.
* Two-way not supported.
* Prohibited: firearms, gambling, adult, money/loan, political, religious, controlled substances, cannabis, alcohol, WhatsApp/LINE links.

Governed by PDPA. Regulator: NCC.

***

### Thailand

**Types:** Alphanumeric sender ID, Long code

|                       | Alphanumeric sender ID | Long code           |
| --------------------- | ---------------------- | ------------------- |
| **Brand reviewer**    | NBTC                   | OneSignal           |
| **Campaign reviewer** | OneSignal              | Individual carriers |
| **Approval timeline** | \~2 weeks              | 1–3 weeks           |

**Additional notes:**

* Registration mandatory since Oct 6, 2025; unregistered blocked.
* URLs must be registered with sender ID. Shortened URLs prohibited. Banks cannot send URLs.
* Marketing hours 9 PM–9 AM prohibited.
* AIS blocks non-Thai numbers (opt-out: \*137).
* Inactive sender IDs may be deactivated.
* Loan content requires Bank of Thailand license.
* Two-way not supported.

Governed by PDPA B.E. 2562 and Computer Crime Act. Regulator: NBTC.

***

### Turkey

**Types:** Alphanumeric sender ID

|                       | Alphanumeric sender ID |
| --------------------- | ---------------------- |
| **Brand reviewer**    | BTK                    |
| **Campaign reviewer** | OneSignal              |
| **Approval timeline** | \~2 weeks              |

**Additional notes:**

* Alphanumeric only; no long codes or short codes.
* Message length reduced: GSM7=155, UCS2=65 (5 chars reserved for operator IDs).
* Effective April 1, 2026: non-Turkish entities cannot send URLs.
* Promotional traffic prohibited since Feb 2021.
* Northern Cyprus not supported. Two-way not supported.
* İYS manages consent.
* Prohibited: gambling, politics, religion.

Governed by Law 6698 and Electronic Communications Law 5809. Regulator: BTK.

***

### United Arab Emirates

**Types:** Alphanumeric sender ID

|                       | Alphanumeric sender ID |
| --------------------- | ---------------------- |
| **Brand reviewer**    | TDRA                   |
| **Campaign reviewer** | OneSignal              |
| **Approval timeline** | \~2 weeks              |

**Additional notes:**

* Alphanumeric only; no long codes or short codes.
* Unregistered IDs blocked entirely.
* Promotional IDs must carry "AD-" prefix (counts toward 11-char limit).
* Promotional messaging ONLY for domestic UAE entities.
* URLs, phone numbers, PII requests not allowed. Avoid URL shorteners.
* Marketing hours 9 PM–7 AM prohibited (queued).
* Health services sender ID requires UAE health authority approval.
* EURO symbol requires UCS2.
* Two-way not supported.
* Prohibited: gambling, adult, money/loan, political, religious, controlled substances, cannabis, alcohol.

Governed by Federal Decree-Law No. 45 of 2021. Regulator: TDRA.

***

## Oceania

Sender resource types, reviewers, and approval timelines for Australia and New Zealand.

### Australia

**Types:** Alphanumeric sender ID, Long code

|                       | Alphanumeric sender ID | Long code           |
| --------------------- | ---------------------- | ------------------- |
| **Brand reviewer**    | ACMA                   | OneSignal           |
| **Campaign reviewer** | OneSignal              | Individual carriers |
| **Approval timeline** | 7–10 business days     | 1–3 business days   |

**Additional notes:**

* As of July 1, 2026, all alphanumeric sender IDs must be registered under the ACMA SMS Sender ID Register. Unregistered sender IDs may be blocked.
* Long codes support MMS in Australia (one of the few international markets where this works).
* Delivery to M2M numbers is not supported.

Governed by Spam Act 2003 and Spam Regulations 2021. Regulator: ACMA. Unsubscribe must remain functional for 30 days; opt-outs actioned within 5 business days.

***

### New Zealand

**Types:** Short code

Short-code-only market. NZ operators mandate dedicated short codes for all A2P messaging.

|                       | Short code                                                               |
| --------------------- | ------------------------------------------------------------------------ |
| **Brand reviewer**    | NZ Telecommunications Forum (TCF) + Department of Internal Affairs (DIA) |
| **Campaign reviewer** | Individual NZ carriers                                                   |
| **Approval timeline** | 5–6 weeks                                                                |

**Additional notes:**

* Application requires: requestor details (name, position, phone, email, address) and a helpdesk 0800/0508 number + email.
* Every message must include: "Reply to this SMS will be charged" with per-carrier charges (Vodafone/Spark/Skinny 20c, 2 Degrees 9c).
* MMS is not supported. Carrier freeze: December through mid-January.
* Prohibited content includes firearms, gambling, adult, money/loan, political, religious, controlled substances, and cannabis.

Governed by Unsolicited Electronic Messages Act 2007. Regulators: TCF, DIA.

***

## FAQ

### How long does sender resource approval take?

Timelines vary by country and sender resource type. Alphanumeric sender IDs in most countries take 1–5 business days. 10DLC in the US takes 1–3 weeks. Short codes and RCS typically take 8–16 weeks depending on the market. See each country section above for specifics.

### Can I use the same sender resource for multiple countries?

No. Sender resources are provisioned for a specific country. The exception is US toll-free numbers, which also cover Canada without a separate application.

### What happens if I send without a registered sender resource?

Messages may be blocked, filtered, or delivered without your sender ID. In countries with mandatory registration (for example, Ireland, Singapore, Philippines, Thailand), unregistered sender IDs are blocked entirely.

### Do I need a separate sender resource for each use case?

Yes. Each use case (promotional, transactional, OTP) requires its own approved campaign. Sending outside the approved use case can result in campaign suspension or sender resource revocation.

***

## Related pages

<Columns>
  <Card title="SMS setup" icon="rocket" href="./sms-setup">
    Start an SMS program, choose between OneSignal SMS and Twilio integration, and submit your first sender resource application.
  </Card>

  <Card title="Regulatory compliance" icon="scale" href="./sms-regulatory-compliance">
    Carrier rules, quiet hours, prohibited content, and the broader regulatory framework.
  </Card>

  <Card title="Consent keyword management" icon="shield" href="./sms-consent-keyword-management">
    STOP, HELP, START, and custom opt-out keyword handling required by carriers.
  </Card>

  <Card title="Composing messages" icon="pen-to-square" href="./sms-composing-messages">
    Character limits, MMS, trackable links, and RCS rich content.
  </Card>
</Columns>


# SMS setup
Source: https://documentation.onesignal.com/docs/en/sms-setup

Set up texting with OneSignal. Understand the brand, sender, and sender resource model, choose between OneSignal SMS and Twilio, and learn how to migrate from an existing provider.

There are two ways to set up texting with OneSignal: a direct integration with Twilio, or OneSignal SMS (which manages the carrier infrastructure on your behalf). Twilio integration is best for customers who can self-serve their sender resource application and sender setup. OneSignal SMS is best for customers who want our compliance team to handle carrier applications, registration, and ongoing support.

Setting up texting involves three core concepts: **brands**, **senders**, and **sender resources**. Getting this structure right from the start directly impacts which regions you can send to, how quickly your messages go out, and what type of content you can send.

***

## Core concepts

### Brand

A brand is the shared identity information (company name, website, tax ID, and logo) that identifies the organization behind your messaging during sender resource approval. In OneSignal, a brand maps to a single OneSignal app.

### Sender

A sender is a sender resource or group of sender resources. Each texting program (promotional, transactional, or OTP) requires a dedicated sender.

The most important reason to use a dedicated sender per program is **consent management**. When each sender maps to a single program, opt-outs stay cleanly scoped. If a recipient unsubscribes from your promotional sender, they stop receiving marketing messages, but they continue to receive order confirmations, shipping updates, or security codes from your other senders.

Grouping multiple sender resources into a single sender is useful for:

* **Geo-sending:** Route messages through the best sender resource for each recipient's geography without segmenting your audience by location. For example, a sender with both a US short code and a UK short code automatically delivers from the US number to US recipients and the UK number to UK recipients.
* **Scaling throughput:** Combine multiple sender resources to multiply your effective send rate. For example, 10 sender IDs each with 1 message per second (MPS) gives you 10 MPS. Throughput scaling is not permitted in the US and may have restrictions in other regions.
* **Managing fallbacks:** Pair RCS and SMS sender resources so that if RCS fails to deliver, SMS is automatically used as a fallback.

Grouping sender resources into a sender does not disrupt the end user's experience. A user who first receives from one resource in the group continues to receive future messages from that same resource.

<Warning>
  You can share a sender across multiple texting programs and use custom keywords to manage opt-outs, but we don't recommend this. STOP is a protected keyword that automatically opts the user out of the entire sender. If a shared sender is used for both a marketing program and a transactional program, a user texting STOP to a marketing message will no longer receive important account notifications either.
</Warning>

### Sender resources

A sender resource is the underlying provisioned number or agent required to send messages across a carrier network.

Sender resources are confined to a single geography and should be dedicated to a single sender. Each sender resource has a maximum throughput, the number of messages it can send per second.

All sender resource types require approval for each combination of geography and use case. For example, a US 10DLC approved for promotional messages and a UK RCS agent approved for transactional messages are two separate sender resources, each requiring its own approval with brand information and sample messages.

### Sender resource types

| Type                       | Best for                                                                                   | Approval timeline                     | Throughput                     | Price    |
| -------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------- | ------------------------------ | -------- |
| **Alphanumeric sender ID** | Branded sender name with medium throughput; requires managing consent (opt-out) separately | Fast (only available in certain geos) | Moderate (10 MPS default)      | Included |
| **Toll-free**              | All types of messages                                                                      | Days                                  | Low (3 MPS default, up to 25+) | Included |
| **Long codes**             | All types of messages                                                                      | Weeks                                 | Moderate–High (3–225 MPS)      | Included |
| **Short code**             | High-volume messages                                                                       | Weeks–Months                          | High (100+ MPS)                | Premium  |
| **RCS**                    | Branded, rich app-like messages, or high-volume messages                                   | 8–16 weeks                            | High (100 MPS)                 | Premium  |

<Card title="Sender resource applications" icon="globe" href="./sms-registration-requirements">
  Country-specific availability, approval timelines, reviewers, and additional notes for every sender resource type.
</Card>

***

## Choose your setup path

Navigate to **Settings > SMS > Set up SMS** in your OneSignal dashboard.

<Tabs>
  <Tab title="OneSignal SMS">
    OneSignal manages the carrier infrastructure on your behalf, with a dedicated compliance team that draws on experience from hundreds of sender resource applications. Choose this if:

    * You send more than 5,000 SMS per month
    * You are on a paid OneSignal plan (see [pricing](https://onesignal.com/pricing))

    Click **Book Demo with SMS Expert** to get assistance from our team. Your account manager can also set up time with our compliance team to begin sender resource applications.

    <Note>
      While waiting for verification, you can begin designing SMS & MMS templates and ensuring you meet the [sender resource application requirements](./sms-registration-requirements).
    </Note>
  </Tab>

  <Tab title="Twilio integration">
    You manage your Twilio account and sender resources directly through Twilio, then connect them to OneSignal. Choose this if:

    * You send fewer than 5,000 SMS per month
    * You want full control of your Twilio account

    This is ideal for testing or small-scale sending. Apply for the sender resources that suit your business needs in Twilio and add them to a messaging service before connecting. Ensure your Twilio sender resource supports SMS (and MMS if needed).

    **Configure Twilio:**

    Add your **Twilio Account SID** and **Auth Token** from your Twilio dashboard, then click **Next: Add Phone Numbers**.

    Once verified, OneSignal retrieves all Twilio sender resources linked to your account. Select a **default sender resource** to use when sending. You can override this during message creation.

    To confirm setup, enter your phone number and click **Send Test SMS**. If the message doesn't arrive, confirm the default sender resource supports SMS and check Twilio logs for errors.

    <Warning>
      Twilio trial accounts require recipient numbers to be [pre-registered](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account).
    </Warning>
  </Tab>
</Tabs>

***

## Migrating from an existing provider

If you want to move existing texting programs to OneSignal SMS from another provider, you will need to migrate your sender resources and existing SMS automations.

* **From Twilio:** No downtime. OneSignal transfers your numbers to the new account. Depending on the number type and registration process, this typically takes around 3 weeks.
* **From another provider:** There is some risk of downtime. Depending on number types and account complexity, this typically takes around 4 weeks or more.

Contact your account manager to set up time with our implementation team to begin your migration.

***

## FAQ

### What's the difference between OneSignal SMS and the Twilio integration?

With the Twilio integration, you manage your own Twilio account, sender resources, and carrier relationships. With OneSignal SMS, OneSignal manages the carrier infrastructure on your behalf, including sender resource applications, compliance guidance, and support. OneSignal SMS is recommended for customers sending more than 5,000 messages per month.

### Can I use multiple sender resources for the same sender?

Yes. You can group multiple sender resources into a single sender for geo-sending, throughput scaling, or RCS/SMS fallback. A user receiving from one sender resource in a sender continues to receive from that same sender resource in the future.

### What is throughput and why does it matter?

Throughput is the number of messages a sender resource (or sender) can send per second. If you need to send to a large audience quickly, you may need a sender resource type with higher throughput (for example, a short code) or group multiple sender resources into one sender. Throughput scaling across multiple sender resources is not permitted in the US.

### How long does sender resource approval take?

Timelines vary by country and sender resource type. Alphanumeric sender IDs in most countries take 1–5 business days. 10DLC in the US takes 1–3 weeks. Short codes and RCS typically take 8–16 weeks. See [Sender resource applications](./sms-registration-requirements) for per-country specifics. Once you submit an application, you can track each sender resource's carrier approval status at **Settings > SMS > Senders**.

***

## Related pages

<Columns>
  <Card title="Sender resource applications" icon="globe" href="./sms-registration-requirements">
    Per-country approval processes, sender resource types, and governing laws.
  </Card>

  <Card title="SMS opt-in and collection" icon="user-plus" href="./sms-opt-in-and-collection">
    Collection methods, required disclosure language, and audience validation.
  </Card>

  <Card title="Regulatory compliance" icon="scale" href="./sms-regulatory-compliance">
    Consent standards, quiet hours, prohibited content, and fraud prevention.
  </Card>

  <Card title="Composing messages" icon="pen-to-square" href="./sms-composing-messages">
    Character limits, MMS, trackable links, and RCS rich content.
  </Card>
</Columns>


# Transactional messaging
Source: https://documentation.onesignal.com/docs/en/sms-transactional-messaging

Send transactional SMS and MMS messages with OneSignal. Covers use cases, opt-in collection, compliance requirements, and sending via Journeys or API.

Transactional messages are triggered by a specific user action or event. They include onboarding messages, order confirmations, shipping and delivery updates, appointment reminders, subscription renewal notices, account alerts, and payment confirmations.

Unlike promotional messages, transactional messages have a lower consent bar. A user entering their phone number in a form that includes disclosure language is sufficient opt-in.

***

## Use cases and collection points

Collect opt-ins at the point where the user provides their phone number for the underlying transaction. The right collection point depends on the use case.

#### Order confirmations and shipping updates

Collect consent at **checkout**. Place disclosure text near the phone number field on your checkout page. The user enters their number, sees the disclosure, and completes their purchase.

#### Account notifications

For example, security alerts, password resets, and billing updates. Collect consent during **account creation or sign-up**. Include disclosure text near the phone number field on your registration form.

#### Appointment reminders and booking confirmations

Collect consent during the **booking or scheduling flow**. Place disclosure text on the booking form where the user enters their phone number.

#### Onboarding and welcome sequences

Collect consent during **account creation or sign-up**. If your onboarding flow includes a separate step where users set up their profile or preferences, you can also collect it there, as long as disclosure text is present at the point where the phone number is entered.

#### In-app or web notification preferences

For users who already have an account, collect transactional SMS consent from a **notification preferences page** in your app or website. Let users toggle on specific types of text notifications, such as order updates, account activity, and appointment reminders, with disclosure text visible on the preferences page.

***

## Compliance requirements

Transactional messages have lower compliance requirements than promotional messages. Disclosure text must be visible at the point where the phone number is collected, directly on or near the phone number field, not on a separate page or buried in terms of service.

<Card title="Required disclosure language" icon="shield" href="./sms-opt-in-and-collection#transactional-opt-ins">
  Disclosure language requirements, common collection points by use case, and the full transactional opt-in compliance rules.
</Card>

<Warning>
  **Don't mix transactional and promotional language.** If your disclosure says "receive updates and offers," that blurs the line between informational and promotional. Promotional messages require a higher standard of consent (express written consent with an unchecked checkbox). Keep transactional disclosures specific to the informational purpose.
</Warning>

<Note>
  If you have multiple senders for different use cases (for example, promotional and transactional), collect which use case the subscriber is opting into as a data tag. This ensures you can route subscribers to the correct sender and keep opt-ins scoped to the right program.
</Note>

***

## Sending

### Before you send

* **Sender name:** Include your brand name in the message body so recipients know who is texting them.
* **Opt-out instruction:** Every transactional message must include a STOP instruction (for example, "Reply STOP to opt out").

Transactional messages are generally exempt from quiet hours, but use good judgment. A shipping update at 3 AM will generate complaints regardless of legality.

### How to send

Because transactional messages are typically triggered by an event, the best sending methods are:

* **Journeys** (Recommended): Gives more visibility and control over message content to non-developers. Supports omnichannel messaging and conditional branching. To set up a Journey, you'll need to configure the trigger as a custom event in OneSignal. See [Journeys](./journeys-overview) and [Custom events](./custom-events).
* **API:** Use the [Create Message API](/reference/create-message) to trigger sends from your backend when your system controls the event.

In both cases, use [Templates](./templates) for content management so non-developers can update message content without code changes.

### Composing your message

For guidance on character limits, personalization, and trackable links, see [Composing messages](./sms-composing-messages). If your sender has an RCS resource, you can also send rich content (branded cards, carousels, and action buttons); see [RCS content](./sms-composing-messages#rcs-content).

***

## FAQ

### What's the difference between transactional and promotional consent?

Promotional messages require express written consent, an affirmative action like checking an unchecked box or texting a keyword. Transactional messages have a lower bar: a user entering their phone number in a form where disclosure language is visible is sufficient. The key is that the disclosure must be present and specific about what types of messages they'll receive.

### Can I send transactional messages during quiet hours?

Transactional and OTP messages are generally exempt from quiet hours restrictions. That said, use good judgment. Sending a non-urgent notification at 3 AM will generate complaints regardless of whether it's technically permitted.

### Do I need a dedicated sender for transactional messages?

Yes. Using a dedicated sender for each program type (promotional, transactional, OTP) keeps opt-outs cleanly scoped. If a subscriber texts STOP to a sender shared across programs, they are opted out of all messages from that sender.

### How do I trigger transactional messages from my backend?

Use the [Create Message API](/reference/create-message) to send messages programmatically. For better visibility and control, consider setting up a Journey triggered by a custom event, which allows non-developers to manage message content without code changes.

***

## Related pages

<Columns>
  <Card title="SMS opt-in and collection" icon="user-plus" href="./sms-opt-in-and-collection">
    Collection methods, required disclosure language, and audience validation for all program types.
  </Card>

  <Card title="One-time passwords" icon="lock" href="./sms-verify">
    OTP-specific opt-in patterns and verification with OneSignal Verify or your own backend.
  </Card>

  <Card title="Composing messages" icon="pen-to-square" href="./sms-composing-messages">
    Character limits, MMS, trackable links, and RCS rich content.
  </Card>

  <Card title="Regulatory compliance" icon="scale" href="./sms-regulatory-compliance">
    Consent standards, quiet hours, prohibited content, and fraud prevention.
  </Card>
</Columns>


# One-time passwords (OTP)
Source: https://documentation.onesignal.com/docs/en/sms-verify

Send one-time password messages with OneSignal for two-factor authentication, account verification, and fraud prevention. Covers OneSignal Verify, DIY code authentication, dedicated sender best practices, and audience validation.

A one-time password (OTP) message is a text containing a short, temporary code to verify a user's identity. The user enters the code into your app or website to prove they have access to the phone number they provided.

OTP messages provide:

* **Account protection:** preventing unauthorized access reduces support costs, fraud losses, and reputational damage
* **Phone number validation:** an OTP that gets delivered and entered correctly confirms the number is real, active, and in the hands of the person who submitted it
* **Fraud prevention at the front door:** OTPs at account creation deter fake signups, bot accounts, and abuse
* **Regulatory and compliance baseline:** for certain industries (finance, healthcare), multi-factor authentication is required. SMS OTP is the most accessible method because it works on every phone with no app install required

Common triggers:

* **Account creation:** confirming a new user's phone number during signup
* **Login / two-factor authentication:** adding a second layer of verification beyond a password
* **Password reset:** confirming identity before allowing a credential change
* **Transaction confirmation:** verifying a high-value action like a money transfer or address change

***

## Consent requirements

Consent for OTP messages follows the same standard as transactional messages. A user entering their phone number in a form that includes disclosure language is sufficient opt-in. The disclosure must appear directly on or near the phone number field, not on a separate page or buried in terms of service.

<Card title="Required disclosure language" icon="shield" href="./sms-opt-in-and-collection#otp-opt-ins">
  Disclosure language requirements and the full OTP opt-in compliance rules.
</Card>

***

## How to send OTP messages

There are two ways to send OTP messages with OneSignal:

| Method                             | Best for                                                                                      | What you manage                                                     |
| ---------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **OneSignal Verify** (Recommended) | Teams that want a managed solution: code generation, delivery, and validation handled for you | Configuration only                                                  |
| **Build your own**                 | Teams that need custom verification logic or already have a code generation system            | Code generation, storage, expiration, rate limiting, and validation |

***

## OneSignal Verify

<Note>
  Verify is only available to OneSignal SMS customers (not the Twilio integration).
</Note>

<Steps>
  <Step title="Create a verification service">
    Set a friendly name (your brand name), code length, and how often a code regenerates.
  </Step>

  <Step title="Send a verification code">
    Provide the user's phone number and the channel (`sms`). Optionally specify a custom code or override the code length.

    By default, the message sent to the end user says: *"Your \[brand name] verification code is: XXXXXX."*
  </Step>

  <Step title="Check the verification code">
    Provide the user's phone number and the code they entered. The API returns whether the code is valid.
  </Step>
</Steps>

### Additional considerations

* **Expiration:** Codes expire after 10 minutes by default. Contact support to customize.
* **Retries:** Handle failed verification attempts and implement retry logic in your app.
* **Security:** Follow best practices for handling sensitive data like phone numbers and verification codes.

***

## Build your own code authentication

You can also manage verification logic yourself: generating codes, tracking expiration, and validating attempts in your own backend. In this approach, you send OTP messages through the OneSignal [Create Message API](/reference/create-message) as a standard API-triggered SMS.

<Steps>
  <Step title="Generate a code in your backend">
    Typically 4–8 digits with an expiration window of 5–10 minutes.
  </Step>

  <Step title="Send it via the OneSignal API">
    Call the Create Message endpoint with the recipient's phone number, your OTP sender, and a message body containing the code (for example, *"Your \[brand name] verification code is 847291. It expires in 10 minutes."*).
  </Step>

  <Step title="Validate the code">
    When the user submits the code in your app, check it against what you stored. Invalidate the code after a successful check or after expiration, whichever comes first.
  </Step>
</Steps>

### Your responsibilities

* Generating and storing codes securely
* Enforcing expiration: codes should not be valid indefinitely
* **Rate limiting:** cap how many codes a single phone number can request in a given window to prevent SMS pumping fraud
* **Attempt limits:** lock out after a set number of failed entries (for example, 3–5 attempts) to prevent brute-force attacks
* **Retry logic:** handling cases where the SMS fails to deliver

***

## Dedicated sender best practice

While you can send OTP messages from any sender, it is best practice to use a dedicated sender approved for the authentication use case.

If your OTP messages share a sender with promotional or transactional messages, a single STOP opt-out means the user can no longer receive verification codes, effectively locking them out of their own account. A dedicated OTP sender keeps opt-outs scoped so a marketing unsubscribe never blocks a security code.

***

## Audience validation

A clean subscriber list is essential for OTP deliverability. Invalid or disconnected numbers mean verification codes don't reach the user, which can block account creation, lock users out of password resets, and erode trust in your authentication flow.

Validate phone numbers with Lookup at the point of collection, only collect numbers for regions you have an approved sender resource in, and store all numbers in E.164 format (for example, `+14155551234`).

<Card title="Audience validation" icon="circle-check" href="./sms-opt-in-and-collection#audience-validation">
  Full details on Lookup, region restrictions, ownership verification, and E.164 formatting.
</Card>

***

## FAQ

### What's the difference between OneSignal Verify and building my own OTP?

OneSignal Verify handles code generation, delivery, and validation for you. You only manage configuration. Building your own gives you more control over verification logic, but you are responsible for code generation, storage, expiration, rate limiting, and retry handling. OneSignal Verify is only available to OneSignal SMS customers (not the Twilio integration).

### How long do verification codes last with OneSignal Verify?

Codes expire after 10 minutes by default. Contact OneSignal support to customize the expiration window.

### Why do I need a dedicated sender for OTPs?

If a user texts STOP to a sender that handles both OTPs and other message types, they are opted out of all messages from that sender, including verification codes. This can lock them out of their account. A dedicated OTP sender keeps opt-outs cleanly scoped.

### What happens if an OTP fails to deliver?

With OneSignal Verify, contact support if you see widespread delivery failures. If you are building your own, implement retry logic in your backend and monitor for error codes in Audience Activity. See [SMS message reports](./sms-message-reports#understanding-sms-failures) for error code troubleshooting.

### Can I use OTP messages for account creation verification?

Yes. This is one of the most common use cases: sending a code during signup to confirm the user owns the phone number they provided. Lookup can also help at this stage to validate the number before sending.

***

## Related pages

<Columns>
  <Card title="SMS opt-in and collection" icon="user-plus" href="./sms-opt-in-and-collection">
    Collection methods, required disclosure language, and audience validation for all program types.
  </Card>

  <Card title="Transactional messaging" icon="receipt" href="./sms-transactional-messaging">
    Transactional use cases and collection points alongside OTP programs.
  </Card>

  <Card title="SMS message reports" icon="chart-line" href="./sms-message-reports">
    Delivery metrics and SMS error codes for troubleshooting OTP failures.
  </Card>

  <Card title="Create Message API" icon="code" href="/reference/create-message">
    API reference for triggering OTP and transactional sends from your backend.
  </Card>
</Columns>


# Suppressions
Source: https://documentation.onesignal.com/docs/en/suppressions

Manage suppressed email addresses in OneSignal to maintain list hygiene, reduce bounces, and protect your sender reputation.

The suppression list is an automated safeguard that helps maintain your email list hygiene and protect your sender reputation. When using OneSignal as your email service provider, this feature automatically manages problematic email addresses to prevent deliverability issues. See [Email deliverability](./email-deliverability) for more details.

## How it works

When OneSignal detects any of the following conditions:

* An email recipient marks your message as spam
* An email address produces a hard bounce (permanent delivery failure)

The system automatically adds these email addresses to your suppression list. Once an address is suppressed, OneSignal no longer sends emails to it, helping to:

* Maintain a clean email list
* Improve overall deliverability
* Protect your sender reputation
* Reduce bounce rates

## Managing your suppression list

You can view and manage your suppression list by navigating to **Settings** > **Email** > **Suppression**:

<Frame>
  <img alt="Suppression list in the OneSignal dashboard showing suppressed email addresses" />
</Frame>

Here you can find a list of all suppressed email addresses, separated into tabs depending on whether they were the result of a bounce, spam report, added manually through the dashboard, or uploaded via the [CSV Import](./import) tool.

<Tip>
  Use the **Reported as spam** tab to spot patterns by inbox provider. For example, if you see a high concentration of Outlook, Hotmail, or Live addresses reporting spam, that indicates poor sender reputation with Microsoft-owned inboxes. Review your consent and opt-in practices to ensure users are explicitly consenting to receive email. See [Email reputation best practices](./email-reputation-best-practices) for guidance on improving your sender reputation.
</Tip>

<Note>
  If you are using another ESP as your email service provider, your suppression list must be managed directly through your ESP's platform.
</Note>

### Adding new suppressions

To manually add a new email address to your suppression list, click the **Add Email** button:

<Frame>
  <img alt="Add Email button in the OneSignal suppression list" />
</Frame>

To add email addresses in bulk, click the **Import** buttons to use the [CSV Import](./import) tool. In the CSV, include a `suppressed` column with the value set to `true` for each email address row you want in the suppression list.

```csv Example CSV theme={null}
email,suppressed
test@example.com,true
```

Map this column to **suppressed** after uploading your CSV:

<Frame>
  <img alt="CSV import tool with suppressed column mapped for bulk suppression" />
</Frame>

<Card title="Import CSV tool" icon="file-csv" href="./import">
  Learn how to import email addresses in bulk using the CSV Import tool.
</Card>

### Removing suppressions

To remove a suppression, click the trash icon next to the email address:

<Warning>
  Removing an address from the suppression list allows OneSignal to send emails to it again. If the address was suppressed due to a hard bounce, re-sending to it may result in another bounce and can harm your sender reputation. Only unsuppress addresses you have confirmed are valid and able to receive email.
</Warning>

To remove emails in bulk, use the [CSV Import](./import) tool and include a `suppressed` column with the value set to `false` for each email you want to unsuppress. Map this column to **suppressed** after uploading your CSV.

***

## FAQ

### What triggers an automatic suppression?

OneSignal automatically suppresses an email address when a recipient marks your message as spam or when the address produces a hard bounce (permanent delivery failure). Soft bounces (temporary failures) are not automatically suppressed.

### Does removing a suppression re-subscribe the user?

Removing an address from the suppression list allows OneSignal to send to it again, but it does not change the user's subscription status. If the user previously unsubscribed, you must also update their subscription separately.

### Are suppressions per-app or account-wide?

Suppressions are per-app. Each OneSignal app maintains its own suppression list. An email address suppressed in one app is not automatically suppressed in another.

### What if I am using SendGrid, Mailchimp, or Mailgun directly?

The OneSignal suppression list only applies when OneSignal is your email service provider. If you are sending email through a third-party ESP like SendGrid, Mailchimp, or Mailgun, your suppression list must be managed directly through that provider's platform. OneSignal does not sync suppression data with external ESPs.

### Can I manage suppressions via the API?

You can add or remove suppressions in bulk using the [CSV Import](./import) tool. For individual suppression management via API, use the [Create User](/reference/create-user) or [Update Subscription](/reference/update-subscription) endpoints.

***

## Related pages

<Columns>
  <Card title="Email deliverability" icon="envelope-circle-check" href="./email-deliverability">
    Key concepts like reputation, bounces, spam traps, and inbox placement.
  </Card>

  <Card title="Email reputation best practices" icon="shield-check" href="./email-reputation-best-practices">
    Warm-up schedules, opt-in strategies, sunset policies, and more.
  </Card>

  <Card title="CSV import" icon="file-csv" href="./import">
    Import and manage user data including suppressions in bulk.
  </Card>
</Columns>


# Templates
Source: https://documentation.onesignal.com/docs/en/templates

Create, send, and track reusable templates for push notifications, email, and SMS in OneSignal with Liquid personalization and aggregate performance metrics.

Templates are reusable blueprints for push notifications, emails, and SMS messages. They ensure consistent messaging and centralize performance metrics across sends. Templates are especially useful for **frequently sent**, **event-driven**, or **transactional** messages.

<Card title="Template analytics" icon="chart-bar" href="./template-analytics">
  Review delivery statistics, engagement metrics, and per-recipient activity for each template.
</Card>

***

## Create templates

Templates can be created in multiple ways:

<Columns>
  <Card title="Dashboard" icon="browser">
    Go to **Messages > Templates** and click **New Template**.
  </Card>

  <Card title="API" icon="code" href="/reference/create-template">
    Create templates programmatically using the Create Template API.
  </Card>

  <Card title="Email template forwarding" icon="envelope" href="./email-template-forwarding">
    Migrate email templates from another email platform.
  </Card>

  <Card title="Copy between apps" icon="copy" href="/reference/copy-template-to-another-app">
    Copy templates between OneSignal apps (one-time copy, not a live sync).
  </Card>
</Columns>

### Design guidelines

Templates support [Liquid syntax](./using-liquid-syntax) for [advanced personalization](./message-personalization), letting you insert dynamic, user-specific content.

For channel-specific best practices, see:

<Columns>
  <Card title="Push notification design" icon="bell" href="./push">
    Push notification design, features, and platform options.
  </Card>

  <Card title="SMS messaging" icon="comment-sms" href="./sms-messaging">
    SMS design, features, and compliance requirements.
  </Card>

  <Card title="Email HTML design" icon="code" href="./design-emails-with-html">
    Build emails with full HTML and CSS control.
  </Card>

  <Card title="Email drag-and-drop design" icon="pen-ruler" href="./design-emails-with-drag-and-drop">
    Build emails visually with the drag-and-drop editor.
  </Card>
</Columns>

***

## Send messages using templates

You can send a template in multiple ways:

* **From the Compose Screen:** When creating a new message in the Dashboard, choose to start from a template.
* **From the Templates Page:** Go to **Messages > Templates**, select **Options (3 dots) > New Message**.
* **API:** Include the `template_id` in your [send request](/reference/create-message).

<Note>
  For SMS/RCS templates, you select a sender, and the editor shown depends on that sender: you get the RCS editor when the sender has an RCS resource, and the SMS editor otherwise. Selecting a sender with an approved RCS resource makes OneSignal automatically prefer RCS for all existing automations using that sender. See [Upgrading existing automations to RCS](./sms-composing-messages#upgrading-existing-automations-to-rcs) for how existing SMS content maps to RCS.
</Note>

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***

## Track performance

The **Templates** page shows aggregate lifetime performance across all sends using the template.

| Column        | Description                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| **Name**      | The template's name.                                                                                     |
| **Labels**    | [Labels](./labels) used to group and filter templates.                                                   |
| **Type**      | Push, Email, or SMS.                                                                                     |
| **Last Sent** | Date and time the template was last used in a sent message.                                              |
| **Delivered** | Total successful deliveries (to push servers, recipient inboxes, or SMS carriers, depending on channel). |
| **Opened**    | Total email opens (including repeat opens). Not applicable for push or SMS.                              |
| **Clicked**   | Total clicks on the notification or links within the email/SMS.                                          |
| **CTR**       | (Clicked ÷ Delivered) × 100%.                                                                            |

For per-send delivery stats, engagement breakdowns, and audience activity:

<Card title="Template analytics" icon="chart-bar" href="./template-analytics">
  Detailed per-template reports with channel-specific metrics and exportable audience data.
</Card>

***

## Update templates

You can update templates via:

* **Dashboard:** Go to **Messages > Templates > Options > Edit**.
* **API:** Use the [Update Template API](/reference/update-template).

Updating a template does not reset its performance stats. New links are tracked and aggregated alongside existing data.

Template fields can be overridden per message. You can use a template as a starting point and update content before sending.

For example, if your push template has a set message and you use the [Create push API](/reference/push-notification) with new `content`, it will override the template message.

***

## Delete templates

You can delete templates via:

* **Dashboard:** Go to **Messages > Templates > Options > Delete**.
* **API:** Use the [Delete Template API](/reference/delete-template).

<Warning>
  Once the template is deleted, all data associated with it is deleted and cannot be recovered.

  You cannot delete templates used within a Journey. Either delete the Journey or remove the template from the Journey.
</Warning>

***

## FAQ

### How long is template data stored?

Template content is stored for the lifetime of the template — until you delete it. Aggregate analytics on the **Templates** page are also lifetime. Individual send-level analytics follow your plan's retention policy. See [Template analytics](./template-analytics) for details.

### Can I duplicate templates across apps?

Yes. Use the [Copy Template to Another App API](/reference/copy-template-to-another-app) for any template type. For email specifically, you can also use [Email Template Forwarding](./email-template-forwarding).

### Does updating a template affect past messages?

No. Past messages retain the content they were sent with. Only future sends use the updated template. Performance stats are not reset.

### Can I use the same template for multiple channels?

No. Each template is tied to a single channel — push, email, or SMS. Create separate templates for each channel.

### Can I override template content when sending via API?

Yes. Include fields like `contents`, `headings`, or `email_body` in your [Create message](/reference/create-message) request alongside the `template_id`. The API fields override the corresponding template fields for that send only.

## Related pages

<Columns>
  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Personalize templates with tags, Liquid syntax, and custom event properties.
  </Card>

  <Card title="Liquid syntax" icon="code" href="./using-liquid-syntax">
    Full reference for Liquid templating in OneSignal messages.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Use templates in automated multichannel messaging flows.
  </Card>

  <Card title="Labels" icon="tag" href="./labels">
    Organize and filter templates with custom labels.
  </Card>
</Columns>


# Push throttling
Source: https://documentation.onesignal.com/docs/en/throttling

Push throttling controls how fast OneSignal delivers push notifications, helping you manage server load and avoid performance issues during high-volume sends.

## Overview

Push throttling controls the rate at which OneSignal delivers push notifications. Use throttling to distribute delivery over time — preventing server overload, avoiding performance degradation during mass sends, and maintaining a consistent user experience across devices.

***

## Why push sends impact your servers

Sending a push notification to a large audience can generate a sudden spike in traffic to your own servers — even if your click-through rate is low. This happens because delivery itself (not just clicks) triggers multiple types of requests back to your infrastructure. Understanding these sources helps you choose the right mitigation strategy.

### Self-hosted images and media

When a push notification includes an image (such as a `big_picture` or `chrome_web_image`), every device that receives the notification downloads that image immediately upon delivery. If the image is hosted on your own servers rather than a CDN, this creates one HTTP request per delivered notification — potentially tens of thousands of requests within seconds.

**Recommendations:**

* Host notification images on a CDN (e.g., CloudFront, Cloudflare, Fastly) instead of your application servers.
* Use [push throttling](#configuration-options) to spread delivery over time if you must self-host media.

### Simultaneous app opens

Push delivery prompts many users to open your app at the same time. Each app open typically generates multiple requests to your backend: session initialization, content fetches, API calls, and analytics events. Even a modest open rate can translate to a significant traffic spike if thousands of notifications are delivered simultaneously.

**Recommendations:**

* Use [push throttling](#configuration-options) to stagger delivery and spread app opens across a wider time window.
* Ensure your backend can handle burst traffic from high-volume sends, or use auto-scaling infrastructure.

### Event Streams

If you have [Event Streams](./event-streams) configured with a webhook destination, OneSignal sends an HTTP request to your endpoint for each event (e.g., `message.sent`, `message.delivered`, `message.clicked`) in real time. During a large push send, this can produce a burst of webhook requests proportional to your audience size.

<Note>
  OneSignal does not rate-limit outbound Event Stream webhook traffic. Your endpoint must be able to handle the volume of events generated by your message sends.
</Note>

**Recommendations:**

* Ensure your webhook endpoint can handle throughput proportional to your audience size.
* Use an intermediary queue or buffer (e.g., Amazon Kinesis, Google Pub/Sub) instead of a direct webhook to absorb bursts. Event Streams supports these as destinations natively.
* Use [push throttling](#configuration-options) to reduce the peak rate of events hitting your endpoint.

### Journey webhooks

[Journey webhooks](./journeys-webhook) send HTTP requests to your servers as users reach specific steps in a Journey. While Journeys naturally pace delivery based on user behavior, high-traffic Journeys can still generate significant webhook volume. Slow or overloaded endpoints may trigger automatic disabling of the webhook.

**Recommendations:**

* Design your webhook endpoint to respond quickly (return `200 OK`) and defer heavy processing to a background job.
* Monitor for `429` responses from your endpoint, which can trigger OneSignal to disable the webhook.
* Review the [performance guidance](./journeys-webhook#performance-guidance) in the Journey webhooks documentation.

### Service Worker fetches (web push)

For web push, browsers periodically re-fetch the [OneSignal Service Worker](./onesignal-service-worker) file from your server (typically when the cache expires, up to every 24 hours). When a push notification is delivered, the browser may check for an updated Service Worker file — generating one request per web push subscription back to your hosting server.

**Recommendations:**

* Serve the `OneSignalSDKWorker.js` file from a CDN or ensure your hosting server can handle the request volume.
* Set appropriate cache headers to reduce re-fetch frequency.
* See the [OneSignal Service Worker](./onesignal-service-worker) documentation for more details.

### Choosing the right approach

| Traffic source           | Affected by throttling?                            | Alternative mitigation                                   |
| ------------------------ | -------------------------------------------------- | -------------------------------------------------------- |
| Self-hosted images       | Yes — slower delivery = fewer concurrent downloads | Host on a CDN                                            |
| Simultaneous app opens   | Yes — staggered delivery spreads user sessions     | Auto-scaling infrastructure                              |
| Event Streams (webhooks) | Yes — slower delivery = slower event rate          | Use a queue-based destination (Kinesis, Pub/Sub, etc.)   |
| Journey webhooks         | No — Journeys don't support throttling             | Optimize endpoint performance; use background processing |
| Service Worker fetches   | Yes — slower delivery = fewer concurrent fetches   | CDN hosting; cache headers                               |

***

## Configuration options

Throttling must be enabled at the global settings level to be available for use.

### Global throttling settings

Enable throttling for all push messages under **Settings > Push & In-App > Throttling**. Once enabled, this setting applies to all push notifications by default, but can be overridden for individual messages.

<Frame>
  <img alt="Push throttling settings in the OneSignal dashboard under Settings > Push & In-App > Throttling" />
</Frame>

### Per-message throttling override

You can override global throttling settings on individual messages.

1. During notification creation, check the "Override throttling setting" box
2. Set your desired messages-per-minute rate
3. To disable throttling for a specific message, enter "0" in the messages-per-minute field

For API-sent notifications, use the [`throttle_rate_per_minute`](/reference/create-message) property.

***

## How throttling works

### Rate conversion process

OneSignal converts your per-minute setting to a per-second rate to optimize delivery:

1. The system divides your throttle rate by 60 (seconds per minute)
2. The result is rounded down to the nearest whole number (OneSignal can't send partial messages)
3. This per-second rate is then applied throughout the delivery process

**Example:** You set a throttle rate of 1,019 messages per minute.

1. OneSignal divides by 60: 1,019 ÷ 60 = 16.98 messages per second
2. Rounds down to 16 messages per second
3. Actual delivery rate: 16 × 60 = **960 messages per minute** (59 fewer than the set rate)

This conversion ensures more efficient processing by eliminating delays between batches.

***

## Limitations and considerations

### 24-hour delivery window

All throttled notifications must complete delivery within 24 hours of being sent. If your throttling rate would cause delivery to exceed 24 hours, OneSignal automatically adjusts the rate to ensure completion within this timeframe.

**Example:** You set a throttle rate of 10 messages per minute for 20,000 users — delivery would take approximately 33 hours. OneSignal automatically adjusts the rate to around 14 messages per minute to complete delivery within 24 hours.

***

## Compatibility and availability

Throttling is only available for push notifications sent via the [Create notification](/reference/create-message) API or the **Messages > New Push** dashboard interface. It is not supported for Journeys (see the [summary table](#choosing-the-right-approach) above).

### Timezone and Intelligent Delivery

Throttling takes precedence over Timezone and Intelligent Delivery. When throttling is enabled, OneSignal ignores these features for that notification.

**To use Timezone or Intelligent Delivery:**

* Disable throttling for that specific notification under Delivery Schedule
* Set "Override throttling setting" to "0"
* For API notifications, set `throttle_rate_per_minute: 0`

***

## FAQ

### Does throttling work with Intelligent Delivery or Timezone delivery?

No. Throttling takes precedence over both Intelligent Delivery and Timezone delivery. When throttling is enabled for a notification, OneSignal ignores these scheduling features.

To use Intelligent Delivery or Timezone delivery, disable throttling for that specific notification using the per-message override.

In the dashboard, uncheck "Override throttling setting" or set the rate to `0`. Via the API, pass `throttle_rate_per_minute: 0` in your [Create notification](/reference/create-message) request. This tells OneSignal to skip throttling for that notification and respect the delivery schedule you've configured.

### What happens if my throttle rate would take longer than 24 hours?

OneSignal automatically increases the throttle rate so delivery completes within 24 hours. For example, sending to 20,000 users at 10 messages per minute would take \~33 hours, so OneSignal adjusts the rate to \~14 messages per minute.

### Can I throttle Journeys?

No. Throttling only applies to push notifications sent via the dashboard (**Messages > New Push**) or the [Create notification](/reference/create-message) API. Journeys deliver dynamically as users qualify, which naturally distributes delivery over time.

### Why is my actual delivery rate lower than what I set?

OneSignal converts your per-minute rate to a per-second rate and rounds down. For example, 1,019 messages per minute becomes 16 messages per second (1,019 ÷ 60 = 16.98, rounded down), resulting in an actual rate of 960 messages per minute.

***

## Related pages

<Columns>
  <Card title="Push overview" icon="bell" href="./push">
    Send and manage mobile and web push notifications with OneSignal.
  </Card>

  <Card title="Create notification API" icon="code" href="/reference/create-message">
    API reference for creating and sending notifications, including the `throttle_rate_per_minute` property.
  </Card>

  <Card title="Event Streams" icon="satellite-dish" href="./event-streams">
    Stream delivery and engagement events to webhooks, Kinesis, or Pub/Sub.
  </Card>

  <Card title="OneSignal Service Worker" icon="gear" href="./onesignal-service-worker">
    Configure the Service Worker file for web push notifications.
  </Card>

  <Card title="Journeys overview" icon="route" href="./journeys-overview">
    Build multi-step messaging workflows that respond to user actions.
  </Card>
</Columns>


# WordPress troubleshooting
Source: https://documentation.onesignal.com/docs/en/troubleshooting-wordpress-web-push

Comprehensive guide for troubleshooting common setup issues with OneSignal Web Push Notifications on WordPress, including browser compatibility (Chrome, Firefox, Safari), plugin integration, and resolving CDN or caching conflicts.

## Common setup issues

### Verify your OneSignal dashboard setup

Make sure you’ve completed each step in the [WordPress setup guide](./wordpress):

* Select the **WordPress Plugin** option when creating your OneSignal app
* Your Site URL must exactly match the browser URL
  * For example, `https://example.com` is **not** the same as `https://www.example.com`. Use one version consistently.
  * Only one site origin is supported for push. See [Same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy).
* Make sure you've added at least one permission prompt.

### Do not add the OneSignal code manually

The OneSignal WordPress plugin **automatically** includes the initialization script and Service Worker.

* Do **not** add OneSignal JavaScript `init` code to your site.
* Do **not** use the [Custom Code Setup](./web-push-custom-code-setup) with the WordPress plugin. If you need to customize the `init` method, **uninstall the plugin** and add the code and Service Worker manually.

### Send notification when post published

When you publish a post, page, or custom post type, OneSignal can automatically send a notification to your subscribers.

<Frame>
  <img alt="OneSignal Push Notifications metabox—drag to reposition if needed" />
</Frame>

If you do not see the **Send notification when post is published or updated** checkbox, check these items:

1. Check the metaboxes to the right and bottom of the editor. You can drag and drop as needed.
2. Check the Screen Options at the top of the editor to make sure the **OneSignal Push Notifications** metabox is checked.

<Frame>
  <img alt="Screen Options showing OneSignal Push Notifications metabox checked" />
</Frame>

3. Check if using a Custom Post Type. This is usually found in the URL as `post_type=your_custom_type`. If so, add the custom post type to the **Custom Post Types** field in the [OneSignal WordPress plugin settings](./wordpress#add-a-custom-post-type-to-onesignal-wordpress-plugin).

<Frame>
  <img alt="OneSignal WordPress plugin settings showing Custom Post Types field" />
</Frame>

***

## How to troubleshoot your site

<Steps>
  <Step title="Verify plugin is active and open developer tools">
    Load your site in a normal (non-incognito) browser window with the plugin enabled.

    <Frame>
      <img alt="Browser DevTools open with the Console tab selected on a WordPress site" />
    </Frame>
  </Step>

  <Step title="Check the console for OneSignal errors">
    Open the **Console** tab, refresh the page, and look for any red or yellow OneSignal-related errors.
    See [Common OneSignal console errors](#common-onesignal-console-errors) for help.
  </Step>

  <Step title="Check subscription status in the browser">
    After the page finishes loading and you see no OneSignal errors in the Console, paste:

    ```javascript JavaScript theme={null}
    OneSignal.User.PushSubscription.id
    ```

    If the visitor is subscribed, this returns a string (the Subscription ID). If they are not subscribed or the subscription is not ready yet, you may see **`null`** or an empty value. If you see **`OneSignal is not defined`**, wait a few seconds and try again, or fix Console errors from [Common OneSignal console errors](#common-onesignal-console-errors) first—the SDK may still be loading via the deferred loader.

    <Frame>
      <img alt="Browser console showing OneSignal User PushSubscription id string result" />
    </Frame>
  </Step>

  <Step title="Verify Subscription ID in OneSignal dashboard">
    In the **OneSignal dashboard**, go to **Audience > Subscriptions** and search for the ID returned above.

    <Frame>
      <img alt="OneSignal dashboard Subscriptions search field with subscription ID lookup" />
    </Frame>
  </Step>

  <Step title="Send a test push notification">
    If the subscription exists and status is **Subscribed**, follow the [Push guide](./push) to send a notification.
    If nothing appears, see [Notifications not shown](./notifications-not-shown-web-push) for browser-specific fixes.
  </Step>
</Steps>

***

## Common OneSignal console errors

### <Danger>SdkInitError: OneSignal: This web push config can only be used on ... Your current origin is ...</Danger>

<Frame>
  <img alt="Console SdkInitError showing web push config origin mismatch" />
</Frame>

Your site URL in the OneSignal dashboard doesn’t match your actual domain.
Make sure it exactly matches the domain you see in the browser.

### <Danger>PushPermissionNotGrantedError: The user dismissed the permission prompt.</Danger>

The visitor declined the browser prompt. It won’t appear again until a cooldown period expires.
See [Web permission prompts](./permission-requests) for browser rules or clear site data to retry immediately.

### <Danger>The OneSignal web SDK can only be initialized once.</Danger>

<Frame>
  <img alt="Console error OneSignal web SDK can only be initialized once" />
</Frame>

You're loading OneSignal twice. Remove manually added OneSignal code if you're using the plugin.

### <Danger>Installing service worker failed.. 403 or 404 error</Danger>

<Frame>
  <img alt="Console error installing service worker failed with 403 or 404" />
</Frame>

Make sure this file is accessible (replace `your-site.com` and match your **actual plugin folder name** if it differs from the default):

`https://your-site.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js`

If not, see [Common plugin support](#common-plugin-support) to fix CDN or caching issues.

***

## Common plugin support

CDNs and caching plugins can block OneSignal’s required files. Paths below assume the plugin directory is **`onesignal-free-web-push-notifications`**; adjust if your install uses a different folder name.

Use these plugin-specific settings:

### Autoptimize

In **Excluded scripts**, add:

```
wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/(.*)
```

### WP Rocket

Under **CDN > Exclude Files From CDN**, add:

```
(.*)/onesignal-free-web-push-notifications/sdk_files/(.*)
```

### LiteSpeed Cache

Under **CDN > Exclude Path**, add:

```
(.*)/onesignal-free-web-push-notifications/sdk_files/(.*)
```

Then press save.

### WP Super Cache

1. Go to **Settings > WP Super Cache > CDN**
2. In **Exclude if substring**, include: `onesignal-free-web-push-notifications`
3. Click **Contents** > **Delete Cache**

### WP Engine

WP Engine can rewrite plugin URLs through its CDN. **HTML Post-Processing** rules are environment-specific; the snippet below is an **example only**—confirm paths with [WP Engine support](https://wpengine.com/support/) or your User Portal before applying.

In the WP Engine **plugin > General Settings > HTML Post-Processing**, you may need rules similar to the following. Replace every placeholder with values from **your** site and WP Engine CDN hostname:

| Placeholder            | Replace with                                                            |
| ---------------------- | ----------------------------------------------------------------------- |
| `YOURSITEHERE`         | Your bare domain (regex segment), e.g. `example` for `example.com`      |
| `mywpenginehandleHere` | Your WP Engine install name (subdomain before `.wpengine.com`)          |
| `wpengineCDNpathHere`  | Your NetDNA / CDN path segment from WP Engine (often shown in CDN URLs) |
| `mywebsiteHere`        | Your live site origin without path, e.g. `https://example.com`          |

```text theme={null}
#https?://(www\.)?(YOURSITEHERE\.com|mywpenginehandleHere.wpengine.com|wpengineCDNpathHere.wpengine.netdna-(ssl|cdn).com)/wp-(content|includes)#
=> https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-$4
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/plugins/onesignal-free-web-push-notifications/#
=> https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-content/plugins/onesignal-free-web-push-notifications/#
=> https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/
```

### W3 Total Cache

1. Go to **Performance > CDN**
2. Under **Rejected files**, add:

```
{plugins_dir}/onesignal-free-web-push-notifications/sdk_files/*
```

<Frame>
  <img alt="W3 Total Cache CDN rejected files list including OneSignal sdk_files path" />
</Frame>

### BunnyCDN

Exclude *onesignal* in the plugin's CDN Excluded Paths.

<Frame>
  <img alt="BunnyCDN WordPress plugin excluded paths including onesignal" />
</Frame>

### CDN Enabler

In Settings > CDN Enabler, add this to "Exclusions":

```
onesignal-free-web-push-notifications
```

### PressCDN

In Exclude Directories, add:

```
/wp-content/plugins/onesignal-free-web-push-notifications/
```

### Breeze

In **Settings > CDN > Exclude Content**, add:

```
/onesignal-free-web-push-notifications/sdk_files/
```

<Frame>
  <img alt="Breeze CDN exclude content field with OneSignal sdk_files path" />
</Frame>

### Hummingbird Pro

Go to **Hummingbird > Asset Optimization**. Under **JavaScript** (and **CSS** if OneSignal assets appear there), locate files whose URLs contain **`onesignal-free-web-push-notifications`** or **`OneSignalSDK`**. **Exclude** them from minification/combination/defer, or switch those assets to **Don't load** optimization so the plugin does not rewrite or delay them.

<Frame>
  <img alt="Hummingbird Pro asset optimization list showing script exclusions" />
</Frame>

### Sucuri

Follow [Sucuri's Whitelist guide](https://kb.sucuri.net/firewall/Whitelist+and+Blacklist/whitelist-file-folder) to allow OneSignal files.

### Solid Security (formerly iThemes Security)

Disable **Disable PHP in Plugins** (or equivalent) under **System Tweaks** so `OneSignalSDKWorker.js.php` can run.

<Frame>
  <img alt="Security plugin setting to allow PHP in plugins unchecked or disabled" />
</Frame>

### Defender Security plugin

Do not enable "Prevent PHP execution".
Go to Defender Plugin > Security Tweaks and verify the setting is disabled.

### Example .htaccess for Service Worker access

```apache theme={null}
<Files *.php>
Order allow,deny
Deny from all
</Files>
<Files OneSignalSDKWorker.js.php>
Allow from all
ForceType 'application/javascript; charset=UTF-8'
</Files>
<Files OneSignalSDKWorker.js>
Allow from all
ForceType 'application/javascript; charset=UTF-8'
</Files>
```

<Note>
  Apache 2.4+ often uses `Require all denied` / `Require all granted` instead of `Order allow,deny`. Ask your host or adjust the rules to match your server’s Apache version.
</Note>

***

## Server slowdowns or site unreachable after sending notifications

If your server experiences slowdowns or becomes unreachable after sending notifications, it is often due to increased load from notification assets or limited server resources.

### Do not host your own notification icons

Avoid self-hosting images used in notifications. When you host your own notification icons or images, your server may become overloaded as every recipient’s browser attempts to fetch the image at the same time a notification is sent.
To reduce server strain, use image hosting solutions or CDN services optimized for high-concurrency access.

### Consider upgrading hosting resources

If server issues persist, you may need to:

* **Upgrade your hosting plan:** Higher bandwidth or more powerful hosting may be necessary to handle large-scale notification sends.
* **Consult your hosting provider:** Your provider can offer insights or optimizations specific to your hosting environment.

***


# Email unsubscribe links & headers
Source: https://documentation.onesignal.com/docs/en/unsubscribe-links-email-subscriptions

Learn how to manage email unsubscribe behavior in OneSignal, including unsubscribe links, List-Unsubscribe headers, suppression rules, and resubscription workflows.

Managing how users unsubscribe from your emails is critical to complying with email standards (like CAN-SPAM), ensuring strong deliverability with providers like Gmail and Yahoo, and building trust with your audience.

OneSignal supports both visible unsubscribe links and List-Unsubscribe headers, ensuring your emails are fully compliant while giving you control over when and how users can opt out.

## Subscription states and suppression logic

Email [Subscriptions](./subscriptions) are either:

* **Subscribed** – eligible to receive email messages.
* **Unsubscribed** – excluded from most email sends unless explicitly overridden.

To include unsubscribed Subscriptions in your email (e.g., for transactional messages):

* In the dashboard: Enable **Advanced Settings > Include sending to unsubscribed users** when sending an email.
* In the API: Use the `include_unsubscribed` property in the [create email notification API](/reference/email).

<Frame>
  <img />
</Frame>

***

## How users get unsubscribed

Email subscription status is updated via:

* The user clicking an unsubscribe link or List-Unsubscribe header
* You [importing a CSV of email addresses](./import) and setting `subscribed` to `no`.
* You setting `enabled : false` via the [Create user](/reference/create-user), [Update user](/reference/update-user), or [Update subscription](/reference/update-subscription) APIs.
* You manually unsubscribing from **Audience > Subscriptions > Options > Unsubscribe from Email**

***

## How unsubscribes are processed

What happens when a recipient unsubscribes depends on which method they use:

* **OneSignal unsubscribe link**: When a recipient clicks the `[unsubscribe_url]` link and confirms on the hosted page, OneSignal marks their subscription as **Unsubscribed** immediately. The email provider does not register this as an unsubscribe event on their end.

* **Email client unsubscribe button**: When a recipient uses the native "Unsubscribe" button in their email client (surfaced via the List-Unsubscribe header), the email provider captures the event and notifies OneSignal, which then updates the subscription status.

* **Custom unsubscribe or preference center page**: If you use your own unsubscribe URL, the email provider only sees a link click and does not trigger an unsubscribe event. You are responsible for calling the OneSignal API to update the subscription status based on what the recipient does on your page. See [Create a Custom Unsubscribe Page](./create-custom-unsubscribe-page).

***

## Unsubscribe header vs unsubscribe link

* **List-Unsubscribe header**: A hidden email header used by inbox providers to display native “Unsubscribe” buttons (e.g., Gmail, Yahoo).
* **Unsubscribe link**: A visible clickable URL placed in your email content using the `[unsubscribe_url]` token.

### List-Unsubscribe header behavior

OneSignal includes a `List-Unsubscribe` header in all emails **except when you enable “Include sending to unsubscribed users.”** This helps:

* Prevent your emails from being marked as spam
* Comply with [Gmail/Yahoo 2024 rules](https://onesignal.com/blog/guide-to-2024-gmail-and-yahoo-requirements-for-email-senders/).

<Warning>
  The List-Unsubscribe header is **not included** if you enable "Include sending to unsubscribed users."

  Some inbox providers may hide this header from display unless you meet certain sending volume thresholds. See [Gmail's](https://support.google.com/a/answer/81126?visit_id=638683263663552218-2680312485\&rd=1#requirements-5k\&zippy=%2Crequirements-for-sending-or-more-messages-per-day) and [Yahoo's](https://senders.yahooinc.com/best-practices/) requirements.
</Warning>

If a user clicks this, their email Subscription will be marked as unsubscribed in your OneSignal app.

### Adding unsubscribe links in emails

OneSignal provides the `[unsubscribe_url]` token, which inserts a visible unsubscribe link into your email content.

You can also create a branded experience with your own unsubscribe page. See [Create a custom unsubscribe page](./create-custom-unsubscribe-page).

#### HTML editor

If using our HTML editor, the default template includes an unsubscribe link automatically:

<Frame>
  <img />
</Frame>

To add it manually (e.g. via API with `email_body`):

```html HTML theme={null}
<a href="[unsubscribe_url]">Unsubscribe</a>
```

#### Drag & drop editor

In a text block:

1. Click **Special Links > Suppression > Unsubscribe**
2. The `[unsubscribe_url]` placeholder is inserted
3. You can highlight text before inserting to turn it into a link

<Frame>
  <img />
</Frame>

<Info> Always make unsubscribe links **highly visible** with readable font sizes (at least 12px) and strong contrast. Hidden or hard-to-find links can lead users to mark your messages as spam, harming future deliverability. </Info>

***

## Custom unsubscribe link destinations

You may replace `[unsubscribe_url]` with your own unsubscribe landing page.

To do this:

* Follow the steps in [Create a Custom Unsubscribe Page](./create-custom-unsubscribe-page).
* Replace `[unsubscribe_url]` in your email with the URL of your custom unsubscribe page.

<Warning>
  If using a custom link, OneSignal will not automatically mark the user as unsubscribed. You must handle that through the API or page behavior.
</Warning>

***

## FAQ

### Why isn’t the unsubscribe link working in my test email?

If your OneSignal email sending domain is not yet verified, unsubscribe links in test emails won’t be functional. You’ll see placeholder text, but no real link.

Once your domain is verified, unsubscribe links will render and function properly.

### How do I resubscribe an email address?

Users can be resubscribed in three ways:

1. Dashboard: Go to **Audience > Subscriptions > Options > Resubscribe to Email**
2. API: Set `enabled: true` in the [Create User](/reference/create-user) or [Update subscription](/reference/update-subscription) APIs
3. CSV Import: Set `subscribed = yes` when importing email addresses

<Warning>
  If you use a third-party email provider, that provider maintains its own suppression list that OneSignal cannot access directly. An address marked **Subscribed** in OneSignal may still be suppressed on the provider's side. If a resubscribed address still is not receiving emails, check and remove it from the provider's suppression list as well.
</Warning>

### Why are there two unsubscribe links in my email?

If you're using ESPs like Mailgun or SendGrid, they may insert their own unsubscribe link. You can disable this in your ESP's settings to avoid duplication.

### Do unsubscribe clicks count toward analytics?

* Clicking the OneSignal custom `[unsubscribe_url]` does not count towards click analytics.
* Clicking a custom unsubscribe URL will be counted as a click. See [URLs, Links, and Deep Links](./links) for more details.

***

## Related articles

* [Create a Custom Unsubscribe Page](./create-custom-unsubscribe-page)
* [Email Messaging](./email-messaging)
* [Email API](/reference/email)
* [URLs, Links, and Deep Links](./links)

***


# Using Liquid syntax
Source: https://documentation.onesignal.com/docs/en/using-liquid-syntax

Personalize email, push, SMS, in-app, and Live Activity content with Liquid tags, filters, conditionals, and loops — powered by OneSignal data sources like tags, properties, custom data, and Data Feeds.

## Overview

Liquid is a templating language OneSignal uses to insert dynamic values into messages at send time. You write Liquid expressions in supported fields; OneSignal replaces them with the matching value for each recipient just before delivery.

```liquid Liquid theme={null}
Hi {{ first_name | default: "there" }}!
You have {{ message.custom_data.cart.size }} items in your cart.
```

OneSignal supports two syntax structures:

| Syntax                      | Purpose                                 | Example                              |
| --------------------------- | --------------------------------------- | ------------------------------------ |
| **Output tags** `{{ ... }}` | Print a value (with optional filters).  | `{{ user.tags.first_name }}`         |
| **Logic tags** `{% ... %}`  | Run a conditional, loop, or assignment. | `{% if level > 5 %} ... {% endif %}` |

For the language itself, see the [official Liquid documentation](https://shopify.github.io/liquid/basics/introduction/). This page focuses on the parts that work in OneSignal and the OneSignal-specific data objects you can reference.

Liquid support varies by channel and by field. Most notably, in-app messages support **only Tag substitution** (no `journey.*`, `message.*`, `subscription.*`, or `user.*` objects), and the push `data` field does not support Liquid at all. See [Supported fields by message type](./message-personalization#supported-fields-by-message-type) for the full per-channel breakdown.

***

## Prerequisites

* A [OneSignal account](https://dashboard.onesignal.com).
* The data you want to reference is already available to OneSignal — for example, [Tags set on the user](./add-user-data-tags), `external_id`, [Custom Event](./personalization-custom-event) properties on a Journey, or [`custom_data` in the Create Message API](./personalization-api-custom-data).
* A message or [template](./templates) where you can edit the field that will use Liquid.

***

## Conditionals

### `if`, `elsif`, `else`

Render different content based on a value.

```liquid Liquid theme={null}
{%- assign userLang = subscription.language -%}
{% if userLang == "es" -%}
Hola {{ first_name }}!
{%- elsif userLang == "fr" -%}
Bonjour {{ first_name }}!
{%- else -%}
Hello {{ first_name }}!
{%- endif %}
```

### `unless`

Inverse of `if` — runs the block when the condition is false.

```liquid Liquid theme={null}
{% unless level == "1" %}
  Great job getting past the first level!
{% endunless %}
```

<Note>
  Tag values are stored as strings. If you compare a numeric tag, either compare against a string (`level == "1"`) or cast first with `{% assign n = level | plus: 0 %}` and then compare numerically.
</Note>

### `case` / `when`

Map a single variable to specific values with a fallback `else`. Useful when interpolating the variable directly would produce invalid output (for example, an unsupported language code in a URL).

```liquid Liquid theme={null}
{% case subscription.language %}
  {% when "es" %}https://example.com/es/page
  {% when "fr" %}https://example.com/fr/page
  {% when "de" %}https://example.com/de/page
  {% else %}https://example.com/en/page
{% endcase %}
```

### Operators

You can use these operators inside `if`, `elsif`, and `unless`.

| Operator             | Meaning                                  |
| -------------------- | ---------------------------------------- |
| `==`, `!=`           | Equal, not equal                         |
| `>`, `<`, `>=`, `<=` | Numeric comparison                       |
| `and`, `or`          | Logical AND / OR                         |
| `contains`           | Substring (string) or membership (array) |

Liquid evaluates conditions **right-to-left** — not by operator precedence — and does **not** support parentheses for grouping. Refactor with nested `if` blocks if you need explicit grouping.

```liquid Liquid theme={null}
{% if false and true or true %}
  Does not render. Right-to-left: (true or true) → true, then (false and true) → false.
{% endif %}
```

If you tried to read this as `(false and true) or true`, you would expect it to render — but Liquid groups the rightmost two operands first, so the final check is `false and ...`.

***

## Variables

### `assign`

Create a reusable variable inside a template. Useful for shortening references and for casting tag values to numbers.

```liquid Liquid theme={null}
{% assign cart = message.custom_data.cart %}
{% assign item_count = cart.size | plus: 0 %}

You have {{ item_count }} items in your cart.
First item: {{ cart.first.product_name }}
```

### Bracket notation for special characters

Use bracket notation when a key contains spaces, hyphens, or other non-alphanumeric characters.

```liquid Liquid theme={null}
{{ user.tags["order status"] }}
{{ journey.first_event.properties["order-id"] }}
{{ message.custom_data["full name"] }}
```

***

## Filters

Apply filters with `{{ variable | filter }}`. You can chain filters: `{{ name | downcase | capitalize }}`.

### `default`

Render a fallback value when the input is empty, null, or undefined.

```liquid Liquid theme={null}
Hello {{ first_name | default: "there" }}.
```

### `date`

Format a timestamp using [strftime](https://strftime.net/) directives. The input can be a Unix timestamp, a parseable date string, or the special words `"now"` / `"today"`.

<Note>
  `"now"` is evaluated **per recipient at send time**. In test sends, it reflects when the test was sent.
</Note>

**From a Unix timestamp tag:**

Store dates as Unix timestamps (seconds) on user tags. The same tag then works for both Liquid date formatting and [Time Operator segmentation](./time-operators) — for example, a tag like `bill_due: 1687968776`.

```liquid Liquid theme={null}
{{ bill_due | date: "%a, %b %d, %y" }}
{{ bill_due | date: "%Y" }}
```

```text Result theme={null}
Wed, Jun 28, 23
2023
```

**From a date string:**

```liquid Liquid theme={null}
{{ "March 14, 2016" | date: "%b %d, %y" }}
```

```text Result theme={null}
Mar 14, 16
```

**Current time at send:**

```liquid Liquid theme={null}
This message was sent at {{ "now" | date: "%Y-%m-%d %H:%M" }}.
```

```text Result theme={null}
This message was sent at 2022-11-02 14:39.
```

### `round`

Round a number to the nearest integer, or to a specified number of decimal places.

```liquid Liquid theme={null}
{{ 1.2 | round }}
{{ 2.7 | round }}
{{ 183.357 | round: 2 }}
```

```text Result theme={null}
1
3
183.36
```

### `pluralize`

Return the singular or plural form of a string based on a count. The count must be a whole number; strings that look like whole numbers are accepted.

<Note>
  `pluralize` is a OneSignal addition — it is not part of the standard Shopify Liquid filter set. Use it inside OneSignal templates only.
</Note>

```liquid Liquid theme={null}
{{ 1 | pluralize: "singular", "plural" }}
{{ 2 | pluralize: "singular", "plural" }}
1 {{ 1 | pluralize: "person", "people" }}
2 {{ 2 | pluralize: "person", "people" }}
2 {{ "2" | pluralize: "person", "people" }}
```

```text Result theme={null}
singular
plural
1 person
2 people
2 people
```

### Math filters

Useful for casting strings to numbers and for arithmetic inside templates.

| Filter       | Example                     | Result               |
| ------------ | --------------------------- | -------------------- |
| `plus`       | `{{ "2" \| plus: 0 }}`      | `2` (cast to number) |
| `minus`      | `{{ 10 \| minus: 3 }}`      | `7`                  |
| `times`      | `{{ 4 \| times: 5 }}`       | `20`                 |
| `divided_by` | `{{ 20 \| divided_by: 4 }}` | `5`                  |
| `modulo`     | `{{ 10 \| modulo: 3 }}`     | `1`                  |

### Array filters

Used with arrays from `custom_data`, Custom Event properties, or Tags.

| Filter  | Description                                              | Example                                        |
| ------- | -------------------------------------------------------- | ---------------------------------------------- |
| `size`  | Number of items in an array (or characters in a string). | `{{ cart.size }}`                              |
| `first` | First item. Equivalent to `[0]`.                         | `{{ cart.first.product_name }}`                |
| `last`  | Last item.                                               | `{{ cart.last.product_name }}`                 |
| `where` | Filter to items whose property matches a value.          | See [`where` example](#where-example) below.   |
| `join`  | Concatenate array items with a separator.                | `{{ message.custom_data.skus \| join: ", " }}` |
| `split` | Split a string into an array.                            | `{{ "a,b,c" \| split: "," }}`                  |

#### `where` example

Given a list of products, build a sub-list containing only the kitchen ones:

```liquid Liquid theme={null}
{% assign products = message.custom_data.products %}
{% assign kitchen_products = products | where: "type", "kitchen" %}

Kitchen products:
{% for product in kitchen_products %}
- {{ product.name }}
{% endfor %}
```

```json Custom data theme={null}
{
  "products": [
    { "name": "Vacuum",        "type": "electronics" },
    { "name": "Spatula",       "type": "kitchen" },
    { "name": "Television",    "type": "electronics" },
    { "name": "Garlic press",  "type": "kitchen" }
  ]
}
```

```text Result theme={null}
Kitchen products:
- Spatula
- Garlic press
```

### String filters

Apply string filters to adjust how values render.

| Filter          | Description                                         | Example                                                        | Output              |
| --------------- | --------------------------------------------------- | -------------------------------------------------------------- | ------------------- |
| `replace`       | Replace every occurrence of a substring.            | `{{ "hello world" \| replace: "world", "there" }}`             | `hello there`       |
| `replace_first` | Replace only the first occurrence.                  | `{{ "hello world world" \| replace_first: "world", "there" }}` | `hello there world` |
| `capitalize`    | Capitalize the first character; lowercase the rest. | `{{ "my GREAT title" \| capitalize }}`                         | `My great title`    |
| `upcase`        | Convert to uppercase.                               | `{{ "hello" \| upcase }}`                                      | `HELLO`             |
| `downcase`      | Convert to lowercase.                               | `{{ "HELLO" \| downcase }}`                                    | `hello`             |
| `strip`         | Remove leading and trailing whitespace.             | `{{ " hello " \| strip }}`                                     | `hello`             |
| `lstrip`        | Remove leading whitespace.                          | `{{ " hello" \| lstrip }}`                                     | `hello`             |
| `rstrip`        | Remove trailing whitespace.                         | `{{ "hello " \| rstrip }}`                                     | `hello`             |
| `strip_html`    | Strip HTML tags.                                    | `{{ "<p>hello</p>" \| strip_html }}`                           | `hello`             |
| `truncate`      | Shorten a string to N characters; appends `…`.      | `{{ "This is a long sentence" \| truncate: 10 }}`              | `This is a…`        |
| `truncatewords` | Shorten a string to N words; appends `…`.           | `{{ "This is a long sentence" \| truncatewords: 2 }}`          | `This is…`          |
| `prepend`       | Add a string to the beginning.                      | `{{ "world" \| prepend: "hello " }}`                           | `hello world`       |
| `append`        | Add a string to the end.                            | `{{ "hello" \| append: " world" }}`                            | `hello world`       |
| `url_encode`    | Percent-encode a string for use in a URL.           | `{{ "a b" \| url_encode }}`                                    | `a%20b`             |
| `escape`        | HTML-escape a string.                               | `{{ "<a>" \| escape }}`                                        | `&lt;a&gt;`         |

***

## Iteration

### `for` loops

Iterate over an array of items. For the full attribute list, see the [Liquid `for` loop documentation](https://shopify.github.io/liquid/tags/iteration/).

```liquid Liquid theme={null}
{% for product in message.custom_data.products %}
- {{ product.name }}
{% else %}
Sorry, we're sold out of all products.
{% endfor %}
```

```json Custom data theme={null}
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "custom_data": {
    "products": [
      { "name": "Sweater" },
      { "name": "Hat" },
      { "name": "Shirt" }
    ]
  }
}
```

```text Result theme={null}
- Sweater
- Hat
- Shirt
```

The `{% else %}` branch renders when the array is empty or undefined:

```text Result (products is empty) theme={null}
Sorry, we're sold out of all products.
```

<Warning>
  `for` loops can degrade delivery performance in rare cases. Be mindful of loop usage on high-volume sends. Push channel fields `contents`, `headings`, `subtitle`, `apns_alert`, and `url` do **not** support `for` loops.
</Warning>

#### `forloop` variables

Inside a `for` block, Liquid exposes a `forloop` object with metadata about the current iteration.

| Variable         | Description                       |
| ---------------- | --------------------------------- |
| `forloop.index`  | Current iteration, starting at 1. |
| `forloop.index0` | Current iteration, starting at 0. |
| `forloop.first`  | `true` on the first iteration.    |
| `forloop.last`   | `true` on the last iteration.     |
| `forloop.length` | Total number of iterations.       |

Useful for separators:

```liquid Liquid theme={null}
{% for item in cart %}{{ item.name }}{% unless forloop.last %}, {% endunless %}{% endfor %}
```

#### `limit` and `offset`

Restrict how many items a loop iterates over and where it starts.

```liquid Liquid theme={null}
{% assign great_numbers = "1,2,3,4,5,6" | split: "," %}

First three:
{% for number in great_numbers limit: 3 %}{{ number }} {% endfor %}

Skip three, then take three:
{% for number in great_numbers limit: 3 offset: 3 %}{{ number }} {% endfor %}
```

```text Result theme={null}
First three:
1 2 3

Skip three, then take three:
4 5 6
```

***

## FAQ

### When should I use `default` vs. `if`/`else`?

Use the `default` filter when only the variable value needs a fallback and the surrounding text stays the same.

```liquid Liquid theme={null}
Hello {{ name | default: "there" }}!
```

```text Result (name = "Jon") theme={null}
Hello Jon!
```

```text Result (name is empty) theme={null}
Hello there!
```

Use `if`/`else` when the surrounding text, punctuation, or sentence structure also needs to change.

```liquid Liquid theme={null}
{% if name %}{{ name }}, shop your favorites!{% else %}Shop your favorites!{% endif %}
```

<Warning>
  Do not use `default` when the sentence structure changes. For example, `{{ name | default: "Shop your favorites" }}, shop your favorites` would render as "Shop your favorites, shop your favorites" when the name is empty. If the fallback changes more than the variable, use `if`/`else`.
</Warning>

### How do I control whitespace and newlines?

Use hyphens inside the tag delimiters to trim surrounding whitespace: `{{- ... -}}` and `{%- ... -%}`. See [Whitespace control](https://shopify.github.io/liquid/basics/whitespace/) for the full rules.

### How do I include literal `{{` or `{%` in the output?

Wrap the section in `{% raw %}` and `{% endraw %}` so Liquid does not parse it. This is the right tool for user-generated content that may contain Liquid-looking characters. See [Liquid `raw` syntax](https://shopify.dev/docs/api/liquid/tags/raw).

```json Push payload theme={null}
{
  "contents": {
    "en": "{% raw %}Your user content with literal {{ braces }}{% endraw %}"
  }
}
```

### What happens if a Liquid expression references a missing value?

The expression renders as an empty string and the message still sends. Wrap optional values in `| default: "fallback"` so the surrounding sentence still reads correctly.

***

## Related pages

<Columns>
  <Card title="Personalize with properties" icon="user" href="./personalization-properties-and-tags">
    Use Tags, External ID, and other stored properties to personalize messages with Liquid.
  </Card>

  <Card title="Personalize with Custom Events" icon="bolt" href="./personalization-custom-event">
    Reference Custom Event properties in Journey messages with `journey.first_event` and related objects.
  </Card>

  <Card title="Personalize with API custom_data" icon="code" href="./personalization-api-custom-data">
    Send dynamic, message-specific data through the Create Message API and render it with Liquid.
  </Card>

  <Card title="Data Feeds" icon="database" href="./data-feeds">
    Pull real-time data from your APIs into messages at send time.
  </Card>

  <Card title="Dynamic Content with CSV" icon="file-csv" href="./dynamic-content">
    Personalize push, email, and SMS at scale using CSV uploads and the `dynamic_content` Liquid object.
  </Card>
</Columns>


# VoIP push notifications
Source: https://documentation.onesignal.com/docs/en/voip-notifications

Send VoIP push notifications on iOS using OneSignal with PushKit token registration and a VoIP certificate, plus Android alternatives for call-style behavior.

VoIP push notifications let your app receive incoming call alerts even when the app is in the background or terminated. Apple handles VoIP pushes differently from standard push notifications — they use a separate certificate type, a separate token (via PushKit), and different delivery rules.

OneSignal supports **sending** VoIP pushes, but the OneSignal SDK does **not** handle VoIP token registration. You are responsible for:

* Registering VoIP tokens in your app using Apple PushKit
* Creating a dedicated OneSignal app with a VoIP Services Certificate
* Registering tokens and sending pushes through the OneSignal REST API

### Platform differences

| Platform    | VoIP push supported? | How it works                                          |
| ----------- | -------------------- | ----------------------------------------------------- |
| **iOS**     | Yes                  | Uses Apple PushKit and a VoIP APNs certificate        |
| **Android** | No                   | Uses data-only pushes to simulate call-style behavior |

If you are building a cross-platform calling app, you will use different approaches per platform.

***

## iOS: send VoIP push notifications

On iOS, VoIP notifications use Apple PushKit and follow special delivery rules that differ from standard push notifications. Because Apple treats VoIP pushes differently, OneSignal requires a separate app configuration for VoIP.

<Warning>
  **Before you start** — these are the most common VoIP setup mistakes:

  1. **Not creating a separate OneSignal app for VoIP.** Apple requires a different certificate type for VoIP, so OneSignal needs a dedicated app to send VoIP pushes. Your existing push app cannot be used for both.
  2. **Uploading the wrong certificate.** You need a **VoIP Services Certificate (.p12)**, not your standard APNs push certificate. Using the wrong one causes silent delivery failures.
  3. **Forgetting `test_type` in sandbox.** When testing with a development build, you must include `"test_type": 1` when registering the token. Without it, the API call succeeds but pushes never arrive.
</Warning>

<Steps>
  <Step title="Register a VoIP token using PushKit">
    Use Apple's PushKit framework to register for VoIP notifications and receive a VoIP token.

    * Implement PushKit in your app
    * Store and refresh the VoIP token as Apple rotates it
    * Follow Apple's VoIP policies closely

    <Accordion title="Example: PushKit delegate implementation">
      ```swift theme={null}
      import PushKit

      class AppDelegate: NSObject, PKPushRegistryDelegate {
          func registerForVoIPPushes() {
              let registry = PKPushRegistry(queue: .main)
              registry.delegate = self
              registry.desiredPushTypes = [.voIP]
          }

          func pushRegistry(_ registry: PKPushRegistry, didUpdatePushCredentials credentials: PKPushCredentials, for type: PKPushType) {
              let token = credentials.token.map { String(format: "%02x", $0) }.joined()
              // Pass this token to OneSignal — see Step 4
          }
      }
      ```

      <Note>This is standard Apple PushKit code. OneSignal does not provide a PushKit SDK — you register the token yourself and pass it to OneSignal in Step 4.</Note>
    </Accordion>

    Apple resources:

    * [PushKit documentation](https://developer.apple.com/documentation/pushkit)
    * [Responding to VoIP pushes](https://developer.apple.com/documentation/pushkit/responding_to_voip_notifications_from_pushkit)
    * [Apple's VoIP best practices](https://developer.apple.com/library/content/documentation/Performance/Conceptual/EnergyGuide-iOS/OptimizeVoIP.html)
  </Step>

  <Step title="Create a separate OneSignal app for VoIP">
    Apple VoIP pushes require a different certificate type than standard push notifications. A single OneSignal app can only use one certificate type, so you must create **two separate OneSignal apps**:

    * **Main Push App**: Uses your APNs certificate for standard push notifications
    * **VoIP Push App**: Uses a VoIP Services Certificate for VoIP-only notifications

    Both apps must use the same iOS bundle ID and be associated with the same native iOS app. You do **not** need to initialize the OneSignal SDK twice — the VoIP app is only used server-side to send VoIP pushes via the API.

    <Note>The bundle ID (e.g., `com.yourcompany.appname`) is found in Xcode under your target's **General** tab.</Note>
  </Step>

  <Step title="Upload a VoIP Services Certificate">
    In your VoIP OneSignal app, upload a **VoIP Services Certificate (.p12)**. This is a different certificate type than the standard APNs push certificate you use for regular notifications.

    To create one:

    1. Go to the [Apple Developer Portal](https://developer.apple.com/account/resources/certificates/add)
    2. Select **VoIP Services Certificate**
    3. Follow the prompts to generate and download the certificate
    4. Open it in Keychain Access and export it as a `.p12` file
    5. Upload the `.p12` file to your VoIP OneSignal app's iOS settings

    <Warning>
      Do **not** upload your standard APNs push certificate to the VoIP app. If you use the wrong certificate type, the API will accept your push request but Apple will reject it and the notification will never arrive.
    </Warning>

    <Frame>
      <img alt="VoIP Services Certificate shown in macOS Keychain Access" />
    </Frame>

    <Frame>
      <img alt="VoIP Services Certificate uploaded in the OneSignal dashboard" />
    </Frame>
  </Step>

  <Step title="Register the VoIP token with OneSignal">
    Use the [Create User](/reference/create-user) API to register the VoIP token with your VoIP OneSignal app.

    <Warning>
      **Sandbox/development builds require `"test_type": 1`.** If you omit this field, the API call succeeds and returns no error, but Apple treats the token as production and silently rejects every push sent to it.
    </Warning>

    ```curl theme={null}
    curl --request POST \
         --url https://api.onesignal.com/apps/YOUR_VOIP_APP_ID/users \
         --header 'accept: application/json' \
         --header 'content-type: application/json' \
         --data '
    {
      "subscriptions": [
        {
          "type": "iOSPush",
          "token": "YOUR_VOIP_TOKEN",
          "test_type": 1
        }
      ]
    }
    '
    ```

    <Note>A valid VoIP token is a 64-character lowercase hex string (e.g., `a1b2c3d4e5f6...`). PushKit does not work on the iOS Simulator — you must use a real device to obtain a valid token.</Note>

    To update the token later, use the [Update Subscription](/reference/update-subscription) API.
  </Step>

  <Step title="Send VoIP notifications">
    Use the [Create Notification](/reference/create-message) API with the following parameters:

    * `"apns_push_type_override": "voip"` — tells Apple this is a VoIP push
    * `app_id` — your VoIP app ID
    * `include_subscription_ids` — the VoIP subscription ID you registered
    * Either `contents` or `content_available` is required

    ```curl theme={null}
    curl --include \
         --request POST \
         --header "Content-Type: application/json; charset=utf-8" \
         --header "Authorization: key YOUR_REST_API_KEY" \
         --data-binary '{
      "app_id": "YOUR_VOIP_APP_ID",
      "content_available": true,
      "data": {
        "your_custom_data": "your_custom_value"
      },
      "apns_push_type_override": "voip",
      "include_subscription_ids": ["YOUR_VOIP_SUBSCRIPTION_ID"]
    }' \
    https://api.onesignal.com/notifications
    ```
  </Step>

  <Step title="Verify your VoIP setup">
    Your iOS VoIP integration is working correctly if:

    1. The VoIP token appears as an iOS push subscription in your **VoIP app**
    2. A VoIP push triggers [`pushRegistry(_:didReceiveIncomingPushWith:for:completion:)`](https://developer.apple.com/documentation/pushkit/responding_to_voip_notifications_from_pushkit) in your app
    3. The app wakes even when it is terminated or backgrounded
  </Step>
</Steps>

***

## Android: simulate VoIP-style behavior

Android does not support VoIP push notifications. There is no equivalent to Apple PushKit.

Instead, Android calling apps simulate VoIP behavior using:

* Data-only push notifications
* Foreground services
* Custom call-style UI

You can use OneSignal's normal Android push support combined with native Android APIs to achieve this.

**Recommended approach:**

* Send data-only notifications
* Handle them in your app to:
  * Start a foreground service
  * Launch a call UI activity
  * Display a custom incoming call notification

If you want to intercept and fully control notification rendering, use Android's [Notification Service Extension](./service-extensions#notification-service-extension).

**Helpful resources:**

* [Android calling app guide](https://developer.android.com/guide/topics/connectivity/telecom/selfManaged)
* [Incoming call UI example](https://medium.com/@dcostalloyd90/show-incoming-voip-call-notification-and-open-activity-for-android-os-10-5aada2d4c1e4)

<Info>Android setup is **not specific to OneSignal**. OneSignal only delivers the push payload; your app handles call behavior.</Info>

***

## FAQ

### Do confirmed deliveries work with VoIP?

No. [Confirmed Deliveries](./confirmed-delivery) are **not tracked** for VoIP pushes. Confirmed Deliveries rely on the Notification Service Extension, which does not trigger for VoIP notifications.

Instead, track receipt via the native iOS PushKit event:

```swift theme={null}
pushRegistry(_:didReceiveIncomingPushWith:for:completion:)
```

This event is part of your main app target and does not require a separate extension. See [Apple's VoIP documentation](https://developer.apple.com/documentation/pushkit/responding_to_voip_notifications_from_pushkit#3377587) for details.

### Can I send VoIP notifications from the OneSignal dashboard?

No. VoIP notifications must be sent via the [Create Notification](/reference/create-message) API with `"apns_push_type_override": "voip"`. The dashboard does not support this parameter.

### Why is my VoIP push silently failing?

VoIP pushes can fail without any error from the OneSignal API. Work through this checklist:

1. **Are you using a sandbox/development build?** You must include `"test_type": 1` when registering the token via the Create User API. Without it, the token registers as production, Apple rejects the push, and it silently fails.
2. **Did you upload the correct certificate?** The VoIP OneSignal app must use a **VoIP Services Certificate (.p12)**, not a standard APNs push certificate. Both look similar in Keychain Access — verify the certificate name starts with "VoIP Services".
3. **Are you sending to the right OneSignal app?** The `app_id` in your send request must be your **VoIP app**, not your main push app. The `REST API Key` must also come from the VoIP app.
4. **Is the VoIP token valid?** Tokens expire when the app is reinstalled or the device is restored. Check that the token is a 64-character lowercase hex string and was recently registered.
5. **Does your app call `reportNewIncomingVoIPPushPayload`?** Starting in iOS 13, Apple **terminates** apps that receive a VoIP push but do not report a call to CallKit. This is an Apple requirement, not a OneSignal limitation.

***

## Related pages

<Columns>
  <Card title="Create message API" icon="code" href="/reference/create-message">
    Send push notifications programmatically using the REST API.
  </Card>

  <Card title="Confirmed deliveries" icon="circle-check" href="./confirmed-delivery">
    Track push notification delivery confirmation on supported platforms.
  </Card>

  <Card title="Service extensions" icon="puzzle-piece" href="./service-extensions">
    Customize notification handling with Notification Service Extensions.
  </Card>

  <Card title="Create User API" icon="user-plus" href="/reference/create-user">
    Register users and subscriptions with the OneSignal API.
  </Card>
</Columns>


# Web push setup
Source: https://documentation.onesignal.com/docs/en/web-push-setup

Set up web push notifications with OneSignal to re-engage Users across Chrome, Firefox, Safari, and Edge.

Web push notifications re-engage Users with timely content — even when they're not actively browsing your website. They support rich content including text, images, action buttons, and sounds.

<Frame>
  <img alt="Web push notification examples across different browsers and devices" />
</Frame>

For web push to work:

* **HTTPS website**: Web push only works on secure sites with a valid SSL certificate
* **Service worker**: You must be able to add the [OneSignal service worker](./onesignal-service-worker) to your website
* **Single domain origin**: Must follow the [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)
* **User permission**: Users must explicitly grant permission to receive notifications
* **Supported browsers**: Works across most modern browsers (Chrome, Firefox, Safari, Edge)

<Warning>
  - **Incognito mode**: Users cannot subscribe while in incognito or private browsing mode.
  - **iOS**: Requires additional setup — see [Web push for iOS](./web-push-for-ios).
  - **Browser limits**: Some browsers may have notification limits or require user interaction — see [Web push FAQ](./web-push-setup-faq).
</Warning>

***

## Web push developer guides

Before sending web push notifications, complete the following setup steps.

<Note>
  Not a developer? See [Manage team members](./manage-team-members) to invite a teammate with developer access to your OneSignal project.
</Note>

<Columns>
  <Card title="Web SDK setup" icon="browsers" href="./web-sdk-setup">
    Install and configure the OneSignal Web SDK, including localhost testing and permission prompts.
  </Card>

  <Card title="iOS web push setup" icon="apple" href="./web-push-for-ios">
    Follow Apple-specific steps to enable web push on iPhones and iPads running iOS 16.4+.
  </Card>

  <Card title="Migration from another provider" icon="arrow-right-arrow-left" href="./migrating-to-onesignal">
    Transition from another web push provider and retain your Subscriptions.
  </Card>

  <Card title="WordPress plugin" icon="plug" href="./wordpress">
    Integrate push notifications on WordPress using the official plugin — no coding required.
  </Card>

  <Card title="Shopify-Vendo integration" icon="shopify" href="./shopify">
    Integrate Shopify with OneSignal through the Vendo integration for web push, custom events, and customer identification.
  </Card>
</Columns>

***

## Configuration options

Set up your website for web push in the OneSignal dashboard under **Settings > Push & In-App > Web**.

<Frame>
  <img alt="OneSignal dashboard showing web push platform activation in settings" />
</Frame>

Select the integration type that matches your site:

<Frame>
  <img alt="OneSignal dashboard showing integration type options: Typical Site, WordPress, and Custom Code" />
</Frame>

<Columns>
  <Card title="Typical site" icon="globe" href="./web-sdk-setup">
    **Recommended** — Configure prompts, welcome notification, and service worker setup directly in the dashboard.
  </Card>

  <Card title="WordPress" icon="plug" href="./wordpress">
    Use the official OneSignal WordPress plugin and configure prompts and welcome notification directly in the dashboard.
  </Card>

  <Card title="Custom code" icon="code" href="./web-push-custom-code-setup">
    Full control for developers who want to customize everything via code.
  </Card>
</Columns>

Site details:

* **Site Name**: Used in default notification titles
* **Site URL**: Must exactly match your domain origin (no paths or `www` mismatch)
* **Auto Resubscribe**: Recommended — Automatically re-subscribes returning Users who cleared browser data
* **Default Icon URL**: `256x256px` image shown in notifications (if unset, a default bell icon is used)

### Auto resubscribe

If Users clear their browser data, they stop receiving push notifications. Enable this option to automatically re-subscribe Users when they return to your site. See [Subscriptions](./subscriptions) for more details.

<Frame>
  <img alt="OneSignal dashboard web push configuration settings showing site details and auto resubscribe option" />
</Frame>

***

### Web permission prompts

Customize when and how the notification permission prompt appears to maximize opt-in rates.

<Tip>
  Use clear messaging that explains the benefit, prompt Users at the right time (e.g., after engagement), and use a pre-prompt before triggering the native browser dialog.
</Tip>

<Columns>
  <Card title="Web permission prompts" icon="bell" href="./permission-requests">
    Compare different prompt types (slidedown, category-based, native, subscription bell, and more).
  </Card>

  <Card title="Web SDK reference" icon="code" href="./web-sdk-reference">
    Programmatically control when and how prompts are shown using the SDK.
  </Card>
</Columns>

***

### Welcome notification

You can enable an optional confirmation push that's sent immediately after a User subscribes. Typical and WordPress integrations can set this in the dashboard.

<Frame>
  <img alt="OneSignal dashboard showing welcome notification configuration with title, message, and URL fields" />
</Frame>

Custom Code integration uses the `welcomeNotification` object in the `OneSignal.init` function. See [Web SDK reference](./web-sdk-reference) for details.

**Why send welcome notifications?**

* Let Users know they've subscribed successfully
* Show what future notifications will look like
* Provide onboarding content or next steps

***

## Users and Subscriptions

When a User subscribes to push, OneSignal automatically creates a unique Subscription tied to their browser and device.

Web push Subscriptions are created when Users:

* Grant permission for push notifications on your website using a specific browser and device
* Return to your site after clearing browser data (if Auto Resubscribe is enabled)
* Subscribe from a new browser or device

<Note>
  Each browser/device combination creates a separate Subscription. Incognito/private browsing mode cannot create Subscriptions. Web push Subscriptions remain anonymous until you assign them an [External ID](./users#external-id).
</Note>

<Frame>
  <img alt="OneSignal dashboard Users page showing a list of Users with Subscription details" />
</Frame>

<Columns>
  <Card title="Users" icon="users" href="./users">
    Manage Users, assign External IDs, and track their activity.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    How Subscriptions work across browsers and devices.
  </Card>

  <Card title="Segments" icon="chart-pie" href="./segmentation">
    Group Users into Segments to target based on behavior, device, and more.
  </Card>
</Columns>

### iOS support

Apple added web push support for iPhones and iPads running iOS 16.4+ with stricter requirements:

* Users must add your site to their Home Screen
* Permission prompts are shown only after that step
* Notifications behave like native app alerts once enabled

<Columns>
  <Card title="Web push for iOS" icon="apple" href="./web-push-for-ios">
    Step-by-step instructions to enable iOS support, including service worker and manifest setup.
  </Card>
</Columns>

***

## Design web push notifications

Web push notifications support titles, messages, icons, images, and action buttons. The diagram below shows which elements you can customize.

<Frame>
  <img alt="Annotated diagram showing the anatomy of a web push notification with customizable and browser-controlled elements" />
</Frame>

**Customizable elements:**

1. [Title](./push#title): Attention-grabbing headline (recommended: under 50 characters)
2. [Message](./push#message): Main notification content (recommended: under 120 characters)
3. [Icon](./notification-icons): Your brand icon or notification-specific image (recommended: `256x256px` PNG or JPG)
4. [Large image](./push#image): Eye-catching visual content
5. [Action buttons](./action-buttons): Call-to-action buttons

**Browser-controlled elements (not customizable):**
6\. Browser: The browser/app displaying the push
7\. Domain: Your site origin, automatically set by the browser
8\. Timestamp and dismiss: Browser-added controls
9\. More options: Browser-specific additional controls

<Columns>
  <Card title="Push overview" icon="bell" href="./push">
    Full overview of push notification creation, options, and delivery behavior.
  </Card>

  <Card title="Templates" icon="clone" href="./templates">
    Save time with reusable templates for consistent messaging.
  </Card>
</Columns>

### Personalization and localization

Customize push messages to match each User's preferences and language.

<Columns>
  <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
    Insert dynamic variables like name or preferences to tailor messages.
  </Card>

  <Card title="Multi-language messaging" icon="language" href="./multi-language-messaging">
    Deliver messages in each User's preferred language.
  </Card>
</Columns>

***

## Configure web push behavior

Control how your push messages behave after sending — when they appear, how long they're stored, and how Users interact.

### Delivery, display, and dismiss settings

<Columns>
  <Card title="Throttling" icon="gauge-high" href="./throttling">
    Control notification delivery speed.
  </Card>

  <Card title="Frequency capping" icon="hand" href="./frequency-capping">
    Set limits to prevent over-sending notifications to the same User.
  </Card>

  <Card title="Time to live (TTL)" icon="clock" href="./push#time-to-live-ttl">
    Define how long push services retain messages when the device is offline.
  </Card>

  <Card title="Web push topic" icon="layer-group" href="./push#web-push-topic-web-push">
    Use topics to group, replace, or suppress duplicate notifications.
  </Card>
</Columns>

### Click behavior

Control what happens when a User clicks a notification.

**By default:** Clicking opens your homepage.

**Customize it:**

* Direct Users to a specific URL
* Use UTM tracking
* Suppress default behavior with `?_osp=do_not_open`

<Columns>
  <Card title="URLs, links, and deep linking" icon="link" href="./links">
    Route Users to relevant content or pages using deep links and tracking.
  </Card>

  <Card title="Action buttons" icon="hand-pointer" href="./action-buttons">
    Let Users take immediate actions from your notification.
  </Card>

  <Card title="Web SDK push event listeners" icon="code" href="./web-sdk-reference#push-notifications">
    Listen for click events and trigger in-app behavior with custom code.
  </Card>
</Columns>

***

## Test your setup

Before launching, thoroughly test your web push implementation across devices and browsers.

### Pre-launch checklist

* SDK is correctly loaded with no console errors
* Permission prompt appears and functions correctly
* Test notification is sent and received
* Icons and images render correctly
* Service worker is registered and up to date
* HTTPS certificate is valid

### Analytics and troubleshooting

Measure notification performance and resolve common delivery issues.

<Columns>
  <Card title="Push message reports" icon="chart-line" href="./push-notification-message-reports">
    View delivery, open rate, and click-through metrics for each message.
  </Card>

  <Card title="Analytics overview" icon="chart-bar" href="./analytics-overview">
    Explore engagement and User behavior metrics across channels.
  </Card>

  <Card title="Notifications not shown or delayed" icon="circle-exclamation" href="./notifications-not-shown-web-push">
    Troubleshooting checklist if messages aren't appearing.
  </Card>

  <Card title="Notification images not showing" icon="image" href="./notification-images-not-showing">
    Fix image rendering issues across different browsers.
  </Card>
</Columns>

***

## Next steps

<Columns>
  <Card title="A/B testing" icon="flask" href="./ab-testing">
    Optimize messages with experiments to find what drives engagement.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build automated, multi-step messaging flows triggered by User behavior.
  </Card>

  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Add custom properties to users for personalization and segmentation.
  </Card>
</Columns>

***

## FAQ

### Can Users subscribe to web push on iOS?

Yes, starting with iOS 16.4+. Users must first add your website to their Home Screen, then grant notification permission. See [Web push for iOS](./web-push-for-ios) for the full setup steps.

### Why did a User stop receiving web push notifications?

The most common cause is that the User cleared their browser data, which removes the push Subscription. Enable **Auto Resubscribe** in your web push settings to automatically re-subscribe returning Users. See [Subscriptions](./subscriptions) for details.

### Do web push notifications work in incognito or private browsing mode?

No. Users cannot subscribe to web push while in incognito or private browsing mode. Subscriptions created in a normal session are not accessible in private mode.

### What browsers support web push notifications?

Chrome, Firefox, Safari (macOS and iOS 16.4+), and Edge all support web push. Each browser may have different prompt behavior and notification display. See [Web push FAQ](./web-push-setup-faq) for browser-specific details.

### Can I use subdomains with web push?

Each subdomain (e.g., `app.example.com` vs `shop.example.com`) is a separate origin. Browsers enforce the [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) for web push, so each subdomain requires its own OneSignal App. The service worker must also be hosted on the same origin as the subscribing page — CDNs and other subdomains are not allowed. See [Multiple sites & subdomains](./web-push-setup-faq#multiple-sites--subdomains) for setup options.

### How do I register more than one domain for web push?

You need a separate OneSignal app for each domain or subdomain. A single OneSignal app can only serve one origin. To manage multiple domains, either redirect Users to a single origin for subscription or create individual OneSignal apps per origin. See [Multiple sites & subdomains](./web-push-setup-faq#multiple-sites--subdomains) for detailed strategies.

### Why is my web push prompt not showing?

Common causes include: the site is not served over HTTPS, the service worker is not registered correctly, the User already granted or denied permission, or the User is in incognito mode. Check the browser console for errors and see [Notifications not shown](./notifications-not-shown-web-push) for a full checklist.


# Web push FAQ
Source: https://documentation.onesignal.com/docs/en/web-push-setup-faq

Complete guide to OneSignal Web Push Notifications setup, requirements, browser compatibility, domain changes, and troubleshooting common issues for developers and website owners.

## Web push requirements

Your website must meet all of the following for Web Push to work:

**Browser APIs required**

* [Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)
* [Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)
* [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)

**Security & connection**

* ✅ HTTPS only (with valid SSL certificate)
* ✅ OneSignal's [service worker](./onesignal-service-worker) installed
* ✅ Browser must reach:
  * Browser push servers (e.g., FCM, Mozilla)
  * `api.onesignal.com`

**User state**

* ✅ Notification permission granted by user
* ❌ Not in Incognito/Private/Guest mode
* ❌ Site data not cleared (deletes subscriptions)

<Warning>Clearing browser data (cookies, site storage) automatically unsubscribes users from push notifications.</Warning>

### iOS/iPadOS requirements

To receive push on iOS or iPadOS:

* iOS 16.4+ or iPadOS 16.4+
* Site must be added to home screen and opened from there
* Valid `manifest.json` file with required fields
* Users must accept notification permissions after opening as web app

<Card title="iOS web push setup" href="./web-push-for-ios">
  Follow Apple-specific steps to enable web push on iPhones and iPads running iOS 16.4+.
</Card>

### Browser compatibility

Users may see [web permission prompts](/docs/en/permission-requests) but cannot subscribe to push notifications in incognito, private, or guest browser modes.

<Accordion title="Browser compatibility by operating system">
  | Browser                                                                          | Windows | macOS | Android | iOS |
  | -------------------------------------------------------------------------------- | ------- | ----- | ------- | --- |
  | [Chrome](https://en.wikipedia.org/wiki/Google_Chrome)                            | ✅       | ✅     | ✅       | ✅ ¹ |
  | [Firefox](https://en.wikipedia.org/wiki/Firefox)                                 | ✅       | ✅     | ✅       | ✅ ¹ |
  | [Safari 10+](https://en.wikipedia.org/wiki/Safari_\(web_browser\))               | ❌       | ✅     | ❌       | ✅ ¹ |
  | [Microsoft Edge](https://en.wikipedia.org/wiki/Microsoft_Edge)                   | ✅       | ✅     | ✅       | ✅ ¹ |
  | [Opera](https://en.wikipedia.org/wiki/Opera_\(web_browser\)) ²                   | ✅       | ✅     | ✅       | ✅ ¹ |
  | [Samsung Internet](https://en.wikipedia.org/wiki/Samsung_Internet_for_Android) ² | ❌       | ❌     | ✅       | ✅ ¹ |
  | [Yandex](https://en.wikipedia.org/wiki/Yandex_Browser) ²                         | ✅       | ✅     | ✅       | ✅ ¹ |
  | [UC Browser](https://en.wikipedia.org/wiki/UC_Browser) ²                         | ✅       | ❌     | ✅       | ✅ ¹ |
  | [Internet Explorer](https://en.wikipedia.org/wiki/Internet_Explorer)             | ❌       | ❌     | ❌       | ❌   |
  | [DuckDuckGo](https://en.wikipedia.org/wiki/DuckDuckGo)                           | ❌       | ❌     | ❌       | ❌   |

  <Info>
    ¹ iOS requires web app installation (see [iOS web push setup](/docs/en/web-push-for-ios))

    ² Chromium-based browsers appear as "Chrome" in OneSignal analytics
  </Info>
</Accordion>

***

## Domain changes & migration

### Understanding browser origin policy

Browsers tie web push subscriptions to a specific [origin (domain/site URL)](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) for security reasons. **You cannot transfer subscribers between different origins** - this is a browser limitation, not a OneSignal restriction.

**Different origins include:**

* HTTP vs HTTPS (e.g., `http://mysite.com` → `https://mysite.com`)
* www vs non-www (e.g., `www.mysite.com` vs `mysite.com`)
* Different domains/subdomains (e.g., `domain1.com` vs `domain2.com` or `sub1.domain.com` vs `sub2.domain.com`)

### Migration options

When changing your site's origin, choose one of these approaches:

<Tabs>
  <Tab title="New OneSignal App (Recommended)">
    **Best for**: Most domain changes, especially when you want a clean migration

    1. **Create new OneSignal App** for your new domain
    2. **Dual-send strategy**: Continue sending from old app, but set "Launch URL" to your new domain
    3. **Gradual transition**:
       * High-frequency senders (1+ notifications/day): 2 weeks transition
       * Medium-frequency senders (2+ notifications/week): 2 months transition
    4. **Migration notifications**: Send 1-2 messages like "We've moved! Visit our new site to stay updated" at the beginning and end of transition

    <Warning> Sending identical messages from both apps will create duplicate notifications for users subscribed to both.</Warning>
  </Tab>

  <Tab title="Update App & Delete Old Subscribers">
    **Best for**: When you need to keep the same OneSignal App ID

    1. Use [Update an app](/reference/update-an-app) API with:
       * `name`: Your app/site name
       * `chrome_web_origin`: New site URL
       * `chrome_web_default_notification_icon`: Icon image URL

    2. **Delete old subscribers** to prevent duplicates:
       * Create segment: "Device Type is Web Push"
       * [Delete all users in segment](./delete-users)
  </Tab>
</Tabs>

### HTTP to HTTPS upgrade

Upgrading from HTTP to HTTPS creates a new origin. Follow the domain migration steps above since browsers treat HTTPS sites as completely separate from their HTTP versions.

***

## Multiple sites & subdomains

### Single app limitations

Due to browser same-origin policy, you **can not** use one OneSignal App for multiple origins like:

* `https://mysite.com` and `https://www.mysite.com`
* `https://main.com` and `https://shop.main.com`

### Solutions for multiple origins

<Tabs>
  <Tab title="Single Origin Strategy">
    * Subscribe users only on your main domain
    * Redirect users from other origins to main domain for subscription
    * Redirect back to original page after subscription
  </Tab>

  <Tab title="Separate Apps">
    * Create individual OneSignal Apps for each origin
    * Accept that users may receive duplicate notifications if subscribed to multiple sites
  </Tab>
</Tabs>

***

### Language support scenarios

<Tabs>
  <Tab title="Same Origin (Recommended)">
    * URLs like `https://mysite.com/en/` or `https://mysite.com/es/`
    * Use single OneSignal App
    * Follow [multi-language prompts guide](./permission-requests#faq)
    * Implement [Language & Localization](./multi-language-messaging)
  </Tab>

  <Tab title="Different Origins">
    * URLs like `https://en.mysite.com` or `https://es.mysite.com`
    * Requires separate OneSignal Apps for each subdomain
  </Tab>
</Tabs>

***

## Advanced configuration

### Multiple OneSignal apps on same site

* **Not recommended** - causes subscription conflicts.
* **What happens**: OneSignal auto-resubscribes users to the most recently visited App ID, causing subscribers to bounce between apps and creating many unsubscribed devices.
* **Better approach**: Use [Tags](./add-user-data-tags) to segment users within a single app.

### Subfolder sites

Web push operates at the origin level. For sites in subfolders (e.g., `https://example.com/blog`), use the main origin (`https://example.com`) for setup.

### Self-hosting SDK files

**Strongly discouraged**. Browser push specifications change frequently, and OneSignal updates files immediately to maintain compatibility. Use OneSignal's CDN URLs from your Web Push Settings instead.

### Custom init code

Custom `init` code only works with [Custom Code Setup](./web-push-custom-code-setup).

**Typical Setup or Website Builder users**: Custom init code will be ignored by the OneSignal SDK. If you need to delay initialization, use the [privacy methods](./web-sdk-reference#privacy).

***

## Development & testing

### Local environment testing

See [Web SDK setup > Local testing](./web-sdk-setup#local-testing) for complete local testing setup.

### Service worker integration

OneSignal can work alongside existing service workers and PWAs. See [Integrating Multiple Service Workers](./onesignal-service-worker) for implementation details.

***

## Push spam

Push notifications are not designed to be used for advertisments, spamming users, or deceptive campaigns.

If your app is detected as sending spam notifications, browsers may send your users a "Spam warning" notification.

Avoid sending notifications that:

* Are not relevant to the users
* Use words like "Ads" or link to a page that is not related to the app
* Are not from a trusted source (e.g. a brand you are not associated with)

<Warning>
  See [Fighting Unwanted Notifications with Machine Learning in Chrome](https://blog.chromium.org/2025/05/fighting-unwanted-notifications-with.html) for more information.
</Warning>

If your app is being flagged as spam, you can:

* Review your notification content and remove anything that may be considered spam. This includes:
  * The words "Ads" or "Ad" in the title or body
  * Links to pages that are not related to the app
  * Links to pages that are not from a trusted source (e.g. a brand you are not associated with)
* Continue sending and monitor further reports.

***

## Troubleshooting

### Update deployment timing

* **Service Worker files**: 24-hour cache
* **Web SDK**: 3-day cache

Plan accordingly when deploying critical updates.

### macOS Chrome notification issues

For macOS Chrome users, ensure notifications are enabled for **both**:

1. **Google Chrome** app (Apple Menu > Settings > Notifications)
2. **Google Chrome Helper** app

Without both enabled, notifications won't appear in the notification center.

### Next steps after setup

1. **Test thoroughly** across your supported browsers and devices
2. **Implement proper error handling** for permission requests
3. **Set up analytics** to monitor subscription rates
4. **Plan your notification strategy** to avoid user fatigue
5. **Consider A/B testing** your permission request timing and messaging

### Common migration gotchas

* **Browser data clearing** unsubscribes users automatically
* **Duplicate notifications** during dual-app transitions
* **iOS requires web app installation** before push works
* **Private/Incognito modes** never support push notifications
* **Service workers must be accessible** at your site's root or configured subdirectory

***

## Next steps

* [Web SDK setup](./web-sdk-setup)
* [Web SDK reference](./web-sdk-reference)

***


# WordPress
Source: https://documentation.onesignal.com/docs/en/wordpress

Complete setup and migration guide for OneSignal WordPress Web Push Plugin v3+. Configure push notifications, prompts, and segmentation through the OneSignal dashboard with streamlined setup process.

## Overview

This guide covers how to set up and configure OneSignal WordPress Web Push Plugin v3+.

<Info>
  For the older version 2.x.x WordPress documentation, see [WordPress Legacy plugin](./wordpress-legacy).
</Info>

### What's New in Version 3+

This release marks a significant upgrade by streamlining the setup and configuration process. With Version 3+, you can handle all your prompt settings in one place—the OneSignal Dashboard.

* 🚀 **SDK Upgrade**: Updates OneSignal Web SDK from version 15 to 16
* 💬 **Dashboard Prompts**: Configure all [permission prompts](./permission-requests) directly in the OneSignal dashboard—no custom code required
* ⏩ **One-Click Publishing**: Check "Send notification when post is published" to automatically send push notifications
* 🧑‍🤝‍🧑 **Audience Targeting**: Choose which [segments](./segmentation) receive notifications for each post
* 📲 **Mobile App Integration**: Send to mobile app subscribers with optional [deep linking](./deep-linking)

***

## Setup

Before you begin, ensure you have:

* [OneSignal account](https://dashboard.onesignal.com/signup) (free to create)
* WordPress admin access to install and configure plugins
* HTTPS-enabled website (required for web push notifications)

### 1. Configure WordPress in OneSignal Dashboard

Navigate to **Settings > Push & In-App > Web > WordPress Plugin or Website Builder**

<Frame>
  <img alt="OneSignal dashboard web channel setup with WordPress selected" />
</Frame>

#### Site setup

* **Site Name**: The name of your site and default notification title.
* **Site URL**: Must match your WordPress site's exact URL (follow [Same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy))
* **Auto Resubscribe**: Enable this to automatically resubscribe users who clear their browser data when they return to your site (no new permission prompt required)
* **Default Icon URL**: Square `256x256px` PNG or JPG file for notifications and prompts – **macOS Safari** will not show a notification prompt without an icon.

<Frame>
  <img alt="OneSignal web channel Site URL and default icon fields" />
</Frame>

<Info>
  Testing locally? See [Local Testing Guide](./web-sdk-setup#local-testing) for localhost development
</Info>

#### Permission prompts

Set up your [permission prompts](./permission-requests) for Push, Email, and/or SMS. The Push Slide Prompt is enabled by default, but you can customize or add additional prompts.

<Info>
  **Pro Tip**: Start with simple prompts and gradually add complexity. You can
  modify all prompt settings anytime through the OneSignal dashboard. Explore
  all available options in [Web permission prompts](./permission-requests).
</Info>

<Tabs>
  <Tab title="Basic Prompt Setup">
    <Steps>
      <Step title="Click on Push Slide Prompt to customize">
        <Frame>
          <img alt="Dashboard permission prompt list with Push Slide Prompt selected" />
        </Frame>
      </Step>

      <Step title="Configure timing and text:">
        * Set **Auto Prompt** to `1` pageview and `1` second for initial testing
          * Customize prompt text and appearance
          * Adjust timing based on user behavior after launch

        <Frame>
          <img alt="Slidedown prompt editor showing auto prompt delay and text fields" />
        </Frame>
      </Step>

      <Step title="Click Done when you've finished configuring the prompt." />
    </Steps>
  </Tab>

  <Tab title="Advanced: Category-Based Segmentation">
    For targeted messaging based on user interests, set up categories:

    <Steps>
      <Step title="Select Categories in your prompt settings" />

      <Step title="Configure each category with:">
        * **Label**: What users see in the prompt
        * **Tag Key**: Internal [tag key](./add-user-data-tags) for segmentation
      </Step>

      <Step title="Click Done when you've finished configuring the prompt." />
    </Steps>

    <Frame>
      <img alt="Category prompt configuration with News and Deals labels and tag keys" />
    </Frame>

    **Tag Logic**: Checked categories set tag value to `1`, unchecked to `0`. These tags enable targeted messaging to specific user interests.
  </Tab>
</Tabs>

#### Welcome notification

Set up an immediate notification sent after users first subscribe. This:

* Thanks users for subscribing
* Demonstrates how notifications appear
* Increases engagement and reduces unsubscribes

Configure your welcome message text and timing, then scroll down and click **Save**.

<Tip>
  Skip the **Advanced Push Settings** section in the OneSignal Dashboard for now — these are for custom [Web SDK setup](./web-sdk-setup). Click **Save** to continue.
</Tip>

### 2. Configure WordPress plugin

After saving your dashboard configuration, you'll see your **App ID** and **API Key** (the same REST API key documented in [Keys & IDs](./keys-and-ids)). Copy these values to your WordPress plugin:

<Frame>
  <img alt="OneSignal keys page showing App ID and REST API Key for WordPress" />
</Frame>

<Info>
  **Don't see an API Key?** Follow our [Keys & IDs guide](./keys-and-ids) to
  create one.
</Info>

<Steps>
  <Step title="In your WordPress admin, navigate to the OneSignal plugin settings" />

  <Step title="Paste the App ID and REST API Key exactly as shown in your dashboard" />
</Steps>

<Frame>
  <img alt="WordPress OneSignal plugin settings with App ID and REST API Key fields" />
</Frame>

#### Advanced settings

Configure additional plugin options based on your needs:

<Frame>
  <img alt="WordPress OneSignal plugin advanced settings and URL parameter tracking" />
</Frame>

**URL parameter tracking**

Add analytics parameters to notification URLs for tracking. **Important**: Escape special characters—input is added as-is to URLs.

**Example for Google Analytics:**

```
utm_medium=push&utm_source=onesignal&utm_campaign=wordpress-plugin
```

**Example with special characters:**

```
utm_medium=ppc&utm_source=adwords&utm_campaign=snow%20boots&utm_content=durable%20snow%20boots
```

**Additional settings**

* **Custom Post Types**: Add post types from plugins to enable notification options
* **Automatically send notifications when a post is published**: Automatically checks notification box when publishing posts so notifications are sent without having to check the box manually
* **Automatically send notifications when a post is updated**: Automatically checks notification box when updating posts so notifications are sent without having to check the box manually
* **Automatically send notifications when a page is published**: Automatically checks notification box when publishing pages so notifications are sent without having to check the box manually
* **Automatically send notifications when a page is updated**: Automatically checks notification box when updating pages so notifications are sent without having to check the box manually
* **Automatically send a push notification when I publish a post from 3rd party plugins**: Auto-send notifications from external publishing plugins
* **Mobile App Integration**: Send notifications to your mobile app subscribers using the same OneSignal App ID

### 3. Complete migration (Upgrading Users Only)

<Note>
  **New installations can skip this step. If you're upgrading from v2+, follow
  along...**
</Note>

<Warning>
  **Time-Sensitive**: Complete these steps ASAP to avoid users missing
  notifications during the transition.
</Warning>

<Steps>
  <Step title="After saving your OneSignal dashboard configuration, return to WordPress" />

  <Step title="Click Migration Completed in the plugin settings" />

  <Step title="Click Save Settings to finalize the upgrade" />
</Steps>

<Frame>
  <img alt="WordPress OneSignal plugin migration completed checkbox and save settings" />
</Frame>

<Check>
  Setup complete! Click **Save Settings** to finish plugin configuration.
</Check>

***

## Testing your setup

<Tabs>
  <Tab title="Initial Test">
    1. **Visit your website** in a normal (non-incognito) window for the most reliable test. Private browsing may show prompts but subscriptions often do not persist—see [WordPress troubleshooting](./troubleshooting-wordpress-web-push).

    2. **Look for the slidedown prompt** you configured.

       <Frame>
         <img alt="Website showing OneSignal slidedown subscribe prompt" />
       </Frame>

    3. **Click the subscribe button** (labeled as **Subscribe** in this example).

    4. **Accept the browser permission** when prompted.

       <Frame>
         <img alt="Browser native notification permission Allow Block prompt" />
       </Frame>

    5. **Check for welcome notification** (if configured).

       <Frame>
         <img alt="Desktop showing welcome push notification from OneSignal" />
       </Frame>
  </Tab>

  <Tab title="Verify Subscription">
    1. In your OneSignal dashboard, go to **Audience > Subscriptions**.
    2. You should see your web push [subscription](./subscriptions) marked as **Subscribed**.

       <Frame>
         <img alt="OneSignal Audience Subscriptions table with subscribed web push entry" />
       </Frame>
  </Tab>

  <Tab title="Send Test Message">
    1. Navigate to **Messages > Push** in your OneSignal dashboard.
    2. Create a **New Message**.
    3. Send a test notification to yourself.
    4. Verify the notification appears correctly.

    See our [Push messaging guide](./push) for detailed instructions.
  </Tab>
</Tabs>

<Check>
  **Success!** Your WordPress site is now configured for web push notifications.
  Users will start appearing in your Subscriptions as they subscribe.
</Check>

**Next Steps:**

* Review [Web permission prompts](./permission-requests) for advanced customization
* Explore [Channel setup](./channel-setup) for email and SMS integration
* Set up [segmentation strategies](./segmentation) for targeted messaging

<Info>
  **Having Issues?** Check our [WordPress troubleshooting
  guide](./troubleshooting-wordpress-web-push) for common solutions.
</Info>

***

## Publishing notifications

When you schedule a post to be published, OneSignal will also schedule a push notification to be sent to your subscribers at the scheduled time. If you reschedule the post, the push notification will be canceled and a new push will be scheduled for the new time.

You can view your scheduled and cancelled notifications in the OneSignal dashboard under **Delivery > Scheduled Messages**. See [Push message reports](./push-notification-message-reports) for more details.

### Basic post notifications

When creating or editing a WordPress post, locate the **OneSignal Push Notifications** metabox (usually at the bottom or sidebar of the post editor).

<Frame>
  <img alt="WordPress post editor OneSignal Push Notifications metabox with send checkbox" />
</Frame>

**To send a notification:**

* Check **"Send notification when post is published or updated"**
* Uncheck to skip sending a notification for that post

### Audience targeting

#### Send to all subscribers (default)

By default, notifications go to all push [subscribers](./subscriptions).

#### Send to specific segments

Target specific audiences using [segments](./segmentation) you create in **OneSignal Dashboard > Audience > Segments**.

**If you set up category-based prompts** in the dashboard (see **Advanced: Category-Based Segmentation** under [Setup](#setup)), create corresponding segments:

1. Go to **Audience > Segments** in your OneSignal dashboard
2. Create segments using your tag keys, eg:
   * **News Segment**: Tag `news` is `1`
   * **Deals Segment**: Tag `deals` is `1`

<Frame>
  <img alt="OneSignal segment editor with tag filters for news and deals" />
</Frame>

3. After creating segments, refresh your WordPress post editor
4. Select your target segment from the dropdown

<Frame>
  <img alt="WordPress OneSignal metabox segment dropdown for audience targeting" />
</Frame>

<Check>
  **Advanced Segmentation**: Create segments based on user behavior, location,
  device type, and more. [Tags](./add-user-data-tags) provide the most
  flexibility for custom user data and personalization.
</Check>

### Customizing notification content

#### Default behavior

* **Title**: Uses your WordPress site title (Settings > General)
* **Message**: Uses the post title
* **Image**: Uses the post's featured image (if set)
* **URL**: Links to the published post

#### Custom content

Check **"Customize notification content"** to override defaults:

<Frame>
  <img alt="WordPress OneSignal metabox customize notification title and message fields" />
</Frame>

**Example result:**

<Frame>
  <img alt="Example customized web push notification with title image and body" />
</Frame>

### Add a Custom Post Type to OneSignal WordPress Plugin

#### Find your custom post type name

Look at your browser's address bar when creating a new post. The URL will look like:

```
https://yoursite.com/wp-admin/post-new.php?post_type=your_custom_type
```

The value of the `post_type` parameter (for example, `your_custom_type`) is the exact name you'll need to add in the OneSignal plugin's settings.

#### Add to OneSignal settings

1. Go to **OneSignal > Settings** in WordPress admin
2. In **Advanced Settings**, add your custom post type names to the **Custom Post Types** field
3. Save settings

<Note>
  **Common examples:** `product` (WooCommerce), `tribe_events` (The Events Calendar), `portfolio`.
</Note>

## Mobile app integration

If you have a mobile app using the same OneSignal App ID:

1. Enable **"Send notification to Mobile app subscribers"** in plugin settings
2. In the post metabox, add a **Mobile URL** for [deep linking](./deep-linking)
3. Mobile users will be directed to your app instead of the web browser

<Check>
  **Ready to Scale**: Explore [advanced push strategies](./push) and
  [automated journeys](./journeys-overview) for sophisticated notification
  campaigns.
</Check>

<Warning>
  **Notifications Not Appearing?** Check our [Web push troubleshooting
  guide](./notifications-not-shown-web-push) for solutions.
</Warning>

***

## FAQ

<Accordion title="How do I disable prompts on specific pages?" icon="circle-chevron-down">
  **Note**: This method only works with slidedown and native permission prompts, not bell or custom link prompts.

  1. In your OneSignal dashboard, go to **Settings > Push & In-App > Web Settings**
  2. Select your prompt from the **Permission Prompt Setup** table
  3. Uncheck **Auto Prompt** and click **Done**

  <Frame>
    <img alt="Dashboard prompt editor with Auto Prompt unchecked" />
  </Frame>

  4. Scroll down, click **Save**, then **Finish**
  5. Add [custom JavaScript code](./web-sdk-reference#slidedown-prompts) to specific pages where you want prompts to appear

  This gives you complete control over prompt timing and placement. See [Web permission prompts](./permission-requests) for implementation details.
</Accordion>

<Accordion title="Can I send notifications to mobile app subscribers?" icon="circle-chevron-down">
  Yes! If your mobile app uses the same OneSignal App ID:

  1. Enable **"Send notification to Mobile app subscribers"** in the WordPress plugin settings
  2. When publishing posts, use the **Mobile URL** field in the OneSignal metabox to specify deep links
  3. Without a custom Mobile URL, users will be directed to your website

  This feature enables cross-platform messaging from a single WordPress interface.
</Accordion>

<Accordion title="How do I send email or SMS from WordPress?" icon="circle-chevron-down">
  The WordPress plugin currently supports push notifications only. For email and SMS:

  1. **Email**: Follow our [Email setup guide](./email-setup), then use [Email messaging tools](./email-messaging)
  2. **SMS**: Follow our [SMS setup guide](./sms-setup), then use [SMS messaging tools](./sms-messaging)

  Both channels can be managed from the same OneSignal dashboard alongside your push notifications.
</Accordion>

<Accordion title="Why aren't my prompts working after migration?" icon="circle-chevron-down">
  **Caching Issues**: WordPress caching may delay migration changes.

  **Solution:**

  **Step 1:** Right-click on your website and select **Inspect**

  **Step 2:** Go to the **Network** tab

  **Step 3:** Check **"Disable cache"**

  <Frame>
    <img alt="Chrome DevTools Network tab with Disable cache checked" />
  </Frame>

  **Step 4:** Refresh your website to see current configuration

  **Step 5:** Clear your WordPress cache plugin settings if applicable
</Accordion>

<Accordion title="What does `A bad HTTP response code (404)` error mean?" icon="circle-chevron-down">
  This error indicates incomplete migration:

  <Frame>
    <img alt="Browser console showing bad HTTP response code 404 for OneSignal" />
  </Frame>

  **Solution:**

  1. Ensure you've saved your OneSignal dashboard configuration
  2. In WordPress, click **"Migration Completed"** in the plugin settings
  3. Click **Save Settings** to finalize the upgrade

  **This error only affects users upgrading from version 2.x.x.**
</Accordion>

<Accordion title="Can I modify the notification parameters before sending?" icon="circle-chevron-down">
  Yes, you can use the `onesignal_send_notification` filter.

  <Info>
    Place custom PHP code in `wp-content/mu-plugins/onesignal-custom.php`. This
    ensures it loads correctly and prevents it from being overwritten by updates.
  </Info>

  ```php theme={null}
  <?php

  add_filter('onesignal_send_notification', function ($fields, $post_id) {

    // Add fields supported by the Create notification API:
    // https://documentation.onesignal.com/reference/create-notification

    $fields['web_buttons'] = array(
      array(
        'id' => 'read-more',
        'text' => 'Read More',
        'url' => get_permalink($post_id),
      ),
    );

    return $fields;

  }, 10, 2);
  ```
</Accordion>

***


# 2-step authentication
Source: https://documentation.onesignal.com/docs/en/2-step-authentication

Set up, manage, and recover 2-step authentication (2FA) for your OneSignal account, including recovery codes, transferring to a new device, and regaining access if locked out.

## Overview

Protect your OneSignal account with 2-step authentication (2FA). Once enabled, you enter a time-sensitive 6-digit code from an authenticator app each time you log in.

<Danger>
  **Save your recovery codes immediately after setup.** Recovery codes are shown only once and are the only way to log back in if you lose access to your authenticator app. If you lose both, you must email `support@onesignal.com` and **CC a team member who can verify your identity** to regain access.
</Danger>

If you're locked out right now, jump to [Recover access if locked out](#recover-access-if-locked-out).

***

## Set up or reconfigure 2-step authentication

Use this flow whether you're enabling 2FA for the first time, moving it to a new device, or replacing a lost setup after logging in with a recovery code. The steps are identical. The button is labeled **Enable** the first time and **Reconfigure** after that.

<Warning>
  Set up your authenticator on a **personal device you control long-term**, not a shared or temporary test device. If you lose access to that device and your recovery codes, you will be locked out of your account.
</Warning>

### Step 1: Choose an authenticator app

Any TOTP (Time-based One-Time Password) compatible app works. Choose one that supports cloud backup or multi-device sync to avoid losing access if you switch phones:

* **Google Authenticator** (recommended, supports [cloud backup](https://support.google.com/accounts/answer/1066447)): [Android](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2) | [iOS](https://apps.apple.com/us/app/google-authenticator/id388497605)
* **Microsoft Authenticator**: [Android](https://play.google.com/store/apps/details?id=com.azure.authenticator) | [iOS](https://apps.apple.com/us/app/microsoft-authenticator/id983156458)
* **Authy** (supports multi-device sync): [authy.com](https://authy.com/download/)
* **1Password**, **Bitwarden**, or any other TOTP app

### Step 2: Open Account Management

<Steps>
  <Step title="Sign in to your OneSignal account">
    Sign in normally. If you can't sign in, see [Recover access if locked out](#recover-access-if-locked-out).
  </Step>

  <Step title="Go to Account Management">
    Navigate to [Account Management](https://dashboard.onesignal.com/profile) or click **your email drop-down > Manage account**.

    <Frame>
      <img alt="Manage Account option in the dashboard email drop-down menu" />
    </Frame>
  </Step>

  <Step title="Click Enable or Reconfigure">
    Scroll to the **2-Step Authentication** section. Click **Enable** for first-time setup, or **Reconfigure** to move 2FA to a new device or replace a lost setup.

    <Frame>
      <img alt="Enable button in the 2-Step Authentication section of the profile page" />
    </Frame>
  </Step>
</Steps>

### Step 3: Connect your authenticator app

<Steps>
  <Step title="Scan the QR code or enter the key manually">
    On the **Enable 2-Step Authentication** screen, scan the QR code with your authenticator app or copy the **Secret Key** to enter it manually.

    <Frame>
      <img alt="OneSignal QR code and Secret Key for authenticator setup" />
    </Frame>

    If entering the key manually in your authenticator app, choose the option to **Enter a setup key** and name the entry something memorable like `OneSignal_[your_email]`.
  </Step>

  <Step title="Enter the 6-digit code">
    Your authenticator app generates a new 6-digit code every 30 seconds. Enter the current code in OneSignal to verify the connection.

    If the code fails, wait 30 seconds and try the next one. If it still fails, confirm the Secret Key was entered correctly and try again.
  </Step>
</Steps>

### Step 4: Save your recovery codes

OneSignal displays **10 one-time recovery codes** after a successful setup or reconfigure. Each code can only be used **once** to log in if you lose access to your authenticator app.

<Frame>
  <img alt="OneSignal recovery codes screen with download option" />
</Frame>

<Danger>
  **Recovery codes are shown only once.** Download or copy them now and store them in a password manager or another secure location. Reconfiguring 2FA invalidates the previous set, so always save the fresh codes after a reconfigure.
</Danger>

***

## Recover access if locked out

If you can't sign in because you don't have your authenticator app, follow the path that matches what you still have access to.

### If you have a recovery code

<Steps>
  <Step title="Log in with a recovery code">
    1. Enter your email and password on the OneSignal login page.
    2. On the 2FA verification screen, choose the option to enter a recovery code instead of a 6-digit code.
    3. Enter one of your saved recovery codes. Each code works only once, so cross it off your list after use.
  </Step>

  <Step title="Immediately reconfigure 2FA on a device you control">
    Recovery codes run out. Follow [Set up or reconfigure 2-step authentication](#set-up-or-reconfigure-2-step-authentication) right after you log in. Reconfiguring invalidates all old recovery codes and generates a fresh set.
  </Step>
</Steps>

<Warning>
  If you keep logging in with recovery codes instead of reconfiguring, you will run out and be locked out again.
</Warning>

### If you don't have recovery codes

Email `support@onesignal.com` and **CC a team member who can verify your identity**. The team member must have access to the OneSignal account and will need to confirm your access before our Support Team can reset your 2FA.

If no one else on your team has access to the OneSignal account, the Support Team will guide you through alternative verification (such as confirming billing or domain ownership).

After your 2FA is reset, log in and follow [Set up or reconfigure 2-step authentication](#set-up-or-reconfigure-2-step-authentication) immediately. Save the new recovery codes this time.

***

## Enforce 2FA for all team members

Organization Admins can require every team member to use 2FA. See [Team members](./manage-team-members) for role details.

<Steps>
  <Step title="Open your organization">
    Go to [Organizations](https://dashboard.onesignal.com/organization) in the left sidebar and select your organization.
  </Step>

  <Step title="Open Security settings">
    Under **Team Members > Security**, click **Enable**.

    <Frame>
      <img alt="Team Members Security settings with Enable button for 2FA enforcement" />
    </Frame>
  </Step>

  <Step title="Require 2-step authentication for all users">
    Select **Require 2-Step Authentication for all users**, then click **Continue**.

    <Frame>
      <img alt="Dialog requiring 2-Step Authentication for all users with Continue button" />
    </Frame>
  </Step>
</Steps>

<Check>
  Future invitations require new users to set up 2FA before accessing the organization or its apps. Existing users without 2FA must set it up on their next login.
</Check>

***

## Disable 2FA

<Warning>
  You may not disable 2FA if your organization requires it. Contact your [Organization Admin](./manage-team-members) or `support@onesignal.com` if needed.
</Warning>

Follow Steps 1 and 2 of [Set up or reconfigure 2-step authentication](#set-up-or-reconfigure-2-step-authentication). If 2FA is currently enabled, the **2-Step Authentication** section gives you the option to disable it.

***

## FAQ

### I'm locked out of my account, how do I get back in?

See [Recover access if locked out](#recover-access-if-locked-out). If you have a recovery code, use it to log in and then reconfigure 2FA immediately. If you don't, email `support@onesignal.com` and CC a team member who can verify your identity.

### Why do I keep getting asked for a recovery code every time I log in?

Your authenticator app is no longer generating valid codes for your OneSignal account. This usually happens when the app was on a device you no longer have. Each recovery code is single-use, so you will eventually run out. To fix this permanently, [reconfigure 2FA on a device you currently use](#set-up-or-reconfigure-2-step-authentication) after logging in.

### Why can't I log in or see "Failed to configure OTP"?

Try these in order:

* Wait for the next 30-second code cycle and try again
* Check that your device with the authenticator app is using automatic time synchronization and not manually set to a different time.
* Disable browser extensions that block scripts or third-party requests (ad blockers, privacy extensions)
* Allow `*.onesignal.com` in any tracking-protection or content-blocker settings
* Hard refresh the page
* Try a different browser

Still having issues? Email `support@onesignal.com` and **CC a team member who can verify your identity**.

### I forgot my password

[Reset your password](https://dashboard.onesignal.com/password-reset). Password reset is separate from 2FA. You still need your authenticator app or a recovery code after resetting your password.

### Can I use OAuth with 2FA?

Yes. Follow the same setup flow after logging in via OAuth.

### Does OneSignal support Okta?

Yes, there are two options:

1. Your Okta admin can add OneSignal as an app using [Secure Web Authentication (SWA)](https://help.okta.com/en/prod/Content/Topics/Apps/Apps_Overview_of_Managing_Apps_and_SSO.htm). See the [OneSignal integration on Okta](https://www.okta.com/integrations/onesignal/) for setup. OneSignal's 2FA is separate from Okta.
2. Talk to our [Sales team](https://www.onesignal.com/contact) to discuss setting this up based on your plan.

### What do the login method icons mean?

<Frame>
  <img alt="Login method icons" />
</Frame>

***

## Related pages

<Columns>
  <Card title="Team members" icon="users" href="./manage-team-members">
    Manage roles, permissions, and 2FA enforcement for your organization.
  </Card>

  <Card title="Single sign-on (SSO)" icon="key" href="./sso">
    Configure SAML-based SSO for your organization.
  </Card>
</Columns>


# Tags
Source: https://documentation.onesignal.com/docs/en/add-user-data-tags

Use OneSignal Tags to store user properties and track events for advanced segmentation and personalized messaging.

Tags are key-value pairs that let you store custom properties and track user behavior in OneSignal. They enable powerful segmentation and personalization.

<Frame>
  <iframe title="Introduction to Tags" />
</Frame>

Use tags to:

* Store user traits like `subscription_tier` or `name`
* Track behaviors like `purchases`, `clicks`, or `levels`
* Segment users for messages and Journeys
* Personalize message content

<Frame>
  <iframe title="Using Tags for segmentation" />
</Frame>

***

## Data tag value formatting rules

All Tag values must be **strings**. You can still store numbers, timestamps, and boolean-like values — stringify them before sending.

| Value Type   | Format Example                      | Notes                                                                    |
| ------------ | ----------------------------------- | ------------------------------------------------------------------------ |
| String Label | `"free"`, `"VIP"`                   | For user types, privileges, statuses                                     |
| Number       | `"42"`, `"3.14"`                    | Enables numeric filters (`greater than`, `less than`)                    |
| Timestamp    | `"1685400000"`                      | Unix timestamp (in seconds). Use with [Time Operators](./time-operators) |
| Boolean      | `"true"` / `"false"`, `"1"` / `"0"` | Use `"1"`/`"0"` to reduce payload size                                   |

<Frame>
  <iframe title="Tag value formatting" />
</Frame>

<Warning>
  **Not supported:** Arrays, objects, nested values, or JSON blobs. If you need to store complex data, use [Custom Events](./custom-events).
</Warning>

### Restricted keywords

The following keywords are restricted and should not be used as tag keys because they are used internally for message personalization:
`message`, `notification`, `subscription`, `user`, `template`, `app`, `org`, `dynamic_content`, `data_feed`, `journey`, `custom_data`

<Card title="Message personalization" icon="user-pen" href="./message-personalization">
  Learn which keywords are reserved and how personalization tags work.
</Card>

### Tags vs Custom Events

[Tags](/docs/en/add-user-data-tags) and [Custom Events](/docs/en/custom-events) are both ways to add data to your users. However, there are some key differences:

| Feature        |                   Tags                   |                                          Custom Events                                         |
| -------------- | :--------------------------------------: | :--------------------------------------------------------------------------------------------: |
| Data usage     |     Segmentation and personalization     | Trigger Journeys without a Segment, Wait Until steps, personalization directly within Journeys |
| Data retention |                 Lifetime                 |        30+ days ([lifetime storage is available](/docs/en/billing-faq#streaming-events))       |
| Data format    |       Key-value strings or numbers       |                                              JSON                                              |
| Data source    |     OneSignal SDK, API, or CSV import    |                               OneSignal SDK, API, or integrations                              |
| Data access    | Segmentation and message personalization |        Journeys and Journey-message-template personalization, Segmentation (Coming soon)       |

The key distinction between Tags and Custom Events is in their depth and use cases. Tags are properties of a user, such as Name, Account Status, or Location. Events are thing that the user has done, such as Purchasing an Item, Completing a Level, or Inviting a Friend. Both tags and events can be used for segmentation and personalization.

In practice, you will likely use both:

* Tags for user properties that are static and don't change often
* Custom Events for real-time scenarios, complex segmentation, and more sophisticated journey workflows

***

## Recommended tag strategies

Tags should represent information you want to **use in messages or audience segmentation**. They're not meant to store full user profiles or logs—use your backend database for that.

<Frame>
  <iframe title="Tag strategy best practices" />
</Frame>

### Event-based behavior tags

Track user actions with tags. Great for triggering Journeys, follow-ups, or reminders.

| Key           | Value Example  | Description                                                                       |
| ------------- | -------------- | --------------------------------------------------------------------------------- |
| `cart_update` | `"1685400000"` | Last time the user added an item to cart. Use [Time Operators](./time-operators). |
| `last_order`  | `"1684100000"` | Last completed purchase timestamp                                                 |

\| `social_share`         | `"2"`                 | Count of social shares or referrals                                        |
\| `tutorial_status`      | `"step2"` or `"completed"` | Tutorial progress—use readable or numbered string values              |

### Game activity tags

Used by games to personalize based on user performance.

| Key          | Value Example | Description               |
| ------------ | ------------- | ------------------------- |
| `points`     | `"1250"`      | Experience or game points |
| `level`      | `"8"`         | Current game level        |
| `high_score` | `"3000"`      | Highest score achieved    |

### Account status tags

Use these to target users by account tier or change in status.

| Key               | Value Example           | Description                       |
| ----------------- | ----------------------- | --------------------------------- |
| `user_type`       | `"free"`, `"premium"`   | Subscription or access tier       |
| `has_downgraded`  | `"1"` or `"1685400000"` | Boolean or timestamp of downgrade |
| `user_privileges` | `"admin"`, `"guest"`    | Role-based segmentation           |

<Note>
  Use **External ID** to identify individual users. Do **not** use tags for this purpose. See [External ID](./users#external-id) and [Aliases](./aliases).
</Note>

### Personalization tags

Use these for name-based message customization with [Message personalization](./message-personalization).

| Key          | Value Example     | Description            |
| ------------ | ----------------- | ---------------------- |
| `first_name` | `"Jon"`           | First name             |
| `last_name`  | `"Smith"`         | Last name              |
| `user_name`  | `"PokeCatcher22"` | Display or screen name |

### Location & demographic tags

Segment users by region or age.

| Key          | Value Example   | Description                                                                       |
| ------------ | --------------- | --------------------------------------------------------------------------------- |
| `region`     | `"New York"`    | Metro area, optionally use [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) |
| `postcode`   | `"94105"`       | Zip or postal code                                                                |
| `location`   | `"Downtown LA"` | Custom string location                                                            |
| `birthdate`  | `"915148800"`   | Unix timestamp in seconds (birth date)                                            |
| `birth_year` | `"1998"`        | Four-digit birth year                                                             |
| `age_range`  | `"18-35"`       | Useful for general audience segmentation                                          |

## How to add, update, and remove Tags

You can manage Tags using any of the methods below, depending on your use case and technical setup.

<Frame>
  <iframe title="How to add and manage Tags" />
</Frame>

<Columns>
  <Card title="SDK methods (recommended)" icon="code" href="./mobile-sdk-reference#data-tags">
    Set tags in real time from your app or website as users perform actions. See also [Web SDK reference](./web-sdk-reference#data-tags).
  </Card>

  <Card title="REST API" icon="server" href="/reference/update-user">
    Add, update, or remove tags server-side with the Update User endpoint.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Automatically apply tags as users move through Journey steps.
  </Card>

  <Card title="Import" icon="file-csv" href="./import">
    Bulk update Tags by uploading a CSV with `external_id` or `subscription_id`.
  </Card>

  <Card title="Web category prompts" icon="browser" href="./permission-requests">
    Prompt users to self-select interests, which are stored as tags.
  </Card>

  <Card title="In-app messages" icon="message" href="./in-app-messages-setup">
    Collect or update tags based on in-app message click actions.
  </Card>

  <Card title="Third-party integrations" icon="plug" href="./integrations">
    Sync tags automatically with Segment, HubSpot, Mixpanel, and others.
  </Card>
</Columns>

***

## FAQ

### How many tags can I set per user?

Depends on your plan. See your [plan limits](https://onesignal.com/pricing) or [contact sales](https://onesignal.com/contact) to increase your quota.

### What happens to my tags if I exceed plan limits?

There is no limit to the number of tags available within a OneSignal app. The limit applies to how many tags can be set on each individual user at a single time.

You **can’t add or update** tags for users who are at or above their limit. You must delete tags first, then send a second request to add new ones.

Tags already set will persist.

Example:

Your plan limit = 20 tags/user.

* User has 19 tags:
  * ✅ Add 1 new tag = success
  * ❌ Add 2+ new tags = failure
* User has 20 tags:
  * ❌ Add any new tag = failure
  * ✅ Update 1+ existing tag = success

### Where can I check tag usage?

* Dashboard: **Audience > Users > Tags column**
* [Export users](./exporting-data) for a complete view

### How do I reduce tag usage?

* Remove tags using SDK or API
* Use [CSV Import](./import) to bulk delete
* Use fewer, more reusable tags (e.g., `status:active`)

### Why are Tags not showing on a user?

**Network connection** — The most common cause. If the network is unstable or unavailable when the tag request fires, it may not reach the server.

* **Mobile SDKs (v5+)** cache tags locally and retry when a stable connection is detected.
* **Web SDK** requires the user to exist before tags can be set. The user is created when they subscribe to web push or you call `addEmail`/`addSms`. Calling the `login` method is recommended so the subscription is associated with a known user. Tags are sent automatically as long as the page session is still active — if the user navigates away before the tags are set, they are lost. Use `getTags` to verify, or call `addTags` again on the next session.

**Browser cache cleared** — When web subscribers clear their browser data, subscription data stored in the browser is destroyed. OneSignal can automatically resubscribe the user when they return, but tags are not restored unless:

1. The `login` method is called, which re-associates the new subscription with the existing user and their tags.
2. The tagging methods are called again on the new session.

<Note>
  See [Web push browser behavior](./browser-behavior-and-unsubscribes) for more details.
</Note>

## Related pages

<Columns>
  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Use tag values to personalize messages with Liquid templating.
  </Card>

  <Card title="Segments" icon="users" href="./segmentation">
    Build audience segments using tag filters and other conditions.
  </Card>

  <Card title="Time operators" icon="clock" href="./time-operators">
    Filter segments by time-based tag values like last purchase or last login.
  </Card>

  <Card title="Import users" icon="file-csv" href="./import">
    Bulk import or update Tags via CSV upload.
  </Card>
</Columns>

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# Adobe Audience Manager
Source: https://documentation.onesignal.com/docs/en/adobe-audience-manager

Learn how to integrate OneSignal with Adobe Audience Manager to sync audience segments and behavioral data, enabling targeted, multi-channel messaging campaigns that drive engagement, conversions, and revenue growth.

Integrating Adobe Audience Manager with OneSignal allows you to bring powerful audience segmentation from Adobe into OneSignal's customer engagement platform. This enables personalized, behavior-based messaging that increases user retention and monetization.

## Capabilities

OneSignal and Adobe Audience Manager integration supports:

* **Real-time segment sync**: Automatically import segments from Adobe Audience Manager into OneSignal.
* **Cross-channel targeting**: Use imported segments to send push notifications, emails, SMS, and in-app messages via OneSignal.
* **ECID-based user matching**: Ensure users in OneSignal align with Adobe identities for accurate targeting.

***

## Requirements

* A [paid OneSignal account](https://onesignal.com/pricing).
* Users must be matched using Adobe's Marketing Cloud ID (MID or ECID).
  * Ensure the `external_id` field in OneSignal is set to the Adobe ECID.
  * If you prefer to use a different identifier, contact OneSignal Support.

***

## Setup

### Connection parameters

You’ll need the Client ID to configure the Adobe Destination:

* Go to your OneSignal Dashboard.
* Navigate to: **Data > Integrations > Adobe**.
* Copy the Client ID displayed there.

<Frame>
  <img />
</Frame>

### Set up with Adobe

Contact your Adobe representative (Adobe consultant or CustomerCare) who will review the integration request and will work with you to activate the OneSignal Destination. You'll need to provide the following information to the Adobe representative:

* the Client ID

Once the Adobe representative has set up the OneSignal Destination, the segments should start flowing to OneSignal.

### Optional: Configure segment friendly names

By default, each segment synced between OneSignal and Adobe Audience Manager will be identified with a numeric Adobe Audience Manager Segment ID. If you'd like to instead use a "friendly" name to identify the Segment within the OneSignal Dashboard, please follow these steps:

1. Log in to Adobe Audience Manager
2. Follow the path to Audience Data > Segments
3. Select all the segments you wish to add to the OneSignal destination
4. Click "Add To Destination"
5. Select the Destination
6. Click Add To Selected Destination
7. Enter the friendly name for each Segment in the "Destination Value" fields

<Frame>
  <img />
</Frame>

8. Click Save
9. The Segment "friendly" name has now been mapped to the Segment and the destination

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Aliases
Source: https://documentation.onesignal.com/docs/en/aliases

Learn how to use custom aliases in OneSignal to identify and track users across different platforms and devices using your own unique identifiers. Aliases help unify user data across multiple sources and are essential for integrations, user data management, and transactional messaging.

Custom aliases allow you to assign custom key-value identifiers to users in OneSignal, enabling cross-platform user tracking and identification using your own internal IDs.

<Warning>
  **Important**: You must set an [External ID](./users) **before** using custom aliases.

  OneSignal uses a unique `onesignal_id` to identify users. This ID only stays consistent across [Subscriptions](./subscriptions) if they have the same `external_id`.

  Custom aliases **do not** link Subscriptions together—they rely on the `external_id` to work correctly. Without it, aliases won't associate with the same user across devices or platforms.
</Warning>

***

## What is a custom alias?

A custom alias is a `key : value` pair where:

* The `alias_label` (key) is a consistent, static identifier across all users (e.g., `facebook_id`, `firebase_id`, `crm_user_id`).
* The `alias_id` (value) is the specific user’s ID for that label (e.g., `facebook_id: 3453443`, `firebase_id: test3555`).

This allows you to link OneSignal user records to identifiers from your other platforms or databases.

***

## Why use aliases?

1. Identify users across multiple platforms and databases.
2. Send targeted transactional messages using the [Create Message REST API](/reference/create-message).
3. Fetch, update, or delete users via the User REST APIs.

***

## How to Set Aliases

You can set aliases either using the OneSignal SDK or via the REST API.

### Using the SDK

Follow these steps in your app:

1. Set the External ID
   Call `OneSignal.login(externalId)` to associate the user record.

2. Set custom aliases
   Use `OneSignal.User.addAlias(label, id)` to add a single alias, or `OneSignal.User.addAliases({ label1: id1, label2: id2 })` to set multiple.

3. Logout (optional)
   Use `OneSignal.logout()` to remove the external ID and any associated aliases for that device or session.

**Example**:

```javascript theme={null}
OneSignal.login("user_123");

OneSignal.User.addAliases({
  facebook_id: "3453443",
  firebase_id: "test3555"
});

// Later, when the user logs out
OneSignal.logout();
```

***

### Using the REST API

To set custom aliases via the API, use the [Create Alias](/reference/create-alias) endpoint. This method is typically used in backend systems for server-side user management.

**Example Request**:

```json theme={null}
POST /aliases
{
  "subscription_id": "abc123",
  "aliases": {
    "facebook_id": "3453443",
    "crm_user_id": "XYZ789"
  }
}
```

#### Alias limits

* Each user can have up to 10 aliases.
* Each alias key and value can be no longer than 128 characters.

***

## Best practices

* Always set the `external_id` before assigning any aliases.
* Use stable, descriptive labels (e.g., `crm_user_id`, `legacy_user_id`) to avoid confusion across teams.
* Avoid using sensitive information such as email addresses or phone numbers as alias values.
* Use `logout()` to clean up aliases on device sign-out or user switch events.

***

<Check>
  Custom aliases tutorial complete!
  Next steps:

  * Review our [Users](./users) and [Subscriptions](./subscriptions) documentation if you have not already.
  * Explore our [REST API](/reference/create-alias) documentation for more details on using aliases via the API.
  * Set up [Integrations](./integrations) to sync user data across systems.
</Check>

***


# AlloyDB
Source: https://documentation.onesignal.com/docs/en/alloydb

Sync custom events from Google AlloyDB to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Google AlloyDB integration enables automatic syncing of custom events from your AlloyDB database directly to OneSignal's Custom Events API. This allows you to trigger automated Journeys and personalized messaging campaigns based on real user behavior stored in your database.

You can sync events like purchases, product views, subscription changes, or any custom user actions to automatically trigger onboarding sequences, re-engagement campaigns, transactional messages, and targeted promotions across push notifications, email, in-app messages, and SMS.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Google AlloyDB

* **Google Cloud Platform** account with AlloyDB instance
* **Auth Proxy** configured as required by Google Cloud
* **Database permissions** to create users and grant access
* **Network access** to your AlloyDB instance

***

## Setup

### Configure AlloyDB permissions

OneSignal needs to read event data from your AlloyDB database. We recommend creating a dedicated `ONESIGNAL` user account with read-only access to your event tables.

<Steps>
  <Step title="Create OneSignal database user">
    Create a dedicated user account with a strong, unique password:

    ```sql theme={null}
    -- Create the OneSignal user
    CREATE USER ONESIGNAL WITH PASSWORD '<strong, unique password>';
    ```
  </Step>

  <Step title="Grant schema access">
    Grant the OneSignal user access to read from your event data schema:

    ```sql theme={null}
    -- Let the OneSignal user see your event schema
    GRANT USAGE ON SCHEMA "<your_event_schema>" TO ONESIGNAL;

    -- Let the OneSignal user read all existing tables in this schema
    GRANT SELECT ON ALL TABLES IN SCHEMA "<your_event_schema>" TO ONESIGNAL;

    -- Let the OneSignal user read any new tables added to this schema
    ALTER DEFAULT PRIVILEGES IN SCHEMA "<your_event_schema>" GRANT SELECT ON TABLES TO ONESIGNAL;
    ```

    <Info>
      Replace `<your_event_schema>` with the actual schema containing your event tables.
    </Info>
  </Step>

  <Step title="Grant function permissions (if needed)">
    If you use stored procedures or functions for event data:

    ```sql theme={null}
    -- Let the OneSignal user execute functions in this schema
    GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA "<your_event_schema>" TO ONESIGNAL;

    -- Let the OneSignal user execute any new functions added to this schema
    ALTER DEFAULT PRIVILEGES IN SCHEMA "<your_event_schema>" GRANT EXECUTE ON FUNCTIONS TO ONESIGNAL;
    ```
  </Step>
</Steps>

### Set up Auth Proxy

<Steps>
  <Step title="Configure Auth Proxy">
    AlloyDB requires an Auth Proxy for third-party connections. Follow [Google's Auth Proxy documentation](https://cloud.google.com/alloydb/docs/auth-proxy/overview) to set this up.

    <Warning>
      The Auth Proxy is required - OneSignal cannot connect directly to AlloyDB without it.
    </Warning>
  </Step>

  <Step title="Note connection details">
    Save the following connection information:

    * **Host**: Auth Proxy endpoint
    * **Port**: Auth Proxy port (typically 5432)
    * **Database**: Your AlloyDB database name
    * **Username**: `ONESIGNAL` (created above)
    * **Password**: The password you set
  </Step>
</Steps>

### Configure OneSignal AlloyDB connection

<Steps>
  <Step title="Navigate to integrations">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.
  </Step>

  <Step title="Select Google AlloyDB">
    Choose **Google AlloyDB** from the list of available integrations.
  </Step>

  <Step title="Enter connection details">
    Provide the AlloyDB connection information:

    * **Host**: Your Auth Proxy endpoint
    * **Port**: Auth Proxy port
    * **Database**: AlloyDB database name
    * **Username**: `ONESIGNAL`
    * **Password**: User password
    * **SSL**: Enabled (recommended)
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify OneSignal can access your AlloyDB instance.
  </Step>
</Steps>

***

## Event Data Mapping

Once connected, you'll need to map your AlloyDB table columns to OneSignal custom event fields:

<Steps>
  <Step title="Select event tables">
    Choose the tables containing your event data that you want to sync to OneSignal.
  </Step>

  <Step title="Map required event fields">
    Map the required fields for custom events:

    * **Event Name**: Column containing the event type (e.g., "purchase", "signup")
    * **User Identifier**: External User ID, Email, or Phone Number column
    * **Event Timestamp**: When the event occurred (optional)
  </Step>

  <Step title="Map event payload data">
    Map additional columns to event payload properties:

    * Custom event properties (product\_id, price, category, etc.)
    * Contextual data (source, campaign, etc.)
    * Behavioral metrics (value, quantity, etc.)
  </Step>

  <Step title="Configure sync settings">
    Set your event processing frequency and delivery preferences.
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

***

## Advanced Network Configuration

### IP Address Allowlists

If your AlloyDB instance uses IP allowlists, add OneSignal's IP addresses. You can find the current IP ranges in your OneSignal dashboard under **Data > Integrations > Network Access**.

### SSH Tunneling

OneSignal supports connecting to AlloyDB through SSH tunnels for additional security:

<Steps>
  <Step title="Create SSH user">
    Create a dedicated user account for OneSignal on your SSH host server.
  </Step>

  <Step title="Configure SSH tunnel">
    In the OneSignal AlloyDB connection settings, enable **Use SSH Tunnel** and provide:

    * SSH Host
    * SSH Port
    * SSH Username
  </Step>

  <Step title="Add SSH key">
    OneSignal will generate an SSH keypair. Copy the public key to your SSH host's `authorized_keys` file for the OneSignal user.
  </Step>
</Steps>

***

## Limitations

* **Performance**: Avoid connecting to production databases during peak usage
* **Permissions**: OneSignal requires read-only access to event tables
* **Auth Proxy**: Required for all AlloyDB connections

***

## FAQ

### What happens if my event table structure changes?

OneSignal will detect schema changes and may require remapping of fields. Update your field mappings in the integration settings.

### How often does OneSignal sync events?

OneSignal checks for new events based on your configured sync frequency, with a minimum interval of 15 minutes.

***

## Need help?

Contact our support team at `support@onesignal.com` or use the in-app chat for assistance with your AlloyDB integration setup.


# Amazon Athena
Source: https://documentation.onesignal.com/docs/en/amazon-athena

Sync custom events from Amazon Athena to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Amazon Athena integration enables automatic syncing of custom events from your Athena data lake directly to OneSignal's Custom Events API. This allows you to trigger automated Journeys and personalized messaging campaigns based on real user behavior stored in your AWS data infrastructure.

You can sync events like purchases, product views, subscription changes, or any custom user actions to automatically trigger onboarding sequences, re-engagement campaigns, transactional messages, and targeted promotions across push notifications, email, in-app messages, and SMS.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Amazon Athena

* **AWS Account** with Athena access
* **Athena Workgroup** configured (default: "primary")
* **S3 Query Results Bucket** for Athena query outputs
* **IAM Permissions** for Athena, S3, and AWS Glue access
* **Event data** stored in S3 and cataloged in AWS Glue

***

## Setup

### Configure AWS permissions

OneSignal needs specific permissions to query your event data through Athena. Create an IAM policy with the following permissions:

<Steps>
  <Step title="Create IAM policy">
    Create an IAM policy that includes these permissions:

    ```json theme={null}
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "athena:StartQueryExecution",
                    "athena:GetQueryExecution",
                    "athena:GetQueryResultsStream",
                    "athena:GetQueryResults",
                    "athena:CreatePreparedStatement",
                    "athena:DeletePreparedStatement",
                    "glue:GetTable",
                    "glue:GetTables",
                    "glue:GetDatabase",
                    "glue:GetDatabases",
                    "s3:PutObject",
                    "s3:GetObject",
                    "s3:ListBucket",
                    "s3:GetBucketLocation"
                ],
                "Resource": [
                    "arn:aws:glue:<region>:<aws-account-id>:table/<database>/*",
                    "arn:aws:glue:<region>:<aws-account-id>:database/<database>",
                    "arn:aws:glue:<region>:<aws-account-id>:catalog",
                    "arn:aws:athena:<region>:<aws-account-id>:workgroup/<workgroup>",
                    "arn:aws:s3:::<query-results-bucket>",
                    "arn:aws:s3:::<query-results-bucket>/*",
                    "arn:aws:s3:::<event-data-bucket>",
                    "arn:aws:s3:::<event-data-bucket>/*"
                ]
            }
        ]
    }
    ```

    <Info>
      Replace the placeholders with your actual AWS region, account ID, database name, workgroup, and bucket names.
    </Info>
  </Step>

  <Step title="Create IAM user or role">
    Create an IAM user for OneSignal and attach the policy created above, or prepare to use role-based access.
  </Step>

  <Step title="Note connection details">
    Collect the following information:

    * **AWS Access Key ID** and **Secret Access Key** (if using IAM user)
    * **S3 Query Results Bucket** URL
    * **AWS Region**
    * **Athena Workgroup** (default: "primary")
  </Step>
</Steps>

### Configure OneSignal Athena connection

<Steps>
  <Step title="Navigate to integrations">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.
  </Step>

  <Step title="Select Amazon Athena">
    Choose **Amazon Athena** from the list of available integrations.
  </Step>

  <Step title="Enter connection details">
    Provide your Athena connection information:

    * **AWS Access Key ID**: Your IAM user access key
    * **AWS Secret Access Key**: Your IAM user secret key
    * **AWS Region**: Your Athena region
    * **S3 Query Results Bucket**: URL for query outputs
    * **Athena Workgroup**: Your workgroup name
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify OneSignal can access your Athena instance and execute queries.
  </Step>
</Steps>

### Alternative: Role-based access

For enhanced security, you can use IAM roles instead of access keys:

<Steps>
  <Step title="Enable role-based access">
    In the Athena connection settings, check **Use Role** and leave the access keys blank.
  </Step>

  <Step title="Create IAM role">
    In the AWS Console, create an IAM role with:

    * **Trusted Entity**: Another AWS Account
    * **Account ID**: `341876425553` (OneSignal's AWS account)
    * **External ID**: The ID shown in OneSignal (appears after initial connection attempt)
    * **Permissions**: The IAM policy created above
  </Step>

  <Step title="Complete the connection">
    Enter the Role ARN in OneSignal and test the connection.
  </Step>
</Steps>

***

## Event Data Mapping

Once connected, you'll need to map your Athena tables to OneSignal custom event fields:

<Steps>
  <Step title="Select event tables">
    Choose the tables or views containing your event data that you want to sync to OneSignal.
  </Step>

  <Step title="Map required event fields">
    Map the required fields for custom events:

    * **Event Name**: Column containing the event type (e.g., "purchase", "signup")
    * **User Identifier**: External User ID, Email, or Phone Number column
    * **Event Timestamp**: When the event occurred (optional)
  </Step>

  <Step title="Map event payload data">
    Map additional columns to event payload properties:

    * Custom event properties (product\_id, price, category, etc.)
    * Contextual data (source, campaign, etc.)
    * Behavioral metrics (value, quantity, etc.)
  </Step>

  <Step title="Configure sync settings">
    Set your event processing frequency and delivery preferences.
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

***

## Limitations

* **Query Performance**: Athena charges per query and data scanned - optimize your event tables
* **S3 Dependencies**: Requires properly configured S3 buckets and Glue catalog
* **Data Freshness**: Event sync frequency depends on how often your S3 data is updated

***

## FAQ

### What happens if my Athena queries fail?

OneSignal will log query errors and retry failed queries. Check your IAM permissions and S3 bucket access if you encounter persistent failures.

### How often does OneSignal sync events?

OneSignal checks for new events based on your configured sync frequency, with a minimum interval of 15 minutes.

***

## Need help?

Contact our support team at `support@onesignal.com` or use the in-app chat for assistance with your Athena integration setup.


# Amazon Redshift
Source: https://documentation.onesignal.com/docs/en/amazon-redshift

Sync custom events from Amazon Redshift to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Amazon Redshift integration enables syncing of custom events from your Redshift data warehouse to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

Amazon Redshift is a fully managed, petabyte-scale data warehouse service that makes it cost-effective to analyze large volumes of data using your existing business intelligence tools.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Amazon Redshift

* **Redshift cluster** with network access
* **Database user** with appropriate permissions
* **Event tables** containing structured behavioral data
* **Network connectivity** from OneSignal to your Redshift cluster

***

## Setup

<Steps>
  <Step title="Create dedicated user for OneSignal">
    Create a dedicated user account with appropriate permissions:

    ```sql theme={null}
    -- Create OneSignal user with strong password
    CREATE USER CENSUS WITH PASSWORD '<strong-unique-password>';

    -- Create private bookkeeping schema for sync state (skip if read-only mode)
    CREATE SCHEMA CENSUS;

    -- Grant full access to bookkeeping schema (skip if read-only mode)
    GRANT ALL ON SCHEMA CENSUS TO CENSUS;

    -- Ensure access to existing objects in bookkeeping schema (skip if read-only mode)
    GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA CENSUS TO CENSUS;
    ```
  </Step>

  <Step title="Grant permissions to event data">
    Provide read access to schemas containing your event data:

    ```sql theme={null}
    -- Grant schema access (repeat for each schema with event data)
    GRANT USAGE ON SCHEMA "<your_schema>" TO CENSUS;

    -- Grant read access to existing tables
    GRANT SELECT ON ALL TABLES IN SCHEMA "<your_schema>" TO CENSUS;

    -- Grant read access to future tables
    ALTER DEFAULT PRIVILEGES IN SCHEMA "<your_schema>" GRANT SELECT ON TABLES TO CENSUS;

    -- Grant execute permissions on functions
    GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA "<your_schema>" TO CENSUS;
    ALTER DEFAULT PRIVILEGES IN SCHEMA "<your_schema>" GRANT EXECUTE ON FUNCTIONS TO CENSUS;
    ```
  </Step>

  <Step title="Configure network access">
    Add OneSignal's IP addresses to your Redshift security groups. Redshift prevents external access by default.

    You can find OneSignal's IP addresses for your region in the integration settings. For more information, visit the AWS Redshift Help Center.
  </Step>

  <Step title="Connect to OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    1. Select **Amazon Redshift** from the list
    2. Enter your connection details:
       * **Host:** Your Redshift cluster endpoint
       * **Port:** Usually 5439
       * **Database:** Your database name
       * **Username:** `CENSUS`
       * **Password:** The password you created
    3. Test the connection
    4. Configure which tables contain your event data
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Table Schema

```sql theme={null}
-- Example Redshift event table
CREATE TABLE analytics.user_events (
    event_id BIGINT IDENTITY(1,1),
    event_name VARCHAR(100) NOT NULL,
    user_id VARCHAR(255) NOT NULL,
    event_timestamp TIMESTAMP DEFAULT GETDATE(),
    event_data SUPER,
    session_id VARCHAR(255),
    created_at TIMESTAMP DEFAULT GETDATE()
)
DISTKEY(user_id)
SORTKEY(event_timestamp);
```

### SQL Query Mode

Write custom SQL queries to transform your event data:

```sql theme={null}
-- Example: Recent high-value events
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_data
FROM analytics.user_events
WHERE event_timestamp >= DATEADD(day, -7, GETDATE())
    AND JSON_EXTRACT_PATH_TEXT(event_data, 'value')::NUMERIC > 100
ORDER BY event_timestamp DESC;
```

***

## dbt Integration

If you're using dbt with Redshift, ensure OneSignal retains access after each dbt run:

### Option 1: Fine-grained Permissions

Add post-hooks in your dbt project to grant access after each model builds:

```sql theme={null}
-- In your dbt model
{{ config(
    post_hook="GRANT SELECT ON {{ this }} TO CENSUS"
) }}
```

### Option 2: Default Privileges (Recommended)

Grant default permissions for your dbt production user:

```sql theme={null}
-- Must be run by Redshift superuser
ALTER DEFAULT PRIVILEGES FOR USER "<your_dbt_run_user>"
IN SCHEMA "<your_dbt_target_schema>"
GRANT SELECT ON TABLES TO CENSUS;
```

***

## Advanced Network Configuration

### SSH Tunnel Setup

For Redshift clusters on private networks:

1. **Create SSH user**: Set up a dedicated user on your SSH host
2. **Configure tunnel**: Enable "Use SSH Tunnel" in OneSignal integration settings
3. **Install keypair**: Add OneSignal's public key to `~/.ssh/authorized_keys`
4. **Test connection**: Verify tunnel connectivity

### VPC Deployment

For Redshift within AWS VPC:

OneSignal uses the `UNLOAD` command for efficient bulk data extraction. VPC deployments require an **S3 VPC Endpoint** to allow Redshift to communicate with S3.

**Setup S3 VPC Endpoint:**

1. Navigate to VPC service in AWS Console
2. Create VPC Endpoint for S3 service
3. Associate with your Redshift subnet
4. Configure routing tables

***

## Performance Optimization

### Distribution and Sort Keys

Optimize your event tables for analytics workloads:

```sql theme={null}
-- Distribute by user_id for user-centric queries
CREATE TABLE analytics.user_events (
    -- columns
)
DISTKEY(user_id)
SORTKEY(event_timestamp, event_name);
```

### Columnar Storage

Take advantage of Redshift's columnar storage for analytics:

* **Compression**: Redshift automatically compresses columns
* **Zone Maps**: Improve query performance with sorted data
* **Column-oriented**: Efficient for analytical queries on event data

***

## Limitations

* Multiple schemas require separate permission grants
* Views referencing cross-schema tables need additional permissions
* Complex stored procedure access may require additional setup
* VPC deployments require S3 VPC Endpoint configuration

***

## FAQ

### How does OneSignal handle large event datasets?

OneSignal uses Redshift's `UNLOAD` command for efficient bulk data extraction, which is optimized for large-scale analytics workloads.

### Can I use read-only mode?

Yes, you can skip the bookkeeping schema creation and use read-only mode if you prefer simpler setup and can't allow OneSignal to create tables.

### What about dbt compatibility?

OneSignal provides specific dbt integration patterns to ensure permissions are maintained after dbt runs. Use post-hooks or default privileges depending on your setup.


# Amplitude
Source: https://documentation.onesignal.com/docs/en/amplitude

Integrate OneSignal with Amplitude to sync behavioral cohorts, track message events, and target Users across push, email, SMS, and in-app channels.

Integrate OneSignal with [Amplitude](https://amplitude.com) to enable real-time, behavior-based targeting across push, in-app, email, and SMS. This app-level integration supports three data flows:

* **Message events → Amplitude**: Track delivery, clicks, failures, and more for all channels.
* **Custom events → OneSignal**: Send Amplitude events into OneSignal to trigger Journeys or Segments.
* **Cohorts → OneSignal**: Sync behavior-based Amplitude cohorts as targeting filters in OneSignal.

***

## Requirements

* [Amplitude Account](https://amplitude.com/pricing)
* [OneSignal Paid Plan](https://onesignal.com/pricing)
* OneSignal app with [Users](./users) and External ID set.

<Warning>
  This integration does not create Users. It maps Users in Amplitude to existing Users in OneSignal by matching identifiers.
</Warning>

***

## Setup

### Add Amplitude to OneSignal (Outbound)

Sends OneSignal message events into your Amplitude project.

1. In OneSignal, navigate to **Data > Integrations > Catalog** and select **Amplitude**.
2. Click **Settings**, then open the **Outbound** tab.
3. Enter your Amplitude API token, select the message events you want to send, and click **Save**.

#### In Amplitude

1. Find your project API Key then copy-paste it into OneSignal.
2. If using Amplitude's EU servers, check **Send events exclusively to Amplitude's EU Residency Endpoint**. You can verify this by your Amplitude URL. If you see `eu.amplitude.com` then you are using Amplitude's EU servers.

### Add OneSignal to Amplitude (Inbound)

In your Amplitude Destinations, search for **OneSignal**.

<Frame>
  <img alt="Amplitude destinations catalog with OneSignal selected" />
</Frame>

Amplitude provides two OneSignal destination types in the catalog:

* **Cohorts**: Sync cohorts from Amplitude to OneSignal.
* **Events User Properties**: Send custom events from Amplitude to OneSignal.

<Note>
  If you plan to use both cohort syncing and custom events, add both OneSignal destinations. Each destination is configured separately in Amplitude, so you will enter your OneSignal credentials for each one.
</Note>

### User ID mapping

The **[External ID](./users)** in OneSignal must match the Amplitude user property you select (e.g., `user_id`). Verify this property is populated in both systems — cohort syncing and event tracking depend on an exact match.

#### Additional properties

You can include extra properties that will be attached to [custom events](./custom-events) in OneSignal. This is useful for conditional event processing.

<Check>
  Click **Save** when finished. You should now be able to export cohorts and custom events from Amplitude to OneSignal and collect message events from OneSignal to Amplitude.
</Check>

***

## Testing custom events

1. In the Amplitude > OneSignal Events Destination, click the Test Connection button.

<Frame>
  <img alt="Amplitude Events destination page with Test Connection button highlighted" />
</Frame>

2. Make sure the `"user_id"` in the payload is set to an existing User’s External ID in your OneSignal App.
3. Click the **Send Test Event** button.
4. The Response box should remain empty and you should see `"OneSignal has successfully received test event."`

<Frame>
  <img alt="Successful test event response showing confirmation message" />
</Frame>

5. In OneSignal, navigate to **Data > Custom Events** and verify the test event appears in the list.

<Frame>
  <img alt="OneSignal Custom Events list showing the test event from Amplitude" />
</Frame>

<Warning>
  If the test fails or the event does not appear in OneSignal, verify that your OneSignal App ID and REST API key are entered correctly in Amplitude, your app is configured for [custom events](./custom-events), and the `"user_id"` matches an existing User’s External ID in your OneSignal App.
</Warning>

## Export Amplitude cohorts to OneSignal

Sync Amplitude cohorts to OneSignal using the matching External ID configured above. Exporting **does not create Users** — each User must already exist in OneSignal.

1. In Amplitude, create a cohort. See [Amplitude's docs on cohorts](https://amplitude.com/docs/analytics/behavioral-cohorts).
2. Click **Sync** and choose **OneSignal** as the destination.
3. Choose sync frequency.

<Frame>
  <img alt="Amplitude cohort sync settings showing frequency options for OneSignal destination" />
</Frame>

### OneSignal Segment creation

The synced cohort appears as an **Amplitude Segment filter**. OneSignal automatically creates a Segment for the cohort if:

* The Users in the Amplitude cohort also exist in OneSignal with a matching External ID.
* You have not exceeded your Segment limit in OneSignal.

<Frame>
  <img alt="OneSignal Segment builder using Amplitude Cohort filter" />
</Frame>

***

## Track message events in Amplitude

OneSignal sends the following message events to Amplitude in real time. Select which events to send in **Data > Integrations > Amplitude > Outbound**.

| Message Event Kind (OneSignal) | Message Event Name (Amplitude)                                | Event Description                                                                      |
| ------------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Push Sent                      | \[Onesignal] Push Delivered                                   | Push notification successfully sent.                                                   |
| Push Received                  | \[Onesignal] Push confirmed receipt                           | Push notification successfully received                                                |
| Push Clicked                   | \[Onesignal] Push Clicked                                     | Push notification touched on device                                                    |
| Push Failed                    | \[Onesignal] Push Failed                                      | Push failed to be sent. Check the failed message report in OneSignal.                  |
| Push Unsubscribed              | \[Onesignal] Push Unsubscribed                                | The [Subscription](./subscriptions) unsubscribed from push.                            |
| In-App Impression              | \[Onesignal] IAM Displayed                                    | In-App Message successfully displayed on device                                        |
| In-App Clicked                 | \[Onesignal] IAM Clicked                                      | In-App Message clicked on device                                                       |
| In-App Page Displayed          | \[Onesignal] IAM Page Displayed                               | In-App Message page is displayed                                                       |
| Email Sent                     | \[Onesignal] Email Delivered                                  | Email successfully sent                                                                |
| Email Received                 | \[Onesignal] Email confirmed receipt                          | Email received by recipient                                                            |
| Email Opened                   | \[Onesignal] Email Opened                                     | Email opened by recipient                                                              |
| Email Link Clicked             | \[Onesignal] Email Clicked                                    | Email link clicked on                                                                  |
| Email Unsubscribed             | \[Onesignal] Email Unsubscribed                               | Email unsubscribed by recipient                                                        |
| Email Reported As Spam         | \[Onesignal] Email Reported as SPAM                           | Email reported as spam by recipient                                                    |
| Email Bounced                  | \[Onesignal] Email Hard bounced                               | Email returned to sender due to permanent error                                        |
| Email Failed                   | \[Onesignal] Email Failed delivery                            | Could not deliver the email to the recipient's inbox                                   |
| Email Suppressed               | \[Onesignal] Email Not delivering to suppressed email address | Email not delivered as the recipient had suppressed the email address it was sent from |
| SMS Sent                       | \[Onesignal] SMS Delivered                                    | SMS sent to recipient                                                                  |
| SMS Failed                     | \[Onesignal] SMS Failed delivery                              | SMS failed to send                                                                     |
| SMS Delivered                  | \[Onesignal] SMS confirmed receipt                            | SMS successfully delivered                                                             |
| SMS Undelivered                | \[Onesignal] SMS Failed delivery                              | The SMS could not be sent.                                                             |

### Event properties

Every event sent from OneSignal to Amplitude includes these properties:

| PROPERTY NAME        | DESCRIPTION                                             |
| -------------------- | ------------------------------------------------------- |
| **Distinct ID**      | The external\_id associated with the message            |
| **Message ID**       | The identifier of the discrete message                  |
| **Message Name**     | The message name                                        |
| **Message Title**    | The message title                                       |
| **Message Contents** | The message contents                                    |
| **message\_type**    | The type of message sent, push, in-app, email, SMS      |
| **template\_id**     | The message template used (API and Journey Messages)    |
| **subscription\_id** | The OneSignal set device/email/sms identifier           |
| **device\_type**     | The device type that received the message               |
| **language**         | The two-character language code of the device           |
| **source**           | `onesignal` (is indicated as the source for all events) |

<Warning>
  Delivery counts may differ between Amplitude and OneSignal. See [Why doesn't delivery data match?](#why-doesnt-delivery-data-match) for details.
</Warning>

***

## FAQ

### Why isn't my Amplitude cohort showing up in OneSignal?

If a synced cohort is not appearing as a Segment in OneSignal, work through the following:

* **Wrong destination type.** Cohorts require the **Cohorts** destination in Amplitude. The **Events User Properties** destination is for custom events only. Verify you are using the correct destination.
* **Sync not complete.** Check the sync history in your Amplitude Cohorts destination to confirm the export completed. Syncs can take several minutes depending on cohort size.
* **No matching External IDs.** OneSignal only creates a Segment for users with a matching External ID in both systems. If no matches are found, the Segment will be empty or not created. See [User ID mapping](#user-id-mapping) for details.
* **Segment limit reached.** OneSignal enforces a Segment limit based on your plan. If you have reached the limit, new Segments from cohort syncs will not be created. Archive unused Segments to free up capacity.

If the Segment appears but counts look off, see [Why don't my cohort and segment counts match?](#why-dont-my-cohort-and-segment-counts-match).

### Why don't my cohort and segment counts match?

1. **Missing or mismatched External IDs**
   Only Users with a matching OneSignal External ID and Amplitude User ID are included. This integration does not create Users or Subscriptions.

2. **Unsubscribed Users**
   OneSignal Segments only display the count for subscribed [Subscriptions](./subscriptions). Unsubscribed Subscriptions are available for Journeys or In-App Messages.

For example, if an Amplitude cohort has 10 users but the OneSignal segment shows 8 Subscriptions, the 2 missing Users may:

* Not exist in OneSignal or have an incorrect External ID.
* Have unsubscribed Subscriptions.

To verify, check the **Audience > Users** tab in OneSignal to see if the Users exist and have active Subscriptions.

### Do unsubscribed Users sync from Amplitude?

Yes, but they are excluded from the OneSignal segment counts at this time. You can still message them via Journeys or In-App Messages if they have other [Subscriptions](./subscriptions) or their Subscription type supports it.

### Why doesn't delivery data match?

A single user may have multiple [Subscriptions](./subscriptions) (push devices, email addresses, phone numbers). Each Subscription generates its own delivery event. For example:

* 1 user = 2 Android + 1 iOS + 2 Web = 5 push Subscriptions
* 1 push message = up to 5 sent/received/clicked events

Use the `subscription_id` in event properties to trace the exact source.

To troubleshoot missing events:

* Ensure `OneSignal.login` is called whenever a user is identified to set the External ID.
* Verify that `OneSignal.logout` isn't removing the External ID.
* Check API requests or CSV uploads that may alter the External ID.

### How can we send user/subscription events?

User and subscription-level events (e.g., permission granted, user login/logout) are not automatically sent.

The OneSignal SDK has event listeners that can be used to track these events for you to send to Amplitude:

* User State Observer: [Mobile SDK](./mobile-sdk-reference#addobserver-user-state), [Web SDK](./web-sdk-reference#addeventlistener-user-state)
* Permission Observer: [Mobile SDK](./mobile-sdk-reference#addpermissionobserver-push), [Web SDK](./web-sdk-reference#permissionchange)

### Why is the OneSignal Subscription ID added to Amplitude as a device\_id?

Amplitude expects a `device_id` for deduplication. OneSignal uses `subscription_id` for this, which maps into `device_id` automatically.

See [Amplitude's docs](https://amplitude.com/docs/apis/analytics/http-v2#event-deduplication) for more information.

***

## Related pages

<Columns>
  <Card title="Analytics overview" icon="chart-line" href="./analytics-overview">
    Overview of OneSignal analytics, delivery metrics, and event tracking.
  </Card>

  <Card title="Custom events" icon="bolt" href="./custom-events">
    Track User actions to trigger Journeys, personalization, and power analytics.
  </Card>
</Columns>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# Metrics glossary
Source: https://documentation.onesignal.com/docs/en/analytics-metrics-glossary

Understand the nuances between metric labels for each message channel across the OneSignal ecosystem to accurately interpret messaging performance.

## Overview

OneSignal records metrics at each step of a message's lifecycle — from when OneSignal hands the message to a third-party provider (FCM, APNs, Twilio, or an email ESP) through delivery, engagement, and any follow-up events. In-app messages and Live Activities have different lifecycles, which are covered in their own sections below.

Use this page to reconcile numbers across the dashboard, API, CSV exports, and Event Streams, or when building internal reports.

Each channel section contains:

1. **Terms**: the glossary of metrics and their definitions.
2. **Delivery lifecycle**: a visual representation of where each metric is captured.
3. **Metrics mapping**: the name of each metric across every OneSignal surface (dashboard, API, CSV, Event Streams).

In the mapping tables, **columns are surfaces** (where the metric appears) and **rows are concepts** (what the metric represents).

### Channel metrics comparison

Different channels have different delivery states and engagement metrics. The table below lists which metrics apply to each channel.

|    Channel    | Sent | Delivered | Failed | Rejected | Remaining | Clicked | Opened | Bounced | Confirmed Receipt | Read | Impressions | Unsubscribed | Reported as Spam | Suppressed | Frequency Capped |
| :-----------: | :--: | :-------: | :----: | :------: | :-------: | :-----: | :----: | :-----: | :---------------: | :--: | :---------: | :----------: | :--------------: | :--------: | :--------------: |
|      Push     |   ✅  |     ✅     |    ✅   |     ❌    |     ✅     |    ✅    |    ❌   |    ❌    |         ✅         |   ❌  |      ❌      |       ✅      |         ❌        |      ❌     |         ✅        |
|     Email     |   ✅  |     ✅     |    ✅   |     ❌    |     ✅     |    ✅    |    ✅   |    ✅    |         ❌         |   ❌  |      ❌      |       ✅      |         ✅        |      ✅     |         ❌        |
|    SMS/RCS    |   ✅  |     ✅     |    ✅   |     ✅    |     ✅     |    ✅    |    ❌   |    ❌    |         ❌         |   ✅  |      ❌      |       ❌      |         ❌        |      ✅     |         ❌        |
|     In-app    |   ❌  |     ❌     |    ✅   |     ❌    |     ❌     |    ✅    |    ❌   |    ❌    |         ❌         |   ❌  |      ✅      |       ❌      |         ❌        |      ❌     |         ❌        |
| Live Activity |   ✅  |     ✅     |    ✅   |     ❌    |     ❌     |    ✅    |    ❌   |    ❌    |         ✅         |   ❌  |      ❌      |       ✅      |         ❌        |      ❌     |         ❌        |

* Some metrics have both **Total** and **Unique** variants in the per-channel tables. This applies to Opens (email) and Clicks (email, SMS/RCS, in-app).

## Push terms

| Metric                | Definition                                                                                                                                                                                                                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Sent**              | The number of push notifications sent from OneSignal, including both those successfully sent to the push provider and failures. This is a composite metric.                                                                                                                                            |
| **Audience**          | The number of Subscriptions in the targeted Segment(s).                                                                                                                                                                                                                                                |
| **Remaining**         | The number of Subscriptions in the target audience that haven't yet received the push notification (queued or in flight). Appears on the dashboard delivery report.                                                                                                                                    |
| **Delivered**         | The number of push notifications successfully sent to and accepted by the push provider (FCM, APNs, HMS).                                                                                                                                                                                              |
| **Confirmed Receipt** | The number of push notifications confirmed as received by the device, verified by the OneSignal SDK. See [Confirmed receipt](/docs/en/confirmed-delivery) for platform-specific details and requirements.                                                                                              |
| **Unsubscribed**      | The number of push Subscriptions that did not receive the push notification because they uninstalled the app, cleared browser data, or opted out of push and have not opened the app since. OneSignal will **not** attempt to send to these Subscriptions in future messages unless they re-subscribe. |
| **Failed**            | The number of push Subscriptions that did not receive the push notification because of an error. OneSignal will attempt to send to these Subscriptions in future messages.                                                                                                                             |
| **Clicked**           | The number of push Subscriptions that clicked the push notification. Push notifications can only be clicked once.                                                                                                                                                                                      |
| **Frequency Capped**  | The number of push Subscriptions that did not receive the push notification due to frequency cap settings.                                                                                                                                                                                             |

### Push lifecycle

```mermaid theme={null}
sequenceDiagram
    participant OneSignal
    participant Provider
    participant Platform
    participant User

    %% -----------------------------
    %% Metrics when sending to provider
    %% -----------------------------
    Note over OneSignal,User: Metrics when sending to provider

    OneSignal--xProvider: Excluded from delivery [Frequency Capped]
    Note left of OneSignal: Messages excluded before delivery

    OneSignal-->>Provider: Send notification
    Provider-->>OneSignal: Error response [Failed / Unsubscribed]
    Note left of OneSignal: Failed to send to provider

    %% -----------------------------
    %% Metrics reported by push provider
    %% -----------------------------
    Note over OneSignal,User: Metrics reported by push provider

    OneSignal->>Provider: Send notification
    Provider->>OneSignal: Provider accepted [Delivered]
    Note left of OneSignal: Successfully sent to provider

    Provider->>Platform: Deliver notification
    Provider->>OneSignal: Delivery reported [Delivered]
    Note left of OneSignal: Provider reported delivery

    %% -----------------------------
    %% Metrics reported by SDK
    %% -----------------------------
    Note over OneSignal,User: Metrics reported by SDK

    Platform->>User: Notification shown
    Platform->>OneSignal: SDK confirms receipt [Confirmed Receipt]
    Note left of OneSignal: Device-level confirmation
    User->>OneSignal: Engagement event [Clicked]
    Note left of OneSignal: User engagement
```

### Push metrics mapping

#### Dashboard

| Term              | Delivery Report Stat Cards | Delivery Report Timeseries Chart | Journey Node Report Stat Card | Journey Node Report Timeseries Chart | Audience Activity | Engagement Trends |
| ----------------- | -------------------------- | -------------------------------- | ----------------------------- | ------------------------------------ | ----------------- | ----------------- |
| Sent              | Sent                       | ❌                                | Sent                          | Sent                                 | ❌                 | ❌                 |
| Audience          | Audience                   | ❌                                | ❌                             | ❌                                    | ❌                 | ❌                 |
| Delivered         | Delivered                  | Delivered                        | Delivered                     | Delivered                            | Delivered         | Delivered         |
| Confirmed Receipt | Confirmed Receipt          | Confirmed Receipt                | Confirmed Receipt             | Confirmed Receipt                    | Confirmed receipt | ❌                 |
| Unsubscribed      | Unsubscribed               | ❌                                | Unsubscribed                  | Unsubscribed                         | Unsubscribed      | Unsubscribed      |
| Failed            | Failed                     | ❌                                | Failed                        | Failed                               | Failed            | ❌                 |
| Clicked           | Clicked                    | Clicks                           | ❌                             | Clicked                              | Clicked           | Clicked           |
| Influenced Opens  | ❌                          | ❌                                | ❌                             | ❌                                    | ❌                 | ❌                 |
| Frequency Capped  | Capped                     | ❌                                | Capped                        | Capped                               | ❌                 | ❌                 |

#### API, CSV, and Event Streams

| Term              | View Message(s) API<sup>1</sup> | Notifications CSV   | Event Streams             |
| ----------------- | ------------------------------- | ------------------- | ------------------------- |
| Sent              | ❌<sup>2</sup>                   | sent                | ❌                         |
| Audience          | ❌                               | ❌                   | ❌                         |
| Delivered         | successful                      | delivered           | message.push.sent         |
| Confirmed Receipt | received                        | confirmed\_receipt  | message.push.received     |
| Unsubscribed      | failed<sup>3</sup>              | failed<sup>3</sup>  | message.push.unsubscribed |
| Failed            | errored<sup>3</sup>             | errored<sup>3</sup> | message.push.failed       |
| Clicked           | converted                       | converted           | message.push.clicked      |
| Influenced Opens  | influenced\_opens               | ❌                   | ❌                         |
| Frequency Capped  | frequency\_capped               | frequency\_capped   | ❌                         |

<sup>1</sup> The API also includes per-platform metrics for all fields except `remaining` (for example, `ios_clicked`, `android_clicked`).

<sup>2</sup> The composite Sent metric does not have a direct field in the View Message(s) API. To derive it, sum `successful` + `failed` + `errored`. Audience activity exports also do not include a Sent field.

<sup>3</sup> In the View Message(s) API and Notifications CSV, the field name `failed` represents **unsubscribed** subscriptions and `errored` represents **delivery errors** (what the dashboard calls Failed). This naming is preserved for backward compatibility.

## Email terms

| Metric               | Definition                                                                                                                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sent**             | The number of emails sent from OneSignal, including both those successfully sent to the email service provider and failures. This is a composite metric.                                                                              |
| **Audience**         | The number of Subscriptions in the targeted Segment(s).                                                                                                                                                                               |
| **Remaining**        | The number of Subscriptions in the target audience that haven't yet received the email (queued or in flight). Appears on the dashboard delivery report.                                                                               |
| **Delivered**        | The number of emails successfully delivered to the recipient's inbox server.                                                                                                                                                          |
| **Failed**           | The number of emails unable to be delivered to the inbox, excluding bounces. May include failures reported by the ESP or OneSignal delivery failures.                                                                                 |
| **Suppressed**       | The number of emails blocked due to prior bounces or spam reports to protect sender reputation. Only recorded for apps configured to use OneSignal email.                                                                             |
| **Bounced**          | The number of emails rejected due to invalid addresses, full inboxes, sender reputation, or DMARC issues. These addresses are added to a [Suppression List](/docs/en/suppressions), either managed by OneSignal or a third party ESP. |
| **Reported as Spam** | The number of recipients who marked the email as spam. These addresses are added to a [Suppression List](/docs/en/suppressions), either managed by OneSignal or a third party ESP.                                                    |
| **Unsubscribed**     | The number of recipients who opted out of receiving emails.                                                                                                                                                                           |
| **Total Opens**      | The total number of times the email was opened, including repeats.                                                                                                                                                                    |
| **Total Clicks**     | The total number of times a link in the email was clicked, including repeats.                                                                                                                                                         |
| **Unique Opens**     | The number of individual Subscriptions who opened the email. Used with Delivered to calculate the open rate.                                                                                                                          |
| **Unique Clicks**    | The number of individual Subscriptions who clicked a link in the email. Used with Delivered to calculate the click rate.                                                                                                              |

**Total vs Unique clicks and opens**

Unique clicks and opens are counted once per Subscription, regardless of how many times that user opens or clicks the same email. Total clicks and opens count every interaction, including repeats from the same user.

### Email lifecycle

```mermaid theme={null}
sequenceDiagram
    participant OneSignal
    participant ESP
    participant Inbox
    participant User

    %% -----------------------------
    %% Metrics when sending to ESP
    %% -----------------------------
    Note over OneSignal,User: Metrics when sending to ESP

    OneSignal--xESP: Excluded from delivery [Suppressed]
    Note left of OneSignal: Messages excluded before delivery

    OneSignal-->>ESP: Send email
    ESP-->>OneSignal: Error response [Failed]
    Note left of OneSignal: Failed to send to ESP

    %% -----------------------------
    %% Metrics reported by ESP
    %% -----------------------------
    Note over OneSignal,User: Metrics reported by ESP

    OneSignal->>ESP: Send email
    ESP->>OneSignal: ESP accepted
    Note left of OneSignal: Successfully delivered to ESP

    ESP-->>Inbox: Attempt delivery to inbox
    Inbox-->>OneSignal: Failed to deliver [Failed / Bounced]
    Note left of OneSignal: Failed to deliver to Inbox

    ESP->>Inbox: Deliver email
    Inbox->>OneSignal: confirmed receipt to inbox [Delivered]
    Note left of OneSignal: Successfully delivered to Inbox

    %% -----------------------------
    %% Metrics reported by User
    %% -----------------------------
    Note over OneSignal,User: Metrics reported by User
    %% Metrics reported to ESP then OS

    Inbox->>User: Email shown
    User->>OneSignal: Engagement event [Opened / Clicked / Unsubscribed / Reported as Spam]
    Note left of OneSignal: User engagement
```

### Email metrics mapping

#### Dashboard

| Term                         | Delivery Report Stat Cards | Delivery Report Timeseries Chart | Journey Node Report Stat Card | Journey Node Report Timeseries Chart | Audience Activity | Engagement Trends |
| ---------------------------- | -------------------------- | -------------------------------- | ----------------------------- | ------------------------------------ | ----------------- | ----------------- |
| Sent                         | Sent                       | Sent                             | ❌                             | Sent                                 | ❌                 | ❌                 |
| Audience                     | Audience                   | ❌                                | ❌                             | ❌                                    | ❌                 | ❌                 |
| Delivered                    | Delivered                  | Delivered                        | Delivered                     | Delivered                            | Delivered         | Delivered         |
| Failed                       | Failed                     | Failed                           | Failed                        | Failed                               | Failed            | ❌                 |
| Suppressed                   | Suppressed                 | Suppressed                       | Suppressed                    | Suppressed                           | Suppressed        | ❌                 |
| Bounced                      | Bounced                    | Bounced                          | Bounced                       | Bounced                              | Bounced           | ❌                 |
| Reported as Spam<sup>1</sup> | Reported as Spam           | Spam                             | Reported as Spam              | Spam                                 | Complained        | ❌                 |
| Unsubscribed                 | Unsubscribed               | Unsubscribed                     | Unsubscribed                  | Unsubscribed                         | Unsubscribed      | Unsubscribed      |
| Total Opens                  | Total Opens                | Total Opens                      | Total Opens                   | Total Opens                          | ❌                 | ❌                 |
| Total Clicks                 | Total Clicks               | Total Clicks                     | Total Clicks                  | Total Clicks                         | ❌                 | ❌                 |
| Unique Opens                 | Unique Opens               | Unique Opens                     | Unique Opens                  | Unique Opens                         | Opened            | Opened            |
| Unique Clicks                | Unique Clicks              | Unique Clicks                    | Unique Clicks                 | Unique Clicks                        | Clicked           | Clicked           |

<sup>1</sup> The dashboard uses different labels for the same metric across surfaces: **Reported as Spam** (stat cards, Journey stat cards), **Spam** (timeseries charts), and **Complained** (Audience Activity). All refer to recipients who marked the message as spam or junk.

#### API, CSV, and Event Streams

| Term             | View Message(s) API                            | Notifications CSV     | Event Streams                    |
| ---------------- | ---------------------------------------------- | --------------------- | -------------------------------- |
| Sent             | platform\_delivery\_stats.email.successful     | ❌                     | message.email.sent               |
| Audience         | ❌                                              | ❌                     | ❌                                |
| Delivered        | platform\_delivery\_stats.email.received       | email\_delivered      | message.email.received           |
| Failed           | platform\_delivery\_stats.email.failed         | email\_failed         | message.email.failed             |
| Suppressed       | platform\_delivery\_stats.email.suppressed     | ❌                     | message.email.suppressed         |
| Bounced          | platform\_delivery\_stats.email.bounced        | email\_bounced        | message.email.bounced            |
| Reported as Spam | platform\_delivery\_stats.email.reported\_spam | email\_reported\_spam | message.email.reported\_as\_spam |
| Unsubscribed     | platform\_delivery\_stats.email.unsubscribed   | email\_unsubscribed   | message.email.unsubscribed       |
| Total Opens      | platform\_delivery\_stats.email.opened         | email\_opened         | message.email.opened             |
| Total Clicks     | platform\_delivery\_stats.email.clicked        | email\_clicked        | message.email.clicked            |
| Unique Opens     | platform\_delivery\_stats.email.unique\_opens  | email\_unique\_opens  | ❌                                |
| Unique Clicks    | platform\_delivery\_stats.email.unique\_clicks | email\_unique\_clicks | ❌                                |

## SMS/RCS terms

| Metric                   | Definition                                                                                                                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sent**                 | The number of messages sent from OneSignal, including both those successfully sent to Twilio and failures. This is a composite metric.                                                                                    |
| **Audience**             | The number of Subscriptions in the targeted Segment(s).                                                                                                                                                                   |
| **Remaining**            | The number of Subscriptions in the target audience that haven't yet received the message (queued or in flight). Appears on the dashboard delivery report.                                                                 |
| **Delivered**            | The number of messages successfully delivered to the carrier as reported by Twilio. Metrics are categorized further to distinguish between SMS/MMS and RCS.                                                               |
| **Failed**               | The number of messages that failed to be sent to Twilio.                                                                                                                                                                  |
| **Suppressed**           | The number of messages not sent to the Subscriptions because they opted out of receiving messages from the sender.                                                                                                        |
| **Rejected**             | The number of messages not delivered by the carrier due to number blockage, velocity blockage, or the recipient is on a block list. This is a **derived** metric and is the sum of provider errors and provider failures. |
| **Provider Errored**     | The number of Subscriptions for which Twilio failed to send the message.                                                                                                                                                  |
| **Provider Undelivered** | The number of Subscriptions for which Twilio sent the message but failed to deliver it.                                                                                                                                   |
| **Read** *(RCS only)*    | The number of Subscriptions who read an RCS message.                                                                                                                                                                      |
| **Total Clicks**         | The total number of times a link in the message was clicked, including repeats.                                                                                                                                           |
| **Unique Clicks**        | The number of unique link clicks across all links in the message. Counted once per Subscription.                                                                                                                          |
| **Replied**              | The number of keywords received by OneSignal, excluding consent keywords.                                                                                                                                                 |
| **Unsubscribed**         | The number of opt-out keywords received by OneSignal.                                                                                                                                                                     |

### SMS/RCS lifecycle

```mermaid theme={null}
sequenceDiagram
    participant OneSignal
    participant Twilio
    participant Device
    participant User

    %% -----------------------------
    %% Metrics before message goes to provider
    %% -----------------------------
    Note over OneSignal,User: Metrics before message goes to provider

    OneSignal--xTwilio: Excluded from delivery [Suppressed]
    Note left of OneSignal: Messages excluded before delivery

    OneSignal-->>Twilio: Send SMS
    Twilio-->>OneSignal: Error response [Failed]
    Note left of OneSignal: Failed to send to provider

    %% -----------------------------
    %% Metrics reported by Twilio
    %% -----------------------------
    Note over OneSignal,User: Metrics reported by Twilio

    OneSignal->>Twilio: Send SMS
    Twilio->>OneSignal: Twilio accepted
    Note left of OneSignal: Successfully delivered to provider

    Twilio-->>Device: Attempt delivery to device
    Device-->>OneSignal: Failed to deliver to device [Rejected]
    Note left of OneSignal: Failed to deliver to device

    Twilio->>Device: Deliver SMS
    Device->>OneSignal: Delivery confirmation [Delivered]
    Note left of OneSignal: Successfully delivered to device

    %% -----------------------------
    %% Metrics reported by user
    %% -----------------------------
    Note over OneSignal,User: Metrics reported by user
    %% Metrics reported to Twilio then OS

    Device->>User: SMS displayed
    User->>OneSignal: Engagement event [Read (RCS) / Clicked]
    Note left of OneSignal: User engagement
```

### SMS/RCS metrics mapping

#### Dashboard

| Term                             | Delivery Report Stat Cards | Delivery Report Timeseries Chart | Journey Node Report Stat Card | Journey Node Report Timeseries Chart | Audience Activity | Engagement Trends  |
| -------------------------------- | -------------------------- | -------------------------------- | ----------------------------- | ------------------------------------ | ----------------- | ------------------ |
| Sent                             | Sent                       | Sent                             | Sent                          | Sent                                 | ❌                 | ❌                  |
| Audience                         | Audience                   | ❌                                | ❌                             | ❌                                    | ❌                 | ❌                  |
| Delivered                        | Delivered                  | Delivered                        | Delivered                     | Delivered                            | Delivered         | Delivered          |
| Failed<sup>1</sup>               | Failed                     | ❌                                | Failed                        | ❌                                    | Failed & Rejected | ❌                  |
| Suppressed                       | Suppressed                 | ❌                                | Suppressed                    | ❌                                    | Suppressed        | ❌                  |
| Rejected<sup>1</sup>             | Rejected                   | ❌                                | Rejected                      | ❌                                    | Failed & Rejected | ❌                  |
| Provider Errored<sup>2</sup>     | ❌                          | Failed (Errored)                 | ❌                             | Failed (Errored)                     | ❌                 | ❌                  |
| Provider Undelivered<sup>2</sup> | ❌                          | Failed (Undelivered)             | ❌                             | Failed (Undelivered)                 | ❌                 | ❌                  |
| Read                             | Read                       | Read                             | Read                          | Read                                 | Read              | Read               |
| Total Clicks                     | Total Clicks               | ❌                                | Total Clicks                  | ❌                                    | ❌                 | ❌                  |
| Unique Clicks                    | Unique Clicks              | ❌                                | Unique Clicks                 | ❌                                    | ❌                 | ❌                  |
| Replied                          | ❌                          | ❌                                | ❌                             | ❌                                    | ❌                 | Replied (keywords) |
| Unsubscribed                     | ❌                          | ❌                                | ❌                             | ❌                                    | ❌                 | Unsubscribed       |

<sup>1</sup> Audience Activity combines **Failed** and **Rejected** into a single **Failed & Rejected** bucket. Stat cards and Journey stat cards show them separately.

<sup>2</sup> Delivery Report timeseries charts break the provider-side failures into **Failed (Errored)** and **Failed (Undelivered)**, which map to Provider Errored and Provider Undelivered. Stat cards roll these up under **Failed**.

#### API, CSV, and Event Streams

| Term                 | View Message(s) API                                                                     | Notifications CSV           | Event Streams           |
| -------------------- | --------------------------------------------------------------------------------------- | --------------------------- | ----------------------- |
| Sent                 | platform\_delivery\_stats.sms.successful                                                | ❌                           | message.sms.sent        |
| Audience             | ❌                                                                                       | ❌                           | ❌                       |
| Delivered            | platform\_delivery\_stats.sms.provider\_successful                                      | ❌                           | message.sms.delivered   |
| Failed               | platform\_delivery\_stats.sms.failed, platform\_delivery\_stats.sms.errored<sup>3</sup> | failed, errored<sup>3</sup> | message.sms.failed      |
| Suppressed           | platform\_delivery\_stats.sms.suppressed                                                | ❌                           | ❌                       |
| Rejected             | ❌                                                                                       | ❌                           | ❌                       |
| Provider Errored     | platform\_delivery\_stats.sms.provider\_errored                                         | ❌                           | ❌                       |
| Provider Undelivered | platform\_delivery\_stats.sms.provider\_failed                                          | ❌                           | message.sms.undelivered |
| Read                 | ❌                                                                                       | ❌                           | ❌                       |
| Total Clicks         | ❌                                                                                       | ❌                           | ❌                       |
| Unique Clicks        | ❌                                                                                       | ❌                           | ❌                       |
| Replied              | ❌                                                                                       | ❌                           | ❌                       |
| Unsubscribed         | ❌                                                                                       | ❌                           | ❌                       |

<sup>3</sup> The sum of `failed` and `errored` — both recorded in OneSignal's internal system when attempting to send to Twilio — is surfaced as **Failed** in the dashboard.

## In-app terms

| Metric               | Definition                                                                                                                                                                                    |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Impression**       | The number of times an in-app message successfully displayed to a Subscription. Depending on your in-app settings, a single Subscription may register multiple impressions.                   |
| **Card Impressions** | The number of times a card within a carousel was displayed on a device. A carousel message will have multiple cards, but not all cards may be viewed by each user. Only applies to carousels. |
| **Total Clicks**     | The number of times a button block, image block, or background was clicked. It does not include the "Close Button" clicks.                                                                    |
| **Unique Clicks**    | The number of unique clicks across all buttons, images, and backgrounds in the message. Counted once per Subscription.                                                                        |

### In-app lifecycle

There is no delivery lifecycle to consider. All metrics captured for an in-app message are from the device through the OneSignal SDK.

### In-app metrics mapping

#### Dashboard

| Term             | Delivery Report Stat Cards | Journey Node Report Stat Card | Journey Node Report Timeseries Chart | Audience Activity | Engagement Trends |
| ---------------- | -------------------------- | ----------------------------- | ------------------------------------ | ----------------- | ----------------- |
| Impressions      | Impressions                | Impressions                   | Impressions                          | Impression        | Impressions       |
| Card Impressions | Card Impressions           | Card Impressions              | ❌                                    | ❌                 | ❌                 |
| Total Clicks     | Total Clicks<sup>1</sup>   | Total Clicks<sup>1</sup>      | ❌                                    | ❌                 | ❌                 |
| Unique Clicks    | ❌<sup>2</sup>              | ❌<sup>2</sup>                 | ❌                                    | Clicked           | Clicked           |

<sup>1</sup> We filter out "Close Button" clicks out of Total Clicks on the IAM Delivery
Report stat card.

<sup>2</sup> While we don't have a label on the dashboard for unique clicks, we show
unique clicks count alongside the CTR.

#### Event Streams

| Term             | Event Streams               |
| ---------------- | --------------------------- |
| Impressions      | message.iam.impression      |
| Card Impressions | message.iam.page\_displayed |
| Total Clicks     | message.iam.clicked         |
| Unique Clicks    | ❌                           |

## Live Activities terms

| Metric                | Definition                                                                                                                                                                                                                                                                       |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sent**              | The number of Live Activity updates sent from OneSignal, including both those successfully sent to the push provider (APNs) and failures. This is a composite metric.                                                                                                            |
| **Delivered**         | The number of Live Activity updates successfully sent to and accepted by the push provider (APNs).                                                                                                                                                                               |
| **Confirmed Receipt** | The number of Live Activity updates confirmed as received by the Subscriptions, verified by the OneSignal SDK. See [Confirmed receipt](/docs/en/confirmed-delivery) for platform-specific details and requirements.                                                              |
| **Unsubscribed**      | The number of push Subscriptions that did not receive the Live Activity update because they uninstalled the app, cleared browser data, or opted out of push and have not opened the app since. OneSignal will **not** attempt to send to these Subscriptions in future messages. |
| **Failed**            | The number of push Subscriptions that did not receive the Live Activity update because of an error. OneSignal will attempt to send to these Subscriptions in future messages.                                                                                                    |
| **Clicked**           | The number of clicks on a Live Activity update.                                                                                                                                                                                                                                  |

### Live Activities lifecycle

```mermaid theme={null}
sequenceDiagram
    participant OneSignal
    participant Provider
    participant Device
    participant User

    %% -----------------------------
    %% Metrics before message goes to provider
    %% -----------------------------
    Note over OneSignal,User: Metrics before message goes to provider

    Note left of OneSignal: Failed to send to provider
    OneSignal-->>Provider: Send live activity update
    Provider-->>OneSignal: Error response [Failed / Unsubscribed]

    %% -----------------------------
    %% Metrics reported by push provider
    %% -----------------------------
    Note over OneSignal,User: Metrics reported by push provider

    Note left of OneSignal: Successfully delivered to provider
    OneSignal->>Provider: Send live activity update
    Provider->>OneSignal: Provider accepted [Delivered]

    Note left of OneSignal: Successfully delivered to device
    Provider->>Device: Deliver live activity update

    %% -----------------------------
    %% Metrics reported by SDK
    %% -----------------------------
    Note over OneSignal,User: Metrics reported by SDK

    Device->>User: Live activity shown
    Device->>OneSignal: SDK confirms receipt [Confirmed Receipt]
    Note left of OneSignal: Device-level confirmation
    User->>OneSignal: Engagement event [Clicked]
    Note left of OneSignal: User engagement
```

### Live Activities metrics mapping

#### Dashboard

| Term              | Delivery Report Stat Cards | Audience Activity | Engagement Trends |
| ----------------- | -------------------------- | ----------------- | ----------------- |
| Sent              | Sent                       | ❌                 | ❌                 |
| Delivered         | Delivered                  | Delivered         | Delivered         |
| Confirmed Receipt | ❌                          | ❌                 | Confirmed Receipt |
| Failed            | Failed                     | Failed            | Failed            |
| Unsubscribed      | Unsubscribed               | Unsubscribed      | Unsubscribed      |
| Clicked           | Total clicks               | Clicked           | Clicked           |

#### API, CSV, and Event Streams

| Term              | View Message(s) API | Notifications CSV   | Event Streams                                |
| ----------------- | ------------------- | ------------------- | -------------------------------------------- |
| Sent              | ❌                   | ❌                   | ❌                                            |
| Delivered         | successful          | delivered           | message.live\_activity.sent<sup>1</sup>      |
| Confirmed Receipt | ❌                   | confirmed\_receipt  | message.live\_activity.delivered<sup>1</sup> |
| Failed            | errored<sup>2</sup> | errored<sup>2</sup> | message.live\_activity.failed                |
| Unsubscribed      | failed<sup>2</sup>  | failed<sup>2</sup>  | message.live\_activity.unsubscribed          |
| Clicked           | ❌                   | ❌                   | message.live\_activity.clicked               |

<sup>1</sup> The Event Streams names are shifted relative to the dashboard concepts: `message.live_activity.sent` maps to **Delivered** (accepted by APNs), and `message.live_activity.delivered` maps to **Confirmed Receipt** (acknowledged by the device). Wire report pipelines to the concept, not the literal event name.

<sup>2</sup> As with push, the View Message(s) API and CSV field `failed` represents **unsubscribed** subscriptions and `errored` represents **delivery errors** (Failed).

## FAQ

### Why don't my dashboard and API counts match for push?

The dashboard **Sent** metric is a composite — it equals Delivered + Unsubscribed + Failed. The View Message(s) API does not return a direct `sent` field; sum `successful + failed + errored` to get the equivalent value.

### Why does the Push API return `failed` for unsubscribes and `errored` for delivery errors?

The field names are preserved from an earlier version of the API. In the View Message(s) API and Notifications CSV, `failed` means the subscription is no longer reachable (uninstalled, cleared browser data, or opted out) and `errored` means a delivery error that OneSignal will retry. The dashboard labels these as Unsubscribed and Failed respectively.

### What's the difference between Total Opens and Unique Opens?

**Total Opens** counts every open event, including repeat opens from the same recipient. **Unique Opens** counts each recipient at most once. The same pattern applies to Total Clicks vs Unique Clicks for email, SMS/RCS, and in-app messages.

### Why does the Live Activities `message.live_activity.sent` event map to Delivered instead of Sent?

The event name is historical. `message.live_activity.sent` fires when APNs accepts the activity update (the **Delivered** concept), and `message.live_activity.delivered` fires when the device acknowledges receipt (the **Confirmed Receipt** concept). Use the mapping table above when configuring downstream analytics.

### Why does Twilio's delivery count sometimes differ from OneSignal's Delivered for SMS/RCS?

OneSignal's **Delivered** metric reflects carrier-confirmed receipt reported back by Twilio. Differences usually come from messages that are still in flight at the time you compare, late status callbacks from carriers, or messages that moved to **Provider Undelivered** after an initial acceptance. See the SMS/RCS lifecycle above for where each state is captured.

### How do I map dashboard labels for SMS Failed to the timeseries chart?

The stat cards show a single **Failed** bucket, while the timeseries chart splits provider-side failures into **Failed (Errored)** (Provider Errored) and **Failed (Undelivered)** (Provider Undelivered). Audience Activity combines Failed and Rejected into **Failed & Rejected**.

## Related

<Columns>
  <Card title="Analytics overview" icon="chart-line" href="./analytics-overview">
    Tour the dashboards, APIs, and export tools OneSignal provides for measuring performance.
  </Card>

  <Card title="Confirmed Receipt" icon="circle-check" href="./confirmed-delivery">
    Platform requirements and SDK setup for the Confirmed Receipt metric on push and Live Activities.
  </Card>

  <Card title="Event Streams" icon="satellite-dish" href="./event-streams">
    Stream real-time message events to your warehouse using the event names in this glossary.
  </Card>

  <Card title="Engagement trends" icon="chart-mixed" href="./engagement-analytics">
    Review aggregate engagement over time using the metrics defined here.
  </Card>

  <Card title="Exporting data" icon="file-export" href="./exporting-data">
    Export the Notifications CSV and other data sets referenced in the mapping tables.
  </Card>

  <Card title="Journey analytics" icon="route" href="./journeys-analytics">
    Measure conversion and drop-off across multi-step Journeys using Journey node reports.
  </Card>
</Columns>


# Analytics overview
Source: https://documentation.onesignal.com/docs/en/analytics-overview

Measure message performance, user engagement, and conversions in OneSignal. Covers dashboards, attribution models, trends, and data export.

## Overview

OneSignal provides analytics to measure message performance, track user engagement over time, and attribute downstream business outcomes like purchases and sign-ups. You can view analytics in the Dashboard, retrieve them through the API, stream real-time events to your own systems using Event Streams, or export data to CSV.

Message reports and aggregate trends are covered below. Jump to other analytics features:

<Columns>
  <Card title="Event Streams" icon="satellite-dish" href="./event-streams"> Send real-time message events like sent, opened, clicked, and dismissed to your data warehouse or analytics tools. </Card>
  <Card title="Exporting data" icon="file-export" href="./exporting-data"> Export message and user data to CSV for offline analysis. </Card>
  <Card title="Journey analytics" icon="route" href="./journeys-analytics"> Measure conversion, drop-off, and performance across multi-step Journeys. </Card>
  <Card title="Template analytics" icon="file" href="./template-analytics"> Aggregate analytics across many messages sent from the same Template. </Card>
  <Card title="Conversion metrics" icon="arrow-trend-up" href="./conversion-metrics"> Measure business impact like revenue and sign-ups with cross-channel last-touch attribution. </Card>
  <Card title="Custom outcomes (legacy)" icon="clock-rotate-left" href="./custom-outcomes"> Track actions like purchases or sign-ups from push and in-app messages. Being replaced by Conversion metrics. </Card>
  <Card title="Goals" icon="bullseye" href="./goals"> Set a target metric on a Journey and track progress on the Journey report. </Card>
</Columns>

### Which analytics should I use?

Choose the right analytics tool based on your goal. Most teams use more than one depending on whether they are optimizing campaigns, debugging delivery, or analyzing long-term behavior.

| Your goal                                                                       | Use this                                                                                                                                                                         |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Review performance of a single message in the dashboard                         | [Message reports](#message-reports)                                                                                                                                              |
| Aggregate performance across similar messages, ideal for transactional messages | [Template analytics](./template-analytics)                                                                                                                                       |
| Measure conversion across a Journey                                             | [Journey analytics](./journeys-analytics)                                                                                                                                        |
| Track engagement trends over time in the dashboard                              | [Engagement trends](./engagement-analytics)                                                                                                                                      |
| Monitor user subscription status changes by channel                             | [Subscription trends](./subscription-trends)                                                                                                                                     |
| Measure downstream actions like purchases or sign-ups                           | [Conversion metrics](./conversion-metrics)                                                                                                                                       |
| Send real-time message events to your own analytics stack                       | [Event Streams](./event-streams)                                                                                                                                                 |
| Analyze data across multiple OneSignal apps                                     | [Event Streams](./event-streams) to a centralized warehouse. See [cross-app analytics](./apps-organizations#how-can-we-access-analytics-messages-and-users-across-multiple-apps) |
| Export data for offline analysis                                                | [Exporting data](./exporting-data)                                                                                                                                               |
| Track whether a Journey met your target metric                                  | [Goals](./goals)                                                                                                                                                                 |

***

## Message reports

Every message sent through OneSignal has a message report showing delivery, engagement, and outcome metrics for that specific send. Message reports cover a single message — they do not aggregate data across multiple messages.

Navigate to **Dashboard > Messages** and select a message to view its report, or retrieve reports programmatically using the [View messages API](/reference/view-messages) and/or [Export audience activity CSV](/reference/export-csv-of-events).

<Note>
  If you send messages using Journeys or Templates, use [Journey analytics](./journeys-analytics) and/or [Template analytics](./template-analytics) to see aggregated performance instead of reviewing each message individually.
</Note>

<Columns>
  <Card title="Push message reports" icon="bell" href="./push-notification-message-reports"> Delivery, opens, clicks, confirmed receipt, and outcomes for push notifications. </Card>
  <Card title="In-app message reports" icon="message" href="./in-app-message-reports"> Impressions, clicks, dismissals, and conversion metrics for in-app messages. </Card>
  <Card title="Email message reports" icon="envelope" href="./email-message-reports"> Sends, opens, clicks, bounces, and unsubscribes for email messages. </Card>
  <Card title="SMS message reports" icon="comment-sms" href="./sms-message-reports"> Delivery, clicks, failures, and opt-outs for SMS/RCS messages. </Card>
  <Card title="Live activity message reports" icon="tower-broadcast" href="./live-activities#message-reports"> Updates, clicks, engagement, and lifecycle events for Live Activities. </Card>
</Columns>

***

## Aggregate trends

Aggregate trends show how message and user activity changes over time across your entire app. These charts help you identify seasonality, spikes, or long-term engagement changes.

For [billing related](./billing-faq) plan usage (sends by channel, MAU, and billing limits), see:

* **App > Settings > Usage** for app-level message volume
* **Organizations > Billing** for plan limits and usage across apps

### Engagement trends

Engagement Trends track message sends, deliveries, opens, clicks, and unsubscribes across all messages. Engagement Trends do not show performance for individual messages — use [message reports](#message-reports) for that.

Navigate to **Dashboard > Analytics > Engagement Trends** to view these charts. Track:

* Sends and deliveries (labeled "Impressions" for in-app messages)
* Opens and clicks
* Unsubscribes

<Frame>
  <img alt="Engagement Trends chart showing message opens, clicks, and sends over time" />
</Frame>

<Card title="Engagement trends" icon="chart-line" href="./engagement-analytics"> Track message sends, opens, clicks, and unsubscribes over time. </Card>

### Subscription trends

Subscription Trends show how Subscriptions subscribe and unsubscribe over time, broken down by channel. Subscription Trends track opt-in and opt-out activity. They do not track message engagement like opens or clicks (use [Engagement Trends](#engagement-trends) for that).

Navigate to **Dashboard > Analytics > Subscription Trends** to view these charts. Subscribes and unsubscribes are each presented in their own chart for clarity.

<Card title="Subscription trends" icon="chart-bar" href="./subscription-trends">
  Track subscribe and unsubscribe activity over time, including Total subscribed, Subscribes, and Unsubscribes.
</Card>

***

## Conversion metrics

Conversion metrics measure the business impact of your messaging by tracking what users do after interacting with messages — such as purchases, sign-ups, or content views.

You define which [Custom Events](./custom-events) count as conversions, and OneSignal attributes those conversions to messages using a **last-touch attribution** model across all channels (push, email, SMS, in-app, and RCS).

<Note>
  Conversion metrics is in **beta** and replaces the legacy [Custom Outcomes](./custom-outcomes) feature. If you are setting up conversion tracking for the first time, use [Conversion metrics](./conversion-metrics).
</Note>

<Card title="Conversion metrics" icon="bullseye" href="./conversion-metrics"> Full details on the attribution model, qualifying interactions per channel, attribution windows, and setup instructions. </Card>

### Legacy outcomes

<Warning>
  [Custom Outcomes](./custom-outcomes) is being deprecated. Legacy outcomes data remains accessible as historical data but will not appear on the new conversion metrics charts.
</Warning>

The legacy Custom Outcomes feature uses a different attribution model that only covers push notifications and in-app messages:

| Attribution      | When it applies                                                                                                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Direct**       | The user clicked the in-app message block or push notification, which launched a new session (app was closed >30s), and triggered the outcome.                                                  |
| **Influenced**   | The user did **not** click a push notification, but opened the app within the influence window (default: 24 hours) and triggered the outcome. Applies to the 10 most recent push notifications. |
| **Unattributed** | The outcome occurred outside of any attribution window or click. Not linked to a specific message.                                                                                              |

***

## FAQ

### How long is message data retained?

| Message Type            | Retention Period                               |
| ----------------------- | ---------------------------------------------- |
| Dashboard-sent messages | Lifetime of the app                            |
| API-sent messages       | 30 days                                        |
| Audience activity CSV   | 30 days                                        |
| Journeys messages       | See [Journeys analytics](./journeys-analytics) |

### How do I aggregate data across multiple messages?

Each message has a unique message ID, which makes manual aggregation via the API possible but inefficient.

**Recommended approach**:

* Use [Templates analytics](./template-analytics) to aggregate performance across related messages sent from the same Template.
* Use [Journeys analytics](./journeys-analytics) to aggregate performance across related Journeys.

### How do I view analytics across multiple apps?

OneSignal analytics are scoped to a single app — there is no built-in cross-app dashboard. To analyze data across multiple apps, use [Event Streams](./event-streams) to route message events from each app to a centralized data warehouse like Snowflake, BigQuery, or Amplitude. From there you can join and query across apps.

For more options including cross-app user data and messaging, see the full breakdown in [Apps, Organizations, & Accounts FAQ](./apps-organizations#how-can-we-access-analytics-messages-and-users-across-multiple-apps).


# Android Firebase credentials
Source: https://documentation.onesignal.com/docs/en/android-firebase-credentials

Learn how to generate and configure Firebase Cloud Messaging (FCM) Service Account credentials for OneSignal to send Android push notifications to apps on the Google Play Store.

To send push notifications to Android devices through the Google Play Store, OneSignal requires Firebase Cloud Messaging (FCM) credentials. This guide walks you through generating the required Service Account JSON file and uploading it to your OneSignal app settings.

For technical background, see [Google’s Service Account documentation](https://cloud.google.com/iam/docs/service-account-overview).

<Note>
  This guide is for developers integrating OneSignal with an Android mobile app distributed via the Google Play Store.

  * This guide should not be used for Web Push. See [Web push setup](./web-push-setup).
  * For Huawei apps distributed via the Huawei App Gallery, see [Huawei: Authorizing OneSignal](./authorize-onesignal-to-send-huawei-push).
</Note>

***

## Requirements

* An Android app distributed via the Google Play Store
* A [Firebase account (free)](https://firebase.google.com)
* A [OneSignal account](https://onesignal.com)

***

## Setup

### 1. Create or open your Firebase Project

Go to the [Firebase console](https://console.firebase.google.com/).

* If you don’t have a project yet, click **Add project** and complete the setup.
* If you already have a project, **select it**.

<Frame>
  <img />
</Frame>

### 2. Enable Firebase Cloud Messaging API v1

<Steps>
  <Step title="Go to Project Settings">
    In Firebase, click the **gear icon** next to **Project Overview > Project settings**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Go to Cloud Messaging">
    Go to the **Cloud Messaging** tab.

    If **Firebase Cloud Messaging API (V1)** is **disabled**, click the **3-dot menu > Open in Cloud Console**.

    <Frame>
      <img />
    </Frame>

    In the Google Cloud Console, click **Enable**. Wait a few minutes for the change to reflect in Firebase.

    <Frame>
      <img />
    </Frame>
  </Step>
</Steps>

### 3. Generate a Service Account JSON file

<Steps>
  <Step title="Return to Project Settings > Service Accounts">
    At the bottom, click **Generate new private key**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Confirm and generate key">
    Confirm by clicking **Generate key** in the popup.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Save the file">
    Save the `.json` file in a secure location. You will need it shortly.

    <Info>
      Required Service Account permissions:

      * `cloudmessaging.messages.create`
      * `firebase.projects.get`

      These are included by default. If you're using a custom Service Account, ensure it has:

      * `roles/firebasemessaging.admin`
      * `roles/firebase.viewer`
    </Info>
  </Step>
</Steps>

### 4. Upload your credentials to OneSignal

<Steps>
  <Step title="Go to Android platform settings">
    In your OneSignal dashboard, go to: **Settings > Push & In-App > Push Platforms > Google Android (FCM)**.

    Click **Activate**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Upload your credentials">
    Upload the `.json` file under **Service Account JSON** by clicking **Choose file**.

    <Frame>
      <img />
    </Frame>

    <Warning>
      If prompted, select **Firebase Cloud Messaging API (V1)** from the dropdown.

      To verify you're using the correct Firebase project, match the **Sender ID** in Firebase (`Cloud Messaging > Sender ID`) with the one shown in your OneSignal settings.
    </Warning>
  </Step>

  <Step title="Save and continue" />

  <Step title="Choose your SDK">
    Select the SDK you are using and click **Save & Continue**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Add the OneSignal App ID to your code">
    Continue following the [Mobile SDK setup](./mobile-sdk-setup) and add this OneSignal App ID to your code.

    <Frame>
      <img />
    </Frame>
  </Step>
</Steps>

<Check>
  You’ve successfully connected your OneSignal app to Firebase Cloud Messaging (V1).

  Next, complete [Mobile SDK setup](./mobile-sdk-setup) or go to [Mobile push setup](./mobile-push-setup) for platform-specific instructions.
</Check>

***

## FAQ

### Error: “This configuration is for a different Firebase Project...”

This error occurs when the uploaded JSON file belongs to a different Firebase project (i.e., different Sender ID).

**Solution**: Use the original Firebase project's JSON file. If unavailable, contact `support@onesignal.com` with your App ID. Switching projects resets push tokens—your users must reopen the app to get push again.

### Can I change my Sender ID?

Yes, but it will impact your existing users.

Device tokens are tied to the original Sender ID. Changing it will invalidate existing tokens.

<Warning>
  Users will stop receiving push notifications until they reopen the app and generate new tokens.
</Warning>

If you need help, contact `support@onesignal.com` with your App ID.

### Do I need to update my code when switching to FCM V1?

No app or SDK changes are required—this is a dashboard-only update.

### What is the deadline for switching to FCM v1?

Google legacy FCM APIs are now fully deprecated. If you are still using the legacy APIs, **you should migrate to FCM V1 immediately**.

### Why don’t I see a Sender ID in OneSignal?

If your Firebase server key looks like `AIz...`, you're likely using an outdated Google Cloud Messaging (GCM) setup. Create a new Firebase project and upload a Service Account JSON file.

### How can I check which apps are still using the Legacy API?

Use the [View apps](/reference/view-apps) API and check for:

* `"gcm_key"` → using Legacy, needs update
* `"fcm_v1_service_account_json"` → using V1 ✅
* Neither → app does not use Android push

***


# Apple App Privacy Requirements
Source: https://documentation.onesignal.com/docs/en/apple-app-privacy-requirements

Understand how to accurately disclose your use of OneSignal in your iOS app to comply with Apple's App Privacy requirements. Learn which data types OneSignal collects and how to report them in App Store Connect.

Starting December 8, 2020, Apple requires a [privacy disclosure for all new apps and app updates](https://developer.apple.com/app-store/app-privacy-details). You must complete the privacy questionnaire in the App Privacy section of [App Store Connect](https://appstoreconnect.apple.com). Apple's official instructions are [available here](https://help.apple.com/app-store-connect/#/dev1b4647c5b).

As OneSignal is a third-party service, it is your responsibility to accurately disclose what data you collect and how it’s used through OneSignal.

By default, OneSignal collects select **in-app purchase data (Consumable)** and **usage data** such as session activity and notification clicks. If you collect additional information via **Tags**, **Outcomes**, or **custom integrations**, you must disclose that as well.

## Data types and their relevance to OneSignal

Use the following table to determine which data types you must disclose when using OneSignal:

✅ = Required when using OneSignal
💡 = May be required, depending on configuration
❌ = Not required when using OneSignal

| Data Type            | Required?                                                                                                                                                                              |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contact Info**     | 💡 If you collect personal identifiers (e.g., name, email) using Tags or Outcomes                                                                                                      |
| **Health & Fitness** | 💡 If you collect health data via custom tags or Outcomes                                                                                                                              |
| **Financial Info**   | 💡 If you collect financial data through tags or Outcomes                                                                                                                              |
| **Location**         | 💡 Only if your app requests and collects location data, and sends it to OneSignal                                                                                                     |
| **Sensitive Info**   | 💡 If you collect sensitive user data (e.g., race, politics, biometrics) via tags or Outcomes                                                                                          |
| **Contacts**         | 💡 If you upload address books or contacts via Tags                                                                                                                                    |
| **User Content**     | 💡 If you collect user-generated content through OneSignal                                                                                                                             |
| **Browsing History** | ❌ Not collected                                                                                                                                                                        |
| **Search History**   | ❌ Not collected                                                                                                                                                                        |
| **Identifiers**      | ✅ OneSignal assigns a unique OneSignal ID for each user (not linked to identity by default). <br /> 💡 If you link other IDs (e.g., email, alias), disclosure requirements may change. |
| **Purchases**        | ✅ Consumable in-app purchase events are collected                                                                                                                                      |
| **Usage Data**       | ✅ Session counts, durations, and notification interactions are collected                                                                                                               |
| **Diagnostics**      | 💡 OneSignal does not collect crash or energy logs, but does collect metadata like device type, OS, network state, etc.                                                                |

## Required data disclosures in App Store Connect

### Type: Purchases

If your app includes in-app purchases, you must report collection of **‘Purchases’** data.

<Frame>
  <img />
</Frame>

#### Purchase History

Mark ‘Analytics’ as a minimum. This enables OneSignal to provide dashboard features like Segments and Outcomes.

<Frame>
  <img />
</Frame>

<Info>
  If you use OneSignal for other purposes (e.g., personalization or app functionality), be sure to select those as well.
</Info>

#### Linked to user identity?

If you're only using OneSignal's anonymous IDs and don’t associate them with identifiable users, you can select **‘No’**.

If you link user data (e.g., email or name) via your backend or third-party tools, select **‘Yes’**.

<Frame>
  <img />
</Frame>

#### Used for tracking?

OneSignal does not track users across other apps. Select ‘No’ unless you use third-party tools or integrations that perform tracking.

<Frame>
  <img />
</Frame>

After saving, you should see a summary like:

<Frame>
  <img />
</Frame>

### Type: Usage Data – Product Interaction

You must disclose collection of **‘Product Interaction’** under **Usage Data**.

<Frame>
  <img />
</Frame>

#### Product Interaction

Select **‘Analytics’** to reflect how OneSignal uses this data in Segments and Outcomes.

<Frame>
  <img />
</Frame>

<Info>
  If you use this data for other purposes, such as app functionality or personalization, include those as well.
</Info>

#### Linked to user identity?

Same guidance as with Purchases — if anonymous, select ‘No’. If linked via user ID or contact info, select ‘Yes’.

<Frame>
  <img />
</Frame>

#### Used for tracking?

OneSignal does not use this data for tracking across apps. Select ‘No’ unless other SDKs or integrations do.

<Frame>
  <img />
</Frame>

You should then see this summary:

<Frame>
  <img />
</Frame>

### Final review

After completing all sections, Apple will show a preview of your app’s privacy disclosure. If you correctly selected Purchases and Usage Data, it should resemble the following:

<Frame>
  <img />
</Frame>

## Ongoing compliance

If your data collection practices change — for example, if you add new tags, link identifiers, or update your SDK version — return to App Store Connect and update your disclosures accordingly.

***


# Azure Synapse
Source: https://documentation.onesignal.com/docs/en/azure-synapse

Sync custom events from Azure Synapse to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Azure Synapse integration enables syncing of custom events from your Azure Synapse Analytics workspace to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

Azure Synapse Analytics is Microsoft's cloud-based analytics service that combines data integration, data warehousing, and analytics.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Azure Synapse

* **Azure Synapse workspace** with SQL pool access
* **Database user** with appropriate permissions
* **Event tables** containing structured behavioral data
* **Firewall access** for the IP addresses provided by OneSignal in the Integration setup

***

## Setup

<Steps>
  <Step title="Create dedicated login for OneSignal">
    Create a dedicated login and user account with a strong, unique password:

    ```sql theme={null}
    USE <your-database>;

    -- Create census login with the ability to sign in with a password
    CREATE LOGIN CENSUS WITH PASSWORD = '<strong-unique-password>';

    -- Create user for the login
    CREATE USER CENSUS FOR LOGIN CENSUS;

    -- Give the census user the ability to connect to database
    GRANT CONNECT TO CENSUS;
    ```

    <Info>
      Replace `<your-database>` with your actual database name containing event data.
    </Info>
  </Step>

  <Step title="Grant read permissions">
    Provide read-only access to your event data:

    ```sql theme={null}
    -- Give the census user the ability to read all tables
    EXEC sp_addrolemember 'db_datareader', CENSUS;

    -- Grant census user ability to read schema and data
    -- Run this for each schema you intend OneSignal to access
    GRANT SELECT, VIEW DEFINITION ON SCHEMA::<your-schema> TO CENSUS;
    ```

    <Info>
      Replace `<your-schema>` with your actual schema name containing event data. Repeat this command for each schema you want OneSignal to access.
    </Info>
  </Step>

  <Step title="Configure firewall access">
    Configure Azure Synapse firewall to allow the IP addresses provided by OneSignal in the Integration setup.

    Use the Windows Azure Management Portal or run **sp\_set\_firewall\_rule** on the primary database:

    ```sql theme={null}
    -- Example: Add firewall rule for OneSignal IP range
    EXEC sp_set_firewall_rule
        N'OneSignal Access',
        'ONESIGNAL_IP_START',
        'ONESIGNAL_IP_END';
    ```

    <Warning>
      Contact OneSignal support for the current IP address ranges for your region.
    </Warning>
  </Step>

  <Step title="Connect to OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Azure Synapse** and provide the following connection details:

    * **Host:** Your Synapse SQL endpoint hostname
    * **Port:** 1433 (default)
    * **Database:** Your database name
    * **Username:** `CENSUS`
    * **Password:** The password from Step 1
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Table Schema

```sql theme={null}
-- Example Azure Synapse event table
CREATE TABLE analytics.user_events (
    event_id BIGINT IDENTITY(1,1) PRIMARY KEY,
    event_name NVARCHAR(100) NOT NULL,
    user_id NVARCHAR(255) NOT NULL,
    event_timestamp DATETIME2 DEFAULT GETUTCDATE(),
    event_data NVARCHAR(MAX),
    session_id NVARCHAR(255),
    device_type NVARCHAR(50)
)
WITH (DISTRIBUTION = HASH(user_id), CLUSTERED COLUMNSTORE INDEX);
```

### SQL Query Mode

Write custom SQL queries to transform your event data:

```sql theme={null}
-- Example: Recent high-value events
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_data
FROM analytics.user_events
WHERE event_timestamp >= DATEADD(day, -7, GETUTCDATE())
    AND JSON_VALUE(event_data, '$.value') > 100
ORDER BY event_timestamp DESC;
```

***

## Azure-Specific Features

### Distributed Architecture

* Events distributed by `user_id` for optimal query performance
* Clustered columnstore indexes for analytics workloads
* Massively parallel processing (MPP) for large-scale event data

### Integration with Azure Ecosystem

* Connect to Azure Data Factory for automated event pipelines
* Integrate with Azure Event Hubs for real-time event streaming
* Leverage Azure Active Directory for authentication

***

## Advanced Network Configuration

OneSignal can successfully connect to Azure Synapse instances that are using advanced networking controls including region constraints, IP address allow lists, or SSH Tunneling.

For more information about configuring network access, contact your Azure Synapse administrator or OneSignal support.

***

## Limitations

* Based on SQL Server JDBC driver connection protocol
* Requires explicit firewall rules for the IP addresses provided by OneSignal in the Integration setup
* Complex queries may impact SQL pool performance and costs
* JSON operations require careful indexing for optimal performance

***

## FAQ

### Can I connect to multiple Azure Synapse schemas?

Yes, you can grant the CENSUS user access to multiple schemas by running the `GRANT SELECT, VIEW DEFINITION ON SCHEMA::<schema>` statement for each schema containing event data.

### How do I configure firewall access for OneSignal?

Use the Azure Management Portal or `sp_set_firewall_rule` to add OneSignal's IP addresses. Contact OneSignal support for the current IP ranges.

### What's the difference between Azure Synapse and SQL Server integration?

Azure Synapse uses the same SQL Server JDBC driver but includes distributed architecture features and requires specific firewall configuration for cloud access.


# Google BigQuery
Source: https://documentation.onesignal.com/docs/en/bigquery

Export messaging event data to BigQuery and import custom events from BigQuery to trigger personalized campaigns.

## Overview

The OneSignal + BigQuery integration supports two powerful data pipelines:

* **Export**: Automatically send messaging event data (push, email, SMS, in-app) from OneSignal to BigQuery for analysis and reporting.
* **Import**: Sync custom user events from your BigQuery datasets to OneSignal to trigger automated Journeys and personalized messaging.

Together, these integrations give you complete control over user engagement data, powering advanced analytics and real-time behavior-driven messaging.

***

## Export OneSignal events to BigQuery

Send messaging performance and engagement events (e.g., sends, opens, clicks) to BigQuery to:

* Build custom dashboards and reports
* Track delivery and engagement trends across channels
* Combine OneSignal data with other business data for analysis

**Requirements**

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

- Google Cloud Platform project with **billing enabled**
- BigQuery enabled in your GCP project
- Service account with BigQuery write permissions

**Setup Steps**

### 1. Create a Service Account

<Steps>
  <Step title="Log in to your Google Cloud Platform account">
    After you login, ensure the proper project is selected.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Create a service account">
    Visit the [Create Service Account page](https://console.cloud.google.com/iam-admin/serviceaccounts/create) and click **Create Service Account.**

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Fill out the fields.">
    Give it any name and service account ID you choose.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Assign the 'BigQuery User' role">
    Give the service account the "BigQuery User" role.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Create a JSON key for this account">
    Go to your new service account > **Keys** > **Add Key** > **Create new key** > select JSON. Save the file.
  </Step>
</Steps>

<Info>
  You’ll paste the entire contents of this JSON key file into OneSignal to activate the integration.
</Info>

### 2. Activate the Integration in OneSignal

<Steps>
  <Step title="Go to OneSignal > Data > Integrations > BigQuery" />

  <Step title="Paste your service account JSON key" />

  <Step title="Configure settings">
    * **Sync Frequency**: As often as every 15 minutes
    * **Dataset/Table Names**: Must only contain lowercase letters, numbers and underscores, and cannot begin with a number.
    * **Event Types**: Select specific message events (e.g., sent, opened, clicked)
      * **Note:** You can select multiple event types or update selected events at a later time.
  </Step>

  <Step title="Click Save and wait for confirmation" />
</Steps>

<Note>
  Initial data sync can take 15–30 minutes to appear in BigQuery.

  While you wait, send messages via push, email, in-app, or SMS to trigger the events selected.
</Note>

### 3. View Data in BigQuery

Open your BigQuery console and locate the dataset (e.g., `onesignal_events_<app-id>`) to explore synced message events.

<Frame>
  <img />
</Frame>

## Message events and properties

### Message event kinds

**Property:** `event_kind`
**Type:** `String`

The kind of message and event (e.g. `message.push.received`, `message.push.sent`).

| Message Event (OneSignal) |           `event_kind`           | Description                                                                |
| :-----------------------: | :------------------------------: | -------------------------------------------------------------------------- |
|         Push Sent         |        `message.push.sent`       | Push notification successfully sent.                                       |
|       Push Received       |      `message.push.received`     | Delivered push (see [Confirmed receipt](/docs/en/confirmed-delivery)).     |
|        Push Clicked       |      `message.push.clicked`      | User clicked the push.                                                     |
|        Push Failed        |       `message.push.failed`      | Delivery failure. See message reports.                                     |
|     Push Unsubscribed     |    `message.push.unsubscribed`   | User unsubscribed from push.                                               |
|     In-App Impression     |     `message.iam.impression`     | In-App message shown.                                                      |
|       In-App Clicked      |       `message.iam.clicked`      | In-App message clicked.                                                    |
|     In-App Page Viewed    |   `message.iam.page_displayed`   | In-App page shown.                                                         |
|         Email Sent        |       `message.email.sent`       | Email delivered.                                                           |
|       Email Received      |     `message.email.received`     | Email accepted by recipient's mail server.                                 |
|        Email Opened       |      `message.email.opened`      | Email opened. See [Email Reports](/docs/en/email-message-reports).         |
|     Email Link Clicked    |      `message.email.clicked`     | Link in email clicked.                                                     |
|     Email Unsubscribed    |   `message.email.unsubscribed`   | Recipient unsubscribed.                                                    |
|   Email Reported As Spam  | `message.email.reported_as_spam` | Marked as spam. See [Email Deliverability](/docs/en/email-deliverability). |
|       Email Bounced       |      `message.email.bounced`     | Bounce due to permanent delivery failure.                                  |
|        Email Failed       |      `message.email.failed`      | Delivery failed.                                                           |
|      Email Suppressed     |    `message.email.suppressed`    | Suppressed due to suppression list.                                        |
|          SMS Sent         |        `message.sms.sent`        | SMS sent.                                                                  |
|       SMS Delivered       |      `message.sms.delivered`     | SMS successfully delivered.                                                |
|         SMS Failed        |       `message.sms.failed`       | SMS failed to deliver.                                                     |
|      SMS Undelivered      |     `message.sms.undelivered`    | SMS rejected or unreachable.                                               |

### Event data schema

For each message event generated by a user, the following metadata will be attached to the record.

|                   Column Name                   |      Type      | Description                                                  |
| :---------------------------------------------: | :------------: | ------------------------------------------------------------ |
|                    `event_id`                   |      UUID      | Unique identifier for the event                              |
|                `event_timestamp`                |    Timestamp   | Time of event occurrence                                     |
|                   `event_kind`                  |     String     | The [Event Kind](#message-event-kinds)                       |
|            `subscription_device_type`           |     String     | Device type (e.g., iOS, Android, Web, Email, SMS)            |
|                    `language`                   |     String     | Subscription language code                                   |
|                    `version`                    |     String     | Integration version                                          |
|                   `device_os`                   |     String     | Device operating system version                              |
|                  `device_type`                  |     Number     | Numeric device type                                          |
|                     `token`                     |     String     | Push token, phone number, or email                           |
|                `subscription_id`                |      UUID      | Subscription ID                                              |
|                   `subscribed`                  |     Boolean    | Subscription status                                          |
|                  `onesignal_id`                 |      UUID      | OneSignal user ID                                            |
|                  `last_active`                  |     String     | Last active timestamp                                        |
|                      `sdk`                      |     String     | OneSignal SDK version                                        |
|                  `external_id`                  |     String     | External user ID that should match the integration user ID   |
|                     `app_id`                    |      UUID      | App ID from OneSignal                                        |
|                  `template_id`                  |      UUID      | Template ID (if applicable)                                  |
|                   `message_id`                  |      UUID      | Message batch/request ID                                     |
|                  `message_name`                 |     String     | Name of the message                                          |
|                 `message_title`                 |     String     | Message title (English only)                                 |
|                `message_contents`               |     String     | Truncated message body (English only)                        |
|                 `failure_reason`                |     String     | Reason for failure (for push failed and email failed events) |
| `_created`, `_id`, `_index`, `_fivetran_synced` | *Internal use* | Fivetran sync metadata                                       |

### Notes

* Syncs after saving/activating may take an additional 15-30 minutes to complete.
* Deactivating may still result in one final sync after deactivation.
* To ensure efficient data synchronization, our system automatically creates and manages staging datasets. These datasets, named with a pattern like `fivetran_{two random words}_staging`, temporarily store data during processing before it's integrated into your main schema. These staging datasets are essential for maintaining a streamlined workflow and should not be deleted, as they will be automatically recreated.

***

## Import events from BigQuery

Send behavioral event data from BigQuery to OneSignal to:

* Trigger Journeys based on user activity
* Personalize messaging based on behavioral data

**Requirements**

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

- GCP project with BigQuery and event data tables
- Service account with read permissions
- Event data tables containing behavioral data in BigQuery datasets

**Setup Steps**

<Steps>
  <Step title="Create BigQuery service account">
    OneSignal will generate a service account automatically when you create the connection. Alternatively, you can provide your own service account key JSON file.

    If creating your own service account, ensure it has the required permissions listed below.
  </Step>

  <Step title="Grant required permissions">
    The OneSignal service account needs these BigQuery IAM roles:

    * **`bigquery.dataViewer`** - Read access to datasets and tables containing event data
    * **`bigquery.jobUser`** - Permission to create jobs for data queries
    * **`bigquery.metadataViewer`** - Project-level metadata access (recommended)

    Grant permissions using the Google Cloud Console or CLI:

    ```bash theme={null}
    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
      --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
      --role roles/bigquery.dataViewer

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
      --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
      --role roles/bigquery.jobUser
    ```
  </Step>

  <Step title="Add integration in OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    <Frame>
      <img />
    </Frame>

    * **Sync Engine**: Advanced sync is recommended for large datasets or complex event data queries. You can start with basic sync and switch to advanced sync later if needed.
    * **Google Cloud Project ID**: Your GCP project containing BigQuery datasets
    * **Dataset Region**: Location where your BigQuery datasets are stored
    * **Service Account Key** (optional): JSON key file if using your own service account
  </Step>

  <Step title="Configure event data source">
    Specify the BigQuery dataset and table containing your event data:

    * **Dataset**: BigQuery dataset name (e.g., `analytics_events`)
    * **Table/View**: Table or view containing event records
    * **Event Query**: Optional SQL query to filter or transform event data

    Your event table should contain columns for:

    * Event name/type
    * User identifier
    * Event timestamp
    * Additional event properties
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify OneSignal can access your BigQuery project and read event data.
  </Step>
</Steps>

***

### Event data mapping

The BigQuery integration recognizes three dedicated fields. All other columns are collected into the `properties` object on the custom event.

| OneSignal Field   | BigQuery Column   | Description                         | Required |
| ----------------- | ----------------- | ----------------------------------- | -------- |
| `name`            | `event_name`      | Event identifier                    | Yes      |
| `external_id`     | `external_id`     | User identifier                     | Yes      |
| `idempotency_key` | `event_id`        | Prevents duplicate event processing | No       |
| `properties`      | All other columns | Mapped as JSON key-value pairs      | No       |

### Advanced configuration

#### Custom SQL Queries

Use custom SQL to filter or transform event data before syncing to OneSignal:

```sql theme={null}
SELECT
  event_name,
  user_id,
  event_timestamp,
  STRUCT(
    product_id,
    purchase_amount,
    category
  ) as payload
FROM `project.dataset.events`
WHERE event_timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
```

#### Cross-Project Access

If your event data spans multiple BigQuery projects, grant the OneSignal service account access to each project containing referenced tables or views.

<Warning>
  Your BigQuery connection region must match the specific table region for optimal performance.
</Warning>

***

## FAQ

### Why is my sync failing?

There are a few common reasons why your sync may be failing:

* The service account does not have the required permissions
* The source dataset is too large for a basic sync and you need to use advanced sync

Review the above setup steps and ensure you have followed them correctly. If you still have issues, please contact `support@onesignal.com`.

### Why do I see multiple message IDs for the same content?

This typically occurs when a message template is reused across multiple sends or triggered flows.

### How often does OneSignal sync data?

Both export and import integrations can sync as frequently as every 15 minutes.

### Can I use BigQuery views?

Yes. Just make sure the service account has access to all referenced tables in the view.

***

## Related Resources

* [Creating service account keys in GCP](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating)
* [OneSignal Journeys documentation](./journeys-overview)
* [OneSignal Data Export documentation](./exporting-data)

***


# BlueConic
Source: https://documentation.onesignal.com/docs/en/blueconic

Sync data from BlueConic to OneSignal

## Overview

[BlueConic webhooks](https://support.blueconic.com/hc/en-us/articles/115004431305-Webhook-Connection) allow you to sync profile or segment data to OneSignal in real time whenever specific events occur on your site. This guide demonstrates how to configure BlueConic to send data to OneSignal via the [Update user](/reference/update-user) API.

## Setup

To sync user data between BlueConic and OneSignal, a common identifier must exist to associate users across both platforms. BlueConic generates a unique identifier called BlueConic ID, which can be linked to a user in OneSignal to synchronize data.

### Update script

We recommend creating a custom alias to identify your users using their BlueConic IDs. Before assigning a new alias, ensure the user is logged in to OneSignal first. The following code provides examples of associating a BlueConic ID with a OneSignal user using an Alias and an External ID.

<CodeGroup>
  ```javascript javascript theme={null}
  // Get the BlueConic ID
  const blueConicId = blueConicClient.profile.getProfile().getId();

  // Ensure the user is logged in
  // Logged in users will have an External ID
  if (!OneSignal.User.externalId) {
  await OneSignal.login("EXTERNAL_ID_FROM_YOUR_BACKENED");
  }

  // External ID must exist before calling this method
  OneSignal.User.addAlias('blueconic_profile_id', blueConicId);

  ```
</CodeGroup>

If your system uses BlueConic IDs as the primary identifier, then pass it to `OneSignal.login`.

<CodeGroup>
  ```javascript javascript theme={null}
  // Get the BlueConic ID
  const blueConicId = blueConicClient.profile.getProfile().getId();

  // Set OneSignal External ID to BlueConic ID
  OneSignal.login(blueConicId);
  ```
</CodeGroup>

### Add webhooks

Use webhooks to synchronize data from BlueConic to OneSignal based on your specific needs. The examples below demonstrate how to use the [Update user](/reference/update-user) API to achieve this.

**API details**

|               |                                                                            |
| ------------- | -------------------------------------------------------------------------- |
| URL           | `https://api.onesignal.com/apps/<APP_ID>/users/by/alias_label/alias_value` |
| Method        | PATCH                                                                      |
| Authorization | Basic \<API\_KEY>                                                          |

If your system uses the BlueConic ID as the primary identifier...

Use the following URL instead:

`https://api.onesignal.com/apps/<APP_ID>/users/by/external_id/{{blueconic_profile_id}}`

### Syncing Profile properties

Synchronize BlueConic profile data to OneSignal by setting [Tags](./add-user-data-tags) and other user data.

<Frame>
  <img />
</Frame>

**Payload**

<CodeGroup>
  ```json json theme={null}
  {
    "properties": {
      "tags": {
        "tag_name_at_onesignal": "{{BLUECONIC_PROPERTY}}"
      }
    }
  }
  ```
</CodeGroup>

#### Syncing segments

Synchronize BlueConic segment data to OneSignal by setting [Tags](./add-user-data-tags). Use these tags to create segments directly within OneSignal.

<Frame>
  <img />
</Frame>

**Payload**

<CodeGroup>
  ```json json theme={null}
  {
    "properties": {
      "tags": {
        "early_bird": "Yes",
      }
    }
  }
  ```
</CodeGroup>

You can name tags based on specific needs, such as **early\_bird** or any other descriptive label. However, the value assigned to the tag should always be hard-coded, such as **Yes**, for consistency between segments in BlueConic and OneSignal.

***


# Building an integration with OneSignal: Partner Guide
Source: https://documentation.onesignal.com/docs/en/building-an-integration-with-onesignal-partner-guide

How to build, verify, and launch a OneSignal partner integration, including the API surface for triggering messages, syncing users, and capturing events.

This guide explains how to build a OneSignal integration, which APIs to use for common use cases, and how to verify your integration once it's complete. Use this page if you're embedding OneSignal into your platform, syncing user data, or triggering messages on behalf of mutual customers. Pay particular attention to the [identity lifecycle](#identity-lifecycle) — it determines whether your integration's data attaches to the right user.

## Benefits of integrating with OneSignal

As a OneSignal partner, you'll gain valuable benefits aligned with your integration success and engagement:

* **Visibility and recognition:** Showcase your integration through a verified listing in the OneSignal Partner Directory, with opportunities for increased exposure and "featured" listings as your partnership grows.
* **Enhanced collaboration:** Participate in joint co-marketing activities, co-selling initiatives, and access comprehensive training to maximize integration adoption.
* **Strategic support:** Gain direct access to our dedicated support and technical teams, with additional levels of support unlocked based on partnership milestones.
* **Growth opportunities:** Access progressively advanced partner benefits such as dedicated documentation pages, enterprise sandbox accounts, and prioritized marketing opportunities as you expand your customer base and reach specific partnership milestones.

***

## Getting started

To start developing your integration, create a free account at [onesignal.com](https://onesignal.com). To join the partner program or to request premium features for integration development and testing, reach out through [partners.onesignal.com](https://partners.onesignal.com) or email `bd@onesignal.com`.

### Requirement: `OneSignal-Usage` header

To join the partner program, you must include the `OneSignal-Usage` header in all API requests. This header lets OneSignal identify your integration, provide better support, and track adoption across mutual customers.

**Format:**

```http theme={null}
OneSignal-Usage: <YourCompany> | Partner Integration
```

Replace `<YourCompany>` with your company or platform name. For example, if your company is Acme, use `Acme | Partner Integration`.

<Warning>
  **Common mistake — header format:** Using only your company name (e.g., `Acme`) without the ` | Partner Integration` suffix. The full format with the suffix and exact spacing is required.
</Warning>

### Submit your integration for verification

Once your integration is ready, complete the [Partner Validation Request form](https://form.asana.com/?k=SHmysllCA1c9RVCtynG8Zg\&d=780103692902078) to open a request ticket with the Partnerships team.

Verification formally recognizes your integration on OneSignal's side, enabling full access to the Integration Partner Program. Before submitting, run through the [end-to-end verification checklist](#verify-your-integration-end-to-end).

***

## Partner architecture patterns

Most OneSignal partner integrations fall into one of three architectural patterns. Identify which one you are building before deciding how to handle identity, Subscription creation, and event timing.

| Pattern                    | Examples                                                    | Where External ID is set                                | What your integration writes                            |
| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
| **Server-side webhook**    | Attribution platforms, marketing automation tools           | Customer's app, via the OneSignal SDK                   | Aliases, tags, custom events (after External ID exists) |
| **CDP-style sync**         | Segment, RudderStack, mParticle                             | The CDP carries a stable `userId` from upstream sources | Users, aliases, tags, email/SMS Subscriptions           |
| **SDK extension or embed** | Mobile BI tools that wrap or coexist with the OneSignal SDK | Your wrapper sets External ID through the OneSignal SDK | Tags, custom events, messages                           |

<Note>
  Regardless of pattern, the OneSignal SDK is the source of truth for push and web Subscriptions when it is installed in the customer's app. Server-side Subscription creation is intended for email and SMS only.
</Note>

***

## Common integration use cases

Pick the use cases relevant to your platform. Each links to the guide and API reference you need. Before writing any user data, review the [Identity lifecycle](#identity-lifecycle).

### Create and identify users

OneSignal's mobile and web SDKs create Users (with OneSignal IDs) and Subscriptions (with Subscription IDs) as end users interact with the customer's app. Partner integrations can attach context to these Users by syncing the customer's External ID and, optionally, custom aliases keyed off it.

<Columns>
  <Card title="Users" icon="user" href="./users">
    How Users are created, stored, and identified by their External ID.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    How Subscriptions are created, stored, and marked as subscribed or unsubscribed.
  </Card>

  <Card title="Aliases" icon="fingerprint" href="./aliases">
    How custom aliases identify Users across platforms and devices.
  </Card>
</Columns>

<Warning>
  Set custom aliases only after the External ID exists. Aliases written to an anonymous user cannot be merged later — see [Identity lifecycle](#identity-lifecycle).
</Warning>

### Sync user attributes

Sync user properties — profile data, preferences, behavior — as Tags so customers can segment audiences and personalize messages.

<Columns>
  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Add custom properties to Users for personalization and segmentation.
  </Card>

  <Card title="Update user API" icon="pen-to-square" href="/reference/update-user">
    Set tags and other properties on an existing User via the external\_id or other alias.
  </Card>
</Columns>

### Send custom events

Send important user actions to OneSignal to trigger Journeys in real time, or use them for delays, segmentation, and personalization.

<Columns>
  <Card title="Custom events" icon="bolt" href="./custom-events">
    Track User actions to trigger Journeys, personalization, and analytics.
  </Card>

  <Card title="Create custom events API" icon="plus" href="/reference/create-custom-events">
    Send custom events to OneSignal programmatically.
  </Card>
</Columns>

### Trigger messages

Trigger push, email, SMS, and Live Activities messages on behalf of mutual customers, directly from your platform. Use `external_id` or an `alias_id` to target individual users (for example, transactional messages), or use segments and filters to target groups.

<Columns>
  <Card title="Create message API" icon="paper-plane" href="/reference/create-message">
    Send push, email, SMS, and Live Activities messages on behalf of mutual customers.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="./live-activities">
    Push real-time Live Activity updates to iOS devices on behalf of mutual customers.
  </Card>
</Columns>

### Manage templates

Sync and manage email, SMS/RCS, and push templates in OneSignal so customers can build campaigns directly from your platform.

<Columns>
  <Card title="Templates" icon="clone" href="./templates">
    Create, manage, and use templates for push, email, SMS, and Live Activities messages.
  </Card>

  <Card title="Create template API" icon="plus" href="/reference/create-template">
    Create templates for push, email, SMS, and Live Activities messages programmatically.
  </Card>
</Columns>

### Capture event streams

Stream real-time engagement data (sends, clicks, opens, bounces, unsubscribes) from OneSignal to your warehouse for downstream analytics and automation.

<Columns>
  <Card title="Event Streams" icon="satellite-dish" href="./event-streams">
    Stream real-time message events to your warehouse using the event names in this glossary.
  </Card>

  <Card title="Analytics overview" icon="chart-line" href="./analytics-overview">
    Measure message performance, user engagement, and conversions in OneSignal.
  </Card>
</Columns>

### Embed OneSignal in your platform

Embed OneSignal with per-customer App IDs so customers can onboard without leaving your product.

<Card title="Platform embedding" icon="plug" href="./developers">
  Embed OneSignal directly within your platform, simplifying customer onboarding with unique App IDs.
</Card>

***

## Identity lifecycle

OneSignal's identity model is sequenced. Calls made in the wrong order can attach data to anonymous users that cannot be merged with the identified user later, breaking multi-channel sync.

<Steps>
  <Step title="The OneSignal SDK creates an anonymous user">
    When a customer's app launches with the OneSignal SDK installed, the SDK creates an anonymous **User** with a OneSignal ID and a **Subscription** with a Subscription ID. At this point, no External ID is set.
  </Step>

  <Step title="The customer's app sets the External ID">
    When the customer's app identifies the end user (for example, on login or signup), it should call `OneSignal.login(externalId)`. This promotes the anonymous user to an identified user. If that user already exists, the OneSignal ID is discarded and the existing OneSignal ID for that user is set.

    This is the **earliest point** at which it is safe for a partner integration to attach data to that user.
  </Step>

  <Step title="The partner integration writes user data">
    Once the External ID is set, your integration can safely:

    * Attach aliases — [Create or update alias](/reference/create-alias)
    * Add tags — [Update user](/reference/update-user)
    * Send custom events — [Create custom events](/reference/create-custom-events) keyed by External ID
    * Send messages — [Create message](/reference/create-message) with `include_aliases.external_id`
  </Step>
</Steps>

<Warning>
  **Common mistake — server-side callbacks:** Webhook-driven integrations that fire on install, session, or event callbacks often arrive **before** the customer's app has called `OneSignal.login()`. Do not attach aliases or tags inside an install handler. Buffer the data until you observe an External ID, or trigger writes from a later callback that includes one.
</Warning>

**Example:**

<Tabs>
  <Tab title="Correct: External ID set first">
    1. A user exists with Subscription ID: `SUB1`, OneSignal ID: `OSID1`, and External ID: `EIDA`.
    2. The user downloads the app on another device. The SDK creates a new anonymous User and a new Subscription with Subscription ID: `SUB2` and OneSignal ID: `OSID2`.
    3. The user logs into the app with `OneSignal.login("EIDA")`. This identifies the anonymous user.
    4. `OSID2` is discarded and `SUB2` is moved to `OSID1` with `EIDA`.
    5. User `OSID1` with `EIDA` now has 2 Subscriptions: `SUB1` and `SUB2`.
  </Tab>

  <Tab title="Incorrect: Alias written first">
    1. A user opens the app. The SDK creates Subscription `SUB1` with OneSignal ID `OSID1`. No External ID is set.
    2. A partner server-side callback fires and posts to [Create user](/reference/create-user) with `adjust_id: "abc"` and the existing push token.
    3. OneSignal creates `OSID2` to hold the new alias and moves `SUB1` from `OSID1` onto `OSID2`. `OSID1` is now orphaned.
    4. The customer's app launches again. The SDK has no record of `OSID2` and creates `OSID3`. `SUB1` is moved again.
    5. The user is now spread across multiple OneSignal IDs, with the partner's alias bound to an anonymous one that cannot be merged later.
  </Tab>
</Tabs>

If your integration writes an alias **before** the External ID is set:

* The alias is bound to an anonymous, orphaned user that cannot be merged with the identified user later
* Subscriptions created under the alias get moved to a new OneSignal ID
* Messages targeted by your alias may fail to deliver

***

## API endpoint reference

Use this matrix to map integration operations to the correct endpoint and its preconditions.

| Operation                                            | Endpoint                                                                                                | Precondition                                                        |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Create or upsert a user with identity and properties | [`POST /apps/{app_id}/users`](/reference/create-user)                                                   | Set External ID via SDK first when the OneSignal SDK is installed   |
| Add or update an alias on an existing user           | [`PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity`](/reference/create-alias)            | External ID is set                                                  |
| Update tags or other user properties                 | [`PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}`](/reference/update-user)                      | External ID is set                                                  |
| Add an email or SMS Subscription to a user           | [`POST /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions`](/reference/create-subscription) | External ID is set; push Subscriptions should be created by the SDK |
| Send a message to one user                           | [`POST /notifications`](/reference/create-message) with `include_aliases.external_id`                   | External ID is set; reuse `idempotency_key` on retries              |
| Send a message to a group                            | [`POST /notifications`](/reference/create-message) with `included_segments` or `filters`                | None                                                                |
| Record a custom event                                | [`POST /apps/{app_id}/integrations/custom_events`](/reference/create-custom-events)                     | External ID is set                                                  |

See the [API reference](/reference/rest-api-overview) for full parameter and response details.

***

## Verify your integration end-to-end

Before submitting your integration for partner verification, confirm each of the following on a test app:

<Steps>
  <Step title="The end user appears with a non-anonymous External ID">
    In **Audience > Users**, find the test user and confirm their identity shows your customer's External ID — not just an anonymous OneSignal ID.
  </Step>

  <Step title="Aliases attach to the identified user">
    Confirm any partner-specific aliases (for example, `integration_id`) appear under the same User as the External ID, not under a separate anonymous user.
  </Step>

  <Step title="Subscriptions link to one User">
    If the user has multiple channels (push, email, SMS), confirm all Subscriptions appear under one User. Multiple Users per person indicates an identity-sequencing issue — see [Identity lifecycle](#identity-lifecycle).
  </Step>

  <Step title="Tags and properties write successfully">
    Confirm tags written by your integration appear on the User's profile in the dashboard.
  </Step>

  <Step title="A test message reaches the test device">
    Send a test message using `include_aliases.external_id` and confirm it delivers to the test user's Subscription.
  </Step>

  <Step title="Retry behavior is correct">
    Trigger a controlled retry on a test endpoint and confirm your integration honors the `Retry-After` header and reuses the same `idempotency_key` on `POST /notifications` retries.
  </Step>
</Steps>

### Common integration mistakes

Avoid these patterns when building a OneSignal integration. Each one is a regression seen in real partner code.

**Writing aliases or tags before the External ID is set**

Aliases and tags attach to whichever User OneSignal can match — typically an anonymous one — and cannot be re-linked to the identified user later. Always require an External ID before writing identity data. See [Identity lifecycle](#identity-lifecycle) for the correct sequence.

**Treating the OneSignal ID as a stable customer identifier**

OneSignal IDs are internal and can change when users merge. Use the External ID as your stable cross-system identifier.

**Creating push Subscriptions server-side when the OneSignal SDK is installed**

The OneSignal SDK is the source of truth for push and web Subscriptions. Server-side Subscription creation is intended for email and SMS Subscriptions. Creating push Subscriptions via API when the SDK is installed produces duplicate or orphaned records.

**Writing the same field via both the SDK and the API**

Pick one writer per field. Concurrent writes from the SDK and a server-side integration create race conditions that overwrite each other unpredictably.

***

## FAQ

### Is the `OneSignal-Usage` header required, or only recommended?

It is required for the partner program. Without the header, OneSignal cannot attribute API traffic to your integration, which blocks partner verification, usage reporting, and prioritized support.

### Do I need a paid OneSignal plan to develop an integration?

No. You can build and test an integration on a free OneSignal account. Contact `bd@onesignal.com` if you need access to premium features for development or testing.

### What's the difference between using the OneSignal API and joining the partner program?

Any developer can call the OneSignal API. The partner program adds verified directory listing, co-marketing and co-selling opportunities, dedicated technical support, and progressively unlocked benefits as your integration grows. See [Benefits of integrating with OneSignal](#benefits-of-integrating-with-onesignal).

### How long does partner verification take?

Verification timing depends on the complexity of your integration and the Partnerships team's review queue. Submit the [Partner Validation Request form](https://form.asana.com/?k=SHmysllCA1c9RVCtynG8Zg\&d=780103692902078) once your integration is feature-complete to start the process.

### Can I use one OneSignal app to serve multiple customers?

No. Each end customer should have their own OneSignal App ID so that data, subscriptions, and messages stay isolated. If you're embedding OneSignal in your platform, see [Platform embedding](./developers) for how to provision per-customer App IDs.


# ClickHouse
Source: https://documentation.onesignal.com/docs/en/clickhouse

Sync custom events from ClickHouse to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + ClickHouse integration enables automatic syncing of custom events from your ClickHouse analytics database to OneSignal. This allows you to trigger automated Journeys and personalized messaging campaigns based on user behavioral data stored in your high-performance columnar database.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### ClickHouse

* **ClickHouse server** (self-hosted or cloud)
* **Database credentials** with read access to event tables
* **Event data tables** containing behavioral data with proper schema

***

## Setup

<Steps>
  <Step title="Create ClickHouse user for OneSignal">
    Create a dedicated user account for OneSignal with read-only access to your event tables:

    ```sql theme={null}
    CREATE USER onesignal_reader IDENTIFIED BY 'strong_password';
    GRANT SELECT ON event_database.* TO onesignal_reader;
    ```
  </Step>

  <Step title="Configure network access">
    Ensure OneSignal can connect to your ClickHouse instance:

    * **Self-hosted**: Allow connections from OneSignal's IP addresses
    * **ClickHouse Cloud**: Add OneSignal IPs to your allowlist
    * **Port**: Default ClickHouse port is 8123 (HTTP) or 9000 (native)
  </Step>

  <Step title="Add integration in OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **ClickHouse** and provide:

    * **Host**: Your ClickHouse server hostname or IP
    * **Port**: ClickHouse port (default: 8123 for HTTP, 9000 for native)
    * **Database**: Database name containing event tables
    * **Username**: `onesignal_reader` (or your chosen username)
    * **Password**: Password for the ClickHouse user
    * **Protocol**: HTTP or Native (HTTP recommended for simplicity)
  </Step>

  <Step title="Configure event data source">
    Specify the ClickHouse table containing your event data:

    * **Table**: Table name containing event records (e.g., `user_events`)
    * **Event Query**: Optional SQL query to filter or transform event data

    Your event table should contain columns for:

    * Event name/type (String)
    * User identifier (String)
    * Event timestamp (DateTime)
    * Additional event properties (JSON or individual columns)
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify OneSignal can access your ClickHouse database and read event data.
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

***

## Advanced Configuration

### Custom SQL Queries

Use custom SQL to filter or transform event data before syncing to OneSignal:

```sql theme={null}
SELECT
  event_name,
  user_id,
  toDateTime(event_timestamp) as timestamp,
  toJSONString(
    map(
      'product_id', product_id,
      'purchase_amount', purchase_amount,
      'category', category
    )
  ) as payload
FROM user_events
WHERE event_timestamp >= now() - INTERVAL 7 DAY
  AND event_name IN ('purchase', 'signup', 'upgrade')
ORDER BY event_timestamp DESC
```

### Performance Optimization

ClickHouse is optimized for analytical queries. Consider:

* **Partitioning**: Use date-based partitioning on event timestamp
* **Indexing**: Create appropriate indexes on user\_id and event\_name
* **Materialized Views**: Pre-aggregate event data for faster querying

<Warning>
  ClickHouse is optimized for append-only workloads. Ensure your event data follows this pattern for best performance.
</Warning>

***

## FAQ

### How often does OneSignal sync events from ClickHouse?

OneSignal syncs event data based on your configured schedule, with a minimum interval of 15 minutes.

### Can I sync events from multiple ClickHouse tables?

Yes, you can create multiple integrations for different tables or use UNION queries to combine data from multiple tables.


# Confluent Cloud
Source: https://documentation.onesignal.com/docs/en/confluent-cloud

Sync custom events from Confluent Cloud to OneSignal to trigger automated Journeys and personalized messaging campaigns based on real-time user behavior.

## Overview

The OneSignal + Confluent Cloud integration enables automatic syncing of custom events from your managed Kafka topics to OneSignal. This allows you to trigger automated Journeys and personalized messaging campaigns based on real-time user behavioral data flowing through your Confluent Cloud streaming platform.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Confluent Cloud

* **Confluent Cloud cluster** with active topics
* **API credentials** with read access to event topics
* **Schema Registry** (optional, for structured event schemas)
* **Event topics** containing behavioral data with proper message format

***

## Setup

<Steps>
  <Step title="Create API credentials in Confluent Cloud">
    Generate API credentials for OneSignal in your Confluent Cloud console:

    1. Navigate to **Data Integration > API Keys** in Confluent Cloud
    2. Click **Create key** and select **Global access**
    3. Save the **API Key** and **API Secret** (you'll need these for OneSignal)
    4. Note your **Bootstrap servers** endpoint from your cluster settings
  </Step>

  <Step title="Configure topic ACLs (if using granular permissions)">
    Grant OneSignal read access to specific topics containing event data:

    ```bash theme={null}
    confluent kafka acl create \
      --allow \
      --service-account <ONESIGNAL_SERVICE_ACCOUNT_ID> \
      --operation READ \
      --topic <EVENT_TOPIC_NAME>

    confluent kafka acl create \
      --allow \
      --service-account <ONESIGNAL_SERVICE_ACCOUNT_ID> \
      --operation DESCRIBE \
      --topic <EVENT_TOPIC_NAME>
    ```
  </Step>

  <Step title="Add integration in OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Confluent Cloud** and provide:

    * **Bootstrap Servers**: Your Confluent Cloud cluster endpoint
    * **API Key**: Confluent Cloud API key
    * **API Secret**: Confluent Cloud API secret
    * **Consumer Group**: Unique group ID for OneSignal (e.g., `onesignal-events`)
    * **Schema Registry URL** (optional): If using Confluent Schema Registry
  </Step>

  <Step title="Configure event topics">
    Specify the Confluent Cloud topics containing your event data:

    * **Topic Names**: Comma-separated list of topics to consume (e.g., `user-events,purchase-events`)
    * **Event Format**: JSON, Avro, or Protobuf message format
    * **Schema Registry**: Enable if using structured schemas

    Your event messages should contain:

    * Event name/type (String)
    * User identifier (String)
    * Event timestamp (Long/ISO format)
    * Additional event properties (nested JSON)
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify OneSignal can connect to your Confluent Cloud cluster and consume event messages.
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

***

## Advanced Configuration

### Schema Registry Integration

Leverage Confluent Schema Registry for structured event data:

```json theme={null}
{
  "schema": "user_event_schema_v1",
  "data": {
    "event_name": "purchase",
    "user_id": "user_12345",
    "event_timestamp": 1640995200000,
    "properties": {
      "product_id": "prod_abc123",
      "amount": 29.99,
      "currency": "USD"
    }
  }
}
```

### Consumer Group Management

OneSignal creates a dedicated consumer group to track message offsets:

* **Auto-commit**: Offsets committed automatically after successful processing
* **Error Handling**: Failed messages logged with retry mechanism
* **Scaling**: Partitions balanced across OneSignal consumer instances

### Real-time Processing

Confluent Cloud enables near real-time event activation:

* **Low Latency**: Events processed within seconds of being published
* **High Throughput**: Handles thousands of events per second
* **Fault Tolerance**: Built-in replication and automatic failover

<Warning>
  Ensure your Confluent Cloud cluster has sufficient throughput capacity to handle OneSignal's consumption rate alongside your other consumers.
</Warning>

***

## FAQ

### How often does OneSignal consume events from Confluent Cloud?

OneSignal consumes events in real-time as they arrive in your topics, with minimal latency (typically under 5 seconds).

### Can I consume from multiple topics simultaneously?

Yes, OneSignal can consume from multiple topics in parallel. Specify topic names as a comma-separated list in the configuration.

### What happens if OneSignal can't connect to Confluent Cloud?

OneSignal will retry connections with exponential backoff. Event consumption will resume automatically once connectivity is restored.


# Conversion metrics
Source: https://documentation.onesignal.com/docs/en/conversion-metrics

Track the business impact of your messaging by attributing conversions like purchases and sign-ups to push, email, SMS, in-app, and RCS messages.

<Info>
  **Beta** — Conversion metrics is in beta and rolling out to all paid plans soon.
</Info>

## Overview

Conversion metrics let you measure the business impact of your OneSignal messaging by tracking real-world outcomes like purchases, sign-ups, and trial starts. You define which [custom events](./custom-events) count as conversions, and OneSignal attributes those conversions to the messages that drove them using a last-touch attribution model across all channels.

This gives you a clear picture of how push notifications, emails, SMS, in-app messages, and RCS messages contribute to your business goals — all from within the OneSignal dashboard.

## Default conversion metrics

OneSignal tracks these conversion metrics out of the box — no additional setup or configuration required on your part:

* **App Sessions** — Counts when a user opens your app after receiving a message.
* **Clicks** — Counts when a user clicks a message.

As long as the OneSignal SDK is integrated in your app or website, these metrics are collected automatically.

***

## Set up custom conversion metrics

Before you can set up custom conversion metrics, you need:

* **Custom events flowing into OneSignal** — Custom conversion metrics are powered by custom events. You must be sending events via the SDK, API, or an integration. See [Custom events](./custom-events) for setup instructions.
* **A paid plan** — Custom conversion metrics are available on all paid plans (Growth, Professional, and Enterprise).

<Steps>
  <Step title="Confirm custom events are sending">
    Verify your custom events are reaching OneSignal by checking **Data > Custom Events** in the dashboard. You should see the events you want to use as conversion metrics listed there.
  </Step>

  <Step title="Go to Settings > Analytics > Conversion Metrics">
    In the OneSignal dashboard, navigate to **Settings > Analytics > Conversion Metrics** to open the configuration page.
  </Step>

  <Step title="Select a custom event">
    Choose the custom event you want to track as a conversion metric. For example, select a `purchase` event to track revenue or a `signup` event to track new registrations.
  </Step>

  <Step title="Choose the tracking type">
    Select how you want to measure the conversion:

    | Tracking type | Description                        | Example            |
    | ------------- | ---------------------------------- | ------------------ |
    | **Count**     | Number of times the event occurred | 15 purchases       |
    | **Value**     | Total of a numeric property value  | \$1,250 in revenue |

    Use **Count** when you want to know how often something happened. Use **Value** when you want to track a cumulative numeric value like revenue or points.
  </Step>

  <Step title="Configure attribution windows">
    Set the attribution window for each channel. The attribution window determines how long after a message interaction a conversion can still be credited to that message. See [Attribution windows](#attribution-windows) for details.
  </Step>
</Steps>

<Frame>
  <img alt="Conversion metrics setup page showing event selection, tracking type, and attribution window configuration" />
</Frame>

***

## Attribution windows

An attribution window is the time period after a message interaction during which a conversion can be credited to that message. If a user converts within the window, the message receives credit. If the user converts after the window closes, the message does not.

When a qualifying interaction happens (for example, a user clicking a push notification) that interaction opens a window for the duration you've configured for that channel. If the push window is set to 15 minutes, the window stays open from the moment of the click until 15 minutes later. Any conversion that occurs while the window is open can be attributed back to that push notification. Once the 15 minutes elapse, the window closes and the message is no longer eligible to receive credit for any conversions occurring after that time.

You can configure attribution windows per channel in **Settings > Analytics > Conversion Metrics**.

| Channel | Notes                                                               |
| ------- | ------------------------------------------------------------------- |
| Push    | Window starts when the notification is delivered or clicked         |
| Email   | Window starts when the email is opened or clicked                   |
| In-App  | Window starts when the message receives an impression or is clicked |
| SMS     | Window starts when the message is delivered                         |
| RCS     | Window starts when the message is delivered or read                 |

***

## Attribution model

Conversion metrics use a **last-touch attribution** model. When a user converts, OneSignal evaluates all qualifying message interactions within their respective attribution windows and classifies the conversion as **attributed**, **influenced**, or **unattributed**.

### Attributed conversions

The most recent qualifying message interaction across **all channels** before the conversion receives attributed credit. Only **one message** gets attribution per conversion.

| Channel | Qualifying interactions |
| ------- | ----------------------- |
| Push    | Clicked                 |
| In-App  | Clicked                 |
| Email   | Opened or clicked       |
| SMS     | Clicked                 |
| RCS     | Read or clicked         |

Thus, when looking backwards in time from when the conversion event occurred, the message that was most recently clicked/opened/read gets attribution credit *as long as* that interaction occurred within the attribution window for that channel.

### Influenced conversions

Any message that meets the qualifying criteria within its attribution window, **except** the message that received direct attribution credit, receives influenced credit. Multiple messages can receive influenced credit for a single conversion.

| Channel | Qualifying interactions     |
| ------- | --------------------------- |
| Push    | Delivered or clicked        |
| In-App  | Impression or clicked       |
| Email   | Opened or clicked           |
| SMS     | Delivered or clicked        |
| RCS     | Delivered, read, or clicked |

Thus, a message can receive influenced credit for a conversion either when:

1. It was clicked/opened/read within the attribution window, but was not the last message that was clicked/opened/read before the conversion happened.
2. It was delivered within the attribution window, regardless of sequencing.

It is possible for a conversion to only be influenced by one or more messages without having any direct attribution credit. This will typically occur when the only qualifying message interaction within the attribution window for that conversion was a message that was delivered but not opened or clicked.

### Unattributed conversions

A conversion is unattributed when no message interaction qualifies within any attribution window. The conversion happened organically, without a traceable message interaction.

<Note>
  **Key rules:**

  * Any single conversion event can have either 0 or 1 messages with direct attribution credit and *any* number of messages (including 0) with influenced credit.
  * A message receives **either** attributed **or** influenced credit for a given conversion, never both.
  * Attribution is cross-channel: the last qualifying interaction from **any** channel wins attributed credit.
</Note>

### Attribution examples

#### Recency wins when windows are open

In this example, a user interacts with messages across four channels before converting. The Push click is the most recent qualifying interaction and its window is still open, so it receives attributed credit. Email and SMS windows are also open, so those messages receive influenced credit. The In-App window closed before the conversion, so it receives no credit.

Thus, this particular conversion was **directly attributed to one message (the push notification)** and **additionally influenced by two messages (the email and the SMS).**

<Frame>
  <img alt="Timeline showing four channel lanes. Push click receives attributed credit as the most recent qualifying interaction. Email and SMS receive influenced credit because their windows are still open. In-app receives no credit because its window closed before the conversion." />
</Frame>

#### Window length can override recency

Attribution windows are configurable per channel, which means an earlier interaction with a longer window can win over a more recent one with a shorter window. Here, the Push click is more recent but its short window closes before the conversion, so it receives no credit. The earlier Email click has a longer window that is still open, so it wins attributed credit.

<Frame>
  <img alt="Timeline showing four channel lanes. Push click is most recent but its attribution window closes before conversion, so it receives no credit. Email click is earlier but has a longer window still open at conversion, so it wins attributed credit. SMS and In-app receive influenced credit." />
</Frame>

***

## View conversion metrics

Conversion data appears across several areas of the OneSignal dashboard.

### Global conversions dashboard

The global conversions dashboard provides a high-level view of all conversion activity. It shows total, attributed, influenced, and unattributed conversions over time.

You can switch between a combined view and per-channel breakdowns using the tabs at the top of the chart.

<Frame>
  <img alt="Global conversions dashboard chart showing total, attributed, influenced, and unattributed conversions over time" />
</Frame>

### Message, template, and Journey reports

Conversion metrics appear on all message reports, template reports, and Journey reports. Each single-message report shows the attributed and influenced conversions for that specific message, while template and Journey reports show conversions aggregated across messages.

You'll see different metrics depending on whether you're viewing **Counts** or **Values.**

### Count metrics

* **Direct (attributed) conversions** -- All conversions with a direct attribution credit. This will include conversions that were also influenced by a message.
* **Influenced conversions** -- All conversions with *only* an influenced credit and no direct attribution credit. Since multiple messages may influence a conversion, it is possible a conversion may be counted more than once across different summary views.
* **Conversion yield** -- Measures how effectively your messages drive conversions. Calculated as direct conversions divided by total delivered messages.

### Value metrics

* **Direct conversion value** -- The sum of the value property for conversions with direct attribution credit. This will include conversions that were also influenced by a message.
* **Influenced conversion value** -- The sum of the value property for conversions that only have influenced credit. Multiple messages may influence a conversion, so a conversion may be counted more than once across different summary views.
* **Value per delivery** -- Measures how much conversion value your messages drive. Calculated as direct conversion value divided by total delivered messages.

### Cross-channel calculation methodology

When presenting aggregated metrics across multiple channels, we use the following methodology:

* **Clicks and Click-through rate** -- Click-through rate is always calculated using unique clicks. Note that because push notifications can be clicked (opened) exactly once, there is no distinction between total and unique clicks for push notifications.
* **Delivered messages** -- This is used as the denominator in click-through rate, conversion yield, and value per delivery. It is the sum of delivered push, email, and SMS / RCS messages and in-app impressions.

<Note>
  **Global vs. message-level reporting:**

  On the global dashboard, each channel receives at most **1 influenced credit** per conversion, even if multiple messages on that channel influenced it. On individual message reports, **each message** that received influenced credit shows it.

  This means the sum of influenced credits across individual message reports may be higher than the channel-level influenced count on the global dashboard.
</Note>

***

## Plan availability

Default conversion metrics (App Sessions and Clicks) are available on all plans. Custom conversion metrics are available on paid plans (Growth, Professional, and Enterprise).

***

## Migration from Custom Outcomes

Custom Outcomes is being deprecated and replaced by conversion metrics.

* **Legacy data is preserved** — Your existing Custom Outcomes data remains accessible as historical data.
* **Separate reporting** — Legacy Custom Outcomes will **not** appear on the new conversion metrics charts. They remain in their original location.
* **No automatic migration** — To track the same metrics with the new attribution model, you need to:
  1. Implement [custom events](./custom-events) via the SDK, API, or integrations (if you haven't already).
  2. Configure those events as conversion metrics in **Settings > Analytics > Conversion Metrics**.
* **Default metrics are migrated** — The default OneSignal outcomes (sessions, clicks) are automatically available as default conversion metrics.

***

## FAQ

### How is this different from Custom Outcomes?

Custom Outcomes only attribute conversions from push notifications and in-app messages. Conversion metrics use a cross-channel last-touch attribution model that covers push, email, SMS, in-app, and RCS. Conversion metrics are also powered by custom events instead of SDK outcome methods, and they provide more granular control over attribution windows per channel.

### What channels support conversion metrics?

Push notifications, email, SMS, in-app messages, and RCS.

### Can I track revenue with conversion metrics?

Yes. When setting up a conversion metric, choose the **Value** tracking type and select the numeric property from your custom event that represents the monetary value (for example, `price` or `order_total`).

### How long is conversion data retained?

Conversion data is retained based on your plan. See [Analytics data retention](./billing-faq#analytics-data-retention) for details.

### What happens to my existing Custom Outcomes data?

Your existing Custom Outcomes data is preserved and remains accessible as historical data. It will not be migrated to or displayed on the new conversion metrics charts. See [Migration from Custom Outcomes](#migration-from-custom-outcomes) for details.

***

## Related pages

<Columns>
  <Card title="Custom events" icon="bolt" href="./custom-events">
    Set up and manage the events that power conversion metrics.
  </Card>

  <Card title="Analytics overview" icon="chart-line" href="./analytics-overview">
    Explore all analytics features available in OneSignal.
  </Card>
</Columns>


# Custom events
Source: https://documentation.onesignal.com/docs/en/custom-events

Track user behavior with Custom Events and use them to trigger Journeys, control flow with Wait Until steps, and personalize messages in real time.

## What are Custom Events?

A Custom Event is a named user action (or inaction) that you send to OneSignal. You send events from your app, website, or external systems so you can trigger automation, control Journey flow, and personalize user experiences in real time.

**Examples include:**

* Completed onboarding
* Made a purchase
* Abandoned a cart
* Canceled a subscription
* Reached a new game level

**When OneSignal receives a Custom Event, you can:**

* Start a Journey
* Continue a Journey with a Wait Until step
* Exit users from a Journey
* Personalize messages using event properties
* Segment users by behavior (Early Access)

### When should you use Custom Events?

Use Custom Events when:

* Messaging should respond to real-time user behavior
* The data represents something that happened (not permanent state)
* You need event properties for personalization or Journey logic

Do not use Custom Events when:

* You want to store long-term user attributes (use Tags instead)

<Warning>
  Custom Events represent something that happened at a specific point in time. Unlike Tags, they do not permanently update the user's profile. They record behavior.

  See [Tags vs Custom Events](#tags-vs-custom-events) below for a detailed comparison.
</Warning>

### Custom Event structure

Custom Events include the following fields:

<ParamField type="string">
  The event name. Maximum `128` characters.
</ParamField>

<ParamField type="object">
  Optional parameters that describe the event (for example: plan name, product ID, or price). These can be used for personalization and Journey flow control.
</ParamField>

<ParamField type="string">
  The user's External ID. A user identifier is required when using the [Create Custom Events API](/reference/create-custom-events). Either `external_id` or `onesignal_id` must be provided.
</ParamField>

<ParamField type="string">
  The time the event occurred (or will occur), formatted as an ISO 8601 string. See [Create Custom Events API](/reference/create-custom-events).
</ParamField>

<ParamField type="string">
  A unique UUID used to prevent duplicate event processing. See [Create Custom Events API](/reference/create-custom-events).
</ParamField>

<Warning>
  Event size limits:

  * Maximum event payload: 2024 bytes
  * Maximum request size (multiple events): 1 MB
</Warning>

***

## Send Custom Events to OneSignal

<Info>
  All events are treated the same for billing purposes, regardless of source.
</Info>

### API and SDKs

<Columns>
  <Card title="Create Custom Events API" icon="server" href="/reference/create-custom-events">
    Send events from your backend.
  </Card>

  <Card title="Mobile/Web SDKs" icon="mobile" href="./mobile-sdk-reference#custom-events">
    Track events client-side.
  </Card>
</Columns>

Example Custom Event payload:

```json JSON theme={null}
{
  "events": [
    {
      "name": "purchase",
      "properties": {
        "item": "T-shirt",
        "size": "small",
        "color": "blue",
        "price": 24.99
      },
      "external_id": "user_12345",
      "timestamp": "2025-10-21T19:09:32.263Z",
      "idempotency_key": "123e4567-e89b-12d3-a456-426614174000"
    },
    {
      "name": "add_to_cart",
      "properties": {
        "item": "Hoodie",
        "size": "medium",
        "color": "black",
        "price": 49.99
      },
      "external_id": "user_12345",
      "timestamp": "2025-10-21T19:12:10.000Z",
      "idempotency_key": "789a0123-b45c-67d8-e901-234567890abc"
    },
    {
      "name": "signup_completed",
      "properties": {
        "plan": "pro",
        "trial": true
      },
      "external_id": "user_67890",
      "timestamp": "2025-10-21T19:15:44.000Z",
      "idempotency_key": "def01234-5678-90ab-cdef-012345678901"
    }
  ]
}
```

### Integrations

OneSignal connects to 25+ external data sources to import custom events, including data warehouses, databases, and streaming platforms, with no custom code required.

<Columns>
  <Card title="Twilio Segment" icon="share-nodes" href="./segment-onesignal-integration">
    Route events and audiences between Segment and OneSignal.
  </Card>

  <Card title="Amplitude" icon="chart-line" href="./amplitude">
    Sync cohorts and import custom events from Amplitude.
  </Card>

  <Card title="Mixpanel" icon="chart-mixed" href="./mixpanel">
    Sync cohorts and import custom events from Mixpanel.
  </Card>

  <Card title="Snowflake" icon="snowflake" href="./snowflake">
    Import custom events from your Snowflake warehouse.
  </Card>

  <Card title="Google BigQuery" icon="database" href="./bigquery">
    Import custom events from BigQuery datasets.
  </Card>

  <Card title="Apache Kafka" icon="bolt" href="./kafka">
    Stream custom events from Kafka topics.
  </Card>
</Columns>

<Card title="Browse all custom event sources" icon="grid-2" href="./integrations#custom-event-sources">
  See the full list of databases, warehouses, and streaming platforms that import custom events into OneSignal.
</Card>

<Tip>
  **No developer resources?** Import custom events directly from a [Google Sheets](./google-sheets) spreadsheet with no code required. Add your event data to a sheet and OneSignal imports it automatically. Ideal for early experimentation or teams without engineering support.
</Tip>

### Verify events are received

After sending events, confirm they are reaching OneSignal in **Data > Custom Events**.

#### Event List tab

<Frame>
  <img />
</Frame>

The Event List tab provides an overview of all Custom Events in your app, organized by event name.

For each event type, you can see:

* Total events ingested
* Most recent event (with full JSON payload and properties)
* Event source (SDK, API, or integration)
* Last occurrence timestamp

Select an event to open its detail view, where you can also update its retention period.

The detail view includes:

* **Source Breakdown**: Number of events ingested by source. Expand to view the latest event schema and the timestamp of the most recent event.
* **Activities**: The 10 most recent events, including source and timestamp. Expand any entry to inspect the full JSON payload.
* **Usage**: Where the event is currently used (Journeys or segments). Click directly into the associated Journey or segment to modify its settings.

#### Event Activity tab

<Frame>
  <img />
</Frame>

The Event Activity tab provides a live feed of the most recent events ingested into your OneSignal app.

Use it to:

* Filter by event name, source, or external ID
* Inspect full JSON payloads
* Debug integration issues

<Warning> The feed does not auto-refresh. Refresh manually after sending new events. </Warning>

<Note>
  Custom events appear on the Custom Events page instantly. However, it can take up to 5 minutes for events to appear in a user's profile under **Activity Timeline > Custom Events**. This is because the Custom Events page reflects recent ingestion, while the user profile is powered by long-term storage.
</Note>

***

## Use Custom Events in OneSignal

After events are flowing into OneSignal, you can use them in the following ways:

### Trigger Journey entry and exit rules

Set a Custom Event as a Journey entry or exit rule to immediately add or remove users when the event occurs.

Example:

* `signup_completed` → Start onboarding or remove from a trial-encouragement Journey
* `purchase` → Send confirmation and cross-sell or remove from abandoned cart Journey

<Card title="Journey settings" icon="gear" href="./journeys-settings#entry-rules">
  Enter users into Journeys with Custom Events.
</Card>

### Control Journey flow (Wait Until)

Use a Wait Until step to hold users until a Custom Event occurs.

Example:

* Wait until `purchase` after `added_to_cart`

<Info> You can define an expiration window. If the user does not trigger the event in time, you can send a fallback message or exit the Journey. </Info>

<Card title="Journey Wait Until step" icon="stopwatch" href="./journeys-actions#wait-until">
  Hold users until a Custom Event occurs.
</Card>

### Personalize Journeys with event properties

Reference event properties using Liquid in your Journey templates.

Example:

```liquid Liquid theme={null}
Thanks for purchasing {{ journey.first_event.properties.item }}!
```

<Card title="Custom Event personalization" icon="bolt" href="./personalization-custom-event">
  Complete guide to using event properties to personalize Journeys.
</Card>

### Segment users with Custom Events

Create a segment based on the occurrence of a Custom Event.

<Note>
  Custom Event segmentation is in Early Access.

  To request access, email `support@onesignal.com` with:

  * Your company name
  * Your OneSignal App ID(s)
</Note>

<Warning>
  Current limitations:

  * Not supported with Email Warm Up or A/B tests
  * Cannot power Journeys
  * Cannot be combined with other segment filters
  * Time-based filters ("has happened in the last X days") reference when the event was received by OneSignal, not when it originally occurred.

    If you are importing historical events and need to segment by original event time, use a [Tag](./add-user-data-tags) to store the event time as a unix timestamp.

    The tag filter supports a "Time Elapsed" operator for dynamic time-based comparisons. Note that tags are user-level, so only the most recent value is stored.
</Warning>

<Card title="Segmentation" icon="filter" href="./segmentation">
  Complete guide to segmentation.
</Card>

***

## Plan availability and retention costs

Custom Events are available on all paid plans.

<Card title="Billing FAQ" icon="receipt" href="./billing-faq#event-related-billing">
  Learn about event retention and pricing.
</Card>

***

## Tags vs Custom Events

[Tags](/docs/en/add-user-data-tags) and [Custom Events](/docs/en/custom-events) are both ways to add data to your users. However, there are some key differences:

| Feature        |                   Tags                   |                                          Custom Events                                         |
| -------------- | :--------------------------------------: | :--------------------------------------------------------------------------------------------: |
| Data usage     |     Segmentation and personalization     | Trigger Journeys without a Segment, Wait Until steps, personalization directly within Journeys |
| Data retention |                 Lifetime                 |        30+ days ([lifetime storage is available](/docs/en/billing-faq#streaming-events))       |
| Data format    |       Key-value strings or numbers       |                                              JSON                                              |
| Data source    |     OneSignal SDK, API, or CSV import    |                               OneSignal SDK, API, or integrations                              |
| Data access    | Segmentation and message personalization |        Journeys and Journey-message-template personalization, Segmentation (Coming soon)       |

The key distinction between Tags and Custom Events is in their depth and use cases. Tags are properties of a user, such as Name, Account Status, or Location. Events are thing that the user has done, such as Purchasing an Item, Completing a Level, or Inviting a Friend. Both tags and events can be used for segmentation and personalization.

In practice, you will likely use both:

* Tags for user properties that are static and don't change often
* Custom Events for real-time scenarios, complex segmentation, and more sophisticated journey workflows

***


# Custom Outcomes
Source: https://documentation.onesignal.com/docs/en/custom-outcomes

Learn how to track user actions and revenue from push notifications and in-app messages using OneSignal Custom Outcomes. Customize attribution and measure engagement with flexible outcome types across platforms.

<Warning>
  **Custom Outcomes is being deprecated.** It is replaced by [Conversion metrics](./conversion-metrics), which provides cross-channel last-touch attribution across push, email, SMS, in-app, and RCS. If you are setting up conversion tracking for the first time, use [Conversion metrics](./conversion-metrics) instead.

  Existing Custom Outcomes data remains accessible as historical data.
</Warning>

OneSignal Custom Outcomes allow you to track meaningful user actions resulting from push notifications and in-app messages. These actions—such as purchases, signups, or app events—can be tracked with count, sum, and unique metrics, giving you insight into the impact of your messaging campaigns.

<Info> Custom Outcomes are available on the **Professional** and **Enterprise** plans. Learn more about our [pricing](https://onesignal.com/pricing). </Info>

***

## Outcome types & SDK methods

You can trigger an Outcome by adding a line of code when a user completes a specific action (e.g., taps "Add to Cart" or "Upgrade").

| Outcome Type       |                          Mobile SDK Method                          |                        Web SDK Method                        | Description                                                                                                                        |
| ------------------ | :-----------------------------------------------------------------: | :----------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Standard Count** |          [`addOutcome`](./mobile-sdk-reference#addoutcome)          |       [`sendOutcome`](./web-sdk-reference#sendoutcome)       | Increases the count by 1 every time it's called. No value tracking.                                                                |
| **Value (Sum)**    | [`addOutcomeWithValue`](./mobile-sdk-reference#addoutcomewithvalue) |       [`sendOutcome`](./web-sdk-reference#sendoutcome)       | Increases count by 1 and sum by the specified numeric value. Useful for revenue tracking.                                          |
| **Unique Count**   |    [`addUniqueOutcome`](./mobile-sdk-reference#adduniqueoutcome)    | [`sendUniqueOutcome`](./web-sdk-reference#senduniqueoutcome) | Increases count by 1, only once per attribution window. Best for binary user actions like "Started Swipe Session" or "Tapped CTA". |

<Info> Outcome events are cached locally if offline and re-attempted on the next OneSignal initialization. </Info>

***

## Count vs sum

Outcomes support two key metrics:

| Metric    | Description                                                       |
| --------- | ----------------------------------------------------------------- |
| **Count** | Number of times the outcome event was triggered                   |
| **Sum**   | Total of all numeric values sent with the outcome (if applicable) |

Outcomes with values always round to the nearest whole number.

**Example**: To track revenue from a purchase:

<CodeGroup>
  ```java java theme={null}
  // "Purchase" button pressed in the app
     ...
     OneSignal.Session.addOutcomeWithValue("Purchase", 18.76);
  ```

  ```objectivec objectivec theme={null}
  // "Purchase" button pressed in the app
     ...
     [OneSignal.Session addOutcomeWithValue:@"Purchase" value:18.76]
  ```

  ```javascript javascript theme={null}
  //Purchase Button pressed on site
  OneSignal.Session.addOutcomeWithValue("Purchase", 20.2);
  ```

  ```javascript Javascript(Web SDK) theme={null}
  //Purchase Button pressed on site
  OneSignal.Session.sendOutcome("Purchase", 20.20);
  ```

  ```swift Swift theme={null}
  let value = "20.20"//you supply the value
  OneSignal.Session.addOutcome(withValue: "Purchase", value: NSNumber(value:value), onSuccess: {outcomeSent in
    print("outcome sent: \(outcomeSent!.name) with random value: \(value)" )
  })
  ```

  ```csharp Unity(C#) theme={null}
  //Send an outcome
  OneSignal.Session.AddOutcome("outcomeName");

  //Send a unique outcome
  OneSignal.Session.AddUniqueOutcome("uniqueOutcomeName");

  //Send an outcome with a float value
  OneSignal.Session.AddOutcomeWithValue("outcomeWithVal", 4.2f);
  ```
</CodeGroup>

***

## Outcome attribution

Each Outcome is tracked with an attribution type that explains how it was generated:

* **direct** — the Outcome occurred when the user directly interacted with the message. Some Outcomes, like `os__click` and `os__confirmed_delivery`, only have direct attribution because they happen solely as a result of the message.
* **influenced** — the Outcome occurred within the attribution time window after the message was sent, but the user never directly interacted with the message.
* **unattributed** — the Outcome occurred without a direct or influenced relationship to the message.
* **total** *(default)* — the sum of **direct + influenced + unattributed**.

## Use cases

### E-commerce site

Online stores can use OneSignal push notifications to drive users back to abandoned carts, flash sales, promotions, and more. With **Outcomes**, store owners can now easily correlate push notifications to user actions such as an add-to-cart, purchase, or coupon redeemed. For purchases, outcomes go even further than simple counts and can track purchase amounts. This allows site owners to easily view the sum total of revenue generated from individual pushes.

<CodeGroup>
  ```java java theme={null}
  OneSignal.Session.addOutcomeWithValue("Purchase", 18.76);
  ```

  ```objectivec objectivec theme={null}
  [OneSignal.Session addOutcomeWithValue:@"Purchase" value:18.76]
  ```

  ```javascript javascript theme={null}
  OneSignal.Session.addOutcomeWithValue("Purchase", 18.76);
  ```

  ```Text Javascript(Web SDK) theme={null}
  OneSignal.Session.sendOutcome("Purchase", 18.76);
  ```

  ```csharp Unity(C#) theme={null}
  OneSignal.Session.AddOutcomeWithValue("Purchase", 18.76);
  ```
</CodeGroup>

### Social apps

Social apps may want to re-engage users by using a push to notify them of a match or friend request, a new like, or simply to get them swiping. By using **Outcomes**, a developer can see whether a push notification led to a user event such as initiating a chat with a match or a 34-second swipe session. These data can then be used to refine notification and targeting strategies.

In the following example, we want to track whether a user started swiping dating profiles after a push. Since we wouldn't want to count every swipe as a conversion, we use `sendUniqueOutcome`

This "Swipe" outcome will only be attributed once to the push that triggered it. Examples:

* If the user clicked the push and performed the action which called this method, it will be a direct attribution.
* If user received the push but did not click it and performed the action within in the attribution window, it will be an influenced attribution. Even if they later click the same push and performed the action again, it will still only be influenced.
* If user performs method outside of an attribution window, it will be unattributed once per session.

<CodeGroup>
  ```java Java theme={null}
  OneSignal.Session.addUniqueOutcome("Swipe");
  ```

  ```objectivec Objective-C theme={null}
  [OneSignal.Session addUniqueOutcome:@"Swipe"]
  ```

  ```javascript JavaScript theme={null}
  OneSignal.Session.addUniqueOutcome("my_outcome_event");
  ```

  ```csharp C# theme={null}
  OneSignal.Session.AddUniqueOutcome("swipe");
  ```
</CodeGroup>

### Pushes clicked by language

Within the Notification Opened/Clicked listener methods of our SDK, you can setup Outcomes to increment how many devices clicked a push by their set language. This will require some native code to detect the language of the device, but you can then pass that language into the Outcome like so:

<CodeGroup>
  ```java Java theme={null}
    public void notificationOpened(OSNotificationOpenResult result) {
      String languageCode = Locale.getDefault().getLanguage();
      System.out.println("languageCode " + languageCode);
      OneSignal.Session.addOutcome(languageCode);
    }
  ```

  ```swift Swift theme={null}
  let notificationOpenedBlock: OSHandleNotificationActionBlock = { result in
    // This block gets called when the user reacts to a notification received
    if let languageCode = Locale.current.languageCode {
        print ("languageCode: " + languageCode);
        OneSignal.Session.addOutcome(languageCode);
    }
  }
  ```

  ```javascript JavaScript theme={null}
  var language = navigator.language;
  OneSignal.Session.addOutcome(language);
  ```
</CodeGroup>

### Pushes clicked by operating system and browser

Within the Notification Opened/Clicked listener methods of our SDK, you can setup Outcomes to increment which platform's specifically were clicked. This is generic for iOS and Android as you can set `OneSignal.addOutcome("iOS")` or `OneSignal.addOutcome("Android")` in your mobile app's click handler, but if you want to track web push platforms as well, you can use this for example:

<CodeGroup>
  ```javascript Javascript(Web SDK) theme={null}
  // Example taken from Stackoverflow: https://stackoverflow.com/questions/11219582/how-to-detect-my-browser-version-and-operating-system-using-javascript
  var os = "Unknown OS";
  if (navigator.userAgent.indexOf("Win") != -1) os = "Windows";
  if (navigator.userAgent.indexOf("Mac") != -1) os = "Macintosh";
  if (navigator.userAgent.indexOf("Linux") != -1) os = "Linux";
  if (navigator.userAgent.indexOf("Android") != -1) os = "Android";
  if (navigator.userAgent.indexOf("like Mac") != -1) os = "iOS";
  console.log('Your os: ' + os);

  var browserType = "Unknown Browser Type";
  if (navigator.userAgent.indexOf("Safari") != -1) browserType = "Safari";
  if (navigator.userAgent.indexOf("Chrome") != -1) browserType = "Chrome";
  if (navigator.userAgent.indexOf("OPR") != -1) browserType = "Opera";
  if (navigator.userAgent.indexOf("Firefox") != -1) browserType = "Firefox";
  console.log('Your Browser: ' + browserType);

  OneSignal.push(["addListenerForNotificationOpened", function(data) {
  OneSignal.Session.sendOutcome(os);
  OneSignal.Session.sendOutcome(browserType);
  }]);

  ```
</CodeGroup>

***

## Disable Outcome tracking

Disable specific Outcomes from being tracked in the dashboard **Settings > Push & In-App > Outcomes Tracking**.

From here, you can click the **Stop Tracking** button to select an outcome to stop tracking in the dashboard. Once you have stopped tracking outcomes, you will see them listed here and can start tracking them again by clicking the **Start Tracking** link.

***

## FAQ

### How long is Outcome data stored?

* Notifications sent from the dashboard keep their Outcome data forever.
* Notifications sent via the API have a 30-day retention of outcomes before being purged.

### What channels support custom outcomes?

Currently custom outcomes be added to actions on Push and In-App Messages only.

Outcomes sent through In-App messages will show as "Unattributed" and will set a tag on the device in format: `outcome name : true`.

### Can I export Outcomes?

You can export a set of outcomes or all outcomes as a CSV. We also provide API access to outcomes for an [individual notification](/reference/view-message) or for [all the notifications](/reference/view-outcomes).

### Can I store strings as values in Custom Outcomes?

This is not supported.

### What happens if a device is offline?

Data for fired outcomes are queued to be sent to OneSignal once the device is online again.

### If a user backgrounds the app after clicking a notification and then comes back to it, firing an Outcome, is it counted direct or influenced?

As long as the user returns to the app within 30 seconds after backgrounding it, the session will still be considered the original session and will get direct attribution.

### When does the new Attribution Window take affect?

If you change the attribution window from 24 hours to 1 hour for example, then the 1 hour window will take affect on a per-device basis once each device opens the app from a brand new session. This new session is created after 30 seconds of being outside the app.

### Why do sessions not match with other analytics?

OneSignal only counts a session after the user has left the app for over 30 seconds. If you close the app or website and return to it within 30 seconds, it will not be a new session.

For instance, Apple's analytics tracks the session as the number of times the app has been used for at least two seconds. If the app is in the background and is later used again, that counts as another session.

***


# Data collected by the OneSignal SDK
Source: https://documentation.onesignal.com/docs/en/data-collected-by-the-onesignal-sdk

Data fields the OneSignal SDK collects automatically, with user permission, or manually — and how to control collection for privacy compliance.

The OneSignal SDK collects data automatically, manually, and through user permission. To customize which data the SDK collects and how to manage consent, see [Handling Personal Data](./handling-personal-data). Most data can be [exported from the dashboard or API](./exporting-data).

## Data used for audience segmentation

The following data can target audiences by [Segments](./segmentation):

| Data                   | Description                                                                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| First Session Time     | The date and time you first used the app or visited the website (UTC).                                                                  |
| Last Session Time      | The date and time you most recently used the app or visited the website (UTC).                                                          |
| Session Count          | The number of times you have used the app or visited the website.                                                                       |
| Total Usage Duration   | The total seconds you have interacted with the app, recorded whenever the app is in the foreground.                                     |
| Device OS              | The operating system of the device or browser.                                                                                          |
| Device Language        | The language the device or browser reports. Can also be set with the SDK language methods.                                              |
| Timezone               | The most recent timezone of the device or browser, in [IANA TZ](https://en.wikipedia.org/wiki/Tz_database) format.                      |
| Country                | The most recent country of the device or browser, in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format.                     |
| Push Permission Status | Whether the device or browser has push notifications enabled or disabled.                                                               |
| App Version            | **Mobile only** — The app version reported by the most recent session.                                                                  |
| Location               | **Mobile only** — GPS coordinates of the device. Must be [enabled and accepted by the user](./handling-personal-data#location-sharing). |

## Data not available for segmentation

The OneSignal SDK also collects the following data, which cannot be used in segments:

| Data                      | Description                                                                                                                                                                              |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Application Identifier    | **Mobile only** — The package name of your mobile application.                                                                                                                           |
| Cellular Carrier          | **Mobile only** — The name of the cellular carrier used by the device.                                                                                                                   |
| Device Model              | The model name of the device or browser.                                                                                                                                                 |
| IP Address                | The IP address the device or browser is visiting from. Not stored on OneSignal servers for EU users. See [handling IP address tracking](./handling-personal-data#ip-address-collection). |
| `web_auth` and `web_p256` | Web push subscription tokens available for export from the [API CSV export](/reference/csv-export).                                                                                      |
| Push Tokens               | Mobile app and web push tokens added to the device by FCM or APNs.                                                                                                                       |

## Data you manually send to OneSignal

You can optionally send the following data to OneSignal. See [Handling Personal Data](./handling-personal-data) for details.

| Data          | Description                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------- |
| Email         | The user's email address, if you want to use OneSignal to deliver emails.                         |
| Phone Number  | The user's phone number, if you want to use OneSignal to deliver SMS.                             |
| Tags          | Any additional data about a user, stored as key-value pairs for segmentation and personalization. |
| Custom Events | Any additional data about a user, stored as key-value pairs for segmentation and personalization. |

## Web SDK browser storage

Identifiers, purpose, and type of browser storage used by the Web SDK:

| Identifier Name                                          | Purpose                                                                     | Type                                        |
| -------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------- |
| `ONE_SIGNAL_SDK_DB`                                      | Storing user preferences in connection with notification permission status. | IndexedDB dictionary, on customer's domain. |
| `os_pageViews`,`isOptedOut`,`isPushNotificationsEnabled` | Prompting and subscription tracking.                                        | Local Storage                               |
| `onesignal-pageview-count`,`ONESIGNAL_HTTP_PROMPT_SHOWN` | Prompting.                                                                  | Session Storage                             |

## FAQ

### Can I disable all automatic data collection?

Yes for some data. You can customize which data the SDK collects and manage user consent through the [Handling Personal Data](./handling-personal-data) guide, which covers disabling location sharing, IP address collection, and more.

### Does OneSignal store IP addresses for EU users?

No. OneSignal does not store IP addresses on its servers for users located in the EU. See [handling IP address tracking](./handling-personal-data#ip-address-collection) for configuration details.

### What browser storage does the Web SDK use?

The Web SDK uses IndexedDB, Local Storage, and Session Storage to manage notification permission status, prompting, and subscription tracking. See the [Web SDK browser storage](#web-sdk-browser-storage) section above for the full list of identifiers.

<Columns>
  <Card title="Handling personal data" icon="shield-halved" href="./handling-personal-data">
    Manage user consent and customize which data the OneSignal SDK collects.
  </Card>

  <Card title="Exporting data" icon="file-export" href="./exporting-data">
    Export user and device data from the OneSignal dashboard or API.
  </Card>
</Columns>


# Data collection & security FAQs
Source: https://documentation.onesignal.com/docs/en/data-questions

Learn how OneSignal protects your data, maintains compliance, and supports privacy regulations.

OneSignal is committed to protecting the privacy and security of all data stored on our platform. We maintain rigorous security controls, adhere to leading compliance frameworks, and continuously monitor and improve our systems to ensure your data remains safe.

This page answers common questions about OneSignal’s data handling, security practices, and compliance certifications.

***

## Data Protection & Compliance

### Hide Email Addresses and Phone Numbers

You can prevent user email addresses and phone numbers from appearing in the OneSignal Dashboard or data exports. See [Handling Personal Data](./handling-personal-data#masking-personally-identifiable-information-pii) for setup instructions.

### SOC 2 Type II & ISO Certifications

OneSignal maintains the following independent security certifications:

* [SOC 2 Type II](./soc-2-type-ii)
* [ISO 27001 & ISO 27701](./iso27001)

These audits validate that OneSignal’s internal controls and privacy management systems meet the highest standards for data security and operational integrity.

### HIPAA

OneSignal complies with HIPAA requirements for customers who manage protected health information (PHI).\
Learn more in our [HIPAA documentation](./hipaa).

### GDPR

OneSignal complies with the EU General Data Protection Regulation (GDPR) and helps customers uphold their GDPR responsibilities. Our primary data centers are located in the European Union.\
See [GDPR & Individual Rights](./gdpr-compliance) for details.

### Data Privacy Framework

OneSignal is certified under the **EU–U.S. Data Privacy Framework** for lawful data transfers between the EU and the U.S.

***

## Security Practices

### Independent Assessments & Vulnerability Scans

We conduct an **annual third-party security assessment** and perform **quarterly vulnerability and penetration scans**. All critical and high-severity findings are remediated promptly.

### Workstation Security

All employee workstations include:

* Firewall and endpoint protection
* Full disk encryption
* Automatic patch management

### Incident Response

We maintain a robust **incident response program** to rapidly detect, contain, and remediate security incidents.

### Dedicated Security Organization

OneSignal’s **Security Team** continuously monitors, triages, and responds to security-related events.

### Encryption

All customer data is encrypted using **industry-standard algorithms**, both **in transit** (TLS 1.2+) and **at rest** (AES-256).

### Single Sign-On (SSO)

OneSignal supports **SSO** through WorkOS, enabling integration with major identity providers. See [Single Sign-On](./sso).

### Two-Factor Authentication (2FA)

Organization administrators can enforce **2-Step Authentication (2FA)** for all team members.\
See [2-Step Authentication](./2-step-authentication).

### Personnel Security

All employees undergo background checks and regular **security awareness training**.

***

## Data Governance & Retention

OneSignal acts as a **data processor**, while customers remain the **data controller**.

* **Message data** (sent via API or Journeys): retained for 30 days before deletion.
* **Dashboard messages**: retained until deleted manually.
* **User data**:
  * Retained indefinitely on paid plans until deleted.
  * Retained for 18 months of inactivity on free plans.

### Data Export

OneSignal provides tools to easily export user and message data. See [Exporting Data](./exporting-data).

***

## FAQs

### How can I or my users opt-out of push notifications?

Users can disable push notifications in the device Notifications settings. For web push notifications, see [Unsubscribe from Notifications](./browser-behavior-and-unsubscribes). For more details, see [Subscriptions](./subscriptions).

### What data is collected by the OneSignal SDK?

See [Data Collected by the OneSignal SDK](./data-collected-by-the-onesignal-sdk).

### Does OneSignal use cookies?

OneSignal’s Web SDK does **not** use cookies. It uses **Local Storage** and **IndexedDB** for storing client data.

You may see a Cloudflare cookie named `__cf_bm`. This cookie is:

* Set by Cloudflare (not OneSignal)
* Used to protect against bots
* Classified as a *Strictly Necessary* cookie that does not require consent under the EU Cookie Law

For more details, see Cloudflare’s [cookie policy](https://www.cloudflare.com/en-gb/cookie-policy/) and [GDPR explainer](https://gdpr.eu/cookies/).

### How should I handle user data in OneSignal?

Follow our best practices in [Handling Personal Data](./handling-personal-data).

### Is OneSignal COPPA Compliant?

OneSignal is certified under the **Families Ads Program** (as of January 10, 2022).

While COPPA compliance is the publisher’s responsibility, OneSignal provides tools to help you collect user consent before data collection or push prompts. See [Getting User Consent](./handling-personal-data#collecting-and-enforcing-user-consent) and [this COPPA guide](https://www.superawesome.com/blog/how-to-implement-coppa-compliant-push-notifications-in-kid-directed-apps/).

### How Can I Secure My OneSignal Account?

Follow these security best practices:

1. Enable [2-Step Authentication](./2-step-authentication) and/or [Single Sign-On](./sso).
2. Remove unnecessary [Team Members](./manage-team-members).
3. Avoid shared logins; each person should have their own OneSignal account.
4. Regularly rotate or delete API keys. See [Keys & IDs](./keys-and-ids).
5. Reset your password as needed. See [Account Management](./apps-organizations).

<Warning>
  Never expose your REST API Keys or App Keys in public repositories or client-side code.
</Warning>

### What are the password rules and policies?

* Passwords need to have 8 characters minimum and cannot appear in a database of exposed passwords.
* There are no predefined expiration or rotation policies for passwords.

### What if my REST API key is compromised?

Immediately **delete and rotate** your API key. See [Keys & IDs](./keys-and-ids) for instructions.

### What if My App ID Is Exposed?

Your App ID is **public** and safe to share—it can only be used to create new user records. However, users cannot receive messages unless they’ve subscribed through valid means. For added protection, enable [Identity Verification](./identity-verification).

### What if a Subscription ID Is Exposed?

A user’s own `subscription_id` is safe to expose to that user—it can only modify their own data. However, **never share other users’ subscription IDs**, as these can be used to send notifications to specific devices. To prevent impersonation, use [Identity Verification](./identity-verification).

***


# Data warehouse, DMP, & CRM integration
Source: https://documentation.onesignal.com/docs/en/database-dmp-crm-integration

Integrate your CRM, database, or DMP with OneSignal to trigger personalized, real-time notifications and sync user messaging data at scale.

Connecting OneSignal to your internal systems like a data warehouse, CRM, or data management platform (DMP) unlocks powerful capabilities for real-time, personalized, and scalable messaging. Whether you're using Salesforce, a custom user system, or another platform, integration enables you to:

* Send personalized, time-sensitive messages using live data
* Sync user attributes and message data between systems
* Trigger automated [Journeys](./journeys-overview) from user actions in your system
* Use your internal system as the source of truth while leveraging OneSignal's messaging infrastructure

<Frame>
  <img alt="Diagram showing data flow between a database and OneSignal" />
</Frame>

***

## Integration guide

OneSignal has direct integrations with many popular platforms. Check the integrations page to see if your platform is supported — if it is, follow that setup guide instead.

<Card title="Integrations" icon="plug" href="./integrations">
  Browse all available OneSignal integrations with CRMs, data warehouses, analytics tools, and more.
</Card>

If your platform isn't listed, follow the steps below to integrate via the OneSignal REST API.

### Step 1: Identify users with External ID

OneSignal's [`external_id`](./users) is the key link between OneSignal and your database. Set each user's `external_id` in OneSignal to match their user ID in your database. This enables you to target users, sync data, and trigger messages using identifiers you already have.

If you use multiple OneSignal apps (e.g., separate apps for iOS, Android, and web), setting the same `external_id` across all apps identifies the same user across platforms.

If you have anonymous users or do not have a stable user ID for tracking users across systems, you can use OneSignal's `onesignal_id` or `subscription_id`. However, we recommend setting an `external_id` when the user is stable and identifiable.

The `onesignal_id` and/or `subscription_id` is available in the Create user API response and via our mobile and web SDKs using the [Observer methods](./mobile-sdk-reference#addobserver-push-subscription-changes).

#### API-only setup

If you're only using OneSignal for email and SMS/RCS (no mobile apps or websites), you can manage users entirely through the REST API:

* [Create user](/reference/create-user) — Create a user with `external_id`, email address, and/or phone number
* [Update user](/reference/update-user) — Update user properties and subscriptions

No SDK installation is required. Your backend sends user data directly to OneSignal.

**SDK setup**

If you have mobile apps or websites, use OneSignal's frontend SDKs to capture push notification tokens and set the `external_id`:

1. Install the [OneSignal SDK](./mobile-sdk-setup) for your platform.
2. Call `login` with the user's `external_id` after they authenticate in your app.
3. The SDK automatically captures the push token and links it to the user.

***

### Step 2: Sync user data and events

Once user identity is set up, you can sync two types of data from your system to OneSignal:

**Tags** — persistent user properties

[Tags](./add-user-data-tags) store user attributes in OneSignal for segmentation and [message personalization](./message-personalization). Use them for data that describes who a user is, such as plan type, preferred language, or signup date.

* Set tags via the [Update user](/reference/update-user) API or through our frontend SDKs
* Tags persist on the user until you update or remove them
* Use tags to build [Segments](./segmentation) and [personalize message content](./message-personalization)

**Custom events** — user actions

[Custom Events](./custom-events) represent actions a user takes, such as `completed_purchase`, `viewed_page`, or `subscription_expired`. Use them to trigger automated [Journeys](./journeys-overview).

* Send Custom Events via our API or frontend SDKs
* Custom events are not persisted like tags but they can be used to trigger Journeys and message personalization

### Step 3: Export message and engagement data

To sync delivery and engagement data back to your systems:

* **[Event Streams](./event-streams)** — (Recommended) Real-time webhook delivery of message events (sent, delivered, clicked, etc.). Best for keeping your database in sync as events happen.
* **[Export subscriptions CSV](/reference/csv-export)** — Bulk export of subscription data for periodic syncs or migrations.
* **[View messages API](/reference/view-messages)** — Query message history and delivery stats programmatically.

***

## Architecture recommendations

* **Keep your database as the source of truth.** Treat OneSignal as the messaging layer — push user data and events to OneSignal, and pull delivery/engagement data back.
* **Use the API for real-time updates.** When a user takes an action (e.g., completes a purchase), call the OneSignal API immediately to update tags or send a custom event.
* **Use CSV import for bulk operations.** For initial onboarding or large migrations, use [CSV import](./import) rather than making thousands of individual API calls.
* **Respect [rate limits](/reference/rate-limits).** For high-volume updates, batch requests where possible and implement retry logic with exponential backoff.
* **Use Event Streams for the return path.** Rather than polling the OneSignal API for delivery data, set up [Event Streams](./event-streams) to receive real-time webhooks for message events.

***

## Triggering messages from your database

You can trigger messages using two approaches — choose one or both based on your use case.

<Tabs>
  <Tab title="API">
    Use the [Create message](/reference/create-message) API for immediate, transactional messaging.

    Target users via:

    * `external_id`
    * Aliases (e.g., `crm_id`)
    * Email or phone number

    Best for:

    * [Transactional messages](./transactional-messages) (e.g., receipts, alerts)
    * Time-sensitive or personalized notifications
    * Targeting individuals or groups (up to 20,000 users per call)

    You can also schedule messages using the `send_after` parameter.
  </Tab>

  <Tab title="Tags and Journeys">
    Use [Tags](./add-user-data-tags) to build dynamic user segments.

    Send messages by:

    * Targeting segments or filters via the API
    * Manual sends through the dashboard
    * Automated messaging using [Journeys](./journeys-overview)

    Best for:

    * Marketing campaigns (promotions, re-engagement)
    * Scheduled or lifecycle messages
    * Empowering non-technical teams to run campaigns
  </Tab>

  <Tab title="Custom events and Journeys">
    Use [Custom Events](./custom-events) to trigger [Journeys](./journeys-overview) based on user actions, either sent via the API or synced from a [supported warehouse integration](./integrations).

    See [Custom Events](./custom-events) for more information.
  </Tab>
</Tabs>

***

## FAQ

### Should I use the API or Journeys to send messages from my database?

Use the [Create message](/reference/create-message) API for immediate, transactional messages like receipts or alerts. Use [Journeys](./journeys-overview) with [Tags](./add-user-data-tags) or [Custom Events](./custom-events) for automated lifecycle and marketing messages that benefit from visual workflow building.

### What data should I store in OneSignal vs. my own system?

Decide based on the data's purpose:

**What to store in OneSignal**

* Store data used directly for messaging:
  * `external_id` and aliases
  * Emails (for email messaging)
  * Phone numbers (for SMS)
  * Lightweight user attributes as [Tags](./add-user-data-tags)
  * Key events you want to send messages for as [Custom Events](./custom-events)

<Note>
  OneSignal supports several ways to personalize messages detailed in [Message personalization](./message-personalization).
</Note>

**What to keep in your own systems**

* Keep data unrelated to messaging (e.g., full user profiles, transaction logs) in your own systems for performance, privacy, and control. Archive message history from OneSignal for long-term analytics or compliance.

### Can I send messages to users who don't have an external ID?

Yes, but it requires extra handling. You can use OneSignal's `onesignal_id` or `subscription_id`, but these are anonymous until linked to an `external_id`. We recommend setting an `external_id` for every user to simplify cross-system identification.

### What's the difference between tags and custom events?

[Tags](./add-user-data-tags) are persistent user properties (e.g., plan type, language preference) used for segmentation and personalization. [Custom Events](./custom-events) represent one-time user actions (e.g., `completed_purchase`) used to trigger [Journeys](./journeys-overview). Tags describe who a user is; custom events describe what a user did.

***

<Columns>
  <Card title="Users" icon="user" href="./users">
    Understand the OneSignal user model and how identities are structured.
  </Card>

  <Card title="Custom events" icon="bolt" href="./custom-events">
    Send events from your systems to trigger Journeys and track user behavior.
  </Card>

  <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
    Personalize messages with tags, custom data, and dynamic content.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build automated messaging workflows triggered by user behavior and data.
  </Card>
</Columns>


# Databricks
Source: https://documentation.onesignal.com/docs/en/databricks

Export OneSignal message events to Databricks and import Databricks behavioral events into OneSignal to trigger Journeys and personalize messaging.

## Overview

The OneSignal + Databricks integration supports **two flows**:

* **Export**: Send OneSignal message events to Databricks for analytics and reporting.
* **Import**: Send custom events from Databricks to OneSignal to trigger Journeys and personalize campaigns.

<Info> Export and import are configured separately. You can set up one without the other. </Info>

***

## Export OneSignal message events to Databricks

Sync all your message events from OneSignal into your Databricks lakehouse for near real-time analytics and visibility.

**Requirements**

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

- Databricks Platform: AWS, Azure, or GCP
- Databricks Plan: Premium or higher
- Databricks Unity Catalog (recommended for governance)
- Databricks SQL Warehouse for querying
- Delta Lake event tables (for custom event import)

**Setup Steps**

### 1. Collect SQL warehouse details

<Steps>
  <Step title="Log in to your Databricks workspace">
    Go to **SQL Warehouses** in your Databricks workspace.
  </Step>

  <Step title="Select your warehouse">
    Select your warehouse and open the **Connection details** tab.
  </Step>

  <Step title="Save the following details">
    * Server Hostname
    * Port
    * HTTP Path

    <Frame>
      <img alt="Databricks SQL connection details for Fivetran setup" />
    </Frame>
  </Step>
</Steps>

### 2. Choose authentication method

Databricks supports two authentication methods. Choose the method that best fits your deployment and security requirements.

<Tabs>
  <Tab title="OAuth M2M">
    **When to use:**

    * Direct connections (not using PrivateLink)
    * Organizations with OAuth infrastructure

    **Note:** Does not support PrivateLink connections.

    #### Create a service principal

    <Steps>
      <Step title="Go to the Service Principals page">
        Go to **Workspace Settings > Identity and Access > Service Principals**.
      </Step>

      <Step title="Add a new service principal">
        Click **Add Service Principal**, then **Add New**.
      </Step>

      <Step title="Name the service principal">
        Name it (e.g., `onesignal-sync`).

        <Frame>
          <img alt="Modal for adding a service principal, with the 'Add new' option highlighted" />
        </Frame>
      </Step>
    </Steps>

    #### Generate a secret

    <Steps>
      <Step title="Click into the created principal" />

      <Step title="Go to the Secrets tab" />

      <Step title="Generate a secret">
        Click **Generate Secret** and save it securely.

        <Warning>
          The secret is only visible once—store it safely.
        </Warning>

        <Frame>
          <img alt="Databricks 'Generate secret' modal showing OAuth secret and client ID for API authentication" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Personal Access Token">
    **When to use:**

    * Using PrivateLink (AWS or Azure)
    * Simpler setup
    * Maximum compatibility

    **Note:** Works with all Databricks deployment types.

    #### Create a Personal Access Token

    <Steps>
      <Step title="Access Settings">
        In your Databricks workspace, click your username in the top bar and select **Settings**.
      </Step>

      <Step title="Navigate to Developer section">
        Click **Developer**.
      </Step>

      <Step title="Manage tokens">
        Next to **Access tokens**, click **Manage**.
      </Step>

      <Step title="Generate new token">
        Click **Generate new token**.
      </Step>

      <Step title="Configure token">
        * Enter a comment like "OneSignal Integration" to help identify this token
        * Set the token's lifetime in days (check your workspace documentation for maximum allowed duration)
        * Click **Generate**
      </Step>

      <Step title="Save the token">
        Copy the displayed token to a secure location, then click **Done**.

        <Warning>
          Save the token securely and don't share it. If you lose it, you must create a new token. Tokens that remain unused for 90 days are automatically revoked by Databricks.
        </Warning>
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Note>
  **Recommendation:** If you're using PrivateLink or want the simplest setup, choose Personal Access Token. For direct connections with existing OAuth infrastructure, OAuth M2M works well.
</Note>

### 3. Assign permissions

<Steps>
  <Step title="Navigate to your Catalog and open the Permissions tab" />

  <Step title="Click Grant" />

  <Step title="Assign the following permissions to the service principal or user">
    * USE CATALOG
    * USE SCHEMA
    * SELECT
    * MODIFY
    * CREATE SCHEMA
    * CREATE TABLE

    <Frame>
      <img alt="Privilege assignment screen for a Databricks principal with custom catalog permissions selected" />
    </Frame>
  </Step>
</Steps>

### 4. Connect OneSignal

<Steps>
  <Step title="Activate the integration">
    In OneSignal, navigate to **Data > Integrations > Databricks**.
  </Step>

  <Step title="Enter the details">
    * Server Hostname
    * Port
    * HTTP Path
    * Catalog Name
    * Schema Name
    * Credentials

    <Frame>
      <img alt="OneSignal Databricks Configuration form with fields for catalog, hostname, HTTP path, and OAuth credentials" />
    </Frame>
  </Step>

  <Step title="Configure the integration">
    * **Sync Frequency:** as often as every 15 minutes
    * **Dataset/Table Names:** pre-set as `onesignal_events_<app-id>` and `message_events` (editable)
    * **Event Types:** choose which to sync—select all or just what you need
  </Step>

  <Step title="Select events">
    Select the events you care to receive in your Databricks catalog.

    <Frame>
      <img alt="OneSignal event export settings screen showing sync status, dataset configuration, and selected message event types" />
    </Frame>
  </Step>

  <Step title="Complete the setup">
    Click **Save** and wait for the success confirmation
  </Step>
</Steps>

<Note>
  Initial data sync can take 15–30 minutes to appear in BigQuery.

  While you wait, send messages via push, email, in-app, or SMS to trigger the events selected.
</Note>

### 5. View data in Databricks

1. Open your **Catalog** in Databricks.

2. Once syncing completes, your configured schema will appear.

3. Access and query the `message_events` table.

   <Frame>
     <img alt="Databricks Catalog view showing OneSignal message events table under a production schema" />
   </Frame>

4. Click into tables for sample data preview.

   <Frame>
     <img alt="Sample data from the message_events_1 table with synced OneSignal event fields" />
   </Frame>

<Info>
  If you run into issues like missing schemas, permission errors, or malformed events, contact `support@onesignal.com`.
</Info>

## Message events and properties

### Message event kinds

**Property:** `event_kind`
**Type:** `String`

The kind of message and event (e.g. `message.push.received`, `message.push.sent`).

| Message Event (OneSignal) |           `event_kind`           | Description                                                                |
| :-----------------------: | :------------------------------: | -------------------------------------------------------------------------- |
|         Push Sent         |        `message.push.sent`       | Push notification successfully sent.                                       |
|       Push Received       |      `message.push.received`     | Delivered push (see [Confirmed receipt](/docs/en/confirmed-delivery)).     |
|        Push Clicked       |      `message.push.clicked`      | User clicked the push.                                                     |
|        Push Failed        |       `message.push.failed`      | Delivery failure. See message reports.                                     |
|     Push Unsubscribed     |    `message.push.unsubscribed`   | User unsubscribed from push.                                               |
|     In-App Impression     |     `message.iam.impression`     | In-App message shown.                                                      |
|       In-App Clicked      |       `message.iam.clicked`      | In-App message clicked.                                                    |
|     In-App Page Viewed    |   `message.iam.page_displayed`   | In-App page shown.                                                         |
|         Email Sent        |       `message.email.sent`       | Email delivered.                                                           |
|       Email Received      |     `message.email.received`     | Email accepted by recipient's mail server.                                 |
|        Email Opened       |      `message.email.opened`      | Email opened. See [Email Reports](/docs/en/email-message-reports).         |
|     Email Link Clicked    |      `message.email.clicked`     | Link in email clicked.                                                     |
|     Email Unsubscribed    |   `message.email.unsubscribed`   | Recipient unsubscribed.                                                    |
|   Email Reported As Spam  | `message.email.reported_as_spam` | Marked as spam. See [Email Deliverability](/docs/en/email-deliverability). |
|       Email Bounced       |      `message.email.bounced`     | Bounce due to permanent delivery failure.                                  |
|        Email Failed       |      `message.email.failed`      | Delivery failed.                                                           |
|      Email Suppressed     |    `message.email.suppressed`    | Suppressed due to suppression list.                                        |
|          SMS Sent         |        `message.sms.sent`        | SMS sent.                                                                  |
|       SMS Delivered       |      `message.sms.delivered`     | SMS successfully delivered.                                                |
|         SMS Failed        |       `message.sms.failed`       | SMS failed to deliver.                                                     |
|      SMS Undelivered      |     `message.sms.undelivered`    | SMS rejected or unreachable.                                               |

### Event data schema

For each message event generated by a user, the following metadata will be attached to the record.

|                   Column Name                   |      Type      | Description                                                  |
| :---------------------------------------------: | :------------: | ------------------------------------------------------------ |
|                    `event_id`                   |      UUID      | Unique identifier for the event                              |
|                `event_timestamp`                |    Timestamp   | Time of event occurrence                                     |
|                   `event_kind`                  |     String     | The [Event Kind](#message-event-kinds)                       |
|            `subscription_device_type`           |     String     | Device type (e.g., iOS, Android, Web, Email, SMS)            |
|                    `language`                   |     String     | Subscription language code                                   |
|                    `version`                    |     String     | Integration version                                          |
|                   `device_os`                   |     String     | Device operating system version                              |
|                  `device_type`                  |     Number     | Numeric device type                                          |
|                     `token`                     |     String     | Push token, phone number, or email                           |
|                `subscription_id`                |      UUID      | Subscription ID                                              |
|                   `subscribed`                  |     Boolean    | Subscription status                                          |
|                  `onesignal_id`                 |      UUID      | OneSignal user ID                                            |
|                  `last_active`                  |     String     | Last active timestamp                                        |
|                      `sdk`                      |     String     | OneSignal SDK version                                        |
|                  `external_id`                  |     String     | External user ID that should match the integration user ID   |
|                     `app_id`                    |      UUID      | App ID from OneSignal                                        |
|                  `template_id`                  |      UUID      | Template ID (if applicable)                                  |
|                   `message_id`                  |      UUID      | Message batch/request ID                                     |
|                  `message_name`                 |     String     | Name of the message                                          |
|                 `message_title`                 |     String     | Message title (English only)                                 |
|                `message_contents`               |     String     | Truncated message body (English only)                        |
|                 `failure_reason`                |     String     | Reason for failure (for push failed and email failed events) |
| `_created`, `_id`, `_index`, `_fivetran_synced` | *Internal use* | Fivetran sync metadata                                       |

### Notes

* Syncs after saving/activating may take an additional 15-30 minutes to complete.
* Deactivating may still result in one final sync after deactivation.
* To ensure efficient data synchronization, our system automatically creates and manages staging datasets. These datasets, named with a pattern like `fivetran_{two random words}_staging`, temporarily store data during processing before it's integrated into your main schema. These staging datasets are essential for maintaining a streamlined workflow and should not be deleted, as they will be automatically recreated.

***

## Import events from Databricks

Send behavioral event data from Databricks to OneSignal to:

* Trigger Journeys based on user activity
* Personalize messaging based on behavioral data

**Requirements**

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

- **Databricks workspace** with SQL Warehouse or compute cluster
- **Personal Access Token** with appropriate permissions
- **Event data tables** containing behavioral data in Delta Lake format
- **Unity Catalog** (recommended for data governance)

**Setup Steps**

<Steps>
  <Step title="Create Databricks Personal Access Token">
    Generate a Personal Access Token for OneSignal to access your Databricks workspace:

    1. Navigate to **User Settings** in your Databricks workspace
    2. Click **Developer** tab and then **Access tokens**
    3. Click **Generate new token**
    4. Enter a comment like "OneSignal Integration" and set expiration (recommend 90 days)
    5. Save the generated token (you'll need this for OneSignal)
  </Step>

  <Step title="Configure SQL Warehouse access">
    Ensure OneSignal can query your event data via SQL Warehouse:

    1. Navigate to **SQL Warehouses** in your Databricks workspace
    2. Select or create a SQL Warehouse for OneSignal access
    3. Note the **Server Hostname** and **HTTP Path** from the connection details
    4. Ensure the warehouse has access to your event data tables
  </Step>

  <Step title="Grant table permissions">
    Grant OneSignal read access to tables containing event data:

    ```sql theme={null}
    -- For Unity Catalog enabled workspaces
    GRANT SELECT ON TABLE catalog.schema.event_table TO `onesignal@yourdomain.com`;

    -- For Hive metastore tables
    GRANT SELECT ON TABLE database.event_table TO `onesignal@yourdomain.com`;
    ```
  </Step>

  <Step title="Add integration in OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Databricks** and provide:

    * **Server Hostname**: Your Databricks SQL Warehouse hostname
    * **HTTP Path**: SQL Warehouse HTTP path
    * **Personal Access Token**: Token created in step 1
    * **Catalog** (optional): Unity Catalog name if using Unity Catalog
  </Step>

  <Step title="Configure event data source">
    Specify the Databricks table containing your event data:

    * **Database/Schema**: Database or schema name containing event tables
    * **Table**: Table name with event records (e.g., `user_events`)
    * **Event Query**: Optional SQL query to filter or transform event data

    Your event table should contain columns for:

    * Event name/type (String)
    * User identifier (String)
    * Event timestamp (Timestamp)
    * Additional event properties
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify OneSignal can access your Databricks workspace and read event data.
  </Step>
</Steps>

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Advanced configuration

#### Unity Catalog Integration

Leverage Unity Catalog for governed data access:

```sql theme={null}
SELECT
  event_name,
  user_id,
  event_timestamp,
  to_json(
    named_struct(
      'product_id', product_id,
      'purchase_amount', purchase_amount,
      'category', category
    )
  ) as payload
FROM catalog.schema.user_events
WHERE event_timestamp >= current_timestamp() - INTERVAL 7 DAYS
```

### Delta Lake Optimization

Optimize event tables for better query performance:

* **Partitioning**: Partition by date (`event_date`) for faster time-based queries
* **Z-Ordering**: Z-order by `user_id` and `event_name` for better filtering
* **Delta Lake Features**: Use liquid clustering for automatic optimization

#### Streaming Event Processing

For real-time event processing, consider:

* **Structured Streaming**: Process events as they arrive
* **Delta Live Tables**: Build robust event processing pipelines
* **Auto Loader**: Continuously ingest new event files

<Warning>
  Ensure your SQL Warehouse has sufficient compute resources to handle OneSignal's queries without affecting other workloads.
</Warning>

***

## FAQ

### Why do I see different message IDs with the same content?

This happens when the same message is sent more than once, likely via a transactional flow or message template reused across multiple sends.

### How often does OneSignal sync events from Databricks?

OneSignal syncs event data based on your configured schedule, with a minimum interval of 15 minutes.

### Can I use Databricks notebooks for event processing?

Yes, you can use notebooks to process and prepare event data, then expose it via tables that OneSignal can query.

### What about cost optimization for event queries?

Consider using serverless SQL Warehouses for cost-effective, on-demand compute that automatically scales based on query load.

***


# Delete users
Source: https://documentation.onesignal.com/docs/en/delete-users

Delete users and subscriptions in OneSignal via the Dashboard or API for privacy compliance, cleanup, or bulk removal of inactive data.

## Why delete users or subscriptions?

You may want to delete [Users](./users) and [Subscriptions](./subscriptions) for a few reasons:

1. **Data privacy compliance** – to honor user requests for data removal.
2. **Cleanup inactive data** – remove old subscriptions from users who no longer use your app or website, or have switched devices.

<Danger>
  Once you delete users, this action is irreversible. Deleted users can only receive messages again if they:

  * **Web:** Clear browser cookies and revisit your site.
  * **Mobile:** Reopen the app (ensure the app uses the latest OneSignal SDK).
  * **Email/SMS:** Are re-added with the same email or phone number.
</Danger>

***

## Recommendations before deletion

1. [**Export user data**](./exporting-data)
   Download a CSV containing all user data and custom fields for backup or compliance.

2. **Understand the difference** between [Users](./users) and [Subscriptions](./subscriptions).

3. **Double-check your audience** to prevent accidental deletion.

***

## Automatic subscription deletion (Free Plan only)

* On **Paid Plans**, Subscriptions are kept until manually deleted.
* On the **Free Plan**, OneSignal **automatically deletes dormant push subscriptions** after 18 months of inactivity.

**Dormancy means:**

* The app or site hasn't been opened in 18+ months, **or**
* No activity has been recorded in that time

See our [Privacy Policy](https://onesignal.com/privacy_policy) for more information.

***

## Delete Users and Subscriptions with the API

Use the [**Delete User API**](/reference/delete-user) to remove a user and all associated data.

* Supports deletion using `external_id`, `onesignal_id`, or other aliases.
* Best for privacy compliance or full user record removal.

Use the [**Delete Subscription API**](/reference/delete-subscription) to delete individual [Subscriptions](./subscriptions), such as old devices or sessions.

***

## Delete Users and Subscriptions in the Dashboard

### Individual deletion

1. Go to **Audience > Subscriptions**.
2. Search for the Subscription you want to delete.
3. Click **Options > Delete**.

The Subscription is permanently removed from the User.

### Bulk deletion

To delete multiple Users or Subscriptions:

<Steps>
  <Step title="Create a segment">
    * Follow the [Segmentation docs](./segmentation) to build your segment.
    * To target a list, [upload a CSV](./import) and apply tags.
    * To remove inactive users, filter by **Last Session > 4321 hours** (\~6 months). Ensure you're using "greater than" (not "less than").

    <Note>
      Consider sending two re-engagement notifications to the segment before deletion.
    </Note>
  </Step>

  <Step title="View the segment">
    Navigate to **Options > View Subscriptions** from the segment view.

    <Frame>
      <img alt="View Subscriptions option in the segment actions menu" />
    </Frame>
  </Step>

  <Step title="Delete Subscriptions in the segment">
    In **Audience > Subscriptions**:

    1. Select the segment.
    2. Click the arrow next to **Update/Import Users**.
    3. Choose **Delete Subscriptions In Segment**.

    <Warning>
      This will only delete subscribed users. See section below on removing all records that meet certain segment filters and rules.
    </Warning>

    <Frame>
      <img alt="Delete Subscriptions In Segment option in the import dropdown" />
    </Frame>

    You'll see a confirmation screen with the number of records and a prompt to input the segment name.

    <Danger>
      Once you confirm deletion, it cannot be undone.
    </Danger>

    <Frame>
      <img alt="Segment name confirmation prompt before deletion" />
    </Frame>

    After confirmation, a success screen appears and you receive a confirmation email. You can only delete one segment at a time per app.

    <Frame>
      <img alt="Deletion success screen with email confirmation notice" />
    </Frame>
  </Step>
</Steps>

### Deleting all records in a segment

Deleting records through the dashboard will not delete unsubscribed records that may match the segment criteria. In order to remove all records that meet the conditions of the segment, you must first get the full list of users.

**Dashboard export**

1. From the segments page, select the 3 vertical dots to the right of the segment you're looking to delete records from.
2. Select "View Subscriptions" to be taken to the Subscriptions page sorted by the records that meet the segment criteria.
3. Select "Export" on the top right of the page and check the box saying "Include unsubscribed records"

**API exports**

1. Make a request to the [Export Subscriptions endpoint](/reference/csv-export) with the following body parameters included:
   * `"include_unsubscribed": true`
   * `"segment_name": "your_segment_name"`
2. Open the gzip link returned from the request. Depending on the file size the link may be ready before it can actually be downloaded. In this case you would wait and try to open again, or poll the file url until it becomes available.

Once you have the list of subscription records, you can make a [**Delete User**](/reference/delete-user) or [**Delete Subscription**](/reference/delete-subscription) request to permanently delete the exported records. See [here](/reference/rate-limits#api-rate-limits) for limits when running delete requests in parallel.

If you are unable to make API requests, please reach out to `support@onesignal.com` with details on which steps you followed.

***

## FAQ

### Can I undo a user or subscription deletion?

No. Deletions are permanent and cannot be reversed. Always export your data and verify your audience before proceeding.

### How can a deleted user start receiving messages again?

Deleted users can re-subscribe through the following channels:

* **Web:** Clear browser cookies and revisit your site.
* **Mobile:** Reopen the app (the app must use the latest OneSignal SDK).
* **Email/SMS:** The user must be re-added with the same email address or phone number.

### When does OneSignal automatically delete subscriptions?

On the **Free Plan**, OneSignal automatically deletes dormant push subscriptions after 18 months of inactivity. On **Paid Plans**, subscriptions are kept until you manually delete them.

***

<Columns>
  <Card title="Users" icon="user" href="./users">
    Understand the OneSignal User model and how users relate to subscriptions.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    Learn about subscription types and how they connect to users.
  </Card>

  <Card title="Segmentation" icon="filter" href="./segmentation">
    Build audience segments to target or manage groups of users.
  </Card>

  <Card title="Export user data" icon="download" href="./exporting-data">
    Download a CSV of user data for backup or compliance purposes.
  </Card>
</Columns>


# Developers
Source: https://documentation.onesignal.com/docs/en/developers

Developer guide to integrating OneSignal: SDK setup, API reference, User identity, and testing across mobile and web.

This guide helps developers integrate OneSignal into mobile and web applications. Follow the sections in order for a first-time setup, or jump to the area you need.

1. [**Get started**](#get-started) — access your OneSignal App and find your API keys
2. [**Set up messaging channels**](#set-up-messaging-channels) — install the SDK and configure channels
3. [**SDK and API reference**](#sdk-and-api-reference) — detailed method, class, and endpoint documentation
4. [**Users and identity**](#users-and-identity) — identify Users, manage Subscriptions, and secure access
5. [**Tutorials**](#tutorials) — step-by-step guides for common use cases
6. [**Testing and debugging**](#testing-and-debugging) — verify your integration before going live
7. [**Analytics and webhooks**](#analytics-and-webhooks) — track performance and receive message events server-side

***

## Get started

If your team already has a OneSignal account, ask an admin to [invite you](./manage-team-members) to the Organization. Otherwise, [create an account](https://onesignal.com) to get started.

Your OneSignal App is where User and message data lives. Each App has its own App ID, API keys, and messaging channels. You can have multiple Apps in a single Organization for different projects or environments.

<Columns>
  <Card title="Apps, Organizations, and accounts" icon="building" href="./apps-organizations">
    How Apps, Organizations, and accounts relate to each other.
  </Card>

  <Card title="Keys and IDs" icon="key" href="./keys-and-ids">
    Find your App ID, REST API key, and Organization ID for authentication.
  </Card>

  <Card title="Add team members" icon="user-plus" href="./manage-team-members">
    Invite developers and assign roles within your Organization.
  </Card>

  <Card title="Usage and billing" icon="credit-card" href="./billing-faq">
    Billing, invoices, and usage details.
  </Card>
</Columns>

***

## Set up messaging channels

Install the OneSignal SDK to create and track user engagement for your platforms. Each message channel has its own setup guide covering credentials, SDK initialization, and tutorials.

<Columns>
  <Card title="Mobile SDK setup" icon="mobile" href="./mobile-sdk-setup">
    SDK setup for iOS, Android, Huawei, and Amazon. Enables push notifications, in-app messages, and Live Activities.
  </Card>

  <Card title="Web push" icon="globe" href="./web-sdk-setup">
    Web SDK installation and browser push notification setup.
  </Card>

  <Card title="Email" icon="envelope" href="./email-setup">
    Email channel configuration and sender domain verification.
  </Card>

  <Card title="In-app messages" icon="window-maximize" href="./in-app-messages-setup">
    Display rich, interactive messages within your mobile app.
  </Card>

  <Card title="SMS" icon="comment-sms" href="./sms-messaging">
    SMS channel setup and carrier registration.
  </Card>

  <Card title="RCS" icon="message" href="./rcs-messaging">
    Rich messaging with branded content and read receipts.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="./live-activities">
    Dynamic iOS lock screen updates. Similar capabilities are available for Android.
  </Card>
</Columns>

***

## SDK and API reference

Detailed documentation for client SDKs, server SDKs, and the REST API.

<Columns>
  <Card title="Mobile SDK reference" icon="mobile" href="./mobile-sdk-reference">
    Methods, classes, and event hooks for iOS, Android, and cross-platform SDKs.
  </Card>

  <Card title="Web SDK reference" icon="globe" href="./web-sdk-reference">
    Initialization, User management, Subscription methods, and custom triggers.
  </Card>

  <Card title="Server SDK reference" icon="server" href="./server-sdk-reference">
    Install and configure server SDKs for Node.js, Python, Java, Go, PHP, Ruby, C#, and Rust.
  </Card>

  <Card title="REST API overview" icon="code" href="/reference/rest-api-overview">
    Endpoints, authentication, rate limits, and request/response formats.
  </Card>
</Columns>

***

## Users and identity

OneSignal assigns each person a **OneSignal ID** and tracks their devices, email addresses, and phone numbers as **Subscriptions**. Users are anonymous until you call `login` with an **External ID** to identify them. Identifying Users unifies their Subscriptions across channels and devices.

<Columns>
  <Card title="Users" icon="users" href="./users">
    User model, External ID, anonymous vs. identified Users, and login/logout.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    Devices, email addresses, and phone numbers that receive your messages.
  </Card>

  <Card title="Identity verification" icon="shield-halved" href="./identity-verification">
    Require server-generated JWTs to prevent User impersonation.
  </Card>

  <Card title="Aliases" icon="fingerprint" href="./aliases">
    Map custom identifiers to Users for cross-platform tracking and integrations.
  </Card>

  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Add custom properties to users for personalization and segmentation.
  </Card>

  <Card title="Custom events" icon="bolt" href="./custom-events">
    Track User actions to trigger Journeys or power analytics.
  </Card>
</Columns>

***

## Tutorials

Step-by-step guides for implementing common messaging use cases with OneSignal.

<Card title="Tutorials & use cases" icon="graduation-cap" href="./tutorials">
  Browse implementation guides for abandoned carts, onboarding flows, re-engagement campaigns, and more.
</Card>

***

## Testing and debugging

Verify your integration works before sending to your full audience.

<Tip>
  Always test with [Test Users](./test-users) first. This lets you verify delivery, rendering, and deep links without affecting real Users.
</Tip>

<Columns>
  <Card title="Test Users" icon="vial" href="./test-users">
    Find and configure test users for push, email, and SMS.
  </Card>

  <Card title="Debug logs" icon="bug" href="./capturing-a-debug-log">
    Capture verbose SDK logs from mobile apps for troubleshooting.
  </Card>

  <Card title="Mobile troubleshooting" icon="mobile" href="./mobile-troubleshooting">
    Resolve common push delivery, APNS, and in-app messaging issues.
  </Card>

  <Card title="Web troubleshooting" icon="globe" href="./troubleshooting-web-push">
    Fix service worker, browser compatibility, and web push issues.
  </Card>
</Columns>

***

## Analytics and webhooks

Track message performance and receive delivery events server-side for analytics, automation, or syncing with external systems.

<Columns>
  <Card title="Event Streams" icon="signal-stream" href="./event-streams">
    Stream clicks, opens, receives, and other message events to your data warehouse in real time.
  </Card>

  <Card title="Journey webhooks" icon="route" href="./journeys-webhook">
    Send HTTP requests to your server from Journey steps.
  </Card>

  <Card title="Web push webhooks" icon="link" href="./webhooks">
    HTTP callbacks for web push display, click, and dismiss events.
  </Card>
</Columns>

***

## FAQ

### How do I authenticate REST API requests?

Include your REST API key in the `Authorization` header using the `key` scheme: `Authorization: key YOUR_REST_API_KEY`. Find your key in **Settings > Keys & IDs** in the OneSignal dashboard. See [Keys & IDs](./keys-and-ids) for details.

### What is the difference between client SDKs and server SDKs?

* **Client SDKs** (mobile and web) run in your app on the user's device. They handle Subscription registration, permission prompts, in-app messages, and user identification via `login`.
* **Server SDKs** run on your backend and call the REST API to send messages, manage users, and export data.

### How do I identify Users across devices?

Call `OneSignal.login("your_external_id")` on each device after the user signs in. OneSignal merges all Subscriptions with the same External ID under a single User. See [Users](./users#external-id) for implementation details.

### Do I need to set up identity verification?

Identity verification is optional but strongly recommended for production apps. Without it, any client can call `login` with an arbitrary External ID. Enabling [identity verification](./identity-verification) requires updating the OneSignal SDK to use a server-generated JWT, preventing impersonation.


# Mobile SDK Mapping
Source: https://documentation.onesignal.com/docs/en/device-user-model-mobile-sdk-mapping

Compare method and property names between OneSignal's legacy Player Model (v3 & v4) and the modern User Model (v5+), with side-by-side Swift code examples for easier migration.

<Warning>
  OneSignal has updated from a device-centric model (Player ID) to a user-centric model (OneSignal ID). For migration guidance, refer to the [User Model Migration Guide](./user-model-migration-guide).

  For documentation on legacy device-centric implementations, see [Version 9](/v9.0/docs/sdk-reference).
</Warning>

This page maps method and property names between OneSignal's Player Model and User Model SDKs. It mirrors the layout of the original [Player Model Client SDK Reference](/v9.0/docs/sdk-reference) for familiarity. Swift examples illustrate the API changes, but these are not always complete working samples. Refer to the linked documentation for examples in other languages and full implementation details.

## Initializing OneSignal

### `initWithLaunchOptions()`

**Player Model** [Reference](/v9.0/docs/sdk-reference)

```swift theme={null}
OneSignal.initWithLaunchOptions(launchOptions)
OneSignal.setAppId("ONESIGNAL_APP_ID")
```

**User Model** [Reference](./mobile-sdk-reference#initialize)

```swift theme={null}
OneSignal.initialize("YOUR_ONESIGNAL_APP_ID", withLaunchOptions: launchOptions)
```

***

## Debugging

### `setLogLevel()`

**Player Model** [Reference](/v9.0/docs/sdk-reference)

```swift theme={null}
OneSignal.setLogLevel(.LL_VERBOSE, visualLevel: .LL_NONE)
```

**User Model** [Reference](./mobile-sdk-reference#debugging)

```swift theme={null}
OneSignal.Debug.setLogLevel(.LL_VERBOSE)
```

***

## External user IDs

### `setExternalId()`

**Player Model** [Reference](/v9.0/docs/sdk-reference)

```swift theme={null}
OneSignal.setExternalId("EXTERNAL_USER_ID")
```

**User Model** [Reference](./mobile-sdk-reference#debugging)

```swift theme={null}
OneSignal.login("EXTERNAL_USER_ID")
```

### `removeExternalUserId()`

**Player Model** [Reference](/v9.0/docs/sdk-reference)

```swift theme={null}
OneSignal.removeExternalUserId({ results in ... })
```

**User Model** [Reference](./mobile-sdk-reference#log-out-a-user)

```swift theme={null}
OneSignal.logout()
```

***

## Tags

### `sendTag()`

**Player Model** [Reference](./add-user-data-tags)

```swift theme={null}
OneSignal.sendTag("key", value: "value")
```

**User Model** [Reference](./mobile-sdk-reference)

```swift theme={null}
OneSignal.User.addTag(key: "key", value: "value")
```

### `sendTags()`

```swift theme={null}
OneSignal.sendTags(["key1": "value1", "key2": "value2"])
```

```swift theme={null}
OneSignal.User.addTags(["key1": "value1", "key2": "value2"])
```

### `getTags()`

```swift theme={null}
OneSignal.getTags({ tags in ..., onFailure: { error in ... })
```

```swift theme={null}
let tags = OneSignal.User.getTags()
```

### `deleteTag()`

```swift theme={null}
OneSignal.deleteTag("key")
```

```swift theme={null}
OneSignal.User.removeTag("key")
```

### `deleteTags()`

```swift theme={null}
OneSignal.deleteTags(["key1", "key2"])
```

```swift theme={null}
OneSignal.User.removeTags(["key1", "key2"])
```

***

## User data

### `notificationPermissionStatus`

```swift theme={null}
OneSignal.getDeviceState().notificationPermissionStatus
```

```swift theme={null}
OneSignal.Notifications.permissionNative
```

### `userId`

```swift theme={null}
OneSignal.getDeviceState().userId
```

```swift theme={null}
OneSignal.User.pushSubscription.id
```

### `hasNotificationPermission()` / `areNotificationsEnabled`

```swift theme={null}
OneSignal.getDeviceState().areNotificationsEnabled()
```

```swift theme={null}
OneSignal.Notifications.permission
```

### `pushToken`

```swift theme={null}
OneSignal.getDeviceState().pushToken
```

```swift theme={null}
OneSignal.User.pushSubscription.token
```

### `hasNotificationPermission`

```swift theme={null}
OneSignal.getDeviceState().hasNotificationPermission
```

```swift theme={null}
OneSignal.User.pushSubscription.optedIn
```

### `isSubscribed` \[Dropped]

```swift theme={null}
OneSignal.getDeviceState().isSubscribed
```

**User Model**: N/A

### `isPushDisabled` \[Dropped]

```swift theme={null}
OneSignal.getDeviceState().isPushDisabled
```

**User Model**: N/A

### `setLanguage()`

```swift theme={null}
OneSignal.setLanguage("es")
```

```swift theme={null}
OneSignal.User.setLanguage("en")
```

***

## Privacy

### `setRequiresUserPrivacyConsent()`

```swift theme={null}
OneSignal.setRequiresUserPrivacyConsent(true)
```

```swift theme={null}
OneSignal.setConsentRequired(true)
```

### `consentGranted()`

```swift theme={null}
OneSignal.consentGranted(true)
```

```swift theme={null}
OneSignal.setConsentGiven(true)
```

***

## Location

### `setLocationShared()`

```swift theme={null}
OneSignal.setLocationShared(false)
```

```swift theme={null}
OneSignal.Location.isShared = false
```

### `isLocationShared()`

```swift theme={null}
OneSignal.isLocationShared()
```

```swift theme={null}
OneSignal.Location.isShared
```

### `promptLocation()`

```swift theme={null}
OneSignal.promptLocation()
```

```swift theme={null}
OneSignal.Location.requestPermission()
```

***

## Subscription observers

### `addSubscriptionObserver()`

```swift theme={null}
OneSignal.addSubscriptionObserver(subscriptionObserver)
```

```swift theme={null}
OneSignal.User.pushSubscription.addObserver(pushSubscriptionObserver)
```

### `removeSubscriptionObserver()`

```swift theme={null}
OneSignal.removeSubscriptionObserver(subscriptionObserver)
```

```swift theme={null}
OneSignal.User.pushSubscription.removeObserver(pushSubscriptionObserver)
```

***

## Push notifications

### `promptForPushNotifications()`

```swift theme={null}
OneSignal.promptForPushNotifications()
```

```swift theme={null}
OneSignal.Notifications.requestPermission()
```

### `postNotification()` \[Dropped]

```swift theme={null}
OneSignal.postNotification()
```

**User Model**: N/A

### `clearOneSignalNotifications()`

```swift theme={null}
OneSignal.clearOneSignalNotifications()
```

```swift theme={null}
OneSignal.Notifications.clearAll()
```

### `disablePush()`

```swift theme={null}
OneSignal.disablePush(true)
```

```swift theme={null}
OneSignal.User.pushSubscription.optOut()
```

### `unsubscribeWhenNotificationsAreDisabled()` \[Dropped]

```swift theme={null}
OneSignal.unsubscribeWhenNotificationsAreDisabled(false)
```

**User Model**: N/A

### `setLaunchURLsInApp()` \[Dropped]

```swift theme={null}
OneSignal.setLaunchURLsInApp(true)
```

**User Model**: N/A

### `registerForProvisionalAuthorization()`

```swift theme={null}
OneSignal.registerForProvisionalAuthorization({userResponse in ...})
```

```swift theme={null}
OneSignal.Notifications.registerForProvisionalAuthorization({ userReponse in ... })
```

### `setNotificationWillShowInForegroundHandler()`

```swift theme={null}
OneSignal.setNotificationWillShowInForegroundHandler(foregroundHandler)
```

```swift theme={null}
OneSignal.Notifications.addForegroundLifecycleListener(notificationLifecyleHandler)
```

### `setNotificationOpenedHandler()`

```swift theme={null}
OneSignal.setNotificationOpenedHandler(notificationOpenHandler)
```

```swift theme={null}
OneSignal.Notifications.addClickListener(notificationClickListener)
```

### `addPermissionObserver()`

```swift theme={null}
OneSignal.addPermissionObserver(self as OSPermissionObserver)
```

```swift theme={null}
OneSignal.Notifications.addPermissionObserver(notificationPermissionObserver)
```

### `removePermissionObserver()`

```swift theme={null}
OneSignal.removePermissionObserver()
```

```swift theme={null}
OneSignal.Notifications.removePermissionObserver(notificationPermissionObserver)
```

***

## Live activities

### `enterLiveActivity()`

```swift theme={null}
OneSignal.enterLiveActivity("my_activity_id", withToken: myToken)
```

```swift theme={null}
OneSignal.LiveActivities.enter("my_activity_id", withToken: "TOKEN")
```

### `exit()`

```swift theme={null}
OneSignal.exitLiveActivity("my_activity_id")
```

```swift theme={null}
OneSignal.LiveActivities.exit("my_activity_id")
```

***

## In-app messages

### `addTrigger()`

```swift theme={null}
OneSignal.addTrigger("prompt_ios", withValue: "true");
```

```swift theme={null}
OneSignal.InAppMessages.addTrigger("KEY", withValue: "VALUE")
```

### `addTriggers()`

```swift theme={null}
OneSignal.addTriggers(["trigger_key_1": "1", "trigger_key_2": "some_other_value"])
```

```swift theme={null}
OneSignal.InAppMessages.addTriggers(["trigger_key_1": "1", "trigger_key_2": "some_other_value"])
```

### `removeTriggerForKey()`

```swift theme={null}
OneSignal.removeTriggerForKey("trigger_key_1");
```

```swift theme={null}
OneSignal.InAppMessages.removeTrigger("trigger_key_1")
```

### `removeTriggerForKeys()`

```swift theme={null}
OneSignal.removeTriggerForKeys(["trigger_key_1", "trigger_key_2"])
```

```swift theme={null}
OneSignal.InAppMessages.removeTriggers(["trigger_key_1", "trigger_key_2"])
```

### `getTriggerValueForKey()` \[Dropped]

```swift theme={null}
OneSignal.getTriggerValueForKey("trigger_key");
```

**User Model**: N/A

### `inAppMessagesArePaused`

```swift theme={null}
OneSignal.inAppMessagesArePaused = true
```

```swift theme={null}
OneSignal.InAppMessages.paused = true
```

### `setInAppMessageLifecycleHandler()`

```swift theme={null}
OneSignal.setInAppMessageLifecycleHandler(handler)
```

```swift theme={null}
OneSignal.InAppMessages.addLifecycleListener(listener)
```

### `setInAppMessageClickHandler()`

```swift theme={null}
OneSignal.setInAppMessageClickHandler(clickHandler)
```

```swift theme={null}
OneSignal.InAppMessages.addClickListener(clickListener)
```

***

## Email

### `setEmail()`

**User Model** [doc](./mobile-sdk-reference#addemail-%2C-removeemail)

```swift theme={null}
OneSignal.setEmail("email@example.com")
```

```swift theme={null}
OneSignal.User.addEmail("email@example.com")
```

### `logoutEmail()`

```swift theme={null}
OneSignal.logoutEmail()
```

```swift theme={null}
OneSignal.User.removeEmail("email@example.com")
```

***

## SMS

### `setSMSNumber()`

```swift theme={null}
OneSignal.setSMSNumber("+11234567890")
```

```swift theme={null}
OneSignal.User.addSms("+11234567890")
```

### `logoutSMSNumber()`

```swift theme={null}
OneSignal.logoutSMSNumber()
```

```swift theme={null}
OneSignal.User.removeSms("+11234567890")
```

### `addSMSSubscriptionObserver()` \[Dropped]

```swift theme={null}
OneSignal.add(subscriptionObserver)
```

**User Model**: N/A

### `getSMSId()` \[Dropped]

```csharp theme={null}
OneSignal.Default.SMSSubscriptionState.smsUserId
```

**User Model**: N/A

***

## Outcomes

### `sendOutcome()`

```swift theme={null}
OneSignal.sendOutcome("Purchase")
```

```swift theme={null}
OneSignal.Session.addOutcome("Purchase")
```

### `sendOutcomeWithValue()`

```swift theme={null}
OneSignal.sendOutcomeWithValue(withValue: "Purchase", value: 18.76)
```

```swift theme={null}
OneSignal.Session.addOutcome("Purchase", 18.76)
```

### `sendUniqueOutcome()`

```swift theme={null}
OneSignal.sendUniqueOutcome("Swipe")
```

```swift theme={null}
OneSignal.Session.addUniqueOutcome("Swipe")
```

***


# Web SDK Mapping
Source: https://documentation.onesignal.com/docs/en/device-user-model-web-sdk-mapping

Compare OneSignal Web SDK methods between the legacy Player Model and the new User Model. Learn how to migrate your implementation with TypeScript-based code examples and updated method references.

<Warning>
  OneSignal has updated from a device-centric model (Player ID) to a user-centric model (OneSignal ID). For migration guidance, refer to the [User Model Migration Guide](./user-model-migration-guide).

  For documentation on legacy device-centric implementations, see [Version 9](/v9.0/docs/web-push-sdk).
</Warning>

## Overview

This document maps the methods, properties, and events from OneSignal's legacy **Player Model Web SDK** to the newer **User Model** SDK. Each section includes matching TypeScript code examples, clearly demonstrating how to update your integration.

All examples are simplified for demonstration purposes. For complete and up-to-date implementations, refer to the documentation links provided under each method or event.

## OneSignal Service Worker

Update the import in your `OneSignalSDKWorker.js` file:

**Player Model:**

```javascript theme={null}
importScripts('https://cdn.onesignal.com/sdks/OneSignalSDKWorker.js');
```

**User Model:**

```javascript theme={null}
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
```

Keep the file path the same. Just update the `importScripts` URL.

See [OneSignal Service Worker](./onesignal-service-worker) for more information.

## Initialization

### `init()`

**Player Model:** [Docs](/v9.0/docs/web-push-sdk)

```html theme={null}
<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async></script>
<script>
window.OneSignal = window.OneSignal || [];
OneSignal.push(function() {
  OneSignal.init({
    appId: "YOUR_APP_ID"
  });
});
</script>
```

**User Model:** [Docs](./mobile-sdk-reference#initialize)

```html theme={null}
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "YOUR_APP_ID",
  });
});
</script>
```

### `provideUserConsent()`

**Player Model:** [Docs](/v9.0/docs/web-push-sdk)

```typescript theme={null}
OneSignal.provideUserConsent(true)
```

**User Model:** [Docs](./mobile-sdk-reference#setconsentgiven)

```typescript theme={null}
OneSignal.setConsentGiven(true)
```

## Registering for push

### `showNativePrompt()`

**Player Model:**

```typescript theme={null}
OneSignal.showNativePrompt()
```

**User Model:** [Docs](./mobile-sdk-reference#requestpermission-fallbacktosettings-push)

```typescript theme={null}
OneSignal.Notifications.requestPermission()
```

### `registerForPushNotifications()` — Dropped in User Model

```typescript theme={null}
OneSignal.registerForPushNotifications()
```

### `#permissionPromptDisplay`

**Player Model:**

```typescript theme={null}
OneSignal.on('permissionPromptDisplay', () => ...)
```

**User Model:** [Docs](./web-sdk-reference#addeventlistener-push-notification)

```typescript theme={null}
OneSignal.Notifications.addEventListener('permissionPromptDisplay', event => { ... })
```

### `showSlidedownPrompt()`

**Player Model:**

```typescript theme={null}
OneSignal.showSlidedownPrompt()
```

**User Model:** [Docs](./web-sdk-reference#promptpush)

```typescript theme={null}
OneSignal.Slidedown.promptPush()
```

### `showHttpPrompt()` — Dropped in User Model

```typescript theme={null}
OneSignal.showHttpPrompt()
```

### `showCategorySlidedown()`

**Player Model:**

```typescript theme={null}
OneSignal.showCategorySlidedown()
```

**User Model:** [Docs](./web-sdk-reference#promptpushcategories)

```typescript theme={null}
OneSignal.Slidedown.promptPushCategories()
```

### `#getNotificationPermission`

**Player Model:**

```typescript theme={null}
OneSignal.on('getNotificationPermission', (permission) => ...)
```

**User Model:** [Docs](./web-sdk-reference#addeventlistener-push-subscription)

```typescript theme={null}
OneSignal.User.PushSubscription.addEventListener('change', ({ optedIn }) => { ... })
```

### `isPushNotificationsSupported()`

**Player Model:**

```typescript theme={null}
OneSignal.isPushNotificationsSupported()
```

**User Model:** [Docs](./web-sdk-reference#ispushsupported)

```typescript theme={null}
OneSignal.Notifications.isPushSupported()
```

### `isPushNotificationsEnabled()`

**Player Model:**

```typescript theme={null}
await OneSignal.isPushNotificationsEnabled()
```

**User Model:** [Docs](./web-sdk-reference#optedin)

```typescript theme={null}
OneSignal.User.PushSubscription.optedIn
```

### `#subscriptionChange`

**Player Model:**

```typescript theme={null}
OneSignal.on('subscriptionChange', (subscribed) => ...)
```

**User Model:**

```typescript theme={null}
OneSignal.User.PushSubscription.addEventListener('change', ({ token }) => { ... })
```

## Analytics

### `#notificationPermissionChange`

**Player Model:**

```typescript theme={null}
OneSignal.on('notificationPermissionChange', ({ to }) => ...)
```

**User Model:** [Docs](./web-sdk-reference#permissionchange)

```typescript theme={null}
OneSignal.Notifications.addEventListener('permissionChange', permission => { ... })
```

### `#popoverShown`

**Player Model:**

```typescript theme={null}
OneSignal.on('popoverShown', () => ...)
```

**User Model:** [Docs](./web-sdk-reference#addeventlistener-slidedown)

```typescript theme={null}
OneSignal.Slidedown.addEventListener('slidedownShown', presented => { ... })
```

### `#customPromptClick`

**Player Model:**

```typescript theme={null}
OneSignal.on('customPromptClick', ({ result }) => ...)
```

**User Model:** [Docs](./web-sdk-reference#click)

```typescript theme={null}
OneSignal.Notifications.addEventListener('click', ({notification, result}) => { ... })
```

## User IDs

### `getUserId()`

**Player Model:**

```typescript theme={null}
OneSignal.getUserId()
```

**User Model:** [Docs](./web-sdk-reference#id)

```typescript theme={null}
OneSignal.User.PushSubscription.id;
```

### `setExternalUserId()`

**Player Model:** [Docs](./users)

```typescript theme={null}
OneSignal.setExternalUserId("external id")
```

**User Model:** [Docs](./web-sdk-reference#login-external-id)

```typescript theme={null}
OneSignal.login("external id")
```

### `removeExternalUserId()`

**Player Model:**

```typescript theme={null}
OneSignal.removeExternalUserId()
```

**User Model:** [Docs](./web-sdk-reference#logout)

```typescript theme={null}
OneSignal.logout()
```

### `getExternalUserId()`

**Player Model:**

```typescript theme={null}
await OneSignal.getExternalUserId()
```

**User Model:** [Docs](./web-sdk-reference#externalid)

```typescript theme={null}
OneSignal.User.externalId
```

## Tags

### `sendTag()`

**Player Model:**

```typescript theme={null}
OneSignal.sendTag("key", "value")
```

**User Model:**

```typescript theme={null}
OneSignal.User.addTag("key", "value")
```

**User Model** [doc](./web-sdk-reference#addtag-%2C-addtags)

### `sendTags()`

**Player Model:**

```typescript theme={null}
OneSignal.sendTags({ key1: 'value1', key2: 'value2' })
```

**User Model:**

```typescript theme={null}
OneSignal.User.addTags({ key1: 'value1', key2: 'value2' })
```

### `getTags()`

**Player Model:**

```typescript theme={null}
await OneSignal.getTags()
```

**User Model:**

```typescript theme={null}
OneSignal.User.getTags()
```

### `deleteTag()`

**Player Model:**

```typescript theme={null}
OneSignal.deleteTag("key")
```

**User Model:**

```typescript theme={null}
OneSignal.User.removeTag("key")
```

### `deleteTags()`

**Player Model:**

```typescript theme={null}
OneSignal.deleteTags(["key1", "key2"])
```

**User Model:**

```typescript theme={null}
OneSignal.User.removeTags(["key1", "key2"])
```

## Push Notifications

### `sendSelfNotification()` — Dropped in User Model

```typescript theme={null}
OneSignal.sendSelfNotification('title', 'message', 'url')
```

### `setSubscription()`

**Player Model:**

```typescript theme={null}
OneSignal.setSubscription(false)
```

**User Model:**

```typescript theme={null}
OneSignal.Notifications.permission = false
```

## Receiving Notifications

### `#notificationDisplay`

**Player Model:**

```typescript theme={null}
OneSignal.on('notificationDisplay', (event) => { ... })
```

**User Model:**

```typescript theme={null}
OneSignal.Notifications.addEventListener('foregroundWillDisplay', ({ notification }) => { ... })
```

### `#notificationDismiss`

**Player Model:**

```typescript theme={null}
OneSignal.on('notificationDismiss', (event) => { ... })
```

**User Model:**

```typescript theme={null}
OneSignal.Notifications.addEventListener('dismiss', ({ notification }) => { ... })
```

### `#addListenerForNotificationOpened`

**Player Model:**

```typescript theme={null}
OneSignal.on('addListenerForNotificationOpened', (event) => { ... })
```

## Email

### `setEmail()`

**User Model** [doc](./web-sdk-reference#addemail-%2C-removeemail)

**Player Model:**

```typescript theme={null}
OneSignal.setEmail('email@example.com')
```

**User Model:**

```typescript theme={null}
OneSignal.User.addEmail('email@example.com')
```

### `logoutEmail()`

**Player Model:**

```typescript theme={null}
OneSignal.logoutEmail()
```

**User Model:**

```typescript theme={null}
OneSignal.User.removeEmail('email@example.com')
```

### `getEmailId()` — Dropped in User Model

## SMS

### `setSMSNumber()`

**Player Model:**

```typescript theme={null}
OneSignal.setSMSNumber('+11234567890')
```

**User Model:**

```typescript theme={null}
OneSignal.User.addSms('+11234567890')
```

### `logoutSMSNumber()`

**Player Model:**

```typescript theme={null}
OneSignal.logoutSMS()
```

**User Model:**

```typescript theme={null}
OneSignal.User.removeSms('+11234567890')
```

***


# Elasticsearch
Source: https://documentation.onesignal.com/docs/en/elasticsearch

Sync custom events from Elasticsearch to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Elasticsearch integration enables automatic syncing of custom events from your Elasticsearch cluster to OneSignal. This allows you to trigger automated Journeys and personalized messaging campaigns based on user behavioral data stored in your search and analytics engine.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Elasticsearch

* **Elasticsearch cluster** (version 7.0 or higher recommended)
* **Authentication credentials** (API key, username/password, or certificate)
* **Event indices** containing behavioral data with proper document structure
* **Network access** from OneSignal to your Elasticsearch cluster

***

## Setup

<Steps>
  <Step title="Configure Elasticsearch access">
    Ensure OneSignal can connect to your Elasticsearch cluster:

    **For Elasticsearch Cloud:**

    * Navigate to **Security** in your Elasticsearch Cloud console
    * Create an API key with read permissions for event indices
    * Note your **Cloud ID** and **API Key**

    **For Self-hosted Elasticsearch:**

    * Configure authentication (basic auth or API key)
    * Ensure your cluster is accessible from OneSignal's IP addresses
    * Note your cluster **endpoint URL** and **credentials**
  </Step>

  <Step title="Create dedicated user (recommended)">
    Create a dedicated user for OneSignal with read-only access to event indices:

    ```json theme={null}
    PUT _security/user/onesignal_reader
    {
      "password": "strong_password",
      "roles": ["onesignal_events_reader"]
    }

    PUT _security/role/onesignal_events_reader
    {
      "indices": [
        {
          "names": ["events-*", "user_events"],
          "privileges": ["read", "view_index_metadata"]
        }
      ]
    }
    ```
  </Step>

  <Step title="Add integration in OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Elasticsearch** and provide:

    * **Cluster URL**: Your Elasticsearch endpoint (e.g., `https://your-cluster.es.amazonaws.com`)
    * **Authentication Method**: API Key, Basic Auth, or Certificate
    * **Username/Password** or **API Key**: Authentication credentials
    * **Cloud ID** (if using Elasticsearch Cloud): Your deployment Cloud ID
  </Step>

  <Step title="Configure event data source">
    Specify the Elasticsearch index containing your event data:

    * **Index Pattern**: Index or index pattern containing events (e.g., `events-*`)
    * **Event Query**: Optional Elasticsearch Query DSL to filter event documents
    * **Time Field**: Timestamp field for time-based filtering (e.g., `@timestamp`)

    Your event documents should contain fields for:

    * Event name/type (String)
    * User identifier (String)
    * Event timestamp (Date)
    * Additional event properties (Object)
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify OneSignal can access your Elasticsearch cluster and read event data.
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

***

## Advanced Configuration

### Query DSL Filtering

Use Elasticsearch Query DSL to filter and transform event data before syncing to OneSignal:

```json theme={null}
{
  "query": {
    "bool": {
      "must": [
        {
          "range": {
            "@timestamp": {
              "gte": "now-7d"
            }
          }
        },
        {
          "terms": {
            "event_name": ["purchase", "signup", "upgrade"]
          }
        }
      ],
      "must_not": [
        {
          "term": {
            "test_user": true
          }
        }
      ]
    }
  },
  "_source": [
    "event_name",
    "user_id",
    "@timestamp",
    "properties.*"
  ]
}
```

### Index Pattern Configuration

Efficiently query across multiple indices:

* **Time-based indices**: Use patterns like `events-2024-*` for time-partitioned data
* **Routing**: Ensure consistent routing for user-based queries
* **Aliases**: Use index aliases for simplified management

### Performance Optimization

Optimize queries for large event volumes:

* **Field filtering**: Use `_source` filtering to retrieve only necessary fields
* **Scroll API**: For large result sets, OneSignal uses scroll pagination
* **Date math**: Use Elasticsearch date math for efficient time-based filtering

<Warning>
  Ensure your Elasticsearch cluster has sufficient resources to handle OneSignal's queries without affecting other applications using the cluster.
</Warning>

***

## FAQ

### How often does OneSignal sync events from Elasticsearch?

OneSignal syncs event data based on your configured schedule, with a minimum interval of 15 minutes.

### Can I sync events from multiple Elasticsearch indices?

Yes, you can use index patterns (e.g., `events-*`) to query across multiple indices, or create multiple integrations for different index groups.

### What happens if my Elasticsearch cluster is temporarily unavailable?

OneSignal will retry connections with exponential backoff. Event syncing will resume automatically once your cluster is accessible again.


# Email regulatory compliance
Source: https://documentation.onesignal.com/docs/en/email-compliance

Learn how to comply with global privacy and communication regulations when sending marketing emails using OneSignal. This guide covers consent requirements, opt-out rules, and email content regulations across major regions, including the EU, US, Canada, and more.

Most countries have legislation in place to protect individuals’ privacy and regulate how organizations can send email communications. As the sender, it is your legal responsibility to:

* Ensure your messages comply with your own country’s privacy legislation.
* Ensure your messages comply with the privacy laws of each recipient’s country.

OneSignal provides tools to help you manage compliance, but you must implement them appropriately based on your target audience and applicable laws.

***

## Consent requirements for marketing emails

Many countries mandate **explicit consent** (opt-in) before sending marketing emails. These include:

* European Union (under the GDPR)
* United Kingdom
* Canada (under CASL)
* Australia
* New Zealand
* Singapore
* Hong Kong

The United States differs by allowing either opt-in or opt-out, depending on the context and applicable state or federal law. The **CAN-SPAM Act** permits sending marketing emails without prior consent, as long as recipients are allowed to unsubscribe.

### Double opt-in requirements

Some countries, like Germany, recommend or require a double opt-in process. This involves:

1. The user submitting a form requesting marketing emails.
2. A follow-up confirmation email with a link the user must click to complete the subscription.

This additional step provides proof of consent and helps reduce spam complaints.

***

## How to get opt-in consent

At minimum, you should collect clear opt-in consent before sending marketing messages. This can be done using:

* A checkbox on your signup form (unchecked by default) labeled clearly for marketing consent.
* A pop-up or banner that explains what communications users will receive.

If it has been a long time since you've emailed your list, consider sending a **re-consent email campaign** to revalidate their interest and compliance.

***

## Unsubscribe and opt-out requirements

Every marketing email you send must include a **visible and functional "unsubscribe" link**. This allows recipients to opt out of future communications.

Timelines for honoring unsubscribe requests vary:

* **United States (CAN-SPAM)**: Opt-out requests must be honored within 10 business days.
* **GDPR and similar laws**: Opt-out must be honored immediately or without undue delay.

### Best practices for opt-out links

* Place the link in a visible location, typically at the bottom of the email.
* Clearly label it as an unsubscribe or subscription management option.
* Do not require users to log in or take additional steps to opt out.

***

## Email content compliance

Certain regulations also govern the content of your marketing emails:

* **Header and sender info**: You must use accurate "From," "Reply-To," and routing information.
* **Subject line**: Must not be misleading or deceptive.
* **Physical address**: Include your organization's physical mailing address in every message.

These rules are strictly enforced under the **CAN-SPAM Act**, and similar guidelines exist in other jurisdictions.

***

## Managing subscription preferences in OneSignal

OneSignal supports tools to help you comply with email legislation:

* [Unsubscribe Links & Email Subscriptions](./unsubscribe-links-email-subscriptions): Easily manage user opt-outs and preferences.
* [Email Best Practices](./email-setup): Guidance to ensure high deliverability and compliance.
* [Email Acceptable Use Policy & Code of Conduct](https://onesignal.com/aup): Outlines what types of content are allowed.

## We recommend all senders follow these tools and policies to ensure your marketing campaigns are respectful, legally compliant, and effective.


# Engagement trends
Source: https://documentation.onesignal.com/docs/en/engagement-analytics

Track user engagement across push, in-app, email, SMS, and Live Activities with the Engagement Trends chart in OneSignal. View delivery, click-through, and unsubscribe rates, and export to CSV.

The **Engagement Trends** chart on the OneSignal dashboard shows delivery and engagement rates across push, in-app, email, SMS/RCS, and Live Activities over time. It aggregates every message sent from the dashboard, API, or a Journey, and can be exported to CSV.

<Note>
  Engagement Trends retains up to two years of data depending on your pricing plan. Data is available starting January 10, 2025.
</Note>

<Frame>
  <img alt="Engagement Trends chart" />
</Frame>

## Metrics by channel

<Tabs>
  <Tab title="Push">
    | Metric                       | Description                                                                                                                                                                                                                                                                                      |
    | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Delivered                    | The number of push notifications successfully sent to and accepted by the push provider (FCM, APNs, HMS).                                                                                                                                                                                        |
    | Clicked                      | The number of clicks on push notifications. Push notifications can only be clicked once per Subscription.                                                                                                                                                                                        |
    | Unsubscribed                 | The number of push Subscriptions marked unsubscribed because their push token was unregistered, either explicitly or due to [token expiration](./fcm-expired-token-faq). These Subscriptions won't receive further notifications unless they re-subscribe. See [Subscriptions](./subscriptions). |
    | Click-Through Rate           | Calculated as `(Clicked / Delivered) * 100%`.                                                                                                                                                                                                                                                    |
    | Confirmed Receipt Rate       | Percentage of delivered notifications confirmed as received by the device. Calculated as `(Confirmed Receipts / Delivered) * 100%`.                                                                                                                                                              |
    | Unsubscribe Rate             | Calculated as `(Unsubscribed / Delivered) * 100%`.                                                                                                                                                                                                                                               |
    | Confirmed Click-Through Rate | Calculated as `(Clicked / Confirmed Receipts) * 100%`.                                                                                                                                                                                                                                           |

    <Card title="Push message reports" icon="bell" href="./push-notification-message-reports">
      Per-message delivery, click, and confirmed-receipt breakdowns for push notifications.
    </Card>
  </Tab>

  <Tab title="In-app">
    | Metric             | Description                                                                                                                                                                 |
    | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Impressions        | The number of times an in-app message successfully displayed to a Subscription. Depending on your in-app settings, a single Subscription may register multiple impressions. |
    | Clicked            | The number of unique in-app message clicks. Counted once per Subscription.                                                                                                  |
    | Click-Through Rate | The ratio of unique clicks to impressions, expressed as a percentage.                                                                                                       |

    <Card title="In-app message reports" icon="window" href="./in-app-message-reports">
      Per-message impressions, clicks, and click-through rates for in-app messages.
    </Card>
  </Tab>

  <Tab title="Email">
    | Metric             | Description                                                                                                                                                                                                     |
    | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Delivered          | The number of emails successfully delivered to the recipient's inbox server.                                                                                                                                    |
    | Opened             | The number of individual recipients who opened the email. User privacy settings can affect these numbers. See [Email message reports](./email-message-reports).                                                 |
    | Clicked            | The number of individual recipients who clicked a link in the email.                                                                                                                                            |
    | Unsubscribed       | The number of recipients who opted out of further emails using the [unsubscribe link](./unsubscribe-links-email-subscriptions). Email subscriptions are marked unsubscribed immediately on receiving the event. |
    | Click-Through Rate | Calculated as `(Clicked / Delivered) * 100%`.                                                                                                                                                                   |
    | Open Rate          | Calculated as `(Opened / Delivered) * 100%`.                                                                                                                                                                    |
    | Unsubscribe Rate   | Calculated as `(Unsubscribed / Delivered) * 100%`.                                                                                                                                                              |
    | Complaint Rate     | Calculated as `(Reported as Spam / Delivered) * 100%`.                                                                                                                                                          |

    <Card title="Email message reports" icon="envelope" href="./email-message-reports">
      Per-message delivery, open, click, bounce, and unsubscribe breakdowns for emails.
    </Card>
  </Tab>

  <Tab title="SMS">
    | Metric              | Description                                                                                                |
    | :------------------ | :--------------------------------------------------------------------------------------------------------- |
    | Delivered           | The number of messages successfully delivered to the carrier as reported by Twilio.                        |
    | Replied (keywords)  | The number of [keywords](./keywords) received by OneSignal, excluding consent keywords.                    |
    | Unsubscribed        | The number of [opt-out keywords](./sms-consent-keyword-management#opt-out-keywords) received by OneSignal. |
    | Keywords Reply Rate | Calculated as `(Replied (keywords) / Delivered) * 100%`.                                                   |
    | Unsubscribe Rate    | Calculated as `(Unsubscribed / Delivered) * 100%`.                                                         |

    <Card title="SMS message reports" icon="comment-sms" href="./sms-message-reports">
      Per-message delivery, reply, and unsubscribe breakdowns for SMS and RCS messages.
    </Card>
  </Tab>

  <Tab title="Live Activities">
    | Metric            | Description                                                                                                                                                                                                |
    | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Sent              | The number of Live Activity updates sent from OneSignal, including those successfully sent to APNs and failures. This is a composite metric and includes push-to-start and push-to-update notifications.   |
    | Delivered         | The number of Live Activity updates successfully sent to and accepted by APNs.                                                                                                                             |
    | Confirmed Receipt | The number of Live Activity updates confirmed as received by the device, verified by the OneSignal SDK. Requires iOS SDK 5.2.15+. See [Confirmed receipt](./confirmed-delivery) for platform requirements. |
    | Failed            | The number of push subscriptions that did not receive the Live Activity update because of an error.                                                                                                        |
    | Unsubscribed      | The number of push subscriptions marked unsubscribed when users dismiss a Live Activity or disable Live Activities in device settings.                                                                     |
    | Clicked           | The total number of clicks across all Live Activity updates, including repeat clicks from the same user.                                                                                                   |

    <Card title="Live Activities analytics" icon="bolt" href="./live-activities-analytics">
      Delivery, confirmed receipt, and click breakdowns for iOS Live Activities.
    </Card>
  </Tab>
</Tabs>

<Card title="Metrics glossary" icon="book" href="./analytics-metrics-glossary">
  Canonical definitions for every metric across the dashboard, API, CSV, and Event Streams.
</Card>

## Export chart data

<Steps>
  <Step title="Filter the chart">
    Set the time range and messaging channel you want to export.
  </Step>

  <Step title="Start the export">
    Click the export button at the top right of the chart.
  </Step>

  <Step title="Receive the CSV">
    OneSignal emails the CSV to the address on your current OneSignal user account. The file contains per-day engagement statistics for the filtered range.
  </Step>
</Steps>

## FAQ

### How far back does Engagement Trends data go?

Data is available starting January 10, 2025. Retention is up to two years depending on your pricing plan.

### Why do my Engagement Trends numbers differ from an individual message report?

Engagement Trends aggregates every message sent in the filtered time range across the selected channel, including messages sent from the API and Journeys. Individual message reports show only that one send. Small rounding differences between the rate calculations shown here and on per-message reports can also occur because Engagement Trends groups by day.

### Why does SMS **Delivered** on this chart differ from the count in Twilio?

OneSignal's SMS **Delivered** reflects carrier-confirmed receipt reported back by Twilio. Differences usually come from messages still in flight at comparison time, late status callbacks from carriers, or messages that moved to **Provider Undelivered** after initial acceptance. See the [Metrics glossary](./analytics-metrics-glossary) for the full SMS lifecycle.

### Can I get raw per-event data instead of aggregated daily statistics?

Yes. Use [Event Streams](./event-streams) to forward real-time message events to your own analytics stack, or [Exporting data](./exporting-data) to download the Notifications CSV for a range of messages.

### Why is Live Activities **Unsubscribed** counted when a user dismisses the activity?

Once a user dismisses a Live Activity or disables Live Activities in device settings, APNs returns an error indicating the activity token is no longer valid. OneSignal counts these push subscriptions as unsubscribed for Live Activity delivery and stops sending further updates.

## Related

<Columns>
  <Card title="Metrics glossary" icon="book" href="./analytics-metrics-glossary">
    Canonical definitions for every metric across push, email, SMS/RCS, in-app, and Live Activities.
  </Card>

  <Card title="Analytics overview" icon="chart-line" href="./analytics-overview">
    Tour the dashboards, APIs, and export tools OneSignal provides for measuring performance.
  </Card>

  <Card title="Event Streams" icon="satellite-dish" href="./event-streams">
    Send real-time message events to your warehouse for custom analysis.
  </Card>

  <Card title="Exporting data" icon="file-export" href="./exporting-data">
    Export message and subscription data to CSV for offline analysis.
  </Card>
</Columns>


# EU-US Data Privacy Framework
Source: https://documentation.onesignal.com/docs/en/eu-us-data-privacy-framework



## Why is the EU-US Data Privacy Framework important?

The Framework provides EU individuals whose data would be transferred to participating companies in the US with several new rights (e.g. to obtain access to their data, or obtain correction or deletion of incorrect or unlawfully handled data). In addition, it offers different redress avenues in case their data is wrongly handled, including before free of charge independent dispute resolution mechanisms and an arbitration panel.This is particularly important for US companies who work with data on EU individuals as it proves there are safeguards in place in maintaining the rights afforded to EU individuals that are recognized by EU Commission. It maintains that handling and accessing data from outside the EU by certified companies is regulated and overseen by this joint agreement.

## Is OneSignal certified?

Yes. OneSignal is a certified company on the public registry found [here](https://www.dataprivacyframework.gov/list).

***


# Event Streams
Source: https://documentation.onesignal.com/docs/en/event-streams

Send message data out of OneSignal in real-time to your chosen destination.

Event Streams allows you to send message data out of OneSignal in real-time to your chosen destination. Event streams are a great way to connect OneSignal to other products within your marketing ecosystem. They enable your team to trigger corresponding messaging, maintain records, and much more.

Available event types include:

* Push message events (sent, received, clicked, failed, unsubscribed)
* Email events (sent, opened, clicked, bounced, unsubscribed, etc.)
* SMS events (sent, failed, unsubscribed, etc.)
* In-app message events (impression, clicked, etc.)
* Live Activity events (sent, delivered, confirmed receipt, failed, unsubscribed, clicked)

## Common use cases

* **Centralize engagement data** — Stream events to a CRM, CDP, or data warehouse so cross-channel activity (opens, clicks, bounces) lives in one place instead of across disconnected tools.
* **Analytics, reporting, and compliance** — Land every message event in a warehouse for trend analysis, auditing, or regulatory record-keeping.
* **Monitor disengagement** — Track unsubscribes, bounces, and dismissals in your own systems to spot retention risks early.
* **Trigger external workflows** — Fire automations in other tools when a user opens or clicks a message (e.g., update a lead score, start a follow-up sequence).
* **Replace batch syncs and extra integrations** — React to events in real-time and connect OneSignal directly to your destination, cutting intermediary tools and maintenance cost.

### Getting your technical team started

Setting up Event Streams is a joint effort between the marketing/product owner (who decides *which* events matter and *where* they go) and the engineering team (who builds the receiving endpoint and configures the stream). Here's what the engineering side involves:

1. **Decide on a destination and scope** — Agree on where events should land (your own API, a data warehouse, a CDP, etc.), which event types to stream (push, email, SMS, IAM, Live Activity), and an estimate of message volume so the endpoint is sized appropriately.
2. **Set up an HTTP endpoint** — Build or configure a publicly reachable endpoint that accepts POST requests. It should record events quickly without heavy processing to keep response times low. See [Retries / Disabling](#retries--disabling) for performance expectations and what happens when the endpoint falls behind.
3. **Configure the Event Stream in OneSignal** — In **Data > Event Streams**, select events, set the URL and authentication headers, and define the JSON body using [Event Streams Data](./event-streams-data) fields with [Liquid syntax](./using-liquid-syntax).
4. **Test end-to-end** — Use [webhook.site](https://webhook.site) to verify the payload shape and headers before switching to your production endpoint (see [Testing](#testing)).

***

## Setup

You can configure a new event stream for your OneSignal application under **Data > Event Streams > New Event Stream**.

<Frame>
  <img alt="New Event Stream button" />
</Frame>

**Requirements**

Events can't be sent unless the following requirements are met:

* A valid URL or IP address for a publicly reachable **HTTP(S) endpoint**
* URLs and IP addresses must be publicly routable
* Domains must include a recognized top-level domain (e.g., ".com", ".net")

### Event Selection

Name your Event Stream and click **Select Events**.

<Frame>
  <img alt="Event stream setup showing Select Events and webhook trigger options" />
</Frame>

This will open the Event Selection page where you can select the events you want to trigger your event stream.

<Warning>
  Each event counts toward your plan's message-event volume. Streaming **every** event type (especially `sent`) for a large audience can use your allowance quickly — for example, a single send to 100,000 users generates 100,000 `sent` events alone.

  To manage volume:

  * **Select only the event types you need** — e.g., `received` and `clicked` may be sufficient if you don't need send-level tracking.
  * **Use [event stream filters](#event-stream-filters)** to limit events to specific messages or templates instead of streaming all traffic.
</Warning>

<Frame>
  <img alt="Event stream event selection with channel and event types checked" />
</Frame>

#### Event stream filters

You can optionally further refine events by specifying the identifiers of one or more messages or templates, enabling you to receive only events related to specific messages.

<Frame>
  <img alt="Event stream filter fields for message and template IDs" />
</Frame>

Template identifiers can be copied by navigating to **Messages > Templates**. Next to the template you want to track, select **Options > Copy Template ID** and paste it into the Event Stream filters.

<Frame>
  <img alt="Message action menu with Copy Template ID option" />
</Frame>

### Configure the Event Stream

Select the HTTP method, the URL, and add headers for the event stream. This is where authentication should be configured to ensure secure communication between OneSignal and your systems.

The URI and Headers can contain liquid syntax which will come from both the user properties and properties of the event stream.

#### Authentication Headers

You can add authentication headers to validate that requests to your endpoint are genuinely from OneSignal. Common authentication methods include:

* **Authorization Header**: Add an `Authorization` header, where `YOUR_TOKEN` is provided by your system or 3rd party like:
  * `Basic {{YOUR_TOKEN}}`
  * `Bearer {{YOUR_TOKEN}}`
  * `ApiKey {{YOUR_API_KEY}}`
* **Custom Headers**: You can also add custom headers like:
  * `X-API-Key: {{YOUR_API_KEY}}`

*Note: OneSignal does not provide encryption services*

#### Testing Your Configuration

If you are looking for an easy way to test, use [webhook.site](https://webhook.site). Find "Your unique URL" in the center of the page. Copy that URL and use it in the URL field of your event stream configuration.

<Frame>
  <img alt="Event stream URL field configured with webhook.site test URL" />
</Frame>

#### Disallowed headers

The following headers are restricted and can't be set.

* `content-length`
* `referer`
* `metadata-flavor`
* `x-google-metadata-request`
* `host`
* `x-onesignal*`

### Body

The body for an event stream will be JSON. The body JSON can be defined either as individual key/value pairs or as an editable code block. To change the input method use the first dropdown under the body heading and select the custom body.

<Frame>
  <img alt="Event stream body editor with key value and custom body options" />
</Frame>

On the right, you can see an example cURL request built from what has been input during event stream setup.

<Frame>
  <img alt="cURL preview panel for configured event stream request" />
</Frame>

### Personalization

You can personalize all fields in your Event Stream with predefined [Event Streams Data](./event-streams-data). This data can be added using [Liquid Syntax](./using-liquid-syntax). This gives you the flexibility to use event streams for nearly any use case.

<Info>
  See [Event Streams Data](./event-streams-data) for a list of all event, message, and user event data available for personalization.
</Info>

#### Example body

Select the "Custom Body" in the drop-down:

```json JSON theme={null}
{
  "Event Data": {
    "event.kind": "{{ event.kind }}",
    "event.id": "{{ event.id }}",
    "event.timestamp": "{{ event.timestamp }}",
    "event.datetime": "{{ event.datetime }}",
    "event.app_id": "{{ event.app_id }}",
    "event.subscription_device_type": "{{ event.subscription_device_type }}",
    "event.subscription_id": "{{ event.subscription_id }}",
    "event.onesignal_id": "{{ event.onesignal_id }}",
    "event.external_id": "{{ event.external_id }}",
    "event.data.page_name": "{{ event.data.page_name}}",
    "event.data.page_id": "{{ event.data.page_id}}",
    "event.data.target_name": "{{ event.data.target_name}}",
    "event.data.target_id": "{{ event.data.target_id}}",
    "event.data.failure_reason": "{{ event.data.failure_reason}}"
  },
  "Message Data": {
    "message.id": "{{ message.id }}",
    "message.name": "{{ message.name }}",
    "message.title": "{{ message.title.en }}",
    "message.contents": "{{ message.contents.en }}",
    "message.template_id": "{{ message.template_id }}",
    "message.url": "{{ message.url }}",
    "message.app_url": "{{ message.app_url }}",
    "message.web_url": "{{ message.web_url }}"
  }
}
```

<Frame>
  <img alt="Event stream custom JSON body with Liquid placeholders" />
</Frame>

#### Using Liquid Syntax in JSON

When using Liquid syntax within JSON, proper quoting depends on the data type:

**Guidelines for JSON Formatting**

* **Strings** → **Must** wrap in quotes.
* **Numbers** → **Don't** wrap in quotes.
* **Objects** → **Must** not be wrapped in quotes.

<Note>
  The `//` comment lines in the **Correct** examples below are for readability only. Remove them in your real Event Stream body—strict JSON does not allow `//` comments.
</Note>

**Examples**

<Tabs>
  <Tab title="Strings">
    **✅ Correct** — wrap in quotes:

    ```liquid JSON theme={null}
    {
      "user_id": "{{ user.onesignal_id }}"
    }
    ```

    **❌ Incorrect** — missing quotes produces invalid JSON:

    ```liquid JSON theme={null}
    {
      "user_id": {{ user.onesignal_id }}
    }
    ```
  </Tab>

  <Tab title="Numbers & Booleans">
    **✅ Correct** — no quotes:

    ```liquid JSON theme={null}
    {
      "user_score": {{ user.tags.score }}
    }
    ```

    **❌ Incorrect** — quotes turn the number into a string:

    ```liquid JSON theme={null}
    {
      "user_score": "{{ user.tags.score }}"
    }
    ```
  </Tab>

  <Tab title="Objects">
    **✅ Correct** — no quotes:

    ```liquid JSON theme={null}
    {
      "user_data": {{ user.tags }}
    }
    ```

    **❌ Incorrect** — quotes turn the object into a string:

    ```liquid JSON theme={null}
    {
      "user_data": "{{ user.tags }}"
    }
    ```
  </Tab>
</Tabs>

**Best practices for handling multilingual conditionals in liquid syntax**

To avoid issues with language-based conditionals

1. **Use Direct Language Checks**: Always check `user.language` directly in conditionals, not in variables like `userLang`, for better compatibility.
2. **Start Simple**: Begin with basic phrases, then gradually add complexity.
3. **Avoid Over-Nesting**: Keep conditionals flat to prevent parsing issues.
4. **Test Basic Punctuation First**: Start with simple sentences and punctuation before using special characters.
5. **Use Fallbacks**: Ensure a default language (e.g., English) in case of missing translations.
6. **Stick to Standard Keys**: Use standard OneSignal keys like `content/title/en` for reliability.

This approach minimizes parsing errors and ensures compatibility with the system.

<Info>
  For details and options on how to personalize your messages using Liquid syntax, check out our [Using Liquid Syntax Guide](./using-liquid-syntax).
</Info>

***

## Results & Debugging

Monitoring your Event Stream's performance and troubleshooting issues:

**Report tab** — Shows all-time totals, the current status of your event stream, and a time-series chart of HTTP response codes over time.

| Response      | Meaning                                                                                                                      |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **2xx**       | The event was successfully received by your endpoint.                                                                        |
| **4xx / 5xx** | Your endpoint returned an error. Check the Logs tab for the specific status code and response body.                          |
| **Timeout**   | Your endpoint did not respond within the allowed window. OneSignal closed the connection and treated the delivery as failed. |

**Logs tab** — Displays a sample of recent requests, including the full request body, headers, and the response from your endpoint. This is the best place to start when debugging — you can see exactly what OneSignal sent and what your server returned.

If the payload or configuration needs adjusting, edit the event stream and use the **Send Test** button to send sample requests. Iterate until the payload matches what your endpoint expects, then go live.

<Frame>
  <img alt="Event stream report with charts and HTTP response status over time" />
</Frame>

### Retries / Disabling

**Retry behavior** — When a request fails with a recoverable status (e.g. `429`), OneSignal retries with increasing delays. If retries for a single event keep failing, that event is marked as permanently failed and is not retried again.

**Auto-disabling** — If your endpoint returns sustained failures across many events, OneSignal may disable the entire event stream. When this happens:

1. App and org admins receive an email when failure volume becomes significant (before disabling) and again when the stream is disabled.
2. A banner also appears on the **Event Streams** index page in the dashboard.
3. Fix the underlying issue, test with the **Logs** tab or [webhook.site](https://webhook.site), and re-enable the stream.

**Performance guidance** — Your endpoint should be able to handle the volume of events your message sends produce. To avoid backlogs and disablement:

* **Record events quickly** — Write the incoming event to a queue or data store without heavy inline processing.
* **Avoid slow responses and 429s** — Consistent slow response times or rate-limit responses cause events to back up, which leads OneSignal to disable the stream.
* **Size for your send volume** — If you send 100k messages, expect up to 100k events per selected event type. Review your plan's message volume and provision accordingly.

**Deduplication** — Each delivered event includes a unique `event.id`. Include it in a header or the JSON body so your system can deduplicate if the same event is retried or replayed.

### Tips for Success

* **Point streams at your own servers first.** You *can* connect directly to a third-party API, but debugging, rate-limit handling, and volume management are harder when you don't control the receiving end.
* **Buffer before forwarding to third parties.** OneSignal sends events as fast as users trigger them — a large send can produce a burst that overwhelms external rate limits or runs up costs (especially with SMS providers). Build a lightweight service that accepts events, queues them, and forwards to external APIs at a pace you control.
* **Check third-party API docs.** Many services expose public HTTP APIs you can target with an event stream. Look for their docs on authentication, accepted payload format, and rate limits before configuring your stream.

### Message event data limitations

Data for messages sent via our Journeys or API are only available in OneSignal for 30 days. This means that any message events (like clicks, opens, unsubscribes, etc.) that happen 30+ days after the Journey or API message was sent, will not be available in the event stream. This may appear as blank or missing data in your analytics.

To work around this limitation, correlate the `message.id` of these clicked/opened/unsubscribed events with the original `sent` event that has the same `message.id`. The original `sent` event should have the relevant message data (title, template, etc.).

***

## Testing

End-to-end testing walkthrough using [webhook.site](https://webhook.site). Paste **Your unique URL** into the Event Stream **URL** field with the **POST** method.

<Frame>
  <img alt="Event stream URL field matching webhook.site unique URL" />
</Frame>

Set the events you want to track. In this example, we will use the push events, but any will work.

<Frame>
  <img alt="Event selection with push message events checked for testing" />
</Frame>

In this example, we will use the above [Example body](#body).

Save the event and set it live.

Send a message to trigger the event. In webhook.site we will see the event with the following data:

<Frame>
  <img alt="webhook.site showing incoming event stream request body and headers" />
</Frame>

This shows the following:

* **Host**: the IP address where the request came from. See [REST API overview](/reference/rest-api-overview) for a list of possible IPs.
* **Request Content**: the data sent in the body of the event stream.

***


# Event Stream data reference
Source: https://documentation.onesignal.com/docs/en/event-streams-data

Schema reference for all event, message, user, and subscription properties available in Event Streams and Webhooks, with Liquid syntax for each field.

Access event stream data [using Liquid syntax](./using-liquid-syntax). Wrap any field in `{{ }}` to include it in your Event Stream body. See [Examples](./event-streams#example-body).

<Warning>
  Message data for Journeys and API sends is retained for 30 days. Interaction events (clicks, opens, unsubscribes) that occur after 30 days may have blank message properties. To recover the data, correlate the `message.id` from the interaction event with the original `sent` event, which contains the full message data.
</Warning>

## `event` properties

Every event includes the core fields below. Channel-specific fields under `event.data.*` are included only when applicable — see [Channel-specific fields](#channel-specific-fields).

<ParamField type="string">
  The event type, combining channel and action (e.g. `message.push.clicked`, `message.email.bounced`). See the full list of values in the [event kind reference](#event-kind-reference) below. **Liquid:** `{{ event.kind }}`
</ParamField>

<ParamField type="string">
  A unique, OneSignal-generated identifier for each individual event in UUID v4 format. Use this ID for idempotent delivery tracking. For the message or template identifier, use [`message.id`](#message-id) or [`message.template_id`](#template-id). **Liquid:** `{{ event.id }}`
</ParamField>

<ParamField type="integer">
  UNIX timestamp of the event. **Liquid:** `{{ event.timestamp }}`
</ParamField>

<ParamField type="string">
  Human-readable time of the event in UTC as an ISO 8601 string (e.g., "2024-02-21T23:45:15.228Z"). **Liquid:** `{{ event.datetime }}`
</ParamField>

<ParamField type="string">
  The OneSignal [App ID](./keys-and-ids). **Liquid:** `{{ event.app_id }}`
</ParamField>

<ParamField type="string">
  The subscription's platform or channel (e.g., `iOS`, `Android`, `Email`, `SMS`). For web push, this is the user's browser (e.g., `Chrome`, `Firefox`, `Safari`, `Edge`). **Liquid:** `{{ event.subscription_device_type }}`
</ParamField>

<ParamField type="string">
  The OneSignal [Subscription ID](./subscriptions) for the subscription that received this message. This is the same value as [`user.subscription.id`](#user-subscription-properties) — both fields are provided so you can address the subscription from either the event or user namespace. **Liquid:** `{{ event.subscription_id }}`
</ParamField>

<ParamField type="string">
  The OneSignal [User ID](./users) (UUID v4 format). **Liquid:** `{{ event.onesignal_id }}`
</ParamField>

<ParamField type="string">
  Your user ID set as the OneSignal [External ID](./users) alias. Empty if no External ID has been set on the user. **Liquid:** `{{ event.external_id }}`
</ParamField>

### Channel-specific fields

Some event kinds carry extra context that doesn't apply to other channels — for example, the `target_id` of a button tapped in an in-app message, or the `failure_reason` for a bounced email. These fields are namespaced under `event.data.*` so the top-level `event.*` schema stays consistent across all event kinds. A field is populated only when the event kind includes it; otherwise it renders as an empty string.

#### In-app message events

Included with `message.iam.*` events. See [In-app message Event Streams](./iam-event-streams) for details.

<ParamField type="string">
  The name of the in-app message page or card displayed. **Liquid:** `{{ event.data.page_name }}`
</ParamField>

<ParamField type="string">
  Unique identifier for the in-app message page or card displayed. **Liquid:** `{{ event.data.page_id }}`
</ParamField>

<ParamField type="string">
  The name of the button or image block element clicked. The element must contain an [in-app click action](./iam-click-actions). **Liquid:** `{{ event.data.target_name }}`
</ParamField>

<ParamField type="string">
  Unique identifier for the button or image block element clicked. **Liquid:** `{{ event.data.target_id }}`
</ParamField>

#### Live Activity events

Included with `message.live_activity.*` events.

<ParamField type="string">
  Unique identifier for a specific Live Activity (e.g., "Knicks vs Cavs - Oct 22 7PM"). **Liquid:** `{{ event.data.live_activity_id }}`
</ParamField>

<ParamField type="string">
  Grouping label for Live Activity categories (e.g., "Knicks\_games"). **Liquid:** `{{ event.data.live_activity_type }}`
</ParamField>

#### Failed events

Included with `message.push.failed` and `message.email.failed` events.

<ParamField type="string">
  The reason the message failed to send. See [Push Message Reports](./push-notification-message-reports#failure-message-troubleshooting) or [Email Message Reports](./email-message-reports#why-are-my-emails-marked-as-failed) for common reasons. **Liquid:** `{{ event.data.failure_reason }}`
</ParamField>

### Event kind reference

For detailed definitions of each metric, see the [Metrics Glossary](./analytics-metrics-glossary).

<Note>
  `message.push.received` is only emitted when [Confirmed receipt](./confirmed-delivery) is enabled. Without it, OneSignal cannot determine whether a push notification reached the device. If your Event Stream depends on this event, verify confirmed receipt is enabled for your app first — otherwise these events will simply never fire.
</Note>

| Message Event Kind (OneSignal) | Event name (in data set)             | Event Description                                                                                                                                                                   |
| ------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Push Sent                      | `message.push.sent`                  | Push notification successfully sent to the push services (FCM, APNS, etc).                                                                                                          |
| Push Received                  | `message.push.received`              | Push notification received by recipient. Not available on all platforms. See [Confirmed receipt](./confirmed-delivery) for more details.                                            |
| Push Clicked                   | `message.push.clicked`               | User tapped the push notification to open the app on device.                                                                                                                        |
| Push Failed                    | `message.push.failed`                | Push failed to be sent. See [Push Message Reports](./push-notification-message-reports) for details.                                                                                |
| Push Unsubscribed              | `message.push.unsubscribed`          | User unsubscribed on push [subscription](./subscriptions). See [When do push subscription statuses update?](./subscriptions#when-do-push-subscription-statuses-update%3F).          |
| In-App Impression              | `message.iam.impression`             | In-App Message successfully displayed on device.                                                                                                                                    |
| In-App Clicked                 | `message.iam.clicked`                | User tapped an element on the In-App Message.                                                                                                                                       |
| In-App Page Displayed          | `message.iam.page_displayed`         | In-App Message page was displayed. Helpful for tracking carousels.                                                                                                                  |
| Email Sent                     | `message.email.sent`                 | Email successfully sent.                                                                                                                                                            |
| Email Received                 | `message.email.received`             | Email received by recipient.                                                                                                                                                        |
| Email Opened                   | `message.email.opened`               | Email was opened by recipient. See [Email Message Reports](./email-message-reports) for details.                                                                                    |
| Email Link Clicked             | `message.email.clicked`              | User tapped a link in the email.                                                                                                                                                    |
| Email Unsubscribed             | `message.email.unsubscribed`         | User unsubscribed from email via the [unsubscribe link](./unsubscribe-links-email-subscriptions).                                                                                   |
| Email Reported As Spam         | `message.email.reported_as_spam`     | User reported the email as spam. Gmail requires [Google Postmaster Tools](./google-postmaster-tools) to track. See [Email deliverability](./email-deliverability) for more details. |
| Email Bounced                  | `message.email.bounced`              | Email returned to sender due to permanent error. See [Email Message Reports](./email-message-reports) for details.                                                                  |
| Email Failed                   | `message.email.failed`               | Email could not be delivered. See [Email Message Reports](./email-message-reports) for details.                                                                                     |
| Email Suppressed               | `message.email.suppressed`           | Email could not be sent because the email address is on the [Suppression list](./email-deliverability).                                                                             |
| SMS Sent                       | `message.sms.sent`                   | SMS sent to recipient.                                                                                                                                                              |
| SMS Failed                     | `message.sms.failed`                 | SMS failed to send. See [SMS Message Reports](./sms-message-reports) for details.                                                                                                   |
| SMS Delivered                  | `message.sms.delivered`              | SMS successfully delivered.                                                                                                                                                         |
| SMS Undelivered                | `message.sms.undelivered`            | SMS could not be sent. See [SMS Message Reports](./sms-message-reports) for details.                                                                                                |
| Live Activity Sent             | `message.live_activity.sent`         | Live Activity successfully sent to FCM/APNS.                                                                                                                                        |
| Live Activity Delivered        | `message.live_activity.delivered`    | Live Activity received by recipient.                                                                                                                                                |
| Live Activity Unsubscribed     | `message.live_activity.unsubscribed` | User unsubscribed from Live Activities.                                                                                                                                             |
| Live Activity Failed           | `message.live_activity.failed`       | Live Activity failed to send.                                                                                                                                                       |
| Live Activity Clicked          | `message.live_activity.clicked`      | Live Activity clicked by user.                                                                                                                                                      |

### Example event object

Copy this Liquid template into your Event Stream body to capture all event fields:

```json JSON theme={null}
{
  "event.kind": "{{ event.kind }}",
  "event.id": "{{ event.id }}",
  "event.timestamp": "{{ event.timestamp }}",
  "event.datetime": "{{ event.datetime }}",
  "event.app_id": "{{ event.app_id }}",
  "event.subscription_device_type": "{{ event.subscription_device_type }}",
  "event.subscription_id": "{{ event.subscription_id }}",
  "event.onesignal_id": "{{ event.onesignal_id }}",
  "event.external_id": "{{ event.external_id }}",
  "event.data.page_name": "{{ event.data.page_name }}",
  "event.data.page_id": "{{ event.data.page_id }}",
  "event.data.target_name": "{{ event.data.target_name }}",
  "event.data.target_id": "{{ event.data.target_id }}",
  "event.data.failure_reason": "{{ event.data.failure_reason }}"
}
```

<Accordion title="Example rendered output">
  What a push click event looks like after Liquid rendering:

  ```json JSON theme={null}
  {
    "event.kind": "message.push.clicked",
    "event.id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "event.timestamp": 1708559115,
    "event.datetime": "2024-02-21T23:45:15.228Z",
    "event.app_id": "your-onesignal-app-id",
    "event.subscription_device_type": "iOS",
    "event.subscription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "event.onesignal_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "event.external_id": "user_12345",
    "event.data.page_name": "",
    "event.data.page_id": "",
    "event.data.target_name": "",
    "event.data.target_id": "",
    "event.data.failure_reason": ""
  }
  ```

  Channel-specific fields like `event.data.page_name` are empty for event kinds that don't include them.
</Accordion>

## `message` properties

The `message` object describes the message sent to the end-user, including its ID, template, content, and URLs.

<ParamField type="string">
  The message ID generated by OneSignal. **Liquid:** `{{ message.id }}`
</ParamField>

<ParamField type="string">
  The name of the message as set in the dashboard or using the API `name` property. **Liquid:** `{{ message.name }}`
</ParamField>

<ParamField type="object">
  The push message title or email subject. For push, returns a localized object like `{'en':'Your title'}`. For email, returns the subject line as a plain string. Set via the dashboard or the API `headings` / `email_subject` properties. **Liquid:** `{{ message.title }}`
</ParamField>

<Tip>
  For push events, dumping `{{ message.title }}` directly into a JSON webhook body produces a Python-style dict (`{'en':'…'}`) rather than valid JSON, which breaks downstream parsers. To extract the locale string, use dot notation: `{{ message.title.en }}` (or `{{ message.title.es }}`, `{{ message.title.fr }}`, etc.). For multi-language apps, branch on `{{ user.language }}` to pick the matching key.
</Tip>

<ParamField type="object">
  The push or SMS message content (clipped at 50 characters). Email contents (`email_body`) are not provided. Set via the dashboard or the API `contents` property. **Liquid:** `{{ message.contents }}`
</ParamField>

<ParamField type="string">
  The template ID for a message sent via Journeys or the API `template_id` property. **Liquid:** `{{ message.template_id }}`
</ParamField>

<ParamField type="string">
  The message's launch URL when using a single URL that is web and app agnostic. See [URLs, Links and Deep Links](./links). **Liquid:** `{{ message.url }}`
</ParamField>

<ParamField type="string">
  The app-specific launch URL when using separate web and app URLs. See [URLs, Links and Deep Links](./links). **Liquid:** `{{ message.app_url }}`
</ParamField>

<ParamField type="string">
  The web-specific launch URL when using separate web and app URLs. See [URLs, Links and Deep Links](./links). **Liquid:** `{{ message.web_url }}`
</ParamField>

<ParamField type="object">
  Custom key-value pairs from the `data` property on the notification, set via the dashboard or the API `data` property. Limited to one level of JSON. Use `{{ message.data }}` to return all properties, or `{{ message.data.key }}` for a specific key.
</ParamField>

<ParamField type="object">
  Custom key-value pairs from the `custom_data` property on the notification (API only). Supports multiple levels of JSON. Use `{{ message.custom_data }}` to return all properties, or `{{ message.custom_data.key }}` for a specific key.
</ParamField>

<ParamField type="string">
  The Live Activity action type: `start`, `update`, or `end`. Only present for `message.live_activity.*` events. **Liquid:** `{{ message.live_activity_event_kind }}`
</ParamField>

### Example message object

Copy this Liquid template into your Event Stream body to capture all message fields:

```json JSON theme={null}
{
  "message.id": "{{ message.id }}",
  "message.name": "{{ message.name }}",
  "message.title": "{{ message.title }}",
  "message.contents": "{{ message.contents }}",
  "message.template_id": "{{ message.template_id }}",
  "message.url": "{{ message.url }}",
  "message.app_url": "{{ message.app_url }}",
  "message.web_url": "{{ message.web_url }}",
  "message.data": "{{ message.data }}",
  "message.custom_data": "{{ message.custom_data }}"
}
```

<Accordion title="Example rendered output">
  A push notification message:

  ```json JSON theme={null}
  {
    "message.id": "f3c9cd09-10d7-4f59-b9bc-66e16607f1d5",
    "message.name": "weekly-promo-push",
    "message.title": "{'en':'Flash Sale: 50% Off Today'}",
    "message.contents": "{'en':'Shop now and save on select items'}",
    "message.template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message.url": "https://example.com/sale",
    "message.app_url": "",
    "message.web_url": "",
    "message.data": {"url": "https://example.com/sale"}
  }
  ```

  An email message — `message.title` is the subject line as a plain string, and `message.contents` is empty because email body content is not included in Event Stream data:

  ```json JSON theme={null}
  {
    "message.id": "e2d3c4b5-a6f7-8901-bcde-f12345678901",
    "message.name": "onboarding-welcome-email",
    "message.title": "Welcome to Acme — here's how to get started",
    "message.contents": "",
    "message.template_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "message.url": "",
    "message.app_url": "",
    "message.web_url": "",
    "message.data": {},
    "message.custom_data": {}
  }
  ```
</Accordion>

## `user` properties

The `user` object contains profile-level data for the user who received the message.

<ParamField type="string">
  The user's OneSignal ID. **Liquid:** `{{ user.onesignal_id }}`
</ParamField>

<ParamField type="string">
  The user's External ID. **Liquid:** `{{ user.external_id }}`
</ParamField>

<ParamField type="object">
  The user's [tags](./add-user-data-tags). Access the full object with `{{ user.tags }}` or a specific tag with `{{ user.tags.your_tag }}`. Use a default to handle missing tags: `{{ user.tags.your_tag | default: '' }}`.
</ParamField>

<ParamField type="string">
  The user's language code. **Liquid:** `{{ user.language }}`
</ParamField>

<Note>
  **Email addresses and phone numbers aren't on `user.*`.** Email and phone are stored as [subscriptions](./subscriptions), not user attributes. To reference the recipient address from an event, use [`user.subscription.subscription_token`](#user-subscription-properties) — for email subscriptions this is the email address, and for SMS subscriptions it is the phone number in E.164 format.
</Note>

<Note>
  If you send dozens of [tags](./add-user-data-tags) per user, dumping the entire `{{ user.tags }}` object into every webhook body can push payloads past the receiver's size limit (most platforms cap inbound webhooks at 1–2 MB). Reference only the specific tags you need (`{{ user.tags.subscription_status }}`, `{{ user.tags.loyalty_tier }}`, etc.) rather than the whole object.
</Note>

## `user.subscription` properties

These properties describe the [subscription](./subscriptions) that received the message.

<ParamField type="string">
  The subscription's OneSignal ID. **Liquid:** `{{ user.subscription.id }}`
</ParamField>

<ParamField type="string">
  The OneSignal App ID. **Liquid:** `{{ user.subscription.app_id }}`
</ParamField>

<ParamField type="string">
  The subscription's platform-specific token. For **Email**, this is the email address. For **SMS**, a phone number in E.164 format. For **Push**, the push token. **Liquid:** `{{ user.subscription.subscription_token }}`
</ParamField>

<ParamField type="number">
  Total sessions recorded for this subscription. **Liquid:** `{{ user.subscription.session_count }}`
</ParamField>

<ParamField type="string">
  The language code set on the subscription. **Liquid:** `{{ user.subscription.language }}`
</ParamField>

<ParamField type="string">
  The app or game version reported by the subscription (e.g., `"4.12.0"`). The `game_version` name is legacy from OneSignal's gaming-app origins — it returns your app's version regardless of category. **Liquid:** `{{ user.subscription.game_version }}`
</ParamField>

<ParamField type="number">
  UNIX timestamp of the subscription's most recent session. **Liquid:** `{{ user.subscription.last_active }}`
</ParamField>

<ParamField type="number">
  Total session time recorded for this subscription, in seconds. **Liquid:** `{{ user.subscription.play_time }}`
</ParamField>

<ParamField type="number">
  UNIX timestamp of when the subscription was created. **Liquid:** `{{ user.subscription.created_at }}`
</ParamField>

<ParamField type="boolean">
  Whether the subscription is currently opted in to receiving messages. **Liquid:** `{{ user.subscription.subscribed }}`
</ParamField>

<ParamField type="string">
  The OneSignal SDK version on the subscription's device. **Liquid:** `{{ user.subscription.sdk }}`
</ParamField>

<ParamField type="string">
  The device hardware model (e.g., "iPhone14,2", "Pixel 7"). **Liquid:** `{{ user.subscription.device_model }}`
</ParamField>

<ParamField type="string">
  The device operating system and version (e.g., "iOS 17.2", "Android 14"). **Liquid:** `{{ user.subscription.device_os }}`
</ParamField>

## Related pages

<Columns>
  <Card title="Event Streams" icon="bolt" href="./event-streams">
    Set up and configure Event Streams, including setup, body templates, and debugging.
  </Card>

  <Card title="Using Liquid syntax" icon="code" href="./using-liquid-syntax">
    Reference for Liquid syntax used to personalize Event Stream bodies.
  </Card>

  <Card title="In-app message Event Streams" icon="message" href="./iam-event-streams">
    Details on in-app message event data and carousel tracking.
  </Card>

  <Card title="Metrics Glossary" icon="chart-bar" href="./analytics-metrics-glossary">
    Definitions for all message event metrics across channels.
  </Card>
</Columns>

## FAQ

### Why is some event data missing or blank?

Message data for Journeys and API sends is retained for 30 days. If a user interacts with a message (click, open, unsubscribe) more than 30 days after it was sent, the associated message properties may be blank. To work around this, correlate the `message.id` from the interaction event with the original `sent` event, which contains the full message data.

### What is the difference between `event.id` and `message.id`?

`event.id` is a unique identifier for the individual event (e.g., one specific click). `message.id` is the identifier for the message that was sent — multiple events can share the same `message.id` (for example, a `sent` event and a `clicked` event for the same push notification).

### What format is `message.title` for push vs email?

For push notifications, `message.title` returns a localized object like `{'en':'Your title'}`. For email, it returns the subject line as a plain string. The format depends on the channel. To get a clean string from a push event regardless of locale, access the language key directly: `{{ message.title.en }}`. Branch on `{{ user.language }}` if you support multiple languages.

### Are Custom Events included in Event Streams?

No. Event Streams contain **message events** (sent, clicked, opened, bounced, etc.) — not [Custom Events](./custom-events). Custom Events are user actions you send *into* OneSignal. Event Streams export message delivery and engagement data *out of* OneSignal.

### How do I reference a specific tag in my Event Stream body?

Use `{{ user.tags.your_tag_key }}` with the exact tag key. To avoid errors when a tag is not set, add a default: `{{ user.tags.your_tag_key | default: '' }}`. See [Using Liquid syntax](./using-liquid-syntax) for more details.


# Exporting data
Source: https://documentation.onesignal.com/docs/en/exporting-data

Export message, subscription, and audience activity data from OneSignal using dashboard CSVs, REST API endpoints, and Event Streams.

## Overview

You can export data from OneSignal using any of the following methods:

* **Dashboard CSV exports** — Download Subscriptions and Sent Messages as CSVs from the **Audience** and **Delivery** pages.
* **REST API endpoints** — Export Subscription data, message reports, and per-user audience activity programmatically.
* **[Event Streams](./event-streams)** — Stream message events to your own destination in real time.
* **[Integrations](./integrations)** — Forward data to third-party tools like Segment, Mixpanel, and Amplitude.

### Data retention

* **User and Subscription data:**
  * **Paid plans:** Available for the lifetime of the app.
  * **Free plans:** Automatically deleted after 18 months of inactivity.
* **Dashboard-sent messages:** Available for the lifetime of the app.
* **API-sent messages:** Available for approximately 30 days from when they were sent.
* **Audience activity:** Available for approximately 30 days from when the related message was sent.
* **Journey-sent messages:** Downloadable from the dashboard. See [Journey analytics](./journeys-analytics).

***

## Export message data

To stream real-time message events to your own destination, use [Event Streams](./event-streams).

<Tabs>
  <Tab title="Dashboard">
    **Bulk export** push, email, SMS, and Live Activity messages from the **Delivery > Sent Messages** page.

    Available filters:

    * **Source:** Dashboard, API, Automated, or Test Messages.
    * **Device type:** Push, In-App, Email, SMS, or Live Activity.
    * **Text search:** Search by message content, heading, and name. Only available when **Source** is set to **Dashboard Messages**.
    * **Start date and end date:** Filters messages by their **Sent At** date in your current timezone.

    **Per-message reports** are available when viewing an individual message in the dashboard. See the channel-specific guide for export details:

    * [Push message reports](./push-notification-message-reports)
    * [In-app message reports](./in-app-message-reports)
    * [Email message reports](./email-message-reports)
    * [SMS message reports](./sms-message-reports)
    * [Live Activity message reports](./live-activities#message-reports)
  </Tab>

  <Tab title="API">
    You can export message data via our REST API using the following endpoints:

    * [View message](/reference/view-message): Fetch data for a single message using its `id`.
    * [View messages](/reference/view-messages): Retrieve a paginated list (up to 50 per page).
    * [Export audience activity CSV](/reference/export-csv-of-events): Per-user event CSV including sent, open, and click data.
  </Tab>
</Tabs>

***

## Export subscription data

OneSignal exports **Subscription records** (push tokens, email addresses, and phone numbers), not Users. A user without any attached Subscription will not appear in these exports. To retrieve individual users, use the [View user API](/reference/view-user). See [Users](./users) and [Subscriptions](./subscriptions) for the distinction.

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Audience > Subscriptions**.
    2. Optionally filter by segment.
    3. Use the column picker to select the fields you want in the export.
    4. Click **Export**.
  </Tab>

  <Tab title="API">
    You can export user and subscription data via our REST API using the following endpoints:

    * [CSV export](/reference/csv-export): Returns a download link to a CSV of Subscription records with their current `notification_types` status and channel-specific fields. Supports segment, last-active, and unsubscribed-state filters.
    * [View user](/reference/view-user): Retrieve the current state of a single user, identified by `alias_label` and `alias_id`. Use this when you have a known user identifier rather than a bulk-export need.
  </Tab>
</Tabs>


# GDPR & Individual Rights
Source: https://documentation.onesignal.com/docs/en/gdpr-compliance

OneSignal provides the following solutions to help be GDPR compliant.

If your business operates in any way, shape, or form in the EU, or with citizens of the EU, then you must comply with the General Data Protection Regulation (GDPR) framework. OneSignal can help your activities in the customer engagement space to remain compliant with the GDPR guidelines through purpose built APIs and SDKs. In this section, OneSignal will outline what tools are provided to clients to adhere to the regulation and maintaining individual rights afforded to EU citizen through the GDPR framework.

## The Right to be Informed

<Steps>
  <Step title="What does it mean" icon="question">
    Individuals have the right to be informed about the collection and use of their personal data. It is your responsibility to provide individuals with information including: your purposes for processing their personal data, your retention periods for that personal data, and who it will be shared with. Relevant in the context of using OneSignal for your messaging is informing your users who their information will be shared with.
  </Step>

  <Step title="How to prepare" icon="check">
    OneSignal provides a purpose built SDK with methods that delay the initialization of data collection. If called, you will have the opportunity to inform users of your intent when capturing individual permissions for notifications. For more information on setting up please view our [Handling Personal Data guide](./handling-personal-data). For more information on how OneSignal processes the data of your users please view the [Privacy Policy](https://onesignal.com/privacy_policy).
  </Step>
</Steps>

## The Right of Access

<Steps>
  <Step title="What does it mean" icon="question">
    Individuals have the right to access and receive a copy of their personal data, and other supplementary information. This practice is commonly known as a Subject Access Request (SAR), a process that you must have in place in order to respond to a SAR.
  </Step>

  <Step title="How to prepare" icon="check">
    There are two easy-to-use ways to access individual level data that OneSignal holds on your behalf. First, within the OneSignal application you can search records by a unique identifier to view and export all data in CSV that is held on OneSignal's server. Second, you can call the [`View user` API endpoint](/reference/view-user) to retrieve the same information in JSON format. For detailed understanding of how to export user data please refer to this guide on [Exporting User Data](./exporting-data).

    OneSignal does not automatically collect any PII (Personally Identifiable Information) except for IP Addresses in countries outside the EU. We can disable all IP Address tracking if you wish.

    Any other data that might be considered PII can only be sent to us in the form of tags which you have full control over. Please review our [Handling Personal Data guide](./handling-personal-data) for more details.
  </Step>
</Steps>

## The Right of Rectification

<Steps>
  <Step title="What does it mean" icon="question">
    Individuals have the right to have inaccurate personal data rectified, or completed if it is incomplete. You have up to one calendar month to respond to a request.
  </Step>

  <Step title="How to prepare" icon="check">
    OneSignal provides you with a choice on how to rectify data tied to a personal record either through the online application or by calling OneSignal's purpose built API endpoint. Within the online application simply import data to either amend, add, or delete fields that are attributed to a specific identifier, here is a [guide on how to get started](./import).

    The other method to rectify data for an individual's request is through the [Update user](/reference/update-user) API.

    By using any of these methods you are in a position to rectify data immediately and view the amended record, thus helping to be compliant with this GDPR right by being able to respond within one calendar month.
  </Step>
</Steps>

## The Right to Erasure

<Steps>
  <Step title="What does it mean" icon="question">
    Also known as the "right to be forgotten", this article empowers individuals to request that their personal data be erased. However, this right is not absolute and can only be exercised under certain circumstances such as when the personal data is no longer necessary for the purpose which you originally collected or processed it for.
  </Step>

  <Step title="How to prepare" icon="check">
    We recommend you carefully locate and identify the individual user record that needs to be deleted as the action of deleting devices cannot be undone. It is sensible to use the [Delete user](/reference/delete-user) API endpoint as it processes one request at a time. However, you can delete bulk users within the online application if, for example, you respond to all erasure requests once every week and handle this in a batch. Please view this documentation for more information on [Deleting Users](./delete-users).
  </Step>
</Steps>

## The Right to Restrict Processing

<Steps>
  <Step title="What does it mean" icon="question">
    Individuals have, under certain circumstances, the right to restrict the processing of personal data which effectively means you are limited in how their data can be used within your organization. This right is an alternative to the right of erasure and it is important to note that there are limited number of circumstances in which this applies, for example when the individual contests the accuracy of their personal data and you are verifying the accuracy of the data.
  </Step>

  <Step title="How to prepare" icon="check">
    Following our [Handling Personal Data](./handling-personal-data) practices, you can setup your own application to not send OneSignal [Tags](./add-user-data-tags) depending on certain conditions you set within your app.
  </Step>
</Steps>

## The Right to Data Portability

<Steps>
  <Step title="What does it mean" icon="question">
    This right allows individuals to receive the personal data held in a structured, commonly used and machine readable format. Very similar to the Right of Access, it also entitles individuals to have their personal data transmitted between one data controller to another controller.
  </Step>

  <Step title="How to prepare" icon="check">
    OneSignal, as the data processor, will make it easy for you to access and extract data held on a specified individual. Within the online application or through our API, you can generate a CSV export file for a user record or you can access the [View user](/reference/view-user) API to retrieve all data in JSON format.
  </Step>
</Steps>

## The Right to Object

<Steps>
  <Step title="What does it mean" icon="question">
    Individuals have the right to object of processing their personal data at any time. When exercised, you are required to stop processing the data subjects' personal data. This objection may be in relation to all personal data or can relate to a particular purpose you are processing the data for, for example with notifications.
  </Step>

  <Step title="How to prepare" icon="check">
    If this right is exercised by an individual you may need to follow the steps outlined above under "The Right to Restrict Processing" and if the request includes you may also need to follow the recommended steps under "Right to Erasure" as outlined in this article. A combination of these will secure you adhering to this request and, most importantly, being able to respond within the legal time limit of one calendar month.
  </Step>
</Steps>

***


# Amazon API key generation
Source: https://documentation.onesignal.com/docs/en/generate-an-amazon-api-key

Step-by-step guide

An Amazon API Key is required for all **Amazon** apps.

## Requirements:

* An Amazon app.
* An [Amazon Developer account](https://developer.amazon.com/login.html) account.
* A [OneSignal Account](https://onesignal.com/), if you do not already have one.

<Steps>
  <Step title="Create a security profile">
    Log in to your [Amazon Developer account](https://developer.amazon.com/login.html) and select your app.

    Click on the **Device Messaging** tab and click **Create a New Security Profile**.

    <Frame>
      <img />
    </Frame>

    Give your Security Profile the required name and description, then click Save.

    <Frame>
      <img />
    </Frame>

    You should get a series of success messages. Next, click **View Security Profile** to continue.

    <Frame>
      <img />
    </Frame>

    You will then see a settings page that lists your **Client ID** and **Client Secret**. Leave this page open, as you will need this information in Step 2.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Configure your OneSignal app's Amazon platform settings">
    In the OneSignal dashboard, select your app from the All Apps page, then go to Settings. Under Native App Platforms, click Amazon Fire.

    <Frame>
      <img />
    </Frame>

    Paste your Client ID and Client Secret into the fields and click Save.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Creating an Amazon API key">
    The following steps are required to test push notifications before publishing your app to the Amazon App Store.

    Go back to the Amazon Security Profile page for your app, and select the **Android/Kindle Settings** tab.

    Enter any name you like for the **API Key Name**.

    Enter your Android package name. **NOTE**: the package name is case sensitive.

    Enter the MD5 signature of your Android Keystore you used to sign the APK file with. See [Amazon's instructions](https://developer.amazon.com/public/apis/engage/login-with-amazon/docs/android_app_signatures.html) to get this value.

    We recommend not using the default debugging keystore, but if you do, make sure you redo this again with your Production keystore, or let Amazon sign your app for you.

    When you're done, click **Generate New Key**.

    <Frame>
      <img />
    </Frame>

    Copy the **Key** shown in the results and save it into a new file named `api_key.txt`.

    When your app is built, this file needs to be located in `/assets/` in the root of your APK.

    More details on the placement of this file can be found in our [Amazon SDK Setup](./amazon-sdk-setup) documentation.

    <Frame>
      <img />
    </Frame>
  </Step>
</Steps>

***

<Check>
  **Done!** You now have a key to send push notifications from your app. 🥳

  Return to the [Amazon SDK Setup](./amazon-sdk-setup) guide to install the OneSignal SDK in your app.
</Check>

***


# Goals
Source: https://documentation.onesignal.com/docs/en/goals

Define a success metric and target value on a Journey, then track progress on the Journey report.

Use Goals to measure the impact of your Journeys against specific targets. Set a metric and threshold, then monitor real-time progress to understand what's working.

<Note>
  Goals for Journeys are currently in **Beta** and available in early access. Functionality may change before general availability.
</Note>

## What Goals track

When you set a Goal, you choose a metric (such as clicks or delivered), decide whether to measure it as a **rate** or **count**, and set a target value. OneSignal continuously evaluates the Goal as your Journey runs.

You can configure Goals in two places within a Journey:

* **Journey Goal** — tracks a single success metric for the entire Journey, such as how many users entered, completed, or exited early.
* **Message Goal** — measures performance for an individual message step, such as CTR or clicks on a Push Notification step.

## Set and track Goals on a Journey

You define a metric and target in the Journey settings (for a Journey Goal) or on a supported message step (for a Message Goal). Once the Journey is live, progress appears at the top of the Journey report, and Message Goals appear on the message-level report for each step.

<Card title="Journey Goals" icon="route" href="./journeys-settings">
  Learn how to set and track Goals on Journeys.
</Card>

## Conversion metrics (coming soon)

Support for conversion-based metrics in Goals is on the way. While you wait, learn how conversion metrics work today.

<Card title="Conversion metrics" icon="chart-line" href="./conversion-metrics">
  Track purchases, sign-ups, and other downstream actions.
</Card>

## FAQ

**Which metrics are available for Goals?**
Available metrics depend on the channel. Common options include Clicked and Delivered. The metric picker in the Goal step shows only metrics supported by the selected channel.

**Do Goals affect message delivery or targeting?**
No. Goals are purely for measurement. They do not change how or to whom a message is delivered.


# Google Cloud SQL
Source: https://documentation.onesignal.com/docs/en/google-cloud-sql

Sync custom events from Google Cloud SQL to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Google Cloud SQL integration enables automatic syncing of custom events from your Cloud SQL database to OneSignal. This allows you to trigger automated Journeys and personalized messaging campaigns based on user behavioral data stored in your managed PostgreSQL database.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Google Cloud SQL

* **Cloud SQL for PostgreSQL** instance (version 11 or higher recommended)
* **Database access** with read permissions for event tables
* **Network connectivity** from OneSignal to your Cloud SQL instance
* **Cloud SQL Auth proxy** for secure connections (recommended)

***

## Setup

<Steps>
  <Step title="Configure Cloud SQL database access">
    Create a dedicated user for OneSignal with read-only access to event tables:

    ```sql theme={null}
    -- Create OneSignal user
    CREATE USER onesignal_reader WITH PASSWORD 'strong_unique_password';

    -- Grant schema access
    GRANT USAGE ON SCHEMA event_data TO onesignal_reader;

    -- Grant table access
    GRANT SELECT ON ALL TABLES IN SCHEMA event_data TO onesignal_reader;

    -- Grant access to future tables
    ALTER DEFAULT PRIVILEGES IN SCHEMA event_data
    GRANT SELECT ON TABLES TO onesignal_reader;
    ```
  </Step>

  <Step title="Configure network access">
    Ensure OneSignal can connect to your Cloud SQL instance:

    **Option 1: Authorized Networks (Public IP)**

    * In Google Cloud Console, go to **SQL > Instances**
    * Select your instance → **Connections** → **Networking**
    * Add the IP addresses provided by OneSignal in the Integration setup to **Authorized networks**

    **Option 2: Private IP (Recommended)**

    * Configure your Cloud SQL instance with a private IP
    * Use Cloud SQL Auth Proxy for secure connections
    * Ensure proper VPC peering or firewall rules

    **Option 3: Cloud SQL Auth Proxy**

    * Download and configure the Cloud SQL Auth Proxy
    * Use service account authentication
    * Connect through secure proxy tunnel
  </Step>

  <Step title="Set up Cloud SQL Auth Proxy (recommended)">
    For enhanced security, use Cloud SQL Auth Proxy:

    ```bash theme={null}
    # Download Cloud SQL Auth Proxy
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64

    # Make executable
    chmod +x cloud_sql_proxy

    # Run proxy (replace with your instance connection name)
    ./cloud_sql_proxy -instances=PROJECT:REGION:INSTANCE=tcp:5432
    ```

    Create a service account with Cloud SQL Client role:

    ```bash theme={null}
    gcloud iam service-accounts create onesignal-cloudsql
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:onesignal-cloudsql@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/cloudsql.client"
    ```
  </Step>

  <Step title="Add integration in OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Google Cloud SQL** and provide:

    * **Instance Connection Name**: `PROJECT_ID:REGION:INSTANCE_ID`
    * **Database Name**: Your event database name
    * **Username**: `onesignal_reader`
    * **Password**: The password created in Step 1
    * **SSL Mode**: `require` (recommended for security)
    * **Connection Type**: Choose between Direct, Auth Proxy, or Private IP
  </Step>

  <Step title="Configure event data queries">
    Define the SQL query to retrieve event data from your Cloud SQL database:

    ```sql theme={null}
    SELECT
        event_name,
        user_id,
        created_at as event_timestamp,
        properties as event_payload
    FROM event_data.user_events
    WHERE created_at >= CURRENT_TIMESTAMP - INTERVAL '1 hour'
    ORDER BY created_at DESC
    ```

    Ensure your event tables include:

    * Event name/type (String)
    * User identifier (String)
    * Event timestamp (Timestamp)
    * Event properties (JSON/JSONB)
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify OneSignal can connect to your Cloud SQL instance and execute the event query successfully.
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

***

## Advanced Configuration

### Connection Pooling

Optimize database connections for high-volume event syncing:

```sql theme={null}
-- Check current connection limits
SELECT * FROM pg_stat_activity WHERE datname = 'your_database';

-- Optimize for OneSignal connections
ALTER SYSTEM SET max_connections = 200;
ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';
```

### Query Optimization

Improve event query performance:

```sql theme={null}
-- Create index on timestamp for efficient filtering
CREATE INDEX idx_events_created_at ON user_events(created_at);

-- Create composite index for user-based queries
CREATE INDEX idx_events_user_time ON user_events(user_id, created_at);

-- Analyze query performance
EXPLAIN ANALYZE
SELECT event_name, user_id, created_at, properties
FROM user_events
WHERE created_at >= NOW() - INTERVAL '1 hour';
```

### JSON Data Handling

If using JSONB for event properties, optimize JSON queries:

```sql theme={null}
-- Create GIN index for JSON properties
CREATE INDEX idx_events_properties ON user_events USING GIN(properties);

-- Query specific JSON properties
SELECT
    event_name,
    user_id,
    properties->>'purchase_amount' as amount,
    properties->>'product_id' as product
FROM user_events
WHERE properties->>'event_type' = 'purchase';
```

<Warning>
  Monitor your Cloud SQL instance's performance when OneSignal queries event data. Consider using read replicas for analytics workloads to avoid impacting production performance.
</Warning>

***

## FAQ

### How often does OneSignal sync events from Cloud SQL?

OneSignal syncs event data based on your configured schedule, with a minimum interval of 15 minutes.

### Can I use Cloud SQL read replicas for event syncing?

Yes, using read replicas is recommended to isolate analytics queries from your production database workload.

### What happens if my Cloud SQL instance is temporarily unavailable?

OneSignal will retry connections with exponential backoff. Event syncing will resume automatically once your instance is accessible again.


# Google Play Data Safety Requirements
Source: https://documentation.onesignal.com/docs/en/google-play-data-safety-requirements

Learn how to accurately complete the Google Play Data Safety form when using OneSignal. Understand what data is collected, how to disclose it, and ensure compliance with Google's privacy policies.

To publish or update your app on Google Play, you must complete the **Data safety** section in the **App Privacy** tab in the [Google Play Console](https://play.google.com/console/app/app-content/summary).

As OneSignal is a third-party service, you are responsible for disclosing how you handle user data when using OneSignal. Google's official guidance can be found [here](https://support.google.com/googleplay/android-developer/answer/10787469?hl=en#in_play_console).

By default, OneSignal collects:

* **In-app purchases**
* **App interactions** (e.g., session counts, durations, and notification clicks)

If you use OneSignal to collect emails, phone numbers, or additional custom data (via [Tags](./add-user-data-tags)),you must disclose those data types as well.

For details on handling user data, see [Handling Personal Data](./handling-personal-data).

## Data types and OneSignal behavior

✅ = Collected when using OneSignal
💡 = May be collected depending on your OneSignal usage
❌ = Not collected by OneSignal

| Category                     | Data Type                      | OneSignal Collection Behavior                                                                            |
| ---------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- |
| **Location**                 | Approximate location           | ❌ Not collected                                                                                          |
|                              | Precise location               | 💡 Only if your app collects it and sends it to OneSignal                                                |
| **Personal info**            | Name                           | 💡 If collected via Tags or Outcomes                                                                     |
|                              | Email address                  | 💡 If added to OneSignal                                                                                 |
|                              | User IDs                       | 💡 If collected via Tags or Outcomes                                                                     |
|                              | Address                        | ❌ Not collected                                                                                          |
|                              | Phone number                   | 💡 If added to OneSignal                                                                                 |
|                              | Race and ethnicity             | ❌ Not collected                                                                                          |
|                              | Political or religious beliefs | ❌ Not collected                                                                                          |
|                              | Sexual orientation             | ❌ Not collected                                                                                          |
|                              | Other info                     | 💡 If collected via Tags or Outcomes                                                                     |
| **Financial info**           | User payment info              | ❌ Not collected                                                                                          |
|                              | Purchase history               | ✅ Collected if your app has in-app purchases                                                             |
|                              | Credit score                   | ❌ Not collected                                                                                          |
|                              | Other financial info           | ❌ Not collected                                                                                          |
| **Health and fitness**       | Health info                    | ❌ Not collected                                                                                          |
|                              | Fitness info                   | ❌ Not collected                                                                                          |
| **Messages**                 | Emails                         | ❌ Not collected                                                                                          |
|                              | SMS or MMS                     | ❌ Not collected                                                                                          |
|                              | Other in-app messages          | ❌ Not collected                                                                                          |
| **Photos and videos**        | Photos                         | ❌ Not collected                                                                                          |
|                              | Videos                         | ❌ Not collected                                                                                          |
| **Audio files**              | Voice or sound recordings      | ❌ Not collected                                                                                          |
|                              | Music files                    | ❌ Not collected                                                                                          |
|                              | Other audio files              | ❌ Not collected                                                                                          |
| **Files and docs**           | Files and docs                 | ❌ Not collected                                                                                          |
| **Calendar**                 | Calendar events                | ❌ Not collected                                                                                          |
| **Contacts**                 | Contacts                       | ❌ Not collected                                                                                          |
| **App activity**             | App interactions               | ✅ Collected: includes sessions and notification clicks                                                   |
|                              | In-app search history          | ❌ Not collected                                                                                          |
|                              | Installed apps                 | ❌ Not collected                                                                                          |
|                              | Other user-generated content   | 💡 If collected via Tags or Outcomes                                                                     |
|                              | Other actions                  | 💡 If collected via Tags or Outcomes                                                                     |
| **Web browsing**             | Web browsing history           | ❌ Not collected                                                                                          |
| **App info and performance** | Crash logs                     | ❌ Not collected                                                                                          |
|                              | Diagnostics                    | ❌ Not collected                                                                                          |
|                              | Other performance data         | ❌ Not collected                                                                                          |
| **Device or other IDs**      | Device or other IDs            | ❌ Does not collect GAID by default<br />💡 Collected if you use [Aliases](./aliases) to link identifiers |

## Required data types for OneSignal

You **must disclose** the following if you use OneSignal:

### Purchase history

If your app includes in-app purchases, disclose collection of **Purchase history** under **Financial info**.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Info>
  At a minimum, select “Analytics” for OneSignal. If you use OneSignal for other use cases, you must select those as well.
</Info>

### App interactions

Disclose collection of **App interactions** under the **App activity** section.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Info>
  Select both “Analytics” and “Developer communications” at a minimum. If additional data is collected through OneSignal, disclose it as well.
</Info>

## Preview of store listing

After completing your privacy selections, Google will generate a preview. If you've disclosed **Purchase history** and **App interactions**, your listing should look like this:

<Frame>
  <img />
</Frame>

## Keep your disclosure up to date

If your data collection practices change, revisit the **Data safety** section in the Play Console and update your disclosures.

***


# Pub/Sub
Source: https://documentation.onesignal.com/docs/en/google-pubsub

Sync custom events from Google Pub/Sub to OneSignal to trigger automated Journeys and personalized messaging campaigns based on real-time user behavior.

## Overview

The OneSignal + Google Pub/Sub integration enables real-time syncing of custom events from your Pub/Sub topics to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

Pub/Sub is Google's scalable messaging service that allows applications to send and receive messages between independent components. OneSignal acts as a subscriber to your Pub/Sub topics, allowing you to sync event messages from Pub/Sub to trigger personalized user experiences.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Google Pub/Sub

* **Google Cloud Project** with Pub/Sub enabled
* **Pub/Sub topics** containing event messages
* **IAM permissions** to grant service account access
* **JSON-formatted messages** on your topics

***

## Setup

<Steps>
  <Step title="Create Pub/Sub connection">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    1. Select **Google Pub/Sub** from the list
    2. Enter the **GCP Project ID** where your Pub/Sub topics are located
    3. Choose authentication method:
       * **Auto-generated Service Account** (recommended): OneSignal creates and manages the service account
       * **Existing Service Account**: Provide your own service account key JSON file
    4. Click **Connect**
  </Step>

  <Step title="Grant permissions to service account">
    OneSignal will create a new service account and provide you with the service account email address.

    Grant the **`roles/pubsub.editor`** role to this service account on your GCP project:

    ```bash theme={null}
    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
      --member serviceAccount:SERVICE_ACCOUNT_EMAIL \
      --role roles/pubsub.editor
    ```

    OneSignal uses this role to:

    * Create subscriptions to your event topics
    * Consume event messages from topics
    * Create error topics (Dead Letter Queue) for failed processing
  </Step>

  <Step title="Test connection">
    Once you've granted the necessary permissions, click **Save** in OneSignal to verify the connection.

    OneSignal will validate that it can access your Pub/Sub topics and is ready to process event messages.
  </Step>
</Steps>

***

## Event Data Schema

Before you can use a Pub/Sub topic for custom events, you must define the schema of the event messages.

<Steps>
  <Step title="Navigate to event schema definition">
    In OneSignal, go to **Data > Integrations** and select your Pub/Sub connection.

    OneSignal automatically pulls the list of topics from your project. Click **Refresh topics** to manually refresh the list.
  </Step>

  <Step title="Define event message schema">
    1. Click on the name of the topic containing your event data
    2. Select **JSON** as the message format (only supported format)
    3. Click **Import sample message** and provide a sample event message
    4. Review the detected schema to ensure proper field mapping
    5. Click **Save Dataset**
  </Step>
</Steps>

### Event Message Format

Your Pub/Sub messages should follow this JSON structure for OneSignal custom events:

```json theme={null}
{
  "event_name": "purchase_completed",
  "user_id": "user_12345",
  "timestamp": "2023-12-01T10:30:00Z",
  "properties": {
    "product_id": "prod_abc123",
    "price": 29.99,
    "category": "electronics",
    "payment_method": "credit_card"
  },
  "session_id": "session_789"
}
```

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

<Warning>
  Do not include customer PII or sensitive data in sample messages. OneSignal stores message samples as part of the dataset definition.
</Warning>

***

## Real-time Event Processing

Unlike batch integrations, Pub/Sub enables near real-time event processing:

* **Low Latency**: Events are processed within seconds of being published to topics
* **Automatic Subscriptions**: OneSignal creates dedicated subscriptions for each topic
* **Error Handling**: Failed events are sent to Dead Letter Queue topics for investigation
* **Scalable Processing**: Handles high-volume event streams automatically

***

## Advanced Configuration

### Dead Letter Queue

OneSignal automatically creates error topics for events that fail processing:

* **Automatic Creation**: Error topics are created per subscription
* **Failed Event Storage**: Events that can't be processed are stored for debugging
* **Manual Review**: Access failed events through Google Cloud Console for troubleshooting

### Message Acknowledgment

OneSignal handles Pub/Sub message acknowledgment automatically:

* **Successful Processing**: Messages are acknowledged after successful event creation
* **Failed Processing**: Messages are negatively acknowledged and sent to Dead Letter Queue
* **Retry Logic**: Built-in retry handling for transient failures

***

## Limitations

* Only JSON message format is supported
* Message samples are stored as part of dataset definitions (avoid PII)
* Requires `roles/pubsub.editor` permissions at project level
* Maximum message size follows Google Pub/Sub limits (10MB)

***

## FAQ

### How quickly are events processed?

Events are typically processed within seconds of being published to your Pub/Sub topic, enabling near real-time Journey triggering.

### What happens if OneSignal can't process an event?

Failed events are automatically sent to a Dead Letter Queue topic that OneSignal creates. You can review these events in the Google Cloud Console for debugging.

### Can I use multiple topics for different event types?

Yes, you can define schemas for multiple topics within the same GCP project. Each topic can contain different event types with their own schema definitions.


# Google Sheets
Source: https://documentation.onesignal.com/docs/en/google-sheets

Sync custom events from Google Sheets to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Google Sheets integration enables automatic syncing of custom events from your Google Sheets to OneSignal. This allows you to trigger automated Journeys and personalized messaging campaigns based on user behavioral data stored in your spreadsheets, perfect for teams that manage event data collaboratively.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Google Sheets

* **Google Account** with access to the sheet containing event data
* **Event spreadsheet** with proper column structure for event data
* **Sheet sharing permissions** for OneSignal to access the data
* **Consistent data format** in your event tracking sheet

***

## Setup

<Steps>
  <Step title="Prepare your event data sheet">
    Structure your Google Sheet with the required columns for event data:

    **Required columns:**

    * `event_name` or `event_type`: The name of the event (String)
    * `user_id` or `email`: User identifier (String)
    * `timestamp` or `created_at`: Event timestamp (Date/DateTime)
    * `properties`: Event properties as JSON or separate columns (Optional)

    **Example sheet structure:**

    ```
    | event_name | user_id | timestamp           | product_id | amount |
    |------------|---------|---------------------|------------|--------|
    | purchase   | user123 | 2024-01-15 10:30:00 | prod_abc   | 29.99  |
    | signup     | user456 | 2024-01-15 11:45:00 |            |        |
    ```
  </Step>

  <Step title="Configure sheet permissions">
    Share your Google Sheet with OneSignal's service account:

    1. Open your Google Sheet
    2. Click **Share** button in the top right
    3. Add OneSignal's service account email (provided during setup)
    4. Set permissions to **Viewer** (read-only access)
    5. Click **Send** to grant access

    <Info>
      OneSignal will provide the specific service account email during the integration setup process.
    </Info>
  </Step>

  <Step title="Add integration in OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Google Sheets** and provide:

    * **Sheet URL**: The full URL of your Google Sheet
    * **Sheet Name**: The specific tab/sheet name containing event data
    * **Header Row**: Row number containing column headers (usually 1)
    * **Data Range**: Cell range containing your event data (e.g., `A2:F1000`)
  </Step>

  <Step title="Configure column mapping">
    Map your Google Sheets columns to OneSignal event fields:

    * **Event Name Column**: Select the column containing event names
    * **User ID Column**: Select the column with user identifiers
    * **Timestamp Column**: Select the column with event timestamps
    * **Properties Columns**: Select additional columns to include as event properties

    <Info>
      You can map multiple columns as event properties. OneSignal will combine them into a single event payload.
    </Info>
  </Step>

  <Step title="Set sync schedule">
    Configure how often OneSignal should check for new event data:

    * **Sync Frequency**: Choose from 15 minutes, hourly, or daily
    * **Incremental Sync**: Enable to only sync new rows since last update
    * **Timestamp Filter**: Only sync events within a specific time range

    <Warning>
      Google Sheets has API rate limits. More frequent syncing may be throttled for sheets with large datasets.
    </Warning>
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify OneSignal can access your Google Sheet and read the event data correctly.
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

***

## Advanced Configuration

### Incremental Sync Setup

Configure incremental syncing to only process new events:

1. **Timestamp Column**: Ensure your sheet has a consistent timestamp column
2. **Sort Order**: Keep events sorted by timestamp (newest last)
3. **Append-Only**: Add new events to the bottom of your sheet
4. **Avoid Edits**: Don't modify historical event rows after they're synced

### Data Validation

Implement data validation in your Google Sheet:

```
Data > Data validation
- Event Name: List from range (predefined event types)
- User ID: Custom formula to check format
- Timestamp: Date/Time format validation
- Amount: Number validation for numeric properties
```

### Collaborative Workflows

Best practices for team collaboration:

* **Named Ranges**: Use named ranges for event data sections
* **Protected Ranges**: Protect header rows from accidental changes
* **Comments**: Add comments to explain event definitions
* **Version History**: Use Google Sheets' version history for tracking changes
* **Access Controls**: Limit edit access to data entry team members

### Performance Optimization

Optimize for large datasets:

* **Sheet Limits**: Keep individual sheets under 10,000 rows for best performance
* **Multiple Sheets**: Use separate sheets for different event types
* **Data Archival**: Archive old data to separate sheets monthly
* **Formulas**: Minimize complex formulas in event data ranges

<Warning>
  Google Sheets performs best with under 50,000 total cells. For high-volume event tracking, consider using a database source instead.
</Warning>

***

## FAQ

### How often does OneSignal sync events from Google Sheets?

OneSignal can sync as frequently as every 15 minutes, but we recommend hourly or daily syncing for most use cases to respect Google's API limits.

### Can multiple team members add events to the same sheet?

Yes, Google Sheets supports real-time collaboration. However, ensure team members understand the required data format and column structure.

### What happens if someone edits historical event data?

OneSignal syncs based on timestamps and row positions. Editing historical data may cause duplicate events or data inconsistencies. We recommend append-only workflows.


# Google Sheets integration with Event Streams
Source: https://documentation.onesignal.com/docs/en/google-sheets-integration-with-event-streams

This guide illustrates the required steps to setup a connection between OneSignal’s Event Webhooks to a custom Google Sheets document to analyze message events generated by OneSignal.

## Toggle event streams

Enable [Event streams](./event-streams), an add-on feature to a paid plan, for your OneSignal application. If you don't have access to this feature, don't hesitate to contact your Success Manager or Account Executive for more information.

## Create an apps script deployment

Navigate to **Extensions > Apps Script** in the Google Sheet you wish to add OneSignal message events. Next, within the code editor, replace the existing code with the following:

<Frame>
  <img />
</Frame>

<CodeGroup>
  ```javascript javascript theme={null}
  function doPost(e) {
      // Log the full request for debugging purposes
    Logger.log("Request received: " + JSON.stringify(e));

    const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
    let jsonData;

    try {
      // Log the postData.contents before parsing
      Logger.log("Post Data Contents: " + e.postData.contents);

      // Attempt to parse the JSON data
      jsonData = JSON.parse(e.postData.contents);
    } catch (error) {
      // Log the error and return an error response
      Logger.log("Failed to parse JSON: " + error);
      return ContentService.createTextOutput(
        JSON.stringify({ status: "error", message: "Invalid JSON" }),
      ).setMimeType(ContentService.MimeType.JSON);
    }

    // Check if the sheet is empty and set headers if necessary
    if (sheet.getLastRow() === 0) {
      sheet.appendRow([
        "User ID",
        "Event ID",
        "Event",
        "Message ID",
        "Message Name",
        "Message Title",
        "Message Contents",
        "Template ID",
        "Subscription ID",
        "Subscription Device Type",
        "Source",
        "Original Timestamp",
      ]);
    }

    // Prepare the row data from the JSON object
    const row = [
      jsonData.user_id || "",
      jsonData.event_id || "",
      jsonData.event || "",
      jsonData.properties ? jsonData.properties.message_id || "" : "",
      jsonData.properties ? jsonData.properties.message_name || "" : "",
      jsonData.properties ? jsonData.properties.message_title || "" : "",
      jsonData.properties ? jsonData.properties.message_contents || "" : "",
      jsonData.properties ? jsonData.properties.template_id || "" : "",
      jsonData.properties ? jsonData.properties.subscription_id || "" : "",
      jsonData.properties
        ? jsonData.properties.subscription_device_type || ""
        : "",
      jsonData.properties ? jsonData.properties.source || "" : "",
      jsonData.originalTimestamp || "",
    ];

    try {
      // Append the new row to the sheet
      sheet.appendRow(row);
    } catch (error) {
      // Log the error if appending the row fails
      Logger.log("Failed to append row: " + error);
      return ContentService.createTextOutput(
        JSON.stringify({ status: "error", message: "Failed to append row" }),
      ).setMimeType(ContentService.MimeType.JSON);
    }

    // Return a success response
    return ContentService.createTextOutput(
      JSON.stringify({ status: "success" }),
    ).setMimeType(ContentService.MimeType.JSON);
  }
  ```
</CodeGroup>

Next, deploy your project. Click Deploy in the top right, and select "Web App" as the deployment type. Provide a description and choose who can access the project; we will select "Anyone" to generate the URL needed in the following step.

<Frame>
  <img />
</Frame>

## Create the event stream

<Steps>
  <Step>
    From the OneSignal dashboard, navigate to **Settings > Event Streams (subject to add-on feature)**. From there, create a new event stream and select "Trigger when any of the following events occur". Choose the message events you'd like to sync in the pop-up with Google Sheets. In the example below, we capture all Push Notification events.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step>
    Next, in the configuration step, choose POST, paste the previous step's URL, and create a header to accept the JSON.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step>
    After this, select "Custom Body" in the Step 3 Dropdown and copy/paste the following code. You can change the properties and events you want to sync, as depicted in the example below. For more information on event stream event properties, visit our [documentation](./event-streams#personalization)

    <CodeGroup>
      ```json json theme={null}
      {
        "user_id": "{{ event.external_user_id }}",
        "event_id": "{{ event.id }}",
        "event": "{{ event.kind }}",
        "properties": {
          "message_id": "{{ message.id }}",
          "message_name": "{{ message.name }}",
          "message_title": "{{ message.title.en }}",
          "message_contents": "{{ message.contents.en }}",
          "template_id": "{{ message.template_id }}",
          "subscription_id": "{{ event.subscription_id }}",
          "subscription_device_type": "{{ event.subscription_device_type }}",
          "source": "onesignal"
        },
        "originalTimestamp": "{{ event.datetime }}"
      }
      ```
    </CodeGroup>
  </Step>

  <Step>
    Finally, select "Save & Activate" to synchronize the chosen message events to the Google Sheet. Below is an example of how the sample code above renders:

    <Frame>
      <img />
    </Frame>
  </Step>
</Steps>

***


# Greenplum
Source: https://documentation.onesignal.com/docs/en/greenplum

Sync custom events from Greenplum to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Greenplum integration enables syncing of custom events from your Greenplum database to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

Greenplum is a massively parallel processing (MPP) database built on PostgreSQL, designed for large-scale analytics workloads.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Greenplum

* **Greenplum instance** with network access
* **Database user** with appropriate permissions
* **Event tables** containing structured behavioral data

***

## Sync Engines and Permissions

OneSignal reads data from tables and views in Greenplum and syncs it to trigger automated messaging campaigns. To limit the load on your database, OneSignal maintains state tracking tables that enable it to only sync data that has been modified since the last sync (incremental syncs). When configuring your Greenplum connection, you'll choose a Sync Engine that determines how state tracking is handled.

The **Basic Sync Engine** maintains state tracking tables on OneSignal-owned infrastructure and is simpler to configure, requiring read access only.

The **Advanced Sync Engine** delivers enhanced performance by maintaining state tracking tables in a dedicated schema within your own Greenplum instance.

## Setup

<Steps>
  <Step title="Create a Census user">
    Create a dedicated database user for OneSignal to use:

    ```sql theme={null}
    -- Create CENSUS user and set password
    CREATE USER CENSUS WITH PASSWORD '<strong unique password>';
    ```
  </Step>

  <Step title="Choose your sync engine and configure permissions">
    **For Basic Sync Engine (Read-only access):**

    Grant read access to your event data schema. Replace `<your schema>` with your schema name:

    ```sql theme={null}
    -- Let the census user read all existing tables in this schema
    GRANT SELECT ON ALL TABLES IN SCHEMA "<your schema>" TO CENSUS;

    -- Let the census user read any new tables added to this schema
    ALTER DEFAULT PRIVILEGES IN SCHEMA "<your schema>" GRANT SELECT ON TABLES TO CENSUS;

    -- Let the census user execute any existing functions in this schema
    GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA "<your schema>" TO CENSUS;

    -- Let the census user execute any new functions added to this schema
    ALTER DEFAULT PRIVILEGES IN SCHEMA "<your schema>" GRANT EXECUTE ON FUNCTIONS TO CENSUS;
    ```

    **For Advanced Sync Engine (Enhanced performance):**

    First complete the Basic Sync Engine steps above, then add:

    ```sql theme={null}
    -- Create a private bookkeeping schema where Census can store sync state
    CREATE SCHEMA CENSUS;

    -- Give the census user full access to the bookkeeping schema
    GRANT ALL ON SCHEMA CENSUS TO CENSUS;

    -- Ensure the census user has access to any existing objects in the bookkeeping schema
    GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA CENSUS TO CENSUS;

    -- Let the census user see your data schema
    GRANT USAGE ON SCHEMA "<your schema>" TO CENSUS;
    ```
  </Step>

  <Step title="Connect to OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Greenplum** and provide:

    * **Host:** Your Greenplum master host
    * **Port:** 5432 (or custom port)
    * **Database:** Your database name
    * **Username:** `CENSUS`
    * **Password:** Password from Step 1
    * **Sync Engine:** Choose Basic or Advanced based on Step 2
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Table Schema

```sql theme={null}
-- Example Greenplum event table
CREATE TABLE analytics.user_events (
    event_id BIGSERIAL,
    event_name VARCHAR(100) NOT NULL,
    user_id VARCHAR(255) NOT NULL,
    event_timestamp TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    event_properties JSONB,
    session_id VARCHAR(255),
    device_type VARCHAR(50)
);
```

***

## Processing Modes

### Table Mode

Sync entire tables or views directly from your Greenplum database. OneSignal will automatically map columns to event fields.

### SQL Query Mode

Write custom PostgreSQL-compatible queries to transform your event data:

```sql theme={null}
-- Example: Recent high-value events
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_properties
FROM analytics.user_events
WHERE event_timestamp >= NOW() - INTERVAL '7 days'
    AND (event_properties->>'value')::NUMERIC > 100
ORDER BY event_timestamp DESC;
```

### MPP Query Optimization

Take advantage of Greenplum's parallel processing by ensuring your event queries are optimized for distributed execution. Use appropriate distribution keys and avoid cross-segment data movement for better performance.

***

## Advanced Network Configuration

OneSignal can successfully connect to Greenplum instances that are using advanced networking controls including region constraints, IP address allow lists, or SSH Tunneling.

We recommend configuring your Greenplum instance to use TLS v1.2 or later for all connections.

## Limitations

* Large analytical queries may impact cluster performance
* JSON/JSONB operations should be optimized for distribution
* Cross-segment joins should be minimized for performance

***

## FAQ

### Which sync engine should I choose?

Use the **Basic Sync Engine** if you prefer simpler setup and read-only access. Choose the **Advanced Sync Engine** if you need enhanced performance and can allow OneSignal to create tables in your Greenplum instance.

### How do I optimize queries for Greenplum's MPP architecture?

Ensure queries utilize distribution keys effectively, avoid unnecessary data movement between segments, and leverage Greenplum's columnar storage for analytics.

### Can I use Greenplum's external tables for event data?

Yes, OneSignal can read from external tables that reference data in formats like Parquet or CSV stored in external systems.

***


# Handling personal data
Source: https://documentation.onesignal.com/docs/en/handling-personal-data

How OneSignal handles personal data and how you can meet GDPR, CCPA, and privacy requirements.

## Overview

OneSignal is designed to help you meet global privacy and data protection requirements, including GDPR and CCPA, across all plans, including Free.

This guide explains:

* What data OneSignal collects
* How to minimize or avoid sending personal data
* How to collect and enforce user consent
* How to mask, restrict, or delete data when required

If you require a Data Processing Addendum (DPA) or Standard Contractual Clauses, see our [Paid Plans](https://onesignal.com/pricing) for details.

***

## How OneSignal collects data

The OneSignal SDK begins collecting data after it is initialized in your app or website. For a full list of fields collected automatically by the SDK, see [Data Collected by the OneSignal SDK](./data-collected-by-the-onesignal-sdk).

Most collected data is not considered PII (Personally Identifiable Information). However, some fields may be considered personal data depending on your region or use case. This guide focuses on how to use OneSignal without sending personal user data, or how to control it when required.

### IP address collection

In some regions, including the EU and UK, IP addresses may be considered personal data.

* **Default behavior:** OneSignal will automatically not collect IP Addresses from Users within the EU and UK.
* **Optional:** Disable IP collection globally
  * If you want to prevent IP address storage for all users, including non-EU/UK users, contact `support@onesignal.com`

<Warning> Disabling IP collection is permanent per app and cannot be selectively re-enabled later. </Warning>

### Masking personally identifiable information (PII)

<Frame>
  <img alt="Emails and phone numbers masked in the OneSignal dashboard" />
</Frame>

PII masking helps protect user privacy while allowing teams to safely view and analyze data.

**What gets masked**

* Email addresses
* Phone numbers

Masking applies to:

* The OneSignal dashboard
* Data exported directly from the dashboard

**What is not masked**

PII masking does not currently apply to:

* REST API responses
* External IDs
* Tags

**Availability**

PII masking is available to:

* Enterprise plans
* Professional or Growth plans with the Security & Legal package

To enable PII masking, contact `support@onesignal.com` or your Account Manager.

<Note> PII masking is a **display-level control**. The underlying data is still stored securely by OneSignal. </Note>

### Personal information sent as tags or other fields

You are responsible for ensuring that you have appropriate consent for any data you send to OneSignal, including:

* Email addresses
* Phone numbers
* Names
* Any personal attributes

For example, if you send an email address as a tag, you must ensure the user has consented to that data being shared and processed.

<Note>
  Some fields are collected automatically by the SDK. You can selectively disable or override many of these fields using SDK configuration options.

  See [Data Collected by the OneSignal SDK](./data-collected-by-the-onesignal-sdk).
</Note>

### Collecting and enforcing user consent

To support GDPR and similar regulations, OneSignal provides consent gating methods that allow you to delay all data collection until the user explicitly agrees.

**Consent vs. Message Opt-in**

* Consent refers to a User-level permission that allows you to delay all data collection until the user explicitly agrees.
* Message opt-in or permission is a Subscription-level permission granted by the user to receive messages for a specific message channel.
  * [Prompt for Push Permissions](./prompt-for-push-permissions)
  * [Email opt-in best practices](./email-reputation-best-practices)
  * [SMS opt-in requirements](./sms-registration-requirements)

**How consent gating works**

* You enable consent requirements before initializing our SDK.
* Our SDK does not collect or send any data until consent is granted via our SDK consent methods.
* Any SDK methods calls made before consent is granted are safely ignored.
* Consent state is persisted across sessions. You only need to collect consent once per user.

<Warning>
  If a user has previously accepted push permissions and has since revoked consent, they can still receive push notifications. To prevent them from receiving push notifications, you can programmatically call our SDK `optOut` method *before* revoking consent, or the user can either:

  * Disable push permissions in their devices notification settings
  * Uninstall the app
</Warning>

**SDK references**

<Note>
  If the user has accepted push permissions previously and has since revoked consent, you can still send push notifications to them as long as they have not unsubscribed from your notifications entirely. To fully opt a user out of receiving notifications you would use optOut() method for [mobile SDKs](./mobile-sdk-reference#optout-%2C-optin-%2C-optedin) or [web](./web-sdk-reference#optout-%2C-optin-%2C-optedin), before revoking consent.
</Note>

<Columns>
  <Card title="Mobile SDKs" href="./mobile-sdk-reference#privacy">
    <Icon icon="mobile" /> More details on the mobile SDK privacy methods.
  </Card>

  <Card title="Web SDKs" href="./web-sdk-reference#privacy">
    <Icon icon="computer" /> More details on the web SDK privacy methods.
  </Card>
</Columns>

### Location sharing

OneSignal provides a method to disable Location sharing within each mobile SDK.

<Columns>
  <Card title="Mobile SDKs" href="./mobile-sdk-reference#location">
    <Icon icon="location-pin" /> More details on the mobile SDK location methods.
  </Card>

  <Card title="Web SDKs">
    <Icon icon="check" /> Our web SDK does not collect or send location data.
  </Card>
</Columns>

### Push tokens

Push tokens are generally not considered PII because:

* They cannot be reused outside the originating app
* They do not reveal user identity or personal attributes

However, you should still disclose in your privacy policy that you use a third-party service (like OneSignal) to deliver personalized or targeted notifications.

***

## Deleting data

OneSignal provides multiple ways to delete or retain data depending on the data type.

* **User data**: See the [Delete Users](./delete-users) guide for deleting user profiles, Subscriptions, and associated data.
* **Message data**: Messages sent from the dashboard are stored indefinitely unless deleted manually or the app is deleted.
  * Messages sent via the API are typically deleted **\~30 days** after delivery.
* **Other data**: Most remaining data is stored until your OneSignal app is deleted. See [Managing your OneSignal account](./apps-organizations) for details.

***


# HIPAA
Source: https://documentation.onesignal.com/docs/en/hipaa

Overview of OneSignal’s HIPAA compliance, including BAAs for enterprise customers.

## What is Health Insurance Portability and Accountability Act of 1996 (HIPAA)?

The Health Insurance Portability and Accountability Act of 1996 (HIPAA) regulates how healthcare information should be shared and stored by healthcare providers (“covered entities”) and companies like us that work with these providers (“business associates”). It's a vital regulation that ensures companies that process health information take adequate protection in ensuring the security of personal health information (PHI).

## OneSignal’s commitment to HIPAA compliance

In order to reach HIPAA compliance, OneSignal has completed a risk assessment of our organization and systems. This includes reviewing how our systems appropriately adheres to the security rule and privacy rule under HIPAA. Thankfully, our efforts were made easier by the work we did in achieving SOC 2 Type II compliance.

## Looking for our Business Associate Agreement (BAA)?

We are happy to say that we now support a core aspect of HIPAA compliance by offering a Business Associate Agreement (BAA) to Enterprise Plan customers. For customers interested in learning more about our HIPAA compliance, [reach out to our sales team](https://onesignal.com/contact) for more information.

***


# HubSpot
Source: https://documentation.onesignal.com/docs/en/hubspot

Automate push notifications, emails, SMS, and in-app messaging from HubSpot Workflows using the native OneSignal integration.

## Overview

The OneSignal HubSpot integration connects your HubSpot CRM to OneSignal through native workflow actions — no third-party middleware required. You can:

* **Send messages** — trigger push notifications, emails, and SMS from HubSpot Workflows
* **Create users** — sync HubSpot contacts to OneSignal with email and SMS subscriptions
* **Manage tags** — set or delete OneSignal [Tags](./add-user-data-tags) based on HubSpot contact properties
* **Target in-app messages** — use tags set by HubSpot to build segments that control in-app message delivery

For capabilities like A/B testing, intelligent delivery, throttling, and retargeting, use the OneSignal dashboard or API directly alongside HubSpot.

<Tip>
  Read [Four Ways to Use the OneSignal Integration with HubSpot](https://onesignal.com/blog/four-ways-to-use-the-onesignal-integration-with-hubspot-to-boost-engagement-across-channels/) for real-world examples.
</Tip>

<Frame>
  <iframe title="OneSignal HubSpot integration overview" />
</Frame>

***

## Prerequisites

* HubSpot Super Admin role or [App Marketplace Permissions](https://knowledge.hubspot.com/settings/hubspot-user-permissions-guide#admin)
* A [paid OneSignal plan](https://onesignal.com/pricing) (not available on free plans)

<Info>
  HubSpot deprecated the original third-party OneSignal app in December 2024. OneSignal now provides its own HubSpot app with expanded functionality. If you used the previous integration, see the migration steps below.
</Info>

<Accordion title="Migrating from the legacy HubSpot integration">
  **Install the new integration**

  Activate the HubSpot integration from the OneSignal dashboard under **Data > Integrations** as described in [Connect HubSpot to OneSignal](#connect-hubspot-to-onesignal) below.

  **Migrate your workflows**

  We recommend creating a new workflow to test the new integration before replacing actions in your existing workflows.

  1. **Clone your workflow** — On the HubSpot **Workflows** page, click **Clone** next to your existing workflow.
  2. **Remove triggers** — In the cloned workflow, remove all enrollment triggers so it does not fire automatically when published.
  3. **Replace legacy actions** — Remove each legacy OneSignal action and replace it with the new version. If both apps are installed, the legacy app shows "Built by HubSpot" — use the one that does not.

  <Frame>
    <img />
  </Frame>

  4. **Test with a single contact** — Save and publish the workflow, then manually enroll one test contact. Check the enrollment history to verify actions completed successfully.

  <Frame>
    <img />
  </Frame>

  5. **Replace or update** — After confirming the workflow works correctly, either replace the original workflow with the clone or apply the same changes to the original.

  If you encounter errors during migration, contact `support@onesignal.com`.
</Accordion>

***

## Connect HubSpot to OneSignal

### Activate the integration

In OneSignal, go to **Data > Integrations > Catalog** and select **HubSpot**.

<Frame>
  <img />
</Frame>

Click **Settings > Authenticate**, then select your HubSpot account and log in.

<Warning>
  You can only connect one HubSpot account to each OneSignal app. If you have a testing environment, you can setup another OneSignal app for testing.
</Warning>

<Frame>
  <img />
</Frame>

After agreeing to the terms and selecting **Connect app**, you are redirected to OneSignal. Open the newly connected HubSpot account to confirm the connection.

### Match users with External ID

To link HubSpot contacts to OneSignal users, set the [External ID](./users) in OneSignal to a value that matches a unique property in HubSpot (e.g., a user ID or email address).

Set External ID using the SDK `login` method in your app or website. Choose a property that is readily available in both your app and HubSpot so matching is reliable.

<Info>
  See [Users](./users) and [Subscriptions](./subscriptions) for details on identity and subscription management.
</Info>

### Create a HubSpot workflow

In HubSpot, go to **Automation > Workflows** and click **Create workflow**. Select **Contact-based** and configure your enrollment triggers.

To add a OneSignal action, click **+** in the workflow editor and search for "OneSignal."

<Frame>
  <img />
</Frame>

Every OneSignal action requires two fields:

<Frame>
  <img />
</Frame>

* **OneSignal App** — the app you connected during setup
* **External ID** — the HubSpot contact property that matches the External ID in OneSignal

***

## OneSignal actions

### Create OneSignal users from HubSpot

The **Create User** action creates a [User](./users) in OneSignal when a contact passes through the workflow. Use this to keep OneSignal and HubSpot in sync as new contacts are added.

If the following HubSpot properties are set, OneSignal automatically creates corresponding [Subscriptions](./subscriptions):

* **Email** → creates an email subscription in OneSignal
* **Phone number** → creates an SMS subscription in OneSignal

You can also set the External ID and tags within the Create User node.

<Frame>
  <img />
</Frame>

<Warning>
  If your OneSignal app has [Double Opt-in](./sms-opt-in-and-collection#promotional-double-opt-in-form) enabled, new SMS subscriptions automatically receive an opt-in message. You can disable this in the Create User node — the SMS subscription will be created but the user will not be subscribed until they opt in separately.
</Warning>

***

### Edit OneSignal tags from HubSpot

The **Edit Tags** action sets or deletes [Tags](./add-user-data-tags) on the matched OneSignal user. Tags enable [Message Personalization](./message-personalization) and [Segmentation](./segmentation), and are the mechanism for [targeting in-app messages from HubSpot](#send-in-app-messages-with-hubspot).

#### Set tags

Enter a JSON object in the Tags field:

```json theme={null}
{ "welcome": "1", "name": "<First Name property>" }
```

You can inject any HubSpot contact property as a tag value by using HubSpot's property token inserter in the workflow editor. For example, adding a user's first name as a tag so you can personalize messages in OneSignal.

#### Delete tags

Set the value to an empty string to remove a tag:

```json theme={null}
{ "old_tag": "" }
```

If the tag does not exist on the user, it is ignored.

<Frame>
  <img />
</Frame>

***

### Send messages from HubSpot workflows

The **Send Notification** action delivers a push notification, email, or SMS to the matched OneSignal user.

<Tip>
  Match users by **OneSignal External ID** rather than email. Email matching is a legacy option for customers who set email using the `addEmail` SDK method.
</Tip>

<Frame>
  <img />
</Frame>

**Using a template**

Select a predefined [Template](./templates) created in the OneSignal dashboard or API. Templates support push notifications, email, and SMS.

**Using form fields**

If you do not select a template, you can compose a push notification directly in the workflow action using the Title, Subtitle, Message, Image URL, and Launch URL fields. Email and SMS are only available via templates.

The form fields option allows you to inject HubSpot contact properties (e.g., `First Name`) to personalize the notification content.

***

#### Send in-app messages with HubSpot

In-app messages cannot be sent directly from a HubSpot workflow. Instead, use HubSpot to tag users, then target those users with a segment-based in-app message in OneSignal.

<Steps>
  <Step title="Tag users from HubSpot">
    In your HubSpot workflow, use the [Edit Tags](#edit-onesignal-tags-from-hubspot) action to set a tag on contacts. For example: `{ "hubspot_campaign": "spring_promo" }`.
  </Step>

  <Step title="Create a segment in OneSignal">
    In the OneSignal dashboard, go to **Audience > Segments** and click **New Segment**. Add a **User Tag** filter matching the tag key and value set by HubSpot (e.g., `hubspot_campaign` is `spring_promo`).
  </Step>

  <Step title="Create the in-app message">
    Go to **Messages > In-App** and create a new in-app message. Under **Audience**, select **Show to Particular Segment(s)** and choose the segment you created.

    As users pass through the HubSpot workflow and receive the tag, they are added to the segment immediately.
  </Step>

  <Step title="Configure the trigger">
    Tags do not trigger in-app messages on their own. If the tag is set while the user is actively using the app, the in-app message does not display until the next session (a new session starts after the app is in the background for 30+ seconds).

    Available triggers:

    * **On app open** — displays the next time the user opens the app
    * **Session duration** — displays after a set number of seconds in-session
    * **Time since last in-app message** — prevents back-to-back messages
    * **Programmatic** — trigger from your app code using the OneSignal SDK

    See [In-App Message Triggers](./iam-triggers) for details on combining triggers with AND/OR operators.
  </Step>
</Steps>

***

## Common workflow patterns

HubSpot workflows combine **enrollment triggers** (the event that starts the workflow) with **OneSignal actions** (what happens to the user in OneSignal). Below are recommended patterns for common use cases.

<Info>
  Every workflow pattern below assumes you have already [connected HubSpot to OneSignal](#connect-hubspot-to-onesignal) and are [matching users via External ID](#match-users-with-external-id).
</Info>

### Welcome and onboarding

Send a welcome message when a new user signs up, and tag them for onboarding in-app messages.

| Step                   | Type                         | Configuration                                                                                                          |
| ---------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Enrollment trigger** | HubSpot                      | Contact property `Became a customer date` is known                                                                     |
| **Action 1**           | OneSignal: Create User       | Set External ID to the HubSpot contact property that matches your app (e.g., a user ID or email address)               |
| **Action 2**           | OneSignal: Edit Tags         | `{ "onboarding": "active", "name": "<First Name>" }` — insert the HubSpot First Name property token for the name value |
| **Action 3**           | OneSignal: Send Notification | Use a welcome push template, or compose inline with a personalized greeting                                            |

<Tip>
  Pair this with an [in-app message](#send-in-app-messages-with-hubspot) that targets the `onboarding` = `active` segment to guide new users through your app on first launch.
</Tip>

### Re-engagement

Reach out to users who have not visited your app recently.

| Step                   | Type                         | Configuration                                                               |
| ---------------------- | ---------------------------- | --------------------------------------------------------------------------- |
| **Enrollment trigger** | HubSpot                      | Contact property `Last activity date` is more than 14 days ago              |
| **Action 1**           | OneSignal: Send Notification | Use a re-engagement push template (e.g., "We miss you — here's what's new") |
| **Delay**              | HubSpot: Wait 3 days         | —                                                                           |
| **If/then branch**     | HubSpot                      | Check if contact has visited your site since enrollment                     |
| **Yes branch**         | OneSignal: Edit Tags         | `{ "reengaged": "true" }`                                                   |
| **No branch**          | OneSignal: Send Notification | Use an email template with a stronger incentive                             |

### Lifecycle stage change

Sync lifecycle stage changes in HubSpot with OneSignal tags so you can target different user segments.

| Step                   | Type                         | Configuration                                                                                                  |
| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Enrollment trigger** | HubSpot                      | Contact property `Lifecycle stage` changes to any value                                                        |
| **Action 1**           | OneSignal: Edit Tags         | `{ "lifecycle_stage": "<Lifecycle Stage>" }` — insert the HubSpot Lifecycle Stage property token for the value |
| **If/then branch**     | HubSpot                      | Check if lifecycle stage = `Customer`                                                                          |
| **Yes branch**         | OneSignal: Send Notification | Use a "Welcome to the family" push or email template                                                           |

### Deal closed / post-purchase

Trigger a thank-you message and tag users for upsell campaigns after a deal closes.

| Step                   | Type                         | Configuration                                                                                                    |
| ---------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Enrollment trigger** | HubSpot                      | Deal property `Deal stage` = `Closed Won`                                                                        |
| **Action 1**           | OneSignal: Edit Tags         | `{ "customer": "true", "deal_value": "<Amount>" }` — insert the HubSpot Deal Amount property token for the value |
| **Action 2**           | OneSignal: Send Notification | Use a thank-you email template                                                                                   |
| **Delay**              | HubSpot: Wait 7 days         | —                                                                                                                |
| **Action 3**           | OneSignal: Send Notification | Use an upsell/cross-sell push template                                                                           |

<Note>
  Deal-based workflows require a **Deal-based** workflow type in HubSpot. Use the associated contact's External ID to match the OneSignal user.
</Note>

### Promotional campaign via in-app message

Target a specific audience with an in-app message triggered by a HubSpot list or form.

| Step                   | Type                 | Configuration                                                                      |
| ---------------------- | -------------------- | ---------------------------------------------------------------------------------- |
| **Enrollment trigger** | HubSpot              | Contact becomes a member of a static or active list (e.g., "Spring Sale Eligible") |
| **Action 1**           | OneSignal: Edit Tags | `{ "promo": "spring_2025" }`                                                       |

Then follow the [Send in-app messages with HubSpot](#send-in-app-messages-with-hubspot) steps to create a OneSignal segment matching `promo` = `spring_2025` and configure an in-app message for that segment.

To remove users from the campaign after it ends, create a second workflow that deletes the tag:

| Step                   | Type                 | Configuration                            |
| ---------------------- | -------------------- | ---------------------------------------- |
| **Enrollment trigger** | HubSpot              | Date-based, set to the campaign end date |
| **Action 1**           | OneSignal: Edit Tags | `{ "promo": "" }`                        |

***

## Troubleshooting

### Workflow action shows "Failed" in HubSpot

1. **Check the error message** — Expand the failed action in the HubSpot workflow enrollment history. The error message often indicates the cause (e.g., "User not found," "Invalid app ID").
2. **Verify the External ID** — Confirm the HubSpot contact property used as the External ID matches a user in OneSignal. Check the user's profile in **OneSignal > Audience > Users** and search by External ID.
3. **Confirm the integration is active** — Go to **OneSignal > Data > Integrations > HubSpot** and verify the connection status is active.

### Message sent but user did not receive it

1. **Check subscriptions** — The user must have an active subscription for the channel you're sending on (push, email, or SMS). Verify this in the user's profile in OneSignal under **Subscriptions**.
2. **Check segment membership** — If you're using a template with segment targeting, confirm the user belongs to the targeted segment.
3. **Review message reports** — In the OneSignal dashboard, go to **Messages**, find the message, and check its delivery report to see if the message was delivered, dropped, or errored.

### Tags not appearing on the OneSignal user

1. **Verify External ID matching** — If the External ID in the workflow does not match an existing OneSignal user, the Edit Tags action silently fails. Use the **Create User** action before Edit Tags to ensure the user exists.
2. **Check JSON format** — Tags must be a valid JSON object. Common mistakes include missing quotes around keys or values, trailing commas, or using single quotes instead of double quotes.
3. **Check for empty values** — Setting a tag value to `""` deletes the tag. Verify that HubSpot contact properties being injected are not blank.

### In-app message not displaying

See [Why didn't my in-app message display after the tag was set?](#why-didnt-my-in-app-message-display-after-the-tag-was-set) in the FAQ below.

***

## FAQ

### What data is shared between HubSpot and OneSignal?

| HubSpot            | Direction | OneSignal         | Description                                                                                                            |
| ------------------ | --------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Contact properties | →         | External ID, Tags | HubSpot contact data matches and enriches OneSignal users via [External ID](./users) and [Tags](./add-user-data-tags). |
| Workflows          | ←         | Message Templates | OneSignal [Templates](./templates) are available for selection in HubSpot workflow actions.                            |

The integration does not sync HubSpot lists, deals, or company records to OneSignal automatically. Use workflow actions to explicitly pass the data you need.

### What happens if the External ID doesn't match a OneSignal user?

The **Send Notification** and **Edit Tags** actions silently fail — no message is sent and no tags are set. Always place a **Create User** action before other OneSignal actions in your workflow to ensure the user exists in OneSignal.

### Can I use HubSpot lists to target OneSignal segments?

Not directly. HubSpot lists and OneSignal segments are independent systems. To bridge them, create a workflow that enrolls contacts from a HubSpot list and uses the **Edit Tags** action to set a tag. Then build a OneSignal segment based on that tag. See [Promotional campaign via in-app message](#promotional-campaign-via-in-app-message) for a worked example.

### Which OneSignal channels can I send from HubSpot?

Push notifications can be sent using templates or form fields. Email and SMS can only be sent using [Templates](./templates) created in OneSignal. In-app messages cannot be sent from HubSpot workflows — use the [tag-and-segment pattern](#send-in-app-messages-with-hubspot) instead.

### Why didn't my in-app message display after the tag was set?

Tags alone do not trigger in-app messages. The tag adds the user to a segment, but the in-app message still requires a **trigger** to display. If the tag is set while the user is actively using the app, the message will not appear until the next session (30+ seconds in background). Set the in-app message trigger to **On app open** for the most reliable behavior. See [In-App Message Triggers](./iam-triggers) for all trigger options.

### Can I use HubSpot webhooks to call the OneSignal API directly?

Yes. HubSpot's **Custom Code** workflow action lets you make HTTP requests to external APIs. You can call the [OneSignal REST API](/reference/create-notification) to send messages, create users, or update tags outside the native integration. This is useful for use cases the native actions do not cover, such as sending to a segment rather than an individual user.

### Can I send OneSignal message events back to HubSpot?

Yes. Use [Event Streams](./event-streams) to export OneSignal message events (sent, clicked, etc.) to a webhook endpoint. You can route these events to HubSpot's [Custom Events API](https://developers.hubspot.com/docs/api/analytics/events) or use a middleware service to update HubSpot contact properties based on OneSignal engagement data.

### Can I trigger a OneSignal Journey from HubSpot?

There are two options for getting HubSpot users into a OneSignal [Journey](./journeys-overview):

1. **Tags** — Use the [Edit Tags](#edit-onesignal-tags-from-hubspot) action to set a tag on the user. Create a segment in OneSignal based on that tag and use the segment as a Journey entry condition.
2. **Custom Events** — Use HubSpot's **Custom Code** action to call the [OneSignal Custom Events API](/reference/create-custom-events), which can serve as a Journey entry trigger.

### Can I send custom events from HubSpot to OneSignal?

Not through the native workflow actions. The native integration supports Create User, Edit Tags, and Send Notification. To send custom events, use HubSpot's **Custom Code** action to call the [OneSignal Custom Events API](/reference/create-custom-events) directly.

### What HubSpot enrollment triggers work with OneSignal?

Any HubSpot enrollment trigger works — the OneSignal actions are standard workflow actions that execute regardless of how the contact was enrolled. Common triggers include:

* **Contact property changes** (lifecycle stage, lead status, last activity date)
* **Form submissions** (signup forms, demo requests, event registrations)
* **List membership** (added to a static or active list)
* **Deal stage changes** (pipeline progression, closed won/lost)
* **Date-based** (scheduled campaigns, time since an event)
* **Manual enrollment** (for one-off sends or testing)

### How do I test a workflow before going live?

1. Create the workflow and remove all automatic enrollment triggers
2. Save and publish the workflow
3. Manually enroll a single test contact
4. Check the enrollment history in HubSpot for action success/failure
5. Verify the user, tags, or message in the OneSignal dashboard
6. Once confirmed, add your enrollment triggers and re-publish

***

<Columns>
  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Add custom properties to users for personalization and segmentation.
  </Card>

  <Card title="Templates" icon="file-lines" href="./templates">
    Create reusable message templates for push, email, and SMS.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build automated multichannel messaging flows triggered by user behavior.
  </Card>

  <Card title="Event Streams" icon="bolt" href="./event-streams">
    Export real-time message events to external platforms via webhooks.
  </Card>

  <Card title="Segmentation" icon="users" href="./segmentation">
    Build audience segments based on tags, behavior, and user properties.
  </Card>

  <Card title="In-App Message Triggers" icon="bell" href="./iam-triggers">
    Control when and how in-app messages display to users.
  </Card>
</Columns>


# In-app message event streams
Source: https://documentation.onesignal.com/docs/en/iam-event-streams

How to utilize event streams to capture in-app message metrics

This document explains the capabilities and usage of our [In-App Messages](./in-app-messages-setup) events. You can track essential engagement statistics each time a user clicks or views these messages including block-level clicks and page-specific displays.

## In-app message events

There are three kinds [`event.kind`](./event-streams-data#event-kind) of In-App Message Events:

* In-app Impression - `message.iam.impression`
* In-app Clicked - `message.iam.clicked`
* In-app Page Displayed - `message.iam.page_displayed`

These events are fired upon a user opening and interacting with an in-app message on device.

### In-app impression

This event fires as soon as the message finishes loading and displayed on screen.

When using [carousels](./design-your-in-app-message#carousels), you can get the name and UUID of the specific page that is shown by using `event.data.page_name` and `event.data.page_id`.

### In-app clicked

This event is applicable to any element or block with a click action (also referred to as “target”). You can get the name and UUID of the specific target that is clicked on by using `event.data.target_name` and `event.data.target_id`, as well as the page the target belongs to using `event.data.page_name` and `event.data.page_id`.

See [In-app click actions](./iam-click-actions) for details.

### In-app page displayed

This is an event that is only applicable to [carousels](./design-your-in-app-message#carousels). You can get the name and UUID of the specific page or card that is shown by using `event.data.page_name` and `event.data.page_id`. The impression for the first card is fired as soon as the document finishes loading. Subsequent page impressions are fired upon swipe.

## In-app message event data

Each `event.kind` can have additional event data depending on how you create the in-app message.

<ParamField type="string">
  The name of the page or card that is displayed when the `event.kind` is `clicked` or `page_displayed`. Not available for `impression` events.

  The `page_name` is helpful to know which page was displayed and what was clicked on that page.

  Page names default to "Card 1", "Card 2", etc. but you can change the names within the Block Editor.

  <Frame>
    <img />
  </Frame>
</ParamField>

<ParamField type="string UUID v4">
  A unique identifier for the page. Helpful for cases of using a [carousel](./design-your-in-app-message#carousels) and an old card is deleted or replaced with a new card.
</ParamField>

<ParamField type="string">
  The name of the button or image block element. You must set a [click actions](./iam-click-actions).
</ParamField>

<ParamField type="string UUID v4">
  A unique identifier for the button or image block element. You must set a [click actions](./iam-click-actions). This is helpful when using a [carousel](./design-your-in-app-message#carousels) and an old card is deleted or replaced with a new card.
</ParamField>

## Create your in-app message Event Stream

### Setup event streams

Review the [Event Stream Setup](./event-streams#setup) instructions for guidance on setting up and personalizing your event stream. The following provides IAM-specific steps for configuring your event stream (step 3).

## Ensure the target you want to track is set up correctly

In order to leverage custom names in the body of an event streams request you must manually specify a new custom name in the Block or HTML editor. In-App Messages that have existed prior to the release of custom names will not be able to expose `page_name` and `target_name` values in the event stream until the In-App is updated with custom names for each page or block.

After the In-App has been updated, event stream requests that are triggered from that moment on will have access to those values. At any given time, the `page_name` and `target_name` values will reflect the custom names state of the In-App at that moment, which may change if the In-App is ever updated again.

<Tabs>
  <Tab title="Block editor">
    All three events can be used with this editor. When using the block editor, ensure that the target contains an [In-app click action](./iam-click-actions). A target includes images, buttons, the close button, and the background block. Text blocks do not currently support click actions and are not included.

    Target custom names should be unique to avoid confusion in the dashboard experience.
  </Tab>

  <Tab title="HTML editor">
    Only In-app Impression and Clicked events can be used with this editor. When using the HTML editor, you can track clicks on any element type, not just buttons and images. There are 2 requirements:

    1. The element must have the `data-onesignal-unique-label="<insert_value>"` attribute to track a target
    2. The element must have an event listener applied to it that calls a method from the embedded [In-app JS library](./in-app-message-api) aka `OneSignalIamAPI`.

    Note: To avoid confusion, ensure target names are unique. For critical uniqueness, such as custom internal reporting, use the `target_id`, which is guaranteed unique by OneSignal. Note that using `data-onesignal-unique-label` attributes with the same label on multiple elements will merge their analytics. Changing these labels retains previous data under the original label, with new data assigned to the new label. For precise tracking, prioritize `target_id`.

    For example:

    <CodeGroup>
      ```html html theme={null}
      // For elements that do something like tag a user or prompt a push do something like this:

      <body>
        <button data-onesignal-unique-label="my-tag-user-button">Tag User</button>
      </body>
      <script>
        document
          .querySelector("button[data-onesignal-unique-label="my-tag-user-button")
          .addEventListener("click", function(e) {
            OneSignalIamApi.tagUser(e, { fiz: "baz" });
           });
      </script>

      // or for elements that don't require any specific functionality of the OneSignalIamApi other than click tracking, just call trackClick

      <body>
        <button data-onesignal-unique-label="my-button">Click Here</button>
      </body>
      <script>
        document
          .querySelector("button[data-onesignal-unique-label="my-button")
          .addEventListener("click", function(e) {
            OneSignalIamApi.trackClick(e);
           });
      </script>
      ```
    </CodeGroup>

    **Sample Input:**

    <CodeGroup>
      ```json json theme={null}
      {
        "page_name":"{{ event.data.page_name }}",
        "page_id":"{{ event.data.page_id }}",
        "target_id":"{{ event.data.target_id }}",
        "target_name":"{{ event.data.target_name }}",
        "iam_id":"{{ message.id }}",
        "iam_name":"{{ message.name }}",
        "event_kind": "{{ event.kind }}"
      }
      ```
    </CodeGroup>

    **Sample Output:**

    <CodeGroup>
      ```json json theme={null}
      {
        "page_name" : "html_page",
        "page_id": "d8b28eda-add3-59f8-a12d-07c70642363b" ,
        "target_id": "6bab1bd9-4de6-557b-b5ed-ecb85baed f89",
        "target_name": "my-location-prompt-button",
        "iam_id": "bb6329b6-f81a-44aa-a571-30ef6746de0c",
        "iam_name": "html iam naming",
        "event_kind": "message. iam.clicked"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Utilize unique IDs

Best Practice: When using Event Streams for analytics purposes, use `message.id`, `page_id`, and `target_id` to validate uniqueness. Custom names can be used but are meant to help differentiate between elements in one IAM in a human-readable format. If you have multiple in-app messages, use `message.id` to differentiate them.

### Use clear names in the block editor

Use meaningful and unique names for all in-app message titles, cards, and blocks to simplify data analysis. To rename a card in a carousel, select the tab you want to update, and select the “Options” dropdown next to the card tabs. You’ll see an option to rename the card.

To rename a block, select the three-dot options menu on the top right-hand corner of each block to open up the renaming modal. All custom names will be reflected in the dashboard report and event stream, if applicable. Custom names will not appear in even streams unless they are set and saved. If you have active IAMs and have recently set up a new IAM event stream, you will want to ensure these IAMs have meaningful custom names for cleaner analysis.

***


# Identity verification
Source: https://documentation.onesignal.com/docs/en/identity-verification

Prevent user impersonation by requiring server-generated JWTs to verify External User IDs, email, and SMS subscriptions sent to OneSignal.

## Overview

OneSignal offers an enhanced security feature called Identity Verification to help prevent user impersonation. This feature utilizes JSON Web Tokens – or [JWTs](https://jwt.io/introduction), securely generated on your server. To verify subscription information, these tokens are passed to your app and OneSignal’s API.

Enable Identity Verification to secure:

* Logging in users
* Adding email subscriptions
* Adding SMS subscriptions
* Modifying user identities

<Warning>
  Identity Verification is currently in beta. Contact `support@onesignal.com` to have it enabled for your account. Once support enables it, you activate it in your dashboard (see [Step 5](#enable-token-identity-verification-in-the-dashboard)).
</Warning>

## Prerequisites

* An existing OneSignal app with a configured push platform.

* A mobile app integrated with one of the supported SDKs:

  * [OneSignal Android SDK 5.2.0+](https://github.com/OneSignal/OneSignal-Android-SDK/releases)
  * [OneSignal iOS SDK 5.3.0+](https://github.com/OneSignal/OneSignal-iOS-SDK/releases)

<Note>
  Wrapper SDK support (Flutter, React Native, Unity, etc.) is coming soon.
</Note>

## Setup

<Steps>
  <Step title="Generate new keys">
    Log in to your OneSignal account and navigate to **Settings > Keys & IDs > Identity Verification**.

    <Frame>
      <img alt="Settings page showing Keys and IDs with Identity Verification section" />
    </Frame>

    Click **Generate New Keys** to create a new key pair.

    <Frame>
      <img alt="Generate New Keys button in the Identity Verification section" />
    </Frame>

    Download the PEM file or copy the private key, making sure to store the private key securely.

    <Frame>
      <img alt="Identity Verification key pair with private key and PEM download" />
    </Frame>

    <Warning>
      Always store your private keys in a secure environment, such as a key management system. Never expose private keys in client-side code, public repositories, or logs.
    </Warning>
  </Step>

  <Step title="Generate verification JWT on your backend">
    Identity verification requires authenticating the end-user with your authentication server **before** logging them into OneSignal. When the end-user authenticates with your backend, generate the token and include it in the auth response to the device. If your app doesn’t run a backend server, consider setting up a lightweight server to verify users and generate these tokens.

    #### JWT payload

    The JWT can have the following properties:

    <ParamField>
      Your OneSignal App ID
    </ParamField>

    <ParamField>
      The token expiration date.
    </ParamField>

    <ParamField>
      The user's alias.
    </ParamField>

    <ParamField>
      Required only when adding Email and SMS subscriptions to a user.
    </ParamField>

    #### Signing the JWT

    Sign the JWT using the ES256 algorithm. Ensure your backend is configured to use this signing method to avoid verification issues when sending the JWT to OneSignal. We recommend a [JWT Library](https://jwt.io/libraries) to do this.

    Example using [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken):

    <CodeGroup>
      ```typescript Node.js theme={null}
      import jwt from 'jsonwebtoken';

      const APP_ID = process.env['ONESIGNAL_APP_ID']
      const IDENTITY_VERIFICATION_SECRET = process.env['ONESIGNAL_IDENTITY_VERIFICATION_SECRET_KEY']

      // Generates JWT, potentially with subscription claims, for the user identified by the External ID
      function signOneSignalJWT(externalId, subscriptions) {
      return jwt.sign({
      iss: APP_ID,
      exp: Math.floor(Date.now() / 1000) + 3600, // 1-hour expiration
      identity: {
      'external_id': externalId,
      },
      subscriptions
      },
      IDENTITY_VERIFICATION_SECRET,
      { algorithm: 'ES256' });
      }

      // Pass this token to your mobile app to use with the `login` SDK method
      const onesignalJWT = signOneSignalJWT('EXTERNAL_ID');

      ```
    </CodeGroup>

    The private key is in the previous step's file we downloaded from the Dashboard.

    #### Verify your JWT

    Before integrating with the SDK, verify your JWT is being generated correctly by starting your server and calling the endpoint:

    <CodeGroup>
      ```typescript Node.js theme={null}
        node server.js
      ```
    </CodeGroup>

    <CodeGroup>
      ```bash cURL theme={null}
        curl http://localhost:3000/generate-jwt/your-external-id
      ```
    </CodeGroup>

    You should receive a response like:

    ```json theme={null}
    {
      "jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
    ```

    Paste the JWT value at [jwt.io](https://jwt.io) and confirm the decoded payload contains the following parameters:

    ```json theme={null}
    {
      "iss": "your-onesignal-app-id",
      "exp": 1234567890,
      "identity": {
        "external_id": "your-external-id"
      }
    }
    ```

    Confirm the following before moving on to the next step:

    * `iss` matches your OneSignal App ID from **Settings > Keys & IDs**
    * `identity.external_id` is present and matches the value you will pass to `OneSignal.login()`
    * `exp` is a future timestamp — an expired token will be rejected by OneSignal

    #### Including subscriptions

    Ideally, subscription details, such as email or phone number, get included in the JWT payload when logging a user in. If these details aren’t available upfront, your verification server must provide an endpoint to generate tokens dynamically as subscription information becomes available.

    Example: Generating JWT to add subscriptions

    <CodeGroup>
      ```typescript Node.js theme={null}
      const subscriptions = [
        {
            "type": "Email",
            "token": "[email protected]"
        },
        {
            "type": "SMS",
            "token": "+12345678"
        }
      ]
      const onesignalJWT = signOneSignalJWT('EXTERNAL_ID', subscriptions)
      ```
    </CodeGroup>
  </Step>

  <Step title="Pass JWT to the `login` method">
    Once your backend generates the JWT, call the `login` method with it. This token ensures the user’s identity is verified before any changes, such as adding an email or SMS subscription, can be made.

    Example of logging in:

    <CodeGroup>
      ```java java theme={null}
      String externalId = "YOUR_EXTERNAL_ID";
      String onesignalJWT = "YOUR_JWT_TOKEN";

      OneSignal.login(externalId, onesignalJWT);
      ```

      ```kotlin kotlin theme={null}
      val externalId = "YOUR_EXTERNAL_ID"
      val onesignalJWT = "YOUR_JWT_TOKEN"

      OneSignal.login(externalId, onesignalJWT)
      ```

      ```swift Swift theme={null}
      let externalId = "YOUR_EXTERNAL_ID"
      let onesignalJWT = "YOUR_JWT_TOKEN"

      OneSignal.login(externalId: externalId, token: onesignalJWT)
      ```

      ```c objective-c theme={null}
      NSString* externalId = @"YOUR_EXTERNAL_ID";
      NSString* onesignalJWT = @"YOUR_JWT_TOKEN";

      [OneSignal login:externalId withToken:onesignalJWT];
      ```
    </CodeGroup>
  </Step>

  <Step title="Handle JWT lifecycle events">
    You’ll need to implement a dedicated endpoint on your backend to handle scenarios like token invalidation. This endpoint should provide a refreshed JWT when OneSignal requests an update.

    Example of handling token invalidation and refreshing the JWT:

    <CodeGroup>
      ```java java theme={null}
      OneSignal.addUserJwtInvalidatedListener(event -> {
        // Get the expired user's External ID
        String externalId = event.getExternalId();

        // Fetch a new JWT from your backend for the user
        String onesignalJWT = "yourUpdatedToken";

        // Provide the new JWT to the SDK
        OneSignal.updateUserJwt(externalId, onesignalJWT);
      });
      ```

      ```kotlin kotlin theme={null}
      OneSignal.addUserJwtInvalidatedListener(
         object : IUserJwtInvalidatedListener {
             override fun onUserJwtInvalidated(event: UserJwtInvalidatedEvent) {
               val externalId = event.externalId
               val onesignalJWT = ""
               updateUserJwt(externalId, onesignalJWT)
             }
         },
      )
      ```

      ```swift Swift theme={null}
      class AppDelegate: UIResponder, UIApplicationDelegate, OSUserJwtInvalidatedListener {
        func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
          // Set self to listen for JWT invalidated events
          OneSignal.addUserJwtInvalidatedListener(self)

          // Remove the JWT listener as needed by calling:
          // `OneSignal.removeUserJwtInvalidatedListener(self)`
        }

        // Required to conform to `OSUserJwtInvalidatedListener` protocol
        func onUserJwtInvalidated(event: OneSignalUser.OSUserJwtInvalidatedEvent) {
          // Get the expired user's External ID
          let externalId = event.externalId

          // Fetch a new JWT from your backend for the user
          let onesignalJWT = "yourUpdatedToken"

          // Provide the new JWT to the SDK
          OneSignal.updateUserJwt(externalId: externalId, token: onesignalJWT)
        }
      }
      ```

      ```c objective-c theme={null}
      @interface MyListener: NSObject<OSUserJwtInvalidatedListener>
      @end

      @implementation MyListener
      - (void)onUserJwtInvalidatedWithEvent:(OSUserJwtInvalidatedEvent * _Nonnull)event {
        // Get the expired user's External ID
        NSString *externalId = event.externalId;

        // Fetch a new JWT from your backend for the user
        NSString *onesignalJWT = @"yourUpdatedToken";

        // Provide the new JWT to the SDK
      	[OneSignal updateUserJwt:externalId withToken:onesignalJWT];
      }

      // Add or remove your User Jwt Invalidated Listener
      [OneSignal addUserJwtInvalidatedListener:myListener];
      [OneSignal removeUserJwtInvalidatedListener:myListener];
      ```
    </CodeGroup>

    This ensures that when a user’s JWT is invalidated, a new one can be fetched from your backend and passed to OneSignal. You can also use this function to generate a token with an email and phone number, allowing you to manage email and SMS subscriptions if the token created during authentication does not contain them.
  </Step>

  <Step title="Enable token identity verification in the dashboard">
    From **Settings > Keys & IDs**, toggle **Token Identity Verification** to enable.

    <Frame>
      <img alt="Token Identity Verification toggle enabled in dashboard settings" />
    </Frame>

    Once enabled, your app must send OneSignal JWTs to verify subscription authenticity. Additionally, your app is required to call the `login` method using a JWT generated by your identity verification token server.
  </Step>
</Steps>

## Adding subscriptions

You don’t need to take extra steps to add subscriptions from your mobile app; calling the login method automatically handles this for you.

<Tabs>
  <Tab title="Add an email">
    <CodeGroup>
      ```java java theme={null}
      OneSignal.getUser().addEmail(emailAddress);
      ```

      ```kotlin kotlin theme={null}
      OneSignal.getUser().addEmail(emailAddress)
      ```

      ```swift Swift theme={null}
      // If you have not already included it in your JWT token, update the JWT with the email
      let onesignalJWT = "newTokenThatContainsTheEmailToAdd"
      OneSignal.updateUserJwt(externalId: externalId, token: onesignalJWT)

      // Add the email
      OneSignal.User.addEmail(emailAddress)
      ```

      ```c objective-c theme={null}
      // If you have not already included it in your JWT token, update the JWT with the email
      NSString *onesignalJWT = @"newTokenThatContainsTheEmailToAdd";
      [OneSignal updateUserJwt:externalId withToken:onesignalJWT];

      // Add the email
      [OneSignal.User addEmail:emailAddress];
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Add a phone number">
    <CodeGroup>
      ```java java theme={null}
      OneSignal.getUser().addSms(smsNumber);
      ```

      ```kotlin kotlin theme={null}
      OneSignal.getUser().addSms(smsNumber)
      ```

      ```swift Swift theme={null}
      // If you have not already included it in your JWT token, update the JWT with the sms
      let onesignalJWT = "newTokenThatContainsTheSmsToAdd"
      OneSignal.updateUserJwt(externalId: externalId, token: onesignalJWT)

      // Add the sms number
      OneSignal.User.addSms(smsNumber)
      ```

      ```c objective-c theme={null}
      // If you have not already included it in your JWT token, update the JWT with the sms
      NSString *onesignalJWT = @"newTokenThatContainsTheSmsToAdd";
      [OneSignal updateUserJwt:externalId withToken:onesignalJWT];

      // Add the sms number
      [OneSignal.User addSms:smsNumber];
      ```
    </CodeGroup>
  </Tab>
</Tabs>

***

## REST API

When Token Identity Verification is enabled, all requests to the following APIs must include a server-generated JWT in the headers as a bearer token, e.g., `Authorization: Bearer <JWT>`.

* [Create user](/reference/create-user)
* [View user](/reference/view-user)
* [Update user](/reference/update-user)
* [Delete user](/reference/delete-user)
* [View user identity](/reference/fetch-aliases)
* [Create alias](/reference/create-alias)
* [Delete alias](/reference/delete-alias)
* [Create subscription](/reference/create-subscription)
* [Update subscription](/reference/update-subscription)

***

## FAQ

### Is identity verification required?

No, but it is strongly recommended. Without it, any client that knows a user's External ID can impersonate that user and modify their subscriptions or data.

### What happens if the JWT expires during a session?

The SDK triggers a JWT invalidation event. Implement the `addUserJwtInvalidatedListener` (see [Handle JWT lifecycle events](#handle-jwt-lifecycle-events)) to fetch a refreshed token from your backend and pass it to `updateUserJwt`.

### Which SDKs support identity verification?

Currently, the native Android SDK (5.2.0+) and iOS SDK (5.3.0+). Wrapper SDK support (Flutter, React Native, Unity, etc.) is coming soon.

### Do I need identity verification for the REST API?

When Token Identity Verification is enabled, all requests to the [supported APIs](#rest-api) must include a server-generated JWT as a bearer token in the `Authorization` header. The JWT is generated the same way as for SDK use.

### What algorithm does the JWT use?

Identity Verification requires JWTs signed with the **ES256** algorithm (ECDSA using P-256 and SHA-256). Other algorithms will be rejected.

***


# Import
Source: https://documentation.onesignal.com/docs/en/import

Import or update users in OneSignal using CSV uploads, REST API, or manual entry. Supports email, SMS, tags, and more for seamless user onboarding or migration.

Import or update users in bulk through the OneSignal dashboard using a CSV file or manual entry. Common use cases include migrating users from another platform, updating user details, and organizing users with [Tags](./add-user-data-tags) and [Segments](./segmentation).

<Note>
  You can also update or create users via the [REST API](/reference/create-user).
</Note>

## CSV import

Use a CSV file to import or update email addresses, phone numbers, external IDs, [Tags](./add-user-data-tags), language, timezone, country, and more.

### CSV requirements

Make sure your `.csv` file meets the following requirements:

* UTF-8 encoding (without BOM)
* No non-printable characters (no special characters or non-ASCII characters)
* Clean, unique column headers
* File size under 150 MB (about 2 million rows)
* At least one identifier from the following:
  * `external_id` — Recommended. Identifies [Users](./users) across all [Subscriptions](./subscriptions).
  * `email` — Required for creating new email subscriptions. See [Email address validation](./email-address-validation) for more info.
  * `phone_number` — Required for creating new SMS subscriptions.
  * `subscription_id` — Only recommended for cases where you track Subscription IDs on your backend and want to set an `external_id`.

<Warning>
  Only one identifier of each type is allowed per row. To associate multiple emails or phone numbers with the same user, use separate rows sharing the same `external_id`.
</Warning>

<Tip>
  * Include `external_id` to deduplicate Users. Make sure it matches the ID used in your SDK `login` method — otherwise it resets when the user opens the app.
  * To change subscription status, the row must include `email`, `phone_number`, or `subscription_id`. An `external_id` alone is not enough.
  * `subscription_id` does not link or merge Subscriptions. Use `external_id` to add new emails or phone numbers to an existing user.
</Tip>

#### Supported columns

<ParamField type="String">
  Your user ID. See [External ID](./users#external-id) for more info. Should be the same ID used via the SDK `login` method.
</ParamField>

<ParamField type="String">
  The user's email address. Creates an Email [Subscription](./subscriptions). Deduplicated if already present in the app.
</ParamField>

<ParamField type="String in E.164 format">
  The user's phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164) like `+15555551234`. Creates an SMS [Subscription](./subscriptions). Deduplicated if already present in the app.
</ParamField>

<ParamField type="String (UUID v4 assigned by OneSignal)">
  Only recommended if you already track OneSignal [Subscription IDs](./subscriptions) on your backend.
</ParamField>

<ParamField type="Boolean ('yes', 'no')">
  Sets subscription status. Requires `email`, `phone_number`, or `subscription_id` in the same row — cannot be used with `external_id` alone.
</ParamField>

<ParamField type="Boolean ('true', 'false')">
  Use with `email` to add or remove from the [Suppression List](./suppressions).

  * `true` adds the email to suppression list.
  * `false` removes the email from suppression list.
</ParamField>

<ParamField type="String (IANA TZ formatted time zones)">
  The user's timezone in [IANA TZ format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

  e.g.) `America/New_York`, `Europe/London`, `Asia/Tokyo`
</ParamField>

<ParamField type="String (2-character ISO 3166-2 codes)">
  The user's country code in [ISO 3166-2 format](https://www.iso.org/obp/ui/).

  e.g.) `GB` for United Kingdom, `US` for United States
</ParamField>

<ParamField type="String (ISO 639-1 codes)">
  The user's language in [ISO 639-1 format](./multi-language-messaging#supported-languages).

  e.g) `en` for English, `es` for Spanish, `fr` for French
</ParamField>

<ParamField type="String">
  Include up to 1,000 [Tags](./add-user-data-tags) per import. Use tag keys in the column headers and tag values in the rows. You can also use a single `tags` column with JSON formatting — see [Bulk tag updates](#bulk-tag-updates) for details.
</ParamField>

#### Tag limits and restrictions

Tag [plan limits](https://onesignal.com/pricing) apply per user, not per app. For example, if your plan allows 20 tags per user and a user already has 19, you can only add 1 more — even though the app itself can have unlimited tag keys.

* Use the [Bulk tag updates](#bulk-tag-updates) workflow to export users, clear unwanted tag values, and re-import with the delete option enabled.
* Avoid spaces in tag keys — use underscores instead.

**Reserved and restricted tag keys**

The following tag keys are reserved and should not be used:

* "user"
* "subscription"
* "message"
* "template"
* "app"
* "org"
* "custom\_data"
* "dynamic\_content"

If you accidentally set one of these as a tag key, remove it via the [Update User API](/reference/update-user).

**Tag overwrites and deletions**

During a CSV import:

* Tags included in your CSV are overwritten with the value provided.
* Tags not included in your CSV remain unchanged on the user record.

If a tag is still present after import, verify that:

* The header column contains the tag key.
* The row contains no value.
* You selected the "Delete tags with blank values" option in the [Review screen](#review-and-confirm).

**Other sources of tags being added**

If deleted tags reappear after import, an integration may be automatically writing them back. Common sources include:

* Segment
* HubSpot
* Journeys
* SDK Tagging methods
* Custom APIs or ETL pipelines

Review integration mappings and event triggers to ensure they are not overwriting your CSV changes.

#### Email address validation

Email address validation detects common problems in email addresses before they reach your audience. It flags typos, invalid domains, role-based addresses, and disposable email services that could increase your bounce rate or hurt your sender reputation.

<Card title="Email address validation" icon="circle-check" href="./email-address-validation">
  Validate email addresses during CSV import and in bulk to reduce bounces and protect your sender reputation.
</Card>

#### Use AI to check your CSV before import

If you have errors or questions about your CSV formatting, you can describe your CSV problem to an AI tool (like Claude, ChatGPT, or similar) to automatically clean or rebuild your file before importing again.

<Warning>Always test with a small sample (5-10 rows) before importing thousands of records.</Warning>

<Accordion title="Example AI prompts for common CSV issues">
  <Tabs>
    <Tab title="Deleting tags">
      ```text AI prompt example for deleting unwanted tags theme={null}
      I want to remove all tags except "user_name" from this CSV.

      Please:
      1. Keep only the "user_name" tag column.
      2. Remove all other tag columns.
      3. Format the CSV so it matches the OneSignal import requirements in this doc:
         https://documentation.onesignal.com/docs/en/import

      Here is my CSV:
      [PASTE CSV]

      ```
    </Tab>

    <Tab title="Tag formatting">
      ```text AI prompt example for fixing multiple tag columns format theme={null}
      I have multiple tag columns such as tag_first_name, tag_last_name, and tag_city.

      According to the OneSignal import documentation, each tag must:
      - Use the tag_ prefix
      - Contain only alphanumeric characters and underscores
      - Follow supported data types

      Could you review my CSV, identify what is incorrectly formatted, and return a corrected version that meets these requirements?

      Documentation link:
      https://documentation.onesignal.com/docs/en/import

      ```
    </Tab>

    <Tab title="Identify invalid formats">
      ```text AI prompt example for identifying missing or invalid formatting theme={null}
      OneSignal rejected my CSV during import.

      Please:
      1. Validate my CSV structure.
      2. Identify any formatting issues (headers, ID columns, tag formats, quoting).
      3. Return a corrected version that follows the requirements in this doc:
         https://documentation.onesignal.com/docs/en/import#csv-requirements

      Here is the file:
      [PASTE CSV]

      ```
    </Tab>

    <Tab title="Fix phone numbers">
      ```text AI prompt example for fixing invalid phone number formats (E.164) theme={null}
      My import is failing because phone numbers are not in E.164 format.

      Please:
      1. Convert all phone numbers to E.164 format.
      2. Keep all other fields unchanged.
      3. Ensure the CSV matches OneSignal's required structure:
         https://documentation.onesignal.com/docs/en/import

      Example of current format: (555) 555-1234

      Here is my CSV:
      [PASTE CSV]

      ```
    </Tab>

    <Tab title="Migrate from another platform">
      ```text AI prompt example for data from another platform theme={null}
      I'm migrating from [Platform Name] to OneSignal.

      Could you transform this CSV to match OneSignal's import format?
      Include:
      - `external_id`
      - Any tags converted with the `tag_` prefix (if desired)
      - Phone numbers in E.164 format (if applicable)

      Reference doc:
      https://documentation.onesignal.com/docs/en/import

      Here is my CSV:
      [PASTE CSV]

      ```
    </Tab>
  </Tabs>
</Accordion>

### Import steps

Navigate to **Audience > Import** and click **Launch CSV Importer**.

<Steps>
  <Step title="Upload your CSV">
    Select your prepared CSV file.

    <Frame>
      <img alt="CSV file upload screen in the OneSignal dashboard" />
    </Frame>
  </Step>

  <Step title="Map fields">
    OneSignal auto-maps your CSV headers to known properties. Review the mappings before confirming — use `external_id`, `email`, `phone_number`, and/or `subscription_id` as **identifiers**, not tags.

    <Warning>
      To add a new email or phone number to an existing user, you **must use** `external_id`. Do **not** use `subscription_id` — it will not link or merge Subscriptions.
    </Warning>

    <Frame>
      <img alt="Map Fields screen showing column headers mapped to OneSignal properties" />
    </Frame>

    If OneSignal detects format issues, fix the CSV and re-upload (recommended) or uncheck the affected column to skip it.
  </Step>

  <Step title="Review and confirm">
    The Review screen allows you to:

    * **Automatically create a Segment** — Adds a tag to each imported user and creates a matching [Segment](./segmentation). Be mindful of your [plan limits](https://onesignal.com/pricing).
    * **Delete tags with blank values** — Removes any tag where the value is blank in the CSV. This is useful for cleaning up unwanted tags and staying under plan limits.
    * **Configure email address validation** — Configure [email address validation](./email-address-validation) settings to reduce bounces and protect your sender reputation.

    For example, given this CSV:

    ```csv theme={null}
    external_id,tag1,tag2
    UserA,,"tag2value"
    UserB,"tag1value",
    ```

    With "Delete tags with blank values" enabled, `tag1` is deleted from UserA and `tag2` is deleted from UserB.

    <Frame>
      <img alt="Review screen with options to create a segment and delete blank tags" />
    </Frame>

    Click **Confirm and Import**. A status screen shows progress.
  </Step>
</Steps>

<Check>
  Import started. You'll receive a confirmation email from `contact@onesignal.com` when it completes.
</Check>

### Email confirmation

Once the import finishes, you receive a confirmation email from `contact@onesignal.com` with the following data. Note that a single [User](./users) can have multiple [Subscriptions](./subscriptions) (e.g., email + push), so subscription counts may be higher than your row count.

**Subscription record(s) added** — New email or SMS [Subscriptions](./subscriptions) created. `0` means no unique `email` or `phone_number` identifiers were found.

**Subscription record(s) modified** — [Subscriptions](./subscriptions) where data changed (tags, properties, etc.). For example, 10 External IDs each linked to 20 subscriptions = `200` records modified.

**Subscription updates skipped** — [Subscriptions](./subscriptions) skipped for the stated reason. If the reason is "over your app's tag limit," remove tags and re-import or upgrade your plan.

**Not imported** — Rows that were not updated or imported. Common causes: the `external_id` does not match any existing subscription, or the `email`/`phone_number` already exists with no new data to set.

**Created new segment** — The segment name, if you selected that option.

<Frame>
  <img alt="Email confirmation showing counts for subscriptions added, modified, skipped, and not imported" />
</Frame>

In the example above:

* `100` subscriptions were created from unique email addresses or phone numbers not already in the app.
* `37,814` subscriptions were updated (not the count of Users — each user can have multiple subscriptions).
* `621,852` rows were not imported because their External IDs did not match existing users, or their emails/phone numbers already existed with no new data.

<Warning>
  [Segments](./segmentation) only count **subscribed** [Subscriptions](./subscriptions). Unsubscribed subscriptions are updated by the import but not reflected in segment counts. Improvements to segmentation are in progress.
</Warning>

### Common use cases

#### Bulk tag updates

You can add, update, or delete [Tags](./add-user-data-tags) in bulk using the CSV import. This section covers how to format tags for import and how to remove unwanted tags.

**Import tags from a single column**

Instead of using separate column headers for each tag key, you can set a single `tags` header with each row containing a JSON map of all key-value pairs within quotes. This is especially useful if you previously exported a CSV with tags and want to re-import it without reformatting.

```text CSV header theme={null}
external_id,email,tags
```

Tags must be formatted as a JSON object enclosed in 2 sets of double quotes around each key-value pair.

```text CSV row example theme={null}
userA,example@email.com,"{""level"":""30"",""color"":""teal""}"
```

When imported, OneSignal automatically converts each key-value pair into distinct tags. For example, the above row would be converted to 2 tags: `level:30` and `color:teal`.

**Bulk delete tags**

To remove tags in bulk, export your current data, blank out the tag values, and re-import the CSV with the delete option enabled.

<Steps>
  <Step title="Export your data">
    * Navigate to **Audience > Subscriptions** in the OneSignal dashboard. Enable only the **External ID**, **Subscription ID**, and **Tags** columns (and optionally **Email** or **Phone Number**).
    * Click **Export** to export the CSV.

    <Frame>
      <img alt="Select the displayable columns for export" />
    </Frame>
  </Step>

  <Step title="Clear the tag values you want to delete">
    Open the exported CSV in a text editor and set the values of each tag you want to delete as an empty string.

    For example, a row with tag values before editing:

    ```text Row before editing theme={null}
    userA,example@email.com,"{""level"":""30"",""color"":""teal""}"
    ```

    The same row after clearing the tag values:

    ```text Row after clearing tag values theme={null}
    userA,example@email.com,"{""level"":"""",""color"":""""}"
    ```

    This will result in deleting the tags `level` and `color` from the user.
  </Step>

  <Step title="Re-import the CSV with the delete option">
    * Take the edited CSV and import.
    * On the [Review](#review-and-confirm) screen, select **Yes** for **Delete tags with blank values**. OneSignal deletes the tags with blank values during import.

    <Frame>
      <img alt="Review screen with remove tags with empty values option" />
    </Frame>
  </Step>
</Steps>

<Tip>
  To remove only specific tags, clear the values for those tags and leave the others unchanged. Only blank values are deleted when the delete option is enabled.
</Tip>

<Note>
  Need help?

  * Try the [Use AI to check your CSV before import](#use-ai-to-check-your-csv-before-import) section above.
  * Contact `support@onesignal.com` and share the CSV file you uploaded along with a screenshot of the confirmation email. We are happy to take a look!
</Note>

***

## Manual entry

You can manually add users' email and phone number Subscriptions through the OneSignal dashboard by navigating to **Audience > Users > Update/Import Users > Manually Add Users**.

<Frame>
  <img alt="Manual user entry form in the OneSignal dashboard" />
</Frame>

On the **New User** screen, include the data you want and select **Create User**.

***

## FAQ

### How long does a CSV import take?

Most imports complete within a few minutes depending on file size. You receive a confirmation email from `contact@onesignal.com` when the import finishes.

### Can I undo a CSV import?

No. Prepare a new CSV with the correct values and re-import it. For tag deletions, use the [Bulk tag updates](#bulk-tag-updates) workflow.

### Why don't my segment counts match the rows in my CSV?

[Segments](./segmentation) only count **subscribed** [Subscriptions](./subscriptions). Unsubscribed subscriptions are updated but not reflected in segment counts. See the [Email confirmation](#email-confirmation) section for details.

### Why did my import show "not imported" for some rows?

Rows are skipped when the `external_id` does not match any existing subscription, or when the `email`/`phone_number` already exists with no new data to set. See [Email confirmation](#email-confirmation) for details on each status.

### Why do deleted tags keep coming back?

An integration or SDK call may be re-adding them. See [Other sources of tags being added](#other-sources-of-tags-being-added) for common causes and how to fix them.


# Integrations overview
Source: https://documentation.onesignal.com/docs/en/integrations

Connect OneSignal to third-party platforms, sync data with analytics tools, and automate messaging workflows.

OneSignal integrates with a wide range of platforms—from data warehouses and CRMs to analytics and automation tools.

Explore the [full integrations catalog](https://onesignal.com/integrations) or [become a partner](https://onesignal.com/contact-partners). To build your own integration, follow the [partner integration guide](./building-an-integration-with-onesignal-partner-guide).

<Note>
  Need something custom? You can [connect to any database, DMP, or CRM](./database-dmp-crm-integration).

  Looking for webhooks? See [Event Streams](./event-streams) for real-time message events or [Journey webhooks](./journeys-webhook) for user-specific automation.
</Note>

## How to choose an integration

| Goal                                                          | Section                                              |
| ------------------------------------------------------------- | ---------------------------------------------------- |
| Full bidirectional sync (events, audiences, and message data) | [Featured integrations](#featured-integrations)      |
| Send custom events or audience data **into** OneSignal        | [Inbound](#inbound-to-onesignal)                     |
| Export message event data **from** OneSignal                  | [Outbound](#outbound-from-onesignal)                 |
| Track attribution, purchases, or enrich user profiles         | [Attribution & enrichment](#attribution--enrichment) |
| Trigger messages from external workflow tools                 | [Automation](#automation)                            |
| Build apps with native OneSignal support                      | [App creation](#app-creation)                        |

***

## Featured integrations

These integrations support full bidirectional data sync:

* Import custom events into OneSignal
* Sync audience cohorts with OneSignal
* Export message events from OneSignal

<Columns>
  <Card title="Mixpanel" icon="chart-mixed" href="./mixpanel">
    Sync cohorts, export message events, and import custom events between Mixpanel and OneSignal.
  </Card>

  <Card title="Amplitude" icon="chart-line" href="./amplitude">
    Sync cohorts, export message events, and import custom events between Amplitude and OneSignal.
  </Card>

  <Card title="Twilio Segment" icon="share-nodes" href="./segment-onesignal-integration">
    Route events, traits, and audiences between Segment and OneSignal in both directions.
  </Card>

  <Card title="HubSpot" icon="address-book" href="./hubspot">
    Trigger messages, create and update users, and sync audience data via HubSpot workflows.
  </Card>
</Columns>

***

## Inbound (to OneSignal)

Import audience data, tags, and custom events from external platforms into OneSignal.

<Tip>
  [Amplitude](./amplitude), [HubSpot](./hubspot), [Mixpanel](./mixpanel), and [Twilio Segment](./segment-onesignal-integration) also support inbound data sync. See [Featured integrations](#featured-integrations).
</Tip>

<Card title="Adobe Audience Manager" icon="users" href="./adobe-audience-manager">
  Import audience segments from Adobe Audience Manager into OneSignal.
</Card>

### Custom event sources

Connect databases, data warehouses, and streaming platforms to import custom events into OneSignal.

<Columns>
  <Card title="AlloyDB" icon="database" href="./alloydb">
    Import custom events from your AlloyDB database.
  </Card>

  <Card title="Amazon Athena" icon="database" href="./amazon-athena">
    Query and import custom events from Amazon Athena.
  </Card>

  <Card title="Amazon S3" icon="box-archive" href="./s3">
    Import custom events from S3 buckets.
  </Card>

  <Card title="Apache Kafka" icon="bolt" href="./kafka">
    Stream custom events from Kafka topics.
  </Card>

  <Card title="AWS Redshift" icon="database" href="./amazon-redshift">
    Import custom events from your Redshift data warehouse.
  </Card>

  <Card title="Azure Synapse" icon="database" href="./azure-synapse">
    Import custom events from Azure Synapse Analytics.
  </Card>

  <Card title="ClickHouse" icon="database" href="./clickhouse">
    Import custom events from your ClickHouse database.
  </Card>

  <Card title="Confluent Cloud" icon="bolt" href="./confluent-cloud">
    Stream custom events from Confluent Cloud.
  </Card>

  <Card title="Databricks" icon="cubes" href="./databricks">
    Import custom events from Databricks lakehouses.
  </Card>

  <Card title="Elasticsearch" icon="magnifying-glass" href="./elasticsearch">
    Import custom events from Elasticsearch indices.
  </Card>

  <Card title="Google BigQuery" icon="database" href="./bigquery">
    Import custom events from BigQuery datasets.
  </Card>

  <Card title="Google Cloud SQL" icon="database" href="./google-cloud-sql">
    Import custom events from Cloud SQL instances.
  </Card>

  <Card title="Google Pub/Sub" icon="bolt" href="./google-pubsub">
    Stream custom events from Pub/Sub topics.
  </Card>

  <Card title="Google Sheets" icon="table" href="./google-sheets">
    Import custom events from Google Sheets spreadsheets.
  </Card>

  <Card title="Greenplum" icon="database" href="./greenplum">
    Import custom events from your Greenplum database.
  </Card>

  <Card title="Materialize" icon="database" href="./materialize">
    Import custom events from Materialize streaming views.
  </Card>

  <Card title="Microsoft Fabric" icon="database" href="./microsoft-fabric">
    Import custom events from Microsoft Fabric lakehouses.
  </Card>

  <Card title="MotherDuck" icon="database" href="./motherduck">
    Import custom events from your MotherDuck database.
  </Card>

  <Card title="MySQL" icon="database" href="./mysql">
    Import custom events from your MySQL database.
  </Card>

  <Card title="PostgreSQL" icon="database" href="./postgresql">
    Import custom events from your PostgreSQL database.
  </Card>

  <Card title="SingleStore" icon="database" href="./singlestore">
    Import custom events from your SingleStore database.
  </Card>

  <Card title="Snowflake" icon="snowflake" href="./snowflake">
    Import custom events from your Snowflake warehouse.
  </Card>

  <Card title="SQL Server" icon="database" href="./sql-server">
    Import custom events from your SQL Server database.
  </Card>

  <Card title="Starburst Enterprise" icon="star" href="./starburst-enterprise">
    Import custom events via Starburst Enterprise queries.
  </Card>

  <Card title="Starburst Galaxy" icon="star" href="./starburst-galaxy">
    Import custom events via Starburst Galaxy queries.
  </Card>

  <Card title="Trino" icon="database" href="./trino">
    Import custom events via Trino queries.
  </Card>
</Columns>

***

## Outbound (from OneSignal)

Export message event data from OneSignal to analytics or storage platforms.

<Tip>
  [Amplitude](./amplitude), [Mixpanel](./mixpanel), and [Twilio Segment](./segment-onesignal-integration) also support outbound message event sync. See [Featured integrations](#featured-integrations).
</Tip>

<Columns>
  <Card title="Databricks" icon="cubes" href="./databricks">
    Export message events to Databricks lakehouses.
  </Card>

  <Card title="Google BigQuery" icon="database" href="./bigquery">
    Export message events to BigQuery datasets.
  </Card>

  <Card title="Snowflake" icon="snowflake" href="./snowflake">
    Export message events to your Snowflake warehouse.
  </Card>
</Columns>

***

## Attribution & enrichment

Track in-app purchases, attribution, and user traits to enrich subscriber profiles.

<Columns>
  <Card title="Adjust" icon="sliders" href="./adjust">
    Sync mobile attribution data with OneSignal.
  </Card>

  <Card title="AppsFlyer" icon="paper-plane" href="https://support.appsflyer.com/hc/en-us/articles/360015926437">
    Sync mobile attribution data from AppsFlyer.
  </Card>

  <Card title="BlueConic" icon="users" href="./blueconic">
    Import audience profiles and segments from BlueConic.
  </Card>

  <Card title="HubSpot" icon="address-book" href="./hubspot">
    Import contact properties and audience data from HubSpot.
  </Card>

  <Card title="RevenueCat" icon="credit-card" href="./revenuecat">
    Sync in-app subscription and purchase data from RevenueCat.
  </Card>
</Columns>

***

## Automation

Trigger push messages and update users from external automation platforms.

<Columns>
  <Card title="ActiveCampaign" icon="gears" href="./activecampaign">
    Trigger OneSignal messages from the ActiveCampaign automation canvas.
  </Card>

  <Card title="HubSpot" icon="address-book" href="./hubspot">
    Send messages and update users via HubSpot workflows.
  </Card>
</Columns>

***

## App creation

Build apps with native OneSignal push notification support.

<Columns>
  <Card title="FlutterFlow" icon="mobile-screen-button" href="./flutterflow-sdk-setup">
    Build Flutter apps with drag-and-drop and native OneSignal push.
  </Card>

  <Card title="Median" icon="mobile-screen-button" href="https://median.co/docs/onesignal">
    Convert websites into native mobile apps with OneSignal push notifications.
  </Card>

  <Card title="Andromo" icon="mobile-screen-button" href="https://www.andromo.com/docs/setting-up-onesignal-notifications-on-your-andromo-powered-android-app/">
    Build Android apps with Andromo and enable OneSignal push notifications.
  </Card>

  <Card title="Retool" icon="screwdriver-wrench" href="https://docs.retool.com/docs/onesignal-integration">
    Build internal tools with Retool and trigger OneSignal messages.
  </Card>
</Columns>


# iOS p12 certificate generation
Source: https://documentation.onesignal.com/docs/en/ios-p12-generate-certificates

Generate and upload a .p12 push certificate to connect your iOS or macOS app to Apple Push Notification service (APNs) through OneSignal.

Sending push notifications to iOS apps requires an authenticated connection to Apple Push Notification service (APNs). You can authenticate using a **[token-based (.p8 key)](./ios-p8-token-based-connection-to-apns)** or a **certificate-based (.p12 file)** method — only one is necessary.

<Warning>
  .p12 certificates expire after one year. If you don't want to manage annual renewal, [create a .p8 key](./ios-p8-token-based-connection-to-apns) instead — .p8 keys do not expire.
</Warning>

This guide covers the **certificate-based (.p12 file)** method. This is not recommended because you must renew it annually, which requires generating a new certificate in your Apple Developer Account and re-uploading it to your OneSignal dashboard.

***

## Requirements

Make sure you have the following before starting:

* An iOS or macOS app.
* A [**Paid Apple Developer Account**](https://developer.apple.com/) with [**Admin** access](https://appstoreconnect.apple.com/access/users).
* A [**OneSignal Account**](https://onesignal.com).
* A Mac with Xcode 14+.
* The **Bundle ID** for your app target as set in Xcode.
* An Xcode project with **Push Notification capability enabled**.

***

## Create a Certificate Signing Request (CSR)

You first need to create a `.certSigningRequest` file on macOS.

1. Open **Applications > Utilities > Keychain Access**.
2. From the menu bar, click **Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority...**

<Frame>
  <img alt="Keychain Access menu showing Certificate Assistant option" />
</Frame>

3. Fill in the required fields:
   * **User Email Address**: `[email protected]`
   * **Common Name**: Your name or the name for the certificate
   * **CA Email Address**: Leave this blank
   * **Request is**: Select **Saved to disk**

<Frame>
  <img alt="Certificate Assistant window with email, common name, and Saved to disk fields" />
</Frame>

4. Click **Continue**, choose a location to save the `.certSigningRequest` file, and click **Save**.

***

## Enable push capabilities for the app

<Note>
  Skip this section if you use **Automatically manage signing** in Xcode.
</Note>

1. Go to the [Identifiers](https://developer.apple.com/account/ios/identifier/bundle) section of the Apple Developer portal, locate and select your app's **App ID** from the list.

<Frame>
  <img alt="Apple Developer Identifiers section showing list of App IDs" />
</Frame>

2. Enable the **Push Notifications** capability by checking the box.

<Warning>
  **Do not** click **"Configure"** — just enable the toggle.
</Warning>

<Frame>
  <img alt="App ID capabilities list with Push Notifications checkbox enabled" />
</Frame>

***

## Create a push certificate

Follow these steps to generate the Apple Push Notification service (APNs) SSL certificate:

1. Visit the [Apple Certificates page](https://developer.apple.com/account/resources/certificates/add).

2. Click the **plus (+)** button to create a new certificate.

3. Under **Services**, select:

   * **Apple Push Notification service SSL (Sandbox & Production)**
   * Then click **Continue**

   <Frame>
     <img alt="Apple Certificates page showing Apple Push Notification service SSL Sandbox and Production option" />
   </Frame>

4. Select your **App ID** from the list and click **Continue**.

<Frame>
  <img alt="App ID selection dropdown for the push certificate" />
</Frame>

5. Upload your previously generated `.certSigningRequest` file.

<Frame>
  <img alt="Upload Certificate Signing Request file dialog" />
</Frame>

6. Click **Continue**, then click **Download** to save the resulting `.cer` file to your computer.

<Frame>
  <img alt="Download button for the generated .cer certificate file" />
</Frame>

You’ll use this `.cer` file in the next section to create your `.p12` certificate.

***

## Create a private key and export the .p12 certificate

1. **Double-click** the downloaded `.cer` file to import it into **Keychain Access**.

2. In Keychain Access, navigate to:

   * **Keychains > Login**
   * **Category > My Certificates**

3. Locate the certificate named **Apple Push Services**.

4. **Right-click** the certificate and select **Export**.

<Frame>
  <img alt="Keychain Access right-click menu showing Export option for Apple Push Services certificate" />
</Frame>

5. Choose a location to save the file, and select the file format as **`.p12`**.

6. When prompted, set a **password** for the `.p12` file. You will need this password when uploading to OneSignal.

<Frame>
  <img alt="Save dialog showing .p12 file format selection and password prompt" />
</Frame>

***

## Upload the .p12 to OneSignal

1. In your [OneSignal dashboard](https://onesignal.com), go to your app > **Settings > Push & In-App > Apple iOS**.
2. Upload the `.p12` file (and enter the password if you set one). Click **Save**.

<Check>
  You’ve successfully set up **APNs authentication using a .p12 certificate** in OneSignal.

  Your iOS app is now ready to send and receive push notifications! 🎉
</Check>

***

## .p12 troubleshooting

### Invalid certificate format error

**Cause:** The uploaded file is not in `.p12` format.

**Fix:** Ensure you export the certificate from Keychain Access **as `.p12`** (not `.cer` or `.pem`).

### "Incorrect password" when uploading to OneSignal

**Cause:** Password was entered incorrectly or not set.

**Fix:**

* Try exporting again and set a **new password**.
* Ensure no extra spaces are added when pasting.
* If using Provisionator, the password is shown in the UI.

### Missing private key in exported file

**Cause:** Certificate was imported but not paired with a private key.

**Fix:**

* Make sure you **generate the CSR** from Keychain Access on the same machine.
* After downloading the `.cer` file, double-click to install and check if the key appears under **My Certificates**.

### Push notifications not working after upload

**Cause:** Incorrect App ID, or Provisioning Profile missing capabilities.

**Fix:**

* Confirm the `.p12` matches the **App ID** used in the app.
* In Apple Developer Portal, ensure the App ID has **Push Notifications enabled**.
* Make sure the Provisioning Profile includes **Push**.

### Expired certificate

**Cause:** `.p12` certificate is no longer valid.

**Fix:**

* Go to Apple Developer > Certificates and check expiry.
* Revoke the old certificate and create a new one.

***

## Next steps

<Columns>
  <Card title="iOS SDK setup" icon="apple" href="./ios-sdk-setup">
    Install the OneSignal SDK, initialize it in your app, and send a test notification.
  </Card>

  <Card title="Mobile SDK setup" icon="mobile" href="./mobile-sdk-setup">
    Choose your platform and follow the full SDK integration guide for Android, iOS, or cross-platform frameworks.
  </Card>
</Columns>

***

## FAQ

### When does my .p12 certificate expire, and how do I renew it?

.p12 certificates expire **one year** after creation. To renew, generate a new CSR, create a new push certificate in Apple Developer, export it as .p12, and re-upload it to your OneSignal dashboard. Set a calendar reminder to avoid disruption. Alternatively, switch to a [.p8 key](./ios-p8-token-based-connection-to-apns), which does not expire.

### Should I use .p8 or .p12?

OneSignal recommends **.p8 keys** for most apps. A .p8 key does not expire, works across all apps under your Apple Developer account, and is simpler to manage. A .p12 certificate is app-specific and must be renewed annually. See the [.p8 key guide](./ios-p8-token-based-connection-to-apns) for setup instructions.

### Do I need a provisioning profile, and how do I create one?

Yes, Apple requires different types of profiles for development, testing (Ad Hoc), and distribution to the App Store.

In Xcode, select **Automatically manage signing** to create one automatically.

<Frame>
  <img alt="Xcode Signing and Capabilities tab with Automatically manage signing enabled" />
</Frame>

Otherwise, see [Apple's docs on provisioning profiles](https://developer.apple.com/help/account/provisioning-profiles/provisioning-profile-updates) for details.

***


# iOS p8 token-based connection to APNs
Source: https://documentation.onesignal.com/docs/en/ios-p8-token-based-connection-to-apns

Set up a .p8 authentication key to connect your iOS or macOS app to Apple Push Notification service (APNs) through OneSignal.

Sending push notifications to iOS apps requires an authenticated connection to Apple Push Notification service (APNs). You can authenticate using a **token-based (.p8 key)** or a **[certificate-based (.p12 file)](./ios-p12-generate-certificates)** method — only one is necessary.

This guide covers the **token-based .p8 key**, the recommended approach.

***

## Requirements

Make sure you have the following before starting:

* An iOS mobile app.
* A [**Paid Apple Developer Account**](https://developer.apple.com/) with [**Admin** access](https://appstoreconnect.apple.com/access/users).
* A [**OneSignal Account**](https://onesignal.com).
* A Mac with Xcode 14+.
* An Xcode project with **Push Notification capability enabled**.

***

## Set up APNs authentication

### Generate your .p8 key in Apple Developer Account

<Tip>
  For Apple's full instructions, see [Create a private key to access a service](https://developer.apple.com/help/account/keys/create-a-private-key/).
</Tip>

1. Log into your [Apple Developer Account](https://developer.apple.com/).
2. Go to **Certificates, Identifiers & Profiles > [Keys](https://developer.apple.com/account/resources/authkeys)**.
3. Click the **blue plus (+)** icon.
   * If you don’t see it, contact your Admin for access.

<Frame>
  <img alt="Apple Developer Keys page showing the blue plus icon to create a new key" />
</Frame>

4. Select **Apple Push Notifications service (APNs)**.
5. When configuring the key, ensure that **Sandbox & Production** is selected:

<Frame>
  <img alt="Apple Developer key configuration with Sandbox and Production selected" />
</Frame>

6. Enter a name for the key and click **Continue**, then **Register**.

<Frame>
  <img alt="Apple Developer key registration page with Continue and Register buttons" />
</Frame>

7. **Download your .p8 key** and store it securely. You won’t be able to download it again.

***

### Upload the .p8 key to OneSignal

1. Navigate to **Settings > Push & In-App > Apple iOS (APNs) Settings** in your OneSignal dashboard.

<Frame>
  <img alt="OneSignal Settings page showing Push and In-App section with Apple iOS APNs settings" />
</Frame>

2. Choose **.p8 Auth Key (Recommended)** as the authentication method.

<Frame>
  <img alt="OneSignal APNs authentication method selection showing p8 Auth Key recommended option" />
</Frame>

Provide the following:

* **`.p8 File`** – The private key file you downloaded from your Apple Developer account.
* **`Key ID`** – A 10-character alphanumeric string (e.g., `ABC123DEFG`) found next to your key name in the [Keys section](https://developer.apple.com/account/resources/authkeys) of your Apple Developer account. Make sure it matches the downloaded .p8 file.
* **`Team ID`** – A 10-character alphanumeric string (e.g., `9A1B2C3D4E`) shown next to your team name in the top-right corner of your [Apple Developer account](https://developer.apple.com/account/). This is **not** the same as the Key ID.
* **`App Bundle ID`** – A reverse-domain string (e.g., `com.example.app`) found in:
  * The [Identifiers section](https://developer.apple.com/account/resources/identifiers/list) of your Apple Developer account, or
  * **Xcode > Main App Target > Signing & Capabilities**

<Warning>
  **Key ID** and **Team ID** are both 10-character strings found in your Apple Developer account but in different locations. Double-check you haven't swapped them — this is the most common misconfiguration.
</Warning>

<Frame>
  <img alt="Apple Developer account showing Key ID and Team ID locations" />
</Frame>

<Frame>
  <img alt="Xcode Signing and Capabilities tab showing the Bundle Identifier field" />
</Frame>

Click **Save & Continue** when done.

<Check>
  You’ve successfully set up **APNs authentication using a .p8 key** in OneSignal.

  Your iOS app is now ready to send and receive push notifications! 🎉
</Check>

***

## .p8 troubleshooting

<Steps>
  <Step title="Check .p8 file format">
    * Open the `.p8` file in a text editor.

    * It should look like this:

      ```text theme={null}
      -----BEGIN PRIVATE KEY-----
      64 character line
      64 character line
      64 character line
      8 character line
      -----END PRIVATE KEY-----
      ```
  </Step>

  <Step title="Ensure you didn’t upload a .p12 by mistake">
    * `.p8` keys come from the **Keys** section of your Apple Developer account.
    * `.p12` certificates are from the **Certificates** section. These are not compatible with .p8 authentication.
  </Step>

  <Step title="Confirm you have the correct Key ID">
    * Go to your [Apple Developer > Keys section](https://developer.apple.com/account/resources/authkeys).
    * The Key ID is the 10-character string shown next to your key name (e.g., `ABC123DEFG`).
    * Match the Key ID you entered in OneSignal with the one listed for the downloaded `.p8` key.
    * **Do not confuse this with your Team ID** — both are 10-character strings but found in different places.
  </Step>

  <Step title="Verify the Team ID">
    * Your **Team ID** is the 10-character string shown next to your team name in the top-right corner of your [Apple Developer account](https://developer.apple.com/account/).
    * Make sure it is copied exactly and matches the account where the key was generated.
    * **Do not confuse this with your Key ID** — the Team ID identifies your developer account, not a specific key.
  </Step>

  <Step title="Ensure the key has apns capability">
    * When viewing your key in Apple Developer, the **Apple Push Notifications service (APNs)** capability should be listed.
    * If not, revoke the key and create a new one.
  </Step>

  <Step title="Wait a few minutes">
    * Newly created keys may take **10–15 minutes** to propagate before Apple allows external authentication.
    * If you get validation errors immediately after creation, wait and try again.
  </Step>
</Steps>

### Need help?

* Revoke the current `.p8` key and create a new one from scratch.
* Double-check you’re using a **valid Bundle ID** from the same account the key was created under.
* Reach out to `support@onesignal.com` with a screenshot of your Apple Developer Key configuration and the Key ID, Team ID, and Bundle ID.

***

## Next steps

<Columns>
  <Card title="iOS SDK setup" icon="apple" href="./ios-sdk-setup">
    Install the OneSignal SDK, initialize it in your app, and send a test notification.
  </Card>

  <Card title="Mobile SDK setup" icon="mobile" href="./mobile-sdk-setup">
    Choose your platform and follow the full SDK integration guide for Android, iOS, or cross-platform frameworks.
  </Card>
</Columns>

***

## FAQ

### What's the difference between .p8 and .p12?

A **.p8 key** is a token-based authentication key that does not expire and works across all apps under your Apple Developer account. A **.p12 certificate** is app-specific and expires after one year, requiring annual renewal. OneSignal recommends .p8 for its simplicity and lower maintenance. See the [.p12 certificate guide](./ios-p12-generate-certificates) for the alternative method.

### Does my .p8 key expire?

No. Unlike .p12 certificates, .p8 keys do not expire. Once created, a .p8 key remains valid until you revoke it in your Apple Developer account.

### Can I use one .p8 key for multiple apps?

Yes. A single .p8 key works for all apps under the same Apple Developer account. You can upload the same .p8 file to multiple OneSignal apps — each app only needs its own unique Bundle ID.

### Do I need a provisioning profile, and how do I create one?

Yes, Apple requires different types of profiles for development, testing (Ad Hoc), and distribution to the App Store.

In Xcode, select **Automatically manage signing** to create one automatically.

<Frame>
  <img alt="Xcode Signing and Capabilities tab with Automatically manage signing enabled" />
</Frame>

Otherwise, see [Apple's docs on provisioning profiles](https://developer.apple.com/help/account/provisioning-profiles/provisioning-profile-updates) for details.

***


# ISO 27001
Source: https://documentation.onesignal.com/docs/en/iso27001

Details on ISO 27001

## What is ISO 27001?

ISO/IEC 27001 is the world's best-known standard for information security management systems (ISMS). It defines requirements an ISMS must meet.

The ISO/IEC 27001 standard provides companies of any size and from all sectors of activity with guidance for establishing, implementing, maintaining and continually improving an information security management system.

Conformity with ISO/IEC 27001 means that an organization or business has put in place a system to manage risks related to the security of data owned or handled by the company, and that this system respects all the best practices and principles enshrined in this International Standard.

## OneSignal ISO27001 certification

OneSignal is ISO27001 certified. This certification underscores our commitment to maintaining the highest standards of information security management. A copy of the certificate can be shared on request.

***


# Journey actions
Source: https://documentation.onesignal.com/docs/en/journeys-actions

Define wait periods, branch journeys based on user behavior, and tag users using journey steps.

Use **Journey actions** to control how and when users move through your Journey, personalize experiences, and test outcomes.

## Wait

Delay the user's Journey progression by a specific amount of time—minutes, hours, days, or weeks.

Use it to:

* Space out messages and steps
* Allow time for users to engage with a message before branching

<Frame>
  <img />
</Frame>

***

## Wait Until

Hold a user at this step until they meet specific conditions:

* Entering a segment
* Triggering a message event (e.g., specific message delivered, opened, or clicked)
  * **Only one message event per wait until step** is supported at this time.
* Triggering a custom event (e.g., onboarding complete, purchase made)

You can **add multiple conditions** and branch users based on the *first condition they meet*. If those conditions are not met in a certain amount of time, you can set an **expiration branch** to continue users through the Journey or exit them completely.

<Note>
  If a user already qualifies for a condition when they reach this step, they'll move down that branch straight away without waiting. Conditions are evaluated in order (top to bottom / A–Z).
</Note>

Using the Custom Events entry rule you can also add [Event Matching](#event-matching) to control which instance of the user to progress through the Journey if you enter them multiple times.

<Frame>
  <img />
</Frame>

When a custom event matches a condition, that event is stored on behalf of the user and may be [referenced in Liquid syntax](./custom-events#liquid-syntax-for-custom-events) when sending Journey messages.

### Event Matching

Using the Custom Events entry rule, you can have users enter a Journey multiple times. With the Wait Until step's **Event Matching** setting, you can control which instance of the user to progress through the Journey.

Requirements:

* Set the Journey Entry Rules to use a custom event.
* Include an event property when entering users into the Journey.

For example, you have a "Survey Reminder" Journey. You have multiple surveys which means users can enter the Journey multiple times (once for each survey). You want to send a reminder message if they did not complete the survey or remove them if they did.

You can use the **Event Matching** setting to control which instance of the user to progress through the Journey.

**Example**:

<Steps>
  <Step title="Set the Journey Entry Rules and custom event properties">
    Set the Journey Entry Rules to use a custom event. **Example**: `survey_start`

    <Frame>
      <img />
    </Frame>

    Users will enter the Journey via the [Custom Event API](/reference/create-custom-events).

    The custom event will have the `name` set to `survey_start` and a `payload` property `survey_id` with a value of the survey they are taking (e.g., `survey_1`).

    ```json Entrance Trigger Event Example theme={null}
    {
      "events": [
        {
          "external_id": "UserA",
          "name": "survey_start",
          "properties": {
              "survey_id": "survey_1"
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="Create a Wait Until step and custom event properties">
    Set the Wait Until condition to use a custom event. **Example**: `survey_complete`

    Set the **Event Matching** option to specify which instance of the user to progress through the Wait Until step by matching the:

    * **Trigger Event Property**: set in the Journey entrance trigger event (e.g., `survey_id`)
    * **Wait Event Property**: set in the Wait Until event (e.g., `survey_type`)

    ```json Wait Until Event Example theme={null}
    {
      "events": [
        {
          "external_id": "UserA",
          "name": "survey_complete",
          "properties": {
              "survey_type": "survey_1"
          }
        }
      ]
    }
    ```

    When the value of `survey_id` matches the value of `survey_type`, that instance of the user will progress through the Journey.

    <Warning>
      You can use the same properties (e.g., `survey_id`) in both the **Trigger Event Property** and the **Wait Event Property**. The example uses different properties (e.g., `survey_id` and `survey_type`) to demonstrate the concept.

      Properties are case-sensitive! `survey_1` does not equal `Survey_1`.
    </Warning>

    **Expiration branch**:

    If the Wait Until event does not occur within the expiration time, the user will progress through the Journey. This example gives the user 1 week to complete the survey.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Add a message step">
    To complete the example, add a message step within the Expiration branch to send the reminder.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Test it out!">
    After following the steps above, you can test it:

    * Replace the `external_id` in the [Custom Event API](/reference/create-custom-events) with your external ID
    * Trigger the `survey_start` event with a `survey_id` of `survey_1`
      * You will see your user enter the Journey and flow into the Wait Until step

    <Warning>
      Events are not immediate but very quick! You may need to wait a few minutes before the event is processed.

      Check the Custom Events list to see if the event was processed.
    </Warning>

    * Trigger another `survey_start` event with a `survey_id` of `survey_2`
      * You will see 2 users enter the Journey and Wait Until step
    * Trigger the `survey_complete` event with a `survey_type` of `survey_1`
      * You will see your user progress through the Journey
    * Trigger another `survey_complete` event with a `survey_type` of `survey_2`
      * You will see both instances of your user progress through the Journey and exit

    <Check>
      You completed the Journey custom event example with Event Matching!
    </Check>
  </Step>
</Steps>

***

## Time Window

Restrict when users can move to the next step in the Journey based on **specific days and times**.

**Example**: Only allow users to receive a message on weekends in the evening.

<Frame>
  <img />
</Frame>

### How time window behavior works

When a user enters this node, OneSignal checks whether the current time falls inside the allowed window:

* If the window is **currently open**, the user continues immediately with no delay.
* If the window is in the **future** (or has already closed for the day), OneSignal delays the user until the next available window. To prevent traffic spikes at the moment a window opens, each user's release time is randomized between the **window start** and **window start + 15 minutes**.

The time window can use the **user's time zone** when time zone data is available. If a user does not have time zone data, the app's default time zone is used.

**Example**:
If your time window is Tuesdays from 1:00 PM to 6:00 PM and a user hits the node on Monday, they continue Tuesday at a random time between 1:00 PM and 1:15 PM. If the user instead hits the node on Tuesday at 3:00 PM, they continue immediately.

### Using time windows for recurring sends

Combine a time window node with [re-entry rules](./journeys-settings#re-entry-rules) to send recurring messages on a schedule (daily, weekly, etc.). Place the time window as the **first step** in the Journey so users wait for the right day and time before receiving the message.

When choosing a re-entry duration, set it **longer than the time window duration** but shorter than the send interval. This prevents double-sends within the same window while ensuring users re-enter early enough to catch the next window.

**Example — daily send:**

* Time window: every day, 10 AM – 6 PM (8-hour window)
* Re-entry: 12 hours (longer than the 8-hour window, shorter than 24 hours)
* Result: users re-enter \~12 hours after exiting, always arrive before the next day's window closes, and receive one message per day

See [Recurring journeys for specific days](./journeys-examples#recurring-journeys-for-specific-days) and [Can I schedule a message to send every day?](./journeys-examples#can-i-schedule-a-message-to-send-every-day) for full examples.

***

## Yes/No branch

Branch users based on **segment membership** or **message behavior**.

### Segment membership

Create branches based on what segment a user is in.

**Example**:
If users are tagged by plan type:

* “Free” branch = promote upgrade
* “Paid” branch = highlight premium features

### Message behavior

Branch based on interaction with previous messages in the Journey:

* **Push**: Clicked, Delivered
* **Email**: Clicked, Opened, Delivered

**Note**: Safari does not support [confirmed receipts](./confirmed-delivery).

***

## Split Branch

Randomly distribute users across different paths to test messaging, channels, or Journey flows.

<Frame>
  <img />
</Frame>

<Warning>
  Once a Journey is live, you **cannot edit** a Split Branch. To change the number of branches, create a new Journey.
</Warning>

### How it works

* Up to 20 branches
* Set equal or custom percentage splits
* Percentages round to whole numbers (e.g., 3-way split becomes 34/33/33)
* Distribution may vary slightly with small sample sizes

<Frame>
  <img />
</Frame>

By default, users are re-randomized each time they re-enter a Journey.
To keep them on the same branch, turn off **Randomize on re-entry**.

Use the **Tag User** action to track which branch a user followed.

### A/B/N Tests

Use nested Split Branches to test more than two variants simultaneously.

**Example**:
To split users equally across 3 variants:

1. First branch: 33% vs 67%
2. Under the 67% branch, add another 50/50 Split Branch

This gives \~33% on each path.

### Control Groups

Test the impact of messaging by leaving one branch empty (no message nodes). This lets you compare against users who receive no message at all.

### Choosing a Winner

Once a winning variant is identified, update the branch to send **100%** of traffic down that path (and 0% down the losing branch).

To continue measuring impact over time, consider keeping a small **holdout group**—a percentage of users who don't receive the winning message.

***

## Tag User

Use this action to apply or remove tags during a Journey.

**Common use cases**:

* Track Journey progress (e.g., `journeyStep: welcome`)
* Power in-app messages by tagging users at key moments
* Exclude users from other Journeys using active tags

<Frame>
  <img />
</Frame>

### Example: onboarding flow control

1. First step: Add a tag (e.g., `onboardingJourney: active`)
2. Use this tag to create a segment for exclusion from other Journeys
3. Last step: Remove the tag by setting the value to blank

<Frame>
  <img />
</Frame>

***

### Best practice: Using tags with webhooks or personalization

When you add or remove tags in a Journey, it can take a short time before those changes are ready to use in the next step. To make sure everything works smoothly:

* **For Webhooks**: Add a short wait after setting a tag before sending data with a webhook.
* **For Personalization**: Add a short wait after setting or removing a tag before using it in an email to personalize content.

<Tip>
  We recommend adding a **15-minute Wait node** between the Tag action and the next step. This ensures the tag is fully ready, so your webhook or email always includes the correct data.
</Tip>

***

## FAQ

### Can I branch a Journey based on which push action button was clicked?

Not with the built-in Yes/No branch alone — the message behavior conditions only detect "Clicked" or "Delivered," not which specific button was clicked. To branch by button, listen for the click event in your SDK, read the Action ID, and send a [Custom Event](./custom-events). Then use a [Wait Until](#wait-until) step to branch based on which custom event fires first.

See [Branch a Journey by action button clicked](./journeys-examples#branch-a-journey-by-action-button-clicked) for a full walkthrough with code examples.

### Do I need to write code to use Custom Events in a Journey?

Yes. Custom Events are sent to OneSignal from your app or website using the [SDK](./mobile-sdk-reference#custom-events), or from your backend using the [REST API](/reference/create-custom-events). There is no dashboard-only way to fire Custom Events. Once events are flowing into OneSignal, you can use them in Journeys and Segments through the dashboard without additional code.

***


# Journey analytics
Source: https://documentation.onesignal.com/docs/en/journeys-analytics

Track Journey performance with delivery metrics, user activity, and conversion insights across push, email, SMS, and in-app channels.

For each Journey, you can view a report of its aggregated statistics over time or drill down into detailed reports for each message within the Journey. Both Journey-level and individual message reports can be exported via CSV.

<Warning>
  These analytics are available for Journeys set live after December 13, 2023. If you do not see message reports for an existing Journey, duplicate and re-launch it to enable detailed insights.
</Warning>

**Users vs. Subscriptions:** Journey-level metrics are based on **Users**, while message-level metrics are based on **Subscriptions** (devices, email addresses, phone numbers). A single user may have multiple subscriptions across channels.

## Journey report

To view a report of the entire Journey, open the Journey and click **Journey Report** at the top. This report shows how your Journey performs over time and provides a high-level view of trends and success metrics. Metrics are based on the number of users moving through the Journey.

<Frame>
  <img alt="Journey report with started, in-progress, early exit, and completed metrics" />
</Frame>

### Journey stats

High-level stats for the entire Journey. Graph data and Audience Activity are only available for 30 days.

| Metric          | Description                                                                                                                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Started**     | Total number of Users that started this Journey. Includes re-entries; a User who re-enters the Journey will increment this count again.                                                     |
| **In Progress** | Users currently in the Journey.                                                                                                                                                             |
| **Early Exit**  | Users who exited due to an [exit rule](./journeys-settings#exit-rules). Calculated as `(early exits / total started) * 100`. Useful for tracking conversions such as upgrade segment entry. |
| **Completed**   | Users who completed all Journey steps. Calculated as `(completed exits / total started) * 100`.                                                                                             |

## Journey step stats

Each step in the Journey shows high-level stats for its lifetime.

<Frame>
  <img alt="Wait node showing waiting, completed, and exited early counts" />
</Frame>

| Metric           | Description                                                                                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Waiting**      | Users currently waiting in this step. For message steps, this is usually 0 as messages are sent immediately.                                                                                                              |
| **Completed**    | Users who completed this step and moved forward. For the last **Exit** step, this shows total completions of the entire Journey.                                                                                          |
| **Exited Early** | Users who exited due to an [exit rule](./journeys-settings#exit-rules). For the last **Exit** step, this represents all early exits across the Journey. Helps track conversions tied to exit criteria like segment entry. |

### Push stats

Click a push message step to see detailed [message reports](#journey-message-reports).

| Metric           | Description                                                                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sent**         | Messages attempted to be sent to subscribed devices. May be limited by [frequency capping](./frequency-capping), unsubscribed users, or missing push permissions. |
| **Delivered**    | Messages successfully sent to the push provider (APNs or FCM).                                                                                                    |
| **Confirmed**    | Messages confirmed as received by the user’s device.                                                                                                              |
| **Clicked**      | Total user clicks on the message.                                                                                                                                 |
| **CTR**          | Click-Through Rate = `(Unique Clicks / Deliveries) * 100`.                                                                                                        |
| **Failed**       | Messages that failed to send.                                                                                                                                     |
| **Unsubscribed** | Devices that unsubscribed from push after receiving the message.                                                                                                  |
| **Capped**       | Messages not sent due to [frequency capping](./frequency-capping).                                                                                                |

### In-app message stats

Click an in-app message step to see detailed [message reports](#journey-message-reports).

| Metric          | Description                                              |
| --------------- | -------------------------------------------------------- |
| **Impressions** | Number of times the in-app card was displayed.           |
| **Clicked**     | Number of times an interactive block was clicked.        |
| **CTR**         | Click-Through Rate = `(Unique Clicks / Displays) * 100`. |

### Email stats

Click an email message step to see detailed [message reports](#journey-message-reports).

| Metric           | Description                                                                                                                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Sent**         | Emails attempted to be sent. May be blocked by unsubscribed users or list errors. For diagnostics, check the [Delivery page](./email-deliverability).                                                        |
| **Delivered**    | Emails confirmed as successfully delivered to inboxes.                                                                                                                                                       |
| **Opens**        | Unique opens. May be affected by privacy protections. See [Why are Open events low?](./email-message-reports#why-are-open-events-low).                                                                       |
| **Clicks**       | Total number of link clicks (not unique).                                                                                                                                                                    |
| **CTR**          | Click-Through Rate = `(Unique Clicks / Deliveries) * 100`.                                                                                                                                                   |
| **CTOR**         | Click-to-Open Rate = `(Unique Clicks / Unique Opens) * 100`.                                                                                                                                                 |
| **Bounced**      | Messages that failed due to invalid addresses, domain issues, or spam reputation. Bounced addresses are added to the [suppression list](./suppressions). See [Email deliverability](./email-deliverability). |
| **Failed**       | Emails that OneSignal could not deliver and dropped. See [Why are emails marked as failed?](./email-message-reports#why-are-my-emails-marked-as-failed).                                                     |
| **Spam**         | Recipients who marked your email as spam. These addresses are added to the [suppression list](./suppressions).                                                                                               |
| **Suppressed**   | Emails not sent because the address was already on the [suppression list](./suppressions) from a prior bounce or spam report. Available only when using [OneSignal Email](./email-setup) as your ESP.        |
| **Unsubscribed** | Users who opted out via the unsubscribe link. Their subscription status is updated immediately.                                                                                                              |

### SMS stats

Click an SMS message step to see detailed [message reports](#journey-message-reports).

| Metric        | Description                                              |
| ------------- | -------------------------------------------------------- |
| **Sent**      | Messages OneSignal attempted to send to SMS subscribers. |
| **Delivered** | Messages successfully delivered.                         |
| **Failed**    | Messages that failed to send.                            |

***

## Journey message reports

Within the Journey editor, click a message step to open its delivery report. These message-level reports are based on the number of [Subscriptions](./subscriptions) that were sent the message. For example, if 1 user entered the Journey and had 2 subscribed Subscriptions for the message channel (push, email, etc.), then 2 messages will be sent (one for each Subscription).

Top-level stats are for the lifetime of the message. For details on each metric, see:

* [Push message reports](./push-notification-message-reports)
* [In-app message reports](./in-app-message-reports)
* [Email message reports](./email-message-reports)
* [SMS message reports](./sms-message-reports)

Graph data and Audience Activity are only available for 30 days. This data is also available in [Template Analytics](./template-analytics).

<Frame>
  <img alt="Push notification delivery report showing sent, delivered, clicked, and failed metrics" />
</Frame>

### Audience activity

The **Audience Activity** section shows the users who were sent a message. You can export the full list of users for a given message step by clicking **Export**. This data is available for 30 days.

<Note>
  Each user appears only once per tab. If a user re-enters and receives the same message multiple times, they will only appear once in the export for that step.
</Note>

<Frame>
  <img alt="Audience activity table showing per-user delivery status and timestamps" />
</Frame>

***

## Conversion metrics

<Info>
  **Coming soon** — [Conversion metrics](./conversion-metrics) will be available on Journey reports. Once available, you will see attributed and influenced conversions at both the Journey level and the individual message level.
</Info>

***

## FAQ

### How long is Journey analytics data retained?

Journey-level stats (Started, In Progress, Early Exit, Completed) and per-step stats are available for the lifetime of the Journey. Graph data and Audience Activity exports are retained for **30 days**. To keep historical data, export it before the 30-day window closes.

### What does a high early exit rate mean?

It depends on your [exit rules](./journeys-settings#exit-rules). If the exit rule is based on goal completion (for example, "user entered the Paid Customers segment"), a high early exit rate indicates successful conversions. If the exit rule is not goal-based, a high rate may mean users are dropping off before completing the Journey — review your audience targeting and message content.

### How can I improve a low CTR?

A low click-through rate usually means the message content or timing is not resonating. Try A/B testing different copy or templates using a [split branch](./journeys-actions#split-branch), personalizing messages with [tags or Liquid syntax](./message-personalization), or adjusting message timing with [wait steps](./journeys-actions#wait). Compare CTR across channels to identify which performs best.

### What do high bounce or failure rates mean?

High bounce rates usually indicate invalid email addresses, full inboxes, or domain issues. High failure rates mean OneSignal could not deliver the message at all. Review the Audience Activity export for specific failure reasons, and see [Email deliverability](./email-deliverability) and [Suppressions](./suppressions) for next steps.

### Why do Journey-level and message-level numbers not match?

Journey-level metrics count **users**, while message-level metrics count **subscriptions**. A single user with two email addresses subscribed to your app would count as 1 user at the Journey level but could generate 2 email sends at the message level.

***

## Related pages

<Columns>
  <Card title="Journeys overview" icon="route" href="./journeys-overview">
    Introduction to Journeys and how multichannel workflows operate.
  </Card>

  <Card title="Journey settings" icon="gear" href="./journeys-settings">
    Configure entry rules, exit rules, re-entry, and scheduling.
  </Card>

  <Card title="Email message reports" icon="envelope" href="./email-message-reports">
    Detailed delivery, open, click, and error metrics for individual email sends.
  </Card>

  <Card title="Push message reports" icon="bell" href="./push-notification-message-reports">
    Delivery and engagement metrics for individual push notification sends.
  </Card>

  <Card title="Template analytics" icon="chart-bar" href="./template-analytics">
    Aggregate performance metrics across all sends of a template.
  </Card>

  <Card title="Exporting data" icon="file-export" href="./exporting-data">
    Export Journey data, Audience Activity, and message reports via dashboard or API.
  </Card>
</Columns>


# Journey examples
Source: https://documentation.onesignal.com/docs/en/journeys-examples

Step-by-step Journey configurations for onboarding, re-engagement, abandoned cart, A/B testing, recurring sends, and event-driven workflows.

Each example below includes the recommended Journey settings and step-by-step configuration. Start with the simpler patterns (onboarding, re-engagement) and work up to more advanced workflows (recurring sends, event-driven progression, action button branching).

<Frame>
  <iframe title="Journey examples walkthrough" />
</Frame>

***

## Onboarding

Use this pattern to send a welcome or onboarding sequence to new subscribers. It is also commonly referred to as a welcome campaign, welcome series, or new user campaign. The goal is to guide users toward completing a key action (finishing their profile, making their first purchase, or discovering a core feature) rather than messaging them the moment they sign up.

| Journey setting    | Description                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entry rules**    | **Event-based (recommended):** Use a [Custom Event](./custom-events) trigger (for example, `signup_completed`) so the sequence starts at a meaningful moment: when the user finishes registration.<br /><br />**Segment-based fallback:** "User matches the segment criteria" using the "Subscribed Users" [segment](./segmentation), future additions only. Use this if you don't have a signup event set up. |
| **Exit rules**     | They moved through the entire journey, or when the user completes the key action (for example, they exit a "has not completed onboarding" segment).                                                                                                                                                                                                                                                            |
| **Re-entry rules** | No                                                                                                                                                                                                                                                                                                                                                                                                             |
| **Content**        | A short sequence over the user's first week: a welcome email on day 0, a push nudge on day 2 if they haven't acted, and a follow-up email on day 7 as a last touch.                                                                                                                                                                                                                                            |

**Journey steps**

<Steps>
  <Step title="Immediately: Send a welcome email">
    The user just signed up and is likely still in your app. An email is the right first touch: it's expected, non-intrusive, and can include more detail than a push notification. Save push for when they've left.
  </Step>

  <Step title="Wait 1 day">
    Give the user time to explore on their own before following up.
  </Step>

  <Step title="Day 2: Branch on key action completed?">
    Add a yes/no branch based on whether the user has completed your onboarding goal. Track this with a [tag](./add-user-data-tags) (for example, `onboarding_complete = true`) or segment membership.

    * **Yes branch:** Exit the journey. The user doesn't need a nudge.
    * **No branch:** Send a push notification with a specific, actionable prompt. For example: "Finish setting up your profile" or "Make your first \[action]."
  </Step>

  <Step title="Wait 5 days">
    Allow time for the push to land before sending a final message.
  </Step>

  <Step title="Day 7: Branch on key action completed?">
    * **Yes branch:** Exit the journey.
    * **No branch:** Send a follow-up email as a last touch. Avoid messaging further. Users who haven't engaged after a week are better candidates for a [re-engagement campaign](#re-engagement-campaign).
  </Step>
</Steps>

<Frame>
  <img alt="Onboarding welcome journey flow with push and email steps" />
</Frame>

***

## Re-engagement campaign

Use this pattern to win back users who haven't opened your app or visited your site recently. The journey sends a series of increasingly compelling messages and exits the user as soon as they return.

| Journey setting    | Description                                                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entry rules**    | **User's last session is greater than 7 days;** subscribed users. Consider excluding segments like paid customers if the goal is to re-engage free users. |
| **Exit rules**     | **They moved through the entire journey or meet certain conditions** — exit when the user becomes active in your app or website.                          |
| **Re-entry rules** | **Yes, after a certain amount of time: 7 days.** Users re-enter whenever they go inactive again.                                                          |
| **Content**        | Remind users to come back to your app when they haven't opened it in a while, and entice them with rewards or discounts.                                  |

**Journey steps**

<Steps>
  <Step title="Send a push notification">
    Start with a push — it's the most visible channel for re-engaging lapsed users. Use a clear, action-oriented message like "We miss you! Here's what's new."
  </Step>

  <Step title="Wait 2 days">
    Give the user time to respond to the push before escalating.
  </Step>

  <Step title="Branch on user activity">
    Add a yes/no branch to check if the user has returned (for example, last session within 2 days).

    * **Yes branch:** Exit the journey. The user is re-engaged.
    * **No branch:** Send an email with a stronger incentive (for example, a discount, new content, or feature highlight).
  </Step>

  <Step title="Wait 3 days">
    Allow time for the email to drive the user back.
  </Step>

  <Step title="Final check">
    * **Active:** Exit the journey.
    * **Still inactive:** Optionally send a final SMS or exit. Avoid further messaging — users who haven't responded after multiple touches are unlikely to convert from more messages.
  </Step>
</Steps>

<Frame>
  <img alt="Re-engagement journey flow with wait steps and exit conditions" />
</Frame>

***

## Abandoned cart

<Card title="Abandoned cart example" href="./abandoned-cart" icon="money-bill">
  Use Custom Events or Tags to track cart activity and send abandoned cart messages.
</Card>

***

## Promotional campaign

Use this pattern for time-limited promotions, sales events, or product launches. The journey builds anticipation, reminds users during the event, and creates urgency as it ends.

| Journey setting    | Description                                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Entry rules**    | **User matches the segment criteria.** Subscribed users, or a segment relevant to the promotion.                                                 |
| **Exit rules**     | **They moved through the entire journey or meet certain conditions.** Select a segment that defines the goal (for example, users who purchased). |
| **Re-entry rules** | **No** — for one-off campaigns, send once.                                                                                                       |
| **Content**        | Prepare them for the event, remind them when it starts, and offer a discount or reward as it gets close to ending.                               |

**Journey steps**

<Steps>
  <Step title="Announcement: Send a teaser message">
    Send an email or push announcing the upcoming promotion. Include the date, what to expect, and a reason to pay attention.
  </Step>

  <Step title="Wait until event start">
    Add a wait step timed to the start of your promotion.
  </Step>

  <Step title="Event start: Send the main offer">
    Send a push notification or email with the promotion details, discount code, or call to action.
  </Step>

  <Step title="Wait 2–3 days (mid-event)">
    Give users time to act on the initial message.
  </Step>

  <Step title="Reminder: Last chance message">
    Send a final push or email with urgency — "Sale ends tomorrow" or "Last chance for 20% off." Users who already converted will have exited via the exit rule.
  </Step>
</Steps>

<Frame>
  <img alt="Promotional campaign journey flow with timed messages" />
</Frame>

***

## Send a message after a user leaves without completing an action

**Initial setup**

1. Use [Tags](./add-user-data-tags) to mark that the action needs to be performed by the user. Remove the tag when the action is completed.
2. Set up the [segment](./segmentation) for this tag.

| Journey setting    | Option                                                        | Description                                                                               |
| ------------------ | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Entry rules**    | The user's last session is greater than the amount of time.   | The threshold for how long the user has been inactive in your app or website.             |
| **Audience**       | Include the segment you want to target with the tag.          | These are the users eligible to receive the message.                                      |
| **Exit rules**     | Exit when the user no longer matches the audience conditions. | When the user leaves the segment, they are no longer eligible for the journey message.    |
| **Re-entry rules** | Yes, after a certain amount of time.                          | The amount of time you want to wait for the user to be eligible to get the message again. |

**Journey steps**

<Steps>
  <Step title="Add the desired message(s)">
    Choose a template for the message step. You can use push, email, SMS, or in-app depending on the action you want the user to take.
  </Step>

  <Step title="Set a wait node for the amount of time you want the user to wait">
    This can be a short or long interval depending on whether the message should repeat as a reminder. In this example, the wait is set to 104 weeks (2 years) so the message effectively sends only once — the long wait prevents the user from looping back through the journey while re-entry rules handle the next trigger.
  </Step>
</Steps>

***

## A/B test within a Journey

Using a **split branch** node, you can set a 50/50 split within your journey. Create two different message templates and as your users flow through, half will get "Template A" and the other "Template B".

Export the message data from each template to compare [analytics](./analytics-overview) between variants.

<Frame>
  <img alt="A/B test journey with a 50/50 split branch and two message templates" />
</Frame>

***

## Display in-app messages in order and once per day

This example displays 3 or more in-app messages in sequence, showing one per day. If a user does not open the app, the next message appears the next time they open it.

**Initial setup**

<Steps>
  <Step title="Create a new segment">
    Create a segment called `iam_journey` with filter: User Tag `iam_journey` is `1`

    1. You can change `iam_journey` to whatever name you choose.
    2. This tag will be set on each user that finishes the journey and gets all messages.

    <Frame>
      <img alt="Segment creation screen with iam_journey tag filter" />
    </Frame>
  </Step>

  <Step title="Create the in-app messages">
    See [design in-app messages with drag and drop](./design-your-in-app-message) for more.
  </Step>

  <Step title="Set up the following journey">
    | Journey setting    | Option                                | Description                                                                              |
    | ------------------ | ------------------------------------- | ---------------------------------------------------------------------------------------- |
    | **Entry rules**    | User matches the segment criteria     | These are the users eligible to receive the message.                                     |
    | **Audience**       | Include segment & exclude segment     | Include the "Subscribed Users" segment. Exclude the "`iam_journey`" segment from step 1. |
    | **Exit rules**     | They moved through the entire journey | No additional conditions necessary.                                                      |
    | **Re-entry rules** | Yes, after a certain amount of time   | 2 minutes                                                                                |

    **Journey steps**

    Repeat this order for the number of messages you want to display. This example uses 3 in-app messages (IAM 1, IAM 2, IAM 3).

    1. **Add an in-app message step.**
       1. Name the message, for example: `IAM 1`.
       2. At the bottom of the message, set **delivery schedule** to **1 day**.

    2. **Add a yes/no branch action before the in-app message step.**
       1. Set your branching condition: previous message behavior: "`IAM 1` viewed".
       2. **Follow the No branch**
          1. Drag the `IAM 1` to the No branch.
          2. Add a wait step for 1 day.
       3. **Follow the Yes branch**
          1. Within the Yes branch, repeat steps 1 and 2 for all messages, replacing `IAM 1` with the next in-app message (`IAM 2`, `IAM 3`).
          2. At the final Yes branch, add **tag user** action.
             1. Tag the same key used in Initial setup → Step 1 segment.
                1. Example `iam_journey : 1`.

    <Frame>
      <img alt="Complete in-app message journey with branching and daily delivery" />
    </Frame>
  </Step>
</Steps>

***

## Limited entry journey

Ensure users can only enter a journey a limited number of times while controlling the experience at each stage.

| Journey setting    | Description                                                                                                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entry rules**    | User matches the segment criteria (for example, subscribed users or any relevant target segment).                                                   |
| **Audience**       | Include your target segment. Exclude users with the tag `journey_count = 2` to cap entries at two times.                                            |
| **Exit rules**     | They moved through the entire journey.                                                                                                              |
| **Re-entry rules** | Yes, after a certain amount of time: 15 days.                                                                                                       |
| **Content**        | Provide a first-time experience on initial entry, and a tailored second-time experience on re-entry. Prevent any further entries beyond the second. |

<Frame>
  <img alt="Limited entry journey settings with audience exclusion and re-entry rules" />
</Frame>

**Initial setup**

<Steps>
  <Step title="Prepare your tag strategy">
    Use a user tag named `journey_count` to track entries. Tags are created automatically when you set them in the Journey. See [tag action](./journeys-actions#tag-user) for details.
  </Step>

  <Step title="Configure audience include/exclude">
    In journey audience:

    * Include your target segment (for example, “Subscribed Users”).
    * Exclude users where user tag `journey_count` is `2`.
  </Step>

  <Step title="Set re-entry rules">
    Set re-entry rules to “Yes, after a certain amount of time: 15 days.”\
    This allows exactly one re-entry between the first and second runs.
  </Step>
</Steps>

**Journey steps**

<Frame>
  <img alt="Limited entry journey flow with yes/no branch based on journey_count tag" />
</Frame>

<Steps>
  <Step title="Add a yes/no branch at the start">
    Condition: user tag `journey_count` equals `1`.

    * **Yes branch** = returning users (second entry).
    * **No branch** = first-time users (no tag present yet).
  </Step>

  <Step title="No branch (first time entry)">
    * Add tag user action: set `journey_count` to `1`.
    * Send your first-time messages and actions.
    * Continue to end or additional logic as needed.
  </Step>

  <Step title="Yes branch (second time entry)">
    * Add tag user action: set `journey_count` to `2`.
    * Send your returning-user messages and actions.
    * Continue to end or additional logic as needed.
  </Step>

  <Step title="Enforce the limit">
    Because the audience excludes users with `journey_count = 2`, any attempted third entry is blocked automatically.
  </Step>
</Steps>

***

## Recurring journeys for specific days

Send recurring messages that align with a specific day of the week, like weekly promotions or event reminders.

| Journey setting    | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| **Entry rules**    | User matches the segment criteria (for example, subscribed users).   |
| **Audience**       | Include your target segment.                                         |
| **Exit rules**     | They moved through the entire journey.                               |
| **Re-entry rules** | Yes, after a certain amount of time: 7 days.                         |
| **Content**        | A weekly message sent on a specific day (for example, every Friday). |

<Frame>
  <img alt="Recurring journey settings with 7-day re-entry" />
</Frame>

**Initial setup**

<Steps>
  <Step title="Configure audience">
    Include your target segment so eligible users can enter the journey at any time during the week.
  </Step>

  <Step title="Set re-entry rules">
    Set re-entry rules to “Yes, after a certain amount of time: 7 days” to enable weekly recurrence.

    * The re-entry timer starts when the user **exits** the Journey, not when they entered.
    * A 7-day re-entry ensures users re-enter in time for the next week’s time window.
    * The re-entry duration must be **longer than the time window duration** to avoid double-sends.

    See [Using time windows for recurring sends](./journeys-actions#using-time-windows-for-recurring-sends) for details.
  </Step>
</Steps>

**Journey steps**

<Frame>
  <img alt="Recurring journey flow with time window node and message step" />
</Frame>

<Steps>
  <Step title="Add a time window node (first step)">
    Configure the time window to filter for your target day of week (for example, Friday).\
    Users entering the journey will wait until the next matching day.
  </Step>

  <Step title="Add your message after the time window">
    Place the message node immediately after the time window so it sends when the day is reached.
  </Step>

  <Step title="End the journey">
    Let users exit after the message sends. With re-entry at 7 days, they will rejoin and repeat weekly.
  </Step>
</Steps>

<Tip>
  Update the message content regularly to avoid sending the same copy each week.
</Tip>

***

## Progressive journeys (event-driven)

Escalate engagement based on user progression using [custom events](./custom-events) and [wait-until](./journeys-actions#wait-until) conditions.

| Journey setting    | Description                                                                                                                                                                                                                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entry rules**    | **Custom Event** = `Progression_Level`, with filter `progression_level = 0`.                                                                                                                                                                                                                                                    |
| **Audience**       | Optional segment filter. You can run this for all users or restrict to a subset; no tags required.                                                                                                                                                                                                                              |
| **Exit rules**     | - They moved through the entire journey.<br />- Or when maximum progression level is reached (`progression_level = 3`).<br />- Optionally: exit when a **Wait Until** node expires.<br />- Optionally: branch from a **Wait Until** node to tag users who do not complete the event, leading them into a re-engagement journey. |
| **Re-entry rules** | No                                                                                                                                                                                                                                                                                                                              |
| **Content**        | Stage-based messages that escalate as users complete milestones (emails in this example).                                                                                                                                                                                                                                       |

<Frame>
  <img alt="Progressive journey flow with wait-until nodes for each level milestone" />
</Frame>

**Journey steps**

<Steps>
  <Step title="User enters the journey">
    All eligible users enter based on entry rules.\
    Trigger: **Custom Event** `Progression_Level` with `progression_level = 0`.\
    Start: **Immediately**.
  </Step>

  <Step title="Level 1">
    * Wait until custom event `Progression_Level` occurs with `progression_level = 1`.
    * Send: **Level 1 Complete!** message.
    * (Optional) Apply expiration on the wait node → exit user if milestone not reached.
    * (Optional) Branch: if expiration hits, tag the user and send them into a re-engagement journey.
  </Step>

  <Step title="Level 2">
    * Wait until custom event `Progression_Level` occurs with `progression_level = 2`.
    * Send: **Level 2 Complete, you are doing great!** message.
    * (Optional) Apply expiration or branch/tag to re-engagement.
  </Step>

  <Step title="Level 3">
    * Wait until custom event `Progression_Level` occurs with `progression_level = 3`.
    * Send: **You’ve reached level 3!** message.
    * (Optional) Apply expiration or branch/tag to re-engagement.
  </Step>

  <Step title="Exit">
    End the journey once users complete Level 3, or when a Wait Until node expires.\
    Optionally, use branch/tag paths to route stalled users into a re-engagement track.\
    Schedule: **Start immediately**, **Never stops**.
  </Step>
</Steps>

<Tip>
  This method ensures progression happens only when real engagement signals occur. Adding expiration and branch/tag logic lets you handle stalled users gracefully — either exiting them or re-routing into a re-engagement Journey.
</Tip>

***

## Branch a Journey by action button clicked

Route users down different Journey paths based on which push notification action button they tapped. This pattern uses [action buttons](./action-buttons), a [custom event](./custom-events), and a [Wait Until](./journeys-actions#wait-until) step to branch users by their specific button click — not just whether they clicked or not.

<Info>
  This example requires website or app code to capture the button click and send a custom event. It cannot be done entirely through the OneSignal dashboard.
</Info>

| Journey setting    | Description                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Entry rules**    | User matches the segment criteria (for example, subscribed users or a campaign-specific segment).               |
| **Exit rules**     | They moved through the entire journey.                                                                          |
| **Re-entry rules** | No                                                                                                              |
| **Content**        | Send a push with multiple action buttons, then branch follow-up messages based on which button the user tapped. |

The built-in [Yes/No branch](./journeys-actions#yesno-branch) message behavior conditions detect whether a user **clicked** or **was delivered** a message — but not *which* button they clicked. To branch by specific button, you capture the Action ID from the click event and send it as a Custom Event property that the Journey can branch on.

<Steps>
  <Step title="Add action buttons to your push">
    When creating the push message in the Journey (or in a [template](./templates)), open **Advanced Options > Action Buttons** and assign a unique **Action ID** to each button.

    **Example**: A promotional push with two CTAs:

    * Button 1: "Shop Now" → Action ID: `shop_now`
    * Button 2: "Learn More" → Action ID: `learn_more`

    See [Action buttons](./action-buttons) for full setup details.
  </Step>

  <Step title="Add a click listener and send a Custom Event">
    On your website or in your app, listen for the notification click event and send a Custom Event that includes the Action ID as a property.

    <Note>
      The Web SDK example requires version `160500` or later. Users should be [logged in](./web-sdk-reference#login) for custom events to be tracked.
    </Note>

    <CodeGroup>
      ```javascript Web SDK theme={null}
      OneSignalDeferred.push(function(OneSignal) {
        OneSignal.Notifications.addEventListener("click", function(event) {
          var actionId = event.result.actionId;
          if (actionId) {
            OneSignal.User.trackEvent("cta_clicked", { button: actionId });
          }
        });
      });
      ```

      ```kotlin Android SDK theme={null}
      OneSignal.Notifications.addClickListener { event ->
          val actionId = event.result.actionId
          if (actionId != null) {
              OneSignal.User.trackEvent("cta_clicked", mapOf("button" to actionId))
          }
      }
      ```

      ```swift iOS SDK theme={null}
      let listener = { (event: OSNotificationClickEvent) in
          if let actionId = event.result.actionId {
              OneSignal.User.trackEvent("cta_clicked", properties: ["button": actionId])
          }
      }
      OneSignal.Notifications.addClickListener(listener)
      ```
    </CodeGroup>

    See [Custom events](./custom-events) for event requirements and limits.
  </Step>

  <Step title="Add a Wait Until step in the Journey">
    After the push message step in your Journey:

    1. Add a **Wait Until** step.
    2. Add a condition for each button: Custom Event `cta_clicked` where property `button` equals the Action ID (for example, `shop_now`).
    3. Add additional conditions for each Action ID you want to branch on (for example, `learn_more`).
    4. Set an **expiration** (for example, 3 days) so users who don't click any button continue down a fallback path.

    Users follow the branch for the **first condition they meet**. If no condition is met before the expiration, they follow the expiration branch.
  </Step>

  <Step title="Add follow-up messages to each branch">
    On each branch after the Wait Until step, add the appropriate follow-up message or action:

    * **"Shop Now" branch**: Send a product recommendation or discount code.
    * **"Learn More" branch**: Send educational content or a feature overview.
    * **Expiration branch**: Send a re-engagement message or exit the Journey.
  </Step>
</Steps>

<Tip>
  You can chain multiple Wait Until steps to branch on subsequent interactions too — there is no limit on the number of Wait Until steps in a Journey.
</Tip>

***

## FAQ

### Can I schedule a message to send every day?

Yes. Add a [time window](./journeys-actions#time-window) node as the first step and configure it for every day of the week with the hours you want the message to send (for example, 10 AM to 6 PM in the user's time zone). Then set **re-entry rules** to re-enter after a time shorter than one day but **longer than the time window duration** — for example, 12 hours for an 8-hour window. This ensures users re-enter early enough to catch the next day's time window without risking a double-send within the same window.

### Can I A/B test different messages in a Journey?

Yes. Add a [split branch](./journeys-actions#random-split) node to divide users evenly (for example, 50/50). Place a different message template on each branch, then compare analytics between the two templates after the Journey runs.

### How do I limit how many times a user can enter a Journey?

Use a tag (for example, `journey_count`) to track entries. Increment the tag each time the user enters, and add an audience exclusion rule that blocks users once the tag reaches your desired limit. See the [Limited entry journey](#limited-entry-journey) example above.

### Why did my recurring Journey send on the wrong day?

The [time window](./journeys-actions#time-window) node filters by the user's local time zone if time zone data is available. If a user does not have time zone data, the message sends based on your app's default time zone. Verify that your time window settings and user time zone data are correct.

### How do I stop a running Journey?

Set the Journey status to **Paused** or **Stopped** in the Journey settings. Paused Journeys retain users at their current step; stopped Journeys exit all users immediately. See [Journey settings](./journeys-settings) for details.

***

## Related pages

<Columns>
  <Card title="Journeys overview" icon="route" href="./journeys-overview">
    Introduction to Journeys and how they work.
  </Card>

  <Card title="Journey actions" icon="code-branch" href="./journeys-actions">
    Add wait steps, branching logic, time windows, and split paths.
  </Card>

  <Card title="Journey settings" icon="gear" href="./journeys-settings">
    Configure entry rules, exit rules, re-entry, and scheduling.
  </Card>

  <Card title="Journey messages" icon="envelope" href="./journeys-messages">
    Configure push, email, SMS, and in-app message steps in a Journey.
  </Card>

  <Card title="Abandoned cart" icon="cart-shopping" href="./abandoned-cart">
    Full walkthrough for building an abandoned cart Journey.
  </Card>

  <Card title="Custom events" icon="bolt" href="./custom-events">
    Trigger Journeys and pass event properties for personalization.
  </Card>

  <Card title="Journey analytics" icon="chart-bar" href="./journeys-analytics">
    Track Journey performance with delivery metrics, user activity, and conversion insights.
  </Card>
</Columns>

<AccordionGroup>
  <Accordion title="Additional resources on the OneSignal blog">
    * [Maximizing User Engagement: The Synergy of Push Notifications and Email](https://onesignal.com/blog/use-push-notifications-and-email-together/)
    * [Consistently Drive Value with Journeys](https://onesignal.com/blog/consistently-drive-value-with-journeys/)
    * [Increase Engagement with Email for Cross-Channel Journeys](https://onesignal.com/blog/increase-engagement-with-email-for-cross-channel-journeys/)
    * [Improve Retention with In-App and SMS for Journeys](https://onesignal.com/blog/improve-retention-with-in-app-and-sms-for-journeys/)
  </Accordion>
</AccordionGroup>


# Journey messages
Source: https://documentation.onesignal.com/docs/en/journeys-messages

Configure push notification, email, SMS, and in-app message steps in a Journey, including templates, delivery timing, and session requirements.

Each message step in a Journey sends a message to the user when they reach that point in the flow. You can add **push notification**, **email**, **SMS**, and **in-app message** steps — each with its own template and delivery behavior.

To add a message step, click the **(+)** button in the Journey canvas and select the channel.

<Note>
  Message scheduling within individual steps is not currently supported. Push, email, and SMS messages send immediately when the user reaches the step. Use a [Wait step](./journeys-actions#wait) before the message step if you need a delay.
</Note>

***

## Push notification

1. Click **(+)** and select **Push Notification**.
2. In the side panel, select an existing [message template](./templates) or create a new one.
3. Save the step.

When a user reaches this step, OneSignal sends the push notification immediately. The user must have an active push subscription to receive it.

<Tip>
  Give templates descriptive names (e.g., "Welcome — Day 1 Push") so they are easy to find in the dropdown.
</Tip>

***

## Email

Before adding an email step, confirm you have [email set up](./email-setup) in your OneSignal app.

1. Click **(+)** and select **Email**.
2. In the side panel, select an existing [email template](./templates) or create a new one.
3. Save the step.

OneSignal sends the email immediately when the user reaches this step. The user must have a subscribed email address.

You can personalize email content using [Liquid syntax](./using-liquid-syntax), [Data Tags](./add-user-data-tags), or [Data Feeds](./data-feeds) for real-time API data at send time.

***

## SMS

Before adding an SMS step, confirm you have [SMS messaging set up](./sms-messaging) in your OneSignal app.

1. Click **(+)** and select **SMS**.
2. In the side panel, select an existing [SMS template](./templates). If you haven't created one yet, go to **Messages > Templates > + New Template > New SMS Template**.
3. Save the step.

OneSignal sends the SMS immediately when the user reaches this step. The user must have a subscribed phone number.

***

## In-app message

Before adding an in-app message step, confirm you have [in-app messaging set up](./in-app-messages-setup) in your app.

1. Click **(+)** and select **In-App Message**.
2. In the side panel, design your message using the [drag-and-drop editor](./design-your-in-app-message) or [HTML editor](./design-your-in-app-message-with-html).
3. Optionally configure [trigger conditions](./iam-triggers) and a **delivery schedule** (the window of time the user has to open the app and see the message).
4. Save the step.

### Session timing

In-app messages require a **new session** to display. A new session begins when the app has been out of focus for 30+ seconds and is brought back into focus.

This means:

1. The user reaches the in-app message step in the Journey.
2. The message does **not** display during the current session.
3. The next time the user opens the app (starting a new session), the message displays if the trigger conditions are met and the delivery schedule has not expired.

<Warning>
  If the user is actively using the app when they reach the in-app message step, they will not see the message until they close and reopen the app (after 30+ seconds). Plan your Journey flow accordingly — consider placing a [Wait step](./journeys-actions#wait) before the in-app message to allow time for a natural session break.
</Warning>

<Info>
  In-app messages in a Journey display only once per user. Even if the user re-enters the Journey, the same in-app message will not display again.
</Info>

***

## Webhooks

In addition to message steps, you can add **webhook steps** to send real-time data to external systems (CRMs, analytics platforms, custom backends) at any point in the Journey. Webhooks are useful for syncing user state, triggering external workflows, or logging Journey progress outside of OneSignal.

<Card title="Journey webhooks" icon="webhook" href="./journeys-webhook">
  Configure webhook steps to send data to external tools during a Journey.
</Card>

***

## FAQ

### Can I schedule a message to send at a specific time?

Not within the message step itself. To delay delivery, add a [Wait step](./journeys-actions#wait) before the message step. You can also use the Journey's [schedule settings](./journeys-settings#schedule) to control when the entire Journey is active.

### Why didn't my in-app message display?

In-app messages require a new session to display. If the user was already in the app when they reached the step, the message queues until the next session (app out of focus for 30+ seconds, then reopened). Also check that trigger conditions are met and the delivery schedule has not expired.

### Will a user see the same in-app message if they re-enter the Journey?

No. In-app messages in a Journey display only once per user, regardless of re-entry. To show a message again, create a new in-app message step with different content.

### What happens if a user doesn't have a subscription for the message channel?

The message step is skipped for that user. For example, if an email step is reached but the user has no subscribed email address, the email is not sent and the user continues to the next step in the Journey.

### Can I personalize Journey messages?

Yes. Push, email, and SMS templates support [Liquid syntax](./using-liquid-syntax) for inserting user attributes, [Data Tags](./add-user-data-tags), and [Custom Event properties](./message-personalization#custom-events). Email templates also support [Data Feeds](./data-feeds) for real-time API data at send time.

## Related pages

<Columns>
  <Card title="Journey webhooks" icon="webhook" href="./journeys-webhook">
    Send real-time data to external systems at any point in a Journey.
  </Card>

  <Card title="Journey actions" icon="code-branch" href="./journeys-actions">
    Add wait steps, branching logic, and split paths between message steps.
  </Card>

  <Card title="Journey settings" icon="gear" href="./journeys-settings">
    Configure entry rules, exit rules, re-entry, and scheduling.
  </Card>

  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Personalize messages with tags, Liquid syntax, and custom event properties.
  </Card>

  <Card title="Templates" icon="copy" href="./templates">
    Create and manage reusable message templates across channels.
  </Card>

  <Card title="Data Feeds" icon="database" href="./data-feeds">
    Pull real-time API data into email messages at send time.
  </Card>
</Columns>


# Journey webhooks
Source: https://documentation.onesignal.com/docs/en/journeys-webhook

Send HTTP requests from Journey steps to external servers, personalized with user data via Liquid syntax, with retry logic and debugging tools.

Journey webhooks send HTTP requests from a Journey step to your servers or any publicly accessible endpoint. You configure the HTTP method, URL, headers, and body content. Requests can be personalized with user-specific data using [Liquid syntax](./using-liquid-syntax), so you can sync Journey events with CRMs, analytics platforms, or custom backends in real time.

## Requirements

* [Contact the OneSignal sales team](https://onesignal.com/contact) for access.
* The URL or IP address must be valid and reachable over HTTP or HTTPS.
* Endpoints must be **publicly routable** — not behind a firewall or on localhost.
* Domains must have a valid top-level domain (`.com`, `.org`, `.net`, etc.).

<Warning>
  Journey webhooks cannot call OneSignal APIs. They are designed for sending data to external systems only.
</Warning>

***

## Setup

Once your Journey is created, follow these steps:

1. Navigate to **Data > Webhooks** in the OneSignal dashboard.
2. Click to create a new webhook.
3. Define the following:
   * **HTTP method** (usually `POST`)
   * **Target URL**
   * **Custom headers** (for example, authentication tokens)
   * **Body content** (plain text or JSON, optionally using Liquid)

<Frame>
  <img alt="Webhook setup form with HTTP method, URL, headers, and body fields" />
</Frame>

### Disallowed headers

You cannot set the following headers:

* `content-length`
* `referer`
* `metadata-flavor`
* `x-google-metadata-request`
* `host`
* Any header starting with `x-onesignal`

### Testing webhooks

You can also test your endpoint manually using a tool like curl:

```bash theme={null}
curl -X POST https://yourserver.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "abc123" }'
```

This validates that your endpoint is reachable and functioning before you add it to a Journey.

***

## Personalization

All webhook fields support [Liquid syntax](./using-liquid-syntax), allowing you to dynamically insert user and subscription data into the request.

See [Message personalization](./message-personalization) for the full list of available properties.

### User data reference

The following properties from the `user` object are available in webhook fields via Liquid syntax:

| Property     | Type   | Usage                               | Available in Test? |
| ------------ | ------ | ----------------------------------- | ------------------ |
| OneSignal ID | String | `{{ user.onesignal_id }}`           | ✅                  |
| External ID  | String | `{{ user.external_id }}`            | ✅                  |
| Tags         | Object | `{{ user.tags.your_tag_key_here }}` | ❌                  |
| Language     | String | `{{ user.language }}`               | ✅                  |

<Warning>
  Tags are not available when testing webhooks outside an active Journey. Use [Test Users](./test-users) to validate behavior before going live.
</Warning>

***

## Adding a webhook to a Journey

1. After creating and testing your webhook, open your Journey.
2. Add a **Webhook step** where needed.
3. Select the webhook you configured earlier.

Each time a user reaches that step, the webhook fires with their personalized data.

<Frame>
  <img alt="Journey canvas with a webhook step connected between message steps" />
</Frame>

***

## Debugging and logs

### Webhook stats

Go to the webhook’s **Stats** tab to view how your webhook is performing. This includes:

* Total events sent
* Response time trends
* Status code distribution

<Frame>
  <img alt="Webhook stats tab with event count, response time trends, and status code distribution" />
</Frame>

### Logs tab

For more granular insights, the Logs tab displays:

* Recent request/response data
* Status codes and error messages
* Headers and payloads (where applicable)

<Frame>
  <img alt="Webhook logs tab with recent requests, status codes, and payloads" />
</Frame>

***

## Retry logic and disabling behavior

OneSignal retries failed webhook requests for recoverable errors (like `429 Too Many Requests`). Retries use increasing delays between attempts.

If retries repeatedly fail, the webhook is marked as **permanently failed** and no further attempts are made.

### Automatic disabling

If a webhook consistently fails, OneSignal disables it to prevent further issues. Admins receive email alerts and a dashboard banner before and after disabling. Troubleshoot the root cause and test the webhook before re-enabling it.

Your endpoint must handle the volume of events your Journey produces. Review your app’s message send volume to estimate the throughput your API needs.

### Performance guidance

* Slow or overloaded endpoints (especially those returning `429` responses) can trigger automatic disabling.
* Record events quickly and defer additional processing to avoid timeouts.
* Volume scales with user activity — ensure your endpoint can handle peak throughput.
* Use the `event.id` value (available as a header or in the body) to deduplicate incoming events.

### Reliability best practices

* **Route through your own server first**, not directly to third-party services. This gives you control over logging, authentication, throttling, and queuing. Third-party services may rate-limit or block requests during volume spikes, and OneSignal does not manage those limits.
* **Plan for bursts.** Webhook execution happens immediately when users reach the step. If many users hit a webhook step at once, OneSignal sends a burst of HTTP requests without rate limiting. Consider building a lightweight API layer or queuing proxy that can ingest webhooks reliably, apply rate limits or batching, and route requests to third-party services gracefully.
* **Review third-party API limits.** Popular tools like Slack, Twilio, and Segment offer public HTTP APIs but have their own rate limits, authentication requirements, and error handling. Check their documentation before connecting directly.

***

## Securing your webhook

To verify that requests are coming from OneSignal, add a custom authorization header (for example, `Authorization: Bearer YOUR_SECRET_TOKEN`) and verify it server-side before accepting the request.

***

## FAQ

### Can I use webhooks to call OneSignal APIs?

No. Journey webhooks are designed for sending data to external systems only. They cannot call OneSignal APIs. To update OneSignal data based on Journey events, route the webhook through your own server and have your server call the OneSignal API.

### Why was my webhook automatically disabled?

OneSignal disables webhooks that consistently fail to prevent further issues. Check the **Logs** tab for error details (status codes, response bodies), fix the root cause, and test the webhook before re-enabling it. Common causes include endpoint downtime, authentication errors, and rate limiting.

### How do I deduplicate webhook events?

Use the `event.id` value (available as a header or in the request body) to identify unique events. Store processed event IDs on your server and skip any duplicates. This is especially important if retries deliver the same event more than once.

### Are webhook requests rate limited by OneSignal?

No. OneSignal sends webhook requests immediately as users reach the step, without rate limiting. If many users hit a webhook step at once, your endpoint receives a burst of requests. Build your endpoint to handle peak volume, or use a queuing proxy to buffer and batch requests.

### Can I test webhooks without launching a Journey?

Yes. Use the **Test** button in the webhook configuration to send a sample request. Note that [tags](./add-user-data-tags) are not available in test requests — use [Test Users](./test-users) in a live Journey for full validation.

***

## Related pages

<Columns>
  <Card title="Journeys overview" icon="route" href="./journeys-overview">
    Introduction to Journeys and how multichannel workflows operate.
  </Card>

  <Card title="Journey actions" icon="code-branch" href="./journeys-actions">
    Add wait steps, branching logic, time windows, and split paths.
  </Card>

  <Card title="Liquid syntax" icon="code" href="./using-liquid-syntax">
    Full reference for Liquid templating in OneSignal messages and webhooks.
  </Card>

  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Overview of all personalization methods including tags, Liquid, and dynamic content.
  </Card>
</Columns>


# Apache Kafka
Source: https://documentation.onesignal.com/docs/en/kafka

Sync custom events from Apache Kafka topics to OneSignal to trigger automated Journeys and personalized messaging campaigns based on real-time user behavior.

## Overview

The OneSignal + Apache Kafka integration enables automatic syncing of custom events from your Kafka topics directly to OneSignal's Custom Events API. This allows you to trigger automated Journeys and personalized messaging campaigns based on real-time user behavior streaming through your Kafka infrastructure.

You can sync events like purchases, product views, subscription changes, or any custom user actions to automatically trigger onboarding sequences, re-engagement campaigns, transactional messages, and targeted promotions across push notifications, email, in-app messages, and SMS.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Apache Kafka

* **Kafka Cluster** (Apache Kafka, Confluent, or cloud-managed)
* **Topics** containing event data
* **Authentication credentials** (SASL/SCRAM, SSL, or API keys)
* **Network access** to Kafka brokers
* **Event data** in JSON format

***

## Setup

### Configure Kafka permissions

OneSignal needs to consume events from your Kafka topics. The exact setup depends on your Kafka configuration:

<Steps>
  <Step title="Gather connection details">
    Collect the following information about your Kafka cluster:

    * **Bootstrap Servers**: Kafka broker endpoints
    * **Security Protocol**: PLAINTEXT, SASL\_PLAINTEXT, SASL\_SSL, or SSL
    * **Authentication**: Username/password, certificates, or API keys
    * **Topic Names**: List of topics containing event data
  </Step>

  <Step title="Create consumer credentials">
    Create credentials for OneSignal to access your Kafka topics:

    **For SASL/SCRAM authentication:**

    ```bash theme={null}
    # Create a user with read access to event topics
    kafka-configs --bootstrap-server localhost:9092 \
      --alter --add-config 'SCRAM-SHA-256=[password=onesignal-password]' \
      --entity-type users --entity-name onesignal-consumer
    ```

    **For ACL-based authorization:**

    ```bash theme={null}
    # Grant read access to topics and consumer group
    kafka-acls --bootstrap-server localhost:9092 \
      --add --allow-principal User:onesignal-consumer \
      --operation Read --topic your-event-topic

    kafka-acls --bootstrap-server localhost:9092 \
      --add --allow-principal User:onesignal-consumer \
      --operation Read --group onesignal-consumer-group
    ```
  </Step>

  <Step title="Verify topic access">
    Test that OneSignal can access your event topics:

    ```bash theme={null}
    kafka-console-consumer --bootstrap-server localhost:9092 \
      --topic your-event-topic \
      --from-beginning \
      --max-messages 5
    ```
  </Step>
</Steps>

### Configure OneSignal Kafka connection

<Steps>
  <Step title="Navigate to integrations">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.
  </Step>

  <Step title="Select Apache Kafka">
    Choose **Apache Kafka** from the list of available integrations.
  </Step>

  <Step title="Enter connection details">
    Provide your Kafka connection information:

    * **Bootstrap Servers**: Comma-separated broker endpoints
    * **Security Protocol**: Your cluster's security configuration
    * **Username/Password**: SASL credentials (if applicable)
    * **Topic Names**: Topics containing your event data
    * **Consumer Group**: Unique group ID for OneSignal
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify OneSignal can connect to your Kafka cluster and consume events.
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

***

## Event Data Schema

Your Kafka event messages should be in JSON format and include fields that map to OneSignal custom event structure:

| Kafka Event Field | OneSignal Event Field | Description |
| ----------------- | --------------------- | ----------- |
| `event_type`      |                       |             |


# Managing journeys
Source: https://documentation.onesignal.com/docs/en/managing-journeys

Edit Journey steps and messages, view stats, duplicate or archive flows, delete Journeys, and add team notes for collaboration.

## Editing a Journey

To edit a Journey, click the **Edit** button. This activates **Edit Mode**, allowing you to modify steps, messages, wait durations, and other Journey components.

Once done, click **Settings > Save**. Changes are applied as follows:

* **Step changes** take effect immediately. Any active or future users will flow through the updated steps based on where they are in the Journey.
* **Settings changes** only affect users who enter the Journey *after* the changes are saved. Existing users in the flow remain unaffected.

### Editing wait steps

Changing the duration of a **Wait** step only affects users who enter the step after the change. Timers already set for existing users are not updated or reset.

### Editing message steps

* If you **update the content/template** of an existing message step, existing stats are retained and new metrics accumulate from the time of the change.
* If you **replace or remove** a message step, the new step starts tracking stats from zero.

### Editing split branches

Split Branches are locked once a Journey is live. If you need to change the number or structure of branches, you must **duplicate or create a new Journey**.

### Editing audience segments

Audience segments on a live Journey with [Future additions only](./journeys-settings#future-additions-only) enabled are locked and cannot be modified. If you need to change the target audience, you must **duplicate or create a new Journey**.

***

## Viewing and refreshing stats

* Click **View Stats** to exit Edit Mode and enter Stat Mode. This allows you to analyze message and Journey performance.
* Use **Refresh Stats** to reload the most recent user interaction data.

For a full breakdown of metrics and reporting, see [Journeys Analytics](./journeys-analytics).

***

## Journey management

Click the **More Options** (⋯) menu to access additional management tools:

### Stop or archive a Journey

* **Stop + Archive** halts all user progress through the Journey and marks it as archived.
* Archived Journeys can still be viewed and duplicated, but cannot resume sending.

### Duplicate a Journey

* **Duplicate** creates a new Journey with the same structure and settings.
* **Start and end times are not copied.** You must set them manually for the new Journey.
* **In-App Messages are copied, not referenced.** If the original Journey contains IAMs, duplicating it creates independent copies of those IAMs. Edits to the original IAM will not affect the copies.

<Note>
  There is currently no way to share a single IAM across multiple Journeys. When adding an IAM to a Journey step, you can create a new IAM or select an existing one. In both cases, a new independent copy is created. Changes made to the source IAM do not propagate to any copies.
</Note>

### Export a Journey as an image

* **Export as Image** downloads a PNG of your Journey canvas.

<Note>
  Only steps visible on screen are included in the export. Zoom out or scroll to ensure all steps are visible before exporting.
</Note>

### Delete a Journey

* **Delete** permanently removes the Journey and all associated data.

<Danger>
  Deleting a Journey is irreversible. All stats, message reports, and audience activity data are permanently lost. Duplicate the Journey first if you need to preserve its structure.
</Danger>

***

## Adding team notes

Use **Notes** to annotate Journey steps with context for your team, such as segmentation logic, testing hypotheses, or what a specific message is intended to achieve.

### How to add a note

1. Enter **Edit Mode**.
2. Select a message or action step.
3. Add your note.
4. Click **Save**.

<Frame>
  <img alt="Adding a note to a Journey step in the editor" />
</Frame>

Once saved, a note icon appears on the step. Click the icon to view or edit the note.

<Frame>
  <img alt="Note icon displayed on a Journey step after saving" />
</Frame>

***

## FAQ

### Can I edit a live Journey without pausing it?

Yes. Click **Edit** to enter Edit Mode on a live Journey. Step changes take effect immediately for active users, while settings changes only affect users who enter after saving. You do not need to pause or stop the Journey.

### What happens to stats when I update a message step?

If you update the content or template of an existing message step, existing stats are preserved and new metrics accumulate from the time of the change. If you replace or remove the step entirely, the new step starts tracking from zero.

### Can I undo changes to a Journey?

No. There is no undo or version history for Journey edits. If you need to revert, duplicate the Journey before making changes so you have a copy of the original structure.

### How do I change the audience on a live Journey with "Future additions only"?

You cannot modify audience segments on a live Journey that uses [Future additions only](./journeys-settings#future-additions-only). Duplicate the Journey, update the audience on the new copy, and launch it instead.

### Can I recover a deleted Journey?

No. Deleting a Journey permanently removes it and all associated data. Duplicate or archive a Journey instead of deleting if you may need it later.

***

## Related pages

<Columns>
  <Card title="Journey settings" icon="gear" href="./journeys-settings">
    Configure entry rules, exit rules, re-entry, and scheduling.
  </Card>

  <Card title="Journey analytics" icon="chart-line" href="./journeys-analytics">
    View delivery metrics, engagement stats, and audience activity for each Journey.
  </Card>

  <Card title="Journey actions" icon="code-branch" href="./journeys-actions">
    Add wait steps, branching logic, time windows, and split paths.
  </Card>

  <Card title="Journey examples" icon="lightbulb" href="./journeys-examples">
    Step-by-step configurations for common Journey patterns.
  </Card>
</Columns>


# Materialize
Source: https://documentation.onesignal.com/docs/en/materialize

Sync custom events from Materialize to OneSignal to trigger automated Journeys and personalized messaging campaigns based on real-time user behavior.

## Overview

The OneSignal + Materialize integration enables automatic syncing of custom events from your Materialize streaming database to OneSignal to trigger automated messaging campaigns and Journeys based on real-time user behavior.

Materialize is a PostgreSQL-compatible streaming database that maintains incrementally updated views of your data, enabling real-time analytics and event processing.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Materialize

* **Materialize account** with console access
* **App Password** for external tool authentication
* **Materialized views** or tables containing event data
* **Event data** accessible in your Materialize database

***

## Setup

<Steps>
  <Step title="Get Materialize connection details">
    Sign in to the Materialize console and navigate to the **Connect** page to find your connection details.
  </Step>

  <Step title="Create App Password">
    In the Materialize console, create a new **App Password** for OneSignal to use for authentication.
  </Step>

  <Step title="Connect to OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Materialize** and provide:

    * **Host:** Your Materialize host name (found under **External Tools** in the Materialize console Connect page)
    * **Username:** Your email address (used to sign in to Materialize)
    * **Password:** The App Password created in Step 2
    * **Database:** Database name (optional, defaults to `materialize`)
  </Step>

  <Step title="Test connection">
    Click **Test** to verify the connection is working correctly.
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Real-time Event View

```sql theme={null}
-- Real-time materialized view for recent events
CREATE MATERIALIZED VIEW analytics.recent_user_events AS
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_properties,
    session_id,
    device_type
FROM raw_events.stream
WHERE event_timestamp >= NOW() - INTERVAL '1 day';
```

***

## Processing Modes

### Materialized Views (Recommended)

Leverage Materialize's real-time processing by syncing from materialized views that automatically update as new data arrives:

```sql theme={null}
-- High-value events materialized view
CREATE MATERIALIZED VIEW analytics.high_value_events AS
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_properties || jsonb_build_object(
        'source', 'materialize',
        'value_tier', 'high'
    ) as event_properties
FROM raw_events.stream
WHERE (event_properties->>'value')::numeric > 100;
```

### SQL Query Mode

Write custom PostgreSQL-compatible queries to transform your event data:

```sql theme={null}
-- Real-time user activity summary
SELECT
    'activity_summary' as event_name,
    user_id,
    NOW() as event_timestamp,
    jsonb_build_object(
        'events_last_hour', COUNT(*),
        'unique_sessions', COUNT(DISTINCT session_id),
        'total_value', SUM((event_properties->>'value')::numeric),
        'last_seen', MAX(event_timestamp)
    ) as event_properties
FROM analytics.recent_user_events
WHERE event_timestamp >= NOW() - INTERVAL '1 hour'
GROUP BY user_id
HAVING COUNT(*) >= 5;
```

### Real-time Stream Processing

```sql theme={null}
-- Progressive profiling view
CREATE MATERIALIZED VIEW analytics.user_progression AS
SELECT
    user_id,
    COUNT(*) as total_events,
    COUNT(DISTINCT event_name) as unique_event_types,
    MAX(event_timestamp) as last_activity,
    CASE
        WHEN COUNT(*) >= 50 THEN 'power_user'
        WHEN COUNT(*) >= 20 THEN 'active_user'
        WHEN COUNT(*) >= 5 THEN 'engaged_user'
        ELSE 'new_user'
    END as user_segment
FROM raw_events.stream
GROUP BY user_id;
```

***

## Limitations

* Materialize only supports the Basic Sync Engine
* Real-time queries may consume more compute resources
* Complex joins across large datasets should be optimized
* Materialized views require ongoing cluster resources

***

## FAQ

### How do I optimize real-time performance in Materialize?

Use indexes on frequently queried columns and consider partitioning large event datasets by time ranges for better performance.

### Can I sync from both tables and materialized views?

Yes, OneSignal can read from both static tables and real-time materialized views in Materialize.

### How does real-time syncing work?

Materialize maintains incrementally updated views, so OneSignal will always read the latest state of your data without additional processing overhead.

***


# Message events
Source: https://documentation.onesignal.com/docs/en/message-events

Track per-user message interactions: delivered, opened, clicked, and more.

## What are message events?

A message event is recorded each time something happens between a message and a user: a push notification is delivered, an email is opened, an SMS is clicked, and so on. OneSignal records these events automatically across push, email, SMS, and in-app for every user in your app.

Message events give you a timestamped, per-user record of your messaging history. They are not the same as message reports — reports are campaign-level totals, while message events are per-user, per-message records.

## When to use message events

* **Support and investigation**: Look up a specific user to confirm whether and when a message was sent, delivered, or opened.
* **Journey debugging**: Trace a user's progress through a multi-step Journey by reviewing what they received and when.
* **Engagement context**: Understand a user's recent interaction history before contacting them or making a product decision about their experience.
* **Segmentation**: Target audiences based on message event behavior — for example, users who received but did not click a push in the last 30 days. See [Segmentation](./segmentation#message-event-filters) for full details.
* **Conversion attribution**: Message events are the basis for conversion attribution. When a user completes a conversion event, OneSignal checks their recent message history to determine which message, if any, influenced the action. See [Conversions](./conversion-metrics) for details.

## View message events for a user

To view message events for a specific user:

<Steps>
  <Step title="Open the user's profile">
    Go to **Audience > Users** in the OneSignal dashboard, then find and open the user's profile.
  </Step>

  <Step title="Select the Event log tab">
    The event log shows each message event associated with that user, in reverse chronological order.
  </Step>

  <Step title="Filter the log">
    Narrow results by:

    * **Time range** — a specific date range, up to your plan's full retention window.
    * **Channel** — push, email, SMS, or in-app events.
  </Step>
</Steps>

<Note>
  Events can take up to 5 minutes from when they occur to appear in a user's event log.
</Note>

## Segment users by message events

You can build audience segments based on message event behavior — for example, targeting users who clicked a push notification in the last 7 days, or who received an email but did not open it.

<Frame>
  <img alt="Email message event filter in the OneSignal segment builder" />
</Frame>

<Card title="Segmentation" icon="filter" href="./segmentation#message-event-filters">
  Build segments based on message event behavior across push, email, SMS, and in-app.
</Card>

## Retention

How far back you can view message events depends on your plan.

| Plan       | Retention     |
| ---------- | ------------- |
| Free       | Not available |
| Growth     | 30 days       |
| Pro        | 60 days       |
| Enterprise | 90 days       |

<Info>
  OneSignal began storing message events to support extended retention on April 14, 2026. Events before that date are not available to view on the user profile, regardless of plan.

  **Older events remain available for segmentation** — they just won't appear in the event log view.
</Info>

For more on how retention affects billing, see the [Billing FAQ](./billing-faq).

## Message events vs. Event Streams

Message events and Event Streams both involve the same underlying data, but they serve different purposes.

|                      | Message events                | Event Streams                           |
| -------------------- | ----------------------------- | --------------------------------------- |
| Where the data lives | OneSignal dashboard           | Your warehouse, CRM, or CDP             |
| Best for             | Per-user lookup, segmentation | Long-term analytics, external workflows |
| Retention            | 30 / 60 / 90 days by plan     | Whatever your destination keeps         |
| Latency              | Up to 5 minutes               | Near real-time                          |

Use **message events** when you need to look up or segment users within OneSignal. Use **Event Streams** when you need messaging data flowing into your own systems, especially when long-term storage of events is required.

<Card title="Event Streams" icon="bolt" href="./event-streams">
  Forward message events to an external destination in near real-time.
</Card>

## FAQ

### Why don't I see message events for a user on the Free plan?

Message event retention is not available on the Free plan. To view per-user event history in the dashboard, you'll need to upgrade to Growth, Pro, or Enterprise. Message events still feed segmentation regardless of plan.

### How long does it take for a message event to appear in the event log?

Up to 5 minutes from when the event occurs. If you need lower latency or external storage, use [Event Streams](./event-streams) instead.

### Can I see message events from before April 14, 2026?

Not on the user profile. OneSignal began storing message events for extended retention on that date, so earlier events do not appear in the event log. They remain available for segmentation.

### How do message events relate to conversion attribution?

When a user completes a conversion event, OneSignal looks back through their recent message events to determine which message influenced the action. Without message events, OneSignal cannot attribute conversions to specific messages. See [Conversions](./conversion-metrics) for the full attribution model.

### Can I export message events to my own data warehouse?

Yes — use [Event Streams](./event-streams) to forward message events to a destination like Snowflake, BigQuery, or a CDP in near real-time. Event Streams is the right tool when you need long-term storage or want to combine messaging data with your own analytics.

## Related pages

<Columns>
  <Card title="Segmentation" icon="filter" href="./segmentation#message-event-filters">
    Build segments based on message event behavior across push, email, SMS, and in-app.
  </Card>

  <Card title="Event Streams" icon="bolt" href="./event-streams">
    Forward message events to an external destination in near real-time.
  </Card>

  <Card title="Conversions" icon="bullseye" href="./conversion-metrics">
    Attribute downstream user actions back to the messages that influenced them.
  </Card>

  <Card title="Billing FAQ" icon="circle-question" href="./billing-faq">
    How retention windows and event volume affect your plan.
  </Card>
</Columns>


# Microsoft Fabric
Source: https://documentation.onesignal.com/docs/en/microsoft-fabric

Sync custom events from Microsoft Fabric to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Microsoft Fabric integration enables automatic syncing of custom events from your Fabric lakehouse or warehouse to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

Microsoft Fabric is a unified analytics platform that brings together data engineering, data science, real-time analytics, and business intelligence in a single environment.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Microsoft Fabric

* **Microsoft Fabric capacity** with workspace access
* **Service Principal** with appropriate permissions
* **SQL Endpoint** (Warehouse or Lakehouse) containing event data
* **External API access** enabled in tenant settings

***

## Setup

<Steps>
  <Step title="Create service principal in Azure">
    Create a new service principal for OneSignal to access your Fabric resources:

    1. Sign in to the Azure portal
    2. Navigate to **Microsoft Entra ID** > **App registrations**
    3. Click **+ New registration**
    4. Enter name: "OneSignal Fabric Integration"
    5. Select **Accounts in this organizational directory only**
    6. Click **Register**
    7. Note the **Application (client) ID** and **Directory (tenant) ID**
    8. Under **Certificates & secrets**, create a new client secret
    9. Note the **client secret value**
  </Step>

  <Step title="Configure Fabric tenant settings">
    Enable external access for service principals:

    1. In Microsoft Fabric, click **Settings** > **Admin portal**
    2. Go to **Tenant settings**
    3. Under **Developer settings**, enable **Service principals can use Fabric APIs**
    4. Under **OneLake settings**, enable **Users can access data stored in OneLake with apps external to Fabric**
  </Step>

  <Step title="Grant workspace access">
    Add the service principal to your Fabric workspace:

    1. Navigate to your workspace (create shared workspace if using "My Workspace")
    2. Click **Manage Access** > **+ Add people or groups**
    3. Select your service principal
    4. Set role to **Contributor**
  </Step>

  <Step title="Get SQL endpoint">
    Obtain the SQL connection string for your data source:

    1. In your workspace, hover over your warehouse/lakehouse
    2. Click **...** > **Settings**
    3. Copy the **SQL connection string** (this is your hostname)
  </Step>

  <Step title="Connect to OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Microsoft Fabric** and provide:

    * **Hostname:** SQL endpoint from Step 4
    * **Database/Catalog:** Your lakehouse or warehouse name
    * **Tenant ID:** Directory ID from Step 1
    * **Client ID:** Application ID from Step 1
    * **Client Secret:** Secret value from Step 1
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Table Schema

```sql theme={null}
-- Example Fabric table structure
CREATE TABLE user_events (
    event_name STRING,
    user_id STRING,
    event_time TIMESTAMP,
    properties JSON,
    session_id STRING,
    device_type STRING
);
```

***

## Processing Modes

### SQL Query Mode

Write custom SQL queries to transform your Fabric data before syncing:

```sql theme={null}
SELECT
    event_name,
    user_id,
    event_time,
    TO_JSON(STRUCT(
        session_id,
        device_type,
        product_id
    )) as properties
FROM user_events
WHERE event_time >= CURRENT_DATE - INTERVAL 7 DAYS
```

### Table Mode

Sync entire tables or views directly from your Fabric workspace. OneSignal will automatically map columns to event fields.

***

## Limitations

* Requires Fabric capacity (not available on trial)
* SQL endpoints must be accessible to external services
* Large result sets may impact sync performance

***

## FAQ

### How do I optimize query performance?

Use partitioning and indexing in your Fabric tables. Consider creating materialized views for frequently accessed event data.

### Can I sync from both lakehouses and warehouses?

Yes, OneSignal supports any Fabric resource that exposes a SQL endpoint, including lakehouses, warehouses, and SQL analytics endpoints.

***


# Mixpanel
Source: https://documentation.onesignal.com/docs/en/mixpanel

Integrate OneSignal with Mixpanel to sync behavioral cohorts, track message events, and target Users across push, email, SMS, and in-app channels.

Integrate OneSignal with [Mixpanel](https://mixpanel.com) to enable real-time, behavior-based targeting across push, in-app, email, and SMS. This app-level integration supports two data flows:

* **Message events → Mixpanel**: Track delivery, clicks, failures, and more for all channels.
* **Cohorts → OneSignal**: Sync behavior-based Mixpanel cohorts as targeting filters in OneSignal.

The Mixpanel integration does not send Mixpanel events to OneSignal as [custom events](./custom-events). See [Can I send custom events from Mixpanel to OneSignal?](#can-i-send-custom-events-from-mixpanel-to-onesignal) for the recommended workaround.

***

## Requirements

* [Mixpanel Account](https://mixpanel.com/)
* [OneSignal Paid Plan](https://onesignal.com/pricing)
* OneSignal app with [Users](./users) and External ID set.

<Info>
  This integration does not create Users. It maps Users in Mixpanel to existing Users in OneSignal by matching identifiers.
</Info>

***

## Setup

### Add Mixpanel to OneSignal (Outbound)

Sends OneSignal message events into your Mixpanel project.

<Steps>
  <Step title="Open the integration in OneSignal">
    In OneSignal, navigate to **Data > Integrations > Mixpanel** and click **Activate**.

    <Frame>
      <img alt="OneSignal Integrations page with Mixpanel selected" />
    </Frame>
  </Step>

  <Step title="Add your Mixpanel project token">
    In Mixpanel, find your [Project Token](https://docs.mixpanel.com/docs/orgs-and-projects/managing-projects#find-your-project-tokens) and paste it into OneSignal.
  </Step>

  <Step title="Set your data residency">
    Check your [Data Residency](https://docs.mixpanel.com/docs/orgs-and-projects/managing-projects#project-details). If you use Mixpanel's EU servers, check the **Send events exclusively to Mixpanel's EU Residency Server** box.
  </Step>

  <Step title="Select message events and activate">
    Select which OneSignal message events to send to Mixpanel, then click **Activate**.

    <Frame>
      <img alt="OneSignal Mixpanel integration settings showing event selection" />
    </Frame>
  </Step>
</Steps>

### Add OneSignal to Mixpanel (Inbound)

Sends Mixpanel cohorts into OneSignal as Segment filters.

<Steps>
  <Step title="Add OneSignal in Mixpanel">
    In your Mixpanel **Integrations**, add OneSignal.

    <Frame>
      <img alt="Mixpanel integrations catalog with OneSignal selected" />
    </Frame>
  </Step>

  <Step title="Name the connector">
    Set the **Connector Name** to something identifiable like `OneSignal - APP_NAME`, where `APP_NAME` is your OneSignal app name.
  </Step>

  <Step title="Add your OneSignal credentials">
    Enter the **App ID** and **API Key** from your OneSignal app's **Settings > [Keys & IDs](./keys-and-ids)** page.
  </Step>
</Steps>

### User ID mapping

The OneSignal **[External ID](./users)** must match the Mixpanel **User ID Property** you select (for example, `user_id`). Cohort syncing and message event tracking only work when this mapping is exact.

<Steps>
  <Step title="Select the User ID Property in Mixpanel">
    In the Mixpanel OneSignal connector, choose the **User ID Property** that holds the same value as the OneSignal External ID.

    <Frame>
      <img alt="Mixpanel OneSignal connector settings showing User ID property selection" />
    </Frame>
  </Step>

  <Step title="Confirm the property exists on Mixpanel user profiles">
    Open **Mixpanel > Users** and verify the **User ID Property** you selected appears in user profile properties.

    <Frame>
      <img alt="Mixpanel user profile properties list" />
    </Frame>
  </Step>

  <Step title="Confirm values match the OneSignal External ID">
    Open the User in **OneSignal > Audience > Users** and confirm the External ID matches the Mixpanel **User ID Property** value exactly.

    <Frame>
      <img alt="OneSignal user profile showing External ID" />
    </Frame>
  </Step>
</Steps>

<Warning>
  If you map the Mixpanel `$distinct_id` to the OneSignal External ID, only the top value in the Distinct ID list matches.

  In the example below, only `890ea9b1-9024-4fb9-a92f-152ba67dd21a` will match. The integration cannot match `109768518080488203109` or `$device:1880c06821f1b3-052354675cde95-1d525634-1fa400-1880c06821f1b3`.

  <Frame>
    <img alt="Mixpanel Distinct ID example showing multiple values" />
  </Frame>
</Warning>

<Check>
  Click **Continue** when finished. You can now export cohorts from Mixpanel to OneSignal and collect message events from OneSignal in Mixpanel.
</Check>

***

## Export Mixpanel cohorts to OneSignal

Sync Mixpanel cohorts to OneSignal using the matching External ID configured above. Exporting **does not create Users** — each User must already exist in OneSignal.

<Steps>
  <Step title="Create a cohort in Mixpanel">
    In Mixpanel, create a cohort containing the Users you want to target.
  </Step>

  <Step title="Export to OneSignal">
    Click **Options > Export to... > *The OneSignal Connection name***.

    <Frame>
      <img alt="Mixpanel cohort export menu with OneSignal destination" />
    </Frame>
  </Step>

  <Step title="Choose a sync frequency">
    Select how often Mixpanel should sync the cohort, then click **Begin Sync**.

    <Frame>
      <img alt="Mixpanel cohort sync frequency selection dialog" />
    </Frame>
  </Step>
</Steps>

### OneSignal Segment creation

The synced cohort appears as a **Mixpanel Segment filter**. OneSignal automatically creates a Segment for the cohort if:

* The Users in the Mixpanel cohort also exist in OneSignal with a matching External ID.
* You have not exceeded your Segment limit in OneSignal.

<Note>
  OneSignal requires at least one matching User to create the Segment. After creation, the Segment remains in OneSignal even if the cohort later has no Users — it shows as empty until matching Users are added again.
</Note>

<Frame>
  <img alt="OneSignal Segment builder using Mixpanel Cohort filter" />
</Frame>

***

## Track message events in Mixpanel

OneSignal sends the following message events to Mixpanel in real time. Select which events to send in **Data > Integrations > Mixpanel**.

To test, send yourself a message from OneSignal, then navigate to your user profile page in Mixpanel. Within the Activity Feed, you should see the events populate.

<Frame>
  <img alt="Mixpanel user activity feed showing OneSignal message events" />
</Frame>

### Message events

#### Push

| Message Event Kind (OneSignal) | Message Event Name (Mixpanel) | Event Description                                                  |
| ------------------------------ | ----------------------------- | ------------------------------------------------------------------ |
| Push Sent                      | Message Sent                  | Push notification successfully sent.                               |
| Push Received                  | Message Received              | Push notification successfully received.                           |
| Push Clicked                   | App Opened from Push          | Push notification tapped on device.                                |
| Push Failed                    | Push Failed                   | Push failed to send. Check the failed message report in OneSignal. |
| Push Unsubscribed              | Push Unsubscribed             | The [Subscription](./subscriptions) unsubscribed from push.        |

#### In-app

| Message Event Kind (OneSignal) | Message Event Name (Mixpanel) | Event Description                                |
| ------------------------------ | ----------------------------- | ------------------------------------------------ |
| In-App Impression              | Message Sent                  | In-app message successfully displayed on device. |
| In-App Clicked                 | Message Opened                | In-app message clicked on device.                |
| In-App Page Displayed          | In-App Page Displayed         | In-app message page displayed.                   |

#### Email

| Message Event Kind (OneSignal) | Message Event Name (Mixpanel) | Event Description                                                                               |
| ------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------- |
| Email Sent                     | Message Sent                  | Email successfully sent.                                                                        |
| Email Received                 | Message Received              | Email received by recipient.                                                                    |
| Email Opened                   | Message Opened                | Email opened by recipient.                                                                      |
| Email Link Clicked             | App Opened from Push          | Email link clicked.                                                                             |
| Email Unsubscribed             | Email Unsubscribed            | Email unsubscribed by recipient.                                                                |
| Email Reported As Spam         | Email Reported as Spam        | Email reported as spam by recipient.                                                            |
| Email Bounced                  | Email Bounced                 | Email returned to sender due to a permanent error.                                              |
| Email Failed                   | Email Failed                  | Could not deliver the email to the recipient's inbox.                                           |
| Email Suppressed               | Email Suppressed              | The email address is on your suppression list. Either it bounced or marked your emails as spam. |

#### SMS

| Message Event Kind (OneSignal) | Message Event Name (Mixpanel) | Event Description           |
| ------------------------------ | ----------------------------- | --------------------------- |
| SMS Sent                       | Message Sent                  | SMS sent to recipient.      |
| SMS Failed                     | SMS Failed                    | SMS failed to send.         |
| SMS Delivered                  | Message Received              | SMS successfully delivered. |
| SMS Undelivered                | SMS Undelivered               | The SMS could not be sent.  |

### Event properties

Every event sent from OneSignal to Mixpanel includes these properties:

| PROPERTY NAME        | DESCRIPTION                                             |
| -------------------- | ------------------------------------------------------- |
| **Distinct ID**      | The external\_id associated with the message            |
| **Message ID**       | The identifier of the discrete message                  |
| **Message Name**     | The message name                                        |
| **Message Title**    | The message title                                       |
| **Message Contents** | The message contents                                    |
| **message\_type**    | The type of message sent, push, in-app, email, SMS      |
| **template\_id**     | The message template used (API and Journey Messages)    |
| **subscription\_id** | The OneSignal-assigned device, email, or SMS identifier |
| **device\_type**     | The device type that received the message               |
| **language**         | The two-character language code of the device           |
| **source**           | `onesignal` (is indicated as the source for all events) |

<Warning>
  Delivery counts may differ between Mixpanel and OneSignal. See [Why doesn't delivery data match?](#why-doesnt-delivery-data-match) for details.
</Warning>

***

## FAQ

### Why don't my cohort and segment counts match?

1. **Missing or mismatched External IDs**
   Only Users with a matching OneSignal External ID and Mixpanel User ID are included. This integration does not create Users or Subscriptions.

2. **Unsubscribed Users**
   OneSignal Segments only display the count for subscribed [Subscriptions](./subscriptions). Unsubscribed Subscriptions are available for Journeys or In-App Messages.

For example, if a Mixpanel cohort has 10 Users but the OneSignal Segment shows 8 Subscriptions, the 2 missing Users may:

* Not exist in OneSignal or have an incorrect External ID.
* Have unsubscribed Subscriptions.

To verify, check the **Audience > Users** tab in OneSignal to see if the Users exist and have active Subscriptions.

### Do unsubscribed Users sync from Mixpanel?

Yes, but they are excluded from the OneSignal Segment counts at this time. You can still message them via Journeys or In-App Messages if they have other [Subscriptions](./subscriptions) or their Subscription type supports it.

### Why doesn't delivery data match?

A single User may have multiple [Subscriptions](./subscriptions) (push devices, email addresses, phone numbers). Each Subscription generates its own delivery event. For example:

* 1 user = 2 Android + 1 iOS + 2 Web = 5 push Subscriptions
* 1 push message = up to 5 sent/received/clicked events

Use the `subscription_id` in event properties to trace the exact source.

To troubleshoot missing events:

* Ensure `OneSignal.login` is called whenever a user is identified to set the External ID.
* Verify that `OneSignal.logout` isn't removing the External ID.
* Check API requests or CSV uploads that may alter the External ID.

### Can I send custom events from Mixpanel to OneSignal?

Not natively. The Mixpanel integration supports message events (OneSignal → Mixpanel) and cohort syncing (Mixpanel → OneSignal), but does not include a built-in custom event destination. Unlike [Amplitude](./amplitude), Mixpanel has no native OneSignal events destination.

To route Mixpanel behavioral events into OneSignal as [custom events](./custom-events) that trigger Journeys or Segments, use a third-party connector like [Vendo](https://www.vendodata.com/use-cases/integrate-mixpanel-with-onesignal).

### How can I send user/subscription events?

User and subscription-level events (e.g., permission granted, user login/logout) are not automatically sent.

The OneSignal SDK has event listeners that can be used to track these events for you to send to Mixpanel:

* User State Observer: [Mobile SDK](./mobile-sdk-reference#addobserver-user-state), [Web SDK](./web-sdk-reference#addeventlistener-user-state)
* Permission Observer: [Mobile SDK](./mobile-sdk-reference#addpermissionobserver-push), [Web SDK](./web-sdk-reference#permissionchange)

***

## Related pages

<Columns>
  <Card title="Analytics overview" icon="chart-line" href="./analytics-overview">
    Overview of OneSignal analytics, delivery metrics, and event tracking.
  </Card>

  <Card title="Custom events" icon="bolt" href="./custom-events">
    Track User actions to trigger Journeys or power analytics.
  </Card>
</Columns>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# Mobile SDK setup
Source: https://documentation.onesignal.com/docs/en/mobile-sdk-setup

Set up the OneSignal SDK for Android, iOS, Huawei, and cross-platform frameworks like React Native, Flutter, and Unity.

The OneSignal mobile SDK enables [push notifications](./push), [in-app messages](./in-app-messages-setup), and [Live Activities](./live-activities) in your iOS, Android, Huawei, and Amazon apps. Setup has two steps:

1. **Configure platform credentials** — connect your FCM, APNs, HMS, or ADM credentials to OneSignal
2. **Integrate the SDK** — install the OneSignal SDK for your platform and initialize it in your app

For websites, see [Web SDK setup](./web-push-setup).

***

## Configure platform credentials

Each platform requires its own push credentials. Configure the credentials for every platform your app supports before integrating the SDK.

### Configure your OneSignal app and platform

Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).

<Note>
  If your organization already has a OneSignal account, [ask to be invited](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Step-by-step setup instructions" icon="circle-chevron-down">
  <Steps>
    <Step title="Create or select your app">
      Create a new app by clicking **New App/Website**, or add a platform to an existing app in **Settings > Push & In-App**. Select the platform(s) you want to configure and click **Next: Configure Your Platform**.

      <Frame>
        <img alt="OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection" />
      </Frame>
    </Step>

    <Step title="Configure platform credentials">
      Enter the credentials for your platform:

      * **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
      * **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
      * **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
      * **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)

      Click **Save & Continue** after entering your credentials.
    </Step>

    <Step title="Save your App ID and install the SDK">
      Your **App ID** is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.

      <Frame>
        <img alt="OneSignal dashboard showing the App ID and team invite option after setup" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

***

## Integrate the SDK

<Columns>
  <Card title="Android native" icon="android" href="./android-sdk-setup">
    Integrate the OneSignal SDK into native Android apps using FCM.
  </Card>

  <Card title="iOS native" icon="apple" href="./ios-sdk-setup">
    Integrate the OneSignal SDK into native iOS apps using APNs.
  </Card>

  <Card title="React Native and Expo" icon="react" href="./react-native-sdk-setup">
    Setup for React Native and Expo environments.
  </Card>

  <Card title="Flutter" icon="mobile" href="./flutter-sdk-setup">
    SDK setup for Flutter apps using Dart.
  </Card>

  <Card title="Unity" icon="unity" href="./unity-sdk-setup">
    Cross-platform SDK setup for Unity-based mobile apps.
  </Card>

  <Card title=".NET MAUI" icon="microsoft" href="./net-sdk-setup">
    Integrate the OneSignal SDK with .NET MAUI apps.
  </Card>

  <Card title="Huawei Android native" icon="mobile-screen" href="./huawei-sdk-setup">
    SDK setup for Huawei devices using HMS push services.
  </Card>

  <Card title="Cordova and Ionic Cordova" icon="code" href="./cordova-sdk-setup">
    Setup for Cordova and Ionic Cordova hybrid mobile apps.
  </Card>

  <Card title="Capacitor and Ionic Capacitor" icon="code" href="./capacitor-sdk-setup">
    Setup for Capacitor and Ionic Capacitor hybrid mobile apps.
  </Card>
</Columns>

### Other integrations

<Columns>
  <Card title="FlutterFlow" icon="wand-magic-sparkles" href="./flutterflow-sdk-setup">
    Low-code SDK setup for FlutterFlow apps.
  </Card>

  <Card title="Median.co" icon="globe" href="./median-integration">
    Integration guide for Median.co (formerly GoNative.io) apps.
  </Card>
</Columns>

***

## SDK versions

<SdkReleasesIframe />

***

## FAQ

### Are the SDKs required?

No, but they're highly recommended and open source on [GitHub](https://github.com/OneSignal/sdks). You can integrate OneSignal using only the [REST API](/reference/rest-api-overview), but the SDKs simplify the process significantly, especially for handling push notifications across platforms.

### What can I do without the SDK?

You can use the following APIs directly:

* [Create User](/reference/create-user)
* [Create Subscription](/reference/create-subscription)
* [Update User](/reference/update-user)
* [Update Subscription](/reference/update-subscription)
* [Create message](/reference/create-message)
* [Notification payload reference](./osnotification-payload)

<Info>
  [In-app messages](./in-app-messages-setup) and [Live Activities](./live-activities) require the SDK — they cannot be delivered via API alone.
</Info>

### Why do you recommend using the SDKs?

Push notifications have platform-specific requirements that the SDKs handle for you, including:

* Obtaining push tokens across Android, iOS, Huawei, and web
* Managing Subscription status and User opt-in prompts
* Displaying and processing push notifications on the client

Apple's APNs and Google's FCM use different payload formats. The OneSignal SDK parses custom payloads to display and track messages accurately. Maintaining this manually adds significant complexity. Learn more: [Build vs. Buy: What Goes Into Building a Push Notification Platform](https://onesignal.com/blog/build-vs-buy-what-goes-into-building-a-push-notification-platform/).

### Do I need separate OneSignal apps for iOS and Android?

No. A single OneSignal app supports multiple platforms — iOS, Android, Huawei, Amazon, and web. Configure each platform's credentials in **Settings > Push & In-App** and they all share the same app, Users, and segments.

### Can devices in China or on Huawei receive push notifications?

If the device has Google Play Services, it receives push through FCM. If the app was downloaded from the Huawei AppGallery (including non-HarmonyOS Huawei devices running Android), it receives push through HMS — set up the [Huawei SDK](./huawei-sdk-setup) to enable this. OneSignal defaults to FCM for devices that support both HMS and FCM. You can [prefer HMS over FCM](./huawei-sdk-setup#prefer-hms-over-fcm-optional) if needed.


# OneSignal MCP Server (Beta)
Source: https://documentation.onesignal.com/docs/en/model-context-protocol

OneSignal MCP Server connects AI assistants to your OneSignal app so you can manage users, segments, templates, messaging, and exports with natural-language prompts.

OneSignal MCP Server lets MCP-compatible AI assistants run OneSignal actions directly — look up a user, check delivery stats, send a test message, or export subscribers — without leaving your editor or AI client.

<Warning>
  OneSignal MCP Server is currently in beta. You may see issues, incomplete behavior, or temporary glitches while we continue improving the experience. If you run into problems, contact `support@onesignal.com`.
</Warning>

## What is MCP?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) is an open-source standard for connecting AI applications to external systems. OneSignal MCP Server lets MCP-compatible assistants run OneSignal actions without switching dashboard pages.

## What can I do with this?

You can complete common OneSignal workflows faster with natural-language prompts.

* Run multi-step tasks in one request, like finding a user, checking subscriptions, and sending a test message
* Reduce onboarding friction for teams that are new to the dashboard or REST API
* Manage day-to-day campaign and user operations directly in your editor or AI client

## Common use cases

You can ask your AI assistant to:

* Send a message to a specific segment
* Look up a user and list all subscriptions
* Check delivery metrics for a recent message
* Create a segment from audience filters
* Create a user and attach email, SMS, or push subscriptions
* Export subscribers or audience activity to CSV

## Set up the OneSignal MCP server

You can usually complete setup in about 5 minutes.

### Prerequisites

You need:

* A OneSignal App ID from **Settings > Keys & IDs**, or from the URL when you're logged into the OneSignal dashboard
* A OneSignal REST API key from **Settings > Keys & IDs**
* A supported MCP client (see options below)

<Warning>
  `Key ID` is not the same as a REST API key. The REST API key value is shown only once when you create it. If you do not already have the key value saved, create a new API key. We recommend creating a dedicated API key for MCP access.
</Warning>

### Connection details

Every client connects to the same server URL:

```text theme={null}
https://server.smithery.ai/onesignal/onesignal
```

After you add the server in your client, the first connection attempt opens a hosted **Connect OneSignal** page in your browser where you enter your **App ID** and **REST API key**. Your credentials are stored with the connection and reused on subsequent requests, so you only do this once per client.

Each MCP server configuration is scoped to one `app_id`. If you manage multiple OneSignal apps, create one MCP configuration per app.

### Configure your AI client

Pick the tab that matches the type of client you use, then follow the steps for your specific app.

<Tabs>
  <Tab title="Chatbots (Claude)">
    #### Claude (Claude Desktop and Claude.ai)

    Add the OneSignal MCP server through Claude's **Connectors** UI. Remote MCP servers cannot be added through `claude_desktop_config.json` — that file is only for local stdio servers.

    <Steps>
      <Step title="Open Connectors settings">
        In Claude Desktop, open **Settings > Connectors**. On claude.ai, open **Settings > Connectors** in the web app.
      </Step>

      <Step title="Add a custom connector">
        Click **Add custom connector** and provide:

        * **Name:** `OneSignal`
        * **Remote MCP server URL:** `https://server.smithery.ai/onesignal/onesignal`

        Then click **Add** (or **Connect**).
      </Step>

      <Step title="Enter your OneSignal credentials">
        A **Connect OneSignal** dialog opens. Enter your:

        * **App ID** — your OneSignal App ID
        * **API Key** — your OneSignal REST API key

        Click **Connect** to finish the setup.
      </Step>

      <Step title="Use OneSignal in a new chat">
        Enable the OneSignal connector in any new chat. Claude lists the connector's tools when the connection succeeds.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Coding tools (Claude Code, Codex, Copilot, Cursor)">
    #### Claude Code

    <Steps>
      <Step title="Add the OneSignal MCP server">
        Run the following command in your terminal:

        ```bash theme={null}
        claude mcp add --transport http onesignal https://server.smithery.ai/onesignal/onesignal
        ```
      </Step>

      <Step title="Authenticate from inside Claude Code">
        Start `claude`, then type `/mcp` to open the MCP panel. Select **onesignal**, then choose **Authenticate** to open the **Connect OneSignal** page in your browser.
      </Step>

      <Step title="Enter your OneSignal credentials">
        On the **Connect OneSignal** page, enter your **App ID** and **API Key**, then click **Connect**. Return to Claude Code and the server status changes to **connected**.
      </Step>
    </Steps>

    Verify with `claude mcp list` or run `/mcp` inside Claude Code to view the tool count.

    #### Codex CLI

    <Steps>
      <Step title="Add OneSignal to your Codex config">
        Open `~/.codex/config.toml` (create the file if it does not exist) and add:

        ```toml theme={null}
        [mcp_servers.onesignal]
        url = "https://server.smithery.ai/onesignal/onesignal"
        enabled = true
        ```
      </Step>

      <Step title="Authenticate with OneSignal">
        Run the following command in your terminal:

        ```bash theme={null}
        codex mcp login onesignal
        ```

        Codex opens the **Connect OneSignal** page in your browser. Enter your **App ID** and **API Key**, then click **Connect**.
      </Step>
    </Steps>

    Restart Codex and the OneSignal tools become available in your next session.

    #### GitHub Copilot (VS Code)

    <Steps>
      <Step title="Add OneSignal to your VS Code MCP config">
        Use `.vscode/mcp.json` in your workspace to share with your team, or run **MCP: Open User Configuration** from the Command Palette to install for your user profile:

        ```json theme={null}
        {
          "servers": {
            "onesignal": {
              "type": "http",
              "url": "https://server.smithery.ai/onesignal/onesignal"
            }
          }
        }
        ```
      </Step>

      <Step title="Authenticate when prompted">
        Open Copilot Chat in **Agent mode**. The first time the OneSignal tools are needed, VS Code prompts you to authenticate and opens the **Connect OneSignal** page in your browser. Enter your **App ID** and **API Key**, then click **Connect**.
      </Step>
    </Steps>

    #### Cursor

    <Steps>
      <Step title="Add OneSignal to your Cursor MCP config">
        Use `~/.cursor/mcp.json` to enable OneSignal across all projects, or `.cursor/mcp.json` inside a project to share with your team:

        ```json theme={null}
        {
          "mcpServers": {
            "onesignal": {
              "url": "https://server.smithery.ai/onesignal/onesignal"
            }
          }
        }
        ```
      </Step>

      <Step title="Authenticate from Cursor settings">
        Restart Cursor and open **Settings > MCP & Integrations**. Click **Authenticate** (or **Needs login**) next to the OneSignal server to open the **Connect OneSignal** page in your browser. Enter your **App ID** and **API Key**, then click **Connect**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Verify the connection

After setup, start a new chat and ask your assistant:

```text theme={null}
Use the onesignal_health tool to check if the server is connected.
```

If the tool returns `ok`, your connection is working.

### Troubleshooting

If a request fails unexpectedly, try the following in order:

* Confirm the API key value you provided on the **Connect OneSignal** page is the secret value shown when you created the key — not the `Key ID`.
* Re-check that the server URL is exactly `https://server.smithery.ai/onesignal/onesignal` with no extra paths or trailing characters.
* Re-authenticate the server from your client's MCP panel (`/mcp` in Claude Code, **Settings > MCP & Integrations** in Cursor, **MCP** view in VS Code, or `codex mcp login onesignal` for Codex).
* Restart the MCP client and start a new chat session. This resolves most transient connection and session issues.

## MCP tool capabilities

OneSignal MCP Server currently supports 31 tools across 7 categories.

### Messaging (3 tools)

| Action                                       | Tool            |
| -------------------------------------------- | --------------- |
| Send a push notification, email, or SMS/RCS  | `send_message`  |
| List recent notifications                    | `list_messages` |
| View notification details and delivery stats | `view_message`  |

To start or update a Live Activity, see [Live Activities](#live-activities-2-tools) below.

### Users and subscriptions (12 tools)

| Action                                            | Tool                                |
| ------------------------------------------------- | ----------------------------------- |
| Look up a user by alias                           | `view_user`                         |
| Get a user's identity aliases                     | `get_user_identity`                 |
| Get identity by subscription ID                   | `get_user_identity_by_subscription` |
| Create a new user with properties                 | `create_user`                       |
| Update user properties (tags, language, and more) | `update_user`                       |
| Add or update identity aliases                    | `create_or_update_alias`            |
| Add aliases via subscription ID                   | `create_alias_by_subscription`      |
| Add a push, email, or SMS subscription            | `create_subscription`               |
| Update an existing subscription                   | `update_subscription`               |
| Update a subscription by token                    | `update_subscription_by_token`      |
| Unsubscribe an email address                      | `unsubscribe_email`                 |
| Transfer a subscription to a different user       | `transfer_subscription`             |

### Templates (4 tools)

| Action            | Tool              |
| ----------------- | ----------------- |
| List templates    | `list_templates`  |
| View a template   | `get_template`    |
| Create a template | `create_template` |
| Update a template | `update_template` |

### Segments (4 tools)

| Action                     | Tool             |
| -------------------------- | ---------------- |
| List segments              | `list_segments`  |
| View a segment and filters | `get_segment`    |
| Create a segment           | `create_segment` |
| Update a segment           | `update_segment` |

### Live Activities (2 tools)

| Action                        | Tool                   |
| ----------------------------- | ---------------------- |
| Start an iOS Live Activity    | `start_live_activity`  |
| Update or end a Live Activity | `update_live_activity` |

### Exports (2 tools)

| Action                                       | Tool                           |
| -------------------------------------------- | ------------------------------ |
| Export subscriptions to CSV                  | `export_subscriptions_csv`     |
| Export notification audience activity to CSV | `export_audience_activity_csv` |

### Analytics and utility (4 tools)

| Action                                 | Tool                           |
| -------------------------------------- | ------------------------------ |
| View outcome analytics                 | `view_outcomes`                |
| Check server health                    | `onesignal_health`             |
| View server configuration              | `onesignal_config`             |
| View a reference overview of all tools | `onesignal_reference_overview` |

## Safety and guardrails

OneSignal MCP Server includes built-in protections for high-impact actions.

### `send_message` protections

* AI clients treat `send_message` as a high-impact action and ask for confirmation before execution
* `send_message` has a lower rate limit (30 requests per minute) than other tools
* Targeting is validated before send (single targeting method, capped filters, recipient limits)
* Inputs are validated before execution, including identifiers and contact fields

### Additional controls

* Access is controlled per app and can be enabled or disabled by OneSignal
* Per-session rate limits help prevent runaway tool loops
* The MCP server is stateless and does not store customer data

## Known limitations

* One MCP configuration supports one OneSignal app (`app_id`)
* Sessions expire after inactivity and automatically re-establish on the next request
* During open beta, app access may require enablement before non-utility tools are available

## FAQ

### What AI clients can I use with OneSignal MCP Server?

You can use Claude Desktop, Claude.ai, Claude Code, OpenAI Codex, GitHub Copilot in VS Code, Cursor, and any other MCP-compatible client that supports remote Streamable HTTP servers.

### Does OneSignal MCP Server cost extra?

The MCP server is free. MCP tool calls still count against your normal OneSignal API usage limits, and your AI client may have separate usage costs.

### Why does my `Key ID` not work as `api_key`?

`Key ID` is an identifier, not the secret API key value. MCP setup requires the REST API key value that is shown one time when the key is created. If you no longer have that value, create a new API key and use that key value in your MCP configuration.

### Can AI send notifications without my approval?

No. `send_message` is flagged as a high-impact action, and compatible MCP clients ask for confirmation before running it.

### Is customer data stored by the MCP server?

No. OneSignal MCP Server is stateless and does not store your customer data.

### How do I use MCP with multiple OneSignal apps?

Create one MCP server configuration per app. Each configuration uses its own `app_id` and `api_key`.


# MotherDuck
Source: https://documentation.onesignal.com/docs/en/motherduck

Sync custom events from MotherDuck to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + MotherDuck integration enables automatic syncing of custom events from your MotherDuck databases to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

MotherDuck is a DuckDB-in-the-cloud service that provides fast OLAP (Online Analytical Processing) capabilities with the simplicity of SQL.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### MotherDuck

* **MotherDuck account** with database access
* **Service token** for authentication
* **Database** containing event data
* **Tables or views** with structured event information

***

## Setup

<Steps>
  <Step title="Create MotherDuck service token">
    Generate an access token for OneSignal to connect to MotherDuck:

    1. Log in to the MotherDuck Web UI at `app.motherduck.com`
    2. Click your profile in the top-left corner
    3. Navigate to **Settings** > **General** > **Access Tokens**
    4. Click **Create Token**
    5. Set expiration date (or leave unlimited)
    6. Copy the generated service token
  </Step>

  <Step title="Prepare your event data">
    Ensure your MotherDuck database contains properly structured event tables:

    ```sql theme={null}
    -- Example event table structure
    CREATE TABLE user_events (
        event_name VARCHAR,
        user_id VARCHAR,
        event_timestamp TIMESTAMP,
        event_properties JSON,
        session_id VARCHAR
    );
    ```
  </Step>

  <Step title="Connect to OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **MotherDuck** and provide:

    * **Service Token:** Token from Step 1
    * **Database Name:** Your MotherDuck database name
    * **Connection String:** `md:your_database_name`
  </Step>

  <Step title="Configure data sync">
    Select the tables or write custom SQL queries to define which event data to sync:

    ```sql theme={null}
    SELECT
        event_name,
        user_id,
        event_timestamp,
        event_properties
    FROM user_events
    WHERE event_timestamp >= CURRENT_DATE - INTERVAL 7 DAYS
    ```
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Query

```sql theme={null}
-- Optimized event query for OneSignal sync
SELECT
    event_name,
    user_id,
    event_timestamp,
    {
        'source': 'motherduck',
        'session_id': session_id,
        'device_type': device_type,
        'value': event_value
    }::JSON as event_properties
FROM analytics.user_events
WHERE event_timestamp >= CURRENT_TIMESTAMP - INTERVAL 1 DAY
ORDER BY event_timestamp DESC
```

***

## Processing Modes

### Table Mode

Sync entire tables directly from your MotherDuck database. OneSignal will automatically map columns to event fields.

### SQL Query Mode

Write custom DuckDB SQL queries to transform and filter your event data:

```sql theme={null}
-- Advanced event aggregation
SELECT
    'daily_summary' as event_name,
    user_id,
    DATE_TRUNC('day', event_timestamp) as event_timestamp,
    {
        'total_events': COUNT(*),
        'unique_sessions': COUNT(DISTINCT session_id),
        'last_activity': MAX(event_timestamp)
    }::JSON as event_properties
FROM user_events
WHERE event_timestamp >= CURRENT_DATE - INTERVAL 7 DAYS
GROUP BY user_id, DATE_TRUNC('day', event_timestamp)
```

***

## Limitations

* Query complexity affects sync performance
* Large result sets may impact sync speed
* JSON parsing requires proper column typing

***

## FAQ

### How do I optimize query performance in MotherDuck?

Use DuckDB's columnar storage advantages by selecting only needed columns and applying filters early in your queries.

### Can I sync from multiple MotherDuck databases?

Yes, you can create separate integrations for each MotherDuck database in your account.

***


# MySQL
Source: https://documentation.onesignal.com/docs/en/mysql

Sync custom events from MySQL to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + MySQL integration enables syncing of custom events from your MySQL database to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

MySQL is a widely-used open-source relational database management system, ideal for storing structured event data that can power personalized messaging campaigns.

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### MySQL

* **MySQL Community 5.7** or later, or recent versions of **MariaDB**
* **Event tables** containing structured behavioral data
* **Network connectivity** from OneSignal to your MySQL instance
* **TLS v1.2** or greater supported

***

## Setup

<Steps>
  <Step title="Create dedicated user for OneSignal">
    Create a dedicated user account with read-only permissions:

    ```sql theme={null}
    -- Create census user with ability to sign in with a password
    CREATE USER CENSUS IDENTIFIED BY '<strong, unique password>';

    -- Grant read-only access to your event schema
    GRANT SELECT ON <your_schema>.* TO CENSUS;
    ```

    <Info>
      If you have multiple schemas that contain event data, repeat the `GRANT SELECT` statement for each schema.
    </Info>
  </Step>

  <Step title="Configure OneSignal connection">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **MySQL** and provide your connection details:

    * **Host:** Your MySQL server hostname
    * **Port:** MySQL port (typically 3306)
    * **Database:** Database name containing your event tables
    * **Username:** `CENSUS`
    * **Password:** The password you created above
  </Step>

  <Step title="Test connection">
    Click **Test Connection** to verify OneSignal can successfully connect to your MySQL database and access your event tables.
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Table Schema

```sql theme={null}
CREATE TABLE user_events (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    event_name VARCHAR(100) NOT NULL,
    user_id VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    event_data JSON,
    session_id VARCHAR(255),
    device_type VARCHAR(50)
);
```

### Table Mode

Select your event table directly and OneSignal will sync all rows as individual events.

### SQL Query Mode

Write custom SQL queries to transform your event data:

```sql theme={null}
-- Example: Recent high-value events
SELECT
    event_name,
    user_id,
    created_at as timestamp,
    event_data as payload
FROM user_events
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)
    AND JSON_EXTRACT(event_data, '$.value') > 100
ORDER BY created_at DESC;
```

***

## Advanced Network Configuration

OneSignal can successfully connect to MySQL instances using advanced networking controls including region constraints, IP address allow lists, or SSH Tunneling.

OneSignal supports MySQL with TLS versions 1.2 and greater for secure connections.

***

## FAQ

### Which MySQL versions are supported?

OneSignal supports MySQL Community 5.7 or later, as well as recent versions of MariaDB.

### Can I connect to MySQL in a private network?

Yes, OneSignal supports SSH tunneling and IP allow lists for connecting to MySQL instances in private networks or behind firewalls.

***


# PostgreSQL
Source: https://documentation.onesignal.com/docs/en/postgresql

Sync custom events from PostgreSQL to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + PostgreSQL integration enables syncing of custom events from your PostgreSQL database to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### PostgreSQL

* **PostgreSQL 9.6+** or compatible database
* **Database user** with appropriate permissions
* **Network access** from OneSignal to your PostgreSQL instance
* **Event tables** containing structured behavioral data

<Warning>
  We **strongly recommend against** connecting OneSignal to a production PostgreSQL database. Event sync queries are analytical in nature and may impact production performance. Use with databases set up for analytic workloads only.
</Warning>

***

## Setup

<Steps>
  <Step title="Create dedicated user for OneSignal">
    Create a dedicated user account with appropriate permissions:

    ```sql theme={null}
    -- Create OneSignal user with strong password
    CREATE USER CENSUS WITH PASSWORD '<strong-unique-password>';

    -- Create private bookkeeping schema for sync state (skip if read-only mode)
    CREATE SCHEMA CENSUS;

    -- Grant full access to bookkeeping schema (skip if read-only mode)
    GRANT ALL ON SCHEMA CENSUS TO CENSUS;

    -- Ensure access to existing objects in bookkeeping schema (skip if read-only mode)
    GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA CENSUS TO CENSUS;
    ```
  </Step>

  <Step title="Grant permissions to event data">
    Provide read access to schemas containing your event data:

    ```sql theme={null}
    -- Grant schema access (repeat for each schema with event data)
    GRANT USAGE ON SCHEMA "<your_schema>" TO CENSUS;

    -- Grant read access to existing tables
    GRANT SELECT ON ALL TABLES IN SCHEMA "<your_schema>" TO CENSUS;

    -- Grant read access to future tables
    ALTER DEFAULT PRIVILEGES IN SCHEMA "<your_schema>" GRANT SELECT ON TABLES TO CENSUS;

    -- Grant execute permissions on functions
    GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA "<your_schema>" TO CENSUS;
    ALTER DEFAULT PRIVILEGES IN SCHEMA "<your_schema>" GRANT EXECUTE ON FUNCTIONS TO CENSUS;
    ```
  </Step>

  <Step title="Connect to OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    1. Select **PostgreSQL** from the list
    2. Enter your connection details:
       * **Host:** Your PostgreSQL server hostname
       * **Port:** Usually 5432
       * **Database:** Your database name
       * **Username:** `CENSUS`
       * **Password:** The password you created
    3. Test the connection
    4. Configure which tables contain your event data
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Table Schema

```sql theme={null}
-- Example PostgreSQL event table
CREATE TABLE analytics.user_events (
    event_id SERIAL PRIMARY KEY,
    event_name VARCHAR(100) NOT NULL,
    user_id VARCHAR(255) NOT NULL,
    event_timestamp TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    event_data JSONB,
    session_id VARCHAR(255),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
```

### SQL Query Mode

Write custom SQL queries to transform your event data:

```sql theme={null}
-- Example: Recent purchase events
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_data
FROM analytics.user_events
WHERE event_timestamp >= NOW() - INTERVAL '7 days'
    AND event_name = 'purchase'
ORDER BY event_timestamp DESC;
```

***

## Advanced Network Configuration

OneSignal can connect to PostgreSQL instances using advanced networking controls:

* **IP Allow Lists**: Add OneSignal's IP addresses to your firewall and `pg_hba.conf`
* **SSH Tunneling**: Connect through a bastion host for private networks
* **VPC Configuration**: Direct connection within cloud environments
* **TLS Encryption**: Secure connections using SSL/TLS

### SSH Tunnel Setup

For PostgreSQL instances on private networks:

1. **Create SSH user**: Set up a dedicated user on your SSH host
2. **Configure tunnel**: Enable "Use SSH Tunnel" in OneSignal integration settings
3. **Install keypair**: Add OneSignal's public key to `~/.ssh/authorized_keys`
4. **Test connection**: Verify tunnel connectivity

***

## Notes

* **Multiple Schemas**: Repeat permission grants for each schema containing event data
* **Views with Cross-Schema References**: May require additional read permissions in older PostgreSQL versions
* **Azure PostgreSQL**: Use `username@hostname` format for Azure instances
* **AWS RDS**: Use standard `username` format
* **Performance**: Consider using read replicas for large-scale event processing

***

## Limitations

* Avoid connecting to production databases due to analytical query overhead
* Complex cross-schema queries may require additional permissions
* Connection pooling recommended for high-frequency event processing

***

## FAQ

### Should I use read-only mode?

Use **read-only mode** if you prefer simpler setup and can't allow OneSignal to create tables. Use **full mode** for better performance with large event datasets.

### How do I handle multiple event schemas?

Repeat the permission grant commands for each schema containing event data. OneSignal can read from multiple schemas within a single connection.


# RevenueCat
Source: https://documentation.onesignal.com/docs/en/revenuecat

Sync in-app purchase and subscription data from RevenueCat to OneSignal for personalized messaging.

## Overview

RevenueCat helps you track in-app purchases and subscription lifecycles across platforms. With OneSignal, you can use this data to send personalized messages based on a user's subscription status.

This integration updates Tags in OneSignal automatically with their latest user info.

### Key benefits

With the RevenueCat–OneSignal integration, you can:

* Send onboarding messages to users in a free trial or who just subscribed.
* Re-engage churned users with surveys or discounts.
* Send transactional messages for purchases, billing issues, or renewals.

With accurate subscription data in OneSignal, your campaigns will be smarter and more effective.

***

## Requirements

* [RevenueCat account](https://www.revenuecat.com/docs/welcome/overview)
  * RevenueCat [*Purchases SDK*](https://www.revenuecat.com/docs/getting-started/quickstart)
  * Understand [RevenueCat-OneSignal integration](https://www.revenuecat.com/docs/integrations/third-party-integrations/onesignal)
* OneSignal account with [integrated SDK](./developers)
  * Understand [Tags](./add-user-data-tags), [Users](./users), and OneSignal [Subscriptions](./subscriptions)

***

## Setup

### Connect OneSignal to RevenueCat

1. In your RevenueCat dashboard, navigate to your project settings and choose 'OneSignal' from the Integrations menu.
2. Add your OneSignal App ID and OneSignal API key. See [Keys and IDs](./keys-and-ids) for more information.
3. Enter the tag names that RevenueCat should use, or choose the default tag names.

### Pass RevenueCat the OneSignal ID

RevenueCat uses the OneSignal user ID (OneSignal ID) to update Tags in OneSignal based on their RevenueCat user details.

<Warning>
  Setting the External ID in OneSignal is required for a stable identifier. If it changes mid-session, the OneSignal ID may also change, breaking the RevenueCat connection.
</Warning>

To pass the OneSignal ID to RevenueCat, you should:

<Steps>
  <Step title="Set the External ID in OneSignal">
    Set the External ID in OneSignal to your main user ID. This can be done with the SDK `login` method.

    * [Mobile SDK `login` method](./mobile-sdk-reference#login-external-id)
    * [Web SDK `login` method](./web-sdk-reference#login-external-id)
  </Step>

  <Step title="Get the OneSignal ID">
    We recommend using the user state observer method to get the OneSignal ID, but we also provide getter methods:

    * User state observers:
      * [Mobile SDK `addObserver` user state](./mobile-sdk-reference#addobserver-user-state)
      * [Web SDK `addObserver` user state](./web-sdk-reference#addeventlistener-user-state)
    * Getter methods:
      * [Mobile SDK `getOneSignalId` method](./mobile-sdk-reference#getonesignalid)
      * [Web SDK `OneSignalId` property](./web-sdk-reference#onesignal-user-onesignalid)
  </Step>

  <Step title="Pass the OneSignal ID to RevenueCat">
    Pass the OneSignal ID to RevenueCat.

    * RevenueCat property: `$onesignalUserId`
    * RevenueCat helper method: `setOneSignalUserID()` (recommended)
  </Step>
</Steps>

### Send RevenueCat events to OneSignal

Users that have a mapped OneSignal ID to RevenueCat will have their tags updated automatically.

#### Testing the integration

<Steps>
  <Step title="Make a sandbox purchase">
    Simulate a new user installing your app, and go through your app flow to complete a sandbox purchase.

    <Warning>
      Make sure the OneSignal ID is set in RevenueCat.
    </Warning>
  </Step>

  <Step title="Check that the required device data is collected">
    In RevenueCat, navigate to the Customer View for the test user that just made a purchase. Make sure that all of the required data is listed as attributes for the user.
  </Step>

  <Step title="Check that the OneSignal event delivered successfully">
    While still on the Customer View, click into the test purchase event in the Customer History and make sure that the OneSignal integration event exists and was delivered successfully.
  </Step>

  <Step title="Check that the OneSignal tags are updated">
    In OneSignal, navigate to **Audience > Users** and search for the OneSignal ID. You should see the tags that were updated by RevenueCat.
  </Step>
</Steps>

<Check>
  Integration complete! You should now see the tags in OneSignal update automatically as users make purchases or update their subscription status.
</Check>

***

## RevenueCat event tags

For every auto-renewing subscription event in RevenueCat, the following tags get added or updated on the user in OneSignal. By leaving the tag blank in the RevenueCat dashboard, you can choose to not send any value for specific tag(s).

| Tag                          | Description                                                                                                                                                |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app_user_id`                | The RevenueCat App User Id that triggered the event                                                                                                        |
| `period_type`                | The latest period type for the purchase or renewal. Either: `TRIAL` (for free trials), `INTRO` (or introductory pricing), `NORMAL` (standard subscription) |
| `purchased_at`               | Epoch time in seconds of the latest user purchase or renewal                                                                                               |
| `expiration_at`              | Epoch time in seconds of the latest user expiration date                                                                                                   |
| `store`                      | Either `APP_STORE`, `PLAY_STORE`, or `STRIPE`                                                                                                              |
| `environment`                | Either `SANDBOX` or `PRODUCTION`                                                                                                                           |
| `last_event_type`            | The latest event type from the user. Either: `INITIAL_PURCHASE`, `TRIAL_STARTED`, `TRIAL_CONVERTED`, `TRIAL_CANCELLED`, `RENEWAL`, `CANCELLATION`          |
| `product_id`                 | The latest user product identifier that the user has purchased or renewed                                                                                  |
| `entitlement_ids`            | Comma separated string of RevenueCat Entitlement identifiers that the user unlocked                                                                        |
| `active_subscription`        | The value will be set to `true` on any purchase/renewal event, and `false` on `EXPIRATION`                                                                 |
| `subscription_status`        | See Subscription Status Attribute below                                                                                                                    |
| `grace_period_expiration_at` | If a billing issue occurs, we will send the date of the grace period expiration.                                                                           |

<Note>
  * Auto-renewing subscriptions only
  * RevenueCat only updates Tags in OneSignal in response to auto-renewing subscription events.
</Note>

### RevenueCat event examples

Provided JSON examples show the tags sent to OneSignal based on [RevenueCat Events](https://www.revenuecat.com/docs/integrations/third-party-integrations/onesignal#events).

The event is saved as the `last_event_type` tag.

<Tabs>
  <Tab title="initial_purchase">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
            "period_type": "NORMAL",
            "purchased_at": 1600016247,
            "expiration_at": 1602608247,
            "store": "APP_STORE",
            "environment": "PRODUCTION",
            "last_event_type": "initial_purchase",
            "last_event_at": 1600016250,
            "product_id": "monthly_sub",
            "entitlement_ids": "Pro"
        }
    }
    ```
  </Tab>

  <Tab title="trial_started">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
            "period_type": "TRIAL",
            "purchased_at": 1600031584,
            "expiration_at": 1600290784,
            "store": "APP_STORE",
            "environment": "PRODUCTION",
            "last_event_type": "trial_started",
            "last_event_at": 1600031586,
            "product_id": "three_month_sub_trial",
            "entitlement_ids": "Pro"
        }
    }
    ```
  </Tab>

  <Tab title="trial_converted">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
            "period_type": "NORMAL",
            "purchased_at": 1602136340,
            "expiration_at": 1602741140,
            "store": "APP_STORE",
            "environment": "PRODUCTION",
            "last_event_type": "trial_converted",
            "last_event_at": 1602114850,
            "product_id": "weekly_sub_trial",
            "entitlement_ids": null
        }
    }
    ```
  </Tab>

  <Tab title="trial_cancelled">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
            "period_type": "TRIAL",
            "purchased_at": 1602051920,
            "expiration_at": 1602311120,
            "store": "APP_STORE",
            "environment": "PRODUCTION",
            "last_event_type": "trial_cancelled",
            "last_event_at": 1602129368,
            "product_id": "weekly_sub_trial",
            "entitlement_ids": null
        }
    }
    ```
  </Tab>

  <Tab title="renewal">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
            "period_type": "NORMAL",
            "purchased_at": 1602125078,
            "expiration_at": 1604807078,
            "store": "APP_STORE",
            "environment": "PRODUCTION",
            "last_event_type": "renewal",
            "last_event_at": 1602122793,
            "product_id": "monthly_sub",
            "entitlement_ids": "Pro"
        }
    }
    ```
  </Tab>

  <Tab title="cancellation">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
            "period_type": "NORMAL",
            "purchased_at": 1602086660,
            "expiration_at": 1602691460,
            "store": "APP_STORE",
            "environment": "PRODUCTION",
            "last_event_type": "cancellation",
            "last_event_at": 1602118600,
            "product_id": "weekly_sub",
            "entitlement_ids": null
        }
    }
    ```
  </Tab>

  <Tab title="uncancellation">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
            "period_type": "TRIAL",
            "purchased_at": 1663445025,
            "expiration_at": 1664049825,
            "store": "APP_STORE",
            "environment": "PRODUCTION",
            "last_event_type": "uncancellation",
            "last_event_at": 1663969096,
            "product_id": "annual_sub",
            "entitlement_ids": "Premium"
        }
    }
    ```
  </Tab>

  <Tab title="non_subscription_purchase">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
            "purchased_at": 1602086660,
            "store": "APP_STORE",
            "environment": "PRODUCTION",
            "last_event_type": "non_renewing_purchase",
            "last_event_at": 1602118600,
            "product_id": "one_time_purchase_product",
            "entitlement_ids": null
        }
    }
    ```
  </Tab>

  <Tab title="subscription_paused">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
            "period_type": "NORMAL",
            "purchased_at": 1602086660,
            "expiration_at": 1602691460,
            "store": "PLAY_STORE",
            "environment": "PRODUCTION",
            "last_event_type": "subscription_paused",
            "last_event_at": 1602118600,
            "product_id": "weekly_sub",
            "auto_resume_at": 1602119600,
            "entitlement_ids": null
        }
    }
    ```
  </Tab>

  <Tab title="expiration">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "period_type": "NORMAL",
            "purchased_at": 1652374230,
            "expiration_at": 1652979030,
            "last_event_type": "expiration",
            "last_event_at": 1652988735
        }
    }
    ```
  </Tab>

  <Tab title="billing_issue">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
            "period_type": "TRIAL",
            "purchased_at": 1652383957,
            "expiration_at": 1654371157,
            "store": "APP_STORE",
            "environment": "PRODUCTION",
            "last_event_type": "billing_issue",
            "last_event_at": 1652988776,
            "product_id": "annual_sub",
            "entitlement_ids": "Premium"
        }
    }
    ```
  </Tab>

  <Tab title="product_change">
    ```json theme={null}
    {
        "app_id": "12345678-1234-1234-1234-123456789012",
        "tags": {
            "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
            "period_type": "NORMAL",
            "purchased_at": 1602086660,
            "expiration_at": 1602691460,
            "store": "APP_STORE",
            "environment": "PRODUCTION",
            "last_event_type": "product_change",
            "last_event_at": 1602118600,
            "product_id": "weekly_sub",
            "new_product_id": "monthly_sub",
            "entitlement_ids": null
        }
    }
    ```
  </Tab>
</Tabs>

### `subscription_status` tag

Whenever RevenueCat sends an event to OneSignal, a `subscription_status` tag is added or updated with any applicable changes, using one of the following values:

| Status               | Description                                                                                                           |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| active               | The customer has an active, paid subscription which is set to renew at their next renewal date.                       |
| intro                | The customer has an active, paid subscription through a paid introductory offer.                                      |
| cancelled            | The customer has a paid subscription which is set to expire at their next renewal date.                               |
| grace\_period        | The customer has a paid subscription which has entered a grace period after failing to renew successfully.            |
| trial                | The customer is in a trial period which is set to convert to paid at the end of their trial period.                   |
| cancelled\_trial     | The customer is in a trial period which is set to expire at the end of their trial period.                            |
| grace\_period\_trial | The customer was in a trial period and has now entered a grace period after failing to renew successfully.            |
| expired              | The customer's subscription has expired.                                                                              |
| promotional          | The customer has access to an entitlement through a RevenueCat                                                        |
| expired\_promotional | The customer previously had access to an entitlement through a RevenueCat Granted Entitlement that has since expired. |
| paused               | The customer has a paid subscription which has been paused and is set to resume at some future date.                  |

For customers with multiple active subscriptions, this attribute will represent the status of only the subscription for which the most recent event occurred.

***

## FAQ

### How do I know if the integration is working?

In OneSignal, navigate to **Audience > Users** and search for the OneSignal ID. You should see the tags that were updated by RevenueCat.

You can also go to **Audience > Segments** and create a segment that filters for the tags you have set via RevenueCat.

### How many tags can I set?

There is no limit to the amount of tags you can set in OneSignal, but there is a limit to how many tags each user can have at a given time.

See our [Pricing page](https://onesignal.com/pricing) for more information.

***


# Amazon S3
Source: https://documentation.onesignal.com/docs/en/s3

Sync custom events from Amazon S3 CSV files to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Amazon S3 integration enables automatic syncing of custom events from CSV files stored in your S3 bucket directly to OneSignal's Custom Events API. This allows you to trigger automated Journeys and personalized messaging campaigns based on real user behavior stored in your data warehouse.

You can sync events like purchases, product views, subscription changes, or any custom user actions to automatically trigger onboarding sequences, re-engagement campaigns, transactional messages, and targeted promotions across push notifications, email, in-app messages, and SMS.

***

## Requirements

### OneSignal

* **Custom Events** feature enabled

### Amazon S3

* **AWS Account** with S3 bucket access
* **IAM permissions** to create roles and policies
* **CSV files** with event data formatted according to OneSignal requirements
* **UTF-8 encoded** comma-delimited files with `.csv` extension

***

## Setup

### Prepare your event CSV files

Your S3 bucket must contain properly formatted CSV files with event data that OneSignal can process:

**File Format Requirements:**

* Uncompressed, UTF-8 encoded, comma delimited CSV with `.csv` file extension
* Include a header row (OneSignal will use headers as event field names)
* Represent null values with the string `#N/A`
* Values containing commas should be wrapped in double quotes
* Values containing double quotes should be escaped with a second double quote

**File Structure:**
OneSignal treats each **folder path as a unique data source** and considers the file name to be a version of the data within that path. When processing events, OneSignal will always select the newest data in the selected folder path based on timestamp.

When updating event data in S3, you can either replace the existing file or add a newer version. OneSignal will process the new events and send them to the Custom Events API.

### Create IAM role for OneSignal

OneSignal uses role-based authentication to connect to your S3 bucket, following AWS security best practices.

<Steps>
  <Step title="Create the IAM role">
    Create an IAM role in your AWS account that provides read-only access to your S3 bucket for OneSignal's AWS Account ID (`341876425553`):

    ```bash theme={null}
    aws iam create-role \
      --role-name OneSignalS3DataImport \
      --assume-role-policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
          "Action": "sts:AssumeRole"
        }]
      }'
    ```

    <Info>
      Save the returned Role ARN as you'll need it for the OneSignal configuration.
    </Info>
  </Step>

  <Step title="Grant S3 permissions">
    Grant your newly-created role read-only access to your S3 bucket:

    ```bash theme={null}
    aws iam put-role-policy \
      --role-name OneSignalS3DataImport \
      --policy-name OneSignalS3Access \
      --policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Action": [
            "s3:ListBucket",
            "s3:GetObject",
            "s3:GetObjectVersion",
            "s3:GetBucketLocation"
          ],
          "Resource": [
            "arn:aws:s3:::YOUR_BUCKET_NAME",
            "arn:aws:s3:::YOUR_BUCKET_NAME/*"
          ]
        }]
      }'
    ```

    <Warning>
      Replace `YOUR_BUCKET_NAME` with your actual S3 bucket name.
    </Warning>
  </Step>
</Steps>

### Configure OneSignal S3 connection

<Steps>
  <Step title="Navigate to Data Sources">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.
  </Step>

  <Step title="Select Amazon S3">
    Choose **Amazon S3** from the list of available integrations.
  </Step>

  <Step title="Enter connection details">
    Provide the following information:

    * **Region:** Your S3 bucket region
    * **Bucket Name:** Your S3 bucket name
    * **Role ARN:** The IAM role ARN from Step 1
    * **Prefix:** The folder path containing your event CSV files (optional)
  </Step>

  <Step title="Complete the security handshake">
    OneSignal will generate a unique external ID and display it on the next screen. Update your IAM role to require this external ID:

    ```bash theme={null}
    aws iam update-assume-role-policy \
      --role-name OneSignalS3DataImport \
      --policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
          "Action": "sts:AssumeRole",
          "Condition": {"StringEquals": {"sts:ExternalId": "GENERATED_EXTERNAL_ID"}}
        }]
      }'
    ```

    <Info>
      Replace `GENERATED_EXTERNAL_ID` with the external ID shown in the OneSignal dashboard.
    </Info>
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** in OneSignal to verify the setup is working correctly.
  </Step>
</Steps>

***

## CSV Processing Modes

OneSignal supports two modes when reading event CSV files from your S3 bucket:

### Most Recent (Default)

OneSignal processes only the most recent file in the configured S3 prefix and folder group. The single file is interpreted as the complete set of events to process. This mode works well when:

* A single file contains all events for a time period
* New versions of files are added over time with updated event data
* You want to process a complete batch of events at once

### Merge All

OneSignal takes every file in the configured S3 prefix and folder group and merges them into a single dataset before processing events. This mode is useful when:

* Your event data has been split into multiple files
* You want to process events from multiple sources
* Files are being added incrementally with new events

<Warning>
  In Merge All mode, all CSV files must have the exact same column names and order.
</Warning>

***

## Event Data Mapping

Once connected, you'll need to map your CSV columns to OneSignal custom event fields:

<Steps>
  <Step title="Review detected fields">
    OneSignal will automatically detect columns from your event CSV files and suggest mappings.
  </Step>

  <Step title="Map required event fields">
    Map the required fields for custom events:

    * **Event Name** (required): The name/type of the event
    * **External ID** (required): External User ID
    * **Event Timestamp** (optional): When the event occurred. Otherwise, assumed to be now.
  </Step>

  <Step title="Configure sync settings">
    Set your event processing frequency and delivery preferences.
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

***

## Limitations

* **SQL Queries:** S3 sources do not support SQL queries or advanced transformations on event data
* **File Size:** Individual CSV files should not exceed 1GB
* **Update Frequency:** Minimum sync interval is 15 minutes
* **File Types:** Only CSV files are supported (no JSON, Parquet, etc.)

***

## FAQ

### What happens if my CSV file has formatting errors?

OneSignal will skip malformed rows and provide detailed error logs in the integrations dashboard. Common issues include missing required columns, invalid timestamp formats, and inconsistent column counts.

### How often does OneSignal check for new files?

OneSignal checks your S3 bucket based on your configured sync frequency, with a minimum interval of 15 minutes.

***

## Need help?

Contact our support team at `support@onesignal.com` or use the in-app chat for assistance with your S3 integration setup.


# Segment (Twilio)
Source: https://documentation.onesignal.com/docs/en/segment-onesignal-integration

Integrate OneSignal with Twilio Segment for user data and messaging events.

<Frame>
  <img />
</Frame>

## Overview

The OneSignal + Segment integration lets you:

* Send user traits and events from Segment to OneSignal to enrich user profiles, power segmentation, and trigger messaging.
* Send message delivery and engagement events from OneSignal to Segment for centralized analytics and data warehousing.

This bidirectional setup supports all major OneSignal channels: Push, In-App, Email, and SMS.

***

## Requirements

* A Growth, Professional or Enterprise [OneSignal Account](https://onesignal.com/pricing).
* Segment Admin Permissions
* The OneSignal [Mobile SDK](./mobile-sdk-setup) and/or [Web SDK](./web-push-setup) from which you want to send data. [Email](./email-setup) or [SMS](./sms-setup) only integrations do not require the SDK.
* The OneSignal Property: [External ID](./users) which maps to the Segment.com `userId`.

***

## Setup

### 1. Set up OneSignal

Use an existing app or create a new one in the OneSignal dashboard. Then set up your preferred channels:

* [Web Push Setup](./web-push-setup)
* [Mobile Push Setup](./mobile-sdk-setup)
* [SMS Setup](./sms-setup)
* [Email Setup](./email-setup)

### 2. Connect Segment to OneSignal

Within OneSignal Dashboard, navigate to **Data > Integrations** and click **Active** within Segment.com card. Then continue with the setup options.

#### Data in

"Data In" to OneSignal allows you to send [OneSignal segments](./segmentation), [tags](./add-user-data-tags), and [custom events](./custom-events) from your Segment.com account to OneSignal. Click **Authenticate** under the *Data In* section of the Segment.com setting page in the OneSignal Dashboard.

<Warning>
  Once enabled to track custom events, the Segment.com integration will send both Tags and Events, so you will not need to update any existing templates that reference Tags.
</Warning>

<Frame>
  <img />
</Frame>

Once you click Authenticate, a Segment.com webpage will open and you'll be prompted to sign in to your Segment.com account. You'll then be prompted to configure a new data destination from your Segment.com account.

<Frame>
  <img />
</Frame>

#### Data out

Enabling "Data Out" to Segment.com syncs message events generated back to your Segment.com account. These message events are generated from sending messages to your users on the OneSignal platform. More details on what kind of events can be generated, and the properties they are sent with can be found [below](./segment-onesignal-integration#message-events).

First, you need to add OneSignal as a source from your Segment.com account. You can do that by navigating to the [OneSignal Source listing ](https://segment.com/docs/connections/sources/catalog/cloud-apps/onesignal/)in the Segment Connections Catalogue.

From there, you can add your Segment.com API token on the OneSignal Dashboard. Please navigate **Data > Integrations > Segment** in the OneSignal Dashboard to add the Segment API key.

<Frame>
  <img />
</Frame>

After you set up the API key, please make sure to check your Data Policy settings in Segment.com to determine if you need to send events to Segment's EU Residency Endpoint.

Once all of those settings are done, you can then select which events you want to sync over to your Segment Account depending on which channels you utilize with OneSigna..

### 3. Add OneSignal destination in Segment

Within **Segment.com Dashboard > Destinations** you should see **OneSignal**. If not, add OneSignal as a new destination.

Enable the OneSignal Destination, you should also see your OneSignal API Key and App ID already

<Frame>
  <img />
</Frame>

If the API key and App Id are not set, navigate to the [OneSignal dashboard](https://app.onesignal.com/apps/), select the App, and go to the **Settings > Keys & IDs**. Copy-Paste the "App ID" and the "API key" into Segment.com.

#### Multiple Segment.com Sources

If you have multiple sources, you can utilize [Segment's **Personas > Spaces** feature ](https://segment.com/docs/personas/#personas-spaces)to bind multiple sources to a destination.

### 4. Send data from Segment to OneSignal

OneSignal stores channel-level records: Push/IAM, Email, and SMS. These records must already be created in OneSignal and you must also set the [External ID](./users) alias in OneSignal to match the `userID` field sent by Segment.com.

<Warning>
  Records that don't have a **Segment User ID \<--> OneSignal External ID** mapping will be dropped.
</Warning>

## User traits or properties

You can aggregate data across every customer touchpoint in Segment and then send these user properties in real-time to OneSignal as [Tags](./add-user-data-tags).

**Note**: OneSignal can not accept nested objects or arrays as user properties.

[Identify](https://segment.com/docs/connections/spec/identify) - User traits or properties sent using *Segment's Identify call* are stored as Tags on OneSignal. For example:

<Frame>
  <img />
</Frame>

[Track](https://segment.com/docs/connections/spec/track/) - For events and associated properties sent using *Segment's Track call*, OneSignal will store all the *event properties* as Tags, but *drop* the *event name* while storing the tags. If you want to keep the *event names* in the Tags, you can append the event name to the properties before sending them to OneSignal. For example:

<CodeGroup>
  ```javascript track example theme={null}
  let timestampInSeconds = Int(NSDate().timeIntervalSince1970).toString()//convert to string since Segment adds decimals to end
  //name will be dropped and only properties will be sent to OneSignal as tag "last opened: timestampInSeconds"
  analytics.track(
    name: "iOS App Last Opened",
    properties: ["last opened": timestampInSeconds]
  )
  ```
</CodeGroup>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Personas Audience and Computed Traits

[Persona Audiences](https://segment.com/docs/personas/) automatically show up as a [segment in OneSignal](./segmentation).

Computed traits are updated as [Tags](./add-user-data-tags) on the OneSignal user records.

**Audience**

<Frame>
  <img />
</Frame>

Audiences sent using Segment's [Track call](https://segment.com/docs/connections/spec/track/) will create a OneSignal segment with the *Audience Name*.

Audiences sent using Segment's [Identify call ](https://segment.com/docs/connections/spec/identify/)will

* create a OneSignal segment with the *Audience Name*
* add Tags (if there are additional properties in the Identify call) on all the matching user records.

<Frame>
  <img />
</Frame>

The Identify and Track calls are automatically sent to OneSignal whenever a user enters or exits the Audience.

**Computed Traits** Personas Computed Traits are stored as [Tags](./add-user-data-tags) on the OneSignal user records whether passed to OneSignal as an Identify call or a Track call. You can then use these Tags to manually create OneSignal segments and automate your messaging workflows.

***

## Message Events

## Event Kinds

These are the message event kinds that OneSignal sends to Segment

| MessageEvent Kind             | Event Description                                    |
| ----------------------------- | ---------------------------------------------------- |
| Push Sent                     | Push notification successfully sent                  |
| Push Received                 | Push notification successfully received              |
| Push Clicked                  | Push notification touched on device                  |
| In-App Message Displayed      | In-App Message successfully displayed on device      |
| In-App Message Clicked        | In-App Message clicked on device                     |
| In-App Message Page Displayed | In-App Message page is displayed                     |
| Email Sent                    | Email successfully sent                              |
| Email Opened                  | Email opened by recipient                            |
| Email Unsubscribed            | Email unsubscribed by recipient                      |
| Email Received                | Email received by recipient                          |
| Email Reported As Spam        | Email reported as spam by recipient                  |
| Email Bounced                 | Email returned to sender due to permanent error      |
| Email Failed                  | Could not deliver the email to the recipient's inbox |
| SMS Sent                      | SMS sent to recipient                                |
| SMS Delivered                 | SMS successfully delivered                           |
| SMS Failed                    | SMS failed to send                                   |

### Event Properties

These are the properties that are present on events sent from OneSignal to Segment.com

| PROPERTY NAME       | DESCRIPTION                                        |
| ------------------- | -------------------------------------------------- |
| `userId`            | The `external_id` associated with the message      |
| `anonymousId`       | The `subscription_id`                              |
| `messageId`         | The identifier of the discrete message             |
| `campaign_id`       | The same value as `messageId`                      |
| `message_name`      | The message name                                   |
| `message_title`     | The message title                                  |
| `message_contents`  | The message contents                               |
|                     |                                                    |
| `subscription_type` | The channel the message was sent through           |
| `template_id`       | The message template used                          |
| `subscription_id`.  | The OneSignal set device/email/sms identifier      |
| `device_type`       | The device type that received the message          |
| `language`          | The two character language code of the device      |
| `message_type`      | The type of message sent, push, in-app, email, SMS |

## FAQ

### How can we pass Subscription events?

Subscription events are not currently being sent automatically. This can be done with the OneSignal SDK Subscription Observer Methods. See [Subscription Tracking](./analytics-overview#subscription-tracking) for more details.

### Managing Segment's Reserved and Custom User Properties in OneSignal

* All the Segment's user traits are sent to OneSignal as Tags. The number of Tags allowed on OneSignal depends on your OneSignal pricing plan. Tags over the entitled number will be dropped.
* OneSignal always updates the firstName and the lastName properties for matching users. All other traits are added/updated on a first-come basis. *firstName* and *lastName* tags are stored as "first\_name" and "last\_name".
* User properties sent to OneSignal with blank/null values are removed from the OneSignal user record. This is done to make sure you are within your data tag limits.

***


# Segments
Source: https://documentation.onesignal.com/docs/en/segmentation

Create and manage dynamic user segments in OneSignal to target personalized messaging based on activity, location, tags, and more.

A **segment** is a dynamic group of users defined by filters on Subscription attributes, behavior, and custom data. OneSignal segments update automatically as users interact with your app or site — no extra tracking required. Use segments to target messages, exclude audiences, and trigger Journeys.

<Warning>
  Push notifications, emails, and SMS messages are only sent to opted-in (subscribed) [Subscriptions](./subscriptions). The segment editor shows both subscribed and unsubscribed counts for transparency, but only subscribed Subscriptions receive messages when you target a segment. In-App Messages are displayed to all mobile Subscriptions, regardless of status.

  When used in Journeys, all Subscriptions in a segment, regardless of status, are evaluated to their respective [users](./users) and those users are entered into the Journey.
</Warning>

## Segment types

The OneSignal platform supports two main categories of segments:

### Subscription-based segments

Subscription-based segments are built using filters on Subscription attributes, such as device type, language, or app version.

### User-based segments

User-based segments are built using filters on user-level attributes rather than individual Subscriptions. Currently, these segments support filters on [message events](./message-events) and [Custom Events](./custom-events). Examples include:

* When a user last opened an email, SMS, or push notification sent via OneSignal.
* Specific Custom Events tracked in your app or website.

A user-based segment includes all users who meet the criteria and automatically makes all of their Subscriptions eligible to be targeted, enabling richer audience definitions that can reach any of the user's devices.

## Creating segments

Segments can be created in the dashboard, via the API, or by uploading a CSV. Target your audience by including and excluding segments when sending messages or building Journeys.

<Columns>
  <Card title="Dashboard" icon="display">
    Create and manage segments from **Audience > Segments**.
  </Card>

  <Card title="API" icon="code" href="/reference/create-segments">
    Create segments programmatically using the Create Segment API.
  </Card>

  <Card title="CSV Import" icon="file-csv" href="./import">
    Bulk-import Subscriptions and Tags via CSV, then build segments that match them.
  </Card>
</Columns>

#### Create a segment in the dashboard

<Steps>
  <Step title="Go to Audience > Segments">
    Navigate to the Segments page in the dashboard.

    <Frame>
      <img alt="Segments page showing list of segments" />
    </Frame>
  </Step>

  <Step title="Click New Segment">
    Opens the segment creation interface.

    <Frame>
      <img alt="Segment creation interface showing filter options and segment name field" />
    </Frame>
  </Step>

  <Step title="Add filters, name the segment, and click Create Segment">
    * Add filters to define your audience criteria.
    * Name the segment.
    * Enter a **Description** (optional). Click **Add description** below the segment name (up to 255 characters).
    * Click **Create Segment**.

    <Frame>
      <img alt="Segment creation interface with filters added and a segment name entered" />
    </Frame>
  </Step>
</Steps>

### Segment logic: AND vs OR

Use **AND** to combine filters that all must match. Use **OR** to match any of multiple conditions.

<Tabs>
  <Tab title="AND example">
    Create a segment of users who:

    * Have been active within the last 30 days
    * Have at least 3 total sessions

    <Frame>
      <img alt="Segment with AND filters for users active within 30 days with at least 3 sessions" />
    </Frame>
  </Tab>

  <Tab title="OR example">
    Create a segment of users who:

    * Have not returned in more than 7 days
    * Have new Subscriptions created in the last 3 days

    <Frame>
      <img alt="Segment with OR filter combining inactive users and new Subscriptions" />
    </Frame>
  </Tab>
</Tabs>

## Filters

Filters define which Subscriptions belong to a segment. You can combine multiple filters using **AND** or **OR** logic. If no filters are selected, the segment defaults to every user of your app.

| Filter             | Description                                                                                                                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **First session**  | Date/time of user creation.                                                                                                                                                                                     |
| **Last session**   | Last time Subscription opened the app or site.                                                                                                                                                                  |
| **Session count**  | Number of times Subscription opened the app or visited the site.                                                                                                                                                |
| **Usage duration** | Total seconds the Subscription had your app/site open.                                                                                                                                                          |
| **Language**       | User's preferred language (based on device/browser). See [multi-language support](./multi-language-messaging).                                                                                                  |
| **App version**    | Pulled from Android `versionCode` or iOS `CFBundleShortVersionString`. Combine with **Device type** to filter by different app versions per platform. See [Target outdated app versions](./app-version-update). |
| **Device type**    | iOS, Android, Web Push (browser), Email, etc. Select multiple device types in one filter with "is any of", or exclude them with "is not any of".                                                                |
| **User tag**       | Custom Tags you set via the SDK or API. See [Add Tags](./add-user-data-tags).                                                                                                                                   |
| **Location**       | Filter by radius from coordinates (lat/long). Requires at least 1 meter and up to 2 decimal places of precision. See [location permission](./mobile-sdk-reference#location).                                    |
| **Country**        | Based on last IP geolocation (ISO 3166-2 code).                                                                                                                                                                 |
| **Test users**     | Users marked as [Test Users](./test-users).                                                                                                                                                                     |
| **Message event**  | Filter by [message event](./message-events) (e.g., "clicked", "delivered", "failed"). See [Message event filters](#message-event-filters).                                                                      |
| **Custom event**   | Filter by [custom event](./custom-events) (e.g., "purchase", "user login"). See [Custom event filters](#custom-event-filters).                                                                                  |

### Message event filters

Message event filters target users based on their interaction with one of your messaging channels within a certain window. See [Message events](./message-events) for the full event catalog and conceptual reference.

<Frame>
  <img alt="Message event filter options showing channel, action, and time window selectors" />
</Frame>

First select the messaging channel you want to filter on, then specify the action to track and whether the user has or has not performed that action.

You can specify a minimum, maximum, or exact number of times the user must have performed the action, as well as a time window ranging from the last 24 hours to the last 90 days. Use the `between` option to define a custom start and end range (in days ago).

#### Trackable interactions by channel

| Channel | Trackable interactions                                                    |
| ------- | ------------------------------------------------------------------------- |
| Push    | Delivered, Confirmed Receipt, Clicked, Failed                             |
| SMS     | Delivered, Read, Failed                                                   |
| Email   | Delivered, Opened, Clicked, Bounced, Failed, Suppressed, Reported as spam |
| In-App  | Impression, Clicked                                                       |

<Warning>
  Segments created with message event filters are user-based.

  They cannot be combined with subscription-based segments for inclusion or exclusion when sending messages outside of Journeys.

  Within [Journeys](./journeys-overview), which is user-based, you can combine event-based and subscription-based segments for more flexible targeting.
</Warning>

#### Message event retention

The amount of time message event data is retained depends on your plan. The dashboard time window selector shows up to 90 days, but data beyond your plan's retention period will not return results.

<Card title="Retention by plan" icon="clock" href="./message-events#retention">
  Free, Growth, Pro, and Enterprise retention windows for message event data.
</Card>

### Custom event filters

[Custom Event](./custom-events) filters let you target users based on meaningful actions they have taken in your app, website, or external systems.

<Note>
  Custom event filters are currently in **Early Access**.

  To request access, contact `support@onesignal.com` with your company name, OneSignal Organization ID, and App ID(s).
</Note>

<Frame>
  <img alt="Custom event filter options showing event type and property selectors" />
</Frame>

Start by selecting:

* The event name you want to filter on.
* Whether the user `has` or `has not` performed that action.
* The minimum, maximum, or exact number of times the action must be performed.
* A time window during which the action must (or must not) occur — choose a preset range or define a custom window using the `between` option (start and end in days ago).

After specifying the event, you can optionally filter on specific or multiple properties:

* `all` — applies an AND condition across properties.
* `at least one` — applies an OR condition.

Then set the properties you want to filter on using `dot notation`.

* Custom Events are represented as [JSON Objects](https://www.w3schools.com/js/js_json.asp).
* See [Custom Events](./custom-events#what-are-custom-events) for more details.

#### Example

Given the following Custom Event:

```json theme={null}
{
  "events": [
    {
      "name": "cart_updated",
      "properties": {
        "product_name": "24 Pack of Acorns",
        "product_price": "12.99",
        "product_quantity": "2"
      },
      "external_id": "ID_OF_THE_USER"
    }
  ]
}
```

You can filter by:

* `product_name` → to target users with product name `24 Pack of Acorns`.
* `product_price` → to target users with product price `12.99`.
* `product_quantity` → to target users with product quantity `2`.

<Frame>
  <img alt="Custom event filter example showing product name, image, price, quantity, and cart URL" />
</Frame>

<Warning>
  Segments created with custom event filters are in Early Access and are user-based. A custom event segment can only contain custom event filters, and cannot be combined with other segments for inclusion or exclusion when sending messages.
</Warning>

## Audience counts

The segment editor shows how many subscribed and unsubscribed Subscriptions are in your segment, with a breakdown by channel (push, email, and SMS).

* **Subscribed** Subscriptions are opted in and will receive messages when you target this segment.
* **Unsubscribed** Subscriptions match your segment filters but are opted out and will not receive messages.

The channel breakdown lets you see reachable vs. unreachable Subscriptions per channel — useful for understanding which channels will be most effective before you build a message or Journey.

<Frame>
  <img alt="Audience counts showing subscribed and unsubscribed counts by channel" />
</Frame>

### Exact counts and estimates

OneSignal always returns a count within approximately 15 seconds. Whenever possible within that time limit, you will see an exact count. For large or complex segments where exact counts can take a long time to compute, an estimate is shown instead.

Estimates are labeled to make clear they are not exact:

| Segment size | Format                     | Example             |
| ------------ | -------------------------- | ------------------- |
| Above 10,000 | Count with margin of error | `140,000 +/- 5,000` |
| Below 10,000 | Less-than value            | `<4,800`            |

Both formats are rounded to signal the number is approximate. Estimates will never display as 0: if your segment has very few members, the estimate reflects a small non-zero estimate to avoid implying the segment is empty when records may exist.

<Note>
  Audience counts are available for subscription-based segments. User-based segment counts are not yet supported.
</Note>

## Managing segments

When viewing your Segments in the dashboard, you can:

* **View Subscriptions:** See which [Subscriptions](./subscriptions) are in the segment.
* **Copy segment ID:** Copy the segment ID to use in the API.
* **Edit:** Change filters or name.
* **Pause / Resume:** If you're near your [segment limit](https://onesignal.com/pricing), you can pause segments without deleting them. Targeting a paused segment will fail.
* **Set as default:** Set a default segment to be auto-selected when sending a new message. This helps reduce targeting mistakes and save time.
* **Duplicate:** Copy a segment's filters to create a new one.
* **View Audit Logs:** See the [audit logs](./audit-logs) for who may have changed a segment and when.
* **Delete:** Delete the segment.

### Deleting segments

Deleting a segment removes it from your list of segments. It does **not** delete the users inside it. To delete the users inside a segment, see [Delete Users](./delete-users).

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Audience > Segments**
    2. Click the three-dot menu next to a segment
    3. Select **Delete**

    <Frame>
      <img alt="Three-dot options menu on a segment showing Edit, Pause, Duplicate, and Delete actions" />
    </Frame>
  </Tab>

  <Tab title="API">
    Use the [Delete Segment API](/reference/delete-segments). This only removes the segment definition — it does not delete the users inside it.
  </Tab>
</Tabs>

## FAQ

### How do I add myself to a segment?

Set yourself as a Test User or add a custom Tag, then create a segment that targets it.

1. Find your Subscriptions using your [External ID](./users).
2. Either:
   * Set yourself as a [Test User](./test-users)
   * Add a custom [Tag](./add-user-data-tags)
3. Create a segment using the **Test Users** filter or the Tag.

### Do segment counts include opted-out users?

Yes. The segment editor shows counts for both subscribed and unsubscribed Subscriptions. Subscribed Subscriptions are opted in and will receive messages. Unsubscribed Subscriptions match your filters but are opted out and will not receive messages.

Only subscribed Subscriptions are targeted when you send a message.

When used in Journeys and in-app messages, segments include both subscribed and unsubscribed Subscriptions.

### Are segment counts always accurate?

OneSignal always returns a count within approximately 15 seconds. For smaller or simpler segments, this is an exact count. For larger or more complex segments, an estimate is shown instead.

Estimates are clearly labeled with their precision. See [Audience counts](#audience-counts) for details on how estimates are formatted and what they mean.

### Can I combine message event filters with subscription filters?

Outside of Journeys, no — segments built with message event or custom event filters are user-based and cannot be combined with subscription-based segments for inclusion or exclusion. Inside [Journeys](./journeys-overview), which are themselves user-based, you can combine both filter types for more flexible targeting.

## Related pages

<Columns>
  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    The push, email, and SMS records segments target.
  </Card>

  <Card title="Add user data tags" icon="tags" href="./add-user-data-tags">
    Tag users with custom data so segments can filter on it.
  </Card>

  <Card title="Custom Events" icon="bolt" href="./custom-events">
    Send user actions to OneSignal for use in segments and Journeys.
  </Card>

  <Card title="Message events" icon="envelope-open" href="./message-events">
    Per-user record of message interactions — the basis of message event filters.
  </Card>

  <Card title="Journeys overview" icon="route" href="./journeys-overview">
    Trigger automated workflows from segment membership.
  </Card>

  <Card title="Import users" icon="file-csv" href="./import">
    Bulk-import users and Tags via CSV.
  </Card>
</Columns>


# Send WhatsApp Messages via Journey Webhooks
Source: https://documentation.onesignal.com/docs/en/sending-whatsapp-messages-via-journey-webhooks

Send WhatsApp messages automatically using OneSignal Journeys and webhooks.

## Requirements

* Paid plan that supports both Journeys and Webhooks
* [WhatsApp Business Platform](https://developers.facebook.com/docs/whatsapp/) + [Webhooks Setup](https://developers.facebook.com/docs/whatsapp/business-management-api/guides/set-up-webhooks/)
* WhatsApp recipients

<Info>
  While the following guide uses the Facebook/Meta API, Twilio can also be used to Post WhatsApp messages.
</Info>

## Setup

### 1. Import recipients phone numbers

WhatsApp supporting numbers should be uploaded as a data tag to a User.

**Here's an example:**

<Frame>
  <img />
</Frame>

<Warning>
  Please add numbers in the E.164 format, but without the + sign. The number +16463938787 should be added as 16463938787.
</Warning>

### 2. Obtain Webhook code

Once you have created your Meta/Facebook Business account and have activated your WhatsApp Module, you'll be given an API access token.

You'll be able to find this information under WhatsApp -> API Setup

<Frame>
  <img />
</Frame>

### 3. Create a Webhook Template

* Within OneSignal, click on: **Data > Webhooks > New Webhook**
* Copy over the credentials. It should look like this:

<Frame>
  <img />
</Frame>

<Warning>
  `{{user.tags.WhatsApp_number}}` tag key is added as the "to" number as highlighted above.
</Warning>

### 4. Create a Journey

You can now create your Journey and add your new WhatsApp Webhook.

<Frame>
  <img />
</Frame>

When testing, please make sure of the following:

* The subscription id in which you have added the WhatsApp number has an external id
* The subscription id matches the Journey included segment(s)

***


# SingleStore
Source: https://documentation.onesignal.com/docs/en/singlestore

Sync custom events from SingleStore to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + SingleStore integration enables syncing of custom events from your SingleStore database to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

SingleStore is a distributed SQL database designed for real-time analytics and high-performance applications.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### SingleStore

* **SingleStoreDB Cloud** or **SingleStoreDB v7.1+**
* **Database user** with appropriate permissions
* **Event tables** containing structured behavioral data
* **Network connectivity** from OneSignal to your SingleStore cluster

***

## Setup

<Steps>
  <Step title="Create dedicated user for OneSignal">
    Create a dedicated user account with a strong, unique password:

    ```sql theme={null}
    -- Create census user with the ability to sign in with a password
    CREATE USER CENSUS IDENTIFIED BY '<strong-unique-password>';
    ```
  </Step>

  <Step title="Grant permissions to event data">
    Provide read-only access to schemas containing your event data:

    ```sql theme={null}
    -- Grant read-only access to schema with event data
    GRANT SELECT ON analytics.* TO CENSUS;

    -- Repeat for additional schemas if needed
    GRANT SELECT ON events.* TO CENSUS;
    ```

    <Info>
      If you have multiple schemas containing event data, repeat the `GRANT SELECT` statement for each schema.
    </Info>
  </Step>

  <Step title="Connect to OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **SingleStore** and provide the following connection details:

    * **Host:** Your SingleStore cluster endpoint
    * **Port:** 3306 (default)
    * **Database:** Your database name
    * **Username:** `CENSUS`
    * **Password:** The password from Step 1
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Table Schema

```sql theme={null}
-- Example SingleStore event table
CREATE TABLE analytics.user_events (
    event_id BIGINT AUTO_INCREMENT PRIMARY KEY,
    event_name VARCHAR(100) NOT NULL,
    user_id VARCHAR(255) NOT NULL,
    event_timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    event_data JSON,
    session_id VARCHAR(255),
    device_type VARCHAR(50)
);
```

### SQL Query Mode

Write custom SQL queries to transform your event data:

```sql theme={null}
-- Example: Recent high-value events
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_data
FROM analytics.user_events
WHERE event_timestamp >= DATE_SUB(NOW(), INTERVAL 7 DAY)
    AND JSON_EXTRACT_STRING(event_data, 'value') > '100'
ORDER BY event_timestamp DESC;
```

***

## Advanced Network Configuration

OneSignal can successfully connect to SingleStore instances that are using advanced networking controls including region constraints and IP address allow lists.

For more information about configuring network access, contact your SingleStore administrator or OneSignal support.

***

## Limitations

* Real-time analytics queries may impact cluster performance during high-traffic periods
* JSON operations should be optimized for distributed execution

***

## FAQ

### Can I connect to multiple SingleStore schemas?

Yes, you can grant the CENSUS user access to multiple schemas by running the `GRANT SELECT` statement for each schema containing event data.

### Does OneSignal support SingleStore Cloud?

Yes, OneSignal supports both SingleStoreDB Cloud and on-premises SingleStoreDB v7.1+ installations.


# SMS regulatory compliance
Source: https://documentation.onesignal.com/docs/en/sms-regulatory-compliance

Understand SMS compliance requirements for every country OneSignal supports. Covers consent standards by message type, sender identification, opt-out, quiet hours, prohibited content, record-keeping, and fraud prevention.

The same core compliance principles apply in every country OneSignal supports. The specific laws differ by country, including TCPA in the US, CASL in Canada, GDPR/PECR in the UK and EU, and the Spam Act in Australia. They all enforce the same fundamental requirements.

***

## Preventing SMS fraud

SMS pumping is a type of fraud where bad actors artificially inflate messaging volumes, typically by triggering high-volume sends in a very short period to high-risk countries, generating revenue at your expense.

For customers using OneSignal SMS, we have built-in protections:

* **Spend warnings:** OneSignal monitors your messaging volume against your contracted spend. If your usage begins to exceed your contracted amount, we'll alert you to investigate.
* **Automatic send disabling:** If your spend crosses a threshold above your contracted amount, OneSignal automatically disables sending on your account to prevent further damage.
* **Geographic restrictions:** Your account is restricted to sending only to the geographies included in your contract, preventing bad actors from routing messages to high-cost international destinations you never intended to reach.

***

## Compliance best practices

### Consent

You must have consent before sending a message. The standard depends on the message type:

* **Promotional messages** require the highest standard of consent. The subscriber must take an affirmative action to opt in, such as an unchecked checkbox, a keyword reply, or a form submission. Pre-checked boxes, bundled consent, or assumed consent from silence are non-compliant everywhere.
* **Transactional messages** (order confirmations, shipping updates, account alerts) have a lower consent bar. In most jurisdictions, a user entering their phone number in a form where disclosure language is visible is sufficient. The message must be directly related to the purpose for which the number was collected.
* **OTP / verification messages** follow the same consent standard as transactional messages.

Consent is always scoped to the stated purpose. If a subscriber consented to receive shipping updates, that does not cover promotional messages. Collect consent for each separately.

Consent is not transferable between brands. Purchased, rented, or shared contact lists are non-compliant in every jurisdiction OneSignal supports.

For collection methods, disclosure language, and audience validation, see [SMS opt-in and collection](./sms-opt-in-and-collection).

### Privacy policy

Every messaging program must have a published privacy policy accessible to subscribers. The privacy policy should explain what data you collect, how you use it, and how subscribers can exercise their rights. A link to your privacy policy is required during the sender resource application process in every country.

### Record-keeping

Maintain clear records of how and when each subscriber's consent was obtained. If challenged by a regulator, the burden of proof is on you to demonstrate that valid consent exists. Store timestamped records of opt-ins (form submissions, keyword replies, API events) and opt-outs.

### Sender identification

Every message must identify who is sending it. Include your brand name in the message body. If you're using an alphanumeric sender ID, the sender name itself serves as primary identification, but still include your brand name in the body, since some devices may not display the sender ID prominently.

### Opt-out mechanism

Every message must include a way for the recipient to unsubscribe:

* For sender resources that can receive inbound messages (toll-free, 10DLC, long codes, short codes), include STOP keyword instructions (for example, "Reply STOP to opt out").
* For alphanumeric sender IDs, which cannot receive inbound messages, include an unsubscribe link. See [Consent keyword management](./sms-consent-keyword-management#managing-opt-outs-for-alphanumeric-senders) for how to build a web-based unsubscribe flow.

Once a recipient opts out, honor it promptly. The universal expectation is that opt-outs are processed as quickly as possible, ideally immediately.

### Quiet hours

Promotional messages should only be sent during appropriate hours in the recipient's local time zone. Transactional and OTP messages are generally exempt from quiet hours, but use good judgment. A shipping update at 3 AM will generate complaints regardless of legality.

| Country        | Recommended sending window |
| -------------- | -------------------------- |
| United States  | 8 AM–9 PM local time       |
| Canada         | 9 AM–9 PM local time       |
| United Kingdom | 8 AM–8 PM local time       |
| EU countries   | 8 AM–8 PM local time       |
| Australia      | 9 AM–8 PM local time       |

Some countries have stricter requirements. See [Sender resource applications](./sms-registration-requirements) for country-specific rules.

<Note>
  OneSignal does not have a built-in quiet hours feature for SMS. Respecting local quiet hours is your responsibility as the sender. To keep messages within permitted hours, add a [time window](./journeys-actions#time-window) node to your Journey to control when sends can occur. The time window uses each recipient's local time zone when time zone data is available, so messages only get sent out during the recommended sending windows.
</Note>

### Match content to your approved use case

Your messages must align with the use case approved during your sender resource application. If your sender resource was approved for transactional messages, do not use it to send promotional content. Carriers and regulators monitor for mismatches, and violations can result in campaign suspension or sender resource revocation.

### Prohibited and restricted content

Every country prohibits certain categories of content. The following are restricted or prohibited in most jurisdictions OneSignal supports:

* **Universally prohibited:** Illegal content, phishing, smishing, social engineering, fraud, and spam.
* **Widely restricted (SHAFT):** Sex, Hate, Alcohol, Firearms, and Tobacco. In the US, some SHAFT categories may be permitted with age gating and a Special Business Review, but require additional carrier approval.
* **Cannabis / CBD:** Prohibited in the US (federally illegal) and Australia. CBD-only content is permissible in the UK but not cannabis. Rules vary by country.
* **Age-restricted content** (alcohol, gambling): May be permitted in some countries but typically requires case-by-case carrier review and age gating.

During the sender resource application process, your sample messages are reviewed against these restrictions. If your content doesn't match what was approved, or falls into a prohibited category, your campaign can be suspended and your sender resource revoked.

***

## Country-specific requirements

<Card title="Sender resource applications" icon="globe" href="./sms-registration-requirements">
  Per-country approval processes, additional notes, and governing laws for every market OneSignal supports.
</Card>

***

## FAQ

### Does consent expire?

There is no universal expiration date for SMS consent, but stale lists can create compliance risk. If a subscriber hasn't received a message in a long time, re-engagement best practices suggest sending a reminder before resuming your program. Some jurisdictions (for example, Australia) require that your unsubscribe mechanism remains functional for 30 days after sending.

### What happens if a subscriber on a purchased list texts STOP?

The opt-out is processed and honored. However, using purchased, rented, or shared contact lists is non-compliant in every jurisdiction OneSignal supports. You should not be sending to lists you did not collect consent for in the first place.

### Do quiet hours apply to OTP messages?

Transactional and OTP messages are generally exempt from quiet hour restrictions. That said, use good judgment. Sending a non-urgent notification at 3 AM will generate complaints regardless of whether it is technically permitted.

### What is SHAFT content?

SHAFT stands for Sex, Hate, Alcohol, Firearms, and Tobacco, categories of content that are restricted or prohibited in most SMS markets. Some SHAFT categories may be permitted in specific countries with additional carrier approval or age gating. Check country-specific requirements in [Sender resource applications](./sms-registration-requirements) before sending SHAFT-adjacent content.

### Can I send cannabis-related content?

Cannabis content is prohibited in the US (federally illegal) and Australia. CBD-only content is permissible in the UK. Rules vary significantly by country. Verify the specific restriction before sending any cannabis or CBD content.

***

## Related pages

<Columns>
  <Card title="Sender resource applications" icon="globe" href="./sms-registration-requirements">
    Per-country approval processes, sender resource types, and governing laws.
  </Card>

  <Card title="SMS opt-in and collection" icon="user-plus" href="./sms-opt-in-and-collection">
    Collection methods, required disclosure language, and audience validation.
  </Card>

  <Card title="Consent keyword management" icon="shield" href="./sms-consent-keyword-management">
    STOP, HELP, START, and custom opt-out keyword handling.
  </Card>

  <Card title="Composing messages" icon="pen-to-square" href="./sms-composing-messages">
    Character limits, MMS, trackable links, and RCS rich content.
  </Card>
</Columns>


# Snowflake
Source: https://documentation.onesignal.com/docs/en/snowflake

Sync custom events from Snowflake to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

<Note>
  If you are using Snowflake with OneSignal's legacy integration, please refer to the [Snowflake Legacy Integration](./snowflake-legacy) guide. See [Migrating from legacy](#migrating-from-legacy) for migration steps.
</Note>

***

## Overview

The OneSignal + Snowflake integration supports two powerful data pipelines:

* **Outbound**: Automatically send messaging event data (push, email, SMS, in-app) from OneSignal to Snowflake for analysis and reporting.
* **Inbound**: Sync custom user events from your Snowflake datasets to OneSignal to trigger automated Journeys and personalized messaging.

Together, these integrations give you complete control over user engagement data—powering advanced analytics and real-time behavior-driven messaging.

***

## Outbound setup

<Note>
  This is currently in early access.
  To request access, contact `support@onesignal.com` with:

  * Your company name
  * Your OneSignal organization ID
  * The app ID(s) you want to enable
</Note>

Export message performance and engagement events (e.g., sends, opens, clicks) to Snowflake to:

* Build custom dashboards and reports
* Track delivery and engagement trends across channels
* Combine OneSignal data with other business data for analysis

**Requirements**

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

- OneSignal **Professional Plan** (not available on free apps)
- [Snowflake account](https://docs.snowflake.com/en/user-guide/getting-started-tutorial)
- SECURITYADMIN or ACCOUNTADMIN role in Snowflake (for setup)

### 1. Gather your Snowflake account details

Before configuring the integration, collect the following information from your Snowflake account:

* **Snowflake Host**: Your account URL in the format `<account_identifier>.snowflakecomputing.com`
* **Database name**: The database where OneSignal will write event data
* **Schema name**: The schema within the database for OneSignal tables (this will be auto created by OneSignal)
* **Warehouse name**: The warehouse to use for data loading operations

<Frame>
  <img />
</Frame>

### 2. Run setup script in Snowflake

Execute the following SQL script in your Snowflake warehouse to create the necessary role, user, warehouse, and database for OneSignal:

```sql theme={null}
begin;

   -- create variables for user / role / warehouse / database (needs to be uppercase for objects)
   set role_name = 'ONESIGNAL_ROLE';
   set user_name = 'ONESIGNAL_USER';
   set warehouse_name = 'ONESIGNAL_WAREHOUSE';
   set database_name = 'ONESIGNAL';

   -- change role to securityadmin for user / role steps
   use role securityadmin;

   -- create role for onesignal
   create role if not exists identifier($role_name);
   grant role identifier($role_name) to role SYSADMIN;

   -- create a user for onesignal
   create user if not exists identifier($user_name)
   default_role = $role_name
   default_warehouse = $warehouse_name;

   grant role identifier($role_name) to user identifier($user_name);

   -- set binary_input_format to BASE64
   ALTER USER identifier($user_name) SET BINARY_INPUT_FORMAT = 'BASE64';

   -- set timestamp_input_format to AUTO for the user
   ALTER USER identifier($user_name) SET TIMESTAMP_INPUT_FORMAT = 'AUTO';

   -- change role to sysadmin for warehouse / database steps
   use role sysadmin;

   -- create a warehouse for onesignal
   create warehouse if not exists identifier($warehouse_name)
   warehouse_size = xsmall
   warehouse_type = standard
   auto_suspend = 60
   auto_resume = true
   initially_suspended = true;

   -- create database for onesignal
   create database if not exists identifier($database_name);

   -- grant onesignal role access to warehouse
   grant USAGE
   on warehouse identifier($warehouse_name)
   to role identifier($role_name);

   -- grant onesignal access to database
   grant CREATE SCHEMA, MONITOR, USAGE
   on database identifier($database_name)
   to role identifier($role_name);

 commit;
```

<Note>
  You can customize the variable values at the top of the script to match your naming conventions. If you're using an existing warehouse or database, modify the script accordingly.
</Note>

### 3. Generate key pair for authentication

OneSignal requires key-pair authentication for secure access to your Snowflake account. Follow these steps to generate and configure the keys:

<Steps>
  <Step title="Generate a private key">
    Run one of the following commands to generate a private key:

    **Unencrypted private key** (simpler, but less secure):

    ```bash theme={null}
    openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
    ```

    **Encrypted private key** (recommended for production):

    ```bash theme={null}
    openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 aes256 -inform PEM -out rsa_key.p8
    ```

    If using an encrypted key, you'll be prompted to create a passphrase. Save this passphrase securely—you'll need it when configuring OneSignal.
  </Step>

  <Step title="Generate the public key">
    Generate the public key from your private key:

    ```bash theme={null}
    openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
    ```
  </Step>

  <Step title="Assign the public key to your Snowflake user">
    Copy the contents of the public key file (excluding the header and footer lines), then run this SQL command in Snowflake:

    ```sql theme={null}
    ALTER USER ONESIGNAL_USER SET RSA_PUBLIC_KEY='<YOUR_PUBLIC_KEY_CONTENT>';
    ```

    Replace `<YOUR_PUBLIC_KEY_CONTENT>` with the key content (without `-----BEGIN PUBLIC KEY-----` and `-----END PUBLIC KEY-----` lines).
  </Step>
</Steps>

<Warning>
  Store your private key file securely. You'll need to provide it to OneSignal in the next step. Never share your private key publicly or commit it to version control.
</Warning>

### 4. Connect OneSignal

<Steps>
  <Step title="Activate the integration">
    In OneSignal, navigate to **Data > Integrations > Snowflake**.
  </Step>

  <Step title="Enter the details">
    * Host: `<your_account>.snowflakecomputing.com`
    * Port: Optional, defaults to `443`
    * Database: e.g. `ONESIGNAL`
    * Role: Optional, uses the user's default role if omitted
    * User: e.g. `ONESIGNAL_USER`
    * Private Key: Paste the contents of your private key file (`rsa_key.p8`)
    * Private Key Passphrase: Optional, only if your private key is encrypted
    * Data processing location: Where data is processed before before sending it to Snowflake
  </Step>

  <Step title="Configure the integration">
    * **Sync Frequency:** as often as every 15 minutes
    * **Schema/Table Names:** pre-set as `onesignal_events_<app-id>` and `message_events` (editable)
    * **Event Types:** choose which to sync—select all or just what you need
  </Step>

  <Step title="Select events">
    Select the events you care to receive in your Snowflake warehouse.
  </Step>

  <Step title="Complete the setup">
    Click **Save** and wait for the success confirmation
  </Step>
</Steps>

<Note>
  Initial data sync can take 15–30 minutes to appear in Snowflake.

  While you wait, send messages via push, email, in-app, or SMS to trigger the events selected.
</Note>

### 5. View data in Snowflake

Once the initial sync completes, query your OneSignal event data:

```sql theme={null}
-- View recent message events
SELECT *
FROM <your-database>.<your-schema>.message_events
ORDER BY _CREATED DESC
LIMIT 100;
```

<Info>
  If you run into issues like missing schemas, permission errors, or malformed events, contact `support@onesignal.com`.
</Info>

## Message events and properties

### Message event kinds

**Property:** `event_kind`
**Type:** `String`

The kind of message and event (e.g. `message.push.received`, `message.push.sent`).

| Message Event (OneSignal) |           `event_kind`           | Description                                                                |
| :-----------------------: | :------------------------------: | -------------------------------------------------------------------------- |
|         Push Sent         |        `message.push.sent`       | Push notification successfully sent.                                       |
|       Push Received       |      `message.push.received`     | Delivered push (see [Confirmed receipt](/docs/en/confirmed-delivery)).     |
|        Push Clicked       |      `message.push.clicked`      | User clicked the push.                                                     |
|        Push Failed        |       `message.push.failed`      | Delivery failure. See message reports.                                     |
|     Push Unsubscribed     |    `message.push.unsubscribed`   | User unsubscribed from push.                                               |
|     In-App Impression     |     `message.iam.impression`     | In-App message shown.                                                      |
|       In-App Clicked      |       `message.iam.clicked`      | In-App message clicked.                                                    |
|     In-App Page Viewed    |   `message.iam.page_displayed`   | In-App page shown.                                                         |
|         Email Sent        |       `message.email.sent`       | Email delivered.                                                           |
|       Email Received      |     `message.email.received`     | Email accepted by recipient's mail server.                                 |
|        Email Opened       |      `message.email.opened`      | Email opened. See [Email Reports](/docs/en/email-message-reports).         |
|     Email Link Clicked    |      `message.email.clicked`     | Link in email clicked.                                                     |
|     Email Unsubscribed    |   `message.email.unsubscribed`   | Recipient unsubscribed.                                                    |
|   Email Reported As Spam  | `message.email.reported_as_spam` | Marked as spam. See [Email Deliverability](/docs/en/email-deliverability). |
|       Email Bounced       |      `message.email.bounced`     | Bounce due to permanent delivery failure.                                  |
|        Email Failed       |      `message.email.failed`      | Delivery failed.                                                           |
|      Email Suppressed     |    `message.email.suppressed`    | Suppressed due to suppression list.                                        |
|          SMS Sent         |        `message.sms.sent`        | SMS sent.                                                                  |
|       SMS Delivered       |      `message.sms.delivered`     | SMS successfully delivered.                                                |
|         SMS Failed        |       `message.sms.failed`       | SMS failed to deliver.                                                     |
|      SMS Undelivered      |     `message.sms.undelivered`    | SMS rejected or unreachable.                                               |

### Event data schema

For each message event generated by a user, the following metadata will be attached to the record.

|                   Column Name                   |      Type      | Description                                                  |
| :---------------------------------------------: | :------------: | ------------------------------------------------------------ |
|                    `event_id`                   |      UUID      | Unique identifier for the event                              |
|                `event_timestamp`                |    Timestamp   | Time of event occurrence                                     |
|                   `event_kind`                  |     String     | The [Event Kind](#message-event-kinds)                       |
|            `subscription_device_type`           |     String     | Device type (e.g., iOS, Android, Web, Email, SMS)            |
|                    `language`                   |     String     | Subscription language code                                   |
|                    `version`                    |     String     | Integration version                                          |
|                   `device_os`                   |     String     | Device operating system version                              |
|                  `device_type`                  |     Number     | Numeric device type                                          |
|                     `token`                     |     String     | Push token, phone number, or email                           |
|                `subscription_id`                |      UUID      | Subscription ID                                              |
|                   `subscribed`                  |     Boolean    | Subscription status                                          |
|                  `onesignal_id`                 |      UUID      | OneSignal user ID                                            |
|                  `last_active`                  |     String     | Last active timestamp                                        |
|                      `sdk`                      |     String     | OneSignal SDK version                                        |
|                  `external_id`                  |     String     | External user ID that should match the integration user ID   |
|                     `app_id`                    |      UUID      | App ID from OneSignal                                        |
|                  `template_id`                  |      UUID      | Template ID (if applicable)                                  |
|                   `message_id`                  |      UUID      | Message batch/request ID                                     |
|                  `message_name`                 |     String     | Name of the message                                          |
|                 `message_title`                 |     String     | Message title (English only)                                 |
|                `message_contents`               |     String     | Truncated message body (English only)                        |
|                 `failure_reason`                |     String     | Reason for failure (for push failed and email failed events) |
| `_created`, `_id`, `_index`, `_fivetran_synced` | *Internal use* | Fivetran sync metadata                                       |

### Notes

* Syncs after saving/activating may take an additional 15-30 minutes to complete.
* Deactivating may still result in one final sync after deactivation.
* To ensure efficient data synchronization, our system automatically creates and manages staging datasets. These datasets, named with a pattern like `fivetran_{two random words}_staging`, temporarily store data during processing before it's integrated into your main schema. These staging datasets are essential for maintaining a streamlined workflow and should not be deleted, as they will be automatically recreated.

***

## Migrating from legacy

If you're currently using the [legacy Snowflake integration](./snowflake-legacy), this section covers the key differences and how to migrate your queries.

### Key differences

| Feature             | Legacy                          | New                                        |
| ------------------- | ------------------------------- | ------------------------------------------ |
| **Sync frequency**  | 24 hours                        | As often as 15 minutes                     |
| **Data ownership**  | Read-only access to shared data | Written directly to your Snowflake account |
| **Data retention**  | 30 days                         | You control retention                      |
| **Event selection** | All events                      | Choose specific event types                |

<Warning>
  If you copied events from the legacy integration (a data share with 30-day retention) into your own tables,
  be aware that your legacy events table likely uses a different schema.

  The new integration uses renamed columns and automatic type inference, so pointing a new setup at a backup
  table may produce errors or unexpected results.

  We recommend creating a new table and using the combined view below if you need to merge historical
  events with new events.
</Warning>

### Schema changes

The new integration creates columns on-demand. If no events contain data for a particular field, that column won't exist in your table. When data appears for that field, the column is created automatically.

#### Column renames

| Legacy column                | New column         |
| ---------------------------- | ------------------ |
| `EVENT_IMPRESSION_TIMESTAMP` | `EVENT_TIMESTAMP`  |
| `SUBSCRIPTION_LANGUAGE`      | `LANGUAGE`         |
| `MESSAGE_BODY`               | `MESSAGE_CONTENTS` |

### Type inference

The new integration uses automatic type inference. If all values in a column are numeric (e.g., all your `EXTERNAL_ID` values are numbers), the column may be typed as `NUMBER`. If a non-numeric value appears later, the column type is promoted to `VARCHAR`.

Use explicit casting if needed:

```sql theme={null}
WHERE EXTERNAL_ID = '12345'::VARCHAR
```

### Migrating queries

To migrate existing queries:

1. Update references to the legacy database to point to your new Snowflake database
2. Account for the column renames listed above
3. Add explicit type casting where needed

Optionally, create a combined view that unions the new integration table with your legacy backup table and deduplicates on `EVENT_ID`:

```sql theme={null}
CREATE VIEW your_schema.message_events_combined AS
SELECT * FROM (
  SELECT
    EVENT_ID,
    EVENT_KIND,
    EVENT_TIMESTAMP,
    SUBSCRIPTION_ID,
    LANGUAGE,
    SUBSCRIPTION_TIMEZONE,
    SUBSCRIPTION_DEVICE_TYPE,
    ONESIGNAL_ID,
    EXTERNAL_ID,
    MESSAGE_ID,
    MESSAGE_NAME,
    MESSAGE_TITLE,
    MESSAGE_CONTENTS,
    ROW_NUMBER() OVER (PARTITION BY EVENT_ID ORDER BY EVENT_TIMESTAMP DESC) AS row_num
  FROM (
    -- New integration data
    SELECT
      EVENT_ID,
      EVENT_KIND,
      EVENT_TIMESTAMP,
      SUBSCRIPTION_ID,
      LANGUAGE,
      SUBSCRIPTION_TIMEZONE,
      SUBSCRIPTION_DEVICE_TYPE,
      ONESIGNAL_ID,
      EXTERNAL_ID,
      MESSAGE_ID,
      MESSAGE_NAME,
      MESSAGE_TITLE,
      MESSAGE_CONTENTS
    FROM <new-database>.<new-schema>.MESSAGE_EVENTS

    UNION ALL

    -- Legacy backup data (aliased to match new column names)
    SELECT
      EVENT_ID,
      EVENT_KIND,
      EVENT_IMPRESSION_TIMESTAMP AS EVENT_TIMESTAMP,
      SUBSCRIPTION_ID,
      SUBSCRIPTION_LANGUAGE AS LANGUAGE,
      SUBSCRIPTION_TIMEZONE,
      SUBSCRIPTION_DEVICE_TYPE,
      ONESIGNAL_ID,
      EXTERNAL_ID,
      MESSAGE_ID,
      MESSAGE_NAME,
      MESSAGE_TITLE,
      MESSAGE_BODY AS MESSAGE_CONTENTS
    FROM <legacy-backup-database>.<legacy-backup-schema>.MESSAGE_EVENTS
  )
)
WHERE row_num = 1;
```

<Note>
  Replace `<new-database>.<new-schema>` with your new integration's database and schema.

  Replace `<legacy-backup-database>.<legacy-backup-schema>` with wherever you backed up your legacy shared data.

  This view merges historical + new data and deduplicates on `EVENT_ID`, so events that
  appear in both sources are only counted once. This is especially important if you run
  both integrations simultaneously during migration.
</Note>

To disconnect your legacy data share, contact [snowflake-data-sharing@onesignal.com](mailto:snowflake-data-sharing@onesignal.com).

***

## Inbound setup

Import behavioral event data from Snowflake to OneSignal to:

* Trigger Journeys based on user activity
* Personalize messaging based on behavioral data

**Requirements**

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

- **Snowflake account** with warehouse access
- **Event data** stored in Snowflake tables or views
- **Network connectivity** from OneSignal to your Snowflake instance
- **User credentials** with appropriate permissions

<Steps>
  <Step title="Create dedicated role for OneSignal">
    Create a role hierarchy following Snowflake best practices:

    ```sql theme={null}
    -- Create a role for the census user
    CREATE ROLE CENSUS_ROLE;

    -- Ensure the sysadmin role inherits any privileges the census role is granted
    GRANT ROLE CENSUS_ROLE TO ROLE SYSADMIN;
    ```
  </Step>

  <Step title="Create dedicated warehouse">
    Create a cost-optimized warehouse for OneSignal operations:

    ```sql theme={null}
    -- Create a warehouse for the census role, optimizing for cost over performance
    CREATE WAREHOUSE CENSUS_WAREHOUSE WITH
        WAREHOUSE_SIZE = XSMALL
        AUTO_SUSPEND = 60
        AUTO_RESUME = TRUE
        INITIALLY_SUSPENDED = FALSE;

    GRANT USAGE ON WAREHOUSE CENSUS_WAREHOUSE TO ROLE CENSUS_ROLE;
    GRANT OPERATE ON WAREHOUSE CENSUS_WAREHOUSE TO ROLE CENSUS_ROLE;
    GRANT MONITOR ON WAREHOUSE CENSUS_WAREHOUSE TO ROLE CENSUS_ROLE;
    ```
  </Step>

  <Step title="Create user and grant permissions">
    Create the OneSignal user and grant access to your event data:

    ```sql theme={null}
    -- Create the census user
    CREATE USER CENSUS WITH
        DEFAULT_ROLE = CENSUS_ROLE
        DEFAULT_WAREHOUSE = CENSUS_WAREHOUSE
        PASSWORD = '<strong-unique-password>';

    GRANT ROLE CENSUS_ROLE TO USER CENSUS;

    -- Grant access to your event data (replace with your actual database/schema)
    GRANT USAGE ON DATABASE "<your-database>" TO ROLE CENSUS_ROLE;
    GRANT USAGE ON SCHEMA "<your-database>"."<your-schema>" TO ROLE CENSUS_ROLE;
    GRANT SELECT ON ALL TABLES IN SCHEMA "<your-database>"."<your-schema>" TO ROLE CENSUS_ROLE;
    GRANT SELECT ON FUTURE TABLES IN SCHEMA "<your-database>"."<your-schema>" TO ROLE CENSUS_ROLE;
    GRANT SELECT ON ALL VIEWS IN SCHEMA "<your-database>"."<your-schema>" TO ROLE CENSUS_ROLE;
    GRANT SELECT ON FUTURE VIEWS IN SCHEMA "<your-database>"."<your-schema>" TO ROLE CENSUS_ROLE;
    ```
  </Step>

  <Step title="Create bookkeeping database (Advanced Sync Engine)">
    Create a private database for OneSignal's sync state management:

    ```sql theme={null}
    -- Create a private bookkeeping database
    CREATE DATABASE "CENSUS";
    GRANT ALL PRIVILEGES ON DATABASE "CENSUS" TO ROLE CENSUS_ROLE;

    CREATE SCHEMA "CENSUS"."CENSUS";
    GRANT ALL PRIVILEGES ON SCHEMA "CENSUS"."CENSUS" TO ROLE CENSUS_ROLE;
    GRANT CREATE STAGE ON SCHEMA "CENSUS"."CENSUS" TO ROLE CENSUS_ROLE;
    ```

    <Warning>
      Skip this step if using Basic Sync Engine or read-only mode.
    </Warning>
  </Step>

  <Step title="Configure authentication">
    Set up key-pair authentication (recommended) for enhanced security:

    1. Generate a public/private key pair following [Snowflake's documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth)
    2. Configure the public key on your Snowflake user
    3. Use the private key in OneSignal's connection settings

    Alternatively, you can use password authentication (deprecated - will be blocked November 2025).
  </Step>

  <Step title="Connect to OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Snowflake** and provide the following connection details:

    * **Account Name:** Your Snowflake account identifier (e.g., `abc123.us-east-1`)
    * **Warehouse:** `CENSUS_WAREHOUSE`
    * **User:** `CENSUS`
    * **Database:** Your event data database name
    * **Schema:** Your event data schema name
    * **Authentication:** Key-pair (provide private key and optional passphrase)
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

#### Example Event Table Schema

```sql theme={null}
-- Example Snowflake event table
CREATE TABLE analytics.user_events (
    event_id STRING,
    event_name STRING NOT NULL,
    user_id STRING NOT NULL,
    event_timestamp TIMESTAMP_TZ DEFAULT CURRENT_TIMESTAMP(),
    event_properties VARIANT,
    session_id STRING,
    device_type STRING
);
```

#### SQL Query Mode

Write custom SQL queries to transform your event data:

```sql theme={null}
-- Example: Recent high-value events
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_properties
FROM analytics.user_events
WHERE event_timestamp >= DATEADD(day, -7, CURRENT_TIMESTAMP())
    AND event_properties:value::NUMBER > 100
ORDER BY event_timestamp DESC;
```

### Advanced configuration

#### Managing Warehouse Costs

* Use X-Small warehouse size for cost optimization
* Configure auto-suspend (60 seconds) and auto-resume
* Schedule syncs during off-peak hours
* Consider sharing warehouse with other batch processing systems

#### Live Syncs Support

For real-time event processing, enable change tracking on your event tables:

```sql theme={null}
ALTER TABLE "analytics"."user_events" SET CHANGE_TRACKING = TRUE;
```

#### Network Security

If using Snowflake's Allowed IPs network policy, add OneSignal's IP addresses to your allowlist. Contact OneSignal support for the current IP ranges.

***

## Limitations

* Complex analytical queries may impact warehouse performance and costs
* User/Password authentication will be deprecated November 2025
* The CENSUS database is reserved for OneSignal operations only

***

## FAQ

### Which authentication method should I use?

Use **Key-pair authentication** (recommended). User/Password authentication will be blocked by Snowflake starting November 2025.

### Can I use an existing warehouse?

Yes, you can share a warehouse with other batch processing systems like dbt or Fivetran to optimize costs. Ensure the warehouse has sufficient capacity for your event processing needs.

### How can I optimize costs?

* Use X-Small warehouse size
* Configure aggressive auto-suspend (60 seconds)
* Schedule syncs during off-peak hours
* Use hourly/daily syncs instead of continuous syncing

***


# SOC 2 Type II
Source: https://documentation.onesignal.com/docs/en/soc-2-type-ii

OneSignal's SOC 2 Type II compliance certification and security controls.

### What is SOC 2 Type II?

SOC 2 Type II is an auditing standard created by the American Institute of Certified Public Accountants (AICPA) that sets compliance standards for a company's security controls. We focused our controls around the Trust Service Criteria for: Security, Confidentiality, and Privacy. The reason why it's important is that it provides independent third party validation that an organization has implemented and is operating with security best practices in place.

### OneSignal's path to SOC 2 Type II compliance

In order for OneSignal to achieve SOC 2 Type II compliance, we worked with an independent auditing firm to identify key areas to implement security controls. All in all, we maintain over 75 controls covering everything from workstation security to encryption standards. The audit process includes verification of over 400 separate pieces of evidence over the course of 6 months. We are happy to say that over all this effort we were able to achieve a clean opinion (meaning all the controls were tested to operate properly) in our certification report.

### Need a copy of our latest SOC 2 Type II Report?

For customers that are on our enterprise plan, we are happy to share a copy of our most recent SOC 2 Type II report. For those that are interested in learning more about our compliance efforts, [contact us](https://onesignal.com/contact) for more details.

***


# SQL Server
Source: https://documentation.onesignal.com/docs/en/sql-server

Sync custom events from Microsoft SQL Server to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + SQL Server integration enables syncing of custom events from your Microsoft SQL Server database to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

SQL Server is Microsoft's relational database management system designed for enterprise applications and data warehousing.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### SQL Server

* **SQL Server instance** with network access
* **Database user** with appropriate permissions
* **Event tables** containing structured behavioral data
* **Network connectivity** from OneSignal to your SQL Server instance

***

## Setup

<Steps>
  <Step title="Create dedicated user for OneSignal">
    Create a dedicated user account with a strong, unique password:

    ```sql theme={null}
    -- Create census user with the ability to sign in with a password
    CREATE USER CENSUS WITH PASSWORD = '<strong-unique-password>';

    -- Give the census user the ability to connect to database
    GRANT CONNECT TO CENSUS;
    ```

    <Info>
      All SQL Server commands will run within the database that is specified when running the script.
    </Info>
  </Step>

  <Step title="Grant read permissions">
    Provide read-only access to your event data:

    ```sql theme={null}
    -- Give the census user the ability to read tables within the database
    EXEC sp_addrolemember 'db_datareader', CENSUS;

    -- Grant census user ability to read data from within a schema
    -- Run this for each schema you intend OneSignal to access
    GRANT SELECT, VIEW DEFINITION ON SCHEMA::<your-schema> TO CENSUS;
    ```

    <Info>
      Replace `<your-schema>` with your actual schema name containing event data. Repeat this command for each schema you want OneSignal to access.
    </Info>
  </Step>

  <Step title="Configure Advanced Sync Engine (Optional)">
    For enhanced performance, create a bookkeeping schema for OneSignal's sync state:

    ```sql theme={null}
    -- Create a private bookkeeping schema where Census can store sync state
    CREATE SCHEMA CENSUS AUTHORIZATION CENSUS;

    -- Give the census user full access to the bookkeeping schema
    GRANT ALTER, DELETE, EXECUTE, INSERT, REFERENCES, SELECT,
              UPDATE, VIEW DEFINITION ON SCHEMA::CENSUS TO CENSUS;

    -- Give the census user the ability to create tables within the database
    GRANT CREATE TABLE TO CENSUS;
    ```

    <Warning>
      Skip this step if using Basic Sync Engine or read-only mode.
    </Warning>
  </Step>

  <Step title="Connect to OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **SQL Server** and provide the following connection details:

    * **Host:** Your SQL Server instance hostname or IP address
    * **Port:** 1433 (default) or your custom port
    * **Database:** Your database name
    * **Username:** `CENSUS`
    * **Password:** The password from Step 1
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Table Schema

```sql theme={null}
-- Example SQL Server event table
CREATE TABLE analytics.user_events (
    event_id BIGINT IDENTITY(1,1) PRIMARY KEY,
    event_name NVARCHAR(100) NOT NULL,
    user_id NVARCHAR(255) NOT NULL,
    event_timestamp DATETIME2 DEFAULT GETUTCDATE(),
    event_data NVARCHAR(MAX),
    session_id NVARCHAR(255),
    device_type NVARCHAR(50)
);
```

### SQL Query Mode

Write custom SQL queries to transform your event data:

```sql theme={null}
-- Example: Recent high-value events
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_data
FROM analytics.user_events
WHERE event_timestamp >= DATEADD(day, -7, GETUTCDATE())
    AND JSON_VALUE(event_data, '$.value') > 100
ORDER BY event_timestamp DESC;
```

***

## Advanced Network Configuration

OneSignal can successfully connect to SQL Server instances that are using advanced networking controls including region constraints, IP address allow lists, or SSH Tunneling.

For more information about configuring network access, contact your SQL Server administrator or OneSignal support.

***

## Sync Engine Options

### Basic Sync Engine

* Read-only access to your event data
* State tracking managed by OneSignal infrastructure
* Simpler setup with minimal permissions

### Advanced Sync Engine

* Enhanced performance with local state tracking
* Requires additional permissions to create tables
* Recommended for high-volume event processing

***

## Limitations

* Complex queries may impact database performance during high-traffic periods
* JSON operations require SQL Server 2016 or later for optimal performance
* All permissions are granted at the database level specified during setup

***

## FAQ

### Can I connect to multiple SQL Server schemas?

Yes, you can grant the CENSUS user access to multiple schemas by running the `GRANT SELECT, VIEW DEFINITION ON SCHEMA::<schema>` statement for each schema containing event data.

### Which SQL Server versions are supported?

OneSignal supports modern SQL Server versions. For JSON operations in event queries, SQL Server 2016 or later is recommended.

### Do I need to use the Advanced Sync Engine?

No, the Basic Sync Engine works well for most use cases. Use Advanced Sync Engine if you need enhanced performance and can allow OneSignal to create tables in your SQL Server instance.


# Single Sign-On (SSO)
Source: https://documentation.onesignal.com/docs/en/sso

Configure SSO (SAML 2.0 or OIDC) for your OneSignal organization so team members authenticate through your identity provider.

<Note>
  SSO is available to enterprise customers only. Contact your account manager or `support@onesignal.com` to get started. Having a product owner for SSO from your team on setup calls helps streamline the process.
</Note>

## What is SSO?

Single Sign-On lets team members log in to OneSignal using your organization's identity provider (IdP) instead of a separate username and password. After authenticating once through your IdP, the user receives a token that grants access to OneSignal and your other SaaS applications without additional sign-in prompts.

OneSignal supports **SAML 2.0** and **OpenID Connect (OIDC)** protocols. Choose whichever protocol your IdP supports — both provide the same SSO experience in OneSignal.

## Supported identity providers

|                                                                                                                     |                                                                                                                                                            |                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [ADP](https://marketplace.adp.com/downloads/setting-up-sso.pdf)                                                     | [Duo](https://duo.com/docs/sso)                                                                                                                            | [OneLogin](https://www.onelogin.com/blog/saml-configuration)                                                                                   |
| [Auth0](https://auth0.com/docs/get-started/applications/enable-sso-for-applications)                                | [Google Workspace](https://support.google.com/a/answer/12032922?hl=en)                                                                                     | [Oracle](https://docs.oracle.com/en/cloud/paas/content-cloud/administer/enable-single-sign-sso.html#GUID-8C87B98B-362E-4AD4-8AB9-BD7057935AFE) |
| [Microsoft Entra ID (Azure AD)](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-sso) | [JumpCloud](https://support.jumpcloud.com/support/s/article/getting-started-applications-saml-sso2)                                                        | PingFederate                                                                                                                                   |
| CAS                                                                                                                 | Keycloak                                                                                                                                                   | PingOne                                                                                                                                        |
| ClassLink                                                                                                           | [LastPass](https://support.lastpass.com/s/document-item?language=en_US\&bundleId=lastpass\&topicId=LastPass/c_lastpass_admins_toolkit_sso.html&_LANG=enus) | [Rippling](https://developer.rippling.com/docs/rippling-api/dii48ovix1887-saml-sso-guide)                                                      |
| [Cloudflare](https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/)                            | [Microsoft ADFS](https://learn.microsoft.com/en-us/microsoft-365/troubleshoot/active-directory/set-up-adfs-for-single-sign-on)                             | [Salesforce](https://help.salesforce.com/s/articleView?id=sf.sso_about.htm\&type=5)                                                            |
| Custom OpenID Connect                                                                                               | miniOrange                                                                                                                                                 | Shibboleth                                                                                                                                     |
| Custom SAML                                                                                                         | NetIQ                                                                                                                                                      | Shibboleth Unsolicited                                                                                                                         |
| [CyberArk](https://docs.cyberark.com/Idaptive/Latest/en/Content/Applications/AppsOvw/ConfigSSO.htm)                 | [Okta](https://developer.okta.com/docs/guides/build-sso-integration/openidconnect/main/)                                                                   | SimpleSAMLphp                                                                                                                                  |
|                                                                                                                     |                                                                                                                                                            | [VMware](https://docs.vmware.com/en/VMware-vSphere/6.7/com.vmware.psc.doc/GUID-75D4E587-3F9B-4B50-96DA-D6DB6D1781D7.html)                      |

If your IdP is not listed, contact `support@onesignal.com` to request it.

***

## Setup

Contact `support@onesignal.com` to begin setup. The support team will provide a setup link and guide you through each step.

<Steps>
  <Step title="Contact support and provide your IdP">
    Email support and specify which identity provider you use. The team will send you a setup link and configure the connection on the OneSignal side.
  </Step>

  <Step title="Follow your IdP-specific guide">
    Each identity provider has a different configuration process. Use the [supported identity providers](#supported-identity-providers) table above to find the guide for yours.
  </Step>

  <Step title="Test your connection">
    After connecting your IdP, sign in using your SSO credentials to verify the connection works.
  </Step>

  <Step title="Onboard existing team members">
    Existing OneSignal users can click **Continue with Single Sign-On** on the sign-in page. Username and password login remains available during testing so messaging continues uninterrupted while you onboard.

    Send support the email addresses you want to enable for SSO testing.

    <Frame>
      <img alt="OneSignal sign-in page showing the Continue with Single Sign-On button alongside username and password fields" />
    </Frame>
  </Step>

  <Step title="Enforce SSO">
    When you are ready to require SSO for all users, contact support to enforce SSO on your organization. After enforcement, username and password login is disabled.
  </Step>
</Steps>

***

## Add users to your SSO organization

### Invite through the dashboard

Organization admins can invite users from the **Team Members** page. See [Team Members](./manage-team-members) for role options and permissions.

<Steps>
  <Step title="Invite the user">
    Go to **Team Members** and click **Invite to Organization**. Set the user's role as you invite them.

    <Frame>
      <img alt="OneSignal Team Members page showing the Invite to Organization button" />
    </Frame>

    <Frame>
      <img alt="Email input form for adding a team member to the OneSignal organization" />
    </Frame>
  </Step>

  <Step title="User accepts the invitation">
    The invited user receives an email with an **Accept invitation** link.

    <Frame>
      <img alt="OneSignal invitation email with Accept invitation button" />
    </Frame>
  </Step>

  <Step title="User signs in with SSO">
    After accepting, the user signs in through your organization's SSO provider.

    <Frame>
      <img alt="OneSignal SSO login page prompting the user to authenticate through their identity provider" />
    </Frame>
  </Step>
</Steps>

### Domain restrictions

The invited user's email domain must be registered under your SSO organization. If you invite someone whose email domain is not part of the organization, an error occurs.

<Frame>
  <img alt="OneSignal error message shown when inviting a user whose email domain is not registered in the SSO organization" />
</Frame>

***

## FAQ

### Who can use SSO?

SSO is available to enterprise customers only and requires an existing identity provider. If you don't have an IdP, work with your internal IT team or a consultancy to set one up first. See the [pricing page](https://onesignal.com/pricing) for plan details, or contact `support@onesignal.com` to get started.

### Is there a limit on the number of SSO seats?

No. There is no seat limit for users under an SSO organization.

### Can I test SSO before enforcing it?

Yes — during [setup](#setup), only the email addresses you specify are enabled for SSO login. Username and password login remains active for everyone else, so messaging continues uninterrupted.

### Why does SSO use email domains? How many domains can an organization have?

SSO maps email domains to your organization — for example, `onesignal.com` covers all `@onesignal.com` email addresses. An organization can have multiple domains registered for SSO login.

### How do I provision and de-provision users?

You can add and remove users from the OneSignal dashboard. De-provisioning and provisioning through your IdP directly is not currently supported.

### I need help finding my organization admin or email domains

Contact `support@onesignal.com` — they can help you identify your organization admin and provide a list of email domains registered to your organization.

### What happens if my IdP goes down?

Users with an active session can continue using OneSignal. Users who need to sign in cannot do so until the IdP is restored.

### Is mixed mode supported (SSO and username/password simultaneously)?

Mixed mode is not officially supported. SSO is intended as the primary login method. One workaround is to separate your apps into two organizations — one with SSO enforcement and one without. Organizations are also used for billing, so contact support to discuss the best approach.

### Can I restrict SSO access to specific users or enforce SSO for a limited group?

Yes. Access to OneSignal through SSO is controlled at two levels:

1. **Identity provider**: Most IdPs (e.g., Google Workspace, Okta, Microsoft Entra ID) let you enable or disable apps per user, group, or organizational unit. Configure your IdP to grant the OneSignal app only to the users who need access.
2. **OneSignal invite**: Users must also be [invited to your OneSignal organization](./manage-team-members) through the dashboard. Even if a user can authenticate through your IdP, they cannot access OneSignal until an organization admin invites them.

Both layers must grant access for a user to sign in. To make SSO the only login method, [enforce SSO](#setup) (Step 5) — this disables username/password login for everyone in the organization.

### Can I connect more than one IdP to an organization?

No. Each organization supports one IdP. Contact support if you have additional requirements.

***

<Columns>
  <Card title="Team Members" icon="users" href="./manage-team-members">
    Invite users, assign roles, and manage permissions across your organization.
  </Card>

  <Card title="Pricing" icon="credit-card" href="https://onesignal.com/pricing">
    Compare plans and see which features are included at each tier.
  </Card>
</Columns>


# Starburst Enterprise
Source: https://documentation.onesignal.com/docs/en/starburst-enterprise

Sync custom events from Starburst Enterprise to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Starburst Enterprise integration enables syncing of custom events from your Starburst Enterprise cluster to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

Starburst Enterprise is a commercial distribution of Trino designed for enterprise analytics and data lake querying across multiple sources.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Starburst Enterprise

* **Starburst Enterprise cluster** with network access
* **User credentials** with appropriate permissions
* **TLS connection** support (required by OneSignal)
* **Event data** accessible through Starburst catalogs

***

## Setup

<Steps>
  <Step title="Get JDBC connection details">
    Follow Starburst's documentation to get your JDBC URL for your desired cluster.

    **Example JDBC URL:**

    ```
    jdbc:trino://census-example-cluster.trino.galaxy.starburst.io:[email protected]/accountadmin
    ```

    **Extract hostname for OneSignal:**

    ```
    census-example-cluster.trino.galaxy.starburst.io
    ```

    <Info>
      OneSignal uses JDBC to connect to Starburst Enterprise. You only need the hostname portion of the JDBC URL.
    </Info>
  </Step>

  <Step title="Configure Starburst Enterprise connection">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Starburst Enterprise** and provide the following connection details:

    * **Host:** Your Starburst cluster hostname (from Step 1)
    * **Username:** Your Starburst username
    * **Password:** Your Starburst password
    * **Port:** 443 (default) or your custom port
  </Step>

  <Step title="Configure Advanced Sync Engine (Optional)">
    For enhanced performance, set up a dedicated CENSUS catalog:

    1. Create a catalog named `CENSUS` containing a schema named `CENSUS`
    2. Ensure your connector supports:
       * `CREATE TABLE` and `DROP TABLE` operations
       * Table writes (INSERT, DELETE, UPDATE)
       * `CREATE OR REPLACE TABLE` statement
    3. Grant full permissions on the `CENSUS.CENSUS` schema to your OneSignal user

    <Info>
      Tested configurations include MySQL, PostgreSQL, Snowflake, Iceberg, and Starburst Delta Lake connectors.
    </Info>
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Query

```sql theme={null}
-- Example: Recent high-value events across catalogs
SELECT
    event_name,
    user_id,
    event_timestamp,
    CAST(event_properties AS JSON) as event_properties
FROM catalog.schema.user_events
WHERE event_timestamp >= current_timestamp - INTERVAL '7' DAY
    AND JSON_EXTRACT_SCALAR(event_properties, '$.value') > '100'
ORDER BY event_timestamp DESC;
```

### Enterprise Data Lake Queries

```sql theme={null}
-- Example: Federated query across enterprise data sources
SELECT
    'enterprise_activity' as event_name,
    u.user_id,
    current_timestamp as event_timestamp,
    JSON_FORMAT(JSON_OBJECT(
        'crm_interactions', c.interaction_count,
        'warehouse_orders', w.order_count,
        'lake_analytics', l.score_value
    )) as event_properties
FROM salesforce_catalog.users.accounts u
LEFT JOIN crm_catalog.interactions.summary c ON u.user_id = c.user_id
LEFT JOIN warehouse_catalog.orders.summary w ON u.user_id = w.user_id
LEFT JOIN datalake_catalog.analytics.scores l ON u.user_id = l.user_id
WHERE u.created_date >= current_date - INTERVAL '30' DAY;
```

***

## Sync Engine Options

### Basic Sync Engine

* Works with any Starburst catalog and connector
* State tracking managed by OneSignal infrastructure
* Simpler setup with no additional requirements

### Advanced Sync Engine

* Enhanced performance with local state tracking
* Requires dedicated `CENSUS.CENSUS` catalog and schema
* Supports connectors with table write operations
* Recommended for high-volume enterprise event processing

***

## Supported Connectors

OneSignal's Advanced Sync Engine has been tested with:

* **MySQL connector** (read-write mode)
* **PostgreSQL connector** (read-write mode)
* **Snowflake connector** (read-write mode)
* **Iceberg connector** (with S3 and AWS Glue)
* **Starburst Delta Lake connector** (with AWS Glue catalogs)

***

## Enterprise Features

### Multi-Source Federation

* Query across enterprise data sources in a single sync
* Combine CRM, warehouse, and data lake event data
* Unified customer event profiles from disparate systems

### Security & Compliance

* Enterprise-grade authentication and authorization
* Row-level security and column masking support
* Audit logging for data access tracking

***

## Limitations

* TLS connection required (OneSignal security requirement)
* Advanced Sync Engine requires `CREATE OR REPLACE TABLE` support
* Warehouse Writeback not yet supported (coming soon)
* Cannot provide custom table options in `WITH` clause

***

## FAQ

### How do I get my Starburst Enterprise hostname?

Follow Starburst's documentation to get your JDBC URL, then extract just the hostname portion (without `jdbc:trino://` prefix) for use in OneSignal.

### Can I query multiple enterprise data sources?

Yes! Starburst Enterprise's federated query capabilities allow you to combine event data from multiple enterprise sources (Salesforce, SAP, Oracle, etc.) in a single query.

### Which Starburst release supports the Advanced Sync Engine?

Check your Starburst Enterprise release notes for `CREATE OR REPLACE TABLE` support, which is required for Advanced Sync Engine functionality.


# Starburst Galaxy
Source: https://documentation.onesignal.com/docs/en/starburst-galaxy

Sync custom events from Starburst Galaxy to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Starburst Galaxy integration enables syncing of custom events from your Starburst Galaxy cluster to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

Starburst Galaxy is a fully managed cloud analytics platform based on Trino, designed for fast SQL queries across cloud data lakes and warehouses.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Starburst Galaxy

* **Starburst Galaxy cluster** with network access
* **User credentials** with appropriate permissions
* **TLS connection** support (built-in for Galaxy)
* **Event data** accessible through Galaxy catalogs

***

## Setup

<Steps>
  <Step title="Get Galaxy JDBC connection details">
    In your Starburst Galaxy console, navigate to your cluster's connection details.

    **Example JDBC URL:**

    ```
    jdbc:trino://census-example-cluster.trino.galaxy.starburst.io:[email protected]/accountadmin
    ```

    **Extract hostname for OneSignal:**

    ```
    census-example-cluster.trino.galaxy.starburst.io
    ```

    <Info>
      OneSignal uses JDBC to connect to Starburst Galaxy. You only need the hostname portion from Galaxy's JDBC URL.
    </Info>
  </Step>

  <Step title="Configure Starburst Galaxy connection">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Starburst Galaxy** and provide the following connection details:

    * **Host:** Your Galaxy cluster hostname (from Step 1)
    * **Username:** Your Galaxy username
    * **Password:** Your Galaxy password
    * **Port:** 443 (default for Galaxy)
  </Step>

  <Step title="Configure Advanced Sync Engine (Optional)">
    For enhanced performance, set up a dedicated CENSUS catalog in Galaxy:

    1. Create a catalog named `CENSUS` containing a schema named `CENSUS`
    2. Ensure your connector supports:
       * `CREATE TABLE` and `DROP TABLE` operations
       * Table writes (INSERT, DELETE, UPDATE)
       * `CREATE OR REPLACE TABLE` statement
    3. Grant full permissions on the `CENSUS.CENSUS` schema to your OneSignal user

    <Info>
      Tested configurations include MySQL, PostgreSQL, Snowflake, Iceberg, and Starburst Galaxy catalogs.
    </Info>
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Query

```sql theme={null}
-- Example: Recent high-value events across Galaxy catalogs
SELECT
    event_name,
    user_id,
    event_timestamp,
    CAST(event_properties AS JSON) as event_properties
FROM catalog.schema.user_events
WHERE event_timestamp >= current_timestamp - INTERVAL '7' DAY
    AND JSON_EXTRACT_SCALAR(event_properties, '$.value') > '100'
ORDER BY event_timestamp DESC;
```

### Cloud Data Lake Queries

```sql theme={null}
-- Example: Federated query across cloud data sources
SELECT
    'cloud_activity' as event_name,
    u.user_id,
    current_timestamp as event_timestamp,
    JSON_FORMAT(JSON_OBJECT(
        's3_interactions', s.interaction_count,
        'snowflake_orders', sf.order_count,
        'bigquery_analytics', bq.score_value
    )) as event_properties
FROM s3_catalog.users.profiles u
LEFT JOIN s3_catalog.interactions.summary s ON u.user_id = s.user_id
LEFT JOIN snowflake_catalog.orders.summary sf ON u.user_id = sf.user_id
LEFT JOIN bigquery_catalog.analytics.scores bq ON u.user_id = bq.user_id
WHERE u.created_date >= current_date - INTERVAL '30' DAY;
```

***

## Sync Engine Options

### Basic Sync Engine

* Works with any Galaxy catalog and connector
* State tracking managed by OneSignal infrastructure
* Simpler setup with no additional requirements

### Advanced Sync Engine

* Enhanced performance with local state tracking
* Requires dedicated `CENSUS.CENSUS` catalog and schema
* Supports connectors with table write operations
* Recommended for high-volume cloud event processing

***

## Supported Connectors

OneSignal's Advanced Sync Engine has been tested with:

* **MySQL connector** (read-write mode)
* **PostgreSQL connector** (read-write mode)
* **Snowflake connector** (read-write mode)
* **Iceberg connector** (with S3 and AWS Glue)
* **Starburst Galaxy catalog** (native Galaxy storage)

***

## Cloud Platform Features

### Multi-Cloud Federation

* Query across AWS, Azure, and GCP data sources
* Combine S3, Snowflake, BigQuery, and Azure data
* Unified event analytics across cloud providers

### Managed Infrastructure

* Fully managed Trino clusters with auto-scaling
* Built-in security and compliance features
* No infrastructure management required

### Galaxy-Native Catalogs

* High-performance native Galaxy storage
* Seamless integration with Galaxy ecosystem
* Optimized for cloud analytics workloads

***

## Limitations

* TLS connection required (built-in for Galaxy)
* Advanced Sync Engine requires `CREATE OR REPLACE TABLE` support
* Warehouse Writeback not yet supported (coming soon)
* Cannot provide custom table options in `WITH` clause

***

## FAQ

### How do I get my Galaxy cluster hostname?

In your Starburst Galaxy console, go to your cluster's connection details and copy the JDBC URL. Extract just the hostname portion (without `jdbc:trino://` prefix) for use in OneSignal.

### Can I query multiple cloud data sources?

Yes! Starburst Galaxy's federated query capabilities allow you to combine event data from multiple cloud sources (S3, Snowflake, BigQuery, etc.) in a single query.

### Does Galaxy support auto-scaling for OneSignal workloads?

Yes, Starburst Galaxy automatically scales clusters based on query load, ensuring optimal performance for your OneSignal event processing without manual intervention.


# Subscription trends
Source: https://documentation.onesignal.com/docs/en/subscription-trends

Track how subscriptions grow and decline over time by channel in OneSignal. Monitors total subscribed count and opt-in and opt-out activity across push, email, SMS, and in-app channels.

The **Subscription Trends** charts on the OneSignal dashboard show how Subscriptions — each device or channel a user can receive messages on — subscribe and unsubscribe over time, broken down by channel.

Subscription Trends track opt-in and opt-out activity. They do not track message engagement like opens or clicks. Use [Engagement Trends](./engagement-analytics) for that.

Navigate to **Dashboard > Analytics > Subscription Trends** to view these charts.

## Charts

Subscription Trends presents two charts.

### Total subscribed

The **Total subscribed** chart shows the cumulative count of Subscriptions that can currently receive messages. The headline number reflects the latest value in the selected time range, not a sum across the period.

<Frame>
  <img alt="Total subscribed chart showing cumulative subscribed count over time" />
</Frame>

| Metric               | Description                                                                                                                                                                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Total subscribed** | The count of all subscribed Subscriptions. Counts will fluctuate as users install and uninstall your app, clear browser data, subscribe and unsubscribe to your messages, or get deleted. For details on how these events are tracked, see [Subscriptions](./subscriptions). |

### Subscription status changes

The **Subscription Status Changes** chart tracks opt-in and opt-out activity using two tabs. Select a tab to view subscribes or unsubscribes independently.

<Note>
  The Subscription Status Changes chart requires a paid plan. Free plan accounts see an upsell prompt in place of the chart.
</Note>

<Frame>
  <img alt="Subscription Status Changes chart with Subscribes and Unsubscribes tabs" />
</Frame>

| Tab              | Description                                                                                                                                                                                                     |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Subscribes**   | The count of subscription status changes from unsubscribed to subscribed. This includes newly created subscribed Subscriptions and current Subscriptions that subscribed to messages in the selected timeframe. |
| **Unsubscribes** | The count of subscription status changes from subscribed to unsubscribed. This does not include newly created Subscriptions that never subscribed or denied the push prompt.                                    |

## What to track

Use Subscription Trends to monitor:

* Growth or decline in your subscribed audience over time
* The impact of permission prompts on new subscribes
* Unsubscribe spikes following campaigns

## FAQ

### What is a Subscription?

A Subscription represents a single device or channel through which a user can receive messages — for example, a push token for a mobile device, an email address, or a phone number for SMS. A single user can have multiple Subscriptions. See [Subscriptions](./subscriptions) for the full definition.

### Why does my Total subscribed count fluctuate?

Total subscribed reflects the live count of subscribed Subscriptions. It changes as users install or uninstall your app, clear browser data, subscribe or unsubscribe from messages, or get deleted from the system. See [Subscriptions](./subscriptions) for how these lifecycle events are tracked.

### Does Unsubscribes include users who denied the push prompt?

No. Unsubscribes counts status changes from subscribed to unsubscribed. Users who deny the push prompt are never subscribed, so they are not counted here.

## Related

<Columns>
  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    Learn how Subscriptions are created, stored, and marked as subscribed or unsubscribed.
  </Card>

  <Card title="Engagement trends" icon="chart-line" href="./engagement-analytics">
    Track message sends, opens, clicks, and unsubscribes over time.
  </Card>

  <Card title="Analytics overview" icon="chart-line" href="./analytics-overview">
    Tour the dashboards, APIs, and export tools OneSignal provides for measuring performance.
  </Card>

  <Card title="Users" icon="user" href="./users">
    Users can have multiple Subscriptions and are identified by their External ID.
  </Card>
</Columns>


# Subscriptions
Source: https://documentation.onesignal.com/docs/en/subscriptions

Manage Subscriptions across mobile push, web push, email, and SMS in OneSignal. Covers properties, statuses, and how to update or migrate them.

## Overview

A **Subscription** represents a specific channel a user can receive messages through—such as an email address, phone number, or device. OneSignal supports four types of Subscriptions:

| Subscription type | Can receive                                                     |
| ----------------- | --------------------------------------------------------------- |
| **Email**         | Email messages                                                  |
| **SMS**           | SMS, MMS, and RCS messages                                      |
| **Web Push**      | Web push notifications                                          |
| **Mobile**        | Mobile push notifications, In-app messages, and Live Activities |

Each user can have multiple Subscriptions. Use the [External ID](./users#external-id) to identify the user across all Subscriptions.

<Frame>
  <img alt="Subscriptions page showing Email, SMS, Web Push, and Mobile subscriptions linked by External ID" />
</Frame>

In the image above, "userA" has 5 Subscriptions:

1. **Mobile** (iOS) created after installing the iOS app. Call `OneSignal.login` to set the External ID and link the Subscription to the user.
2. **SMS** created after the phone number was provided within the iOS app. See [SMS Subscriptions](#sms-subscriptions) below for details.
3. **Web Push** created after subscribing to push on the website. Can receive push notifications.
4. **Email** created after the email address was provided. For sending email messages.
5. **Mobile** (Android) created after installing the Android app. Can receive push notifications, in-app messages, and live activities.

<Note>
  A user can have a maximum of 20 Subscriptions. If a 21st is added, OneSignal removes the External ID from the oldest Subscription (based on last session) and assigns it a new OneSignal ID—effectively creating a new anonymous user for the inactive Subscription.

  However, OneSignal ensures at least 3 Email and 3 SMS Subscriptions (if applicable) are retained.

  See [Users](./users) for details.
</Note>

<Frame>
  <iframe title="YouTube video player" />
</Frame>

***

## Subscription properties

Each Subscription has the following properties:

|         Property        | Description                                                                                                                                                                                                                                                                                                                   |
| :---------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|       **Channel**       | Type of Subscription: `Email`, `SMS`, or `Push`. Push can be Mobile (iOS, Android, etc.) or Web. Only Mobile Push Subscriptions support in-app messages.                                                                                                                                                                      |
| **Subscription Status** | Indicates if the Subscription can receive messages. See [Subscription status](#subscription-statuses) for more details.                                                                                                                                                                                                       |
|     **Last Session**    | Timestamp of the last session tracked by the OneSignal SDK. For Email/SMS, it's based on the most recent push Subscription.                                                                                                                                                                                                   |
|    **Usage Duration**   | Total time (in seconds) the Subscription was active on the app or site tracked by the OneSignal SDK. Only tracked when session exceeds 60s.                                                                                                                                                                                   |
|       **Sessions**      | Count of how many times the app/site was opened. A new session starts after 30+ seconds of being out-of-focus.                                                                                                                                                                                                                |
|    **First Session**    | Timestamp when the first Subscription for the User was created.                                                                                                                                                                                                                                                               |
|      **IP Address**     | Network location when using OneSignal SDKs. Not collected in the EU. See [Handling Personal Data](./handling-personal-data).                                                                                                                                                                                                  |
|   **Subscription ID**   | UUID representing the specific Subscription. Used for identifying the Subscription.                                                                                                                                                                                                                                           |
|     **OneSignal ID**    | UUID representing the User. See [Users](./users).                                                                                                                                                                                                                                                                             |
|     **External ID**     | Your custom user ID. Helps link multiple Subscriptions to the same user.                                                                                                                                                                                                                                                      |
|        **Device**       | The device model the Subscription was created with. For example, `armv81` for web push browsers are Android devices.                                                                                                                                                                                                          |
|        **Email**        | Only set for Email Subscriptions.                                                                                                                                                                                                                                                                                             |
|     **Phone Number**    | Only set for SMS Subscriptions. Must be in [E.164 format](https://en.wikipedia.org/wiki/E.164).                                                                                                                                                                                                                               |
|     **App Version**     | From SDK: Android `versionCode`, iOS `CFBundleShortVersionString`.                                                                                                                                                                                                                                                            |
|     **SDK Version**     | Version of the OneSignal SDK used. See [GitHub > SDKs (select your SDK) > Releases](https://github.com/OneSignal/sdks).                                                                                                                                                                                                       |
|     **Timezone ID**     | From the device at time of last interaction.                                                                                                                                                                                                                                                                                  |
|       **Country**       | Derived from IP address.                                                                                                                                                                                                                                                                                                      |
|    **Location Point**   | Latitude/longitude if location tracking is enabled. See [Location-triggered notifications](./location-triggered-event).                                                                                                                                                                                                       |
|    **Language Code**    | From the device at time of Subscription creation. See [Multi-language messaging](./multi-language-messaging).                                                                                                                                                                                                                 |
|         **Tags**        | Custom key-value metadata. See [Tags](./add-user-data-tags).                                                                                                                                                                                                                                                                  |
|      **Push Token**     | Platform token used for push delivery (e.g., APNS or FCM). Only for Push Subscriptions.<br />- **iOS Push APNS token format**: 64 characters, hexadecimal characters only (0-9,a-f).<br />- **Android Push FCM token format**: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore. |

### Subscription statuses

Generally, Subscriptions can either receive messages (**Subscribed**) or cannot (**Unsubscribed**). The details vary by channel:

| Status               | Mobile                                                                                                                                                              | Web Push                                                                                                        | Email                                                                                                                                                                       | SMS                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Subscribed**       | User granted push permission. With [iOS Provisional push](./ios-provisional-push-notifications), all iOS Subscriptions start as Subscribed.                         | User clicked "Allow" on the browser permission prompt.                                                          | Email address is valid and user has consented.                                                                                                                              | Phone number is valid and user has consented.                                     |
| **Unsubscribed**     | Cannot receive push, but **can still receive in-app messages**. See [Handling uninstalls & invalid tokens](#handling-uninstalls-unsubscribes--invalid-push-tokens). | Cannot receive push. See [Handling unsubscribes & invalid tokens](#handling-unsubscribes--invalid-push-tokens). | User opted out via [unsubscribe link](./unsubscribe-links-email-subscriptions). Can be [overridden](./email-messaging#send-to-unsubscribed-users) for transactional emails. | User replied "STOP" or other [opt-out keyword](./sms-consent-keyword-management). |
| **Never Subscribed** | User was never prompted or never granted permission.                                                                                                                | User was never prompted or blocked the prompt.                                                                  | N/A                                                                                                                                                                         | N/A                                                                               |

<Info>
  In the API, `invalid_identifier: true` means unsubscribed. Check `notification_types` for more details.
</Info>

***

### `notification_types`

Indicates the Subscription's ability to receive messages, including reasons for failures. Automatically updated via the frontend SDKs or manually via the API. Viewable via the [View User API](/reference/view-user) or [Export CSV](/reference/csv-export).

<Accordion title="Notification Types definitions." icon="circle-chevron-down">
  `1` or positive number = Subscribed.

  * The Subscription can receive messages on this channel.
  * Can be used with `enabled` property if you are enabling messages on behalf of the user. For push Subscriptions, a valid `token` must still be set to receive push notifications. See our SDK setup docs for details.

  `0`, `-99` = Never Subscribed.

  * The Subscription has not subscribed to the channel yet.

  `-2` = Unsubscribed (Opted Out).

  * Set when `optOut()` is called via the SDK, or when `enabled` is set to `false` via the API.
  * The Subscription cannot receive messages on this channel.
  * To re-enable, call `optIn()`. See `optOut` / `optIn` / `optedIn` ([mobile](./mobile-sdk-reference#optout-optin-optedin) | [web](./web-sdk-reference#optout-optin-optedin)) for details.

  `-3`, `-5` = Android `Support Library Error`.

  Add or update your app's [Android Support Library](https://developers.google.com/android/).

  `-4`, `-8`, `-11`, `-12` = Android `Google Play Services Library Error`.

  * Check the logcat. See [Getting a Debug Log](./capturing-a-debug-log).
  * Upgrade your [Google Play Services Library](https://developers.google.com/android/) in your app and check the app's logcat for Google Play Services errors. See [Getting a Debug Log](./capturing-a-debug-log).

  `-6` = Android `Invalid Google Project Number`.

  * The FCMv1 Sender ID doesn't match the original in which this `token` belongs. Check the app's logcat. See [Getting a Debug Log](./capturing-a-debug-log).

  `-7`, `-9` = Android `Outdated Google Play Services App`

  * Update or enable the Google Play Services app on the device.

  `-10` = Not Subscribed.

  * Push Subscription uninstalled app or unsubscribed in device settings.
  * Web push blocked notifications, cleared all data and workers.

  `-13` = iOS `missing_push_capability`.

  * Review the SDK setup docs to make sure all steps are implemented. See [Channel setup](./channel-setup).

  `-14`, `-16`, `-17` = iOS `APNS Errors`.

  * The device is having an issue connecting to APNS. Check the [Troubleshooting iOS](./mobile-troubleshooting) guide and [Getting a Debug Log](./capturing-a-debug-log).

  `-15` = iOS `Simulator Error`.

  * iOS Simulator requires iOS 16.4+. Use a different simulator or device.

  `-18` = Never Prompted.

  * The Subscription was never prompted to subscribe. This only tracks the required permission prompt and does not include in-app messages.

  `-19` = Prompted But Never Answered.

  * The Subscription was prompted but didn't provide an answer.

  `-20`, `-21` = temp\_web\_record. Web, `pushSubscriptionchange` permission revoked

  `-22` = Manually Unsubscribed via dashboard.

  * Permission was revoked.

  `-23`, `-24` = Web `Service Worker Error`.

  * See [Web SDK troubleshooting](./troubleshooting-web-push).

  `-31` = Disabled via REST API.

  `-98` = SMS Subscription awaiting double opt-in.
</Accordion>

***

## Mobile Subscriptions

Mobile Subscriptions represent iOS, Android, Huawei, or Amazon devices and support:

* Push notifications
* In-app messages
* Live Activities

They're automatically created when a user installs and opens your app with the OneSignal SDK.

<Note>
  Each mobile Subscription is tied to the device & push token it was created on. If your app is uninstalled and reinstalled on the same device, a new Subscription will be generated.

  Call [`OneSignal.login`](./mobile-sdk-reference#login-external-id) each time the user opens the app to make sure the [External ID](./users#external-id) is set and the Subscription is linked to the user.
</Note>

### Updating mobile Subscriptions

Update Mobile Subscription properties using the [OneSignal mobile SDK](./mobile-sdk-reference).

* [Prompt for push permissions](./prompt-for-push-permissions) and [observe permission/Subscription changes](./mobile-sdk-reference#addobserver-push-subscription-changes)
* [Login users](./mobile-sdk-reference#login-external-id) to set External ID and Aliases
* Add [Tags](./add-user-data-tags)
* Set [Language](./multi-language-messaging)

You can update tags, language, and some other properties via the [CSV Import](./import) feature.

Mobile Subscriptions can be created and updated via the [Users](/reference/create-user) and [Subscriptions](/reference/create-subscription) APIs as well, but the mobile SDK is recommended for most use cases.

### Handling uninstalls, unsubscribes, & invalid push tokens

Mobile Subscriptions stop receiving push notifications if the user:

* Uninstalls the app
* Disables push in device settings and never reopens the app
* [Push token expires](./fcm-expired-token-faq)

In these cases, the Subscription status will be set to **Unsubscribed** when sending push notifications. See below [When do push Subscription statuses update?](#when-do-push-subscription-statuses-update) for more details.

* If the user re-installs the app on the same device or new device, a new Subscription will be created and they need to re-subscribe to receive messages.
* If the user re-enables push in the device settings, the Subscription status will be set to **Subscribed** and a push token will be updated when they open the app.
* If the push token expires, the Subscription status and new push token will update when the user opens the app on the same device.

Track changes via:

* [Event Streams](./event-streams) - detect unsubscribes when sending push
* [Push reports](./push-notification-message-reports) - detect unsubscribes when sending push
* Use the SDK’s [Subscription change listener](./mobile-sdk-reference#addobserver-push-subscription-changes) - detect unsubscribes when user disables push in device settings then opens the app

***

## Web push Subscriptions

Web push Subscriptions are tied to a specific device, browser, and browser profile. A user who subscribes on Chrome desktop will not receive push on Chrome mobile unless they also subscribe to your website from that mobile device—creating a separate web push Subscription.

New web push Subscriptions are created in these scenarios:

* User subscribes to your website by clicking "Allow" on the browser's system-level [native permission prompt](./permission-requests). This generates a unique push token and Subscription ID.
* User clears browser data (history, cache, cookies, local storage) and revisits your site. This results in a new unique Subscription ID being created.

<Note>
  Web push Subscription IDs will never change. However, new Subscription IDs will be created if the user clears browser data and returns to the site or subscribes on a different browser/browser profile.

  Call [`OneSignal.login`](./web-sdk-reference#login-external-id) each time the user opens the site or within the [Subscription change listener](./web-sdk-reference#addeventlistener-push-subscription-changes) to make sure the [External ID](./users#external-id) is set and the Subscription is linked to the user.
</Note>

### Updating web push Subscriptions

Update web push Subscription properties using the [OneSignal web SDK](./web-sdk-reference).

* [Prompt for push permissions](./permission-requests) and [observe permission/Subscription changes](./web-sdk-reference#addeventlistener-push-subscription-changes)
* [Login users](./web-sdk-reference#login-external-id) to set External ID and Aliases
* Add [Tags](./add-user-data-tags)
* Set [Language](./multi-language-messaging)

You can update tags, language, and some other properties via the [CSV Import](./import) feature.

Web push Subscriptions cannot be created via the REST API. You can update them with the [Users](/reference/update-user) and [Subscriptions](/reference/update-subscription) APIs, but the web SDK is recommended for most use cases.

### Handling unsubscribes & invalid push tokens

Web push Subscriptions stop receiving push notifications if the user:

* Clears browser data (history, cache, cookies, local storage)
* Disables push in the browser system settings
* [Push token expires](./fcm-expired-token-faq)

In these cases, the Subscription status will be set to **Unsubscribed** when sending push notifications. See below [When do push Subscription statuses update?](#when-do-push-subscription-statuses-update) for more details.

* If the user returns to the site after clearing browser data, a new Subscription will be created and they will be automatically re-subscribed to receive messages if you have [auto-resubscribe enabled](./web-push-setup#auto-resubscribe).
* If the user re-enables push in the browser settings, the Subscription status will be set to **Subscribed** when they return to the site.
* If the push token expires, the Subscription status and new push token will update when the user returns to the site.

<Warning>
  Chromium put out a [blog post](https://blog.chromium.org/2025/10/automatic-notification-permission.html?m=1) in October 2025, regarding a change that will **automatically revoke push permissions** for users with low site engagement who are being sent a high volume of notifications. The threshold for when a user is considered to have a [low engagement score](https://www.chromium.org/developers/design-documents/site-engagement/), appears to be about 30 days of inactivity. When revoked, the end user should receive a notification from Chrome directly.
</Warning>

Track changes via:

* [Event Streams](./event-streams) - detect unsubscribes when sending push
* [Push reports](./push-notification-message-reports) - detect unsubscribes when sending push
* Use the SDK’s [Subscription change listener](./web-sdk-reference#addeventlistener-push-subscription-changes) - detect unsubscribes when user disables push then returns to the site

***

## Email Subscriptions

Email Subscriptions are based on the email address and used only for email delivery. This is different from setting a [Tag](./add-user-data-tags).

Create Email Subscriptions via:

1. SDK `addEmail` method or [email prompt](./permission-requests) - use these methods after calling `OneSignal.login` to set the External ID and link the Subscription to the user.
2. [Create user API](/reference/create-user) or [Create email API](/reference/email)
3. Dashboard [CSV Importer](./import) or manually add email addresses

<Note>
  Emails are unique per app. Deleting and re-adding the same email creates a new Subscription ID.

  It is recommended to include the `external_id` when creating email Subscriptions to link them to a [User](./users).
</Note>

### Managing email Subscriptions

**Link to a user**

Make sure to set the `external_id` when creating email Subscriptions to link them to a [User](./users).

* Using the SDK, call the `login` method before calling `addEmail` to set the `external_id` and link the email Subscription to the user.
* Using the CSV Importer or REST API, set the `external_id` identifier with the email.

**Subscription statuses**

Newly created email Subscriptions will automatically be set to **Subscribed** unless otherwise specified.

Email Subscriptions can become unsubscribed when:

* Sending emails, the user opts-out via the [Unsubscribe link](./unsubscribe-links-email-subscriptions)
* Setting `enabled` to `false` via the API
* Using the dashboard to unsubscribe the Subscription via the options button
  Email Subscriptions can become resubscribed via:
* Setting `enabled` to `true` via the API
* Using the dashboard to subscribe the Subscription via the options button

If a user unsubscribes from emails, you can keep them as unsubscribed but send them important emails by [sending to unsubscribed emails](./email-messaging#send-to-unsubscribed-users).

***

## SMS Subscriptions

SMS Subscriptions are tied to [E.164 formatted phone numbers](https://en.wikipedia.org/wiki/E.164) (e.g., `+14155551234`).

Create SMS Subscriptions via:

1. SDK `addSms` method or [SMS prompt](./permission-requests) — call `OneSignal.login` first to set the External ID and link the Subscription to the user.
2. [Create user](/reference/create-user) or [Create SMS](/reference/sms) API
3. Dashboard [CSV Importer](./import)

<Note>
  Phone numbers are unique per app. Re-adding after deletion creates a new Subscription ID.

  Include the `external_id` when creating SMS Subscriptions to link them to a [User](./users).
</Note>

### Managing SMS Subscriptions

**Link to a user**

Set the `external_id` when creating SMS Subscriptions to link them to a [User](./users).

* Using the SDK, call the `login` method before calling `addSms` to set the `external_id` and link the SMS Subscription to the user.
* Using the CSV Importer or REST API, set the `external_id` identifier with the phone number.

**Subscription statuses**

Newly created SMS Subscriptions are automatically set to **Subscribed** unless otherwise specified.

SMS Subscriptions can become unsubscribed when:

* The user replies with "STOP" or another [opt-out keyword](./sms-consent-keyword-management)
* You set `enabled` to `false` via the API
* You unsubscribe the Subscription in the dashboard via the options button

SMS Subscriptions can become resubscribed when:

* The user replies with "START" or another [opt-in keyword](./sms-consent-keyword-management)
* You set `enabled` to `true` via the API
* You resubscribe the Subscription in the dashboard via the options button

<Warning>
  Re-subscribing an SMS Subscription without the user's consent violates carrier compliance rules (TCPA, CTIA) and can result in carrier filtering or account suspension.
</Warning>

***

## Importing or migrating Subscriptions

Import push tokens, email addresses, and phone numbers from another provider using:

* [Create user API](/reference/create-user)
* [Create Subscription API](/reference/create-subscription)

<Card title="Migrating to OneSignal" icon="arrow-right-to-bracket" href="./migrating-to-onesignal">
  Import push tokens, emails, and phone numbers from another provider.
</Card>

***

## Delete Subscriptions

Subscriptions can be deleted for:

* Data privacy
* Cleaning up inactive records

<Card title="Delete users" icon="trash" href="./delete-users">
  Remove Subscriptions and user data for privacy or cleanup.
</Card>

<Note>
  Subscriptions with no activity for 18+ months are automatically deleted on Free plans.
</Note>

***

## Finding Subscriptions

The easiest way to find a Subscription is through the OneSignal dashboard. If you already know the user's External ID, email, or phone number, search for it directly in **Audience > Subscriptions**.

### Search by last active

If you don't know the user's ID, you can find your device by activity:

1. Open your app or site on the device you want to find. Make sure OneSignal is initialized (code actively running).
2. In the OneSignal dashboard, go to **Audience > Subscriptions**.
3. Sort by **Last Active** (arrow pointing up) to see the most recently active devices at the top.

### Verify it is your device

If multiple Subscriptions appear, use the **Displayed Columns** filter at the top-right to show additional columns that help identify your device:

| Column                | What to check                                                                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **External ID**       | Should match the ID in your database for this user.                                                                                                                  |
| **Last Active**       | Should reflect the time you just opened the app or site. Refresh the page to update.                                                                                 |
| **First Session**     | The first time the device subscribed. Useful if you just subscribed for the first time.                                                                              |
| **IP Address**        | If enabled, compare with your IP at [whatismyipaddress.com](https://whatismyipaddress.com/). See [Data collected by the SDK](./data-collected-by-the-onesignal-sdk). |
| **Tags**, **Country** | Helpful if you set a known tag like `user_name` or `email` on this device.                                                                                           |
| **Device**            | Shows browser and version for web, or device model and OS version for mobile apps.                                                                                   |

### Find by segment tag

If you added a specific tag to the user (e.g., `user_name` or another identifier), you can create a [segment with the User Tag filter](./segmentation#creating-segments) to isolate that device.

<Frame>
  <img alt="Segment builder with a user tag filter to find a specific device" />
</Frame>

### Find Subscription ID programmatically

For developers who need the Subscription ID directly from code:

<Accordion title="Web Push (browser console)">
  1. Open your site in the browser profile that is subscribed to push.
  2. Open the browser console (F12 or right-click > **Inspect** > **Console**).
  3. Run: `OneSignal.User.PushSubscription.id`
  4. The Subscription ID is logged to the console.

  For mobile web, connect your Android device via USB and use `chrome://inspect/#devices` to open a remote console session.
</Accordion>

<Accordion title="Mobile app (Xcode / Android Studio)">
  Use the OneSignal SDK [User Data Methods](./mobile-sdk-reference) to log the Subscription ID to the console from Xcode or Android Studio.
</Accordion>

***

## FAQ

### Why can't I find my Subscription in the dashboard?

The most common causes are:

* The OneSignal SDK is not initialized on the page or screen you are using.
* You are searching by the wrong ID type. Try searching by email, phone number, or Subscription ID instead.
* The Subscription was created in a different OneSignal app (e.g., staging vs. production).

### When do push subscription statuses update?

Push subscription statuses update through two mechanisms:

**1. When the user opens your app or site**

The OneSignal SDK checks whether the push token is valid and whether notification permissions are still granted, then updates the subscription status immediately.

For example, if a user disables push notifications in their device settings and then reopens your app, the SDK detects the change and marks the subscription as **Unsubscribed** right away.

You can capture these changes with the SDK's Subscription Observer ([mobile](./mobile-sdk-reference#addobserver-push-subscription-changes) | [web](./web-sdk-reference#addeventlistener-push-subscription-changes)) to sync status to your own database.

**2. When you send push notifications**

If a user uninstalls your app, clears browser data, or disables push **and never returns**, OneSignal cannot detect the change until you send a notification. The push service (FCM, APNs, HMS) reports the token as invalid, and OneSignal marks the subscription as **Unsubscribed**.

This detection typically takes 2 or more messages because the push service does not immediately reject an invalid token:

| Send       | What happens                                                                                                                                                |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Message 1  | Delivered to device. User then unsubscribes in device settings or uninstalls the app.                                                                       |
| Message 2  | Push service accepts the message but the device does not receive it. OneSignal reports "Delivered" because the push service has not rejected the token yet. |
| Message 3  | Push service rejects the token. OneSignal marks the subscription as **Unsubscribed**.                                                                       |
| Message 4+ | OneSignal does not attempt delivery to this subscription.                                                                                                   |

Use [Event Streams](./event-streams) to detect unsubscribes in real time when sending messages.

<Note>
  If you go long periods without sending to all users, unsubscribes accumulate silently and appear as a large spike when you resume sending. Send to all users at least once or twice a month to detect unsubscribes gradually. See [FCM expired token FAQ](./fcm-expired-token-faq) for more on unsubscribe spikes.
</Note>

<Warning>
  Apple delays unsubscribe reporting by 14+ days. To protect user privacy, Apple does not immediately report uninstalls or permission revocations. If a user opens your app after disabling push, OneSignal detects the change instantly via the SDK. If the user never opens the app again, it may take several weeks for Apple to report the invalid token after you send notifications.

  See [Apple Forum](https://developer.apple.com/forums/thread/670868) and [Technical Note](https://developer.apple.com/library/archive/technotes/tn2265/_index.html#//apple_ref/doc/uid/DTS40010376-CH1-TNTAG34) for details. Use the dashboard or API to [delete old subscriptions](./delete-users) to keep your audience clean.
</Warning>

### A subscription was deleted and a new one was created, why did the user's data come back after they logged in?

When `OneSignal.login` is called with a user's [External ID](./users#external-id), OneSignal links the new subscription to their existing user profile. If a subscription was deleted and a new one was created (for example, after a reinstall), calling `login` with the same External ID re-associates the new subscription with the user's profile. This is working as designed.

Note that there is a difference between deleting a **subscription record** (removes the channel entry but the user profile remains) and deleting the **entire user profile** (removes all subscriptions and user data). See [Delete users](./delete-users) for details.

### If a user turns off notifications in their device settings and never opens the app again, what happens?

The subscription remains marked as **Subscribed** in OneSignal until you send a notification to that device. After 2 or more send attempts, the push service reports the token as invalid and OneSignal marks the subscription as **Unsubscribed**. See [When do push subscription statuses update?](#when-do-push-subscription-statuses-update) above for the full sequence.

***

## Related pages

<Columns>
  <Card title="Users" icon="users" href="./users">
    The OneSignal user model, aliases, and how users relate to Subscriptions.
  </Card>

  <Card title="Test users" icon="flask" href="./test-users">
    Mark a User as a test user to validate message delivery before sending to production.
  </Card>

  <Card title="Delete users" icon="trash" href="./delete-users">
    Remove Subscriptions and user data for privacy or cleanup.
  </Card>

  <Card title="Migrating to OneSignal" icon="arrow-right-to-bracket" href="./migrating-to-onesignal">
    Import push tokens, emails, and phone numbers from another provider.
  </Card>
</Columns>


# Template analytics
Source: https://documentation.onesignal.com/docs/en/template-analytics

Review delivery statistics, engagement metrics, and audience activity for push, email, and SMS templates in OneSignal.

Template analytics show how your push, email, and SMS templates perform — delivery outcomes, engagement metrics, and per-recipient activity. Open a template report by clicking any template in the dashboard. To modify the template, click **Edit**.

<Note>
  Template analytics are retained for up to 2 years depending on your [pricing plan](https://onesignal.com/pricing). Per-recipient audience activity data is retained for 30 days from the time the message is sent.
</Note>

## How to access and use template analytics

<Steps>
  <Step title="Go to Templates">
    In your OneSignal dashboard, navigate to **Messages > Templates**.

    Select a template that has been used for at least one send, or create a new template and send a test message.
  </Step>

  <Step title="Review analytics and statistics">
    The template report displays performance metrics and delivery statistics, organized by channel (push, email, or SMS).

    Use these metrics to monitor engagement, troubleshoot delivery issues, and evaluate template effectiveness.
  </Step>

  <Step title="Edit or export data">
    Click **Edit** at the top of the report to modify the template.

    Click **Export** to download per-recipient activity as a CSV.
  </Step>
</Steps>

## Template statistics by channel

Each channel reports its own delivery and engagement metrics. For canonical metric definitions across all channels, see the [Metrics glossary](./analytics-metrics-glossary).

<Tabs>
  <Tab title="Push">
    ### Summary

    | Name                                | Description                                                                                                                                                               |
    | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Delivered                           | The number of push notifications successfully sent to and accepted by the push provider (FCM, APNs, HMS).                                                                 |
    | Click-Through Rate (CTR)            | `(Clicked / Delivered) × 100`.                                                                                                                                            |
    | Confirmed Click-Through Rate (CCTR) | `(Clicked / Confirmed Receipt) × 100`.                                                                                                                                    |
    | Influenced Opens                    | Users who opened the app within the influenced time window without directly clicking the notification. Configure this in **Settings > Push & In-app > Influenced Opens**. |

    ### Delivery statistics

    | Name              | Description                                                                                                                                                                                                                                                                                                                                                                                          |
    | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Sent              | The number of push notifications sent from OneSignal, including both those successfully sent to the push provider and failures. Composite metric.                                                                                                                                                                                                                                                    |
    | Delivered         | The number of push notifications successfully sent to and accepted by the push provider (FCM, APNs, HMS).                                                                                                                                                                                                                                                                                            |
    | Confirmed Receipt | The number of push notifications confirmed as received by the device, verified by the OneSignal SDK. Several factors can affect this count — see [Confirmed receipt](./confirmed-delivery).                                                                                                                                                                                                          |
    | Unsubscribed      | The number of push Subscriptions that did not receive the push notification because they uninstalled the app, cleared browser data, or opted out of push. OneSignal does not attempt to send to these Subscriptions in future messages. Older tokens may also expire — see [FCM expired tokens](./fcm-expired-token-faq) and [unsubscribe causes](./push-notification-message-reports#unsubscribed). |
    | Failed            | The number of push Subscriptions that did not receive the push notification because of an error. See [push error reference](./push-notification-message-reports#failed) for common causes.                                                                                                                                                                                                           |
    | Remaining         | The number of Subscriptions in the target audience that haven't yet received the push notification (queued or in flight).                                                                                                                                                                                                                                                                            |
    | Frequency Capped  | The number of push Subscriptions that did not receive the push notification due to [frequency cap](./frequency-capping) settings.                                                                                                                                                                                                                                                                    |

    ### Conversion statistics

    <Info>
      **Coming soon** — [Conversion metrics](./conversion-metrics) will be available on template reports. Once available, you will see attributed and influenced conversions aggregated across all messages sent from this template.
    </Info>

    ### Outcome statistics (legacy)

    <Warning>
      Custom Outcomes is being deprecated and replaced by [Conversion metrics](./conversion-metrics).
    </Warning>

    | Name              | Description                                                                                                                                                                                                                    |
    | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | Clicks            | Direct clicks or opens on the push message. Always measured with direct attribution.                                                                                                                                           |
    | Confirmed Receipt | The number of push notifications confirmed as received by the device. See [Confirmed receipt](./confirmed-delivery). [Paid plan required](https://onesignal.com/pricing).                                                      |
    | Sessions          | Count or cumulative duration (in seconds) of app sessions attributed to this push. A new session starts only after the app has been out of focus for 30+ seconds. [Professional plan required](https://onesignal.com/pricing). |
    | Custom Outcomes   | Custom metrics like purchase amount or user actions, configured in your app code. See [Custom Outcomes](./custom-outcomes).                                                                                                    |
  </Tab>

  <Tab title="Email">
    ### Summary

    | Name                     | Description                                                                                                                                   |
    | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
    | Open Rate                | `(Unique Opens / Delivered) × 100`. User privacy settings may affect open tracking — see [Why are open events low?](#why-are-open-events-low) |
    | Click-Through Rate (CTR) | `(Unique Clicks / Delivered) × 100`. Requires [click tracking enabled](./unsubscribe-links-email-subscriptions).                              |
    | Unsubscribed             | The number of recipients who opted out via the unsubscribe link in this email.                                                                |

    ### Delivery statistics

    | Name         | Description                                                                                                                                                                              |
    | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Audience     | The number of Subscriptions in the targeted Segment(s).                                                                                                                                  |
    | Sent         | The number of emails sent from OneSignal, including both those successfully sent to the email service provider and failures. Composite metric.                                           |
    | Delivered    | The number of emails successfully delivered to the recipient's inbox server.                                                                                                             |
    | Remaining    | The number of Subscriptions in the target audience that haven't yet received the email (queued or in flight).                                                                            |
    | Total Clicks | The total number of times a link in the email was clicked, including repeats. See [URLs, links and deep links](./links).                                                                 |
    | Total Opens  | The total number of times the email was opened, including repeats. Privacy settings may affect this — see [Why are open events low?](#why-are-open-events-low)                           |
    | Unsubscribed | The number of recipients who opted out via the unsubscribe link.                                                                                                                         |
    | Bounced      | The number of emails rejected due to invalid addresses, full inboxes, sender reputation, or DMARC issues. Bounced addresses are added to the [suppression list](./email-deliverability). |
    | Failed       | The number of emails unable to be delivered to the inbox, excluding bounces. See [Why are emails marked as failed?](#why-are-my-emails-marked-as-failed)                                 |
    | Suppressed   | The number of emails blocked due to prior bounces or spam reports to protect sender reputation. Only recorded for apps configured to use [OneSignal Email](./email-setup).               |

    <Note>
      Email templates do not currently support Conversion metrics or Custom Outcomes.
    </Note>
  </Tab>

  <Tab title="SMS">
    ### Summary

    | Name          | Description                                                                                         |
    | ------------- | --------------------------------------------------------------------------------------------------- |
    | Delivery Rate | `(Delivered / Sent) × 100`.                                                                         |
    | Failure Rate  | `(Failed / Sent) × 100`. For a combined view of carrier rejections, also review **Rejected** below. |

    ### Delivery statistics

    | Name       | Description                                                                                                                            |
    | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
    | Audience   | The number of Subscriptions in the targeted Segment(s).                                                                                |
    | Sent       | The number of messages sent from OneSignal, including both those successfully sent to Twilio and failures. Composite metric.           |
    | Delivered  | The number of messages successfully delivered to the carrier as reported by Twilio.                                                    |
    | Failed     | The number of messages that failed to be sent to Twilio.                                                                               |
    | Suppressed | The number of messages not sent to the Subscriptions because they opted out of receiving messages from the sender.                     |
    | Rejected   | The number of messages not delivered by the carrier due to number blockage, velocity blockage, or the recipient being on a block list. |

    <Note>
      **Sent** and **Delivered** on SMS both represent upstream confirmations (OneSignal → Twilio, Twilio → carrier). Neither guarantees the recipient's device has received the message.
    </Note>

    <Note>
      SMS templates do not currently support Conversion metrics or Custom Outcomes.
    </Note>
  </Tab>
</Tabs>

## Audience activity

Audience activity reports break down each recipient's delivery result so you can segment for retargeting and monitor Subscription health.

<Tabs>
  <Tab title="Push">
    * Lists each Subscription and its delivery result (sent, confirmed, clicked, failed, unsubscribed).
    * Click **Export** to download the full Subscription list.
    * A dash or blank entry in the **Device** column means the Subscription has since been deleted.
  </Tab>

  <Tab title="Email">
    Lists each email Subscription and its status: delivered, opened, clicked, unsubscribed, bounced, failed, or complained. Timestamps reflect the most recent event.

    * **Export** activity data, including failure reasons.
    * **Retarget** users based on activity data to follow up. See [Retargeting messages](./retargeting).
  </Tab>

  <Tab title="SMS">
    Lists each SMS Subscription as sent, delivered, or failed. See [Retargeting messages](./retargeting).
  </Tab>
</Tabs>

<Note>
  Audience activity is retained for 30 days from the time the message is sent.
</Note>

## FAQ

### How long is template data stored?

Template analytics are retained for up to 2 years depending on your plan. Per-recipient audience activity is retained for 30 days. See [Analytics data retention](./billing-faq#analytics-data-retention) for details.

### Why are open events low?

Email open tracking relies on a tracking pixel that loads when the recipient opens the email. Many email clients and privacy features (Apple Mail Privacy Protection, Gmail image proxying) block or pre-fetch this pixel, which under-reports opens. Click tracking is generally a more reliable engagement signal.

### Why are my emails marked as failed?

A "failed" email means OneSignal could not deliver the message and dropped it. Common causes:

* The recipient's email address is invalid or misspelled.
* The recipient's mailbox is full.
* The receiving server rejected the message (for example, content filtering or sender reputation).
* A DNS or authentication issue with your sending domain (SPF, DKIM, DMARC).

Check your [email deliverability settings](./email-deliverability) and sending domain configuration if you see a high failure rate.

### What does "Suppressed" mean?

A suppressed message was intentionally withheld by OneSignal. For email, this happens when the recipient previously reported your email as spam or their address hard-bounced, which protects your sender reputation. For SMS, this happens when the Subscription opted out of receiving messages from the sender. See [Suppressions](./suppressions).

### Can I export audience activity data?

Yes. Click the **Export** button in the Audience Activity section to download a CSV with per-recipient delivery results, including failure reasons and timestamps.

## Related

<Columns>
  <Card title="Metrics glossary" icon="book" href="./analytics-metrics-glossary">
    Full definitions for all analytics metrics across channels.
  </Card>

  <Card title="Push message reports" icon="file-chart-column" href="./push-notification-message-reports">
    Delivery and engagement reports for individual push messages.
  </Card>

  <Card title="Email deliverability" icon="envelope-circle-check" href="./email-deliverability">
    Improve delivery rates and manage bounces, spam reports, and sender reputation.
  </Card>

  <Card title="Templates" icon="copy" href="./templates">
    Create and manage reusable message templates across channels.
  </Card>

  <Card title="Confirmed receipt" icon="circle-check" href="./confirmed-delivery">
    How confirmed receipt tracking works and what affects the count.
  </Card>

  <Card title="Frequency capping" icon="gauge-high" href="./frequency-capping">
    Limit how often users receive messages to reduce fatigue.
  </Card>
</Columns>


# Test users
Source: https://documentation.onesignal.com/docs/en/test-users

Mark a User as a test user in OneSignal to validate message delivery, rendering, and Journey behavior across all of their Subscriptions before sending to production.

A **test user** is a User you designate for testing message delivery. Test users have a dedicated segment filter and can be targeted directly from the message composer, in Journey audiences, and in webhook tests.

The test flag is a User-level property: marking a User as a test user automatically applies to **all** of their Subscriptions under the same test name. You can mark a User as a test user from the User profile, when manually creating a User, from any of their Subscriptions, or through the API.

<Frame>
  <img alt="Options menu on a subscription record with Add as test user highlighted" />
</Frame>

## Mark a User as a test user

### From the User profile

Use this flow when you already know the User and want to mark them as a test user without finding a specific Subscription.

1. Go to **Audience > Users** and open the User's profile.
2. Select **Actions > Add as test user**.
3. Enter a test user name. All Subscriptions linked to this User are added as test users under the same name.

### When manually creating a User

When adding a single User through the dashboard's **New User** form, check **Add as Test User** and provide a name. All Subscriptions created for this User will be marked as test users under that name.

### From a Subscription

Use this flow when you have your device's Subscription ID or want to find your device by activity. Marking a Subscription as a test user marks the underlying User as a test user, which propagates to all of their other Subscriptions.

1. Go to **Audience > Subscriptions** and [find the Subscription](./subscriptions#finding-subscriptions) for the device you want to test with.
2. Next to the Subscription, select **Options > Add as test user**.
3. Enter a test user name.

### Via the API

Set the `test_user_name` property when creating or updating a user with the REST API:

<CodeGroup>
  ```bash Create user theme={null}
  curl -X POST https://api.onesignal.com/apps/YOUR_APP_ID/users \
    -H "Content-Type: application/json" \
    -d '{
      "properties": {
        "test_user_name": "QA Device - Jane"
      }
    }'
  ```

  ```bash Update user theme={null}
  curl -X PATCH https://api.onesignal.com/apps/YOUR_APP_ID/users/by/{alias_label}/{alias_id} \
    -H "Content-Type: application/json" \
    -d '{
      "properties": {
        "test_user_name": "QA Device - Jane"
      }
    }'
  ```
</CodeGroup>

To remove the test user label, set `test_user_name` to an empty string (`""`).

See [Create user](/reference/create-user) and [Update user](/reference/update-user) for the full API reference.

***

## Send to test users

Once a User is marked as a test user, you can send to them from:

* **The message composer**: use the **Test & Preview** action.
* **Journeys** — use a [Test Users segment filter](./segmentation#filters) to scope an entry rule to test users only. See [Journey settings](./journeys-settings).
* **Webhook tests**: Journey webhooks can be validated against test users before going live. See [Journey webhooks](./journeys-webhook).

***

## FAQ

### How do I remove a test user?

From the dashboard:

* **From the User profile:** Open the User and select **Options > Remove as test user**.
* **From the Subscriptions list:** Go to **Audience > Subscriptions**, find any Subscription belonging to the User, then select **Options > Remove from Test Users**.

Either action clears the test flag from the User and all of their Subscriptions. The User and Subscriptions remain in your app, they're just no longer marked as test users.

You can also clear the flag via the API by setting `test_user_name` to `""` on the User.

### What's the difference between a test user and a test subscription?

There is no longer a meaningful difference. Test status is stored on the User, so marking any one Subscription as a test user marks the underlying User as a test user, which applies the flag to all of that User's other Subscriptions. The "Add as test user" entry point on the Subscriptions list is preserved for convenience.

### My test user has a subscription that shows as unsubscribed. How do I re-subscribe them?

The simplest option is to manually re-subscribe on the **User profile > Subscriptions** tab.

<Frame>
  <img alt="User profile Subscriptions tab with the manual re-subscribe option" />
</Frame>

<Warning>
  Re-subscribing a user without their consent violates messaging compliance rules and can result in spam complaints, carrier filtering, or account suspension.
</Warning>

### Why does the same person appear multiple times in the Test Users filter?

Each app reinstall creates a new Subscription. If the new Subscription isn't linked to the existing User via [External ID](./users#external-id), it shows up as a separate User. Call `OneSignal.login` with the same External ID after install to keep all of a person's Subscriptions tied to one User.

### Can I send to test users from the API?

Yes. Use the [Create notification](/reference/create-message) API with `include_subscription_ids` and pass the Subscription IDs of your test devices.

***

## Related pages

<Columns>
  <Card title="Users" icon="users" href="./users">
    The OneSignal user model, aliases, and how Users relate to Subscriptions.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    Manage Subscriptions and find a specific device for testing.
  </Card>

  <Card title="Segmentation" icon="filter" href="./segmentation">
    Build segments, including a Test Users segment, to scope sends.
  </Card>

  <Card title="Create message API" icon="code" href="/reference/create-message">
    Send notifications programmatically to specific Subscription IDs.
  </Card>
</Columns>


# Tags: Time Operators
Source: https://documentation.onesignal.com/docs/en/time-operators

Automate time-based messages using Time Elapsed operators with Tags that store Unix timestamps in seconds.

## Overview

Time Operators let you send messages relative to a specific moment in time—such as **after an action happens** or **before an upcoming date**.

You store that moment as a **Unix timestamp (in seconds)** on the user using a **Tag**. OneSignal then compares the current time to that timestamp and lets you target users based on how much time has passed (or how much time remains).

This makes it easy to automate messages like reminders, follow-ups, and deadlines without scheduling messages manually.

**Common use cases:**

* **[Abandoned cart](./abandoned-cart)**: Remind users who haven't checked out after a certain time
* **Event reminders**: Message users before a scheduled appointment or renewal date
* **Milestones**: Follow up when users haven't completed an action by a deadline
* **Birthdays**: Send messages on (or around) a user's birthday

<Note>
  Time Operators are only available on paid plans. Free plans can still use
  default time-based segment filters like First Session and Last Session.
</Note>

### When should I use this?

Use Time Operators when you want to:

* Send messages **relative to an event**, not at a fixed calendar time
* Create **moving time windows** (for example, “24–48 hours after”)
* Reuse the same logic for many users with different dates
* Continuously evaluate eligibility as time passes

If you need to trigger messaging immediately when an event occurs, consider using **[Custom Events](./custom-events)** instead.

### Tags vs Custom Events

You can solve many "reminder" use cases with either **Tags** or **Custom Events**. The best option depends on what you need to store and how you want to trigger automation.

* Use **Tags** when you want to store the **latest known timestamp** on the user (for example, `cart_updated_at` or `subscription_expires_at`) and segment off that value over time.
* Use **Custom Events** when you want to record **each event occurrence** (with properties) and trigger Journeys based on real-time behavior.

<Info>
  In practice, many implementations can use both: Custom Events for real-time tracking and Tags for user state you want to segment on later.
</Info>

[Tags](/docs/en/add-user-data-tags) and [Custom Events](/docs/en/custom-events) are both ways to add data to your users. However, there are some key differences:

| Feature        |                   Tags                   |                                          Custom Events                                         |
| -------------- | :--------------------------------------: | :--------------------------------------------------------------------------------------------: |
| Data usage     |     Segmentation and personalization     | Trigger Journeys without a Segment, Wait Until steps, personalization directly within Journeys |
| Data retention |                 Lifetime                 |        30+ days ([lifetime storage is available](/docs/en/billing-faq#streaming-events))       |
| Data format    |       Key-value strings or numbers       |                                              JSON                                              |
| Data source    |     OneSignal SDK, API, or CSV import    |                               OneSignal SDK, API, or integrations                              |
| Data access    | Segmentation and message personalization |        Journeys and Journey-message-template personalization, Segmentation (Coming soon)       |

The key distinction between Tags and Custom Events is in their depth and use cases. Tags are properties of a user, such as Name, Account Status, or Location. Events are thing that the user has done, such as Purchasing an Item, Completing a Level, or Inviting a Friend. Both tags and events can be used for segmentation and personalization.

In practice, you will likely use both:

* Tags for user properties that are static and don't change often
* Custom Events for real-time scenarios, complex segmentation, and more sophisticated journey workflows

***

## Quick reference

1. Convert the event date into a Unix timestamp in **seconds**.
2. Set a [Tag](./add-user-data-tags) where the key is the event name and the value is the timestamp as a **string** (e.g., `'event_date': '1739145600'`).
3. Create a segment using the **Time Elapsed Greater Than** operator:
   * After a past date using **Time Elapsed Greater Than** operator with a positive value
   * Before a future date using **Time Elapsed Greater Than** operator with a negative value

<Warning>
  A common mistake is setting timestamps in **milliseconds** (13 digits) instead
  of **seconds** (10 digits). Time Operators require **seconds**.
</Warning>

***

## Send messages after a past event

Use this pattern when you want to message users **after a certain amount of time has passed** since something happened.

**Example: Abandoned cart reminder 24 hours after the user updated their cart**

<Steps>
  <Step title="Store the timestamp when the event happens">
    When the user updates their cart, save the current time as a Unix timestamp (in seconds):

    ```javascript theme={null}
    // SDK example
    const timestampSeconds = String(Math.floor(Date.now() / 1000));
    OneSignal.User.addTag("current_time", timestampSeconds);
    ```

    <Warning>
      Use seconds (10 digits), not milliseconds (13 digits).
    </Warning>
  </Step>

  <Step title="Create a segment">
    1. Go to **Audience** > **Segments**
    2. Add a **User Tag** filter
    3. Set **Key** to `current_time`
    4. Choose **Time Elapsed Greater Than**
    5. Set **Value** to `1` day (or `24` hours or `86400` seconds)

    <Frame>
      <img alt="Segment using Time Elapsed Greater Than" />
    </Frame>
  </Step>

  <Step title="Add an upper limit (Recommended)">
    Without an upper limit, users stay in the segment forever. Add a second filter to create a window:

    * **Time Elapsed Greater Than** `24` hours
    * **Time Elapsed Less Than** `48` hours

    Now users are only in the segment between 24-48 hours after the event.

    <Frame>
      <img alt="Segment with both Time Elapsed Greater Than and Less Than" />
    </Frame>
  </Step>

  <Step title="Use the segment in a Journey">
    Create a [Journey](./journeys-overview) that targets your segment to automate the messaging.
  </Step>
</Steps>

***

## Send messages before a future event

Use this pattern to message users **leading up to a future date**, such as an appointment or renewal.

1. Store the future date as a Unix timestamp tag (e.g., `'future_date': '1739145600'`)
2. Create a segment with **Time Elapsed Greater Than** and your desired entry time as a negative value
   * Example: `-2` days (or `-172800` seconds)

<Frame>
  <img alt="Segment using Time Elapsed Greater Than with a negative value" />
</Frame>

3. Add an upper limit using the same **Time Elapsed Greater Than** operator with a negative value of a closer time
   * Example: `-1` day (or `-86400` seconds)

<Frame>
  <img alt="Segment using Time Elapsed Greater Than with a negative value and an upper limit" />
</Frame>

### Example: Birthday messages

Send birthday messages by storing each user’s **next upcoming birthday** as a timestamp.

<Steps>
  <Step title="Store the next birthday timestamp">
    Calculate and store the user's next upcoming birthday:

    ```javascript theme={null}
    function getNextBirthday(month, day) {
      // month: 0-11 (Jan=0), day: 1-31
      const now = new Date();
      let birthday = new Date(now.getFullYear(), month, day);

      if (birthday <= now) {
        birthday = new Date(now.getFullYear() + 1, month, day);
      }

      return String(Math.floor(birthday.getTime() / 1000));
    }

    // Example: January 15th birthday
    OneSignal.User.addTag("birthday", getNextBirthday(0, 15));
    ```
  </Step>

  <Step title="Create a birthday segment">
    * **User Tag**: `birthday`
    * **Time Elapsed Greater Than**: `0 seconds`

    Users enter the segment once their birthday timestamp passes.

    <Frame>
      <img alt="Birthday segment using Time Elapsed Greater Than 0" />
    </Frame>
  </Step>

  <Step title="Set up a recurring Journey">
    1. Create a [Journey](./journeys-overview) targeting your birthday segment
    2. Set re-entry to **52 weeks** so users can re-enter next year
    3. Update the `birthday` tag to next year's date after sending (in your backend or Journey)
  </Step>
</Steps>

<Note>
  Calculate birthday timestamps using the user’s local timezone when possible.
  Using server time only may cause messages to send earlier or later than
  expected.
</Note>

<Warning>
  If you want messages to stay accurate year-over-year, update the user's
  `birthday` tag to the next upcoming birthday after you send the message (for
  example, in your backend or in a Journey step). Keep in mind, if you do this,
  it may be easier to use [Custom Events](./custom-events) instead.
</Warning>

<Check>
  Birthday messages will be sent to users around their `birthday` tag date.
</Check>

***

## FAQ

### How does the math work? (technical details)

Time Operators exist to let you create **relative, moving windows** instead of fixed dates.

OneSignal calculates elapsed time using this formula:

```
time_elapsed = current_time - tag_timestamp
```

* **Past timestamps** → positive values
* **Future timestamps** → negative values

**Operators:**

* `Time Elapsed Greater Than X`: matches when `elapsed > X`
* `Time Elapsed Less Than X`: matches when `elapsed < X`

**Why future timestamps match immediately with `Less Than`:**

Any negative number is less than any positive number. So `time_elapsed_lt 2 days` (172,800 seconds) will match a timestamp 30 days in the future because:

```
-2,592,000 < 172,800  →  true (matches)
```

Because future timestamps always produce negative elapsed time, **you must use negative values** to define when users should enter and exit segments before an upcoming event. Positive values cannot represent time *before* a future date.

### How can I test?

1. Find your user via the External ID, Subscription ID, Email or Phone number. See [Find and set Test Users](./test-users) for details on finding your user.
2. Get a timestamp in seconds of the current date and a future date (5 minutes from now).
3. Set two tags with the keys 'current\_time' and 'future\_time' and the values as the timestamps in seconds.
4. Create a `current_time` segment with the following filters:
   * **User Tag**: `current_time` **Time Elapsed Greater Than**: `2` minutes
   * AND **User Tag**: `current_time` **Time Elapsed Less Than**: `5` minutes
5. Create a `future_time` segment with the following filters:
   * **User Tag**: `future_time` **Time Elapsed Greater Than**: `-5` minutes
   * AND **User Tag**: `future_time` **Time Elapsed Less Than**: `-2` minutes

You should see your user:

* Enter the `current_time` segment 2 minutes after the current time date and exit the segment 5 minutes after the current time date.
* Enter the `future_time` segment 5 minutes before the future time date and exit the segment 2 minutes before the future time date.

***


# Trino
Source: https://documentation.onesignal.com/docs/en/trino

Sync custom events from Trino to OneSignal to trigger automated Journeys and personalized messaging campaigns based on user behavior.

## Overview

The OneSignal + Trino integration enables syncing of custom events from your Trino cluster to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

Trino is a distributed SQL query engine designed for running fast analytics queries against large datasets from multiple sources.

***

## Requirements

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Trino

* **Trino cluster** with network access
* **User credentials** with appropriate permissions
* **TLS connection** support (required by OneSignal)
* **Event data** accessible through Trino catalogs

***

## Setup

<Steps>
  <Step title="Configure Trino connection">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    Select **Trino** and provide the following connection details:

    * **Host:** Your Trino cluster hostname
    * **Username:** Your Trino username
    * **Password:** Your Trino password
    * **Port:** 443 (default) or your custom port

    <Info>
      OneSignal requires a TLS connection to Trino. If your instance doesn't run on port 443, specify your custom port.
    </Info>
  </Step>

  <Step title="Configure Advanced Sync Engine (Optional)">
    For enhanced performance, set up a dedicated CENSUS catalog:

    1. Create a catalog named `CENSUS` containing a schema named `CENSUS`
    2. Ensure your connector supports:
       * `CREATE TABLE` and `DROP TABLE` operations
       * Table writes (INSERT, DELETE, UPDATE)
       * `CREATE OR REPLACE TABLE` statement
    3. Grant full permissions on the `CENSUS.CENSUS` schema to your OneSignal user

    <Info>
      Tested configurations include MySQL, PostgreSQL, Snowflake, Iceberg, and Delta Lake connectors.
    </Info>
  </Step>
</Steps>

***

### Event data mapping

Map your   to OneSignal's custom events format:

| OneSignal Field | Description       | Required            |     |
| --------------- | ----------------- | ------------------- | --- |
| `name`          | `event_name`      | Event identifier    | Yes |
| `external_id`   | `user_id`         | User identifier     | Yes |
| `timestamp`     | `event_timestamp` | When event occurred | No  |
| `properties`    | `event_data`      | No                  |     |

### Example Event Query

```sql theme={null}
-- Example: Recent high-value events across catalogs
SELECT
    event_name,
    user_id,
    event_timestamp,
    CAST(event_properties AS JSON) as event_properties
FROM catalog.schema.user_events
WHERE event_timestamp >= current_timestamp - INTERVAL '7' DAY
    AND JSON_EXTRACT_SCALAR(event_properties, '$.value') > '100'
ORDER BY event_timestamp DESC;
```

### Cross-Catalog Event Queries

```sql theme={null}
-- Example: Federated query across multiple data sources
SELECT
    'combined_activity' as event_name,
    u.user_id,
    current_timestamp as event_timestamp,
    JSON_FORMAT(JSON_OBJECT(
        'web_sessions', w.session_count,
        'mobile_events', m.event_count,
        'purchase_value', p.total_value
    )) as event_properties
FROM postgres_catalog.users.profiles u
LEFT JOIN web_catalog.analytics.sessions w ON u.user_id = w.user_id
LEFT JOIN mobile_catalog.events.activities m ON u.user_id = m.user_id
LEFT JOIN purchases_catalog.orders.summary p ON u.user_id = p.user_id
WHERE u.created_date >= current_date - INTERVAL '30' DAY;
```

***

## Sync Engine Options

### Basic Sync Engine

* Works with any Trino catalog and connector
* State tracking managed by OneSignal infrastructure
* Simpler setup with no additional requirements

### Advanced Sync Engine

* Enhanced performance with local state tracking
* Requires dedicated `CENSUS.CENSUS` catalog and schema
* Supports connectors with table write operations
* Recommended for high-volume event processing

***

## Supported Connectors

OneSignal's Advanced Sync Engine has been tested with:

* **MySQL connector** (read-write mode)
* **PostgreSQL connector** (read-write mode)
* **Snowflake connector** (read-write mode)
* **Iceberg connector** (with S3 and AWS Glue)
* **Delta Lake connector** (with AWS Glue and Starburst Galaxy catalogs)

***

## Limitations

* TLS connection required (OneSignal security requirement)
* Advanced Sync Engine requires `CREATE OR REPLACE TABLE` support (Trino October 2023+)
* Warehouse Writeback not yet supported (coming soon)
* Cannot provide custom table options in `WITH` clause

***

## FAQ

### Which Trino connectors work with OneSignal?

Any connector that supports read operations works with Basic Sync Engine. For Advanced Sync Engine, you need connectors that support table writes and `CREATE OR REPLACE TABLE`.

### Can I query multiple catalogs in a single sync?

Yes! Trino's federated query capabilities allow you to combine event data from multiple sources (PostgreSQL, MySQL, S3, etc.) in a single query.

### Do I need the Advanced Sync Engine?

No, Basic Sync Engine works well for most use cases. Use Advanced Sync Engine if you need enhanced performance and can set up the required `CENSUS.CENSUS` catalog.


# User model & migration guide
Source: https://documentation.onesignal.com/docs/en/user-model-migration-guide

Learn how to migrate from OneSignal’s device-centric model to the new user-centric APIs and SDKs for more personalized, multi-channel engagement.

OneSignal has migrated from a device-centric (Player ID) model to a user-centric model built around the concept of a unified user. This guide explains the new model, how it differs from the old approach, and how to migrate your app safely and successfully.

<Note>
  This guide is for customers who have been using OneSignal for a long time on versions 2, 3, or 4 of our Mobile SDKs or v15 of our Web SDK.

  If you are a new customer or have already migrated to version 5 of our Mobile SDKs or v16 of our Web SDK, you can skip this guide and go to:

  * [Users](./users)
  * [Subscriptions](./subscriptions)
  * [Mobile SDK reference](./mobile-sdk-reference)
  * [Web SDK reference](./web-sdk-reference)
</Note>

<Frame>
  <img alt="User Model multi-channel illustration" />
</Frame>

## What is the User Model?

The User Model lets you target actual users across all the messaging channels they subscribe to (mobile push, web push, email, SMS, and in-app) rather than targeting individual devices.

Each User:

* Has one or more Identity Aliases (e.g. external\_id, custom alias)
* Can have multiple Subscriptions, one for each channel or device
* Includes metadata like tags, language, and activity history

This model simplifies audience targeting, supports personalized multi-channel messaging, and unlocks advanced features like Journeys, User-Level Analytics, and Real-Time Identity Resolution.

<Frame>
  <img alt="Diagram showing difference between Player and User Models" />
</Frame>

***

## Key concepts

<Tabs>
  <Tab title="Users">
    A **User** represents a real person. You can identify a user using system-generated or custom aliases.

    * `onesignal_id`: Auto-generated by OneSignal
    * `external_id`: Set via SDK `login()` or the API (reserved alias)
    * Custom Aliases: e.g. `user_id`, `email`, `facebook`, etc.

    Learn more: [Users](./users)
  </Tab>

  <Tab title="Subscriptions">
    A **Subscription** represents a channel the user is subscribed to. This includes metadata like device info, tokens, session history, and opt-in status.

    * Mobile & In-app
    * Web Push
    * Email
    * SMS

    Learn more: [Subscriptions](./subscriptions)
  </Tab>

  <Tab title="Aliases">
    Aliases map external identifiers (e.g., user ID from your app, Mixpanel ID) to a OneSignal user. You can assign multiple aliases to unify fragmented identities across platforms.

    * Special aliases:
      * `onesignal_id`: Auto-managed, read-only
      * `external_id`: Writable, legacy-compatible

    Learn more: [Aliases & External ID](./users)
  </Tab>
</Tabs>

***

## Benefits of migrating

* **Unified Identity**: One user across all devices and channels
* **Advanced Messaging**: Power features like Journeys, in-app login tracking, and lifecycle campaigns
* **Clean Segmentation**: Group users by tags, subscription status, channel engagement, and more
* **Simplified API**: Fewer endpoints, more consistent data model

***

## Migration steps

<Warning>
  The User Model is not backwards compatible. Migration is **one-way** from Player Model to User Model.

  Before migrating:

  * Thoroughly test with a staging environment
  * Migrate only after all SDKs and backend services are updated
</Warning>

<Steps>
  <Step title="Unify users with external_id">
    Use identity aliases to link existing player records into unified users.

    **Options**:

    * SDK `login(externalId)`
    * API: [Create User](/reference/create-user), [Update User](/reference/update-user)
    * CSV: [Import](./import)

    OneSignal will auto-merge subscriptions under the same External ID.
  </Step>

  <Step title="Update your OneSignal SDKs">
    All OneSignal mobile SDKs v5+ and web SDK v16+ support the User Model.

    Roll out SDK updates using phased deployment strategies to minimize risk:

    * [Apple Phased Rollout](https://developer.apple.com/help/app-store-connect/update-your-app/release-a-version-update-in-phases)
    * [Google Play Staged Rollout](https://support.google.com/googleplay/android-developer/answer/6346149)

    See [SDK support table below](#sdk-support).
  </Step>

  <Step title="Update your backend to use the new User APIs">
    Replace deprecated Player Model API calls with the new User Model equivalents.

    Use our [API Reference](/reference/rest-api-overview) and tables below to map old endpoints to new ones.
  </Step>
</Steps>

## SDK support & migration guides

<Tabs>
  <Tab title="Mobile SDKs">
    | Platform     | SDK                                                                 | Migration Guide                                                                                            |
    | ------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
    | Android      | [v5+](https://github.com/OneSignal/OneSignal-Android-SDK/releases)  | [Guide](https://github.com/OneSignal/OneSignal-Android-SDK/blob/user-model/main/MIGRATION_GUIDE.md)        |
    | iOS          | [v5+](https://github.com/OneSignal/OneSignal-iOS-SDK/releases)      | [Guide](https://github.com/OneSignal/OneSignal-iOS-SDK/blob/major_release_5.0.0/MIGRATION_GUIDE.md)        |
    | Unity        | [v5+](https://github.com/OneSignal/OneSignal-Unity-SDK/releases)    | [Guide](https://github.com/OneSignal/OneSignal-Unity-SDK/blob/user-model/main/MIGRATION_GUIDE_v3_to_v5.md) |
    | Flutter      | [v5+](https://github.com/OneSignal/OneSignal-Flutter-SDK/releases)  | [Guide](https://github.com/OneSignal/OneSignal-Flutter-SDK/blob/user_model/main/MIGRATION_GUIDE.md)        |
    | React Native | [v5+](https://github.com/OneSignal/react-native-onesignal/releases) | [Guide](https://github.com/OneSignal/react-native-onesignal/blob/major_release_5.0.0/MIGRATION_GUIDE.md)   |
    | .NET MAUI    | [v5+](https://github.com/OneSignal/OneSignal-DotNet-SDK/releases)   | [Guide](https://github.com/OneSignal/OneSignal-DotNet-SDK/blob/user-model/main/MIGRATION_GUIDE.md)         |

    <Note>
      For a map of old player model methods to new user model methods, see [Mobile SDK mapping](./device-user-model-mobile-sdk-mapping).
    </Note>
  </Tab>

  <Tab title="Web SDKs">
    | Platform  | SDK                                                                 | Migration Guide                                                                            |
    | --------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
    | Web       | [v16+](https://github.com/OneSignal/OneSignal-Website-SDK/releases) | [Guide](https://github.com/OneSignal/OneSignal-Website-SDK/blob/160000/MIGRATION_GUIDE.md) |
    | React     | [v3+](https://www.npmjs.com/package/react-onesignal)                | [Guide](https://github.com/OneSignal/react-onesignal/blob/main/MigrationGuide.md)          |
    | Vue 2 & 3 | [v2+/v3+](https://www.npmjs.com/package/@onesignal/onesignal-vue3)  | [Guide](https://github.com/OneSignal/onesignal-vue/blob/HEAD/MigrationGuide.md)            |
    | Angular   | [v2+](https://www.npmjs.com/package/onesignal-ngx)                  | [Guide](https://github.com/OneSignal/onesignal-ngx/blob/HEAD/MigrationGuide.md)            |

    <Note>
      For a map of old player model methods to new user model methods, see [Web SDK mapping](./device-user-model-web-sdk-mapping).
    </Note>
  </Tab>

  <Tab title="Backend SDKs">
    | Language | SDK                                                                                  |
    | -------- | ------------------------------------------------------------------------------------ |
    | Node     | [@onesignal/node-onesignal](https://www.npmjs.com/package/@onesignal/node-onesignal) |
    | Python   | [onesignal-python-api](https://pypi.org/project/onesignal-python-api/)               |
    | Go       | [onesignal-go-api](https://pkg.go.dev/github.com/OneSignal/onesignal-go-api/v2)      |
    | .NET     | [OneSignalApi](https://www.nuget.org/packages/OneSignalApi)                          |
    | Rust     | [onesignal-rust-api](https://crates.io/crates/onesignal-rust-api)                    |
    | Ruby     | [onesignal](https://rubygems.org/gems/onesignal)                                     |
    | PHP      | [onesignal-php-api](https://packagist.org/packages/onesignal/onesignal-php-api)      |
  </Tab>
</Tabs>

***

## API reference

<Tabs>
  <Tab title="Player Model (Deprecated)">
    | Old API                                        | Replacement                                                                                    |
    | ---------------------------------------------- | ---------------------------------------------------------------------------------------------- |
    | [Add Device](/reference/add-a-device)          | [Create User](/reference/create-user) or [Create Subscription](/reference/create-subscription) |
    | [Edit Device](/reference/edit-device)          | [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) |
    | [Delete Player](/reference/delete-user-record) | [Delete User](/reference/delete-user) or [Delete Subscription](/reference/delete-subscription) |
  </Tab>

  <Tab title="User Model (New)">
    | Action       | API                                     |
    | ------------ | --------------------------------------- |
    | Create       | [Create User](/reference/create-user)   |
    | View         | [View User](/reference/view-user)       |
    | Update       | [Update User](/reference/update-user)   |
    | Delete       | [Delete User](/reference/delete-user)   |
    | Add Alias    | [Create Alias](/reference/create-alias) |
    | Remove Alias | [Delete Alias](/reference/delete-alias) |

    ### Subscription APIs

    | Action   | API                                                       |
    | -------- | --------------------------------------------------------- |
    | Create   | [Create Subscription](/reference/create-subscription)     |
    | Update   | [Update Subscription](/reference/update-subscription)     |
    | Delete   | [Delete Subscription](/reference/delete-subscription)     |
    | Transfer | [Transfer Subscription](/reference/transfer-subscription) |
  </Tab>
</Tabs>

***

## Next steps

* 📘 See our [Users](./users) and [Subscriptions](./subscriptions) documentation
* 🛠️ Update SDKs and test in staging before going live
* 💬 Need help? Contact `support@onesignal.com`

<Check>
  You’re now ready to build personalized, multi-channel messaging experiences powered by the new User Model!
</Check>

***


# User and Subscription Profiles
Source: https://documentation.onesignal.com/docs/en/user-subscription-profiles

View and manage individual user records, subscriptions, tags, journeys, and message activity from the Audience section of the dashboard.

The dashboard gives you two levels of detail for inspecting audience members: the **User Profile** and the **Subscription Profile**. Use the User Profile to see a complete picture of a user across all their channels and devices. Use the Subscription Profile to inspect a single messaging channel, for example a push or email subscription.

***

## User Profile

You can open a User Profile in two ways:

* From **Audience > Users**, search by External ID, email address, phone number, or OneSignal ID, then click the record.
* From **Audience > Subscriptions**, click the OneSignal ID on a subscription record directly, or use the menu option on the record, select **View subscription**, then click the OneSignal ID.

The profile header shows the user's External ID, email address, OneSignal ID, and their current subscription status across channels.

### Overview tab

The Overview tab is a summary of the user's identity and recent activity.

**Profile section**

| Field          | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| External ID    | Your system's unique identifier for this user.               |
| OneSignal ID   | OneSignal's internal UUID for this user record.              |
| Email          | Email address associated with the user.                      |
| Phone          | Phone number associated with the user, if any.               |
| Country        | Country detected or set for this user.                       |
| Language       | Language preference.                                         |
| Timezone       | Timezone associated with the user.                           |
| Location Point | Geographic coordinates, if location data has been collected. |

**Devices section**

Lists all devices associated with this user, such as an iOS or Android device.

**Aliases section**

Any additional [aliases](./aliases) (beyond External ID and OneSignal ID) that have been associated with this user record.

**Activity section**

Shows aggregate session data across all of the user's subscriptions:

| Field                  | Description                   |
| ---------------------- | ----------------------------- |
| First active           | When the user was first seen. |
| Last active            | Most recent session.          |
| Total sessions         | Total session count.          |
| Total session duration | Cumulative in-app time.       |

**Message events in last 30 days** shows a summary of recent message interactions across all channels.

***

### Event log tab

The Event log shows [message events](./segmentation#message-event-filters) and [custom events](./custom-events) for this user across all subscriptions.

Use the date range picker and message type filter to narrow results. Toggle between **Message events** and **Custom events** using the sidebar tabs.

<Note>
  Message events include sends, deliveries, opens, and clicks. Custom events are logged via the SDK or API and reflect actions you define in your app.
</Note>

***

### Subscriptions tab

The Subscriptions tab lists every channel subscription associated with this user, including push, email, and SMS. Each subscription shows:

* Channel type and address (email address, push device, phone number)
* Subscription status
* Subscription ID
* Created at and last active timestamps
* For push: device, app version, usage duration, sessions, IP address, SDK version, and push token

Click a Subscription ID to open the full [Subscription Profile](#subscription-profile) for that record.

***

### Data tags tab

The Data tags tab shows all tags currently set on this user. Tags are key-value pairs you use for segmentation and personalization.

You can search tags by key or value, and add new tags directly from this view using the **Add tag** button.

<Note>
  Tags edited here are applied at the user level and are shared across all of this user's subscriptions. Tag values are always strings.
</Note>

***

### Journeys tab

The Journeys tab shows all Journeys this user is currently enrolled in or has previously exited. Each row shows the Journey name and the user's current status: **Active** or **Exited**.

***

## Subscription Profile

You can reach a Subscription Profile in two ways:

* From **Audience > Subscriptions**, search for the subscription directly
* From a User Profile's **Subscriptions tab**, click the Subscription ID

The profile header shows the Subscription ID and its current status, for example **Subscribed**.

### Profile section

The Profile section shows channel-specific metadata for this subscription.

**For push subscriptions:**

| Field          | Description                                                |
| -------------- | ---------------------------------------------------------- |
| Device         | Device model and OS version.                               |
| Status details | Additional status context, if available.                   |
| OneSignal ID   | The OneSignal ID of the user this subscription belongs to. |
| External ID    | Your system's identifier for the associated user.          |
| Language       | Language setting on the device.                            |
| Timezone       | Device timezone.                                           |
| Last Session   | Time of the most recent app session.                       |
| First Session  | Time of the first recorded session.                        |
| Sessions       | Total session count.                                       |
| Usage Duration | Cumulative time spent in the app.                          |
| SDK Version    | Version of the OneSignal SDK installed on the device.      |
| App Version    | Version of your app installed on the device.               |

**For email subscriptions:**

| Field          | Description                                       |
| -------------- | ------------------------------------------------- |
| Channel        | Email.                                            |
| Email          | The email address for this subscription.          |
| Status details | Additional status context, if available.          |
| OneSignal ID   | The OneSignal ID of the associated user.          |
| External ID    | Your system's identifier for the associated user. |
| Language       | Language preference.                              |
| Last Session   | Most recent session.                              |
| First Session  | First recorded session.                           |
| Sessions       | Total session count.                              |
| Usage Duration | Cumulative session time.                          |

### User Tags

The **User Tags** section on the Subscription Profile shows the [tags](./add-user-data-tags) currently set on the associated user. The tag count in the section header reflects the total number of tags on the user, not just those relevant to this subscription.

Click **Edit in User Profile** to navigate directly to the Data tags tab on the User Profile, where you can add, edit, or remove tags.

### Segments

Lists all [segments](./segmentation) this subscription currently qualifies for, based on the user's tags, behavior, and other filters. Each segment name is a link to the segment in **Audience > Segments**.

### Journeys Audience

Lists the Journeys this user has entered. A Journey remains listed even if the user exited early, as long as they still meet the Journey's entry criteria. It is removed from this list only when the user no longer qualifies for that Journey.

### Message Activity Timeline

The right side of the Subscription Profile shows a timeline of message events for this specific subscription, including sends, deliveries, opens, and clicks, within the selected date range.

Use the date range picker to adjust the window. If there is no recent activity, the timeline displays "No Recent Activity."

<Note>
  The Message Activity Timeline on a Subscription Profile is scoped to that subscription only. To see activity across all of a user's subscriptions, use the Event log tab on the User Profile.
</Note>

***

## Related pages

<Columns>
  <Card title="Users" icon="users" href="./users">
    The OneSignal user model, aliases, and how users relate to subscriptions.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    Devices, email addresses, and phone numbers that receive your messages.
  </Card>

  <Card title="Segments" icon="filter" href="./segmentation">
    Build audience segments based on tags, behavior, and subscription data.
  </Card>

  <Card title="Data Tags" icon="tags" href="./add-user-data-tags">
    Add custom properties to users for personalization and segmentation.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Automate multi-step messaging workflows across channels.
  </Card>
</Columns>


# Users
Source: https://documentation.onesignal.com/docs/en/users

How OneSignal Users, OneSignal IDs, and External IDs connect Subscriptions across channels and devices.

Users tie every Subscription a person has across push, email, and SMS to a single identity. This page covers OneSignal IDs, External IDs, how anonymous Users become identified, what transfers when User context changes, and how Users factor into MAU billing.

## Overview

In OneSignal, a **User** represents an individual with one or more [Subscriptions](./subscriptions) across your messaging channels (mobile push, web push, email, and SMS).

* Each User can have up to **20 Subscriptions**.
* Every User is automatically assigned a **OneSignal ID** (UUID v4).
* Users start as **anonymous** until you assign them an **External ID**. Assigning an External ID links Subscriptions together and may replace the existing OneSignal ID if the user already exists in your app.
* **Users and Subscriptions have different properties.** For example, **Tags** are stored at the User level, while **subscription status** (opted-in/out) belongs to the Subscription.
* When the User context changes, for example logging in (anonymous → identified) or switching accounts (UserA → UserB), the **Subscription is reassigned** from the old User to the new one.
  * The Subscription will now inherit the properties of the new User.
  * Properties tied to the previous User (like Tags, language, or External ID) will no longer apply.

### What transfers when a User changes

Subscriptions move from the old User to the new one, but the properties they inherit are the new User's. For example:

* UserA has Tag `premium=true`
* UserB has Tag `premium=false`
* If a Subscription moves from UserA to UserB, it no longer reflects `premium=true` and instead reflects UserB's properties.

<Frame>
  <iframe title="How OneSignal Users, External IDs, and Subscriptions fit together" />
</Frame>

### Anonymous vs. identified users

* **Anonymous user:** Has no External ID → each Subscription is separate with its own OneSignal ID (treated as separate Users).
* **Identified user:** Has an External ID → OneSignal merges all Subscriptions under a single OneSignal ID.

**Example: Anonymous user**

* Web push Subscription → `OneSignal_ID_1`
* Mobile Subscription → `OneSignal_ID_2`
* Email Subscription → `OneSignal_ID_3`
* SMS Subscription → `OneSignal_ID_4`
* **Result:** Four Users (each Subscription is a separate User with unique properties)

**Example: Identified user**

* Web push Subscription with External ID `External_ID_A` → `OneSignal_ID_1`
* Mobile Subscription with same `External_ID_A` → merged into `OneSignal_ID_1`
* Email Subscription with same `External_ID_A` → merged into `OneSignal_ID_1`
* SMS Subscription with same `External_ID_A` → merged into `OneSignal_ID_1`
* **Result:** One User with four Subscriptions (all tied to the same User)

<Note>
  Always assign an External ID. This ensures Subscriptions across channels and devices unify under a single User profile and prevents duplication.

  * Use stable, non-generic identifiers (e.g., your internal user ID or email address).
  * Call `OneSignal.login` early in your app lifecycle.
</Note>

***

## User properties

| Property           | Description                                                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **External ID**    | A unique identifier you assign to unify the user with your system.                                                                                      |
| **OneSignal ID**   | A UUID v4 auto-generated by OneSignal for each user. It may change upon assigning an External ID.                                                       |
| **Aliases**        | Key-value pairs like `mixpanel_id : 1234`. See [Aliases](./aliases).                                                                                    |
| **Channel**        | The [Subscriptions](./subscriptions) the user has, such as Push, Email, or SMS.                                                                         |
| **Country**        | Country code in [ISO 3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.                                                          |
| **Email**          | Email from the most recent Email Subscription.                                                                                                          |
| **First session**  | When the user was initially created in OneSignal.                                                                                                       |
| **IP Address**     | From the latest updated Subscription.                                                                                                                   |
| **Language**       | User's language in [ISO 639-1 format](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). Can be updated via API or `setLanguage`.           |
| **Last session**   | The latest timestamp of app interaction.                                                                                                                |
| **Location**       | GPS coordinates of mobile subscriptions (if location tracking is enabled). See [Location-Triggered Notifications](./location-triggered-event).          |
| **Phone**          | Phone number from the most recent SMS Subscription.                                                                                                     |
| **Tags**           | Custom metadata (e.g. preferences, behavior). See [Tags](./add-user-data-tags).                                                                         |
| **Test User name** | A label assigned when marking a User as a test user. Set via the dashboard or the `test_user_name` property in the API. See [Test users](./test-users). |
| **Timezone**       | `timezone_id` in [IANA TZ format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), set by the SDK. Can be updated via API.                |

## OneSignal ID

The **OneSignal ID** is an internal UUID v4 generated to uniquely represent a user. It's automatically created in scenarios such as:

* First-time mobile app open (or after reinstall)
* New web push Subscription
* Creating Users/Subscriptions via [Create user](/reference/create-user) or [CSV Import](./import)
* Clearing browser cache and returning to the site
* Logging out with `OneSignal.logout`

Once an **External ID** is used via `OneSignal.login`, any existing OneSignal ID tied to the current Subscription is replaced by the one associated with that External ID. Subscriptions across platforms (Push, Email, SMS) will be merged under the same OneSignal ID if they share the same External ID.

### Reassignment and behavior

If a user reinstalls the app or clears cache, a new OneSignal ID and Subscription are created. However, calling `OneSignal.login` will link the new Subscription back to the original user profile.

Email and SMS Subscriptions added via `OneSignal.User.addEmail` or `addSms` inherit the current OneSignal ID. For full method details, see the [Mobile SDK reference](./mobile-sdk-reference) and [Web SDK reference](./web-sdk-reference).

<Warning>
  If you call `addEmail` or `addSms` before `OneSignal.login`, those Subscriptions are associated with the anonymous User. After calling `login`, you must call `addEmail` or `addSms` again to associate the email and SMS Subscriptions with the newly identified User.
</Warning>

## External ID

The **External ID** is a unique string you assign to users to track them across devices and Subscriptions.

<Frame>
  <img alt="Diagram showing how an External ID links multiple Subscriptions to a single User" />
</Frame>

You can set or remove the External ID via:

* `OneSignal.login` (**recommended**). See [Mobile SDK](./mobile-sdk-reference#login-external-id) and [Web SDK](./web-sdk-reference#login-external-id).
* [Create user API](/reference/create-user).
* [Transfer subscription API](/reference/transfer-subscription).
* `OneSignal.logout`. Removes the External ID and returns the User to anonymous.

External IDs have a maximum length of **128 characters.**

### Restricted IDs

<Warning>
  OneSignal rejects the values below as External IDs to prevent accidental User merges, since teams commonly use them as placeholders or fallbacks. Submitting one of these values fails the assignment and leaves the User in its previous state. Use stable identifiers from your auth or billing system instead.

  * `NA`, `NULL`, `null`, `none`, `not set`, `unknown`, `undefined`
  * `0`, `1`, `-1`, `NaN`
  * `00000000-0000-0000-0000-000000000000`
  * `-`, `ok`, `all`, `123ABC`
  * `UNQUALIFIED`, `INVALID_USER`
</Warning>

***

## Multiple users on the same device

When multiple users share a device, each new login should trigger a call to `OneSignal.login` with a different External ID. This reassigns the OneSignal ID and Subscription to the new user. For the full list of what transfers when the User changes, see [What transfers when a User changes](#what-transfers-when-a-user-changes) in the Overview.

To handle logout, you can do the following to remove the user context:

* Call `OneSignal.logout` to clear the External ID, remove previous User properties (Tags, Aliases, etc.), and assign an anonymous OneSignal ID.
* Optionally disable notifications using `optOut`, and re-enable with `optIn` when logging back in.

***

## Monthly active users (MAU)

MAU is used for **billing** and is defined as a mobile [Subscription](./subscriptions) that has a last session within the 30-day billing period. This includes:

* Users that open your app for the first time, creating a mobile Subscription via our SDK
* Users that reinstall the app and open it again, creating another mobile Subscription via our SDK
* Users that get imported via our API

### MAU billing example

If a User has these Subscriptions:

* iOS mobile (active in the last 30 days)
* Android mobile (active in the last 30 days)
* Web push
* Email
* SMS

Only iOS and Android mobile Subscriptions count, resulting in **2 MAUs**.

The subscription status does not matter for MAU billing.

### Reducing MAUs (e.g., paywall use cases)

You can delay SDK initialization and Subscription creation using the mobile SDK [privacy methods](./mobile-sdk-reference#privacy).

1. Call `setConsentRequired()` before initializing the SDK. This prevents auto-creation of a Subscription.
2. Call `setConsentGiven()` when ready to create a Subscription for the user.

***

## FAQ

### What is the difference between a OneSignal ID and an External ID?

The **OneSignal ID** is a UUID v4 that OneSignal generates automatically for every User. The **External ID** is a value you assign from your own system (auth, billing, CRM) to identify the same User across devices and channels. The OneSignal ID is OneSignal's identifier for the User; the External ID is your identifier for the same User.

### When should I call `OneSignal.login`?

Call `OneSignal.login` as soon as you have a stable identifier for the user: at signup, on every login, and on session resume. Calling it late or sporadically breaks attribution between anonymous activity and the authenticated User, and may leave Subscriptions split across multiple OneSignal IDs.

### What happens when a user reinstalls the app?

A new OneSignal ID and Subscription are created. Calling `OneSignal.login` with the same External ID links the new Subscription back to the original User profile, preserving Tags, Aliases, and other User-level properties.

### What happens when a user logs out and another logs in on the same device?

Call `OneSignal.logout` first to clear the previous User context, then `OneSignal.login` with the new user's External ID. The Subscription transfers to the new User and inherits their Tags, language, and other properties. The previous User's properties no longer apply to that Subscription. See [Multiple users on the same device](#multiple-users-on-the-same-device).

### How many Subscriptions can a User have?

Each User can have up to 20 Subscriptions across all channels (mobile push, web push, email, and SMS).

### What is the difference between an anonymous and identified User?

An anonymous User has no External ID. Each Subscription is treated as a separate User with its own OneSignal ID. An identified User has an External ID, which causes OneSignal to merge all Subscriptions sharing that External ID under a single User profile.

### Does subscription status affect MAU billing?

No. Any mobile Subscription with a session in the 30-day billing period counts as an MAU, regardless of whether the Subscription is opted in or opted out of notifications.

***

## Related pages

<Columns>
  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    Devices, email addresses, and phone numbers that receive your messages.
  </Card>

  <Card title="Aliases" icon="fingerprint" href="./aliases">
    Map custom identifiers to Users for cross-platform tracking and integrations.
  </Card>

  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Add custom properties to users for personalization and segmentation.
  </Card>

  <Card title="Identity verification" icon="shield-halved" href="./identity-verification">
    Require server-generated JWTs to prevent User impersonation.
  </Card>
</Columns>


# Abandoned cart tutorial
Source: https://documentation.onesignal.com/docs/en/abandoned-cart

Recover lost sales with abandoned cart notifications using OneSignal by tracking cart activity, building targeted segments, and sending timely reminders with Journeys.

## Overview

Abandoned carts are one of the highest-impact opportunities to recover lost revenue. Most users who abandon a cart still intend to purchase — they just need a timely reminder.

This guide shows you how to build an **automated abandoned cart Journey** in OneSignal that:

* Detects cart activity
* Waits for a short period of inactivity
* Sends a personalized reminder
* Stops messaging immediately after purchase or cart removal

You can implement this using either:

* Custom Events (recommended for most implementations)
* Tags (simpler, limited to track 1 item instead of multiple)

The right choice depends on the data you want to show in the message and where that data comes from.

**What you will build**

By the end of this guide, you will have:

* Cart activity sent to OneSignal (via Tags or Custom Events)
* A clear, **code-defined** abandonment signal
* Message templates that personalize cart data
* A Journey that:
  * Starts when an abandonment signal is received
  * Waits before sending
  * Sends abandoned cart messages
  * Exits immediately when the cart is emptied or purchased
  * Re-enters the Journey if the user still has items in their cart within a specific time period
* Analytics to measure message and revenue performance

**How abandoned carts are modeled**

This guide assumes you are tracking "cart updated" actions, meaning each time a user adds or removes items from their cart. This could be a single item like a subscription to your content or multiple items like a shopping cart.

Once OneSignal receives a `cart_updated` event or tag:

* The user becomes eligible to enter the Journey
* A wait period gives them time to return naturally
* Messages are sent only if they do not exit
* The user exits immediately when the cart is emptied

***

## Setup

### Step 1: Plan your cart data and source

Decide **what cart information you want to show** and **where that data comes from**.

Common cart data includes:

* Product name, image, price, and quantity
* Number of items in the cart
* A deep link back to the cart

Your data source determines how you send events:

| Data source          | Recommended method              |
| -------------------- | ------------------------------- |
| App or website       | OneSignal Frontend SDK          |
| Backend or database  | OneSignal REST API              |
| Third-party platform | Integration-based Custom Events |

<Check>
  By the end of this step, you know **what data you will send** and **how you will send it**.
</Check>

### Step 2: Send cart activity to OneSignal

When the cart state changes, send the updated cart data to OneSignal so the activity can be tracked.

This guide uses the event or tag `cart_updated` to track cart activity and at least one property.

Select the method you chose in Step 1:

<Tabs>
  <Tab title="Custom Events">
    Send a `cart_updated` Custom Event each time the cart changes. Include product properties when items are in the cart and omit them when the cart is emptied.

    | Reference                                            | Description                                                                                                              |
    | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
    | `trackEvent` method                                  | Send via Frontend SDK ([Mobile SDK](./mobile-sdk-reference#custom-events), [Web SDK](./web-sdk-reference#custom-events)) |
    | [Custom Events API](/reference/create-custom-events) | Send via REST API                                                                                                        |
    | [Integrations](./integrations)                       | Send via integration                                                                                                     |

    **Frontend SDK `trackEvent` method example**

    <CodeGroup>
      ```javascript Cart Updated theme={null}
      OneSignal.User.trackEvent("cart_updated", {
        product_name: "24 Pack of Acorns",
        product_image: "https://i.imgur.com/ssPCfbC.png",
        product_price: 12.99,
        product_quantity: 1,
        cart_url: "https://yourdomain.com/cart"
      });
      ```

      ```javascript Cart Emptied theme={null}
      OneSignal.User.trackEvent("cart_updated");
      ```
    </CodeGroup>

    **Custom Events API example**

    <CodeGroup>
      ```json Cart Updated theme={null}
      {
        "events": [
          {
            "name": "cart_updated",
            "properties": {
              "product_name": "24 Pack of Acorns",
              "product_image": "https://i.imgur.com/ssPCfbC.png",
              "product_price": "$12.99",
              "product_quantity": "1",
              "cart_url": "https://yourdomain.com/username/cart"
            },
            "external_id": "ID_OF_THE_USER"
          }
        ]
      }
      ```

      ```json Cart Emptied theme={null}
      {
        "events": [
          {
            "name": "cart_updated",
            "external_id": "ID_OF_THE_USER"
          }
        ]
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Tags">
    Set tags when items are in the cart and remove them when the cart is emptied.

    <Info>
      These examples set the `cart_updated` tag to a Unix timestamp (in seconds) representing when the cart was last updated. You can also use a boolean value (true/false), but a timestamp provides more flexibility with [Time Operators](./time-operators).
    </Info>

    | Reference                                 | Description                                                                                                      |
    | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
    | `addTags` / `removeTags`                  | Send via Frontend SDK ([Mobile SDK](./mobile-sdk-reference#data-tags), [Web SDK](./web-sdk-reference#data-tags)) |
    | [Update User API](/reference/update-user) | Send via REST API                                                                                                |

    **Frontend SDK `addTags` / `removeTags` methods example**

    <CodeGroup>
      ```javascript Cart Updated theme={null}
      OneSignal.User.addTags({
        cart_updated: unix_timestamp_seconds,
        product_name: "24 Pack of Acorns", 
        product_image: "https://i.imgur.com/ssPCfbC.png",
        product_price: "$12.99",
        product_quantity: "1",
        cart_url: "https://yourdomain.com/username/cart"
      })
      ```

      ```javascript Cart Emptied (remove tags) theme={null}
      OneSignal.User.removeTags([
        "cart_updated", "product_name", "product_image", "product_price", "product_quantity", "cart_url"
      ])
      ```
    </CodeGroup>

    **Update User API example**

    <CodeGroup>
      ```json Cart Updated theme={null}
      {
        "properties": {
          "tags": {
            "cart_updated": 1779305030, // Unix timestamp in seconds
            "product_name": "24 Pack of Acorns",
            "product_image": "https://i.imgur.com/ssPCfbC.png",
            "product_price": "$12.99",
            "product_quantity": "1",
            "cart_url": "https://yourdomain.com/username/cart"
          }
        }
      }
      ```

      ```json Cart Emptied (remove tags) theme={null}
      {
        "properties": {
          "tags": {
            "cart_updated": "",
            "product_name": "",
            "product_image": "",
            "product_price": "",
            "product_quantity": "",
            "cart_url": ""
          }
        }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Check>
  Cart activity is now being sent to OneSignal. Each time the cart changes, OneSignal receives the updated data needed to trigger and personalize messages.
</Check>

***

### Step 3: Create abandoned cart message templates

Create message templates that reference cart data dynamically.

For more details on the concepts used in this section, see:

* [Liquid syntax](./using-liquid-syntax)
* [Message Personalization](./message-personalization)
* [Templates](./templates)

<Tabs>
  <Tab title="Custom Event Push Template">
    Reference event properties using liquid syntax format:

    ```liquid Liquid theme={null}
    {{journey.event.name.properties.property_name | default: "fallback_value"}}
    ```

    **Message**:

    ```liquid Liquid theme={null}
    You left {{journey.event.cart_updated.properties.product_name | default: "items"}} in your cart.
    ```

    **Image**:

    ```liquid Liquid theme={null}
    {{journey.event.cart_updated.properties.product_image | default: "https://i.imgur.com/ssPCfbC.png"}}
    ```

    **Launch URL**:

    ```liquid Liquid theme={null}
    {{journey.event.cart_updated.properties.cart_url | default: "https://yourdomain.com/cart"}}
    ```

    <Warning>
      The image will not display if `product_image` is not a **direct**, **publicly accessible** image URL.

      If your `product_image` is the name of an image file available online, you can reference the image using the following format:
      `https://yourdomain.com/images/{{journey.event.cart_updated.properties.product_image | default: "stock_image"}}.png`
    </Warning>

    <Frame>
      <img alt="Abandoned cart template example with Custom Events" />
    </Frame>
  </Tab>

  <Tab title="Tag Push Template">
    Reference tag properties using liquid syntax format:

    ```liquid Liquid theme={null}
    {{tag_key | default: "fallback_value"}}
    ```

    **Message**:

    ```liquid Liquid theme={null}
    You left {{product_name | default: "items"}} in your cart.
    ```

    **Image**:

    ```liquid Liquid theme={null}
    {{product_image | default: "https://i.imgur.com/ssPCfbC.png"}}
    ```

    **Launch URL**:

    ```liquid Liquid theme={null}
    {{cart_url | default: "https://yourdomain.com/cart"}}
    ```

    <Warning>
      The image will not display if `product_image` is not a **direct**, **publicly accessible** image URL.

      If your `product_image` is the name of an image file available online, you can reference the image using the following format:
      `https://yourdomain.com/images/{{product_image | default: "stock_image"}}.png`
    </Warning>

    <Frame>
      <img alt="Abandoned cart template example with Tags" />
    </Frame>
  </Tab>
</Tabs>

**Need email examples, help, or more inspiration?**

<Columns>
  <Card title="Personalize messages with Custom Events" icon="bolt" href="./personalization-custom-event">
    Complete guide to using Custom Events in Journeys. Includes event storage, Journey configuration, abandoned cart example, best practices, and troubleshooting.
  </Card>

  <Card title="Personalize messages with Properties" icon="tags" href="./personalization-properties-and-tags">
    Complete guide to using Properties and Tags in Journeys. Includes event storage, Journey configuration, abandoned cart example, best practices, and troubleshooting.
  </Card>
</Columns>

### Step 4: Create abandoned cart Segment (Tags only)

<Warning>
  This step is only required if you are using Tags to track cart activity. If you are using Custom Events, you can skip this step.
</Warning>

The Segment will determine who can enter the Journey. See [Segments](./segmentation) for more details.

Add two filters to the Segment:

1. **User Tag** — `cart_updated` `exists`
2. **Last Session** — `less than` `7` `days ago` - Adjust the time period as desired

<Frame>
  <img alt="Abandoned Cart Segment with Tag Filter where the cart_updated tag exists and the last session is less than 7 days ago" />
</Frame>

<Check>
  You can now track users that update their cart and have visited the app or website in the last 7 days.

  Users are automatically removed from the segment when either of the following conditions are met:

  * After 7 days have passed since they last visited the app/website
  * When the `cart_updated` tag is removed
</Check>

### Step 5: Create the abandoned cart Journey

Create a Journey that reacts to cart activity. See [Journeys](./journeys-overview) for more details.

<Frame>
  <img alt="New Abandoned Cart Journey create screen" />
</Frame>

#### Journey settings

Review the [Journey Settings](./journeys-settings) guide for more details on Entry, Exit, and Re-entry rules.

**Entry Rules**:

<Tabs>
  <Tab title="Custom Event: Entry Rules">
    * Select **Custom Event**
    * Custom Event Name: `cart_updated`
    * Filter by property: With **all** of the following properties: `product_name` **exists**

    <Warning>
      Using Custom Events allows individual users to enter Journeys multiple times.

      Use properties to filter users so they only enter when a specific property exists.
    </Warning>

    <Frame>
      <img alt="Abandoned Cart Journey Custom Event Entry Rules" />
    </Frame>
  </Tab>

  <Tab title="Tag: Entry Rules">
    * Select **Audience Segment**
    * Include Segment: **Abandoned Cart - cart\_updated**

    <Frame>
      <img alt="Abandoned Cart Journey entry rules" />
    </Frame>
  </Tab>
</Tabs>

**Exit Rules**:

<Tabs>
  <Tab title="Custom Event: Exit Rules">
    Users should exit the Journey when they empty their cart or complete the Journey.

    * Select **Meet a certain condition**
    * Check **Exit when custom event condition occurs**
    * Custom Event Name: `cart_updated`

    <Frame>
      <img alt="Abandoned Cart Journey Custom Event Exit Rules" />
    </Frame>

    <Note>
      This configuration uses the same Custom Event name (`cart_updated`) for both entry and exit rules.

      This allows the user to only be in the Journey once at a time. Each time they update their cart, that instance of the user will exit and a new instance of the same user will enter the Journey. **This is why it is important to use properties to filter users within the Entry Rules.**
    </Note>
  </Tab>

  <Tab title="Tag: Exit Rules">
    * Select **Meet a certain condition**
    * Check **Exit when a user no longer matches the audience conditions**

    <Frame>
      <img alt="Abandoned Cart Journey Tag Exit Rules" />
    </Frame>

    <Info>
      Users will exit the Journey when either:

      * They leave the segment.
      * They complete the Journey.
    </Info>
  </Tab>
</Tabs>

**Re-entry Rules** (Tags only):

* Select **Yes, after a certain amount of time**
* Set the re-entry time to `3` `Days` - Adjust the time period as desired

<Frame>
  <img alt="Abandoned Cart Journey Re-entry Rules" />
</Frame>

<Check>
  If you have followed this guide completely so far, then users will:

  1. Enter the Journey when they abandon/update their cart
  2. Exit the Journey when they empty their cart or complete the Journey.
  3. Be eligible to re-enter the Journey:
     * **Custom Events**: Each time the `cart_updated` event is performed
     * **Tags**: After 3 days have passed since they last exited the Journey and are in the segment.
</Check>

#### Journey steps

Users will enter the Journey based on your Entry Rules. This typically happens within a few minutes after the event/tag is received.

Users will flow through the Journey step-by-step until they reach the end or an Exit Rule is met.

A basic abandoned cart Journey does two things:

1. Gives the user enough time to empty their cart (make a purchase or remove items manually)
2. If they do not, sends a message reminding them about the items in their cart

Achieve this by first adding a **Wait** step to the Journey.

* Set the wait time to be as long as you want. We recommend setting it to `1` or `2` `hours` so you can message them while they still have the intent to purchase.

Add a **Message** step.

* Select the **Abandoned Cart** Push Notification template you created in Step 3.

<Frame>
  <img alt="Basic Abandoned Cart Journey Steps" />
</Frame>

<Check>
  Basic Abandoned Cart Journey is now configured.

  When a user enters the Journey, they will wait for 1 hour. If they do not exit the Journey, they will receive the abandoned cart push notification.
</Check>

## Advanced Journey Setup

Extend the Journey to send more messages over time for higher recovery rates.

### Message sequence

A common high-performing cadence is:

1. Send the first message after 1 hour (completed in this guide).
2. Add another **Wait** step for 1 day and send a second message (\~24 hours since they updated their cart).
3. Add another **Wait** step for 2 days and send a third message (\~72 hours since they updated their cart).

#### Message types and content

Depending on which channels you set up with OneSignal, you will achieve better results using an omnichannel approach.

1. This guide shows how to send a push notification message after the first hour. This is used as a helpful reminder to try capturing the sale while the user may still be online.
2. Consider using both a push and email for your 2nd message. Use this second message to highlight benefits and social proof with light urgency to encourage them to purchase.
3. For the final message of the sequence, use an email or maybe an SMS (depending on the use case) as a "last call". Consider using a discount code or other incentive to encourage them to purchase.

### Fallback messages

OneSignal's Journeys provide **Wait Until** branching logic that you can use to check if a message was confirmed delivered, clicked or opened and if not performed within a certain time period, send a fallback message.

This is extremely helpful for users who may have unsubscribed from a specific message channel. More details on how to setup fallback messages can be found in our [Fallback Messages](./push-fallback-method) guide.

### Track performance

[Journey analytics](./journeys-analytics) can be used to track how the Journey as a whole is performing. You can also track each message performance using [Template analytics](./template-analytics).

#### Track revenue with Outcomes

To track revenue from this Journey, you can use [Custom Outcomes](./custom-outcomes).

When a purchase is made, you can send the event as a "Custom Outcome" to track the revenue associated with the specific message sent.

Custom Outcomes can be sent via the [Mobile SDK](./mobile-sdk-reference#outcomes) or [Web SDK](./web-sdk-reference#outcomes).

```javascript Example: Send purchase outcome via frontend SDK theme={null}
// Example: capture total price and item count at checkout
const checkoutPriceTotal = document.querySelector(".checkout-price-total").innerText;
const checkoutItemsTotal = document.querySelector(".checkout-items-total").innerText;

function updateOSOnCartPurchase(checkoutPriceTotal, checkoutItemsTotal) {
  const purchasePriceTotal = parseFloat(checkoutPriceTotal);
  const purchasedItemCount = parseInt(checkoutItemsTotal);

  OneSignalDeferred.push(function (OneSignal) {
    OneSignal.Session.sendOutcome("Purchase", purchasePriceTotal);
    OneSignal.Session.sendOutcome("Purchased Item Count", purchasedItemCount);
  });
}

const submitPurchaseButton = document.querySelector(".submit-payment");
if (submitPurchaseButton) {
  submitPurchaseButton.addEventListener("click", () => {
    updateOSOnCartPurchase(checkoutPriceTotal, checkoutItemsTotal);
  });
}
```

<Info>
  Outcomes can attribute revenue to messages users clicked or were influenced by within a defined attribution window.
</Info>

<Check>
  You have successfully implemented an abandoned cart Journey. When you are ready to start sending messages, select **Set Live**.
</Check>

## FAQ

### Should I use Custom Events or Tags for cart tracking?

Custom Events are recommended for most implementations. They support richer data, allow property-based filtering in Journey entry rules, and automatically handle re-entry when the same event fires again. Tags work for simpler use cases where you only need to track whether a cart exists, but require manual segment creation and re-entry configuration.

### How long should I wait before sending the first reminder?

One to two hours is a common starting point. This gives the user enough time to return on their own while the purchase intent is still fresh. Test different wait times and use [Journey analytics](./journeys-analytics) to find what works best for your audience.

### What happens if a user updates their cart while in the Journey?

With Custom Events, the user exits the current Journey instance (because `cart_updated` fires as an exit condition) and immediately re-enters with the updated event data. With Tags, the user stays in the same Journey instance because the tag still exists — they only re-enter after exiting and waiting for the re-entry period.

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# AI message composer
Source: https://documentation.onesignal.com/docs/en/ai-message-composer

Use OneSignal's built in AI to write and adjust push notifications to suit your needs and send the right message quickly and easily

The OneSignal **AI Message Composer** helps you quickly generate and fine-tune push notification content using a simple prompt. It’s designed to help you strike the right tone and messaging for your audience—whether you're starting from scratch or optimizing an existing message.

With just one prompt, the AI can generate a complete push notification or enhance your current text. You can continue refining your message by selecting predefined tone styles or entering additional instructions to get closer to your desired output.

## Creating a New Push Notification with AI

<Steps>
  <Step title="Create a new push notification">
    In the OneSignal dashboard, click **"+ Create"**, select **"Push"**, then choose **"AI-generated Push"**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Describe your message">
    Enter a description of what you want to say, or choose from the predefined prompt suggestions. Then click **"Generate"** to create the initial message.

    <Frame>
      <img />
    </Frame>

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Refine your message">
    To adjust tone or content, click **"Refine"**. You can choose from preset
    tonal options or select **"Writing Assistant"** to enter a custom prompt for
    further refinements.

    <Frame>
      <img />
    </Frame>

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Insert your message">
    Once you're satisfied with the message or ready to make final manual edits,
    click **"Insert"** to add the AI-generated content to your notification.
  </Step>

  <Step title="Finalize and send">
    Add any additional content or adjust settings as needed. Then complete the usual steps to send your push notification.
  </Step>
</Steps>

## Editing an Existing Push Notification with AI

While editing an existing push, begin typing in the **Title** or **Message** field. This will reveal the option to refine your message using the AI composer.

<Frame>
  <img />
</Frame>

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# Amazon SDK setup
Source: https://documentation.onesignal.com/docs/en/amazon-sdk-setup

Step-by-step guide to integrate the OneSignal SDK into your Amazon Fire OS app for push notifications and in-app messaging capabilities.

## Overview

This guide explains how to integrate OneSignal push notifications into an Amazon Fire OS app. It covers everything from installation to configuration and service worker management.

***

## Requirements

* Your app must be distributed on the Amazon AppStore
* Android 7.0+ device or emulator
* Configured OneSignal app and platform

### Configure your OneSignal app and platform

Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).

<Note>
  If your organization already has a OneSignal account, [ask to be invited](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Step-by-step setup instructions" icon="circle-chevron-down">
  <Steps>
    <Step title="Create or select your app">
      Create a new app by clicking **New App/Website**, or add a platform to an existing app in **Settings > Push & In-App**. Select the platform(s) you want to configure and click **Next: Configure Your Platform**.

      <Frame>
        <img alt="OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection" />
      </Frame>
    </Step>

    <Step title="Configure platform credentials">
      Enter the credentials for your platform:

      * **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
      * **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
      * **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
      * **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)

      Click **Save & Continue** after entering your credentials.
    </Step>

    <Step title="Save your App ID and install the SDK">
      Your **App ID** is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.

      <Frame>
        <img alt="OneSignal dashboard showing the App ID and team invite option after setup" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

***

## Setup

### Update `AndroidManifest.xml`

Open your `AndroidManifest.xml` file and add `xmlns:amazon="http://schemas.amazon.com/apk/res/android"` in the manifest tag right after the `xmlns:android` property.

```xml xml theme={null}
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:amazon="http://schemas.amazon.com/apk/res/android"
    package="com.onesignal.example"
    android:versionCode="1"
    android:versionName="1.0" >
```

Add the following permissions, replacing `COM.YOUR.PACKAGE_NAME` with your actual package name:

```xml xml theme={null}
<uses-permission android:name="com.amazon.device.messaging.permission.RECEIVE" />
<permission
  android:name="COM.YOUR.PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE"
  android:protectionLevel="signature"
/>
<uses-permission android:name="COM.YOUR.PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE" />
```

Configure ADM services and receivers in the `<application>` tag, replacing `COM.YOUR.PACKAGE_NAME` with your actual package name:

```xml xml theme={null}
<application ....>
  <amazon:enable-feature android:name="com.amazon.device.messaging"
                         android:required="false"/>
  <service android:name="com.onesignal.notifications.services.ADMMessageHandler"
           android:exported="false" />
  <service android:name="com.onesignal.notifications.services.ADMMessageHandlerJob"
           android:permission="android.permission.BIND_JOB_SERVICE"
           android:exported="false" />
  <receiver android:name="com.onesignal.notifications.receivers.ADMMessageReceiver"
           android:permission="com.amazon.device.messaging.permission.SEND"
            android:exported="true" >
    <intent-filter>
      <action android:name="com.amazon.device.messaging.intent.REGISTRATION" />
      <action android:name="com.amazon.device.messaging.intent.RECEIVE" />
      <category android:name="COM.YOUR.PACKAGE_NAME" />
    </intent-filter>
  </receiver>

</application>
```

### Amazon API key file

Place your `api_key.txt` inside an `assets` folder in the root of your Android project.

<Frame>
  <img />
</Frame>

To create an `api_key.txt` for your app, follow our [Generate an Amazon API Key](./generate-an-amazon-api-key) guide.

Make sure to use the same keystore when building your APK as you did in step 2.4 in the Amazon Configuration guide.

Ensure that you are not building a `debug` app when testing Amazon push notifications. It must be a `release` type.

Submit the signed APK to [Live App Testing](https://developer.amazon.com/docs/app-testing/live-app-testing-getting-started.html). Submitting a signed APK is a necessary requirement for ADM to work.

<Frame>
  <img />
</Frame>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications, subscription registration, and in-app messaging.

<Warning>
  If you are testing with an Android emulator, it should start with a cold boot.

  1. Go to **Device Manager** in Android Studio.
  2. Select your emulator device and click **Edit**.
  3. Go to **Additional Settings** or **More**.
  4. Set the **Boot option** to **Cold Boot**.
  5. Save changes and restart the emulator.
</Warning>

### Check mobile subscriptions

<Steps>
  <Step title="Launch your app on a test device.">
    The native push permission prompt should appear automatically if you added the `requestPermission` method during initialization.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    Before accepting the prompt, check the OneSignal dashboard:

    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status "Never Subscribed".

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Return to the app and tap Allow on the prompt." />

  <Step title="Refresh the OneSignal dashboard Subscription's page.">
    The subscription's status should now show **Subscribed**.

    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a [mobile subscription](/docs/en/subscriptions).
    Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a segment of test users.
    We can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

    ```curl theme={null}
    curl -X \
    POST --url 'https://api.onesignal.com/notifications' \
     --header 'content-type: application/json; charset=utf-8' \
     --header 'authorization: Key YOUR_APP_API_KEY' \
     --data \
     '{
      "app_id": "YOUR_APP_ID",
      "target_channel": "push",
      "name": "Testing basic setup",
      "headings": {
      	"en": "👋"
      },
      "contents": {
        "en": "Hello world!"
      },
      "included_segments": [
        "Test Users"
      ],
      "ios_attachments": {
        "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      },
      "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
    }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification with an image included:

    <Frame>
      <img />
    </Frame>

    <Info>Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Info>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats.

    You should see the **confirmed** stat, meaning the device received the push.
    <Check>You have successfully sent a notification via our API to a segment.</Check>

    <Warning>
      * No image received? Your [Notification Service Extension](#ios-setup) might be missing.
      * No confirmed receipt? Review the troubleshooting guide [here](/docs/en/confirmed-delivery#troubleshooting-confirmed-delivery).
      * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
    </Warning>
  </Step>
</Steps>

### Send an in-app message

[In-app messages](/docs/en/in-app-messages-setup) let you communicate with users while they are using your app.

<Steps>
  <Step title="Close or background your app on the device.">
    This is because users must meet the in-app audience criteria *before* a new session starts. In OneSignal, a new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds. For more details, see our guide on [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
  </Step>

  <Step title="Create an in-app message.">
    * In your OneSignal dashboard, navigate to **Messages > In-App > New In-App**.
    * Find and select the **Welcome** message.
    * Set your Audience as the **Test Users** segment we used previously.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Customize the message content if desired.">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Set Trigger to 'On app open'." />

  <Step title="Schedule frequency.">
    Under **Schedule > How often do you want to show this message?** select **Every time trigger conditions are satisfied**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Make message live.">
    Click **Make Message Live** so it is available to your Test Users each time they open the app.
  </Step>

  <Step title="Open the app and see the message.">
    After the in-app message is live, open your app. You should see it display:

    <Frame>
      <img />
    </Frame>

    <Warning>
      Not seeing the message?

      * Start a new session
        * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
        * For more, see [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
      * Still in the `Test Users` segment?
        * If you reinstalled or switched devices, re-add the device to [Test Users](#set-up-test-users) and confirm it's part of the Test Users segment.
      * Having issues?
        * Follow [Getting a Debug Log](/docs/en/capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
    </Warning>
  </Step>
</Steps>

<Check>
  You have successfully setup the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](/docs/en/subscriptions), setting [Test Users](/docs/en/find-set-test-subscriptions), and creating [Segments](/docs/en/segmentation).
  * Sending [Push](/docs/en/push) with images and [Confirmed receipt](/docs/en/confirmed-delivery) using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](/docs/en/in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

***

## User identification

Previously, we demonstrated how to create mobile [Subscriptions](/docs/en/subscriptions). Now we'll expand to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We'll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with our SDK's [`login` method](/docs/en/mobile-sdk-reference#login-external-id) each time they are identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with our SDK [`addTag` and `addTags` methods](/docs/en/mobile-sdk-reference#data-tags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img />
</Frame>

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

### Add email and/or SMS subscriptions

Earlier we saw how our SDK creates mobile subscriptions to send push and in-app messages. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/mobile-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/mobile-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/mobile-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/mobile-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

See our Privacy & security docs for more on:

* [Data collected by the SDK](/docs/en/data-collected-by-the-onesignal-sdk)
* [Handling personal data](/docs/en/handling-personal-data)

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](/docs/en/prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners for you to hook into. See our [SDK reference guide](/docs/en/mobile-sdk-reference) for more details.

### Push notification events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-push): Detect when a notification is tapped. Helpful for [Deep Linking](/docs/en/deep-linking).
* [`addForegroundLifecycleListener()`](/docs/en/mobile-sdk-reference#addforegroundlifecyclelistener-push): Control how notifications behave in foreground.

For full customization, see [Mobile Service Extensions](/docs/en/service-extensions).

### User state changes

* [`addObserver()` for user state](/docs/en/mobile-sdk-reference#addobserver-user-state): Detect when the External ID is set.
* [`addPermissionObserver()`](/docs/en/mobile-sdk-reference#addpermissionobserver-push): Track the user's specific interaction with the native push permission prompt.
* [`addObserver()` for push subscription](/docs/en/mobile-sdk-reference#addobserver-push-subscription-changes): Track when the push subscription status changes.

### In-app message events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Handle in-app click actions. Ideal for deep linking or tracking events.
* [`addLifecycleListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Track full lifecycle of in-app messages (shown, clicked, dismissed, etc.).

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

* [🔁 Migrating to OneSignal from another service](/docs/en/migrating-to-onesignal)
* [🌍 Location tracking](/docs/en/mobile-sdk-reference#location)
* [🔗 Deep Linking](/docs/en/deep-linking)
* [🔌 Integrations](/docs/en/integrations)
* [🧩 Mobile Service Extensions](/docs/en/service-extensions)
* [🛎️ Action buttons](/docs/en/action-buttons)
* [🌐 Multi-language messaging](/docs/en/multi-language-messaging)
* [🛡️ Identity Verification](/docs/en/identity-verification)
* [📊 Custom Outcomes](/docs/en/custom-outcomes)
* [📲 Live Activities](/docs/en/live-activities)

### Mobile SDK setup & reference

Make sure you've enabled all key features by reviewing the [Mobile push setup](/docs/en/mobile-push-setup) guide.

For full details on available methods and configuration options, visit the [Mobile SDK reference](/docs/en/mobile-sdk-reference).

<Check>Congratulations! You've successfully completed the Mobile SDK setup guide.</Check>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Android live notifications
Source: https://documentation.onesignal.com/docs/en/android-live-notifications

Create and update dynamic, real-time notifications on Android devices using OneSignal Live Notifications. Deliver continuously updated content inside a single notification, simulating iOS Live Activities for Android.

OneSignal’s Android Live Notifications let you send real-time updates to a single notification, reducing clutter and improving engagement. These notifications remain persistent and update their content dynamically—ideal for sports scores, download progress, or event tracking.

To receive Live Notifications, Android users must have push notifications enabled.

## Requirements

* Your app must use the latest version of the [OneSignal SDK](./mobile-sdk-setup).
* Android users must have push notification permissions enabled.

***

## Live notifications vs. standard push

Unlike regular push notifications, which send a new notification each time, Live Notifications use a single notification updated over time. Updates are sent via the [Create Message API](/reference/create-message) using the same `collapse_id`.

***

## Configuration

### 1. Implement a Notification Service Extension

Create a `NotificationServiceExtension` class that implements `INotificationServiceExtension`. This class intercepts incoming notifications and can modify or override them.

<Info>
  Refer to [Android Notification Service Extension](./service-extensions#android-notification-service-extension) for more details.
</Info>

```kotlin NotificationServiceExtention.kt theme={null}
package com.onesignal.sample.android

import android.app.NotificationChannel
import android.app.NotificationManager
import android.content.Context
import android.os.Build
import com.onesignal.notifications.INotificationReceivedEvent
import com.onesignal.notifications.INotificationServiceExtension
import org.json.JSONObject
import java.util.logging.Logger

class NotificationServiceExtension : INotificationServiceExtension {
  override fun onNotificationReceived(event: INotificationReceivedEvent) {
        val context = event.context
        val notificationManager = context.getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
            ?: run {
                logger.warning("NotificationManager not available.")
                return
            }

        notificationManager.let {
            if (!notificationChannelsCreated) {
                createNotificationChannels(notificationManager)
            }
        }

        // Use `additional_data`to submit the Live Notification payload.
    		val additionalData = event.notification.additionalData
        val liveNotificationPayload = additionalData?.optJSONObject("live_notification")
        if (liveNotificationPayload == null) {
            logger.info("No live notification payload found. Showing original notification.")
            return
        }

        event.preventDefault()
        handleLiveNotification(event, liveNotificationPayload, notificationManager, context)
    }
}

```

### 2. Add the extension to the Android Manifest

<CodeGroup>
  ```xml AndroidManifest.xml theme={null}
    <meta-data android:name="com.onesignal.NotificationServiceExtension"
                android:value="com.onesignal.sample.android.NotificationServiceExtension" />
  ```

  ```xml Example AndroidManifest.xml theme={null}
  <?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
      xmlns:tools="http://schemas.android.com/tools">

      <application
          android:allowBackup="true"
          android:dataExtractionRules="@xml/data_extraction_rules"
          android:fullBackupContent="@xml/backup_rules"
          android:icon="@mipmap/ic_launcher"
          android:name=".MainApplication"
          android:label="@string/app_name"
          android:roundIcon="@mipmap/ic_launcher_round"
          android:supportsRtl="true"
          android:theme="@style/Theme.OneSignalAndroidSample"
          tools:targetApi="31">
          <meta-data android:name="com.onesignal.NotificationServiceExtension"
              android:value="com.onesignal.sample.android.NotificationServiceExtension" />
          <activity
              android:name=".MainActivity"
              android:exported="true">
              <intent-filter>
                  <action android:name="android.intent.action.MAIN" />

                  <category android:name="android.intent.category.LAUNCHER" />
              </intent-filter>
          </activity>
      </application>

  </manifest>
  ```
</CodeGroup>

### 3. Create Live Notification types

A Live Notification Type indicates which Live Notification to start.

#### Define keys

Live Notifications are referenced by a `key`, which determines how updates are routed.

```kotlin NotificationServiceExtention.kt theme={null}
private const val PROGRESS_LIVE_NOTIFICATION = "progress"
```

#### Create notification channels

Channels define how notifications behave (sound, vibration, appearance). You must create channels for your Live Notification types. We recommend:

* Low Importance for progress notifications
* Disable badges
* Keep sound and vibration to a minimum

See [Android Notification Channel Categories](./android-notification-categories) for more information.

#### Design the Live Notification

When designing a Live Notification, you have the flexibility to create a notification design for each update type. Each design you create must be assigned a specific type, allowing for varied presentations of a Live Notification.

```kotlin NotificationServiceExtention.kt theme={null}
private fun updateProgressNotification(
        liveNotificationUpdates: JSONObject,
        context: Context,
        notificationManager: NotificationManager
    ) {
        val currentProgress = liveNotificationUpdates.optInt("current_progress", 0)

        val builder = NotificationCompat.Builder(context, PROGRESS_CHANNEL_ID)
            .setContentTitle("Progress Live Notifications")
            .setContentText("It's working...")
            .setSmallIcon(android.R.drawable.ic_media_play)
            .setLargeIcon(BitmapFactory.decodeResource(context.resources, android.R.drawable.ic_dialog_info))
            .setOngoing(true)
            .setOnlyAlertOnce(true)
            .setProgress(100, currentProgress, false)
            .setAutoCancel(false) // Prevent auto-dismissal of notification until you set the end event

        notificationManager.notify(keyMap[PROGRESS_LIVE_NOTIFICATION]!!, builder.build())
        logger.info("Updated progress notification with progress: $currentProgress")
    }
```

**Design considerations:**

* Small icon & accent color
* Large icon
* Big picture
* Action buttons

<Info>
  See [Android custom notification layout](https://developer.android.com/develop/ui/views/notifications/custom-notification) for advanced design options.
</Info>

### 4. Extract the Live Notification payload

Live Notifications use the `additional_data` field to pass structured content.

```kotlin NotificationServiceExtention.kt theme={null}
val additionalData = event.notification.additionalData
val liveNotificationPayload = additionalData?.optJSONObject("live_notification")
```

#### Live Notification Schema

| Property           | Required | Description                                                                                                                       |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `key`              | Yes      | Used to load the correct notification UI.                                                                                         |
| `event`            | Yes      | The action to perform on the Live Notification.                                                                                   |
| `event_attributes` | No       | Static data is used to initialize the Live Notification; a Self-defined schema that defines the data your notification needs.     |
| `event_updates`    | No       | Dynamic content of the Live Notification. Must conform to the ContentState interface defined within your app's Live Notification. |

```json Example Live Notification Payload theme={null}
  {
      "key": "celtics-vs-lakers",
      "event": "start",
      "event_attributes": {
          "homeTeam": "Celtics",
          "awayTeam": "Lakers",
          "game": "Finals Game 1"
      },
      "event_updates": {
          "quarter": 1,
          "homeScore": 0,
          "awayScore": 0,
      }
  }
```

### 5. Handle Live Notification events

Each Live Notification must respond to the following events:

| Event    | Description                                              | Required fields                     |
| -------- | -------------------------------------------------------- | ----------------------------------- |
| `start`  | Begins a Live Notification with static and dynamic data. | `event_attributes`, `event_updates` |
| `update` | Updates the Live Notification with new dynamic data.     | `event_updates`                     |
| `end`    | Ends and removes the Live Notification.                  | None                                |

```kotlin NotificationServiceExtention.kt theme={null}
val liveNotificationEvent = liveNotificationPayload.optString("event", "")
```

***

## Start a Live Notification

When you are ready to start a Live Notification:

* Set `event_attributes` to initialize the static data for the Live Notification. This data will not change during the lifetime of the Live Notification.
* Set `event_updates` data to initialize the dynamic data for the Live Notification. This is the data that can and will change during the lifetime of the Live Notification.
* A [`collapse_id`](./push#collapse-id) to make sure each update overrides the previous. This ID should be unique to the Live Notification to ensure subsequent updates are reflected in the same notification.

```curl curl theme={null}
  curl -X "POST" "https://api.onesignal.com/notifications" \
       -H 'Authorization: key YOUR_REST_API_KEY' \
       -H 'Content-Type: application/json; charset=utf-8' \
       -d $'{
    "app_id": "YOUR_APP_ID",
    "isAndroid": true,
    "collapse_id": "THE_UNIQUE_ID_FOR_THIS_LIVE_NOTIFICATION",
    "data": {
      "live_notification": {
        "key": "progress",
        "event": "start",
        "event_attributes": {},
        "event_updates": {
          "current_progress": 0
        }
      }
    },
    "headings": {
      "en": "Start"
    },
    "contents": {
      "en": "Starting Live Notification"
    },
    "include_aliases": {
      "external_id": ["EID1", "EID2"]
    },
    "target_channel": "push"
  }'
```

***

## Update Live Notification

You can update the Live Notification as many times as you like, so long as it's started first.

* Set `event_updates` data to initialize the dynamic data for the Live Notification. This is the data that can and will change during the lifetime of the Live Notification and informs what to update your Live Notification's content with.

**Example cURL request**

```curl curl theme={null}
  curl -X "POST" "https://api.onesignal.com/notifications" \
       -H 'Authorization: key YOUR_REST_API_KEY' \
       -H 'Content-Type: application/json; charset=utf-8' \
       -d $'{
    "app_id": "YOUR_APP_ID",
    "isAndroid": true,
    "collapse_id": "THE_UNIQUE_ID_FOR_THIS_LIVE_NOTIFICATION",
    "data": {
      "live_notification": {
        "key": "progress",
        "event": "update",
  			"event_attributes": {},
        "event_updates": {
          "current_progress": 80
        }
      }
    },
    "headings": {
      "en": "Update"
    },
    "contents": {
      "en": "Updating Live Notification"
    },
    "include_aliases": {
      "external_id": ["EID1", "EID2"]
    },
    "target_channel": "push"
  }'
```

## End Live Notification

**Example cURL request**

```curl curl theme={null}
  curl -X "POST" "https://api.onesignal.com/notifications" \
       -H 'Authorization: key YOUR_REST_API_KEY' \
       -H 'Content-Type: application/json; charset=utf-8' \
       -d $'{
    "app_id": "YOUR_APP_ID",
    "isAndroid": true,
    "collapse_id": "THE_UNIQUE_ID_FOR_THIS_LIVE_NOTIFICATION",
    "data": {
      "live_notification": {
        "key": "progress",
        "event": "dismiss"
      }
    },
    "headings": {
      "en": "Dismissing"
    },
    "contents": {
      "en": "Dismissing Live Notification"
    },
    "include_aliases": {
      "external_id": ["EID1", "EID2"]
    },
    "target_channel": "push"
  }'
```

***

<Check>
  You have successfully created a Live Notification!

  Related docs:

  * [Android Notification Service Extension](./service-extensions#android-notification-service-extension)
  * [Android SDK Setup](./mobile-sdk-setup)
  * [Create Message API](/reference/create-message)
</Check>

***


# Android SDK setup
Source: https://documentation.onesignal.com/docs/en/android-sdk-setup

Add push notifications and in-app messages to your Android app using OneSignal's Android SDK.

<SdkReleasesIframe />

This guide walks you through adding OneSignal to your Android app using Android Studio. You'll install our SDK, setup push and in-app messages, and send test messages to confirm everything is working.

If this is your first time using OneSignal, follow the steps in order. If you're experienced, feel free to jump to the sections you need.

<Info>
  **Using an AI coding assistant?**
  For AI-driven installation, use this prompt:

  ```
  Integrate the OneSignal Android SDK into this codebase.

  Follow the instructions at:
  https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md
  ```
</Info>

## Step 0. Configure FCM in OneSignal (required to deliver push)

You can install and initialize the OneSignal Android SDK without completing this step. However, **push notifications will not deliver** until Firebase Cloud Messaging (FCM) credentials are configured in your OneSignal app.

<Note>
  If your company already has a OneSignal account, [ask to be invited as an admin role](./manage-team-members) to configure the app. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Steps to configure your OneSignal app.">
  These steps connect your OneSignal app to Firebase Cloud Messaging (FCM). You only need to do this once per app.

  1. Login to [https://onesignal.com](https://onesignal.com) and create or select your App.
  2. Navigate to **Settings > Push & In-App**.
  3. Select **Google Android (FCM)** and **Continue** through the setup wizard.
  4. Input your [Firebase Server Key or Service Account](./android-firebase-credentials) details.
  5. Continue through the setup wizard to get your App ID. This will be used to initialize the SDK.

  <Info>For full setup instructions, see our [Mobile push setup](./mobile-push-setup) guide.</Info>
</Accordion>

***

## Setup contract & requirements

This section summarizes the tools, versions, and assumptions used throughout the guide.

* **SDK version:** `5.6.1+` (latest: check [releases](https://github.com/OneSignal/OneSignal-Android-SDK/releases))
* **AI setup instructions:** `https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md`
* **SDK repo:** `https://github.com/OneSignal/OneSignal-Android-SDK`
* **Android Studio:** Meerkat+ (2024.2.1+)
* **Android API:** 23+ minimum (Android 6.0+), 31+ recommended (Android 12+)
* **Device/Emulator:** Android 7.0+ with Google Play Services installed
* **Required dependency:** `com.onesignal:OneSignal:[5.6.1, 5.9.99]`
* **Application class:** Required for proper SDK initialization
* **App ID format:** 36-character UUID (example: `12345678-1234-1234-1234-123456789012`) — find at OneSignal Dashboard > Settings > Keys & IDs
* **Initialize:** `OneSignal.initWithContext(this, "YOUR_APP_ID")`
* **Battery Optimization:** May affect background notifications
* **Recommended:** Assign External ID via `OneSignal.login("user_id")` to unify users across devices

***

## Android setup steps

By the end of the steps below, you will have:

* The OneSignal SDK installed and initialized in your Android app
* Push notification permissions prompting correctly on a real device
* A test push and in-app message successfully delivered

<Info>
  If you skipped **Step 0 (Configuring FCM in OneSignal)**, you can still complete the Android Studio setup below. Complete Step 0 before you test or send push notifications.
</Info>

### Step 1. Add the OneSignal SDK

1. In Android Studio, open your `build.gradle.kts (Module: app)` or `build.gradle (Module: app)` file
2. Add OneSignal to your `dependencies` section:

<CodeGroup>
  ```kotlin app/build.gradle.kts theme={null}
  implementation("com.onesignal:OneSignal:[5.6.1, 5.9.99]")
  ```

  ```groovy app/build.gradle theme={null}
  implementation 'com.onesignal:OneSignal:[5.6.1, 5.9.99]'
  ```
</CodeGroup>

<Frame>
  <img />
</Frame>

3. **Sync Gradle:** Click **Sync Now** in the banner that appears or go to **File > Sync Project with Gradle Files**

<Check>
  Verify that the gradle sync completes successfully without dependency conflicts.
</Check>

### Step 2. Create and configure Application class

It's best practice to initialize OneSignal in the `onCreate` method of your `Application` class to ensure proper SDK setup across all entry points.

**Create an Application class if you don't already have one:**

1. **File > New > Kotlin Class/File** (or Java Class)
2. Name: `ApplicationClass` (or your preferred name)

<Frame>
  <img />
</Frame>

**Add the following OneSignal code to the Application class.**

Replace `YOUR_APP_ID` with your actual OneSignal App ID from the Dashboard > Settings > [Keys & IDs](./keys-and-ids).

<CodeGroup>
  ```kotlin ApplicationClass.kt theme={null}
  // FILE: ApplicationClass.kt
  // PURPOSE: Initialize OneSignal when your app launches
  // REQUIREMENT: Must be registered in AndroidManifest.xml

  package com.your.package.name // Replace with your actual package name

  import android.app.Application
  import kotlinx.coroutines.CoroutineScope
  import kotlinx.coroutines.Dispatchers
  import kotlinx.coroutines.launch

  import com.onesignal.OneSignal
  import com.onesignal.debug.LogLevel

  class ApplicationClass : Application() {
      override fun onCreate() {
          super.onCreate()

          // Enable verbose logging to debug issues (remove in production)
          OneSignal.Debug.logLevel = LogLevel.VERBOSE

          // Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
          OneSignal.initWithContext(this, "YOUR_APP_ID")

          // Prompt user for push notification permission
          // In production, consider using an in-app message instead for better opt-in rates
          CoroutineScope(Dispatchers.IO).launch {
              OneSignal.Notifications.requestPermission(false)
          }
      }
  }
  ```

  ```java ApplicationClass.java theme={null}
  // FILE: ApplicationClass.java
  // PURPOSE: Initialize OneSignal when your app launches
  // REQUIREMENT: Must be registered in AndroidManifest.xml

  package com.your.package.name; // Replace with your actual package name

  import android.app.Application;

  import com.onesignal.Continue;
  import com.onesignal.OneSignal;
  import com.onesignal.debug.LogLevel;

  public class ApplicationClass extends Application {
      @Override
      public void onCreate() {
          super.onCreate();
          
          // Enable verbose logging to debug issues (remove in production)
          OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE);
          
          // Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
          OneSignal.initWithContext(this, "YOUR_APP_ID");
          
          // Prompt user for push notification permission
          // In production, consider using an in-app message instead for better opt-in rates
          OneSignal.getNotifications().requestPermission(false, Continue.none());
      }
  }
  ```
</CodeGroup>

<Frame>
  <img />
</Frame>

<Warning>
  Initializing in an `Activity` (like `MainActivity`) is not recommended because it may not be called on app cold-starts from deep links or notifications. Always initialize OneSignal in your `Application` class for reliability.
</Warning>

**Register the Application class:**

1. Open your app's `AndroidManifest.xml`
2. In your `<application>` tag add `android:name=".ApplicationClass"` (replace `.ApplicationClass` with your actual class name if set it to something different).

```xml AndroidManifest.xml theme={null}
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application
        android:name=".ApplicationClass"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        ...
      </application>

  </manifest>
```

<Frame>
  <img />
</Frame>

<Check>
  Verify that the app builds and runs without errors.
</Check>

### Step 3. Configure default notification icons (recommended)

Customize [notification icons](./notification-icons) to match your app's branding. This step is optional but recommended for a professional appearance.

### Step 4. Test the integration

**Verify Subscription creation:**

1. Launch app on device or emulator with Google Play Services
2. Check Dashboard > **Audience > Subscriptions** — status shows "Never Subscribed"
3. Accept the permission prompt when it appears
4. Refresh dashboard — status changes to "Subscribed"

<Frame>
  <img alt="Example of the iOS and Android push permission prompts." />
</Frame>

<Frame>
  <img alt="Dashboard showing Subscription with 'Never Subscribed' status." />
</Frame>

<Frame>
  <img alt="After allowing push permissions, refresh the dashboard to see the Subscription status update to 'Subscribed'." />
</Frame>

<Check>
  You have successfully created a [mobile Subscription](./subscriptions).
  Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.
</Check>

#### Create test user and segment

1. Click **⋮** next to the Subscription > **Add to Test Users** > name it
2. Go to **Audience > Segments > New Segment**
3. Name: `Test Users`, add filter **Test Users** > **Create Segment**

<Frame>
  <img alt="Add a test user." />
</Frame>

<Frame>
  <img alt="Create a 'Test Users' segment with the Test Users filter." />
</Frame>

<Check>
  You have successfully created a segment of test users.

  We can now test sending messages to this individual device and groups of test users.
</Check>

#### Send test push via API

1. Navigate to **Settings > [Keys & IDs](./keys-and-ids)**.
2. In the provided code, replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

```bash theme={null}
curl -X POST 'https://api.onesignal.com/notifications' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Key YOUR_APP_API_KEY' \
  -d '{
    "app_id": "YOUR_APP_ID",
    "target_channel": "push",
    "name": "Testing basic setup",
    "headings": { "en": "👋" },
    "contents": {"en": "Hello world!"},
    "included_segments": ["Test Users"],
    "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  }'
```

<Frame>
  <img alt="Images in push notifications appear small in the collapsed notification view. Expand the notification to see the full image." />
</Frame>

<Frame>
  <img alt="Delivery stats showing confirmed receipt (unavailable on free plans)." />
</Frame>

<Check>
  Verify the test device received a notification with:

  * Your custom icon (if configured)
  * Large image when expanded
  * Dashboard > **Delivery > Sent Messages** shows "Confirmed" status (unavailable on free plans).
</Check>

<Warning>
  * No notification received? See [Mobile push not shown](./notifications-show-successful-but-are-not-being-shown).
  * No custom icon? Verify the icon name is `onesignal_small_icon_default` and in the correct drawable folders.
  * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
</Warning>

#### Test in-app messages

1. Close app for 30+ seconds
2. Dashboard > **Messages > In-App > New In-App** > select **Welcome** template
3. Audience: **Test Users** segment
4. Trigger: **On app open**
5. Schedule: **Every time trigger conditions are satisfied**
6. Click **Make Message Live**
7. Open app

<Frame>
  <img alt="Targeting the 'Test Users' segment with an in-app message." />
</Frame>

<Frame>
  <img alt="Example customization of in-app Welcome message." />
</Frame>

<Frame>
  <img alt="In-app message scheduling options." />
</Frame>

<Frame>
  <img alt="Welcome in-app message shown on devices." />
</Frame>

<Check>
  Verify the test device received an in-app message. See the [In-app messages setup](./in-app-messages-setup) guide for more details.
</Check>

<Warning>
  Not seeing the message?

  * Start a new session
    * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
    * For more, see [how in-app messages are displayed](./in-app-messages-setup#how-are-iams-displayed%3F).
  * Still in the `Test Users` segment?
    * If you reinstalled or switched devices, re-add the device to [Test Users](./test-users) and confirm it's part of the Test Users segment.
  * Having issues?
    * Follow [Getting a Debug Log](./capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
</Warning>

<Check>
  You have successfully set up the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](./subscriptions), setting [Test Users](./test-users), and creating [Segments](./segmentation).
  * Sending [Push](./push) with images using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](./in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

### Common Errors & Fixes

| Error / Symptom                             | Cause                                         | Fix                                                                 |
| ------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------- |
| `Cannot resolve symbol 'OneSignal'`         | SDK dependency not added or gradle not synced | Add dependency to build.gradle and sync project                     |
| `Application class not found`               | Application class not registered in manifest  | Add `android:name=".ApplicationClass"` to `<application>` tag       |
| `Google Play Services not available`        | Emulator/device missing Play Services         | Use device with Play Store or emulator with Google APIs             |
| Push received but default Android icon      | Custom icon not configured or wrong name      | Create notification icon asset named `onesignal_small_icon_default` |
| No push notifications received              | FCM not configured in OneSignal               | Complete Step 0: Configure FCM credentials in OneSignal dashboard   |
| In-app messages not showing                 | Session not started or network issues         | Close app 30+ seconds, reopen, check internet connection            |
| `Manifest merger failed`                    | Conflicting manifest attributes               | Check for duplicate application names or permissions conflicts      |
| Battery optimization blocking notifications | Device power management                       | Guide users to disable battery optimization for your app            |
| Can't diagnose issue                        | Not enough log info                           | Add verbose logging and check logcat output for errors              |

***

## User management

Previously, we demonstrated how to create mobile [Subscriptions](./subscriptions). Now we'll expand to identifying [Users](./users) across all their Subscriptions (including push, email, and SMS) using the OneSignal SDK.

### Assign External ID (recommended)

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems. See our [Mobile SDK reference](./mobile-sdk-reference) for more details and Java code examples.

```kotlin Kotlin theme={null}
// Call when user logs in or is identified, safe to call multiple times
// Typically used in a login completion handler, or on app launch if already authenticated
fun onUserAuthenticated(userId: String) {
    OneSignal.login(userId)
}

// If you want to remove the External ID from the Subscription, setting it to an anonymous user
fun onUserLoggedOut() {
    OneSignal.logout()
}
```

<Note>
  OneSignal generates unique read-only IDs for Subscriptions (Subscription ID) and Users (OneSignal ID).

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.

  Learn more about the [`login` method](./mobile-sdk-reference#login-external-id) in the SDK reference guide.
</Note>

### Add Tags & Custom Events

Tags and Custom Events are both ways to add data to your users. Tags are `key-value` strings and are generally associated with user properties (like `username`, `role`, or `status`) while Custom Events have a JSON format and are usually associated with actions (like `new_purchase`, `abandoned_cart`, and associated properties). Both can be used to power advanced [Message Personalization](./message-personalization) and Journeys. See our [Mobile SDK reference](./mobile-sdk-reference) for more details and Java code examples.

```kotlin Kotlin theme={null}
// Add a tag when the user's name is set
OneSignal.User.addTag("username", "john_doe")

// Create a custom event when user abandoned a cart
val properties = mapOf(
    "product_id" to "123456",
    "product_name" to "Product Name",
    "product_price" to 100,
    "product_quantity" to 1
)
OneSignal.User.trackEvent("abandoned_cart", properties)
```

<Note>
  More details on how to use Tags and Custom Events in the [Tags](./add-user-data-tags) and [Custom Events](./custom-events) guides.
</Note>

### Add email and/or SMS subscriptions

You can reach users through email and SMS channels in addition to push notifications. If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user — it will not create duplicates. See our [Mobile SDK reference](./mobile-sdk-reference) for more details and Java code examples.

```kotlin Kotlin theme={null}
// Add email subscription
// Call when user provides their email (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addEmail("user@example.com")

// Add SMS subscription
// Use E.164 format: + country code + number
// Call when user provides their phone number (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addSms("+15551234567")
```

<Frame>
  <img alt="A user profile with push, email, and SMS subscriptions unified by External ID." />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods. See our [Mobile SDK reference](./mobile-sdk-reference) for more details and Java code examples.

```kotlin Kotlin theme={null}
// In ApplicationClass onCreate(), BEFORE OneSignal.initWithContext()
// Use this if your app requires GDPR or other privacy consent before data collection
OneSignal.consentRequired = true

// Later, after user grants consent (e.g., taps "I Agree" on your consent screen)
OneSignal.consentGiven = true
```

<Note>
  See our Privacy & security docs for more on:

  * [Data collected by the SDK](./data-collected-by-the-onesignal-sdk)
  * [Handling personal data](./handling-personal-data)
</Note>

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](./prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes. Add these in your Application class after `OneSignal.initWithContext()`.

### Push notification events

```kotlin Kotlin theme={null}
// Add click listener to handle when users tap notifications
val clickListener = object : INotificationClickListener {
  override fun onClick(event: INotificationClickEvent) {
    Log.d("OneSignal", "Notification clicked: ${event.notification.title}")
  }
}
OneSignal.Notifications.addClickListener(clickListener)
```

### User state changes

Example shows how to use push subscription observer. Other user state events like the user state observer and notification permission observer are available in the [Mobile SDK Reference](./mobile-sdk-reference).

```kotlin Kotlin theme={null}
// Add subscription observer to track push subscription changes
class MyObserver : IPushSubscriptionObserver {
  init {
    OneSignal.User.pushSubscription.addObserver(this)
  }

  override fun onPushSubscriptionChange(state: PushSubscriptionChangedState) {
    if (state.current.optedIn) {
      println("User is now opted-in with push token: ${state.current.token}")
    }
  }
}
```

### In-app message events

Additional in-app message methods are available in the [Mobile SDK Reference](./mobile-sdk-reference).

```kotlin Kotlin theme={null}
// Add click listener for in-app message interactions
val clickListener = object : IInAppMessageClickListener {
  override fun onClick(event: IInAppMessageClickEvent) {
    print(event.result.actionId)
  }
}
OneSignal.InAppMessages.addClickListener(clickListener)
```

***

## Advanced setup & capabilities

### Android-specific features

* **[Notification Channels](./mobile-sdk-reference#notification-channels)** — Organize notifications into categories (Android 8.0+)
* **[Service Extensions](./service-extensions)** — Advanced notification customization
* **[Huawei/HMS Support](./huawei-sdk-setup)** — Alternative to Google Play Services

### Universal features

* [Deep Linking](./deep-linking) — Navigate users to specific screens from notifications
* [Action Buttons](./action-buttons) — Add interactive buttons to notifications
* [Identity Verification](./identity-verification) — Secure user identification
* [Location Tracking](./mobile-sdk-reference#location) — Location-based targeting
* [Integrations](./integrations) — Connect with analytics and data platforms
* [Multi-language Messaging](./multi-language-messaging) — Localized notifications

For full SDK method documentation, visit the [Mobile SDK Reference](./mobile-sdk-reference).

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Angular Web SDK setup
Source: https://documentation.onesignal.com/docs/en/angular-setup

Integrate OneSignal Web Push Notifications into your Angular application using the onesignal-ngx package. Learn how to install, configure, and troubleshoot service workers to deliver seamless push notifications.

<SdkReleasesIframe />

## Overview

This guide explains how to set up push notifications in your Angular application using the `onesignal-ngx` package, covering everything from installation to configuration and service worker management.

***

## Requirements

* Configured OneSignal app and platform. See [Web Push Setup](./web-push-setup) to get started.

***

## Installation

Install the `onesignal-ngx` package using your preferred package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install --save onesignal-ngx
  ```

  ```bash yarn theme={null}
  yarn add onesignal-ngx
  ```
</CodeGroup>

***

## Initialization

Import the OneSignal service and initialize it in your root component:

```typescript ts theme={null}
import { OneSignal } from 'onesignal-ngx';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  constructor(private oneSignal: OneSignal) {
    this.oneSignal.init({
      appId: 'YOUR-ONESIGNAL-APP-ID',
    });
  }
}

```

<Note>The example above initializes in the `AppComponent` constructor, which is the recommended approach. If you use `ngOnInit` instead, ensure it is not triggered multiple times due to route changes re-creating the root component. Alternatively, use a service with a guard to prevent re-initialization.</Note>

### Awaiting initialization

You can handle the promise returned by `init()` in two ways:

```typescript ts theme={null}
// Option 1: async/await
await this.oneSignal.init({ appId: 'YOUR-APP-ID' });
// proceed with other logic

// Option 2: .then()
this.oneSignal.init({ appId: 'YOUR-APP-ID' }).then(() => {
  // safe to interact with OneSignal APIs
});

```

### Customizing init options

You can customize your initialization with additional [`init` parameters](./web-sdk-reference#init).

### Service Worker Settings

To avoid conflicts with Angular's own service worker (used in PWA setups), specify a unique scope and path for the OneSignal service worker.

If you haven't done so already, you will need to [download the OneSignal Service Worker file](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip) to add to your site.

The `OneSignalSDKWorker.js` file must be publicly accessible. You can put it in your `public` directory, top-level root, or a subdirectory. However, if you are placing the file in a subdirectory and/or have another service worker for your site, then make sure to specify the path. See [OneSignal Service Worker](./onesignal-service-worker) for details.

| Option               | Description                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `serviceWorkerParam` | Scope controlled by the OneSignal worker. **Recommendation:** Use a custom sub-path (e.g., `"/onesignal/"`).                |
| `serviceWorkerPath`  | Path to your hosted OneSignal service worker file (e.g., `"onesignal/OneSignalSDKWorker.js"`). Must be publicly accessible. |

**Example:**

```typescript theme={null}
this.oneSignal.init({
  appId: 'YOUR-APP-ID',
  serviceWorkerParam: {
    scope: '/onesignal/'
  },
  serviceWorkerPath: 'onesignal/OneSignalSDKWorker.js'
});
```

#### Hosting the worker

* Public root (default): `/OneSignalSDKWorker.js`
* Custom folder (recommended): e.g., `/onesignal/OneSignalSDKWorker.js` as set in the previous step.

#### Verify service worker hosting

Visit the path in your browser to confirm it's accessible.

If you used root:

```
https://your-site.com/OneSignalSDKWorker.js
```

If using the example path:

```
https://your-site.com/onesignal/OneSignalSDKWorker.js
```

It should return valid JavaScript.

#### Important for Angular CLI users

If the file is not being served, ensure it's listed in your `angular.json` under the `assets` array:

```json json theme={null}
"assets": [
  "src/assets",
  "onesignal/OneSignalSDKWorker.js"
]
```

### Important notes

* Avoid Duplicate Initialization in Development
  * When testing in a development environment, ensure OneSignal.init() is called only once.
  * If you are using Angular's OnInit lifecycle hook, make sure it is not triggered multiple times (e.g., due to route changes re-creating the root component). Consider initializing in the AppComponent constructor or using a service with a guard to prevent re-initialization.

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications and subscription registration.

### Check web push subscriptions

<Steps>
  <Step title="Launch your site on a test device.">
    * Use Chrome, Firefox, Edge, or Safari while testing.
    * **Do not use Incognito or private browsing mode.** Users cannot subscribe to push notifications in these modes.
    * The prompts should appear based on your [permission prompts](/docs/en/permission-requests) configuration.
    * Click **Allow** on the native prompt to subscribe to push notifications.

    <Frame>
      <img alt="Browser native permission prompt asking the user to allow or block notifications" />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status **Subscribed**.

    <Frame>
      <img alt="OneSignal dashboard Subscriptions page showing a web push subscription with Subscribed status" />
    </Frame>

    <Check>You have successfully created a [web push subscription](/docs/en/subscriptions).
    Web push subscriptions are created when users first subscribe to push notifications on your site.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img alt="Options menu on a subscription showing the Add to test users option" />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img alt="Segment editor with Test Users filter selected and the segment named Test Users" />
    </Frame>

    <Check>You have successfully created a segment of test users.
    You can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment created earlier.

    ```curl theme={null}
    curl -X POST --url 'https://api.onesignal.com/notifications' \
      --header 'content-type: application/json; charset=utf-8' \
      --header 'authorization: Key YOUR_APP_API_KEY' \
      --data '{
        "app_id": "YOUR_APP_ID",
        "target_channel": "push",
        "name": "Testing basic setup",
        "headings": {
          "en": "👋"
        },
        "contents": {
          "en": "Hello world!"
        },
        "included_segments": [
          "Test Users"
        ],
        "chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification.

    <Warning>Only Chrome supports images. Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Warning>

    <Frame>
      <img alt="Expanded Chrome push notification on macOS displaying a custom image" />
    </Frame>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats. You should see the **confirmed** stat, meaning the device received the push.

    <Note>Safari does not support confirmed receipt.</Note>

    <Card title="Push notification message reports" icon="chart-bar" href="/docs/en/push-notification-message-reports">
      View delivery, click, and conversion stats for your push notifications.
    </Card>
  </Step>
</Steps>

<Check>You have successfully sent a notification via the API to a segment.</Check>

If notifications are not arriving, contact `support@onesignal.com` with the following:

* The API request and response (copy-paste into a `.txt` file)
* Your Subscription ID
* Your website URL with the OneSignal code

***

## User identification

The previous section covered creating web push [Subscriptions](/docs/en/subscriptions). This section expands to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. It covers External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with the SDK's [`login` method](/docs/en/web-sdk-reference#login-external-id) each time a user is identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via the SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with the SDK's [`addTag` and `addTags` methods](/docs/en/web-sdk-reference#addtag-%2C-addtags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img alt="OneSignal user profile showing a data tag named current_level with value 6" />
</Frame>

You can create a segment of users with a level between 5 and 10, then use that segment to send targeted and personalized messages:

<Frame>
  <img alt="Segment editor filtering users where current_level is greater than 4 and less than 10" />
</Frame>

<Frame>
  <img alt="Push notification composer targeting the Level 5-10 segment with a personalized message" />
</Frame>

### Add email and/or SMS subscriptions

The OneSignal SDK creates web push subscriptions automatically when users opt in. You can also reach users through email and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/web-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/web-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address or phone number already exists in the OneSignal app, the SDK adds it to the existing user. It does not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img alt="OneSignal user profile showing push, email, and SMS subscriptions linked by External ID" />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/web-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/web-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

For more on privacy and security:

<Columns>
  <Card title="Data collected by the SDK" icon="database" href="/docs/en/data-collected-by-the-onesignal-sdk">
    Review what data the OneSignal SDK collects from users.
  </Card>

  <Card title="Handling personal data" icon="shield-halved" href="/docs/en/handling-personal-data">
    Manage and protect user data in compliance with privacy regulations.
  </Card>
</Columns>

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners you can hook into. See the [SDK reference guide](/docs/en/web-sdk-reference) for more details.

### Push notification events

* [Click event listener](/docs/en/web-sdk-reference#click): Detect when a notification is tapped.
* [Foreground lifecycle listener](/docs/en/web-sdk-reference#foregroundwilldisplay): Control how notifications behave in foreground.

### User state changes

* [User state change event listener](/docs/en/web-sdk-reference#addeventlistener-user-state): Detect when the External ID is set.
* [Permission observer](/docs/en/web-sdk-reference#permissionchange): Track the user's specific interaction with the native push permission prompt.
* [Push subscription change observer](/docs/en/web-sdk-reference#addeventlistener-push-subscription-changes): Track when the push subscription status changes.

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

<Columns>
  <Card title="Migrating to OneSignal" icon="rotate" href="/docs/en/migrating-to-onesignal">
    Move from another push provider to OneSignal.
  </Card>

  <Card title="Integrations" icon="plug" href="/docs/en/integrations">
    Connect OneSignal with third-party tools and platforms.
  </Card>

  <Card title="Action buttons" icon="bell" href="/docs/en/action-buttons">
    Add interactive buttons to push notifications.
  </Card>

  <Card title="Multi-language messaging" icon="globe" href="/docs/en/multi-language-messaging">
    Send localized messages to users in their preferred language.
  </Card>

  <Card title="Identity Verification" icon="shield-check" href="/docs/en/identity-verification">
    Secure your SDK integration with server-side identity verification.
  </Card>

  <Card title="Custom Outcomes" icon="chart-line" href="/docs/en/custom-outcomes">
    Track custom conversion events tied to your messages.
  </Card>
</Columns>

### Web SDK setup & reference

<Columns>
  <Card title="Web push setup" icon="gear" href="/docs/en/web-push-setup">
    Enable all key web push features for your integration.
  </Card>

  <Card title="Web SDK reference" icon="code" href="/docs/en/web-sdk-reference">
    Full details on available methods and configuration options.
  </Card>
</Columns>

<Check>Congratulations! You've successfully completed the Web SDK setup guide.</Check>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# iOS: App Clip Support
Source: https://documentation.onesignal.com/docs/en/app-clip-support

Learn how to enable and configure OneSignal push notifications in iOS App Clips. Covers setup steps, limitations, and support for advanced experiences like Target-Content-ID.

## OneSignal support for App Clips

OneSignal supports sending push notifications to iOS App Clips. Since App Clips have a separate bundle identifier, they require their own push configuration. Follow the steps below to properly configure your App Clip with OneSignal and understand current limitations.

***

## Setup

### 1. Create a new app for your App Clip

You must create a separate app in the OneSignal Dashboard for your App Clip. This is because:

* App Clips use a different bundle identifier from the main app.
* Apple requires a distinct APNs certificate or Key for each unique bundle ID.

<Info>
  Make sure your App Clip bundle ID has its own APNs authentication configured
  in Apple Developer Console and linked in OneSignal.
</Info>

### 2. Set up OneSignal in your App Clip

Follow the standard OneSignal [iOS SDK setup guide](./ios-sdk-setup), but skip the Notification Service Extension step:

* ✅ Do: Add the OneSignal SDK to your App Clip target.
* ❌ Skip: Notification Service Extension — App Clips do not support this capability.

### 3. Enable ephemeral push permission

Add the following to your App Clip’s `Info.plist` to automatically enable 8-hour push notification permissions when the App Clip is opened:

```xml theme={null}
<key>NSAppClip</key>
<dict>
  <key>NSAppClipRequestEphemeralUserNotification</key>
  <true/>
</dict>
```

<Frame>
  <img />
</Frame>

This ephemeral permission expires after 8 hours unless the user disables it earlier.

You can also request indefinite push permission upon launch, similar to full apps.

Refer to [Apple’s documentation](https://developer.apple.com/documentation/appclip/enabling-notifications-in-app-clips) for full guidance.

### 4. Support advanced App Clip experiences

To target specific App Clip experiences with notifications:

1. In the OneSignal Dashboard, open **Settings > iOS platform configuration**.
2. Add a value to the **Target-Content-ID** field. This should be the experience URL you configured in App Store Connect.

<Frame>
  <img />
</Frame>

Learn more in Apple’s guide to [Creating an App Clip](https://developer.apple.com/documentation/app_clips/creating_an_app_clip), which covers Associated Domains and Target-Content-ID usage.

***

## App Clip limitations

Due to iOS platform restrictions, the following limitations apply to App Clips:

* Ephemeral permission duration: Only lasts 8 hours. To send notifications beyond this, request full push permission.
* No Notification Service Extension support:
  * ❌ No rich media (images, videos, etc.)
  * ❌ No custom action buttons (only predefined categories allowed)
* Location access is limited:
  * App Clips cannot request Always location access.
  * They can request When In Use, which expires at 4:00 a.m. the next day.

***


# Target outdated app versions to encourage app updates
Source: https://documentation.onesignal.com/docs/en/app-version-update

Use in-app messages to detect outdated app versions and prompt users to update, with platform-specific segments for iOS and Android.

Use in-app messages to notify users on older app versions that an update is available and prompt them to install it. This tutorial walks through creating platform-specific segments and messages for iOS and Android.

## Requirements

* OneSignal SDK v5 or later

## Setup

**Example scenario**: The latest version of our app is `1.0.1`. We want to target users on version `1.0.0` and older with an in-app message prompting them to update.

### 1. Get your latest app version

OneSignal detects `App Version` based on the following:

**iOS**: The `Version` found in Xcode **your main app Target > General > Identity**

<Frame>
  <img alt="Xcode project settings showing the Version field under Identity" />
</Frame>

**Android**: The `versionCode` found in your app `build.gradle` file

<Frame>
  <img alt="Android build.gradle file showing the versionCode field" />
</Frame>

<Note>
  If you don't have access to Xcode and/or Android Studio, ask your developer for these values.
</Note>

<Warning>
  iOS and Android use different version formats, and the store links differ by platform. Create separate segments and in-app messages for each.
</Warning>

### 2. Set up the segments

You will need to create two segments, one for iOS and one for Android.

**iOS**:

* Segment Name: `iOS App version less than 1.0.1`
* Filters: `App Version` is `less than` `1.0.1` AND `Device Type` is `iOS`.

<Frame>
  <img alt="OneSignal segment with App Version less than 1.0.1 and Device Type is iOS filters" />
</Frame>

**Android**:

* Segment Name: `Android App version less than 10001`
* Filters: `App Version` is `less than` `10001` AND `Device Type` is `Android`.

<Frame>
  <img alt="OneSignal segment with App Version less than 10001 and Device Type is Android filters" />
</Frame>

### 3. Set up the in-app messages

Navigate to **Messages > In-App > New Message > New In-App**.

Start from the pre-built design **New Feature Announcement** or create your own from scratch.

<Frame>
  <img alt="OneSignal in-app message template selection showing the New Feature Announcement option" />
</Frame>

Name the message something to reflect this is for iOS users.

#### Add your audience

Select the particular segment **iOS App version less than 1.0.1**.

#### Update the message

Update the message content as needed. To navigate the user to your app store listing, add a [URL click action](./iam-click-actions#url) to a button or other element.

<Frame>
  <img alt="OneSignal in-app message editor showing a URL click action configured on a button" />
</Frame>

Enter the store link as the URL:

* **iOS**: `https://apps.apple.com/app/idYOUR_APP_STORE_ID` — see [Requesting App Store Reviews](https://developer.apple.com/documentation/storekit/requesting_app_store_reviews)
* **Android**: `https://play.google.com/store/apps/details?id=YOUR_PACKAGE_NAME` — see [Linking to Google Play](https://developer.android.com/distribute/marketing-tools/linking-to-google-play.html)

### 4. Triggers

We recommend using the **On app open** trigger to ensure the message is shown when the user opens the app.

### 5. Schedule and frequency

If you scheduled the app update to be some time in the future, you can schedule the message to start showing at that time.

Depending on how aggressive you want to be with your update prompts, you can set the "How often do you want to show this message?" frequency to:

* **Every time trigger conditions are satisfied** - which means every time they open the app in this example.
* **Multiple times** - set the total number of times to show the message and what delay in between. For example, 100 times with a gap of 3 days in between. Will show the message every 3 days for up to 100 times.

### 6. Save as draft and duplicate for Android

Click the **Save as Draft** button to save the message.

In the **In-App Messages** page, click **Options > Duplicate** next to the message you just saved.

Update the following for your Android users:

* The IAM name to reflect this is for Android users
* Set the Segment to **Android App version less than 10001**
* Update the URL to the Android store link
* Add any additional changes to the message to make it unique for Android users

Click **Save as Draft** to save the message.

***

## Testing

Before publishing your messages, we suggest testing them with the following steps:

<Steps>
  <Step title="Find your test device and set as a test user">
    * Find your test device and set it as a [test user](./test-users).
    * Make sure the test device is on the lower version of your app.
  </Step>

  <Step title="Update the Segment to include Test Users">
    * Open the in-app message you want to test.
    * Click the Segment and add an **And** filter for **Test Users**.
      * This will ensure the message only shows for your test devices
    * For example, if your test device is on iOS, the segment will look like this:
      <Frame>
        <img alt="OneSignal segment with App Version, Device Type, and Test Users filters" />
      </Frame>
    * Click **Update Segment** to save the changes.
  </Step>

  <Step title="Publish the message">
    * Click **Update Message** to update the in-app message.
    * Click **Options > Resume** next to the message to set it live.
  </Step>

  <Step title="Verify the message is shown">
    * Close the app on the test device.
    * Wait 1 minute.
    * Open the app on your test device.
    * You should see the message if:
      * The device is a test user
      * The device is on the lower version of your app.
      * The segment is set to **Test Users**.
  </Step>
</Steps>

***

## Go live checklist

When you are ready to go live:

* Update the Segments to remove the `Test Users` filter.
* Check the Schedule to make sure it is set to the correct date and time.
* Click **Update Message** to update the in-app message.

<Check>
  You're done! Any users that open your app on an older version will get notified of your App Update.

  Return to the in-app message after some time to check progress. You can also get in-app message analytics with [Event Streams](./event-streams) or 3rd party [Integrations](./integrations).
</Check>

***

## FAQ

### Does OneSignal detect app version automatically?

Yes. The OneSignal SDK reports the app version to OneSignal automatically. On iOS this is the `Version` field in Xcode, and on Android it is the `versionCode` in your `build.gradle` file.

### Why do I need separate messages for iOS and Android?

iOS and Android use different version formats (e.g., `1.0.1` vs `10001`), and the store links for each platform are different. Separate segments and messages ensure the correct version filter and store link are used for each platform.

### Can I use this with Journeys instead of in-app triggers?

Yes. You can create a Journey that targets the same version-based segments and sends an in-app message as a step. This gives you additional control over timing and follow-up actions.

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

<Columns>
  <Card title="In-app click actions" icon="hand-pointer" href="./iam-click-actions">
    Configure URL, permission prompt, tag, outcome, and custom click actions on in-app message elements.
  </Card>

  <Card title="Segments" icon="users" href="./segmentation">
    Create segments based on user properties, behavior, and device attributes.
  </Card>
</Columns>


# Huawei authorization
Source: https://documentation.onesignal.com/docs/en/authorize-onesignal-to-send-huawei-push

Step-by-step guide to connect your Huawei app to OneSignal for push notifications, including PushKit setup, API key configuration, and Huawei's optional message self-classification for apps with users in China.

## Requirements

To enable push notifications on Huawei Android devices using OneSignal, you'll need:

* A [Huawei Developer Account](https://developer.huawei.com/consumer/en/console)
* An Android mobile app registered in [Huawei's AppGallery Connect](https://developer.huawei.com/consumer/en/doc/distribution/app/agc-create_app)
* A [OneSignal Account](https://onesignal.com/)
* (Optional) [Huawei Self-Classification Rights](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835#section1653845862216) if targeting users in China and needing more precise message categorization via the `Huawei_category` API field

***

## Setup

### 1. Enable PushKit

See [Huawei's docs on Push Kit](https://developer.huawei.com/consumer/en/codelab/HMSPushKit/index.html#0).

### 2. Get your Huawei Push credentials

Open [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html) and select your app/project.

<Frame>
  <img />
</Frame>

Go to **In-App Purchases** under **All services > Earn**. Copy the following:

* **Package Name**
* **Client ID**
* **Client Secret**

<Frame>
  <img />
</Frame>

### 3. Add credentials to OneSignal

In the OneSignal dashboard, go to your app **Settings > Push & In-App > Huawei Android (HMS)**.

<Frame>
  <img />
</Frame>

Click **Activate** and paste your credentials:

* **Package Name**
* **Client ID** (into **App ID** field)
* **Client Secret** (into **App Secret** field)

Then click **Next**.

<Frame>
  <img />
</Frame>

### 4. (Optional) Apply for Huawei’s Self-Classification Rights

Huawei requires AppGallery apps sending notifications to **users in China** to categorize messages. They offer **automatic classification**, but **self-classification** gives more control and higher send limits for critical message types.

#### How to apply

1. Follow Huawei’s [Self-Classification application guide](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835#section1653845862216).
2. Once approved, use the `Huawei_category` field in the OneSignal API to classify your messages.

#### Supported `Huawei_category` values

| Category          | Description                        |
| ----------------- | ---------------------------------- |
| `IM`              | Instant messaging                  |
| `VOIP`            | Voice-over-IP services             |
| `SUBSCRIPTION`    | Subscribed content notifications   |
| `TRAVEL`          | Travel info (e.g., ticket updates) |
| `HEALTH`          | Health and wellness updates        |
| `WORK`            | Work-related reminders             |
| `ACCOUNT`         | Account activity alerts            |
| `EXPRESS`         | Logistics/delivery updates         |
| `FINANCE`         | Financial/banking alerts           |
| `DEVICE_REMINDER` | Device-level system reminders      |
| `MAIL`            | Email client messages              |
| `MARKETING`       | Marketing or promotional content   |

<Note>
  Default category is `MARKETING`, which is limited to 2–5 sends/day depending on [third-level classifications](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-restriction-description-0000001361648361#section199311418515).

  **Important:** [Classification violations](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/volation-classification-violation-penalty-criteria-0000001356540133) may lead to penalties or delivery restrictions.
</Note>

***

## Huawei badges

OneSignal supports setting app icon badge counts on Huawei devices via the API and dashboard. Use the `huawei_badge_class`, `huawei_badge_set_num`, and `huawei_badge_add_num` parameters when creating push notifications.

See [Badges](./badges#huawei-badges) for full details and examples.

***

<Check>
  You're now authorized to send Huawei push notifications using OneSignal!
  Next steps:

  * [Integrate the OneSignal SDK](./mobile-sdk-setup)
</Check>

***


# Track topic interest for smarter targeting
Source: https://documentation.onesignal.com/docs/en/auto-segment-users-by-page-visit

Tag users based on the pages they visit and the page they subscribe to push notifications from, then segment for targeted campaigns.

You can tag users in OneSignal based on the pages they interact with on your site or app, then segment those tags for targeted messaging. This page covers two distinct patterns — pick the one that matches your goal, or run both side by side.

## Choose your pattern

| Pattern                                                       | When the code runs                | What it sets                                      | Platforms         |
| ------------------------------------------------------------- | --------------------------------- | ------------------------------------------------- | ----------------- |
| [Tag by page topic](#tag-by-page-topic-every-visit)           | On every page or screen visit     | A `cat_<category>` opt-in Tag set to `"1"`        | Web, Android, iOS |
| [Tag at subscription](#tag-at-subscription-one-time-web-only) | Once, when a user opts in to push | An attribution tag (`subscription_page = gaming`) | Web only          |

**Tag by page topic** uses the [`cat_*` Tag convention](./permission-requests#categories) to build a category-interest profile from browsing behavior. The same `cat_<category>` Tags that a [Category Prompt](./permission-requests#categories) sets explicitly can be filled in automatically as readers browse — so a single segment like `cat_sports = "1"` matches both audiences.

**Tag at subscription** captures a single point-in-time signal at opt-in — useful for source-aware welcome messaging and drip campaigns where the page a user subscribed from predicts what they want to read next.

## Prerequisites

* OneSignal [Web SDK](./web-sdk-setup) and/or [Mobile SDK](./mobile-sdk-setup) installed and initialized.
* Familiarity with [Tags](./add-user-data-tags) and [Segments](./segmentation).

***

## Tag by page topic (every visit)

Tag users with the categories they engage with most so you can deliver more personalized messaging — boosting relevance, click-through, and satisfaction.

This pattern uses the `cat_<category>` Tag convention — the same Tag namespace populated by the [Category Prompt](./permission-requests#categories) and by [preference centers](./preference-center). Auto-tagging from page visits and explicit opt-ins from prompts coexist in the same Tags, so a single segment like `cat_sports = "1"` matches both audiences.

Example use cases:

* On a fashion site, a user is only interested in men's shoes — not women's dresses.
* On a news app, a user consistently visits finance and sports articles — but never entertainment or politics.

### 1. Define your category taxonomy

Start by identifying the content categories you want to track. These might be:

* Broad verticals like `sports`, `finance`, or `entertainment`
* Product types like `apparel`, `home`, or `beauty`
* Authors or brands

The category name becomes the suffix on the `cat_*` Tag — for example, the `sports` category produces a `cat_sports` Tag.

<Note>
  * Start with 3–8 categories to keep management simple.
  * Stay under 20 categories overall to avoid bloat.
  * Use lowercase, underscored category names so they match the Tag Key convention everywhere they appear (`cat_breaking_news`, not `cat_BreakingNews`).
</Note>

### 2. Add code to track category visits

Set `cat_<category> = "1"` whenever a reader views a page or screen in that category. The Tag is idempotent — repeated calls with the same value are a no-op — so you can call this on every page load.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const categories = ["sports", "entertainment"]; // One or many

  categories.forEach(category => {
    OneSignal.User.addTag(`cat_${category}`, "1");
  });
  ```

  ```kotlin Kotlin theme={null}
  val categories = listOf("sports", "entertainment") // One or many

  categories.forEach { category ->
      OneSignal.User.addTag("cat_$category", "1")
  }
  ```

  ```swift Swift theme={null}
  let categories = ["sports", "entertainment"] // One or many

  for category in categories {
      OneSignal.User.addTag(key: "cat_\(category)", value: "1")
  }
  ```
</CodeGroup>

<Warning>
  If you also use the [Category Prompt](./permission-requests#categories) to capture explicit opt-ins, respect the user's choice. A `cat_<category> = "0"` value means the reader explicitly opted out — overwriting it with `"1"` from browsing behavior breaks their preference. Gate your `addTag` call on the existing Tag value, or skip the auto-tag for users who have already seen the Category Prompt.
</Warning>

### 3. Segment and send personalized messages

Once Tags are applied, you can target users with:

* [Segments](./segmentation) to build rule-based groups.
* [API filters](/reference/create-message#filters) to dynamically include users in a single campaign.

Common segmentation patterns:

* **Any engagement** with a category: `cat_sports exists`. Matches both explicit opt-ins and auto-tagged readers, regardless of value.
* **Active interest** in a category: `cat_sports = "1"`. Includes the auto-tagged readers above the threshold and the prompt opt-ins.
* **Multi-category** targeting: `cat_sports = "1" OR cat_finance = "1"`.
* **Excluded categories**: `cat_politics != "1"` to suppress readers who opted out.

Example use cases:

* Send breaking news alerts to readers with `cat_breaking_news = "1"`.
* Promote a finance newsletter to readers with `cat_finance = "1"` who do not have `nl_morning_briefing = "1"`.
* Send Black Friday deals to shoppers with `cat_apparel = "1"`.

### Best practices

Do:

* Use the `cat_<category>` Tag Key convention consistently across the Category Prompt, preference centers, and this auto-tag pattern. A single Tag namespace makes segmentation predictable.
* Test your tag logic with `console.log()` (web) or your platform's logger before launching campaigns.
* Keep the category list in a central place (a config file or remote config) so you can adjust without touching every page.

Avoid:

* Long or overly specific tag keys (full article titles, long URLs).
* Exceeding OneSignal's [tag limits](https://onesignal.com/pricing).
* Tagging with personally identifiable information (PII).
* Overwriting an explicit `cat_<category> = "0"` opt-out with an auto-tagged `"1"`.

***

## Tag at subscription (one-time, web only)

Tag web push subscribers with contextual data — such as the page topic or URL path they subscribed from — to deliver targeted follow-up campaigns. This pattern detects the opt-in, applies tags, and feeds segments for drip-style messaging.

### 1. Tag users on opt-in

When a user subscribes to push notifications, use the [`PushSubscription` change listener](./web-sdk-reference#addeventlistener-push-subscription-changes) to detect the opt-in and apply tags with contextual data about the page they were viewing.

```javascript theme={null}
function pushSubscriptionChangeListener(event) {
  if (event.current.optedIn && !event.previous.optedIn) {
    // User just opted in — tag with subscription context
    var pathSegment = window.location.pathname.split('/')[1] || 'home';
    var pageTopic = document.querySelector('meta[name="article-topic"]')?.content || 'general';

    OneSignal.User.addTags({
      subscription_page: pathSegment,
      subscription_page_topic: pageTopic,
    });
  }
}

OneSignalDeferred.push(function(OneSignal) {
  OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
});
```

**How this works:**

* The `change` event fires whenever the user's push subscription state changes (opt-in, opt-out, token refresh).
* `event.current.optedIn` is `true` when the user has an active subscription. Checking `!event.previous.optedIn` ensures tags are only applied on the initial opt-in, not on every state change.
* `window.location.pathname.split('/')[1]` captures the first path segment as the subscription context. For example, if the URL is `https://example.com/gaming/article-123`, the `subscription_page` tag is set to `gaming`.
* `pageTopic` is extracted from a `<meta>` tag, falling back to `'general'`. Adjust this to match your site's metadata structure.

### 2. Segment users by tag

Once tags are applied, use [Segments](./segmentation) or [API filters](/reference/create-message#filters) to target users based on those tags. For example:

* Send a campaign to users where `subscription_page` is `gaming`.
* Create dynamic segments based on tag values and timing (for example, hours since first session).

### 3. Automate follow-up messaging

Build drip-style campaigns that trigger messages based on when the user subscribed and what content they subscribed under.

**Example: Drip campaign for gaming subscribers**

| Segment name | Filters                                                           | Description                              |
| ------------ | ----------------------------------------------------------------- | ---------------------------------------- |
| Gaming 1     | `subscription_page` = `gaming` AND First Session > 2h AND \< 24h  | Reach out 2–24 hours after subscription. |
| Gaming 2     | `subscription_page` = `gaming` AND First Session > 24h AND \< 48h | Follow up 1 day later.                   |
| Gaming 3     | `subscription_page` = `gaming` AND First Session > 72h AND \< 96h | Final check-in after 3 days.             |

<Info>
  Use upper time limits (`<`) to prevent users from lingering in segments once the messaging window has passed.
</Info>

### 4. Combine segments with message templates

Once segments are created:

* Build [Templates](./templates) for each stage in the campaign (intro, reminder, promo).
* Use [Journeys](./journeys-overview) to send these messages when users enter the appropriate segment.

Example message ideas:

* Invite to a gaming community or social group.
* Recommend trending articles related to their topic.
* Send an exclusive offer or discount code.

### Best practices

* Use meaningful tag names and values that reflect actual user intent.
* Extract tag values dynamically from page metadata when possible.
* Only tag on the initial opt-in — the listener above checks `!event.previous.optedIn` to avoid re-tagging on every state change.

<Warning>
  Do not include personally identifiable information (PII) such as names or email addresses in tag values. Avoid hardcoding tag values across your entire site — extract them dynamically from page context.
</Warning>

***

## FAQ

### When should I use one pattern versus the other?

Use **tag by page topic** to build a behavioral interest profile over time. The counter grows with every visit, so segments can be tuned by engagement depth (`gaming >= 5`). Use **tag at subscription** to capture a single point-in-time attribution at opt-in, useful for source-aware welcome messaging where you want to react to *where* the user subscribed before they have a long visit history. Both patterns can run side by side on the same site — they set different tags and answer different questions.

### Do tags persist if the user clears browser data?

No. Clearing browser data on web creates a new Subscription, and the per-topic counters stored in `localStorage` reset along with it. If the user re-subscribes (manually or via [auto-resubscribe](./web-push-setup#auto-resubscribe)), the `change` listener fires again and re-applies the subscription tag based on the current page, but the visit counters start fresh.

### Can I update tags after the initial subscription?

Yes. You can call `OneSignal.User.addTag()` or `OneSignal.User.addTags()` at any time to add or update tags. The subscription listener is useful for the initial context, but you can also tag users based on ongoing behavior.

### Should I use these patterns instead of message event filters?

They serve different purposes. Use the patterns on this page when you want to segment by **which pages a user visited or subscribed from** — that is, signal that originates on your site or app. Use [Message event filters](./segmentation#message-event-filters) when you want to segment by **which OneSignal messages a user has interacted with** (delivered, clicked, etc.). They are complementary, not redundant.

### Can I only tag readers who show repeated engagement, or use counter values for engagement depth?

Yes — both variants layer on top of the same `cat_*` namespace by tracking a per-category visit counter in `localStorage` (web), `SharedPreferences` (Android), or `UserDefaults` (iOS):

* **Threshold (binary).** Increment the local counter on every visit, but only call `OneSignal.User.addTag("cat_<category>", "1")` once the counter reaches your threshold (for example, `3` visits). The Tag stays binary and combines cleanly with the [Category Prompt](./permission-requests#categories) — only engaged readers get tagged.
* **Counter values.** Call `OneSignal.User.addTag("cat_<category>", visits.toString())` every visit. You can then segment with `cat_sports >= "5"` for engagement-depth targeting. The trade-off is that you can no longer combine these auto-tagged values with the binary `"0"` / `"1"` opt-in scheme used by the Category Prompt — pick one scheme per category and use it consistently.

### Does the subscription-source pattern work on mobile?

Not directly. The `PushSubscription.addEventListener("change", ...)` API is web-specific. On iOS and Android, you can achieve a similar attribution by calling `addTag` from inside your opt-in flow — for example, immediately after the user accepts a [permission prompt](./permission-requests), tag them with the screen or feature they were on.

***

## Related pages

<Columns>
  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Add custom properties to users for personalization and segmentation.
  </Card>

  <Card title="Segments" icon="users" href="./segmentation">
    Group users by properties, tags, and behavior for targeted messaging.
  </Card>

  <Card title="Web SDK reference" icon="code" href="./web-sdk-reference">
    Full reference for the OneSignal Web SDK including subscription listeners and tagging methods.
  </Card>

  <Card title="Mobile SDK reference" icon="mobile" href="./mobile-sdk-reference">
    Full reference for the OneSignal Mobile SDK including tagging methods.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build multi-step messaging workflows triggered by segment entry or custom events.
  </Card>
</Columns>


# Back-in-stock alerts
Source: https://documentation.onesignal.com/docs/en/back-in-stock-alerts

Send restock alerts via push, email, or SMS to users who opted in. Use SKU-keyed tags with the Create Message API or Custom Events with a Journey.

Back-in-stock alerts let you recapture lost sales when a product goes out of stock. A "Notify me when available" button on your product page lets users opt in, and OneSignal sends the restock alert the moment the item is available again. The same flow works for push, email, or SMS — you choose the channel when you create the message template.

This guide covers two approaches. Pick the one that matches how you store back-in-stock requests today:

* **Tag-based** — Use this when OneSignal is the only system that needs to know who opted in. Each user-SKU pair is recorded as a tag, and a single Create Message API call fans out the restock alert to everyone tagged for that SKU.
* **Custom Events with Journey** — Use this when you already store `(user, SKU)` records on your own backend. The opt-in fires a Custom Event that enters a single Journey; the Journey waits for a matching restock event and sends the alert. This trades a heavier customer-side build for native deduplication, no per-user tag limits, and Journey-level controls (expiration, frequency caps, channel sequencing).

## Choose your approach

|                       | Tag-based                                                       | Custom Events with Journey                                                          |
| --------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Where opt-ins live    | OneSignal (as user tags)                                        | Your backend                                                                        |
| Per-restock work      | One `POST /notifications` call with a tag filter                | Backend iterates `(user, SKU)` records and fires one Custom Event per opted-in user |
| Cleanup after send    | Required: segment → CSV export → blank → re-import              | None — user exits the Journey naturally after the message step                      |
| Per-user opt-in limit | Plan-dependent — heavy opt-in users can hit per-user tag limits | Not a concern                                                                       |
| Dedup across restocks | Manual via cleanup workflow                                     | Native — Wait Until + Event Matching ensures one send per `(user, SKU)` instance    |
| Multi-step nurture    | Requires another tool (no built-in delays, channel sequencing)  | Built into the Journey (delays, channel branches, control groups, A/B)              |
| Customer build cost   | Low (opt-in tag + one send call)                                | Higher (database + opt-in event + per-user fan-out)                                 |

The two approaches are independent — pick one and skip the other section.

<CardGroup>
  <Card title="Approach 1: Tag-based" icon="tags" href="#approach-1%3A-tag-based">
    Lower build cost. OneSignal is your system of record. One API call fans out the alert at restock time.
  </Card>

  <Card title="Approach 2: Custom Events with Journey" icon="bolt" href="#approach-2%3A-custom-events-with-journey">
    Higher build cost. Your backend stores opt-ins. Native dedup via Event Matching, no tag limits.
  </Card>
</CardGroup>

## Prerequisites

Before you start, make sure you have:

* Subscribers opted in to the channel you plan to use (push permission, email subscription, or SMS opt-in)
* Access to your app's codebase or backend to record opt-ins when a user taps "Notify me"
* A signal from your inventory or commerce system (such as a webhook or scheduled job) that fires when a SKU returns to stock
* For the Custom Events approach: a `(user, SKU)` table on your backend so you can fire one restock event per opted-in user

***

## Approach 1: Tag-based

This approach runs in three steps: tag the user at opt-in, fire one API call at restock to fan out the alert, then clean up the tags so users don't receive duplicate messages on the next restock.

Each user gets one tag per SKU they opt in to: `bis_requested_<SKU> = "1"`. When the SKU restocks, you call the Create Message API with a filter on that tag and OneSignal fans out the alert.

### Set up your tag structure

For this flow, each user gets one tag per SKU they opt in to. The tag key encodes the SKU; the value is a sentinel.

| Tag key               | Example value | What it does                                                                                                                                                                                   |
| --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bis_requested_<SKU>` | `"1"`         | Existence on a user signals that user has opted in for that SKU. The product name, image, and cart link are passed in `custom_data` at send time, so they don't need to be stored on the user. |

If a user opts in for two products, they have two independent tags:

```text theme={null}
bis_requested_SKU_1234 = "1"
bis_requested_SKU_5678 = "1"
```

<Warning>
  Per-user tag count is plan-dependent (for example, 20 tags per user on lower-tier plans). When a user reaches the limit, further `addTag` operations **fail silently**. Always remove the tag after the restock alert is sent so a heavy opt-in user doesn't get stuck. See [plan limits](https://onesignal.com/pricing) for your tier.
</Warning>

<Note>
  **Use the SKU verbatim from your backend.** Tag keys via the SDK and API accept spaces, uppercase letters, and most punctuation, so `bis_requested_SKU 123` works as a tag key just as well as `bis_requested_SKU_1234`. Tag keys are **case-sensitive**, so pull the SKU from a single source (such as your product database) and use the exact same value at opt-in and at send time, or your filter will miss users.
</Note>

### Tag the user when they tap "Notify me"

When a user taps your "Notify me when available" button, set `bis_requested_<SKU>` on that user. You can do this from your app via the OneSignal SDK, or from your backend via the REST API.

<Tabs>
  <Tab title="SDK (Recommended)">
    Call the OneSignal SDK from your app when the user taps the button. This is the most direct approach for mobile and web apps. The example below is JavaScript; the same `addTag` call exists across platforms.

    | Reference       | Description                                                                    |
    | --------------- | ------------------------------------------------------------------------------ |
    | `addTag` method | [Mobile SDK](./mobile-sdk-reference#tags), [Web SDK](./web-sdk-reference#tags) |

    ```javascript JavaScript theme={null}
    const sku = "SKU_1234"; // the SKU as it appears in your product database
    OneSignal.User.addTag(`bis_requested_${sku}`, "1");
    ```

    <Check>
      The tag is applied instantly. The user is now included in any audience filter that targets `bis_requested_SKU_1234`.
    </Check>
  </Tab>

  <Tab title="REST API">
    Use this approach when the opt-in is recorded on your backend, for example when a logged-in user taps "Notify me" on a server-rendered page.

    ```bash theme={null}
    curl -X PATCH \
      https://api.onesignal.com/apps/{app_id}/users/by/external_id/{external_id} \
      -H "Content-Type: application/json" \
      -H "Authorization: Key YOUR_REST_API_KEY" \
      -d '{
        "properties": {
          "tags": {
            "bis_requested_SKU_1234": "1"
          }
        }
      }'
    ```

    Replace `{app_id}` with your OneSignal App ID and `{external_id}` (the value after `/by/external_id/`) with the user's ID in your system. Keep the literal `external_id` in the path — it tells OneSignal which alias type you are using. Replace `YOUR_REST_API_KEY` with your REST API key from **Settings > Keys & IDs**.
  </Tab>
</Tabs>

### Create a message template

A template lets you define the message content once and reuse it across every restock send. You create it in the dashboard and reference it by ID in your API calls.

1. In your OneSignal dashboard, go to **Templates** and click **New Template**.

2. Select the template type for the channel you want to send on — **Push Notification**, **Email**, or **SMS**.

3. Fill in the fields. The product name, image, and cart link are pulled from `custom_data` you pass at send time:

   | Field          | Value                                                                        |
   | -------------- | ---------------------------------------------------------------------------- |
   | **Title**      | `{{message.custom_data.product_name}} is back in stock!`                     |
   | **Message**    | `{{message.custom_data.product_name}} is back! Grab it before it sells out.` |
   | **Image**      | `{{message.custom_data.image_url}}`                                          |
   | **Launch URL** | `{{message.custom_data.cart_url}}`                                           |

4. Click **Save Template** and copy the **Template ID**. You will use it in the next step.

<Note>
  The same template handles every SKU because the product details come from `custom_data` at send time, not from the user's tags. You don't need a separate template per product.
</Note>

<Tip>
  **Email and SMS variations.** For email, use the same `custom_data` Liquid in the subject line and HTML body; the image and launch URL fields don't apply. For SMS, keep the body short and put the cart link inline (for example, `{{message.custom_data.product_name}} is back: {{message.custom_data.cart_url}}`).
</Tip>

### Send the restock alert

When your inventory system detects that a SKU is back in stock, send the message to all users tagged with `bis_requested_<SKU>`.

<Tabs>
  <Tab title="API (Recommended)">
    Trigger the following [Create message](/reference/create-message) call from your backend when a SKU is restocked. OneSignal targets only users with the matching tag and personalizes the message using the `custom_data` you provide.

    ```bash theme={null}
    curl -X POST \
      https://api.onesignal.com/notifications \
      -H "Content-Type: application/json" \
      -H "Authorization: Key YOUR_REST_API_KEY" \
      -d '{
        "app_id": "YOUR_APP_ID",
        "filters": [
          { "field": "tag", "key": "bis_requested_SKU_1234", "relation": "exists" }
        ],
        "target_channel": "push",
        "template_id": "YOUR_TEMPLATE_ID",
        "custom_data": {
          "product_name": "Pink Clogs",
          "image_url": "https://yourstore.com/images/pink-clogs.jpg",
          "cart_url": "https://yourstore.com/cart/SKU_1234"
        }
      }'
    ```

    Replace `YOUR_APP_ID` with your OneSignal App ID, `YOUR_TEMPLATE_ID` with the Template ID you copied in the previous step, and `YOUR_REST_API_KEY` with your REST API key from **Settings > Keys & IDs**. Set `target_channel` to `email` or `sms` to send on those channels instead — the `template_id` must reference a template of the matching type.

    <Check>
      When the call succeeds, OneSignal delivers the message to every user tagged with `bis_requested_SKU_1234`. The product name, image, and cart link are pulled from `custom_data`, so the same template renders correctly for any SKU.
    </Check>
  </Tab>

  <Tab title="Dashboard">
    Use this approach for one-off or low-volume restocks where you want to send manually from the dashboard.

    1. Go to **Audience > Segments** and click **New Segment**.
    2. Add a filter: **User Tag** → `bis_requested_SKU_1234` **exists**.
    3. Save the segment (e.g. name it `BIS - SKU_1234`).
    4. Go to **Messages** and click **New Push**, **New Email**, or **New SMS** — pick the channel that matches your template — and select the segment you created.
    5. Select your restock template under **Templates**.
    6. Add the product name, image URL, and cart URL to **Additional Data** so the template's `custom_data` Liquid renders correctly.
    7. Review and click **Send**.

    <Warning>
      The dashboard approach requires creating a new segment for every SKU you want to notify about. For multiple SKUs or automated restocks, use the API instead.
    </Warning>
  </Tab>
</Tabs>

### Clean up after sending

After a successful send, remove `bis_requested_<SKU>` from the users who received the alert so they don't get the same message twice on the next restock. Use OneSignal's [Bulk tag updates](./import#bulk-tag-updates) workflow — segment, export, blank, re-import:

<Steps>
  <Step title="Create a segment of opted-in users">
    Create a segment that filters users where `bis_requested_<SKU>` exists. You can do this in **Audience > Segments** in the dashboard, or via the [Create segments](/reference/create-segments) API.

    For SKU\_1234, the segment is one filter: **User Tag** → `bis_requested_SKU_1234` **exists**. Name it something predictable like `BIS - SKU_1234` so you can find it for cleanup.
  </Step>

  <Step title="Export the segment to CSV">
    Go to **Audience > Subscriptions** in the dashboard, filter by the segment, enable the **External ID**, **Subscription ID**, and **Tags** columns, and click **Export**. Or call the [CSV export](/reference/csv-export) API with `segment_name` set to the segment from the previous step.
  </Step>

  <Step title="Blank the tag value in the CSV">
    Open the exported CSV and clear the value for `bis_requested_SKU_1234` on every row. Leave the identifier column (External ID or Subscription ID) and the other tag values intact.
  </Step>

  <Step title="Re-import with delete enabled">
    Upload the edited CSV in **Audience > Import**. On the Review screen, enable **Delete tags with blank values**. OneSignal removes `bis_requested_SKU_1234` from every user in the segment.
  </Step>
</Steps>

<Tip>
  For the full reference — including a worked example with JSON-formatted tag rows — see [Bulk tag updates](./import#bulk-tag-updates).
</Tip>

***

## Approach 2: Custom Events with Journey

This approach runs in three steps: fire a Custom Event at opt-in to enter the Journey, hold the user at a Wait Until step until a matching restock event arrives for that SKU, then send the alert automatically.

Each opt-in fires a `bis_requested` Custom Event that enters a Journey. The Journey sends an immediate acknowledgment, then holds the user at a Wait Until step until your backend fires a matching `bis_item_restocked` event for that SKU. [Event Matching](./journeys-actions#event-matching) on the Wait Until step ensures each Journey instance is paired to the right SKU, so a single Journey handles every product in your catalog.

This approach assumes you already store `(user, SKU)` records on your own backend so you can fan out the restock event when stock returns.

### Send the opt-in event

When the user taps "Notify me when available," fire a `bis_requested` Custom Event with the SKU and item name as properties. **Fire one event per SKU.** If a user opts in to three SKUs, send three separate events — each one creates an independent Journey instance for that user.

<Tabs>
  <Tab title="SDK (Recommended)">
    Call the OneSignal SDK from your app when the user taps the button. The example below is JavaScript; the same `trackEvent` call exists across platforms.

    | Reference           | Description                                                                                      |
    | ------------------- | ------------------------------------------------------------------------------------------------ |
    | `trackEvent` method | [Mobile SDK](./mobile-sdk-reference#custom-events), [Web SDK](./web-sdk-reference#custom-events) |

    ```javascript JavaScript theme={null}
    const sku = "pink_clogs";
    const itemName = "Pink Clogs";
    OneSignal.User.trackEvent("bis_requested", {
      sku: sku,
      item_name: itemName,
    });
    ```

    <Check>
      The event enters the user into the Journey instantly. If they opt in to another SKU, fire another `bis_requested` event with the new SKU — they will run two parallel Journey instances.
    </Check>
  </Tab>

  <Tab title="REST API">
    Use this approach when the opt-in is recorded on your backend, for example when a logged-in user taps "Notify me" on a server-rendered page. Fire one event per SKU.

    ```bash theme={null}
    curl -X POST \
      https://api.onesignal.com/apps/{app_id}/custom_events \
      -H "Content-Type: application/json" \
      -H "Authorization: Key YOUR_REST_API_KEY" \
      -d '{
        "events": [
          {
            "external_id": "user_123",
            "name": "bis_requested",
            "properties": {
              "sku": "pink_clogs",
              "item_name": "Pink Clogs"
            }
          }
        ]
      }'
    ```

    See [Create custom events](/reference/create-custom-events) for the full schema, batching, and `idempotency_key` support.
  </Tab>
</Tabs>

<Note>
  You can also fire `bis_requested` from a third-party platform via [Custom event sources](./integrations#custom-event-sources) (Segment, Amplitude, Mixpanel, BigQuery, and others). The Journey works the same regardless of source.
</Note>

### Build the Journey

Create one Journey that handles every SKU. Wait Until's Event Matching feature pairs each Journey instance to the correct restock event by `sku`.

<Steps>
  <Step title="Set the entry rule">
    In **Messages > Journeys**, create a new Journey. Set the entry rule to **Custom Event** and select `bis_requested`.

    See [Custom events entry rules](./journeys-settings#custom-events) for full details on Custom Event entry.
  </Step>

  <Step title="Send an acknowledgment message">
    Add a message step right after entry to confirm the opt-in. Pick the channel that matches your alert (push, email, or SMS), create or select a template, and use Liquid to personalize with the entry event's properties.

    Example message body:

    ```liquid theme={null}
    Thanks — we'll let you know when {{ journey.first_event.properties.item_name }} is back in stock.
    ```

    See [Personalize with Custom Events](./personalization-custom-event) for the full Liquid reference for `journey.first_event`.
  </Step>

  <Step title="Add a Wait Until step with Event Matching">
    Add a **Wait Until** action and set the condition to a custom event named `bis_item_restocked`. Then enable **Event Matching** to pair the Journey instance to the right SKU:

    * **Trigger Event Property**: `sku` — the property on the entry `bis_requested` event
    * **Wait Event Property**: `sku` — the property on the `bis_item_restocked` event

    Because both properties are `sku`, only a `bis_item_restocked` event whose `sku` value matches the user's original opt-in advances them through the step. See [Event Matching](./journeys-actions#event-matching) for the canonical reference.

    Set an **expiration branch** so dormant instances don't accumulate forever. A reasonable default is six months, with **exit user** as the expiration action — tune this to your restock cadence (shorter for fast-fashion, longer for evergreen catalog items).
  </Step>

  <Step title="Send the restock message">
    Add a message step on the main branch of the Wait Until (the path users take when the event fires before expiration). Pick your channel and use Liquid to render the item name from the entry event:

    ```liquid theme={null}
    {{ journey.first_event.properties.item_name }} is back in stock! Tap to buy now.
    ```

    If you need fresh values from the restock event itself (for example, an updated price), reference them with `{{ journey.last_event.properties.<key> }}` — `journey.last_event` resolves to the most recently stored event, which is the `bis_item_restocked` event after Wait Until advances.
  </Step>

  <Step title="Exit the user">
    After the message step, the Journey ends and the instance exits naturally. No tag cleanup is needed — each `(user, SKU)` instance only sends once.

    If the user opts in to the same SKU again later, your backend should fire a new `bis_requested` event, which creates a fresh Journey instance.
  </Step>
</Steps>

### Trigger the restock event

When your inventory system detects that a SKU is back in stock, iterate the `(user, SKU)` records in your database and fire `bis_item_restocked` for each opted-in user. Each event must carry the `sku` so Event Matching pairs it to the correct Journey instance.

```bash theme={null}
curl -X POST \
  https://api.onesignal.com/apps/{app_id}/custom_events \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_REST_API_KEY" \
  -d '{
    "events": [
      {
        "external_id": "user_123",
        "name": "bis_item_restocked",
        "properties": {
          "sku": "pink_clogs",
          "item_name": "Pink Clogs"
        }
      },
      {
        "external_id": "user_456",
        "name": "bis_item_restocked",
        "properties": {
          "sku": "pink_clogs",
          "item_name": "Pink Clogs"
        }
      }
    ]
  }'
```

You can batch many users into a single API call. Include `idempotency_key` on each event if you implement retries — see [Create custom events](/reference/create-custom-events) for the full schema.

<Check>
  When the events are processed, OneSignal advances the matching Journey instances through the Wait Until step and sends the restock message to each user. Instances that don't match the `sku` are unaffected.
</Check>

<Warning>
  Custom Events require an `external_id` (or `onesignal_id`) per event. There is no broadcast variant — your backend must enumerate the opted-in users for the SKU and fire one event per user. This is why the approach assumes you already store `(user, SKU)` records.
</Warning>

***

## FAQ

### Which approach should I use?

If OneSignal is your only system of record for back-in-stock requests, use the **tag-based approach** — it's the lower-build option and lets a single API call fan out the alert. If you already store `(user, SKU)` records on your backend (for analytics, abandoned-cart, or other reasons), use **Custom Events with Journey** — you avoid per-user tag limits, get native dedup via Event Matching, and inherit the rest of Journey's features (delays, channel branches, control groups). See [Choose your approach](#choose-your-approach) for the full comparison.

### Does OneSignal handle message throttling or frequency caps?

No. Any throttling — for example, frequency caps, batching, or how many restock alerts you send in a period — must be handled on your side (your app or backend). OneSignal does not apply those rules for you.

### Does OneSignal limit how many users can opt in to a back-in-stock alert?

No. OneSignal does not cap how many users can opt in for a SKU. When stock is limited, you should cap opt-ins yourself — for example, if a SKU only has 1,000 units, stop accepting new opt-ins (don't set the `bis_requested_<SKU>` tag or fire `bis_requested`) once 1,000 requests have been reached.

### How many SKUs can a single user opt in to?

For the **tag-based approach**, this depends on your plan's per-user tag limit. Once a user reaches the limit, further `addTag` calls fail silently. Plan to remove the tag after the restock alert is delivered so a heavy opt-in user is not blocked from new alerts. See [Tags](./add-user-data-tags) for limits and best practices.

For the **Custom Events approach**, there is no per-user opt-in limit — each opt-in is a separate Journey instance, not a tag.

***

## Next steps

<CardGroup>
  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Add custom properties to users for personalization and segmentation.
  </Card>

  <Card title="Custom events" icon="bolt" href="./custom-events">
    Track user actions to trigger Journeys, personalization, and power analytics.
  </Card>

  <Card title="Journey actions" icon="diagram-project" href="./journeys-actions">
    Reference for Wait Until, Event Matching, and other Journey actions.
  </Card>

  <Card title="Create message API" icon="paper-plane" href="/reference/create-message">
    Full schema for the Create Message endpoint, including filters and `target_channel`.
  </Card>

  <Card title="Message personalization" icon="user" href="./message-personalization">
    Use Liquid to personalize messages with tags and `custom_data`.
  </Card>

  <Card title="Personalize with Custom Events" icon="code" href="./personalization-custom-event">
    Liquid syntax for `journey.first_event` and Custom Event properties in Journey messages.
  </Card>
</CardGroup>


# Booking confirmations
Source: https://documentation.onesignal.com/docs/en/booking-confirmations

Use custom events, Journeys, and Data Feeds to send booking confirmation or recovery emails based on real-time booking status.

## Overview

In this tutorial, you will set up a common booking workflow:

* Send a booking confirmation email after a user completes a booking.
* Send a recovery email if a user starts a booking but does not complete it in time.

By the end, you will have:

* Two Custom Events (`booking_started`, `booking_complete`)
* One Journey that branches on completion vs abandonment
* A booking Data Feed for confirmation details
* An optional coupon Data Feed for recovery incentives

This guide focuses on configuring OneSignal. Your booking system and backend can be implemented in any language or framework.

### Setup flow

1. Your app tracks a `booking_started` [custom event](./custom-events).
2. This enters the user into a Journey.
3. The Journey waits for a `booking_complete` event and if not received in time, it sends follow-up reminders.
4. If the booking completes, OneSignal calls a booking Data Feed at send time and sends a confirmation email with the latest booking details.
5. If the booking does not complete within the wait window, the Journey follows the expiration path and sends a recovery email.

***

## Setup

### Prerequisites

Before you begin, make sure you have:

* A OneSignal app with the [**Email**](./email-setup) channel enabled
* A backend endpoint that can return booking and/or coupon data as JSON
* A stable user identifier shared between your app, backend, and OneSignal's [External ID](./users#external-id)
* Access to [Custom Events](./custom-events)

### 1. Track booking events

Track the following Custom Events. These can be from your app (using our SDK) or from your backend (using our REST API).

**Event names:**

* `booking_started` — when the user begins the booking flow
* `booking_complete` — when the booking is successfully completed

<Tabs>
  <Tab title="App - Mobile and Web">
    Use the `trackEvent()` method on our [Mobile SDK](./mobile-sdk-reference) and/or [Web SDK](./web-sdk-reference) to send custom events directly from your app/website.

    ```js Example theme={null}
    OneSignal.User.trackEvent("booking_started");
    OneSignal.User.trackEvent("booking_complete");
    ```
  </Tab>

  <Tab title="Server Side">
    If you are tracking events from your backend, use the [Create Custom Events API](/reference/create-custom-events) to send events to OneSignal.

    ```bash theme={null}
    curl --request POST \
      --url https://api.onesignal.com/apps/{app_id}/custom_events \
      --header 'Authorization: Key YOUR_APP_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "events": [
          {
            "name": "booking_started",
            "external_id": "user123",
            "properties": {}
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

<Note>
  Use the same user identity when tracking events and when returning data from
  your backend. Mismatched IDs are the most common cause of missing
  personalization.
</Note>

### 2. Create Data Feed aliases

In OneSignal, go to **Settings > Data Feeds** and create the following aliases.

**Booking Data Feed:**
Use this feed to pull the latest booking details at send time.

* **Alias:** `booking_data`
* **Method:** GET
* **URL:**

```liquid Example endpoint theme={null}
https://your-domain.com/datafeed/booking?user_id={{subscription.external_id}}
```

Example response:

```json JSON theme={null}
{
  "first_name": "Sam",
  "last_booking": {
    "service_type": "Consultation",
    "booking_date": "January 22, 2026",
    "booking_time": "2:00 PM",
    "price": 45
  }
}
```

**Coupon Data Feed (optional):**

Use this optional feed if you want to include a coupon code in your recovery email.

* **Alias:** `coupon`
* **Method:** GET
* **URL:**

```liquid Example endpoint theme={null}
https://your-domain.com/datafeed/coupon?user_id={{subscription.external_id}}
```

Example response:

```json JSON theme={null}
{
  "first_name": "Sam",
  "code": "PROMO8F3K2",
  "discount_text": "10%",
  "expires_in_hours": 2,
  "deep_link": "https://your-domain.com/checkout?coupon=PROMO8F3K2"
}
```

<Warning>
  Secure your Data Feed endpoints. In production, send an API key in request headers (for example `x-api-key`) and configure that header in **Settings > Data Feeds** instead of embedding secrets in the URL.
</Warning>

### 3. Create email templates

#### Booking confirmation email:

**Subject:**

```text theme={null}
Your booking details
```

**Body:**

```liquid theme={null}
Hi {{ data_feed.booking_data.first_name | default: "there" }},

Thanks for your booking! Here are your appointment details:

Service: {{ data_feed.booking_data.last_booking.service_type }}
Date: {{ data_feed.booking_data.last_booking.booking_date }}
Time: {{ data_feed.booking_data.last_booking.booking_time }}
Price: ${{ data_feed.booking_data.last_booking.price }}

We look forward to seeing you!
```

#### Booking recovery email

**Subject:**

```text theme={null}
Complete your booking and save
```

**Body:**

<Tabs>
  <Tab title="Using a Coupon Data Feed">
    ```liquid theme={null}
    Hi {{ data_feed.coupon.first_name | default: "there" }},

    Finish your booking in the next {{ data_feed.coupon.expires_in_hours }} hours and save
    {{ data_feed.coupon.discount_text }} with this code:

    {{ data_feed.coupon.code }}

    Use it here:
    {{ data_feed.coupon.deep_link }}
    ```
  </Tab>

  <Tab title="Without a Coupon Data Feed">
    ```text theme={null}
    Hi there,

    You have not completed your booking yet!

    Complete it now to save on your next appointment.

    Use this link to complete your booking:
    [Insert deep link here]
    ```
  </Tab>
</Tabs>

<Note>
  Always include `default` filters in Liquid to prevent blank content if a Data
  Feed field is missing.
</Note>

### 4. Build the Journey

1. In OneSignal, go to **Messages > Journeys > Create Journey**

2. Set the **Entry Trigger** to:
   * **Custom Event:** `booking_started`

3. Add a **Wait Until** step:
   * **Condition:** Custom Event occurs
   * **Event name:** `booking_complete`
   * **Maximum wait time:** 10 minutes
   * Enable the expiration path

4. Configure the branches:
   * **Completed:** Send booking confirmation email
     * **Data Feed:** `booking_data`
   * **Expired:** Send recovery email
     * **Data Feed:** `coupon`

<Info>
  The expiration branch allows you to handle abandonment without additional
  logic in your app. See: - [Journey settings](./journeys-settings) - for
  details on Custom Event entry and exit rules - [Journeys
  actions](./journeys-actions) - for details on Wait Until steps and expiration
  branches
</Info>

### 5. Test and verify

#### Verify events

Trigger the custom events from your app or backend and confirm.

In OneSignal, go to **Analytics > Custom Events** and confirm you see:

* `booking_started` events appear for your External ID
* `booking_complete` events appear for your External ID

#### Verify Data Feeds

Manually call your Data Feed endpoints using a known user ID and confirm:

* A 200 response is returned
* All expected fields are present

#### Verify emails

Send test messages from the Journey editor and confirm:

* Booking emails contain real booking details
* Recovery emails contain a valid coupon
* No Liquid variables render empty

<Check>
  If personalization is missing, confirm that the user ID in the Data Feed
  request matches the user who triggered the Journey.
</Check>

## Example: Data Feed implementation

<Accordion title="Example Node.js Data Feed endpoints">
  This example shows a minimal Express implementation for booking confirmation and recovery Data Feeds. Your backend language, framework, and data source can differ as long as the JSON response shape matches your email templates.

  ### Booking Data Feed example

  ```js theme={null}
  import express from "express";

  const app = express();

  function dataFeedAuth(req, res, next) {
    if (req.headers["x-api-key"] !== process.env.DATAFEED_API_KEY) {
      return res.status(401).json({ error: "Unauthorized" });
    }
    next();
  }

  app.get("/datafeed/booking", dataFeedAuth, async (req, res) => {
    const { user_id } = req.query;

    if (!user_id) {
      return res.status(400).json({ error: "Missing user_id" });
    }

    const booking = await getLatestBookingForUser(user_id);

    if (!booking) {
      return res.status(404).json({ error: "No booking found" });
    }

    res.json({
      first_name: booking.first_name,
      last_booking: {
        service_type: booking.service_type,
        booking_date: booking.booking_date,
        booking_time: booking.booking_time,
        price: booking.price,
      },
    });
  });
  ```

  ### Coupon Data Feed example

  ```js theme={null}
  app.get("/datafeed/coupon", dataFeedAuth, async (req, res) => {
    const { user_id } = req.query;

    if (!user_id) {
      return res.status(400).json({ error: "Missing user_id" });
    }

    const coupon = await generateCouponForUser(user_id);

    res.json({
      first_name: coupon.first_name,
      code: coupon.code,
      discount_text: coupon.discount_text,
      expires_in_hours: coupon.expires_in_hours,
      deep_link: coupon.deep_link,
    });
  });
  ```

  ### Implementation guidelines

  * Keep responses fast (Data Feeds are called at send time)
  * Always return a predictable JSON structure
  * Use 404 when no data exists
  * Secure endpoints with an API key sent via request headers
</Accordion>

## Common issues

### Email shows empty values

* Data Feed returned 404
* Field names changed in the JSON response
* User identity mismatch

### Journey does not branch

* `booking_complete` event not tracked
* Event name mismatch (case-sensitive)
* Event occurs outside the wait window

### Data Feed returns 401 or 403

* Missing or invalid API key
* Header not configured in the Data Feed settings

## Next steps

* Add event properties (service type, price) for more advanced Journey conditions
* Add additional recovery steps such as push or SMS reminders
* Use Journey exit rules to prevent repeated recovery messages

***


# Capacitor SDK setup
Source: https://documentation.onesignal.com/docs/en/capacitor-sdk-setup

Set up the OneSignal Capacitor SDK to add push notifications to Capacitor apps for iOS and Android.

<SdkReleasesIframe />

## Overview

This guide explains how to integrate OneSignal push notifications into a Capacitor or Ionic Capacitor application. It covers installation, SDK initialization, and required platform configuration.

<Note>
  Not using Capacitor? See our [Ionic/Cordova SDK setup](./cordova-sdk-setup) guide.
</Note>

***

## Requirements

* Capacitor v7+
* Configured OneSignal app and platform

**iOS Requirements**

* macOS with Xcode 14+ (setup instructions use Xcode 16.2)
* Device with iOS 12+, iPadOS 12+, or Xcode simulator running iOS 16.2+
* CocoaPods 1.16.2+

**Android Requirements**

* Android 7.0+ device or emulator with Google Play Store (Services) installed

<Warning>
  App name should not contain spaces (e.g. "MyApp" instead of "My App") to avoid build issues.
</Warning>

### Configure your OneSignal app and platform

Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).

<Note>
  If your organization already has a OneSignal account, [ask to be invited](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Step-by-step setup instructions" icon="circle-chevron-down">
  <Steps>
    <Step title="Create or select your app">
      Create a new app by clicking **New App/Website**, or add a platform to an existing app in **Settings > Push & In-App**. Select the platform(s) you want to configure and click **Next: Configure Your Platform**.

      <Frame>
        <img alt="OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection" />
      </Frame>
    </Step>

    <Step title="Configure platform credentials">
      Enter the credentials for your platform:

      * **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
      * **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
      * **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
      * **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)

      Click **Save & Continue** after entering your credentials.
    </Step>

    <Step title="Save your App ID and install the SDK">
      Your **App ID** is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.

      <Frame>
        <img alt="OneSignal dashboard showing the App ID and team invite option after setup" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

***

## SDK setup

### 1. Add SDK

Add the `@onesignal/capacitor-plugin` package to your project.

```shell theme={null}
npm install @onesignal/capacitor-plugin
npx cap sync
```

### Optional: Disable the location module

Starting with `@onesignal/capacitor-plugin` 1.1.0, you can exclude OneSignal's native location module from iOS and Android builds when your app does not use `OneSignal.Location`.

Set `ONESIGNAL_DISABLE_LOCATION=true` before resolving or building native dependencies. The value is case-insensitive. You can also set it to `1`.

<CodeGroup>
  ```shell Sync theme={null}
  ONESIGNAL_DISABLE_LOCATION=true npx cap sync
  ```

  ```shell Run theme={null}
  ONESIGNAL_DISABLE_LOCATION=true npx cap run ios
  ONESIGNAL_DISABLE_LOCATION=true npx cap run android
  ```

  ```yaml GitHub Actions theme={null}
  env:
    ONESIGNAL_DISABLE_LOCATION: true
  ```
</CodeGroup>

With the location module disabled, calls to `OneSignal.Location` are ignored on Android. `OneSignal.Location.isShared()` resolves `false`.

#### Apply the change after native dependencies are cached

The environment variable is read when native dependencies are resolved. If you change the variable in an existing project, clear the relevant cache and re-resolve in a shell where the variable is exported.

<CodeGroup>
  ```shell Swift Package Manager theme={null}
  rm -rf ~/Library/Caches/org.swift.swiftpm ~/Library/Developer/Xcode/DerivedData/*
  ONESIGNAL_DISABLE_LOCATION=true npx cap sync ios
  ```

  ```shell CocoaPods theme={null}
  cd ios/App
  pod deintegrate
  rm -rf Pods Podfile.lock
  ONESIGNAL_DISABLE_LOCATION=true pod install
  ```

  ```shell Android Gradle theme={null}
  ONESIGNAL_DISABLE_LOCATION=true npx cap sync android
  cd android
  ONESIGNAL_DISABLE_LOCATION=true ./gradlew assembleDebug
  ```
</CodeGroup>

<Warning>
  When using Xcode or Android Studio, launch the IDE from a terminal where `ONESIGNAL_DISABLE_LOCATION` is exported. On CI, key DerivedData, Swift Package Manager, CocoaPods, and Gradle caches on the value of `ONESIGNAL_DISABLE_LOCATION`.
</Warning>

### 2. Initialize SDK

Initialize OneSignal when your app starts.

Replace `YOUR_APP_ID` with your OneSignal App ID found in your OneSignal dashboard **Settings > [Keys & IDs](./keys-and-ids)**.

<Note>
  If you don't have access to the OneSignal app, ask your [Team Members](./manage-team-members) to invite you.
</Note>

<CodeGroup>
  ```typescript Angular theme={null}
  import OneSignal, { LogLevel } from '@onesignal/capacitor-plugin';

  @Component({
    selector: 'app-root',
    templateUrl: 'app.component.html',
    styleUrls: ['app.component.scss'],
  })
  export class AppComponent {
    constructor() {
      // Enable verbose logging for debugging (remove in production)
      OneSignal.Debug.setLogLevel(LogLevel.Verbose);
      // Initialize with your OneSignal App ID
      OneSignal.initialize("YOUR_APP_ID");
      // Use this method to prompt for push notifications.
      // We recommend removing this method after testing and instead use In-App Messages to prompt for notification permission.
      OneSignal.Notifications.requestPermission(false).then((accepted: boolean) => {
        console.log("User accepted notifications: " + accepted);
      });
    }
  }
  ```

  ```typescript React theme={null}
  import { useEffect } from 'react';
  import OneSignal, { LogLevel } from '@onesignal/capacitor-plugin';

  const App: React.FC = () => {
    useEffect(() => {
      // Enable verbose logging for debugging (remove in production)
      OneSignal.Debug.setLogLevel(LogLevel.Verbose);
      // Initialize with your OneSignal App ID
      OneSignal.initialize("YOUR_APP_ID");
      // Use this method to prompt for push notifications.
      // We recommend removing this method after testing and instead use In-App Messages to prompt for notification permission.
      OneSignal.Notifications.requestPermission(false).then((accepted: boolean) => {
        console.log("User accepted notifications: " + accepted);
      });
    }, []);
  };
  ```

  ```typescript Vue theme={null}
  import { createApp } from 'vue';
  import App from './App.vue';
  import router from './router';
  import OneSignal, { LogLevel } from '@onesignal/capacitor-plugin';
  import { IonicVue } from '@ionic/vue';

  const app = createApp(App)
    .use(IonicVue)
    .use(router);

  router.isReady().then(() => {
    app.mount('#app');

    // Enable verbose logging for debugging (remove in production)
    OneSignal.Debug.setLogLevel(LogLevel.Verbose);
    // Initialize with your OneSignal App ID
    OneSignal.initialize("YOUR_APP_ID");
    // Use this method to prompt for push notifications.
    // We recommend removing this method after testing and instead use In-App Messages to prompt for notification permission.
    OneSignal.Notifications.requestPermission(false).then((accepted: boolean) => {
      console.log("User accepted notifications: " + accepted);
    });
  });
  ```
</CodeGroup>

Open your `capacitor.config.json` or `capacitor.config.ts` file and add the following code to allow OneSignal to handle iOS push notifications.

<Note>
  If subscription fails with an "APNS Delegate Never Fired" error, this configuration resolves the issue.
</Note>

<CodeGroup>
  ```json json theme={null}
  {
    "ios": {
      "handleApplicationNotifications": false
    }
  }
  ```

  ```typescript capacitor.config.ts theme={null}
  const config: CapacitorConfig = {
    // ... additional configuration

    ios: {
      // ... additional configuration
      handleApplicationNotifications: false
    }
  };
  ```
</CodeGroup>

***

## Android setup

Make sure your OneSignal app is configured for the Android platform using your [Firebase credentials](/docs/en/android-firebase-credentials).

Set up your [notification icons](/docs/en/notification-icons) to match your app’s branding. If this step is skipped, a default bell icon will display for your push notifications.

**Build for Android**

At this point, you should be able to build and run your app on a physical Android device or emulator without issues.

<Check>
  After confirming that your Android build works:

  * Continue with the [iOS setup](#ios-setup), if applicable.
  * Or jump ahead to [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## iOS setup

Make sure your OneSignal app is configured for the iOS platform using either the [p8 Token (Recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 Certificate](/docs/en/ios-p12-generate-certificates).

Follow these steps to add push notifications to your iOS app, including support for [Badges](/docs/en/badges), [Confirmed receipt](/docs/en/confirmed-delivery), and images.

### 1. Add Push Notifications capability to app target

The [Push Notifications capability](https://developer.apple.com/documentation/UserNotifications/registering-your-app-with-apns#Enable-the-push-notifications-capability) allows your app to register a push token and receive notifications.

1. Open your app’s `.xcworkspace` file in Xcode.
2. Select **your app target > Signing & Capabilities**
3. Click **+ Capability** and add **Push Notifications** capability

<Frame>
  <img />
</Frame>

### 2. Add Background Modes capability to app target

This enables your app to wake in the background when push notifications arrive.

1. Add [Background Modes](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app) capability
2. Enable **Remote notifications**

<Frame>
  <img />
</Frame>

### 3. Add app target to App Group

[App Groups](https://developer.apple.com/documentation/xcode/configuring-app-groups/#Create-App-Groups-for-all-other-platforms) allow data sharing between your app and the Notification Service Extension. Required for confirmed receipt and Badges.

<Tabs>
  <Tab title="If you do NOT have an App Group configured">
    1. Add **App Groups** capability
    2. In the App Groups capability click **+**
    3. Add a new container ID in format: `group.your_bundle_id.onesignal`

    * Keep **group.** and **.onesignal** prefix and suffix. Replace **`your_bundle_id`** with your app's bundle identifier.
    * For example, bundle identifier `com.onesignal.MyApp`, will have the container name `group.com.onesignal.MyApp.onesignal`.

    <Frame>
      <img />
    </Frame>

    <Warning> Your App Group name must exactly match your bundle ID’s spelling and capitalization across all targets. </Warning>
  </Tab>

  <Tab title="If you DO have an App Group">
    1. Open your **App Target** and **OneSignalNotificationServiceExtension Target's** `Info.plist`
    2. Add a new property to the `Info.plist` for both targets:

    * **Key:** `OneSignal_app_groups_key`
    * **Value:** Your existing App Group name (e.g., `group.your-custom-group-id`)

    ```xml XML theme={null}
    <key>OneSignal_app_groups_key</key>
    <string>group.your-custom-group-id</string>
    ```

    <Frame>
      <img />
    </Frame>

    <Warning>
      Make sure to update the `OneSignal_app_groups_key` in **both** the App Target **and** OneSignalNotificationServiceExtension Target's `Info.plist`!
    </Warning>
  </Tab>
</Tabs>

### 4. Add Notification Service Extension

The [Notification Service Extension (NSE)](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications) enables rich notifications and confirmed receipt analytics.

1. In Xcode: **File > New > Target...**
2. Select **Notification Service Extension**, then **Next**.
3. Set the product name to `OneSignalNotificationServiceExtension` and press **Finish**.
4. Press **Don't Activate** on the Activate scheme prompt.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

Set the OneSignalNotificationServiceExtension **Minimum Deployment Target** to match your main app (iOS 15+ recommended).

<Info> If you're using CocoaPods, set the deployment version in your Podfile as well. </Info>

<Frame>
  <img />
</Frame>

### 5. Add NSE target to app group

Use the same App Group ID you added in step 3.

1. Go to **OneSignalNotificationServiceExtension > Signing & Capabilities**
2. Add **App Groups**
3. Add the exact same group ID

<Warning>
  If you are using a custom App Group name and not `group.your_bundle_id.onesignal` then make sure to add your App Group ID to both the App Target and OneSignalNotificationServiceExtension Target's `Info.plist`! See [step 3](#3-add-app-target-to-app-group) for more information.
</Warning>

<Frame>
  <img />
</Frame>

### 6. Update NSE code

1. Navigate to the **OneSignalNotificationServiceExtension** folder
2. Replace the contents of the `NotificationService.swift` or `NotificationService.m` file with the following:

<Frame>
  <img />
</Frame>

<CodeGroup>
  ```swift Swift theme={null}
  import UserNotifications
  import OneSignalExtension

  class NotificationService: UNNotificationServiceExtension {
      var contentHandler: ((UNNotificationContent) -> Void)?
      var receivedRequest: UNNotificationRequest!
      var bestAttemptContent: UNMutableNotificationContent?

      // Note this extension only runs when `mutable_content` is set
      // Setting an attachment or action buttons automatically sets the property to true
      override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
          self.receivedRequest = request
          self.contentHandler = contentHandler
          self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

          if let bestAttemptContent = bestAttemptContent {
              // DEBUGGING: Uncomment the 2 lines below to check this extension is executing
  //            print("Running NotificationServiceExtension")
  //            bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

              OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
          }
      }

      override func serviceExtensionTimeWillExpire() {
          // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
          if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
              OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
              contentHandler(bestAttemptContent)
          }
      }
  }
  ```

  ```objectivec Objective-C theme={null}
  #import <OneSignalExtension/OneSignalExtension.h>
  #import "NotificationService.h"

  @interface NotificationService ()

  @property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
  @property (nonatomic, strong) UNNotificationRequest *receivedRequest;
  @property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

  @end

  @implementation NotificationService

  // Note, this extension only runs when mutable-content is set
  // Setting an attachment or action buttons automatically adds this
  - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
      self.receivedRequest = request;
      self.contentHandler = contentHandler;
      self.bestAttemptContent = [request.content mutableCopy];

      // DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is executing
  //     NSLog(@"Running NotificationServiceExtension");
  //     self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];

      [OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
                         withMutableNotificationContent:self.bestAttemptContent
                                     withContentHandler:self.contentHandler];
  }

  - (void)serviceExtensionTimeWillExpire {
      // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.

      [OneSignalExtension serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];

      self.contentHandler(self.bestAttemptContent);
  }

  @end
  ```
</CodeGroup>

You should see an error because the OneSignal package is not installed. This will be resolved in the next step.

<Frame>
  <img />
</Frame>

### 7. Add OneSignal to the NSE target

<Note>
  If your SDK uses Swift Package Manager (SPM) for iOS dependencies, you can skip this step. The OneSignal package is already resolved and available to all targets.
</Note>

Update your `ios/Podfile` to include:

<CodeGroup>
  ```ruby Podfile theme={null}
  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```

  ```ruby Example theme={null}
  target 'MyApp' do
    config = use_native_modules!

    use_react_native!(
      :path => config[:reactNativePath],
      # An absolute path to your application root.
      :app_path => "#{Pod::Config.instance.installation_root}/.."
    )

    post_install do |installer|
      # https://github.com/facebook/react-native/blob/main/packages/react-native/scripts/react_native_pods.rb#L197-L202
      react_native_post_install(
        installer,
        config[:reactNativePath],
        :mac_catalyst_enabled => false,
        # :ccache_enabled => true
      )
    end
  end

  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```
</CodeGroup>

Open your project in the terminal and run:

```shell shell  theme={null}
cd ios pod install cd .. 
```

#### Common pod install errors

You may run into the following errors, here is how you can resolve them.

<Accordion
  title="ArgumentError - \[Xcodeproj] Unable to find compatibility version string for
object version `70`."
>
  CocoaPods relies on the `xcodeproj` Ruby gem to read your Xcode project files. As of now, the latest `xcodeproj` release does not recognize object version 70, which was introduced by Xcode 16. So when CocoaPods tries to open your `.xcodeproj` file, it crashes with this error.

  1. Close Xcode.
  2. Navigate to your project's `ios/<your-app>.xcodeproj/project.pbxproj` file.
  3. Change this line: `objectVersion = 70;`
  4. Replace it with: `objectVersion = 55;`
  5. Save, close, and rerun `cd ios pod install cd ..`
</Accordion>

### Build for iOS

You should now be able to build and run your app on a real iOS device or iOS simulator (16.2+).

#### Common iOS build errors

<Accordion title="commandPhaseScript Execution exited with a non-zero code">
  1. Delete your Podfile.lock
  2. Delete your Pods folder
  3. Delete your .xcworkspace
  4. Pod install
  5. Cmd + Shift + K to Clean the build and then retry building

  If these steps do not resolve the error, build directly from the Xcode, then find the build error in the report navigator pictured below.

  <img />
</Accordion>

<Accordion title="Cycle Inside... building could produce unreliable results.">
  You may see this error when building with Xcode 15+, due to a default configuration change affecting cross platform systems.

  1. Open your `.xcworkspace` folder in Xcode and navigate to **your app target > Build Phases**.
  2. You should have a phase called **"Embed Foundation Extensions"** or **"Embed App Extensions"**.
  3. Drag and move this build phase to *above* **"Run Script"**.
  4. Build and run your app. The error should be resolved.

  <Frame>
    <img />
  </Frame>

  <Frame>
    <img />
  </Frame>
</Accordion>

<Accordion title="PBXGroup Error">
  <Info>
    RuntimeError - `PBXGroup` attempted to initialize an object with unknown ISA `PBXFileSystemSynchronizedRootGroup` from attributes: `{"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}`
  </Info>

  Fix:

  1. Find the folder listed under "path" in the error
  2. In Xcode project sidebar, right-click the folder
  3. Select **Convert to Group**

  <Frame>
    <img />
  </Frame>

  <br />

  <Frame>
    <img />
  </Frame>
</Accordion>

<Check>
  After confirming that your iOS build works, continue with [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications, subscription registration, and in-app messaging.

<Warning>
  If you are testing with an Android emulator, it should start with a cold boot.

  1. Go to **Device Manager** in Android Studio.
  2. Select your emulator device and click **Edit**.
  3. Go to **Additional Settings** or **More**.
  4. Set the **Boot option** to **Cold Boot**.
  5. Save changes and restart the emulator.
</Warning>

### Check mobile subscriptions

<Steps>
  <Step title="Launch your app on a test device.">
    The native push permission prompt should appear automatically if you added the `requestPermission` method during initialization.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    Before accepting the prompt, check the OneSignal dashboard:

    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status "Never Subscribed".

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Return to the app and tap Allow on the prompt." />

  <Step title="Refresh the OneSignal dashboard Subscription's page.">
    The subscription's status should now show **Subscribed**.

    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a [mobile subscription](/docs/en/subscriptions).
    Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a segment of test users.
    We can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

    ```curl theme={null}
    curl -X \
    POST --url 'https://api.onesignal.com/notifications' \
     --header 'content-type: application/json; charset=utf-8' \
     --header 'authorization: Key YOUR_APP_API_KEY' \
     --data \
     '{
      "app_id": "YOUR_APP_ID",
      "target_channel": "push",
      "name": "Testing basic setup",
      "headings": {
      	"en": "👋"
      },
      "contents": {
        "en": "Hello world!"
      },
      "included_segments": [
        "Test Users"
      ],
      "ios_attachments": {
        "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      },
      "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
    }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification with an image included:

    <Frame>
      <img />
    </Frame>

    <Info>Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Info>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats.

    You should see the **confirmed** stat, meaning the device received the push.
    <Check>You have successfully sent a notification via our API to a segment.</Check>

    <Warning>
      * No image received? Your [Notification Service Extension](#ios-setup) might be missing.
      * No confirmed receipt? Review the troubleshooting guide [here](/docs/en/confirmed-delivery#troubleshooting-confirmed-delivery).
      * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
    </Warning>
  </Step>
</Steps>

### Send an in-app message

[In-app messages](/docs/en/in-app-messages-setup) let you communicate with users while they are using your app.

<Steps>
  <Step title="Close or background your app on the device.">
    This is because users must meet the in-app audience criteria *before* a new session starts. In OneSignal, a new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds. For more details, see our guide on [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
  </Step>

  <Step title="Create an in-app message.">
    * In your OneSignal dashboard, navigate to **Messages > In-App > New In-App**.
    * Find and select the **Welcome** message.
    * Set your Audience as the **Test Users** segment we used previously.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Customize the message content if desired.">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Set Trigger to 'On app open'." />

  <Step title="Schedule frequency.">
    Under **Schedule > How often do you want to show this message?** select **Every time trigger conditions are satisfied**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Make message live.">
    Click **Make Message Live** so it is available to your Test Users each time they open the app.
  </Step>

  <Step title="Open the app and see the message.">
    After the in-app message is live, open your app. You should see it display:

    <Frame>
      <img />
    </Frame>

    <Warning>
      Not seeing the message?

      * Start a new session
        * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
        * For more, see [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
      * Still in the `Test Users` segment?
        * If you reinstalled or switched devices, re-add the device to [Test Users](#set-up-test-users) and confirm it's part of the Test Users segment.
      * Having issues?
        * Follow [Getting a Debug Log](/docs/en/capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
    </Warning>
  </Step>
</Steps>

<Check>
  You have successfully setup the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](/docs/en/subscriptions), setting [Test Users](/docs/en/find-set-test-subscriptions), and creating [Segments](/docs/en/segmentation).
  * Sending [Push](/docs/en/push) with images and [Confirmed receipt](/docs/en/confirmed-delivery) using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](/docs/en/in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

***

## User identification

Previously, we demonstrated how to create mobile [Subscriptions](/docs/en/subscriptions). Now we'll expand to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We'll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with our SDK's [`login` method](/docs/en/mobile-sdk-reference#login-external-id) each time they are identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with our SDK [`addTag` and `addTags` methods](/docs/en/mobile-sdk-reference#data-tags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img />
</Frame>

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

### Add email and/or SMS subscriptions

Earlier we saw how our SDK creates mobile subscriptions to send push and in-app messages. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/mobile-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/mobile-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/mobile-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/mobile-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

See our Privacy & security docs for more on:

* [Data collected by the SDK](/docs/en/data-collected-by-the-onesignal-sdk)
* [Handling personal data](/docs/en/handling-personal-data)

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](/docs/en/prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners for you to hook into. See our [SDK reference guide](/docs/en/mobile-sdk-reference) for more details.

### Push notification events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-push): Detect when a notification is tapped. Helpful for [Deep Linking](/docs/en/deep-linking).
* [`addForegroundLifecycleListener()`](/docs/en/mobile-sdk-reference#addforegroundlifecyclelistener-push): Control how notifications behave in foreground.

For full customization, see [Mobile Service Extensions](/docs/en/service-extensions).

### User state changes

* [`addObserver()` for user state](/docs/en/mobile-sdk-reference#addobserver-user-state): Detect when the External ID is set.
* [`addPermissionObserver()`](/docs/en/mobile-sdk-reference#addpermissionobserver-push): Track the user's specific interaction with the native push permission prompt.
* [`addObserver()` for push subscription](/docs/en/mobile-sdk-reference#addobserver-push-subscription-changes): Track when the push subscription status changes.

### In-app message events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Handle in-app click actions. Ideal for deep linking or tracking events.
* [`addLifecycleListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Track full lifecycle of in-app messages (shown, clicked, dismissed, etc.).

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

* [🔁 Migrating to OneSignal from another service](/docs/en/migrating-to-onesignal)
* [🌍 Location tracking](/docs/en/mobile-sdk-reference#location)
* [🔗 Deep Linking](/docs/en/deep-linking)
* [🔌 Integrations](/docs/en/integrations)
* [🧩 Mobile Service Extensions](/docs/en/service-extensions)
* [🛎️ Action buttons](/docs/en/action-buttons)
* [🌐 Multi-language messaging](/docs/en/multi-language-messaging)
* [🛡️ Identity Verification](/docs/en/identity-verification)
* [📊 Custom Outcomes](/docs/en/custom-outcomes)
* [📲 Live Activities](/docs/en/live-activities)

### Mobile SDK setup & reference

Make sure you've enabled all key features by reviewing the [Mobile push setup](/docs/en/mobile-push-setup) guide.

For full details on available methods and configuration options, visit the [Mobile SDK reference](/docs/en/mobile-sdk-reference).

<Check>Congratulations! You've successfully completed the Mobile SDK setup guide.</Check>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Getting a Debug Log
Source: https://documentation.onesignal.com/docs/en/capturing-a-debug-log

Learn how to capture detailed debug logs from your mobile app using the OneSignal SDK. This guide walks through enabling verbose logging, reproducing issues, and sharing logs for troubleshooting push notification issues across Android and iOS platforms.

<Frame>
  <iframe title="YouTube video player" />
</Frame>

Capturing a debug log is the most effective way to troubleshoot mobile SDK and push notification issues. This guide will help you generate debug logs for your iOS and Android app and share logs with our Support Team if needed.

## Requirements

To capture a debug log, make sure you have:

* A device that can reproduce the issue
* Access to the app's developer tools
* OneSignal Mobile SDK version **5.0.0 or higher**

<Warning>
  If you're using an earlier SDK version, refer to [Version 9.0
  docs](/v9.0/docs/capturing-a-debug-log) for instructions.
</Warning>

## Step-by-step instructions

### 1. Enable verbose logging

Add the `VERBOSE` log level call to your app **before** initializing the OneSignal SDK. This ensures detailed diagnostic information is captured for every OneSignal operation.

<CodeGroup>
  ```Java Java theme={null}
  // LogLevel: NONE | FATAL | ERROR | WARN | INFO | DEBUG | VERBOSE
  OneSignal.getDebug().setLogLevel(OneSignal.LOG_LEVEL.VERBOSE);
  ```

  ```Kotlin Kotlin theme={null}
  // LogLevel: .None | .Fatal | .Error | .Warn | .Info | .Debug | .Verbose
  OneSignal.Debug.logLevel = LogLevel.Verbose
  ```

  ```objectivec Objective-C theme={null}
  // LogLevel: ONE_S_LL_NONE | ONE_S_LL_FATAL | ONE_S_LL_ERROR | ONE_S_LL_WARN | ONE_S_LL_INFO | ONE_S_LL_DEBUG | ONE_S_LL_VERBOSE
  [OneSignal.Debug setLogLevel:ONE_S_LL_VERBOSE];
  ```

  ```Swift Swift theme={null}
  OneSignal.Debug.setLogLevel(.LL_VERBOSE)
  ```

  ```csharp C# theme={null}
  // LogLevel: None | Fatal | Error | Warn | Info | Debug | Verbose
  OneSignal.Debug.LogLevel = LogLevel.Verbose;
  ```

  ```javascript React Native theme={null}
  OneSignal.Debug.setLogLevel(6);
  ```

  ```Text Flutter theme={null}
  OneSignal.Debug.setLogLevel(OSLogLevel.verbose);
  ```

  ```javascript Cordova/Ionic theme={null}
  // 0 = None, 1 = Fatal, 2 = Errors, 3 = Warnings, 4 = Info, 5 = Debug, 6 = Verbose
  window.plugins.OneSignal.Debug.setLogLevel(6);
  ```
</CodeGroup>

<Note>
  Set the log level *before* calling `OneSignal.init` to ensure all SDK activity
  is logged.
</Note>

### 2. Reproduce the issue

With verbose logging enabled, reproduce the issue on a physical device or emulator connected to Android Studio or Xcode.

<Frame>
  <img />
</Frame>

### 3. Capture and Share the Logs

Once the issue is reproduced, review the logs to see if it helps diagnose the issue.

If you need assistance, copy-paste the entire log from start to end and send them to OneSignal Support as a `.txt` file.

Include all relevant reproduction steps, screenshots, and other details.

<Frame>
  <img />
</Frame>

#### Platform-specific instructions

<Tabs>
  <Tab title="Android Studio">
    ### Android Studio

    1. Open the Run tab in the bottom panel. (If not visible, go to **View > Tool Windows > Run**)
    2. Run the app on a connected device or emulator.
    3. Reproduce the issue.
    4. Select all log output (` Ctrl + A` or `Cmd + A`) and copy it.
    5. Paste it into a `.txt` file.
    6. Send the file to OneSignal Support with steps to reproduce.

    📎 [Sample Log (Google Drive)](https://drive.google.com/file/d/1XphR4u4CRtUO37X6VZzzeyLUhq5pRMYw/view?usp=sharing)

    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="Xcode">
    ### Xcode

    <Info>
      **Important:** Crashes must occur while the device is **not connected** to
      your Mac. Plug it in **after** reproducing the crash.
    </Info>

    1. Open **Window > Devices and Simulators** in Xcode.
    2. Select your device and click **Open Console**.
    3. Filter by **All Messages** in the dropdown.
    4. Reproduce the issue.
    5. Select all output (`Cmd + A`) and copy (`Cmd + C`).
    6. Paste into a `.txt` file.
    7. Send the file to OneSignal Support with steps to reproduce.

    <Frame>
      <img />
    </Frame>
  </Tab>
</Tabs>

#### Advanced use cases

<Accordion title="Offline Logging">
  If your app encounters issues while running in the background, or if you cannot attach a debugger, you can enable offline logging to capture logs directly on the device.

  To enable offline logging, add the following code before initializing the OneSignal SDK

  <CodeGroup>
    ```Swift AppDelegate theme={null}

    import Darwin
    import os.Log
    // ... rest of imports

    extension OSLog {
        private static var subsystem = Bundle.main.bundleIdentifier!
        static let test = OSLog(subsystem: subsystem, category: "Test")
    }

    class AppDelegate: UIResponder, UIApplicationDelegate  {

        func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {

            /* LOGGING REDIRECT */
            if true { // if no terminal is attached to stderr
                let documentsUrl = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
                let logfileUrl = documentsUrl.appendingPathComponent("out.log")
                logfileUrl.withUnsafeFileSystemRepresentation { path in
                    guard let path = path else {
                        return
                    }
                    print("redirect stderr and stderr to: \(String(cString: path))")
                    let file = fopen(path, "a")
                    assert(file != nil, String(cString: strerror(errno)))
                    let fd = fileno(file)
                    assert(fd >= 0, String(cString: strerror(errno)))
                    let result1 = dup2(fd, STDERR_FILENO)
                    assert(result1 >= 0, String(cString: strerror(errno)))
                    let result2 = dup2(fd, STDOUT_FILENO)
                    assert(result2 >= 0, String(cString: strerror(errno)))

                    os_log("* os_log: Test", log: OSLog.test, type: .debug)
                    print("* print: Test")
                    NSLog("* NSLog: Test")
                }
            }

            // ... OneSignal initialization and any existing code

            /* LOGGING CALL */
            os_log("os_log: Test", log: OSLog.test, type: .debug)
            print("print: Test")
            NSLog("NSLog: Test")

            return true
        }
    }

    ```
  </CodeGroup>

  <Steps>
    <Step>
      Run the app on the device with the new code added, ideally just before reproducing the issue to reduce the amount of logged output
    </Step>

    <Step>
      Plug the device into your computer and open Xcode.
    </Step>

    <Step>
      Navigate to "Window → Devices and Simulators" and click on the name of the app you added the logging to.
    </Step>

    <Step>
      Click the settings icon and select "Download Container".

      <Frame>
        <img alt="Download container" />
      </Frame>
    </Step>
  </Steps>

  You should now have access to the folder where you've chosen to download it, and inside of the /Documents folder, you'll see the "out.log" file containing the logs captured while offline.
</Accordion>

***


# Clearing cache and resetting push permissions
Source: https://documentation.onesignal.com/docs/en/clearing-cache-and-resetting-push-permissions

Learn how to reset browser push permissions, service workers, and site data across Chrome, Firefox, and Safari to ensure clean test environments and resolve web push notification issues.

Residual data from outdated or misconfigured notification settings can prevent push notifications from working properly—even when your current implementation is correct. Use the instructions below to fully reset your browser’s notification permissions, unregister service workers, and clear site data for a clean testing state.

<Tabs>
  <Tab title="Chrome desktop">
    1. Click the **View Site Information** (lock or info) icon next to the URL bar.
    2. Under **Notifications**, click **Reset permission**.
    3. Open [Chrome Developer Tools](https://developer.chrome.com/docs/devtools/open) (`F12` on PC or `fn + F12` on Mac).
    4. In the **Application tab > Storage**, click **Clear Site Data**.
    5. When prompted, click **Reload** to refresh the page.

    <Frame>
      <img />
    </Frame>

    If you have [Prompting](./permission-requests) configured, a new permission request should appear. **Do not subscribe just yet.**

    **Optional:**
    To manually unregister background workers:

    * Visit [chrome://serviceworker-internals](chrome://serviceworker-internals) in a new tab.
    * Find entries under “Scopes” containing your domain.
    * Click **Stop** and **Unregister**.

    <Info>If these buttons are disabled, ensure all tabs for your site are closed.</Info>

    <Frame>
      <img />
    </Frame>

    <Check>Open a *new* tab to your site and try it out!</Check>
  </Tab>

  <Tab title="Chrome Android">
    If you still see a push notification from your site:

    1. Tap the **gear icon > Site Settings**

    <Frame>
      <img />
    </Frame>

    2. Tap **Clear & Reset**

    <Frame>
      <img />
    </Frame>

    If no notification is visible:

    * Open Chrome, then the **3-dot menu > Settings**
    * Scroll to **Site Settings >Notifications**
    * Ensure it is set to *Ask before sending (recommended)*
    * Find your site in the list, tap it, then tap **Clear & Reset**

    <Check>Open a *new* tab to your site and try it out!</Check>
  </Tab>

  <Tab title="Firefox desktop">
    1. Click the **i** or **lock** icon next to your site’s URL.
    2. Under **Permissions**, next to **Receive Notifications**, click the **X** to remove permission.

    <Frame>
      <img />
    </Frame>

    3. In the same dialog, scroll to the bottom and click **Clear Cookies and Site Data...**

    <Frame>
      <img />
    </Frame>

    4. On the popup dialog, click **OK**

    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="Firefox Android">
    Refer to [Firefox's official guide](https://support.mozilla.org/en-US/kb/clear-your-browsing-history-and-other-personal-data#w_clear-specific-items-from-your-browser) to clear browsing data on Android.
  </Tab>

  <Tab title="Safari macOS">
    <Info>
      Apple does not support Web Push in Safari on Windows.
    </Info>

    To reset notification permissions and cache:

    1. From the menu bar, go to: **Safari > Settings > Websites > Notifications**
    2. Find your site and click **Remove**

    <Frame>
      <img alt="" />
    </Frame>

    3. Navigate to **Privacy > Manage Website Data...**

    <Frame>
      <img alt="" />
    </Frame>

    <br />

    4. Search for your domain, select it, and click **Remove** or **Remove All**

    <Frame>
      <img alt="" />
    </Frame>

    5. Click **Done**

    <Check>
      Return to your site and refresh. It should behave like a first-time visit.
    </Check>
  </Tab>
</Tabs>

***


# Cordova SDK setup
Source: https://documentation.onesignal.com/docs/en/cordova-sdk-setup

Set up the OneSignal Cordova SDK to add push notifications to Cordova and Ionic Cordova apps for iOS and Android.

<SdkReleasesIframe />

## Overview

This guide explains how to integrate OneSignal push notifications into a Cordova or Ionic Cordova application. It covers installation, SDK initialization, and required platform configuration.

***

## Requirements

* Cordova v10+ (setup instructions use v12)
* Configured OneSignal app and platform

**iOS Requirements**

* cordova-ios 8.0+
* macOS with Xcode 14+ (setup instructions use Xcode 16.2)
* Device with iOS 12+, iPadOS 12+, or Xcode simulator running iOS 16.2+
* CocoaPods 1.16.2+

**Android Requirements**

* Android 7.0+ device or emulator with Google Play Store (Services) installed

<Warning>
  App name should not contain spaces (e.g. "MyApp" instead of "My App") to avoid build issues.
</Warning>

### Configure your OneSignal app and platform

Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).

<Note>
  If your organization already has a OneSignal account, [ask to be invited](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Step-by-step setup instructions" icon="circle-chevron-down">
  <Steps>
    <Step title="Create or select your app">
      Create a new app by clicking **New App/Website**, or add a platform to an existing app in **Settings > Push & In-App**. Select the platform(s) you want to configure and click **Next: Configure Your Platform**.

      <Frame>
        <img alt="OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection" />
      </Frame>
    </Step>

    <Step title="Configure platform credentials">
      Enter the credentials for your platform:

      * **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
      * **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
      * **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
      * **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)

      Click **Save & Continue** after entering your credentials.
    </Step>

    <Step title="Save your App ID and install the SDK">
      Your **App ID** is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.

      <Frame>
        <img alt="OneSignal dashboard showing the App ID and team invite option after setup" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

***

## SDK setup

### 1. Add SDK

Add the `onesignal-cordova-plugin` package to your project.

<CodeGroup>
  ```shell Cordova theme={null}
  cordova plugin add onesignal-cordova-plugin
  ```

  ```shell Ionic Cordova theme={null}
  npm install onesignal-cordova-plugin
  ```
</CodeGroup>

### 2. Initialize SDK

Depending on your project framework, initialize OneSignal with the provided instructions.

<Accordion title="Instructions for Ionic Cordova">
  In your `src/app/app.component.ts` file, initialize OneSignal with the provided methods.

  Replace `YOUR_APP_ID` with your OneSignal App ID found in your OneSignal dashboard **Settings > [Keys & IDs](./keys-and-ids)**.

  <Note>
    If you don't have access to the OneSignal app, ask your [Team Members](./manage-team-members) to invite you.
  </Note>

  <CodeGroup>
    ```typescript TypeScript theme={null}
    import OneSignal, { LogLevel } from 'onesignal-cordova-plugin';

    constructor(platform: Platform) {
      platform.ready().then(() => {
        // Enable verbose logging for debugging (remove in production)
        OneSignal.Debug.setLogLevel(LogLevel.Verbose);
        // Initialize with your OneSignal App ID
        OneSignal.initialize("YOUR_APP_ID");
        // Use this method to prompt for push notifications.
        // We recommend removing this method after testing and instead use In-App Messages to prompt for notification permission.
        OneSignal.Notifications.requestPermission(false).then((accepted: boolean) => {
          console.log("User accepted notifications: " + accepted);
        });
      });
    }
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Instructions for Cordova">
  In your `www/js/index.js` file, initialize OneSignal with the provided methods.

  Replace `YOUR_APP_ID` with your OneSignal App ID found in your OneSignal dashboard **Settings > [Keys & IDs](./keys-and-ids)**.

  <Note>
    If you don't have access to the OneSignal app, ask your [Team Members](./manage-team-members) to invite you.
  </Note>

  <CodeGroup>
    ```javascript index.js theme={null}
    document.addEventListener('deviceready', onDeviceReady, false);

    function onDeviceReady() {
      // Enable verbose logging for debugging (remove in production)
      window.plugins.OneSignal.Debug.setLogLevel(6);
      // Initialize with your OneSignal App ID
      window.plugins.OneSignal.initialize('YOUR_APP_ID');
      // Use this method to prompt for push notifications.
      // We recommend removing this method after testing and instead use In-App Messages to prompt for notification permission.
      window.plugins.OneSignal.Notifications.requestPermission(false).then((accepted) => {
        console.log("User accepted notifications: " + accepted);
      });
    }
    ```
  </CodeGroup>
</Accordion>

***

## Android setup

Make sure your OneSignal app is configured for the Android platform using your [Firebase credentials](/docs/en/android-firebase-credentials).

Set up your [notification icons](/docs/en/notification-icons) to match your app’s branding. If this step is skipped, a default bell icon will display for your push notifications.

**Build for Android**

At this point, you should be able to build and run your app on a physical Android device or emulator without issues.

<Check>
  After confirming that your Android build works:

  * Continue with the [iOS setup](#ios-setup), if applicable.
  * Or jump ahead to [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## iOS setup

Make sure your OneSignal app is configured for the iOS platform using either the [p8 Token (Recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 Certificate](/docs/en/ios-p12-generate-certificates).

Follow these steps to add push notifications to your iOS app, including support for [Badges](/docs/en/badges), [Confirmed receipt](/docs/en/confirmed-delivery), and images.

### 1. Add Push Notifications capability to app target

The [Push Notifications capability](https://developer.apple.com/documentation/UserNotifications/registering-your-app-with-apns#Enable-the-push-notifications-capability) allows your app to register a push token and receive notifications.

1. Open your app’s `.xcworkspace` file in Xcode.
2. Select **your app target > Signing & Capabilities**
3. Click **+ Capability** and add **Push Notifications** capability

<Frame>
  <img />
</Frame>

### 2. Add Background Modes capability to app target

This enables your app to wake in the background when push notifications arrive.

1. Add [Background Modes](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app) capability
2. Enable **Remote notifications**

<Frame>
  <img />
</Frame>

### 3. Add app target to App Group

[App Groups](https://developer.apple.com/documentation/xcode/configuring-app-groups/#Create-App-Groups-for-all-other-platforms) allow data sharing between your app and the Notification Service Extension. Required for confirmed receipt and Badges.

<Tabs>
  <Tab title="If you do NOT have an App Group configured">
    1. Add **App Groups** capability
    2. In the App Groups capability click **+**
    3. Add a new container ID in format: `group.your_bundle_id.onesignal`

    * Keep **group.** and **.onesignal** prefix and suffix. Replace **`your_bundle_id`** with your app's bundle identifier.
    * For example, bundle identifier `com.onesignal.MyApp`, will have the container name `group.com.onesignal.MyApp.onesignal`.

    <Frame>
      <img />
    </Frame>

    <Warning> Your App Group name must exactly match your bundle ID’s spelling and capitalization across all targets. </Warning>
  </Tab>

  <Tab title="If you DO have an App Group">
    1. Open your **App Target** and **OneSignalNotificationServiceExtension Target's** `Info.plist`
    2. Add a new property to the `Info.plist` for both targets:

    * **Key:** `OneSignal_app_groups_key`
    * **Value:** Your existing App Group name (e.g., `group.your-custom-group-id`)

    ```xml XML theme={null}
    <key>OneSignal_app_groups_key</key>
    <string>group.your-custom-group-id</string>
    ```

    <Frame>
      <img />
    </Frame>

    <Warning>
      Make sure to update the `OneSignal_app_groups_key` in **both** the App Target **and** OneSignalNotificationServiceExtension Target's `Info.plist`!
    </Warning>
  </Tab>
</Tabs>

### 4. Add Notification Service Extension

The [Notification Service Extension (NSE)](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications) enables rich notifications and confirmed receipt analytics.

1. In Xcode: **File > New > Target...**
2. Select **Notification Service Extension**, then **Next**.
3. Set the product name to `OneSignalNotificationServiceExtension` and press **Finish**.
4. Press **Don't Activate** on the Activate scheme prompt.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

Set the OneSignalNotificationServiceExtension **Minimum Deployment Target** to match your main app (iOS 15+ recommended).

<Info> If you're using CocoaPods, set the deployment version in your Podfile as well. </Info>

<Frame>
  <img />
</Frame>

### 5. Add NSE target to app group

Use the same App Group ID you added in step 3.

1. Go to **OneSignalNotificationServiceExtension > Signing & Capabilities**
2. Add **App Groups**
3. Add the exact same group ID

<Warning>
  If you are using a custom App Group name and not `group.your_bundle_id.onesignal` then make sure to add your App Group ID to both the App Target and OneSignalNotificationServiceExtension Target's `Info.plist`! See [step 3](#3-add-app-target-to-app-group) for more information.
</Warning>

<Frame>
  <img />
</Frame>

### 6. Update NSE code

1. Navigate to the **OneSignalNotificationServiceExtension** folder
2. Replace the contents of the `NotificationService.swift` or `NotificationService.m` file with the following:

<Frame>
  <img />
</Frame>

<CodeGroup>
  ```swift Swift theme={null}
  import UserNotifications
  import OneSignalExtension

  class NotificationService: UNNotificationServiceExtension {
      var contentHandler: ((UNNotificationContent) -> Void)?
      var receivedRequest: UNNotificationRequest!
      var bestAttemptContent: UNMutableNotificationContent?

      // Note this extension only runs when `mutable_content` is set
      // Setting an attachment or action buttons automatically sets the property to true
      override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
          self.receivedRequest = request
          self.contentHandler = contentHandler
          self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

          if let bestAttemptContent = bestAttemptContent {
              // DEBUGGING: Uncomment the 2 lines below to check this extension is executing
  //            print("Running NotificationServiceExtension")
  //            bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

              OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
          }
      }

      override func serviceExtensionTimeWillExpire() {
          // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
          if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
              OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
              contentHandler(bestAttemptContent)
          }
      }
  }
  ```

  ```objectivec Objective-C theme={null}
  #import <OneSignalExtension/OneSignalExtension.h>
  #import "NotificationService.h"

  @interface NotificationService ()

  @property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
  @property (nonatomic, strong) UNNotificationRequest *receivedRequest;
  @property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

  @end

  @implementation NotificationService

  // Note, this extension only runs when mutable-content is set
  // Setting an attachment or action buttons automatically adds this
  - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
      self.receivedRequest = request;
      self.contentHandler = contentHandler;
      self.bestAttemptContent = [request.content mutableCopy];

      // DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is executing
  //     NSLog(@"Running NotificationServiceExtension");
  //     self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];

      [OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
                         withMutableNotificationContent:self.bestAttemptContent
                                     withContentHandler:self.contentHandler];
  }

  - (void)serviceExtensionTimeWillExpire {
      // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.

      [OneSignalExtension serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];

      self.contentHandler(self.bestAttemptContent);
  }

  @end
  ```
</CodeGroup>

You should see an error because the OneSignal package is not installed. This will be resolved in the next step.

<Frame>
  <img />
</Frame>

### 7. Add OneSignal to the NSE target

<Note>
  If your SDK uses Swift Package Manager (SPM) for iOS dependencies, you can skip this step. The OneSignal package is already resolved and available to all targets.
</Note>

Update your `ios/Podfile` to include:

<CodeGroup>
  ```ruby Podfile theme={null}
  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```

  ```ruby Example theme={null}
  target 'MyApp' do
    config = use_native_modules!

    use_react_native!(
      :path => config[:reactNativePath],
      # An absolute path to your application root.
      :app_path => "#{Pod::Config.instance.installation_root}/.."
    )

    post_install do |installer|
      # https://github.com/facebook/react-native/blob/main/packages/react-native/scripts/react_native_pods.rb#L197-L202
      react_native_post_install(
        installer,
        config[:reactNativePath],
        :mac_catalyst_enabled => false,
        # :ccache_enabled => true
      )
    end
  end

  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```
</CodeGroup>

Open your project in the terminal and run:

```shell shell  theme={null}
cd ios pod install cd .. 
```

#### Common pod install errors

You may run into the following errors, here is how you can resolve them.

<Accordion
  title="ArgumentError - \[Xcodeproj] Unable to find compatibility version string for
object version `70`."
>
  CocoaPods relies on the `xcodeproj` Ruby gem to read your Xcode project files. As of now, the latest `xcodeproj` release does not recognize object version 70, which was introduced by Xcode 16. So when CocoaPods tries to open your `.xcodeproj` file, it crashes with this error.

  1. Close Xcode.
  2. Navigate to your project's `ios/<your-app>.xcodeproj/project.pbxproj` file.
  3. Change this line: `objectVersion = 70;`
  4. Replace it with: `objectVersion = 55;`
  5. Save, close, and rerun `cd ios pod install cd ..`
</Accordion>

### Build for iOS

You should now be able to build and run your app on a real iOS device or iOS simulator (16.2+).

#### Common iOS build errors

<Accordion title="commandPhaseScript Execution exited with a non-zero code">
  1. Delete your Podfile.lock
  2. Delete your Pods folder
  3. Delete your .xcworkspace
  4. Pod install
  5. Cmd + Shift + K to Clean the build and then retry building

  If these steps do not resolve the error, build directly from the Xcode, then find the build error in the report navigator pictured below.

  <img />
</Accordion>

<Accordion title="Cycle Inside... building could produce unreliable results.">
  You may see this error when building with Xcode 15+, due to a default configuration change affecting cross platform systems.

  1. Open your `.xcworkspace` folder in Xcode and navigate to **your app target > Build Phases**.
  2. You should have a phase called **"Embed Foundation Extensions"** or **"Embed App Extensions"**.
  3. Drag and move this build phase to *above* **"Run Script"**.
  4. Build and run your app. The error should be resolved.

  <Frame>
    <img />
  </Frame>

  <Frame>
    <img />
  </Frame>
</Accordion>

<Accordion title="PBXGroup Error">
  <Info>
    RuntimeError - `PBXGroup` attempted to initialize an object with unknown ISA `PBXFileSystemSynchronizedRootGroup` from attributes: `{"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}`
  </Info>

  Fix:

  1. Find the folder listed under "path" in the error
  2. In Xcode project sidebar, right-click the folder
  3. Select **Convert to Group**

  <Frame>
    <img />
  </Frame>

  <br />

  <Frame>
    <img />
  </Frame>
</Accordion>

<Check>
  After confirming that your iOS build works, continue with [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications, subscription registration, and in-app messaging.

<Warning>
  If you are testing with an Android emulator, it should start with a cold boot.

  1. Go to **Device Manager** in Android Studio.
  2. Select your emulator device and click **Edit**.
  3. Go to **Additional Settings** or **More**.
  4. Set the **Boot option** to **Cold Boot**.
  5. Save changes and restart the emulator.
</Warning>

### Check mobile subscriptions

<Steps>
  <Step title="Launch your app on a test device.">
    The native push permission prompt should appear automatically if you added the `requestPermission` method during initialization.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    Before accepting the prompt, check the OneSignal dashboard:

    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status "Never Subscribed".

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Return to the app and tap Allow on the prompt." />

  <Step title="Refresh the OneSignal dashboard Subscription's page.">
    The subscription's status should now show **Subscribed**.

    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a [mobile subscription](/docs/en/subscriptions).
    Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a segment of test users.
    We can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

    ```curl theme={null}
    curl -X \
    POST --url 'https://api.onesignal.com/notifications' \
     --header 'content-type: application/json; charset=utf-8' \
     --header 'authorization: Key YOUR_APP_API_KEY' \
     --data \
     '{
      "app_id": "YOUR_APP_ID",
      "target_channel": "push",
      "name": "Testing basic setup",
      "headings": {
      	"en": "👋"
      },
      "contents": {
        "en": "Hello world!"
      },
      "included_segments": [
        "Test Users"
      ],
      "ios_attachments": {
        "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      },
      "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
    }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification with an image included:

    <Frame>
      <img />
    </Frame>

    <Info>Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Info>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats.

    You should see the **confirmed** stat, meaning the device received the push.
    <Check>You have successfully sent a notification via our API to a segment.</Check>

    <Warning>
      * No image received? Your [Notification Service Extension](#ios-setup) might be missing.
      * No confirmed receipt? Review the troubleshooting guide [here](/docs/en/confirmed-delivery#troubleshooting-confirmed-delivery).
      * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
    </Warning>
  </Step>
</Steps>

### Send an in-app message

[In-app messages](/docs/en/in-app-messages-setup) let you communicate with users while they are using your app.

<Steps>
  <Step title="Close or background your app on the device.">
    This is because users must meet the in-app audience criteria *before* a new session starts. In OneSignal, a new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds. For more details, see our guide on [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
  </Step>

  <Step title="Create an in-app message.">
    * In your OneSignal dashboard, navigate to **Messages > In-App > New In-App**.
    * Find and select the **Welcome** message.
    * Set your Audience as the **Test Users** segment we used previously.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Customize the message content if desired.">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Set Trigger to 'On app open'." />

  <Step title="Schedule frequency.">
    Under **Schedule > How often do you want to show this message?** select **Every time trigger conditions are satisfied**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Make message live.">
    Click **Make Message Live** so it is available to your Test Users each time they open the app.
  </Step>

  <Step title="Open the app and see the message.">
    After the in-app message is live, open your app. You should see it display:

    <Frame>
      <img />
    </Frame>

    <Warning>
      Not seeing the message?

      * Start a new session
        * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
        * For more, see [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
      * Still in the `Test Users` segment?
        * If you reinstalled or switched devices, re-add the device to [Test Users](#set-up-test-users) and confirm it's part of the Test Users segment.
      * Having issues?
        * Follow [Getting a Debug Log](/docs/en/capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
    </Warning>
  </Step>
</Steps>

<Check>
  You have successfully setup the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](/docs/en/subscriptions), setting [Test Users](/docs/en/find-set-test-subscriptions), and creating [Segments](/docs/en/segmentation).
  * Sending [Push](/docs/en/push) with images and [Confirmed receipt](/docs/en/confirmed-delivery) using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](/docs/en/in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

***

## User identification

Previously, we demonstrated how to create mobile [Subscriptions](/docs/en/subscriptions). Now we'll expand to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We'll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with our SDK's [`login` method](/docs/en/mobile-sdk-reference#login-external-id) each time they are identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with our SDK [`addTag` and `addTags` methods](/docs/en/mobile-sdk-reference#data-tags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img />
</Frame>

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

### Add email and/or SMS subscriptions

Earlier we saw how our SDK creates mobile subscriptions to send push and in-app messages. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/mobile-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/mobile-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/mobile-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/mobile-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

See our Privacy & security docs for more on:

* [Data collected by the SDK](/docs/en/data-collected-by-the-onesignal-sdk)
* [Handling personal data](/docs/en/handling-personal-data)

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](/docs/en/prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners for you to hook into. See our [SDK reference guide](/docs/en/mobile-sdk-reference) for more details.

### Push notification events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-push): Detect when a notification is tapped. Helpful for [Deep Linking](/docs/en/deep-linking).
* [`addForegroundLifecycleListener()`](/docs/en/mobile-sdk-reference#addforegroundlifecyclelistener-push): Control how notifications behave in foreground.

For full customization, see [Mobile Service Extensions](/docs/en/service-extensions).

### User state changes

* [`addObserver()` for user state](/docs/en/mobile-sdk-reference#addobserver-user-state): Detect when the External ID is set.
* [`addPermissionObserver()`](/docs/en/mobile-sdk-reference#addpermissionobserver-push): Track the user's specific interaction with the native push permission prompt.
* [`addObserver()` for push subscription](/docs/en/mobile-sdk-reference#addobserver-push-subscription-changes): Track when the push subscription status changes.

### In-app message events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Handle in-app click actions. Ideal for deep linking or tracking events.
* [`addLifecycleListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Track full lifecycle of in-app messages (shown, clicked, dismissed, etc.).

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

* [🔁 Migrating to OneSignal from another service](/docs/en/migrating-to-onesignal)
* [🌍 Location tracking](/docs/en/mobile-sdk-reference#location)
* [🔗 Deep Linking](/docs/en/deep-linking)
* [🔌 Integrations](/docs/en/integrations)
* [🧩 Mobile Service Extensions](/docs/en/service-extensions)
* [🛎️ Action buttons](/docs/en/action-buttons)
* [🌐 Multi-language messaging](/docs/en/multi-language-messaging)
* [🛡️ Identity Verification](/docs/en/identity-verification)
* [📊 Custom Outcomes](/docs/en/custom-outcomes)
* [📲 Live Activities](/docs/en/live-activities)

### Mobile SDK setup & reference

Make sure you've enabled all key features by reviewing the [Mobile push setup](/docs/en/mobile-push-setup) guide.

For full details on available methods and configuration options, visit the [Mobile SDK reference](/docs/en/mobile-sdk-reference).

<Check>Congratulations! You've successfully completed the Mobile SDK setup guide.</Check>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Create activity feed
Source: https://documentation.onesignal.com/docs/en/create-an-activity-feed

Learn how to build an in-app activity feed using OneSignal's REST API, Event Streams, or on-device logic to track and display user notification history.

## What is an activity feed?

An activity feed lets users see the history of notifications they've received within your app.

OneSignal focuses on delivering notifications but does not currently store the history of messages sent to each individual user. To build this functionality, you'll need to store notification data yourself—either on your backend server or directly on the user’s device.

<Tabs>
  <Tab title="Option 1">
    ## Saving to server

    **Recommended Approach**

    Rather than relying on background processing in your app, use the [Create notification](/reference/create-message) REST API to send each notification and also store a copy on your server. Then, when the app launches, it can check the server for updates.

    Once the data is stored, you can retrieve and display the user’s notification history at any time.
  </Tab>

  <Tab title="Option 2">
    ## Create an activity feed using OneSignal Event Streams

    OneSignal’s [Event Streams](./event-streams) feature provides a scalable way to stream real-time events from your app to your backend systems or data warehouse. This lets you build a feed that reflects in-app user behavior—like follows, comments, purchases, or notification events—without manually updating the feed within your app.

    ### How it works

    Event Streams exports live event data including:

    * Notification deliveries
    * Email/SMS opens and clicks
    * User-triggered actions

    Destinations include:

    * Webhooks (your HTTP endpoints)
    * Amazon Kinesis
    * Amazon S3
    * Google Cloud Storage
    * BigQuery
    * And more

    Your system receives these events as they occur and can use them to update a feed UI or analytics pipeline.

    ## Steps to set up an Activity Feed with Event Streams

    <Steps>
      <Step title="Enable Event Streams">
        * Go to the **OneSignal Dashboard** > **Settings** > **Event Streams**.
        * Choose a destination such as a Webhook or data pipeline (e.g., Amazon Kinesis).
        * Select the events you want to stream (e.g., `message.sent`, `message.delivered`, `message.clicked`).
      </Step>

      <Step title="Configure your backend to handle event data">
        * Create a webhook or consumer that ingests event data.
        * Parse the event payload to extract relevant fields like:

          * `external_id` (the user ID)
          * `event` type (`message.delivered`, etc.)
          * `timestamp`
          * `contents` (notification message)
          * `additional_data` (any custom metadata)
      </Step>

      <Step title="Store and structure Activity Feed entries">
        * Save these events to your database in a format suitable for querying and rendering.

        ```json theme={null}
        {
          "message.id": "f3c9cd09-10d7-4f59-b9bc-66e16607f1d5",
          "message.name": "the-name-you-set",
          "message.title": "Claim 50% Off Today", // email subject example
          "message.title": "{'en':'the message title/headings'}", // push title example
          "message.contents": "{'en':'the message content'}",
          "message.template_id": "the-template-uuid-if-set",
          "message.url": "the-message-url",
          "message.app_url": "the-message-app-url",
          "message.web_url": "the-message-web-url"
        }
        ```
      </Step>

      <Step title="Render the feed in your app">
        * Build a frontend component (e.g., React, SwiftUI, or Android View) to query and display recent events for the logged-in user.
        * Optionally include filters or grouping by event type.
      </Step>

      <Step title="Enhance with additional metadata">
        * When sending notifications, include `additional_data` to provide feed context, for example:

          ```json theme={null}
          {
            "action": "commented",
            "post_id": "xyz123"
          }
          ```

        * This allows you to create rich feed entries such as “Jane commented on your post.”
      </Step>
    </Steps>

    ### Example use cases

    * **E-commerce**: Show order confirmations, shipping updates, and promotions.
    * **Social Apps**: Show likes, comments, follows.
    * **SaaS Platforms**: Track task assignments, mentions, or activity logs.

    ### Benefits

    * Real-time updates via event streaming
    * Fully customizable logic and display
    * Scalable, backend-driven architecture
  </Tab>
</Tabs>

***


# Cross-platform Live Activity SDK setup
Source: https://documentation.onesignal.com/docs/en/cross-platform-live-activity-setup

Learn how to implement Live Activities in OneSignal's Wrapper SDKs like React Native, Flutter, Unity, Cordova, and more, with support for Push To Start and Default Live Activity Type.

Live Activities are a relatively new iOS feature and require native implementation, which can pose challenges when using cross-platform frameworks like React Native, Flutter, Unity, Cordova, etc. To simplify the process, OneSignal's SDK includes functionality that minimizes native code requirements, enabling streamlined Live Activity integration across supported platforms.

## Requirements

* The latest version of our SDK.
* iOS 16.1+ and iPadOS 17+
* Use a [.p8 APNs key](./ios-p8-token-based-connection-to-apns). Apple doesn't support p12 certificates with Live Activities.
* Xcode 14 or higher

## Setup

### 1. Setup our SDK

Ensure that you've set up the most recent version of our Mobile SDK on your app. Live Activities are not available for websites or with our Web SDK.

<Columns>
  <Card href="./unity-sdk-setup">
    <div>
      <div>
        <img />
      </div>

      <div>
        <div>
          Unity
        </div>

        <div>
          Cross-platform SDK guide for Unity-based mobile apps.
        </div>
      </div>
    </div>
  </Card>

  <Card href="./react-native-sdk-setup">
    <div>
      <div>
        <img />
      </div>

      <div>
        <div>
          React Native & Expo
        </div>

        <div>
          Setup instructions for React Native and Expo environments.
        </div>
      </div>
    </div>
  </Card>

  <Card href="./flutter-sdk-setup">
    <div>
      <div>
        <img />
      </div>

      <div>
        <div>
          Flutter
        </div>

        <div>
          SDK guide for Flutter apps using Dart.
        </div>
      </div>
    </div>
  </Card>

  <Card href="./capacitor-sdk-setup">
    <div>
      <div>
        <img />
      </div>

      <div>
        <div>
          Ionic & Ionic Capacitor
        </div>

        <div>
          Setup for Ionic and Capacitor hybrid mobile apps.
        </div>
      </div>
    </div>
  </Card>

  <Card href="./net-sdk-setup">
    <div>
      <div>
        <img />
      </div>

      <div>
        <div>
          .NET MAUI
        </div>

        <div>
          Guide for integrating with .NET MAUI apps.
        </div>
      </div>
    </div>
  </Card>

  <Card href="./huawei-sdk-setup">
    <div>
      <div>
        <img />
      </div>

      <div>
        <div>
          Huawei Android Native
        </div>

        <div>
          SDK setup for Huawei devices using HMS push services.
        </div>
      </div>
    </div>
  </Card>
</Columns>

### 2. Add the new `setupDefault` method

In order to tell the OneSignal SDK to manage the LiveActivity lifecycle for the `DefaultLiveActivityAttributes` type, you can call the `setupDefault` method. This method allows you to use both the [Start Live Activity](/reference/start-live-activity) and [Update Live Activity](/reference/update-live-activity-api) APIs to start/update/end the Default Live Activity.

<CodeGroup>
  ```javascript React Native/Expo theme={null}
  import { OneSignal } from 'react-native-onesignal'

  //Push To Start
  OneSignal.LiveActivities.setupDefault()

  //Launching the Live Activity from within the app (not needed for push to start)
  const activityId = "my_activity_id"
  const attributes = { title: "Sample Title" } ;
  const content = { message: { en: "message" } };
  OneSignal.LiveActivities.startDefault(activityId, attributes, content);

  ```

  ```csharp Unity theme={null}
  using OneSignalSDK;

  //Push To Start
  OneSignal.LiveActivities.SetupDefault();

  //Launching the Live Activity from within the app (not needed for push to start)
  string activityId = "my_activity_id";

  OneSignal.LiveActivities.StartDefault(
    activityId,
    new Dictionary<string, object>() {
        { "title", "Welcome!" }
    },
    new Dictionary<string, object>() {
        { "message", new Dictionary<string, object>() {
            { "en", "Hello World!"}
        }},
    });
  ```

  ```javascript Cordova/Ionic theme={null}
  /*Cordova*/

  //Push To Start
  window.plugins.OneSignal.LiveActivities.setupDefault();

  //Launching the Live Activity from within the app (not needed for push to start)
  const activityId = "my_activity_id";
  const attributes = { title: "Sample Title" };
  const content = { message: { en: "message" } };
  window.plugins.OneSignal.LiveActivities.startDefault(
    activityId,
    attributes,
    content
  );

  /*Ionic/Capacitor*/
  import OneSignal from "onesignal-cordova-plugin";

  //Push To Start
  OneSignal.LiveActivities.setupDefault();

  //Launching the Live Activity from within the app (not needed for push to start)
  const activityId = "my_activity_id";
  const attributes = { title: "Sample Title" };
  const content = { message: { en: "message" } };
  OneSignal.LiveActivities.startDefault(activityId, attributes, content);
  ```

  ```csharp .NET theme={null}
  using OneSignalSDK;

  //Push To Start
  OneSignal.LiveActivities.SetupDefault();

  //Launching the Live Activity from within the app (not needed for push to start)
  string activityId = "my_activity_id";

  OneSignal.LiveActivities.StartDefault(
    activityId,
    new Dictionary<string, object>() {
        { "title", "Welcome!" }
    },
    new Dictionary<string, object>() {
        { "message", new Dictionary<string, object>() {
            { "en", "Hello World!"}
        }},
    });
  ```

  ```javascript Flutter theme={null}
  import 'package:onesignal_flutter/onesignal_flutter.dart';

  OneSignal.LiveActivities.setupDefault()

  //Launching the Live Activity from within the app (not needed for push to start)
  const String activityId = "my_activity_id";
  OneSignal.LiveActivities.startDefault(activityId!, {
    "title": "Welcome!"
    }, {
    "message": {"en": "Hello World!"},
  });
  ```
</CodeGroup>

### 3. Create Activity Widget

<Steps>
  <Step title="Update your Info.plist">
    In Xcode, open your main target’s `Info.plist`, add the key `Supports Live Activities` as **Boolean**, and set it to `YES`.

    <Frame>
      <img />
    </Frame>

    <Note>
      When updating Live Activities, you have the option to set a "priority" which Apple uses to determine how urgent the update is. Apple has internal thresholds in which they will throttle requests that use the high priority flag too frequently.

      If your use cases for Live Activities relies on more frequent high priority updates, you can add the key `NSSupportsLiveActivitiesFrequentUpdates` to your Info.plist as a Boolean type set to YES as directed in [Apple's Developer Docs](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency). Users will be presented with a dialog when the Live Activity exceeds its push budget, and if they allow the Live Activity to continue, the budget will automatically be increased for a seamless user experience.
    </Note>
  </Step>

  <Step title="Create a Widget Extension">
    In Xcode, go to **File > New > Target... > Widget Extension**.

    <Frame>
      <img />
    </Frame>

    Select and press **Next**.

    Configure the Widget Extension by providing a name (example: `OneSignalWidget`) and ensure **Include Live Activity** is selected. Then click **Finish**.

    <Frame>
      <img />
    </Frame>

    Click **Don't Activate** if prompted to activate the scheme.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Add the OneSignalXCFramework to your Podfile">
    Find the name of your widget extension target in your project's Targets list. Example's name is `OneSignalWidgetExtension`.

    <Frame>
      <img />
    </Frame>

    Open your `Podfile` and add the following code. Replace `OneSignalWidgetExtension` with the name of your widget extension target.

    ```ruby Podfile theme={null}
    target 'OneSignalWidgetExtension' do
      #use_frameworks!
      pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
    end
    ```

    Close Xcode and run `pod repo update && pod install` to install the `OneSignalLiveActivities` pod.
  </Step>
</Steps>

### 4. Setup the LiveActivity.swift file

In Xcode, open the *WidgetExtensionLiveActivity.swift* file.

Open the Inspector panel on the right side of the screen. Within **Target Membership**, click the **+** button and select your Runner target.

<Frame>
  <img />
</Frame>

Update the contents of *WidgetExtensionLiveActivity.swift* with the following default Live Activity layout. The values in this Widget can be changed to whatever you'd like displayed on the widget, the setupDefault method will handle defining the struct for these attributes.

```swift Swift theme={null}
import ActivityKit
import WidgetKit
import SwiftUI
import OneSignalLiveActivities

// Your struct name might be different here
@available(iOS 16.2, *)
struct OneSignalWidgetLiveActivity: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: DefaultLiveActivityAttributes.self) { context in
            // Lock screen / banner UI
            VStack {
                Spacer()

                Text("Title: " + (context.attributes.data["title"]?.asString() ?? ""))
                    .font(.headline)

                Spacer()

                HStack {
                    Spacer()
                    Text(context.state.data["message"]?.asDict()?["en"]?.asString() ?? "Default Message")
                    Spacer()
                }

                Text("INT: " + String(context.state.data["intValue"]?.asInt() ?? 0))
                Text("DBL: " + String(context.state.data["doubleValue"]?.asDouble() ?? 0.0))
                Text("BOL: " + String(context.state.data["boolValue"]?.asBool() ?? false))

                Spacer()
            }
            .activitySystemActionForegroundColor(.black)
            .activityBackgroundTint(.white)

        } dynamicIsland: { _ in
            DynamicIsland {
                // Expanded UI
                DynamicIslandExpandedRegion(.leading) {
                    Text("Leading")
                }
                DynamicIslandExpandedRegion(.trailing) {
                    Text("Trailing")
                }
                DynamicIslandExpandedRegion(.bottom) {
                    Text("Bottom")
                    // More content
                }
            } compactLeading: {
                Text("L")
            } compactTrailing: {
                Text("T")
            } minimal: {
                Text("Min")
            }
            .widgetURL(URL(string: "http://www.apple.com"))
            .keylineTint(Color.red)
        }
    }
}

```

***

## Test the Live Activity

1. Start the app

2. See all possible fields in our [Start Live Activity API reference](/reference/start-live-activity). The structure of these fields might differ depending on how you've set up your UI. For example :

* `"event_updates"`: This is the dynamic data that can be updated after the Live Activity has been started (anything after `context.state` in the code example). Since we have context.state.data we would add a data object to this field and any additional fields within like the message dictionary we have added in the code example. For usage, see example request below.
* `"event_attributes"`: This is the static data that is set in the push to start request, and remains the same value until the Live Activity is removed or overwritten.

3. When using push to start, you set the `"activity_id"` in the request, rather than in the code. Using different Activity ID's will start new Live Activities. Using the same Activity ID will overwrite the widget that is currently using that ID.

4. Ensure that you've changed the [OneSignal App ID](./keys-and-ids) in your url path, and the [Rest API Key](./keys-and-ids#rest-api-key) in the Authorization header. The `DefaultActivityAttributes` type cannot be changed if you are using the default setup. Please also note, the activity type added to your path is case sensitive and should match what is defined either by you or the Default activity used in the example below.

```curl curl theme={null}
curl --request POST \
     --url https://api.onesignal.com/apps/YOUR_APP_ID/activities/activity/DefaultLiveActivityAttributes \
     --header 'Authorization: key YOUR_REST_API_KEY' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --data '
{
  "event": "start",
  "event_updates": {
    "data": {
      "message": {
        "en": "The message is nested in context.state.data[\"message\"] as a dictionary"
      },
      "intValue": 10,
      "doubleValue": 3.14,
      "boolValue": true
    }
  },
  "event_attributes": {
    "data": {
      "title": "this is set when the LA starts and does not get updated after"
    }
  },
  "activity_id": "my-activity-id",
  "name": "OneSignal Notification Name",
  "contents": {
    "en": "English Message"
  },
  "headings": {
    "en": "English Message"
  },
  "sound": "beep.wav",
  "priority": 10
}'
```

***

## Low-level methods

These are optional methods to use if you want to generate your own Push To Start token, which has also been added in the latest release of the SDK. Using these methods requires that you interact with Xcode more, and generate your own token for Push To Start with Swift. You can find a guide on this [here](https://github.com/OneSignal/OneSignal-iOS-SDK/pull/1377#:~:text=Alternative%20\(low%20level\)%20method%20to%20setup%20Live%20Activities%20with%20OneSignal).

<CodeGroup>
  ```javascript React Native/Expo theme={null}
  //Setting the Push To Start Token
  OneSignal.LiveActivities.setPushToStartToken(activityType: string, token: string)

  //Removing the Push To Start Token
  OneSignal.LiveActivities.removePushToStartToken(activityType: string)

  ```

  ```csharp Unity theme={null}
  //Setting the Push To Start Token
  OneSignal.LiveActivities.SetPushToStartToken(string activityType, string token)

  //Removing the Push To Start Token
  OneSignal.LiveActivities.RemovePushToStartToken(string activityType)
  ```

  ```javascript Cordova/Ionic theme={null}
  /* Cordova */
  //Setting the Push To Start Token
  window.plugins.OneSignal.LiveActivities.setPushToStartToken(activityType: string, token: string)

  //Removing the Push To Start Token
  window.plugins.OneSignal.LiveActivities.removePushToStartToken(activityType: string)

  /* Ionic */
  //Setting the Push To Start Token
  OneSignal.LiveActivities.setPushToStartToken(activityType: string, token: string)

  //Removing the Push To Start Token
  OneSignal.LiveActivities.removePushToStartToken(activityType: string)
  ```

  ```csharp .NET theme={null}
  //Setting the Push To Start Token
  OneSignal.LiveActivities.SetPushToStartToken(string activityType, string token)

  //Removing the Push To Start Token
  OneSignal.LiveActivities.RemovePushToStartToken(string activityType)
  ```

  ```javascript Flutter theme={null}
  //Setting the Push To Start Token
  OneSignal.LiveActivities.setPushToStartToken(String activityType, String token)

  //Removing the Push To Start Token
  OneSignal.LiveActivities.removePushToStartToken(String activityType)
  ```
</CodeGroup>

***


# Daily streak journey
Source: https://documentation.onesignal.com/docs/en/daily-streak

Use Journeys to build daily streak reminders that keep users coming back, using last session time or tags and custom events.

## Overview

Daily streaks are one of the most effective retention mechanics in mobile and web apps. By reminding users to return each day, you can build habits, increase engagement, and reduce churn.

This tutorial walks through three Journey configurations:

* **[1-day recurring streak reminder (last session time)](#1-day-recurring-streak-reminder)**: A simple daily nudge for users who haven't opened the app yet today.
* **[7-day streak Journey (last session time)](#7-day-streak-journey)**: A guided 7-day challenge that checks daily activity and rewards users who complete the full streak.
* **[1-day recurring streak with tags and custom events](#1-day-recurring-streak-with-tags-and-custom-events)**: A tag-based approach that tracks streak count and sends personalized reminders based on progress.

### Prerequisites

Before starting, make sure you have:

* A OneSignal app with [push notifications](/docs/en/channel-setup) configured
* [External IDs](/docs/en/users) assigned to your users (recommended for cross-channel accuracy)
* Familiarity with [Journeys](/docs/en/journeys-overview), [Segments](/docs/en/segmentation), and [Journey actions](/docs/en/journeys-actions)

***

## 1-day recurring streak reminder

**Goal**: Send multiple daily push notifications throughout the day to users who haven't opened the app today, reminding them to keep their streak alive. When the user opens the app, they exit the Journey. The next day, the cycle repeats.

This approach uses user session activity only to trigger and manage the journey - no tags or custom events required. Users move through the journey using time window nodes, ensuring that your push notifications are sent at specific times of day.

#### Segments used

| Segment                               | Filters                                | Notes                                                                  |
| ------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------- |
| **Total Users** (optional)            | **No filters**                         | To include all users in the journey                                    |
| **Active in last 8 hours** (required) | **Last session less than 8 hours ago** | In order to check if the user was active before the first time window. |

<Note>
  If your first time window is not set to start at 8am in the user's timezone, change the settings of the `Active in last X hours` segment to a suitable time (e.g. for a 10am time window, the segment should check for users that were active in the last 10 hours)
</Note>

#### Journey settings

| Setting            | Configuration                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| **Entry rules**    | **Audience Segment**                                                                                                |
| **Audience**       | Include: `Total Users` segment                                                                                      |
| **Exit rules**     | **Exit when user becomes active in your app/website**. & **Tag users when they exit early**: `streak_ongoing: true` |
| **Re-entry rules** | **Yes, after a certain amount of time**: `10 minutes`                                                               |
| **Schedule**       | **Start immediately, never stops**                                                                                  |

<Note>
  Setting re-entry to 10 minutes ensures users re-enter the Journey as soon as possible. This is important to ensure that all eligible users are in the journey at the start of the new day.
</Note>

#### Journey steps

<Steps>
  <Step title="Add a Time Window node">
    Begin by setting a Time Window node to your preferred delivery hours for the first reminder push, for example **8:00 AM – 8:15 AM** every day. Enable **Use user's time zone** so messages arrive at a reasonable local time.

    <Frame>
      <img alt="A time window node for 8:00 AM – 8:15 AM every day" />
    </Frame>

    Users who enter the journey after this window will wait until the next day before receiving the first push notification (this will only affect new sign-ups who have had their first ever session after 8am).
  </Step>

  <Step title="Check for activity before first Time Window - Add a Yes/No branch">
    Before we send any messages, we need to check if the user was active in the last 8 hours, in case they joined the journey after 0:00am.

    <Frame>
      <img alt="A yes/no branch for a 'Active in last 8 hours' segment" />
    </Frame>

    The Yes/No branch will check membership of this segment and if the user has been active in the last 8 hours, then they skip all of the messaging steps of the journey (following the yes branch).
    <Warning>If you have selected a different time for your first check, then you will need to adjust this segment's name and filters accordingly to check if the user's last session was between this time window and 00:00am</Warning>
  </Step>

  <Step title="Add a Yes/No branch">
    On the "No" branch of the previous Yes/No check, we want to ensure that we send appropriate messaging to our users. Here we want to branch based on whether the user has a streak ongoing or not. To do this, we need a segment of users who already have the `streak_ongoing: true` tag that is set when a user exits this journey early:

    <Frame>
      <img alt="A yes/no branch for a 'Currently in streak' segment" />
    </Frame>

    The Yes/No branch will check membership of this segment and send different push notifications depending on whether the user is in the streak or not.
  </Step>

  <Step title="First push notifications">
    Create two different push templates which remind the user to return to the app. One should mention continuing a streak, the other should mention starting a streak. Add the continuing template to the "Yes" branch, and the starting template to the "No" branch.

    <Frame>
      <img alt="Two push notification nodes." />
    </Frame>
  </Step>

  <Step title="Repeat the above steps.">
    After the branches converge, repeat the above steps - Time Window → Yes/No branch → Push notifications - as many times as you think necessary, changing the time window appropriately each time.
    <Note>**Think about your users' daily routines**: Set the time windows for times of the day when your users might be active on their device (e.g. during their commute, at lunch time, after dinner time). Always avoid times when users are likely to be asleep.</Note>
    <Warning>**Don't be repetitive**: Make sure that you use a different push template each time you repeat the steps - users will quickly get frustrated with seeing the same notification repeatedly throughout the day.</Warning>
  </Step>

  <Step title="Add a final time window">
    Add a time window for 12:00 AM to 12:15 AM. This signifies the start of a new day and the end of the streak.

    <Frame>
      <img alt="A time window node for 12:00 AM – 12:15 AM every day" />
    </Frame>
  </Step>

  <Step title="Update the &#x22;streak_ongoing&#x22; tag">
    If the user has made it this far through the messaging branch of the journey without exiting early, it means that they have failed their streak. We need to update the `streak_ongoing` tag to `false` with a "Tag" node, both for tracking purposes and also so that when they rejoin the journey, they are sent the appropriate push notifications.

    Similarly, on the "Yes" branch of our first Yes/No node (from step 2), we need to update the `streak_ongoing` tag to `true`, as the user completed their streak before our first Time Window check:

    <Frame>
      <img alt="A tag node setting the 'streak_ongoing' tag on two branches." />
    </Frame>
  </Step>
</Steps>

<Check>
  That's it - set the Journey live. Each day users will enter the journey and be sent one of two sets of push notifications (depending on whether they are continuing or starting a streak) reminding them to log in to maintain/build their streak.
</Check>

***

## 7-day streak Journey

**Goal**: Guide users through a 7-day streak challenge. This can be a one-off, one-shot streak (ideal for time-limited events), or a repeatable streak that users can reattempt (for weekly streaks).

This approach uses user activity only to trigger and manage the journey - no tags or custom events required.

#### Segments used

| Segment                               | Filters                                 | Notes                                                                                                              |
| ------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Total Users** (optional)            | **No filters**                          | To include all users in the journey. You can use other segments in place of this to target a more limited audience |
| **7 day streak completed** (optional) | **"7\_day\_streak" tag is "completed"** | Can be used to exclude users that have already completed the streak or for tracking purposes                       |
| **Active in last 8 hours** (required) | **Last session less than 8 hours ago**  | To check for user activity between time windows.                                                                   |
| **Active in last 6 hours** (required) | **Last session less than 6 hours ago**  | To check for user activity between time windows.                                                                   |
| **Active in last 4 hours** (required) | **Last session less than 4 hours ago**  | To check for user activity between time windows.                                                                   |
| **7 day streak failed** (required)    | **"7\_day\_streak" tag is "failed"**    | Used to force the user to exit the journey early if they are inactive for more than a day.                         |

#### Journey settings

| Setting            | Configuration                                                                                                                                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entry rules**    | **Audience Segment**                                                                                                                                                                                                                   |
| **Audience**       | **Include: `Total Users`** segment. (**Optional: Exclude `7 day streak completed`** to make it so that users can only complete the streak once, and `7 day streak failed` to make it so that a user can only attempt the streak once)  |
| **Exit rules**     | **Exit when user enters a segment: `7 day streak failed`** (**Optional : Tag users when they exit early**: `7_day_streak: 0` - removes users from `7 day streak failed` segment and allows them to re-enter the journey after failing) |
| **Re-entry rules** | **Yes, after a certain amount of time**: `10 minutes` (if repeating) OR **No, they can receive this only once** (for single attempts)                                                                                                  |
| **Schedule**       | **Start immediately, never stops**                                                                                                                                                                                                     |

<Note>
  The above journey settings are a guide only. If you want to change your target audience or allow users to repeat the journey, simply adjust the settings accordingly. Only the **Exit rules** criteria laid out above are mandatory for this journey to function correctly.
</Note>

#### Journey steps

<Steps>
  <Step title="Add a Time Window node">
    Begin by setting a Time Window node to your preferred delivery hours for the first reminder push, for example **8:00 AM – 8:15 AM** every day. Enable **Use user's time zone** so messages arrive at a reasonable local time.

    <Frame>
      <img alt="A time window node for 8:00 AM – 8:15 AM every day" />
    </Frame>

    Users who enter the journey after this window will wait until the next day before receiving the first push notification (this will only affect new sign-ups who have had their first ever session after 8am).
  </Step>

  <Step title="Check for activity before first Time Window - Add a Yes/No branch">
    Before we send any messages, we need to check if the user was active in the last 8 hours, in case they joined the journey after 0:00am.

    <Frame>
      <img alt="Yes/no branch for Active in last 8 hours segment" />
    </Frame>

    The Yes/No branch will check membership of this segment and if the user has been active in the last 8 hours, then they skip all of the messaging steps for the first day (following the yes branch).
    <Warning>If you have selected a different time for your first check, then you will need to adjust this segment's name and filters accordingly to check if the user's last session was between this time window and 00:00am</Warning>
  </Step>

  <Step title="First push notification">
    Send your Day 1, first push notification.

    <Frame>
      <img alt="A 'Day 1 - Morning' push notification" />
    </Frame>
  </Step>

  <Step title="Add another Time Window node">
    Add another time window node so that you can send a second reminder push for Day 1 (in this example at 12pm).

    <Frame>
      <img alt="A time window node for 12:00 PM – 12:15 PM every day" />
    </Frame>
  </Step>

  <Step title="Check for activity before Time Window - Add a Yes/No branch">
    Before we send the next message, we need to check if the user was active since the last message, and only send the next message if they were not.

    <Frame>
      <img alt="Yes/no branch for Active in last 4 hours segment" />
    </Frame>

    The Yes/No branch will check membership of this segment and if the user has been active in the last X hours, then they skip all of the messaging steps for the rest of the day if so (following the yes branch).
  </Step>

  <Step title="Second push notification">
    Send your Day 1, second push notification.

    <Frame>
      <img alt="A 'Day 1 - Afternoon' push notification" />
    </Frame>
  </Step>

  <Step title="Repeat steps 4, 5 & 6 to send more notifications.">
    Add more time window and message nodes to send as many push notifications in this day as you like.

    <Frame>
      <img alt="A time window node for 8:00 AM – 8:15 AM every day" />
    </Frame>
  </Step>

  <Step title="Add another Time Window node for 12:00am">
    Add another time window node set to 12:00am to move to the next day.

    <Frame>
      <img alt="A time window node for 12:00 AM – 12:15 AM every day" />
    </Frame>
  </Step>

  <Step title="Check for activity before Time Window - Add a Yes/No branch">
    Before we move to the next day's messages, we need to check if the user was active since the last message, and only continue the journey if they were.

    <Frame>
      <img alt="A yes/no branch for Active in last 6 hours segment" />
    </Frame>

    The Yes/No branch will check membership of this segment. If the user has not been active in the last X hours, they have failed the journey.
  </Step>

  <Step title="Add a tag to eject the user from the journey. ">
    Down the "No" branch of the above Yes/No check, we need to add a tag to eject the user from the journey as they have failed to continue their streak. Add the tag `7_day_streak` with the value `failed` here. This will put the user into the "7 day streak failed" segment and automatically end the journey for them.
    Optionally, you can also add a `streak_failed_day` tag here with the day number as the value in order to track what days your users failed their streaks.

    <Frame>
      <img alt="A tag node setting 7_day_streak to failed" />
    </Frame>
  </Step>

  <Step title="Add a wait node on the original 'Yes' branch of this day.">
    On the "Yes" branch from the Yes/No node in step 2, add a wait node for 16 hours (or whatever the time difference between your first time window time and midnight of the next day). This ensures that the users on this branch are kept in line with users who have been receiving messages on the other branch.

    <Frame>
      <img alt="A 16 hour wait node" />
    </Frame>
  </Step>

  <Step title="Add a tag to signify the streak day achieved.">
    For tracking and personalization purposes, you may want to update the value of your "7\_day\_streak" tag to the number of the day the user is on at this stage (this step is optional).

    <Frame>
      <img alt="An update tag node" />
    </Frame>
  </Step>

  <Step title="Repeat for days 2-7.">
    After the Yes/No branches from step 2 converge, repeat steps 2-12 for each day. Make sure that you vary your messaging each day to reflect the user's progress through the streak.

    <Note>
      You can use message personalisation if you want to reuse your message templates each day. Simply use liquid syntax and the `7_day_streak` tag that was updated in step 12 to remind users how big their streak is so far.
    </Note>
  </Step>

  <Step title="Add a final data tag">
    For tracking purposes, and to prevent users from re-entering if you want to only allow them to finish the streak once, just before the exit node as the final step of your journey, update the `7_day_streak` to `completed`.

    If you have been setting the `streak_failed_day` tag as well, update this to a blank value to delete the tag.

    <Frame>
      <img alt="7 day streak tag updated and exit settings" />
    </Frame>
  </Step>

  <Step title="Optional: Send a 'Congratulations' push notification">
    At this point you may want to congratulate your users via a push notification for completing your 7 day streak before exiting the journey.
  </Step>
</Steps>

<Check>
  That's it - set the Journey live. Your users will enter the journey on day 1 and will progress until they either complete their entire streak or until they have been inactive for a full calendar day. If they are inactive for a full day they will be ejected from the journey early, and depending on your journey settings, may re-enter the journey later.
</Check>

***

## 1-day recurring streak with tags and custom events

**Goal**: Send escalating push reminders throughout the day, using a custom event (`streak_continued`) to detect when the user completes their daily action. As soon as the event fires, the user skips all remaining reminders for that day. If the user doesn't act, they receive up to four reminders spaced 4 hours apart. The cycle resets the next day.

This approach uses a **[custom event](/docs/en/custom-events)** (`streak_continued`) to signal that a user has completed their daily streak action, and **[Wait Until](/docs/en/journeys-actions#wait-until)** nodes to listen for that event between reminders. Unlike the previous examples, this journey doesn't rely on segment-based activity checks: instead, it reacts directly to an event fired by your app.

<Note>
  This journey focuses on **sending reminders**. Your app or backend should handle streak count tracking: incrementing the counter when the user completes their daily action, and resetting it when a day is missed. The journey uses a `streak_count` [tag](/docs/en/add-user-data-tags) on the user profile to personalize messages with [liquid syntax](/docs/en/using-liquid-syntax), so users who are continuing a streak see different copy than users who are starting fresh.
</Note>

### Send the custom event and update streak tags from your app

Each time a user completes their daily streak action (opening the app, finishing a lesson, logging a workout, etc.), send a `streak_continued` custom event to OneSignal **and** update the `streak_count` tag on the user profile:

<Tabs>
  <Tab title="Frontend SDK">
    ```javascript theme={null}
    // Fire the custom event to signal streak completion
    OneSignal.User.trackEvent("streak_continued");

    // Update the streak count tag (your app calculates the value)
    OneSignal.User.addTags({
      streak_count: currentStreakCount.toString()
    });
    ```
  </Tab>

  <Tab title="REST API">
    Fire the custom event via the [Custom Events API](/reference/create-custom-events):

    ```json theme={null}
    {
      "events": [
        {
          "name": "streak_continued",
          "external_id": "USER_EXTERNAL_ID"
        }
      ]
    }
    ```

    Update the tag via the [Update User API](/reference/update-user):

    ```json theme={null}
    {
      "properties": {
        "tags": {
          "streak_count": "5"
        }
      }
    }
    ```
  </Tab>
</Tabs>

When a user misses a day, your app should reset the `streak_count` tag to `0` (or remove it). This ensures the journey's push templates always reflect the correct streak state.

### Create personalized message templates

Use [liquid syntax](/docs/en/using-liquid-syntax) in your push notification templates to show different copy depending on whether the user has an active streak or is starting fresh. This keeps the journey structure simple: a single push node handles both cases.

**Example push template:**

| Field          | Value                                                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title**      | `{% if streak_count and streak_count != "0" %}Keep your streak alive!{% else %}Start a streak today!{% endif %}`                                                          |
| **Message**    | `{% if streak_count and streak_count != "0" %}You're on a {{streak_count}}-day streak. Don't let it end!{% else %}Open the app to start building your streak.{% endif %}` |
| **Launch URL** | `https://yourapp.com/streak`                                                                                                                                              |

Create a separate template for each time slot (8am, 12pm, 4pm, 8pm) so you can vary the tone throughout the day. For example, the morning template can be encouraging while the evening template adds gentle urgency, but each template should include the liquid conditional so it adapts to both streak states.

<Tip>
  **Alternative approach**: If you prefer to manage "continue" and "start" messages as separate templates rather than using liquid syntax, you can add a [Yes/No branch](/docs/en/journeys-actions#yesno-branch) before each push node. Branch on segment membership (e.g., a segment where `streak_count` is greater than `0`) and route each path to a different template. This gives you more visual control in the journey builder but adds extra nodes to the canvas.
</Tip>

### Segments used

| Segment                                      | Filters        | Notes                                                                                |
| -------------------------------------------- | -------------- | ------------------------------------------------------------------------------------ |
| **Total Users** (or your preferred audience) | **No filters** | To include all users in the journey. Replace with a more targeted segment if needed. |

### Journey settings

| Setting            | Configuration                                               |
| ------------------ | ----------------------------------------------------------- |
| **Entry rules**    | **Audience Segment**                                        |
| **Audience**       | Include: `Total Users` (or your preferred audience segment) |
| **Exit rules**     | **They moved through the entire journey**                   |
| **Re-entry rules** | **Yes, after a certain amount of time**: `10 minutes`       |
| **Schedule**       | **Start immediately, never stops**                          |

<Frame>
  <img alt="Journey settings showing Audience Segment entry with Total Users segment included" />
</Frame>

<Frame>
  <img alt="Re-entry rules set to Yes, after 10 minutes" />
</Frame>

<Note>
  Setting re-entry to 10 minutes ensures users re-enter the journey as soon as possible after exiting. Combined with the Time Window as the first step, users will wait at the time window until the next morning before starting a new cycle.
</Note>

### Journey steps

The journey uses **Wait Until** nodes to listen for the `streak_continued` custom event between each reminder. If the event fires at any point, the user follows the **A branch** and skips all remaining reminders for the day. If the event doesn't fire before the expiration, the user receives a push notification and moves to the next Wait Until node.

<Steps>
  <Step title="Add a Time Window node">
    Begin by setting a Time Window node that starts slightly before your first desired reminder time, for example **7:00 AM – 7:15 AM** every day. Enable **Use user's time zone** so the cycle starts at a reasonable local time.

    <Frame>
      <img alt="A time window node for 7:00 AM – 7:15 AM every day" />
    </Frame>

    Users who enter the journey after this window will wait until the next day before the reminder cycle begins. The window starts at 7:00 AM to give the first Wait Until node time to expire before the 8am reminder.
  </Step>

  <Step title="Add a Wait Until node (1-hour expiration)">
    Add a **Wait Until** node with the condition: Custom Event `streak_continued` occurs. Set the **expiration** to `1 hour`.

    * **A branch** (event fires): The user already completed their daily action early in the morning, so they skip all reminders and proceed directly to the exit.
    * **Expire branch** (1 hour, no event): The user hasn't acted yet. Continue to the first push reminder.

    The 1-hour expiration covers the gap between the Time Window (7:00 AM) and the first reminder (\~8:00 AM). This gives users who are already active a chance to trigger the event before any push is sent.

    <Frame>
      <img alt="Wait Until node listening for streak_continued event with 1-hour expiration" />
    </Frame>
  </Step>

  <Step title="Send the 8am Streak Reminder push">
    On the **Expire branch**, add a Push Notification node with your first personalized template (e.g., "8am Streak Reminder"). The liquid syntax in the template will automatically show "Keep your streak alive!" for users with an active streak, or "Start a streak today!" for users starting fresh.

    <Frame>
      <img alt="Push notification node for 8am Streak Reminder" />
    </Frame>
  </Step>

  <Step title="Add a second Wait Until node (4-hour expiration)">
    After the push notification, add another **Wait Until** node with the same condition: Custom Event `streak_continued`. This time, set the **expiration** to `4 hours`.

    * **A branch**: User completed their action after the first reminder. Skip remaining reminders and proceed to the exit.
    * **Expire branch**: No action after 4 hours. Continue to the 12pm reminder.
  </Step>

  <Step title="Send the 12pm Streak Reminder push">
    On the **Expire branch**, add a Push Notification node for your midday reminder (e.g., "12pm Streak Reminder"). Use a different template from the 8am one, but include the same liquid conditional so it adapts to the user's streak state.

    <Frame>
      <img alt="Push notification node for 12pm Streak Reminder" />
    </Frame>
  </Step>

  <Step title="Continue the pattern for afternoon and evening reminders">
    Repeat the **Wait Until (4 hours) → Push Notification** pattern for each additional reminder you want to send. In this example:

    * **Wait Until** (4 hours) → **4pm Streak Reminder** push
    * **Wait Until** (4 hours) → **8pm Streak Reminder** push

    At each Wait Until node, the `streak_continued` event can fire to skip all remaining reminders and jump straight to the exit.

    <Warning>**Don't be repetitive**: Use a different push template for each time slot. Vary the tone and messaging. Morning reminders can be encouraging, while evening reminders can add gentle urgency. Users will tune out identical repeated notifications.</Warning>
  </Step>

  <Step title="Converge all branches to the Exit node">
    All **A branches** (from each Wait Until node where the `streak_continued` event fired) and the final push notification branch should converge at the end of the journey, leading to the **Exit** node.

    <Frame>
      <img alt="Exit node showing re-entry after 10 minutes" />
    </Frame>

    The user exits and re-enters after 10 minutes. Since the Time Window is the first step, they'll wait there until 7:00 AM the next morning before starting a new reminder cycle.
  </Step>
</Steps>

### How the flow works

Here's a walkthrough of a typical day for a user in this journey:

| Time             | User action                              | Journey behavior                                                                    |
| ---------------- | ---------------------------------------- | ----------------------------------------------------------------------------------- |
| 7:00 AM          | -                                        | User passes through Time Window, enters first Wait Until (1-hour expiration)        |
| 7:00–8:00 AM     | No `streak_continued` event              | Wait Until expires → sends **8am Streak Reminder** push                             |
| 8:00 AM–12:00 PM | No event                                 | Wait Until expires (4 hours) → sends **12pm Streak Reminder** push                  |
| 2:30 PM          | User opens app, `streak_continued` fires | Wait Until condition met → user follows A branch, **skips 4pm and 8pm reminders**   |
| -                | -                                        | User exits journey → re-enters after 10 min → waits at Time Window for next 7:00 AM |

If the user never acts, they receive all four reminders (8am, 12pm, 4pm, 8pm), then exit and re-enter the cycle the next day.

<Note>
  The first Wait Until uses a **1-hour expiration** while all subsequent ones use **4 hours**. This is because the Time Window starts at 7:00 AM, so the short first expiration ensures the 8am reminder fires on time. Adjust these values if you change your Time Window start time.
</Note>

<Check>
  That's it. Set the Journey live. Each day, users will be prompted up to four times to complete their daily action, with messaging that automatically adapts based on their streak status. As soon as the `streak_continued` event fires, all remaining reminders are skipped for the day. The cycle resets the next morning at your configured Time Window.
</Check>

***

## Comparison of approaches

|                         | Last session (1-day)   | Last session (7-day)           | Tags + custom events           |
| ----------------------- | ---------------------- | ------------------------------ | ------------------------------ |
| **Complexity**          | Low                    | Medium                         | High                           |
| **Setup required**      | Segment only           | Segment + branching            | SDK/API integration + segments |
| **Personalization**     | Generic messages       | Day-specific messages          | Streak count in messages       |
| **Tracks streak count** | No                     | Implicitly (by day in Journey) | Yes (via tags)                 |
| **Best for**            | Simple daily reminders | Time-limited challenges        | Apps with streak UI/rewards    |
| **Code required**       | None                   | None                           | Yes (events + tag updates)     |

***

## Tips and best practices

* **Don't over-message.** Ensure that you send an appropriate amount of reminders, and use [Time Window](/docs/en/journeys-actions#time-window) nodes to control when messages are sent and avoid interrupting users during off-hours.
* **Use different channels where appropriate.** If your users are subscribed to multiple channels, try experimenting with SMS and Email messages as part of your flow to see if streak retention increases. Note that in-app messages are not appropriate for streak reminders, as the user has to be in the app to see them, and in-app messages in journeys can only be shown to a user once, even if they re-enter the journey.
* **Combine with outcomes.** Track streak completions as [Custom Outcomes](/docs/en/custom-outcomes) to measure the impact of your streak Journeys on retention and engagement.
* **Test your timing.** Experiment with different delivery windows and message frequencies. Use [Split Branch](/docs/en/journeys-actions#split-branch) nodes to A/B test.
* **Reset streaks gracefully.** When a streak breaks, consider sending an encouraging "start a new streak" message rather than a punitive one.

***

## FAQ

### Can I track the actual streak count without tags or custom events?

Not directly. OneSignal's **Last Session** filter tells you *when* a user was last active but does not count consecutive days. For streak counting, use [tags](/docs/en/add-user-data-tags) or [custom events](/docs/en/custom-events) as shown in the third example.

### What happens if a user has multiple subscriptions?

Segment checks evaluate all of a user's subscriptions. If a user has both a mobile and web subscription, activity on *either* device updates their last session time. Assign [External IDs](/docs/en/users) to unify subscriptions under a single user profile.

### Can I reward users for completing a streak?

Yes. At the end of a streak Journey, use a [Tag User](/docs/en/journeys-actions#tag-user) action to mark the user (for example, `streak_7day_complete: true`). Your app can read this tag to unlock rewards, badges, or other incentives. You can also use a [Journey webhook](/docs/en/journeys-webhook) to notify your backend when a user completes the streak.

### How do I prevent users from getting multiple streak reminders in one day?

The combination of **re-entry rules** and **Time Window** nodes handles this. Set re-entry to at least 12 hours and use a single daily time window. This ensures each user receives at most one reminder per day.


# Set up confirmed opt-in for email
Source: https://documentation.onesignal.com/docs/en/double-opt-in-email

Implement double opt-in (confirmed opt-in) for email in OneSignal using Tags, Segments, and Journeys to improve engagement, compliance, and list quality.

A **confirmed opt-in** (also called **double opt-in**) requires new email subscribers to verify their email address by clicking a confirmation link in a follow-up email. This extra step ensures your email subscribers genuinely want to hear from you and protects your sender reputation by filtering out fake, mistyped, and spam-trap addresses before they enter your sending list.

This tutorial sets up a confirmed opt-in workflow using one Tag, one Segment, and one Journey. If you'd rather build the same flow via API, see [Example verification magic link OTP](./example-verification-magic-link-otp).

## Single vs double opt-in

* **Single opt-in**: A user enters their email (e.g., signup form) and is immediately added to your mailing list.
* **Double opt-in (confirmed opt-in)**: After entering their email, the user must click a confirmation link in a verification email before they're added.

### Benefits of double opt-in

* Improves engagement and list quality
* Verifies compliance with **GDPR**, **CAN-SPAM**, and other regulations
* Filters out fake, spam-trap, or mistyped addresses
* Reduces bounce and complaint rates
* Protects against abuse and list bombing

<Note>
  Most professional senders use double opt-in to protect their domain reputation and maximize [deliverability](./email-deliverability).
</Note>

## Prerequisites

Before starting:

* A configured OneSignal Email sending domain — see [Email setup](./email-setup) and [Email DNS configuration](./email-dns-configuration).
* At least one email Subscription marked as a Test User — see [Test Users](./test-users).
* Dashboard access to **Audience > Segments**, **Messages > Templates**, and **Journeys**.

If you already have a list of email subscribers who are confirmed, you can use the [CSV importer](./import) to bulk-set the `confirmed_opt_in` Tag so they bypass the Journey entirely.

## How to create a confirmed opt-in Journey

This setup uses a Tag called `confirmed_opt_in` with a value of `true` or `false` to identify confirmed subscribers.

### 1. Create a segment of users that did not confirm opt-in

Within the OneSignal dashboard, go to **Audience > Segments** and click **New Segment**.

Build a segment called **Did not confirm email opt-in** that uses the following filters with **AND** logic:

* **User Tag** with `confirmed_opt_in` **is not** `true`
* **Device Type** is **Email**
* **Test Users** is true (remove this filter before going live in production)

This segment contains all test users with an email Subscription where `confirmed_opt_in` is set to `false` or is not set.

<Frame>
  <img alt="Segment builder showing the Did not confirm email opt-in segment with three AND filters" />
</Frame>

### 2. Create a confirmed opt-in email template

Navigate to **Messages > Templates > New Email Template** and select **HTML Editor** or **Drag & Drop Editor**.

Design a simple confirmation email:

* Clear subject line (e.g., "Confirm your subscription")
* A single, prominent confirmation CTA ("Confirm Subscription")
* No social media buttons or other CTAs that might distract from the confirmation action

Here's a starter template you can paste into the HTML editor:

```html HTML theme={null}
<!DOCTYPE html>
<html>
  <body style="font-family: Arial, sans-serif; background-color: #f7f7f7; padding: 20px;">
    <table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="max-width: 600px; margin: auto; background: #ffffff; border-radius: 8px; overflow: hidden;">
      <tr>
        <td style="padding: 30px; text-align: center;">
          <h2 style="color: #333;">Please confirm your subscription</h2>
          <p style="color: #555;">We just need to verify your email address before adding you to our list.</p>
          <a href="YOUR_CONFIRMATION_URL"
             style="display: inline-block; padding: 12px 20px; margin-top: 20px; background-color: #007bff; color: #ffffff; text-decoration: none; border-radius: 4px; font-weight: bold;">
             Confirm Subscription
          </a>
          <p style="font-size: 12px; color: #999; margin-top: 30px;">
            If you did not request this, you can safely ignore this email.
          </p>
        </td>
      </tr>
    </table>
  </body>
</html>
```

<Note>
  Replace `YOUR_CONFIRMATION_URL` with the page on your site that thanks the user for confirming their subscription. The Wait Until step in the next section detects clicks on this link, so it must be a tracked URL inside the OneSignal template editor.
</Note>

<Frame>
  <img alt="OneSignal HTML email template editor showing the confirmation email preview" />
</Frame>

Save the template with the name **Confirm email opt-in**. The next section references this template by that name.

### 3. Build a confirmed opt-in Journey

Navigate to **Journeys > New Journey** and select **Start from scratch**.

#### Journey settings

1. **Name**: `Confirm email opt-in` (or any name that helps you recognize this Journey).
2. **Entry rules**: Include the **Did not confirm email opt-in** segment.
3. **Exit rules**: Check **They moved through the entire Journey**.
4. **Re-entry rules**: Select **No, they can receive this only once**.
5. **Schedule**: Select **Start immediately** (or schedule for a later time) and **Never stops**.

Click **Save**.

#### Email message step

Add an **Email** message step and select the **Confirm email opt-in** template.

<Frame>
  <img alt="Journey editor showing the Confirm email opt-in template attached to an Email message step" />
</Frame>

#### Wait Until step

Add a **Wait Until** step and set the Branch A condition to:

* **Previous Message**
* **Confirm email opt-in** template name
* **Clicked**

Check the **Expiration Branch** option and set it to "Wait a maximum of `1 Day` and **Continue Journey**".

<Frame>
  <img alt="Wait Until step configured to wait for a click on the Confirm email opt-in message" />
</Frame>

#### Tag users who confirm

Under the **A (Message Clicked)** branch, add a **Tag User** action and set the Tag to `confirmed_opt_in` with a value of `true`.

<Frame>
  <img alt="Journey editor showing Tag User action setting confirmed_opt_in to true" />
</Frame>

When users click the confirmation button, their `confirmed_opt_in` Tag changes from `false` (or unset) to `true`. You can use this Tag to track which users have confirmed their email subscription.

#### Follow up with non-confirmers

After 1 day, users who did not click the confirmation button go down the **Expire (1 Day)** branch. From there you can repeat the pattern (second confirmation email > Wait Until clicked > Tag if clicked) to give users another chance. Two attempts is a good baseline; three is usually the upper limit before it feels like nagging.

<Frame>
  <img alt="Complete confirmed opt-in Journey with email step, Wait Until, tag action, and a follow-up branch" />
</Frame>

### 4. Test the Journey

The Journey is now ready to test. Because the Segment uses the **Test Users** filter, only emails marked as Test Users will receive the confirmation message. To add more test addresses, see [Import emails](./import) and [Test Users](./test-users).

<Steps>
  <Step title="Set the Journey live">
    Click **Set Live** in the Journey.
  </Step>

  <Step title="Receive the confirmation email">
    Wait a few minutes — you should receive the confirmation email at your test address.
  </Step>

  <Step title="Click the confirmation button">
    Click the button in the email and wait a few more minutes for the click to register.
  </Step>

  <Step title="Verify the Tag">
    Check the user profile in **Audience > Users**. You should see `confirmed_opt_in=true` and the user should have exited the Journey.
  </Step>
</Steps>

#### Troubleshooting

If you did not receive the confirmation email after a few minutes:

1. Navigate back into the active Journey.
2. Click the first Email step.
3. Select **Audience Activity** at the top left. See [Journey analytics](./journeys-analytics) for more details.
4. You should see your email in the **Delivered** column. If it's not there, check that your email address is Subscribed and matches the Segment criteria.

If you received the email and clicked the button but the Tag did not update after a few minutes:

1. Navigate to **Audience > Users**.
2. Search for your email address.
3. Check the **Tags** column. You should see `confirmed_opt_in=true` if the Journey worked correctly.

<Info>
  Still need help? Email `support@onesignal.com` with:

  * The email address that you are testing.
  * A link to the Journey (copy the URL from your browser address bar).
  * Any additional information that may be helpful.
</Info>

### 5. Set live in production

When you're ready to send to actual users:

<Steps>
  <Step title="Stop and archive the test Journey">
    Navigate to the Journey and click **More Options > Stop + Archive**.
  </Step>

  <Step title="Duplicate the segment">
    Navigate to the Segment and click **Options > Pause**, then **Options > Duplicate**.
  </Step>

  <Step title="Remove the Test Users filter">
    Update the duplicated Segment to remove the **Test Users** filter, then save.
  </Step>

  <Step title="Duplicate the Journey">
    Navigate back to the Journeys page and click **Options > Duplicate** on the test Journey.
  </Step>

  <Step title="Point the Journey at the production segment">
    Update the duplicated Journey to use the segment without the Test Users filter, then save.
  </Step>

  <Step title="Set live">
    Click **Set Live** when you're ready to roll out to all users.
  </Step>
</Steps>

<Check>
  Subscribers who confirm now carry the `confirmed_opt_in=true` Tag, which you can use for segmentation and to ensure you only message verified users.
</Check>

## FAQ

### Is double opt-in required by GDPR or CAN-SPAM?

**GDPR** requires explicit consent, which double opt-in provides cleanly. **CAN-SPAM** does not strictly require it, but using double opt-in reduces complaint rates and helps you store proof of consent (timestamp + source). Always log the confirmation event for compliance audits.

### Do existing email subscribers need to re-confirm?

No — for users you already trust as confirmed, use the [CSV importer](./import) to bulk-set `confirmed_opt_in=true` so they bypass the confirmation Journey entirely.

### What should my confirmation email look like?

Keep it plain and short. Use a clear subject line ("Confirm your subscription"), a single confirmation CTA, and avoid heavy images, marketing content, or extra links. Make sure your sending domain has SPF, DKIM, and DMARC configured — see [Email DNS configuration](./email-dns-configuration).

### How can I improve confirmation rates?

Show a thank-you page after signup that explains the upcoming confirmation step. Use a benefit-led subject line ("One last step: confirm your subscription"). Send 2–3 reminders maximum — more becomes nagging. If you're sending from a new domain, [warm it up](./email-warm-up) before launching at scale.

### Why aren't my confirmation links tracking?

Make sure the button uses a tracked link generated by the OneSignal template editor — raw external URLs won't fire click events. If users click through but the Tag isn't applied, verify the Wait Until step is set to **Previous Message** **Clicked** and that the **Tag User** action sits on the click branch, not the expiration branch.

### Why aren't users confirming?

Confirmation emails sometimes land in spam or promotions. Encourage users on your post-signup thank-you page to check those folders. Follow the [email reputation best practices](./email-reputation-best-practices) to keep your sender reputation high enough to land in the inbox.

### What happens to users who never click the confirmation link?

After the Wait Until step expires (1 day in this tutorial), users go down the expiration branch. Send one or two follow-up confirmations, then exclude them from your primary segments — they remain unconfirmed and shouldn't receive marketing email.

## Related pages

<Columns>
  <Card title="Email deliverability" icon="envelope" href="./email-deliverability">
    How sender reputation, list hygiene, and inbox placement work together to land in the inbox.
  </Card>

  <Card title="Email reputation best practices" icon="shield-check" href="./email-reputation-best-practices">
    Opt-in, monitoring, frequency, warm-up, and list-hygiene recommendations.
  </Card>

  <Card title="Email warm-up" icon="fire" href="./email-warm-up">
    Ramp volume on a new sending domain without hurting deliverability.
  </Card>

  <Card title="Email setup and compliance" icon="gear" href="./email-setup">
    Configure your sending domain and meet legal sending requirements.
  </Card>

  <Card title="Journeys actions" icon="route" href="./journeys-actions">
    Wait Until branches, Tag actions, and other Journey building blocks.
  </Card>

  <Card title="Magic Link OTP example" icon="link" href="./example-verification-magic-link-otp">
    Build the same confirmation flow programmatically via the OneSignal API.
  </Card>
</Columns>


# Ecommerce strategies
Source: https://documentation.onesignal.com/docs/en/ecommerce-strategies

Implementation hub for ecommerce messaging — customer IDs, RFM Tags, browse and purchase Custom Events, segments, and Journey playbooks for cart recovery, loyalty, and re-engagement.

An ecommerce messaging strategy targets sites and apps where success depends on conversion of browsers to buyers, repeat purchase frequency, and customer lifetime value. If you sell products online — direct-to-consumer, marketplace, or subscription commerce — this guide is for you.

This page is the implementation hub: which customer identifier to set, what browse and purchase data to capture, which segments to build, and which Journeys drive cart recovery, post-purchase engagement, and win-back. Each section links to the canonical docs for deeper detail.

## Implementation roadmap

This guide assumes you have already integrated the OneSignal [Mobile SDK](./mobile-sdk-setup) and/or [Web SDK](./web-sdk-setup).

<Steps>
  <Step title="Unify customer identity across devices">
    Set a stable customer identifier on every authenticated shopper so push, email, and SMS tie to one profile across reinstalls and devices. [Jump to section](#identify-your-customers-with-external-ids).
  </Step>

  <Step title="Track customer state and lifetime value">
    Start with `customer_status`, `total_spend_cents`, and `last_purchase_date` as Tags. These three power every RFM (recency, frequency, monetary) segment. [Jump to section](#tags).
  </Step>

  <Step title="Capture browse, cart, and purchase moments">
    Fire `product_viewed`, `product_added_to_cart`, `checkout_started`, and `checkout_completed` as Custom Events from your storefront or backend. [Jump to section](#custom-events).
  </Step>

  <Step title="Group shoppers by lifecycle stage">
    Build audiences such as Cart abandoners, First-time buyers, Repeat customers, VIPs, and Lapsed customers. [Jump to section](#segments).
  </Step>

  <Step title="Automate cart recovery, loyalty, and win-back">
    Build Welcome, cart recovery, post-purchase, loyalty, and win-back Journeys against your segments. [Jump to section](#journey-examples).
  </Step>
</Steps>

## Identify your customers with External IDs

Every Journey downstream depends on a stable customer identifier. Without one, mobile browse activity disconnects from a desktop purchase, cart recovery fires to ghost profiles, and lifetime-value analytics undercount your best customers. External IDs preserve identity across installs and tie push, email, and SMS to one customer profile. Use the unique identifier from your commerce platform — for example, your Shopify Customer ID, an Auth0 `uid`, or your internal `customer_id`.

Set the External ID at signup, on every login, on order placement, and on session resume. The OneSignal SDK does not assign it for you, and assigning it late or sporadically breaks attribution between browse activity, cart events, and downstream purchases — making conversion and retention analytics unreliable.

For anonymous shoppers (the majority of ecommerce traffic), the OneSignal-assigned anonymous user ID still ties Tags and behavior to a Subscription. Promote anonymous profiles to authenticated profiles by setting the External ID the moment a shopper logs in or completes checkout — that single call merges the anonymous browse history with the new identity.

<Card title="External ID setup" icon="id-card" href="./users#external-id">
  Assign a unique customer identifier so browse history, cart state, and notifications follow the customer across devices.
</Card>

## Recommended data

Tags and Custom Events are the raw material every Journey uses to decide *who* to message and *when*. Tags persist on the customer profile (current state); Custom Events record discrete moments (what just happened). Use both — Tags drive RFM segmentation and personalization, Custom Events trigger Journey entry and Wait Until conditions.

Ecommerce leans heavily on Custom Events because most lifecycle moments are behavioral: a product view, a cart add, a checkout start, a purchase. Tags capture the resulting state — total spend, purchase count, customer tier — which Journeys filter on for loyalty and retention messaging.

### Tags

Tags answer *"who is this customer right now?"* — they hold the lifecycle state, lifetime value, recency, and category preferences that segments filter on. Set them whenever customer state changes. For boolean-style signals, set the Tag to `1` when true and **remove it** when false — segment with "tag exists" rather than storing `0`/`false` values.

<Tip>
  If you only set up four Tags, start with `customer_status`, `total_spend_cents`, `last_purchase_date`, and `first_name`. They power every RFM-based Journey.
</Tip>

#### Customer lifecycle and value

| Tag                  | Values                                                                 | Use                                                                                                                  |
| :------------------- | :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| `customer_status`    | `prospect` / `first_time_buyer` / `repeat_customer` / `vip` / `lapsed` | Lifecycle state — drives Journey entry, exit, and audience filters.                                                  |
| `loyalty_tier`       | `bronze` / `silver` / `gold` / `platinum` (your tiers)                 | Tailor offers, perks, and exclusivity by tier.                                                                       |
| `total_spend_cents`  | integer (as string)                                                    | Lifetime value. Powers VIP and high-spender segments.                                                                |
| `purchase_count`     | integer (as string)                                                    | Frequency signal. Combine with `total_spend_cents` and `last_purchase_date` for RFM scoring.                         |
| `last_purchase_date` | Unix timestamp (seconds)                                               | Recency. Use [time operators](./time-operators) to send win-back offers a fixed number of days after the last order. |

#### Browse and cart

| Tag                 | Values                                     | Use                                                                                                                                                                                                                                                                                               |
| :------------------ | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cart_value_cents`  | integer (as string)                        | Current cart subtotal. Personalize cart-recovery copy with the actual value at risk.                                                                                                                                                                                                              |
| `cart_item_count`   | integer (as string)                        | Number of items in the active cart. Useful for "you have N items waiting" messaging.                                                                                                                                                                                                              |
| `wishlist_count`    | integer (as string)                        | Engagement signal. Wishlist activity often outperforms cart adds as a purchase predictor.                                                                                                                                                                                                         |
| `favorite_category` | string (e.g., `apparel`, `home`, `beauty`) | Single most-shopped category. Personalize subject lines, push copy, and product recommendations.                                                                                                                                                                                                  |
| `cat_<category>`    | `1` (set when shopped)                     | One Tag per category for stores with broad catalogs (e.g., `cat_apparel`, `cat_home`, `cat_beauty`). Use when shoppers regularly buy across multiple categories — `favorite_category` alone can't express multi-interest. Set automatically from `product_viewed` or `purchase_completed` events. |

#### Subscription commerce (subscribe-and-save)

Use these Tags only if you offer subscribe-and-save, replenishment, or other recurring-shipment programs. Skip the subsection for one-time-purchase stores.

| Tag                          | Values                                       | Use                                                                                                                      |
| :--------------------------- | :------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
| `subscribe_save_active`      | `1` (set when an active subscription exists) | Lifecycle filter for subscription-aware messaging; suppress one-off promotions for the same SKU.                         |
| `next_replenishment_date`    | Unix timestamp (seconds)                     | Drive pre-shipment reminders ("ships in 3 days") and skip-window outreach. Pair with [time operators](./time-operators). |
| `replenishment_cadence_days` | integer (as string, e.g., `30`, `60`, `90`)  | Personalize copy with the customer's chosen cadence and detect cadence-mismatched usage.                                 |

#### Personalization and source

| Tag                   | Values                                            | Use                                                                                                                                                                               |
| :-------------------- | :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `first_name`          | string                                            | Personalize message content (e.g., `Hi {{ first_name \| default: 'there' }}`).                                                                                                    |
| `preferred_locale`    | string (e.g., `en-US`, `fr-CA`)                   | Drive locale-aware content and localized message variants.                                                                                                                        |
| `email_signup_source` | `popup` / `checkout` / `account` / `referral`     | Where the customer entered their email (form they filled). Tailor welcome copy to the surface that captured the address.                                                          |
| `acquisition_source`  | `paid_social` / `organic` / `referral` / `direct` | First-touch channel that brought the customer to your store. Tune onboarding to the acquisition channel — distinct from `email_signup_source` which is the on-site capture point. |

<Card title="Add user data tags" icon="tags" href="./add-user-data-tags">
  Add key-value pairs to customer profiles for segmentation and personalization.
</Card>

### Custom Events

Custom Events answer *"what just happened?"* — they're how Journeys react in real time. A cart-recovery Journey can't trigger without `checkout_started`; a thank-you push can't fire without `purchase_completed`. Send a Custom Event for each shopper action you want to react to. Events are stored shorter-term than Tags but can carry properties (product ID, variant, price, currency, cart contents), making them ideal for Journey entry triggers, Wait Until conditions, and Liquid personalization. Use lowercase `snake_case` for event names and keep them consistent across your storefront, backend, and any platform integrations.

The events below match the ones the [Shopify Vendo integration](./shopify#client-side-events) sends automatically — align with these names even on custom storefronts so your Journeys port cleanly between platforms.

| Event                                       | Use case                                                                                                                                                                                |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signup_completed`                          | Welcome Journey entry.                                                                                                                                                                  |
| `product_viewed`                            | Browse-abandonment Journey entry; build behavioral interest profile via properties.                                                                                                     |
| `collection_viewed`                         | Category-level interest signal.                                                                                                                                                         |
| `search_submitted`                          | Intent signal — surface relevant products in next session.                                                                                                                              |
| `product_added_to_cart`                     | Cart-recovery Journey priming step.                                                                                                                                                     |
| `product_removed_from_cart`                 | Down-weight cart urgency or exit a cart Journey for that product.                                                                                                                       |
| `cart_viewed`                               | Active-shopping signal; useful as a Wait Until anchor.                                                                                                                                  |
| `checkout_started`                          | **Cart-recovery Journey entry**. Pair with a Wait Until on `checkout_completed` to detect abandonment.                                                                                  |
| `checkout_completed` / `purchase_completed` | Exit cart-recovery Journey; trigger post-purchase Journey. Carries order ID, total, and items.                                                                                          |
| `payment_failed`                            | Declined-card recovery Journey entry. Carry `failure_reason` (e.g., `card_declined`, `insufficient_funds`) as a property for tailored copy and a quick retry path.                      |
| `order_shipped` / `order_delivered`         | Transactional updates — send via the [Transactional messages API](./transactional-messages).                                                                                            |
| `refund_requested` / `return_initiated`     | Service-recovery Journey trigger; suppress upsell and review-request copy while the return is open.                                                                                     |
| `review_submitted`                          | Post-purchase satisfaction signal; use to gate referral and UGC asks.                                                                                                                   |
| `loyalty_points_earned`                     | Update progress messaging ("250 points to next reward"). Carry `points` and `running_balance` as properties.                                                                            |
| `loyalty_tier_upgraded`                     | Tier-celebration Journey entry. Carry `previous_tier` and `new_tier` as properties for personalized copy.                                                                               |
| `back_in_stock`                             | Backend-fired event that triggers a wishlist-targeted alert Journey.                                                                                                                    |
| `price_drop`                                | Backend-fired event mirroring `back_in_stock`. Targets customers with the product on their wishlist or recently viewed. Carry `product_id`, `old_price`, and `new_price` as properties. |
| `subscribe_save_started`                    | *(Subscription commerce only.)* Onboarding Journey entry for new subscribe-and-save customers.                                                                                          |
| `replenishment_skipped`                     | *(Subscription commerce only.)* Churn-risk signal — trigger a save Journey before the next billing date.                                                                                |
| `replenishment_processed`                   | *(Subscription commerce only.)* Confirm shipment, surface upsells for complementary SKUs, and reset the cadence-reminder Journey.                                                       |
| `subscribe_save_cancelled`                  | *(Subscription commerce only.)* Win-back Journey entry — separate from one-off `subscription_cancelled` flows.                                                                          |

<Card title="Custom Events" icon="bolt" href="./custom-events">
  Capture shopper actions and use them to trigger Journeys or Wait Until steps.
</Card>

### Segments

Segments turn the data you've collected into messaging audiences. Without them, every send is a broadcast — with them, cart abandoners get recovery, VIPs get launch invites, and lapsed shoppers get win-back offers, automatically. Combine Tags and Custom Events into the ten starter segments below.

| Segment                  | Definition                                                                                                                                                                                      |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New visitors             | `First Session < 7 days ago` AND `purchase_count` does not exist. Welcome and first-purchase target.                                                                                            |
| Cart abandoners          | `checkout_started` in the last 24 hours AND `checkout_completed` does not exist in the same window. Highest-leverage recovery segment.                                                          |
| Browsers (no purchase)   | `product_viewed` in the last 30 days AND `purchase_count` does not exist. Long-tail conversion target.                                                                                          |
| First-time buyers        | `purchase_count = "1"`. Onboarding into the loyalty Journey, second-purchase incentive target.                                                                                                  |
| Repeat customers         | `purchase_count > 1`. Cross-sell and category-expansion target.                                                                                                                                 |
| High-frequency loyalists | `purchase_count >= 5` in the last 90 days. Surfaces frequent shoppers at lower price points (consumables, beauty, replenishment categories) — distinct from spend-based VIPs.                   |
| VIPs / High-spenders     | `customer_status = "vip"` OR `total_spend_cents > 50000` (your threshold in cents). Premium offer audience.                                                                                     |
| At-risk repeat customers | `purchase_count > 1` AND `last_purchase_date` between 30 and 60 days ago. Catches early signs of lapse before the 90-day Lapsed bucket — win-back copy lands much better at 45 days than at 90. |
| Lapsed customers         | `last_purchase_date > 90 days ago` AND `customer_status != "vip"`. Win-back audience.                                                                                                           |
| Wishlist holders         | `wishlist_count > 0`. High-intent for back-in-stock and price-drop alerts.                                                                                                                      |

<Note>
  Mature ecommerce setups run 30+ segments split by category, geography, loyalty tier, channel, and seasonality. Start with the ten above plus a segment per top-level category, then add depth (predicted LTV bucket, return-rate cohort, last-channel-clicked) as your Journeys grow.
</Note>

<Card title="Segmentation" icon="users" href="./segmentation">
  Group customers by shared characteristics to target Journeys and campaigns.
</Card>

## Journey examples

Journeys are where the data and segments turn into revenue. With Tags, Custom Events, and segments in place, build Journeys against them. Ecommerce Journeys mix channels by intent — push and in-app for time-sensitive nudges (cart recovery, back-in-stock, flash sales), email for receipts, recommendations, and longer-form recovery, and SMS for high-value moments like VIP launches and order updates.

Most ecommerce customers move through five lifecycle stages, with a different Journey driving each transition:

```mermaid theme={null}
flowchart LR
    A[Prospect] -->|Welcome| B[First-time buyer]
    B -->|Post-purchase| C[Repeat customer]
    C -->|Loyalty| D[VIP]
    C -. 90+ days inactive .-> E[Lapsed]
    E -. Win-back .-> C
```

The lifecycle has six core Journey flows:

<Columns>
  <Card title="Welcome and first purchase" icon="hand-wave" href="./mobile-first-journeys#welcome-journeys">
    Drive a new shopper from signup to their first checkout with a graduated nudge cadence.
  </Card>

  <Card title="Abandoned cart recovery" icon="cart-shopping" href="./abandoned-cart">
    End-to-end Wait Until tutorial for `checkout_started` → `checkout_completed` recovery.
  </Card>

  <Card title="Post-purchase and cross-sell" icon="circle-check" href="./event-driven-journeys">
    Receipt, shipping updates, review request, and timed cross-sell on `purchase_completed`.
  </Card>

  <Card title="Loyalty and tier upgrades" icon="trophy" href="./event-driven-journeys">
    Reward tier transitions and milestone purchases with VIP-only offers.
  </Card>

  <Card title="Win-back for lapsed customers" icon="rotate-left" href="./mobile-first-journeys#retention-journeys">
    Re-engage shoppers who haven't purchased in 90+ days with category-aware comeback offers.
  </Card>

  <Card title="Back-in-stock alerts" icon="bell" href="./back-in-stock-alerts">
    Restock alerts via push, email, or SMS — choose SKU-keyed tags with the Create Message API or Custom Events with a Journey.
  </Card>
</Columns>

### Common ecommerce patterns

* **Cart recovery is the highest-leverage Journey.** Most cart abandoners still intend to purchase — they just need a reminder. Build a [Wait Until](./journeys-actions#wait-until) on `checkout_completed` after `checkout_started`, with a 30-minute first-touch and a 24-hour follow-up. See the [Abandoned cart tutorial](./abandoned-cart) for the full implementation.
* **Personalize with cart contents using Liquid.** Cart-recovery and browse-abandonment messages pull dramatically higher CTR when they reference the actual product. Use [Custom Event personalization](./personalization-custom-event) to inject `{{ product_name }}` and `{{ product_image_url }}` from the `product_added_to_cart` event payload — see [Liquid syntax](./using-liquid-syntax).
* **Treat post-purchase as both transactional and marketing.** Order confirmations, shipping updates, and delivery alerts are transactional — send via the [Transactional messages API](./transactional-messages) so they bypass marketing-consent gates. Cross-sell, review requests, and refill prompts are marketing — send through standard Journeys with marketing-consent filters.
* **RFM-based win-back, not blanket discounts.** A 90-day-lapsed VIP needs different copy and incentive than a 90-day-lapsed first-time buyer. Build separate win-back Journeys per `customer_status` × `loyalty_tier` cell so your highest-LTV customers don't get the same 10%-off email as a one-time clearance shopper.
* **Wishlist + back-in-stock is an underused loop.** Track wishlist additions as a Tag (`wishlist_count`) and per-product Custom Events. When inventory returns, fire `back_in_stock` from your backend with the `product_id` as a property and target only the customers with that product on their wishlist. Conversion rates are often the highest in your messaging program. For an explicit per-SKU "Notify me when available" pattern, see the [Back-in-stock alerts tutorial](./back-in-stock-alerts).
* **Quiet hours and frequency caps matter more in ecommerce.** Promotional fatigue compounds fast. Apply Journey-level frequency caps (e.g., at most one promo push per 24 hours per customer) and use [Time Window](./journeys-actions#time-window) to keep sends inside reasonable hours in the customer's local timezone.

Measure success by these metrics — not just opens or CTR:

<Columns>
  <Card icon="cart-shopping">
    **Cart-recovery rate** — `checkout_completed` after `checkout_started` within the recovery window
  </Card>

  <Card icon="repeat">
    **Repeat-purchase rate** at 30 / 60 / 90 days from first purchase
  </Card>

  <Card icon="dollar-sign">
    **Average order value (AOV)** trend over time
  </Card>

  <Card icon="chart-line">
    **90-day customer LTV** by acquisition cohort
  </Card>
</Columns>

## FAQ

### How is this different from the Mobile-first strategy?

[Mobile-first](./mobile-first) targets subscription, freemium, and trial-driven apps where success is measured by trial-to-paid conversion. Ecommerce overlaps on the data foundation (External IDs, Tags, Custom Events, segments) but the conversion moment is a transaction (or repeat transaction), not a trial flip. The lifecycle is shaped around RFM segmentation and Wait-Until-based recovery flows rather than time-based trial sequences.

### Should I use a Tag or a Custom Event for cart state?

Use **Custom Events** for cart actions (`product_added_to_cart`, `checkout_started`, `checkout_completed`) — they carry the cart contents and are the right fit for Journey entry and Wait Until conditions. Use a **Tag** (`cart_value_cents`, `cart_item_count`) for the resulting state when you want to personalize copy with the current cart total or filter segments by cart presence. Both work together.

### How do I prevent cart-recovery messages from sending after a purchase?

Use a [Wait Until](./journeys-actions#wait-until) step on `checkout_completed` with [Event Matching](./journeys-actions#event-matching) on a shared property like `cart_id` or `customer_id` — the event branch fires the moment the same customer completes the matching cart, exiting them from the recovery Journey before any reminder sends. The [Abandoned cart tutorial](./abandoned-cart) shows the full configuration.

### How long should my cart-recovery window be?

A 30-minute first touch and a 24-hour follow-up convert most recoverable carts. Push past 48 hours and you're generally wasting opt-in — abandoners who haven't returned by then either bought elsewhere or weren't ready to buy. Stage the cadence by channel: push or in-app for the first nudge (lowest friction), email for the 24-hour follow-up (more space to surface the cart contents and recommendations), and SMS only for high-value carts where you have explicit consent.

### How do I handle returned and refunded orders in segmentation?

Decrement `total_spend_cents` and `purchase_count` on `refund_processed`, or maintain a parallel `lifetime_spend_net_cents` Tag if you want gross spend for analytics and net spend for segmentation. Without this, a customer with one $500 return registers as a repeat $500 customer who will never buy again — they pollute Lapsed and VIP segments. Also fire `refund_requested` to suppress upsell and review-request copy while the return is open.

### What about sending transactional order updates?

Order confirmations, shipping notices, and delivery updates should send via the [Transactional messages API](./transactional-messages) — these are time-sensitive, don't require marketing consent, and shouldn't be subject to marketing-frequency caps. Keep them separate from your promotional Journey infrastructure.

### Can I run this without a Shopify or commerce-platform integration?

Yes. The [Custom Events](./custom-events) and [Tags](./add-user-data-tags) APIs accept the same data from any storefront — custom builds, headless commerce, or other platforms. The [Vendo Shopify integration](./shopify) automates the wiring; for other platforms, instrument the events listed above on your storefront and order-management system.

### How do I handle international stores with different currencies?

Track money values in the smallest unit of a single base currency in `total_spend_cents` and `cart_value_cents` (typically USD cents) and convert at display time using a `preferred_locale` or `currency_code` Tag. This keeps RFM segmentation consistent across regions while letting Liquid personalization render the localized currency in copy.

### How does this guide work for subscribe-and-save and replenishment commerce?

Use the ecommerce Tags and events as the foundation, plus the Subscription commerce Tags (`subscribe_save_active`, `next_replenishment_date`, `replenishment_cadence_days`) and events (`subscribe_save_started`, `replenishment_skipped`, `replenishment_processed`, `subscribe_save_cancelled`) listed above. Subscription messaging blends ecommerce patterns (cart, browse, post-purchase) with mobile-first patterns (renewal reminders, churn-risk Journeys) — see [Mobile-first strategies](./mobile-first) for the recurring-revenue side, especially the renewal-window and at-risk subscriber Journeys.

## Related pages

<Columns>
  <Card title="Abandoned cart tutorial" icon="cart-shopping" href="./abandoned-cart">
    End-to-end Wait Until Journey for `checkout_started` → `checkout_completed` recovery.
  </Card>

  <Card title="Shopify integration" icon="bag-shopping" href="./shopify">
    Vendo integration that auto-syncs the customer Tags and Custom Events recommended in this guide.
  </Card>

  <Card title="Mobile-first lifecycle Journeys" icon="route" href="./mobile-first-journeys">
    Welcome and retention Journey patterns adaptable to ecommerce onboarding and win-back.
  </Card>

  <Card title="Event-driven Journeys" icon="bolt" href="./event-driven-journeys">
    Trigger Journeys from `purchase_completed`, `back_in_stock`, and other commerce events.
  </Card>

  <Card title="Transactional messages" icon="bell" href="./transactional-messages">
    Send order receipts, shipping updates, and delivery alerts through the API.
  </Card>

  <Card title="Personalization with Custom Events" icon="wand-magic-sparkles" href="./personalization-custom-event">
    Inject product names, images, and prices into messages from event payloads.
  </Card>

  <Card title="Back-in-stock alerts" icon="boxes-stacked" href="./back-in-stock-alerts">
    Notify wishlist and recently-viewed customers when out-of-stock products return.
  </Card>

  <Card title="Flash sales and Black Friday" icon="bullhorn" href="./flash-sale">
    Drive urgency with time-limited sale campaigns across push, email, and SMS.
  </Card>

  <Card title="Loyalty Journey" icon="trophy" href="./loyalty-journey">
    Notify customers of points balances and unlocked rewards to drive repeat purchases.
  </Card>
</Columns>


# Event-driven Journeys
Source: https://documentation.onesignal.com/docs/en/event-driven-journeys

Design Journeys that respond to user behavior using Custom Events as entry rules, Wait Until conditions, exit rules, and message personalization sources.

Event-driven Journeys turn user behavior into automated messaging. Instead of waiting on the clock or relying on broad segment membership, the Journey reacts the moment a user performs a specific action. This guide shows you how to wire Custom Events into Journeys cleanly so your automation stays accurate as you scale.

This guide builds on [Custom Events](./custom-events) for sending events and [Personalize with Custom Events](./personalization-custom-event) for the full Liquid reference. The focus here is choosing the right event-to-Journey shape for the behavior you're modeling.

## Prerequisites

* A OneSignal app sending [Custom Events](./custom-events) via SDK or the [Create Custom Events API](/reference/create-custom-events)
* Familiarity with [Journey settings](./journeys-settings) and [Journey actions](./journeys-actions)
* One or more messaging channels configured (push, email, SMS, or in-app)

## Where Custom Events fit in a Journey

A single Custom Event can drive a Journey in three different places. Picking the right slot is the first design decision.

| If the event represents...                                               | Use it as...                                  | Reference                                                                                              |
| ------------------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| The starting moment of an experience (signup, purchase, completion)      | Entry rule                                    | [Custom Event entry rules](./journeys-settings#custom-events)                                          |
| The expected next step inside an in-progress Journey                     | Wait Until condition                          | [Wait Until](./journeys-actions#wait-until)                                                            |
| A signal the user is no longer eligible (cancelled, refunded, opted out) | Exit rule                                     | [Exit when Custom Event condition occurs](./journeys-settings#exit-when-custom-event-condition-occurs) |
| A repeating triggering action (cart updated, plan changed)               | Both entry and exit, with the same event name | [Same-event entry and exit](./journeys-settings#exit-when-custom-event-condition-occurs)               |

Reusing the same event name on both entry and exit lets the latest trigger replace any in-progress instance — useful for Journeys that should always reflect the most recent state (e.g., a cart-recovery Journey that always operates on the latest `cart_updated` payload, not a stale one from yesterday).

<Note>
  Each Journey instance stores the events that triggered entry and matched any Wait Until step. Those events become available to message templates as `journey.first_event`, `journey.last_event`, and `journey.event.EVENT_NAME`. Each instance can store up to **100 event properties per user** (oldest dropped). See [Event property storage rules](./personalization-custom-event#event-property-storage-rules).
</Note>

## Design events for Journey use

The shape of your events determines how clean your Journey logic stays. A few rules of thumb pay off as automation grows.

### Naming

* Use **snake\_case** for event names and property keys so they read predictably.
* Use a **past-tense verb phrase** for the action: `lesson_completed`, `cart_updated`, `payment_failed`. Past tense is unambiguous; it describes something that already happened.
* Keep event names **stable**. Renaming an event after Journeys depend on it silently breaks every reference. Add new event names; don't rename old ones.
* Prefer **specific names over umbrella names**. `subscription_cancelled` and `subscription_paused` produce cleaner Journey logic than a single `subscription_changed` event with a `status` property.

### Property design

Include properties when you'll actually use them, for personalization, branching, or filtering. Skip properties just because they're available. Useful categories:

* **Identifiers** for matching across events: `order_id`, `workspace_id`, `course_id`. These are what Wait Until's [Event Matching](./journeys-actions#event-matching) keys on.
* **Display values** for templates: `product_name`, `price`, `image_url`. These render directly inside messages.
* **Branching values** for filters: `plan_tier`, `is_first_purchase`, `payment_method`.
* **Numeric values** for entry rule property filters: `amount`, `quantity`, `score`.

### Data types

Pick the right type up front. Journey filters and Liquid behave differently across types.

| Type                | Use when                                         | Example                    |
| ------------------- | ------------------------------------------------ | -------------------------- |
| String              | Categorical or identifier values                 | `"premium"`, `"prod_3342"` |
| Number              | Values you'll filter or compare                  | `49.99`, `12`              |
| Boolean             | Binary flags                                     | `true`, `false`            |
| Datetime (ISO 8601) | Time-of-event values used in Liquid date filters | `"2025-04-30T14:22:00Z"`   |
| Array               | Repeating items rendered with for-loops          | `["push", "email"]`        |

<Warning>
  Sending numbers as strings is the most common Journey filter bug. Numeric comparisons like `>`, `<`, and `>=` require numbers. A `price: "49.99"` will not match `price > 25`. Always send numbers as numbers.
</Warning>

### What to avoid

* **PII in properties.** Names, emails, phone numbers, payment details, and sensitive health or auth data should not travel inside event properties. Use anonymized internal identifiers instead.
* **Properties you don't reference.** They eat into the 2024-byte event payload limit and clutter analytics. See [Custom Event structure](./custom-events#custom-event-structure).
* **Inconsistent naming across events.** `productId` in one event and `product_id` in another will silently break Wait Until's Event Matching.
* **Firing the same event from both the SDK and a backend webhook.** A common Journey-doubling bug — the mobile SDK fires `purchase_completed` from the client *and* a Stripe webhook fires it server-side, so every purchase triggers two Journey entries. Pick a single source of truth, or deduplicate using the [`idempotency_key` field](./custom-events#custom-event-structure) on the API.

<Warning>
  Verify your event source map before turning a Journey live. The most common cause of "users are getting two of every message" is the same event firing from two places.
</Warning>

## Pattern 1: React in real time with an entry trigger

Use this pattern when the event itself is the moment you want to message the user. The Journey enters, sends one or two personalized messages immediately, and exits.

**Use it for:**

* Order or appointment confirmations
* Course or task completions
* Account creation, plan upgrades

### Example: Course completion celebration

A learning app fires `course_completed` whenever a user finishes a course. The Journey congratulates them and surfaces what to take next.

Event payload:

```json JSON theme={null}
{
  "name": "course_completed",
  "properties": {
    "course_id": "intro_to_python",
    "course_title": "Intro to Python",
    "completion_score": 92,
    "next_course_title": "Python for Data Analysis",
    "next_course_url": "https://example.com/courses/python-for-data-analysis"
  },
  "external_id": "user_12345",
  "timestamp": "2025-04-30T18:42:00Z"
}
```

<Steps>
  <Step title="Set the Journey entry rule">
    In **Journey settings**, under **Entry rules**, choose **Custom events** and set the event name to `course_completed`. Leave **Filter by property** unset so every completion enters the Journey. See [Custom event entry rules](./journeys-settings#custom-events).
  </Step>

  <Step title="Add a celebration push step">
    Reference the event payload directly with Liquid:

    ```liquid Liquid theme={null}
    You finished {{ journey.first_event.properties.course_title | default: "your course" }}! Score: {{ journey.first_event.properties.completion_score }}/100. Ready for what's next?
    ```
  </Step>

  <Step title="Add a follow-up email">
    Recommend the next course using the event's recommendation properties.

    **Subject:** Up next: `{{ journey.first_event.properties.next_course_title }}`

    **Body excerpt:**

    ```liquid Liquid theme={null}
    You earned {{ journey.first_event.properties.completion_score }}/100 in {{ journey.first_event.properties.course_title }}. Keep your streak going. Start {{ journey.first_event.properties.next_course_title }} now.
    ```

    Set the call-to-action button URL to `{{ journey.first_event.properties.next_course_url }}`.
  </Step>
</Steps>

**Why this works.** The event payload carries everything the messages need. There's no segment lookup, no follow-up event, and no branching. The Journey is a personalization wrapper around a single triggering moment.

## Pattern 2: Wait for a follow-up event with Event Matching

Use this pattern when the entry event sets the stage but the actual decision depends on whether a *second* event fires within a window. [Event Matching](./journeys-actions#event-matching) ties the wait event to the entry event so concurrent Journey instances stay scoped to the same workflow (the same order, the same workspace, the same conversation).

**Use it for:**

* Order tracking with a delivery SLA
* Trial-to-feature-activation funnels
* Quote-to-acceptance windows
* Any "did the expected next step happen?" question

### Example: Food delivery order tracking

A food delivery app enters users into an order Journey when `order_placed` fires. If `order_delivered` fires within 90 minutes for the same `order_id`, the Journey sends a review prompt. Otherwise, it sends a delay-handling support message.

Entry event (sent when the user places the order):

```json JSON theme={null}
{
  "name": "order_placed",
  "properties": {
    "order_id": "ord_88412",
    "restaurant_name": "Marcello's Pizzeria",
    "estimated_delivery_minutes": 45
  },
  "external_id": "user_12345"
}
```

Wait Until event (sent by the courier system when delivery is confirmed):

```json JSON theme={null}
{
  "name": "order_delivered",
  "properties": {
    "order_id": "ord_88412"
  },
  "external_id": "user_12345"
}
```

<Steps>
  <Step title="Set the entry rule">
    **Custom events** entry rule on `order_placed`. No property filter, since every order should enter the Journey.
  </Step>

  <Step title="Add a Wait Until on the delivery event">
    Add a [Wait Until](./journeys-actions#wait-until) step:

    * **Condition:** Custom Event `order_delivered`
    * **Event Matching:**
      * Trigger Event Property: `order_id`
      * Wait Event Property: `order_id`
    * **Expiration:** 90 minutes

    The Event Matching binding ensures that if the same user places two concurrent orders, each order's Journey instance only advances when *that order's* delivery event fires.
  </Step>

  <Step title="Configure the event branch">
    On the event branch (delivery happened in time), send a review prompt:

    ```liquid Liquid theme={null}
    How was your order from {{ journey.first_event.properties.restaurant_name }}? Tap to leave a review.
    ```

    You can use `journey.last_event` here if you want to reference properties on the matched `order_delivered` event. The full reference is in [Custom Event Liquid reference](./personalization-custom-event#custom-event-liquid-reference).
  </Step>

  <Step title="Configure the expiration branch">
    On the expiration branch (90 minutes elapsed without `order_delivered`), send a delay-handling message:

    ```liquid Liquid theme={null}
    Your order from {{ journey.first_event.properties.restaurant_name | default: "the restaurant" }} is taking longer than expected. Tap to track it or reach support.
    ```

    This branch references `journey.first_event` because the wait event never fired. `journey.last_event` would point to the same `order_placed` record in this case.
  </Step>
</Steps>

**Why Event Matching matters.** Without it, the Wait Until would advance on *any* `order_delivered` event for that user. If the user has two open orders, the first delivery would prematurely complete both Journey instances. Binding to a shared `order_id` keeps each instance scoped to its own context.

## Pattern 3: Wait for a threshold or milestone event

Use this pattern when the question is "did the user accumulate enough behavior?" Total spend, total sessions, total invitations sent. Wait Until matches discrete events, not aggregates, so the right way to model thresholds is to **fire a discrete event from your backend the moment a threshold is crossed**.

**Use it for:**

* Lifetime value tiers (silver, gold, platinum)
* Engagement milestones (10 workouts, 50 lessons, 100 transactions)
* Funded-account thresholds
* Streak or consistency achievements

### Example: 30-day VIP loyalty Journey

An ecommerce app enters new users into a 30-day loyalty Journey on `signup_completed`. When cumulative spending crosses a threshold, the backend fires a derived `loyalty_milestone_reached` event. The Journey waits up to 30 days for that event to land and routes accordingly.

Backend-fired milestone event (sent the first time the user crosses the threshold):

```json JSON theme={null}
{
  "name": "loyalty_milestone_reached",
  "properties": {
    "tier": "vip",
    "amount_spent_cents": 25000,
    "currency": "USD"
  },
  "external_id": "user_12345"
}
```

<Steps>
  <Step title="Send the milestone event from your backend">
    Track cumulative spend in your own data store. Each time a `purchase` succeeds, recompute the running total. The first time it crosses the threshold, fire `loyalty_milestone_reached` to OneSignal.

    Fire this event **once per user per milestone**. Use the [`idempotency_key` field](./custom-events#custom-event-structure) to deduplicate if your retry logic could re-fire it.
  </Step>

  <Step title="Set the entry rule">
    **Custom events** entry rule on `signup_completed`. Every new user enters the Journey at signup; the wait then determines what they receive.

    <Note>
      With default re-entry rules, only users who fire `signup_completed` *after* the Journey is published will enter — existing users won't be retroactively enrolled. To run the Journey for your existing user base, fire a one-time `loyalty_journey_eligible` event from your backend or use a segment-based entry rule on `Last Session > 0` instead.
    </Note>
  </Step>

  <Step title="Add a Wait Until on the milestone">
    Wait Until step:

    * **Condition:** Custom Event `loyalty_milestone_reached`
    * **Expiration:** 30 days
    * No Event Matching needed. The milestone fires once per user per signup, so there is no instance ambiguity to resolve.
  </Step>

  <Step title="Configure the event branch">
    On the event branch, send a "Welcome to VIP" email and a celebratory push using the milestone event's properties:

    ```liquid Liquid theme={null}
    You just unlocked {{ journey.last_event.properties.tier | upcase | default: "VIP" }} status. Your perks are live now.
    ```
  </Step>

  <Step title="Configure the expiration branch">
    On the expiration branch (30 days elapsed without the milestone), send a motivating nudge. Two ways to surface progress:

    **Option A — generic copy (simplest):** Don't reference a specific dollar amount, since the cumulative spend lives in your backend rather than the Journey instance:

    ```liquid Liquid theme={null}
    You're closer to VIP than you think. See what's waiting for you.
    ```

    **Option B — Tag-driven progress (recommended for personalization):** Have your backend write a `cents_to_next_tier` Tag on each purchase. Reference the Tag directly in Liquid — no extra Journey machinery needed:

    ```liquid Liquid theme={null}
    You're {{ cents_to_next_tier | divided_by: 100 | money_with_currency }} away from VIP. See what's waiting for you.
    ```

    The Tag-based approach is simpler than firing a second derived event and adding another Wait Until — Tags are evaluated at send time, so the value is always current. Fire a `loyalty_progress_check` event only if you specifically need the progress check to *trigger* a Journey step rather than just personalize copy.
  </Step>
</Steps>

<Tip>
  **Why a derived event beats raw event filtering.** You could try to model thresholds with raw `purchase` events and an entry rule property filter, but that only catches *single purchases* above a threshold, not *cumulative* spending. Cumulative state lives in your backend. Fire a discrete event the moment the state crosses a meaningful boundary, and let the Journey react to that boundary event.
</Tip>

## Personalize messages with event properties

Every Journey instance stores the events that drove its entry and any Wait Until matches. Reference them in templates with Liquid:

```liquid Liquid theme={null}
{{ journey.first_event.properties.product_name }}
{{ journey.last_event.properties.amount }}
{{ journey.event.signup_completed.properties.plan }}
```

* `journey.first_event` is the entry-triggering event.
* `journey.last_event` is the most recently matched event (entry or any Wait Until).
* `journey.event.EVENT_NAME` returns the most recent matched event with a specific name.

For nested property access, default fallbacks, arrays, and the full reference, see the canonical [Custom Event Liquid reference](./personalization-custom-event#custom-event-liquid-reference).

<Card title="Personalize with Custom Events" icon="wand-magic-sparkles" href="./personalization-custom-event">
  Full Liquid reference, nested property access, for-loops over event arrays, and worked examples.
</Card>

## Optimization checklist

Work through this list as you ship more event-driven Journeys.

* **Use Event Matching wherever the same user can have concurrent instances.** Orders, conversations, surveys, support tickets. Bind Wait Until events to a shared identifier so each instance advances independently. See [Event Matching](./journeys-actions#event-matching).
* **Always pair Wait Until with a meaningful expiration.** A wait without a thoughtful expiration leaves users in limbo. Decide what message, or no message, should fire if the expected event never arrives.
* **Reuse the same event for entry and exit on repeating signals.** Cart updates, address changes, plan changes. When a triggering event repeats, set the same event name on the entry rule and the exit rule. The user exits the current instance and re-enters with the latest properties. See [Exit when Custom Event condition occurs](./journeys-settings#exit-when-custom-event-condition-occurs).
* **Watch the 100-property storage cap.** Each Journey instance stores at most 100 event properties across all matched events. Long-running Journeys with many Wait Until matches can hit the cap.
* **Stay under the 2024-byte event payload limit.** Strip properties you won't reference. Move large content like HTML, base64 images, or full carts behind a deep link or a backend lookup.
* **Throttle high-velocity events at the source.** Backfills, retry storms, and dual SDK + backend writes can flood Journey instances and trigger duplicate messages. Fire critical events from a single source of truth and use the [`idempotency_key` field](./custom-events#custom-event-structure) to deduplicate retries. Watch out especially for analytics pipelines that replay events on schema changes.
* **Use Custom Events to drive in-app messages and SMS too, not just push and email.** A `feature_unlocked` event can target the next-session IAM that surfaces the new feature, and a high-intent event like `payment_failed` is the right moment for SMS to consenting users. See [In-app message triggers](./in-app-messages-setup#triggers).
* **Verify events with the Custom Events Activity feed before activating.** The dashboard's [Event Activity tab](./custom-events#event-activity-tab) shows events as they land. Use it to confirm property names, types, and values match your Journey configuration before turning the Journey live.
* **Check Journey entry logs when events land but no Journey runs.** If your Custom Events Activity feed shows events arriving but the Journey isn't entering users, see [Journey analytics](./journeys-analytics) for entry/exit logs that show which entry rule a user matched (or why they didn't).

## FAQ

### When should I use a Custom Event entry rule vs. a segment-based entry rule?

Use a Custom Event entry rule when the trigger is a discrete user action (the user just placed an order). Use a segment-based entry rule when the trigger is a state (the user has been inactive for 7 days). You cannot combine the two on the same Journey, but you can still reference Custom Events inside a segment-based Journey via Wait Until steps.

### Can a single user be in the same Journey multiple times?

Yes. Custom Event entry rules allow concurrent instances by default. Each `order_placed` for the same user starts its own instance with its own stored event. To prevent overlap, either filter the entry rule by a property or set the same event name as both the entry rule and the exit rule, which exits the current instance before the new one begins. See the [Custom Event entry rule warning](./journeys-settings#custom-events).

### Why is my Wait Until step matching the wrong event?

A Wait Until without [Event Matching](./journeys-actions#event-matching) advances on *any* event of the configured name for that user. If the user has multiple concurrent Journey instances or fires the event from an unrelated workflow, the Wait Until completes prematurely. Bind it to a shared property like `order_id` or `workspace_id` so each instance scopes to its own context.

### How do I model thresholds like "spent more than \$100"?

For per-event thresholds (this single purchase was above $100), use a property filter on the entry rule. For cumulative thresholds (lifetime spend crossed $100), compute the cumulative state in your backend and fire a derived event the moment the threshold is crossed. Wait Until matches discrete events, not aggregates.

### What happens to the stored event when a user exits a Journey?

The stored event is cleared. If the user re-enters the same Journey, a fresh `journey.first_event` is captured from the new entry trigger. See [Event property storage rules](./personalization-custom-event#event-property-storage-rules).

### Do I need to send Custom Events from a mobile or web SDK?

No. You can send Custom Events from any source: SDKs, the [Create Custom Events API](/reference/create-custom-events), or one of OneSignal's [data integrations](./custom-events#integrations). All sources are treated identically inside Journeys.

## Related pages

<Columns>
  <Card title="Custom Events" icon="bolt" href="./custom-events">
    Send events from your SDK or REST API, configure retention, and verify events in the dashboard.
  </Card>

  <Card title="Personalize with Custom Events" icon="wand-magic-sparkles" href="./personalization-custom-event">
    Full Liquid reference for `journey.first_event`, `journey.last_event`, and `journey.event.EVENT_NAME`.
  </Card>

  <Card title="Journey actions" icon="code-branch" href="./journeys-actions">
    Wait, Wait Until, Time Window, Yes/No branch, Split Branch, and Tag User reference.
  </Card>

  <Card title="Journey settings" icon="gear" href="./journeys-settings">
    Configure entry rules, exit rules, re-entry, and scheduling.
  </Card>

  <Card title="Welcome Journey: Mobile gaming" icon="gamepad" href="./welcome-journey-mobile-gaming">
    Worked example of a 7-day onboarding Journey using a `daily_session` Wait Until.
  </Card>

  <Card title="Abandoned cart tutorial" icon="cart-shopping" href="./abandoned-cart">
    End-to-end ecommerce Journey using cart events for entry, exit, and personalization.
  </Card>
</Columns>


# Get more app store reviews
Source: https://documentation.onesignal.com/docs/en/example-app-store-review

Prompt users to review your app using OneSignal in-app messages with native iOS and Android review prompts, reducing friction and increasing ratings.

Use OneSignal in-app messages to prompt users for an App Store or Google Play review without leaving your app. This tutorial covers both no-code and code-required approaches.

<Frame>
  <img alt="In-app message with a Review Now button prompting the user to rate the app" />
</Frame>

## Setup

### 1. Create the message

Navigate to **Messages > In-App > New In-App** or open the existing App Store Rating template.

Add an Action ID to your review button:

<Frame>
  <img alt="OneSignal in-app message editor showing the Custom Action ID field set to review on a button element" />
</Frame>

### 2. Add the trigger

The trigger controls when the message displays. You can use a no-code or code-based approach.

**No-code**: Set up the Audience to target users you want reviews from — for example, users with many sessions who have used the app for a long time.

**Code-based**: Use the SDK's `addTrigger` method to programmatically display the message based on user actions. Avoid showing the prompt when the user is in the middle of an important task.

In this example, the **In-App Trigger** key is `ask_for_review` with a value of `show`. The key and value can be anything, but must match what you pass to `addTrigger`:

`OneSignal.InAppMessages.addTrigger("ask_for_review", "show");`

<Frame>
  <img alt="OneSignal dashboard showing the in-app message trigger set to ask_for_review equals show" />
</Frame>

### 3. Handle the app store rating prompt

You can direct users to leave a review with a no-code or code-based approach.

<Accordion title="No-code option">
  1. Update the segment to use the "Device Type is Android" filter.
  2. Duplicate the in-app message and update the duplicate's segment to use the "Device Type is iOS" filter. You should have two in-app messages with two separate segments.
  3. Add a [URL Click Action](./iam-click-actions) to the "Review Now" button linking to your app's store listing:
     * **Android**: `https://play.google.com/store/apps/details?id=YOUR_PACKAGE_NAME` — see [Linking to Google Play](https://developer.android.com/distribute/marketing-tools/linking-to-google-play.html)
     * **iOS**: `https://apps.apple.com/app/idYOUR_APP_STORE_ID?action=write-review` — see [Requesting App Store Reviews](https://developer.apple.com/documentation/storekit/requesting_app_store_reviews)
</Accordion>

<Accordion title="Code-based option">
  Use the SDK's `InAppMessages.addClickListener` method to detect when the review button is clicked (by checking the Action ID), then call the native iOS or Android review API to present the rating modal.

  ```dart theme={null}
  OneSignal.InAppMessages.addClickListener((event) async {
    if (event.result.actionId == 'review') {
      if (await inAppReview.isAvailable()) {
        inAppReview.requestReview();
      }
    }
  });
  ```

  This example uses the [in\_app\_review](https://pub.dev/packages/in_app_review) Flutter package. Adapt for your platform — see [RequestReviewAction](https://developer.apple.com/documentation/storekit/requestreviewaction) for iOS or the [Google Play In-App Reviews API](https://developer.android.com/guide/playcore/in-app-review) for Android.
</Accordion>

### 4. Schedule and enable

Apple displays the native review prompt a maximum of three times within a 365-day period. Google Play enforces a time-bound quota but does not publish the exact limit — calling the API more than once in a short period (less than a month) may not show a dialog.

To stay within these limits, set your in-app schedule to display once every 17 weeks:

<Frame>
  <img alt="OneSignal in-app message scheduling settings showing 40 total displays with 17-week intervals" />
</Frame>

<Tip>
  To increase positive reviews, target users who have had a great experience — for example, users with many sessions or those who gave positive feedback via a previous in-app message. Set [tags](./add-user-data-tags) on these users and create a segment to use as the audience for your review prompt.
</Tip>

***

## FAQ

### How often can Apple's native review prompt appear?

Apple displays the `RequestReviewAction` prompt a maximum of three times per 365-day period per user. This is enforced by the system — your app does not need to track the count. See [Requesting App Store Reviews](https://developer.apple.com/documentation/storekit/requesting_app_store_reviews).

### How often can Google's native review prompt appear?

Google Play enforces a quota but does not publish the exact limit. Calling `launchReviewFlow` more than once in a short period (less than a month) may not display the dialog. The quota is an implementation detail that Google can change without notice. See [In-App Reviews quotas](https://developer.android.com/guide/playcore/in-app-review#quotas).

### Can I use this with non-native apps (Flutter, React Native, Expo)?

Yes. Use a platform-specific plugin to call the native review API — for example, [in\_app\_review](https://pub.dev/packages/in_app_review) for Flutter or [StoreReview](https://docs.expo.dev/versions/latest/sdk/storereview/) for Expo. The OneSignal in-app message and click listener work the same way regardless of framework.

***

<Columns>
  <Card title="In-app click actions" icon="hand-pointer" href="./iam-click-actions">
    Configure URL, permission prompt, tag, outcome, and custom click actions on in-app message elements.
  </Card>

  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Tag users based on behavior to build segments for targeted messaging.
  </Card>
</Columns>


# Create a survey to ask for feedback
Source: https://documentation.onesignal.com/docs/en/example-create-a-survey

Build a multi-page in-app survey using Carousel, Button Click Actions, Outcomes, and Tags for analytics and segmentation.

Using the in-app message Carousel and Button Click Actions, you can create a survey with up to 10 pages of questions and multiple-choice answers. When users respond, you can collect the data as Outcomes and group respondents with [Tags](./add-user-data-tags) for follow-up targeting.

<Note>
  Before starting, make sure you have [in-app messaging set up](./in-app-messages-setup) in your OneSignal app.
</Note>

***

## Design your survey

1. Select the **Full** message type to enable the Carousel feature.
2. Add 3 Text Blocks, 1 Image Block, and 2 Button Blocks.
3. Select **+ Create Carousel** to duplicate this card, then navigate back to **Card 1**.

When you duplicate a card, all blocks are duplicated as well, so you only need to update the content on each new card.

The initial setup looks similar to this:

<Frame>
  <img alt="In-app message editor showing a full-screen survey with text, image, and button blocks" />
</Frame>

Add your question text, an image, and button labels to each card. Users read the question, select a button, and swipe to the next question.

### Set up click actions for the first question

The first question might ask whether the user has time to take the survey. Configure each button to send an Outcome so you can track how many users accept or decline.

1. Select a button block and click **Add Click Action** > **Send Outcome**.
2. Adding an Outcome also sets a Tag, giving you both analytics and a segment filter for re-targeting.

For the "Yes" button, **uncheck** "Dismiss on click" (found in the block's top-right menu > **Show Advanced Settings**) so the user can continue to the next card.

<Frame>
  <img alt="Button block settings showing Send Outcome action with Dismiss on click unchecked" />
</Frame>

<Frame>
  <img alt="Block menu showing the clone option" />
</Frame>

For the "No" button, configure it the same way but **check** "Dismiss on click" so the in-app message closes.

<Frame>
  <img alt="Button block settings showing Send Outcome action with Dismiss on click checked" />
</Frame>

***

## Add more cards and questions

Click **Card 2** or swipe the Carousel to the next page. All blocks are duplicated from Card 1.

Update the text and image for the new question. Keep "Dismiss on click" **unchecked** on both buttons so the user can continue to the next card.

<Frame>
  <img alt="Card 2 showing updated question text and two button blocks with Outcome actions" />
</Frame>

Press **+ Add Card** to add additional cards. You can add up to 10 cards total.

***

## Final survey question

For the last card, set up a multiple-choice question to give users more options.

To make room for additional buttons, remove the Image Block and add 2 more Button Blocks. You can clone existing blocks to reuse their configuration.

<Frame>
  <img alt="Block menu showing the clone option for a button block" />
</Frame>

Since this is the final question, **check** "Dismiss on click" on every button so the in-app message closes after the user responds.

<Frame>
  <img alt="Final survey card showing four button options, each configured to dismiss on click" />
</Frame>

<Tip>
  After publishing, check your Outcome analytics in the OneSignal dashboard to see response rates. Use the Tags set by each button to build segments for follow-up messages.
</Tip>

***

## FAQ

### How many questions can I include in a survey?

Up to 10. Each Carousel card represents one question, and the Carousel supports a maximum of 10 cards.

### Can I use this for multiple-choice questions with more than two options?

Yes. Add additional Button Blocks to any card. Each button can have its own Outcome and Tag, so every answer option is tracked independently.

### How do I target users based on their survey responses?

Each button click action can set a Tag on the user. After the survey runs, create a [segment](./segmentation) that filters by those tag values to target respondents with follow-up messages.

## Related pages

<Columns>
  <Card title="In-app messages" icon="message" href="./in-app-messages-setup">
    Set up and configure in-app messaging in your app.
  </Card>

  <Card title="Data Tags" icon="tags" href="./add-user-data-tags">
    Store user properties for segmentation and personalization.
  </Card>

  <Card title="Design your in-app message" icon="pen-ruler" href="./design-your-in-app-message">
    Full reference for the in-app message editor, blocks, and Carousel.
  </Card>
</Columns>


# Onboard users with banner in-app messages
Source: https://documentation.onesignal.com/docs/en/example-create-a-tutorial

Guide users with contextual top and bottom banner in-app messages that don't block your app UI.

Banner In-App Messages (IAMs) let you guide users without blocking your app UI. You display short, contextual messages at the top or bottom of the screen while users continue interacting with your app.

You typically use banner IAMs when users need extra context at a specific moment, such as the first time they reach a screen or start a key workflow.

<Info>
  In-App Messages display only when their trigger conditions are met. You control exactly when a banner appears by setting triggers from your app.
</Info>

***

## When to use banner IAMs

Use banner IAMs for onboarding when you want to:

* Explain a screen as the user reaches it
* Guide users through multi-step flows
* Highlight actions users should take next
* Keep onboarding visible but non-intrusive

If you need a structured, multi-screen walkthrough, use a card or carousel IAM instead.

***

## Example onboarding flow

When a user opens your site or app for the first time, a top banner welcomes them and prompts exploration. When the user taps a product to view details, a bottom banner guides them on what to do next. Each banner appears only when the user reaches the relevant screen.

This approach ensures users see guidance only when it is relevant.

### Visual example: E-commerce onboarding

Here's how banner IAMs guide users through an e-commerce app. This example uses **two separate IAMs**, each with a **3-second auto-dismiss**. When the first banner dismisses, the trigger for the second banner activates, creating a smooth sequential flow:

<Columns>
  <Card title="Initial welcome banner" icon="hand-wave">
    <Frame>
      <img alt="Welcome banner displaying 'Tap on any product to learn more and start shopping!'" />
    </Frame>

    When users first open the app, a bottom banner prompts them to explore products.
  </Card>

  <Card title="Product selection banner" icon="cart-shopping">
    <Frame>
      <img alt="Product banner displaying 'You're viewing a product! Check out all the details and add it to your cart when you're ready.'" />
    </Frame>

    When a user taps on a product, a banner provides guidance for the product detail view.
  </Card>
</Columns>

***

## Prerequisites

Before you begin, make sure you have:

* An active OneSignal app
* OneSignal SDK installed in your app
* The ability to trigger events or call methods from your app code
* [User consent](./mobile-sdk-reference#privacy) granted for the OneSignal SDK (required for In-App Messaging)

***

## Create a banner in-app message

<Steps>
  <Step title="Navigate to In-App Messages">
    In the OneSignal dashboard, go to **Messages → In-App Messages** and select **New In-App Message**.
  </Step>

  <Step title="Choose banner type">
    Under **Message Type**, choose **Top** or **Bottom**.
  </Step>

  <Step title="Design your content">
    Include a short heading that explains the purpose of the screen, optional supporting text if needed, and an optional button to guide the next action.
  </Step>

  <Step title="Configure triggers">
    Add one or more **[In-App Message triggers](./iam-triggers)** that define when the banner should appear. Optionally add conditions or limits to control how often the message displays.
  </Step>

  <Step title="Set display duration">
    Choose between auto-dismiss (banner disappears after 3-10 seconds) or user-dismissible (banner remains until the user taps close).
  </Step>

  <Step title="Activate the message">
    Save and activate your banner In-App Message.
  </Step>
</Steps>

<Note>
  Use top banners for high-visibility guidance and bottom banners for subtle prompts that align with primary actions. For onboarding, use auto-dismiss to keep the flow moving without requiring user action.
</Note>

<Warning>
  Avoid long explanations. Banner IAMs are not designed for detailed onboarding or tutorials.
</Warning>

***

## Trigger the banner from your app

You trigger the banner IAM when the user reaches a specific screen or completes an action using In-App Message triggers. Triggers are key–value pairs that you set from your app code. When the trigger conditions match the IAM's display rules, the banner displays.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Trigger when the user views the dashboard
  OneSignal.addTrigger('dashboard_viewed', 'true');
  ```

  ```swift iOS theme={null}
  // Trigger when the user views the dashboard
  OneSignal.addTrigger("dashboard_viewed", value: "true")
  ```

  ```kotlin Android theme={null}
  // Trigger when the user views the dashboard
  OneSignal.addTrigger("dashboard_viewed", "true")
  ```
</CodeGroup>

<Info>
  Triggers persist for the session unless you remove or update them. Make sure each trigger represents a clear, intentional onboarding moment.
</Info>

### Remove triggers when no longer needed

To prevent banners from reappearing unintentionally, remove triggers when they're no longer needed:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Remove trigger after the user completes onboarding
  OneSignal.removeTrigger('dashboard_viewed');
  ```

  ```swift iOS theme={null}
  // Remove trigger after the user completes onboarding
  OneSignal.removeTrigger("dashboard_viewed")
  ```

  ```kotlin Android theme={null}
  // Remove trigger after the user completes onboarding
  OneSignal.removeTrigger("dashboard_viewed")
  ```
</CodeGroup>

***

## Chain banner messages (optional)

You can guide users through a flow by creating **multiple IAMs**, each with its own trigger. Set each banner to **auto-dismiss after 3 seconds** so the next banner can appear. Remove the previous trigger before adding the next one to prevent overlapping banners.

<Tip>
  For smooth sequential onboarding, create one IAM per step, set each to auto-dismiss after 3 seconds, and chain them by removing the previous trigger when adding the next one.
</Tip>

### Example: E-commerce onboarding flow

1. Page loads → Trigger `iam_welcome` → Banner: "🎉 Welcome! Explore our products"
2. User taps product → Trigger `iam_product_view` → Banner: "👀 Tap ❤️ to save favorites"
3. User adds to cart → Trigger `iam_add_to_cart` → Banner: "✅ Great choice! View cart anytime"
4. User views cart → Trigger `iam_cart_view` → Banner: "🛒 Review your items here"
5. User checks out → Trigger `iam_checkout` → Banner: "🎊 Thanks for your order!"

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Move from step 1 to step 2
  OneSignal.removeTrigger('iam_welcome');
  OneSignal.addTrigger('iam_product_view', 'true');
  ```

  ```swift iOS theme={null}
  // Move from step 1 to step 2
  OneSignal.removeTrigger("iam_welcome")
  OneSignal.addTrigger("iam_product_view", value: "true")
  ```

  ```kotlin Android theme={null}
  // Move from step 1 to step 2
  OneSignal.removeTrigger("iam_welcome")
  OneSignal.addTrigger("iam_product_view", "true")
  ```
</CodeGroup>

This creates progressive onboarding without overwhelming the user.

***

## Verify the setup

<Check>
  The banner appears only when the trigger fires and does not block the app UI.
</Check>

If the banner does not appear:

* Confirm the trigger key and value match exactly (case-sensitive)
* Verify the IAM is Active in the dashboard
* Check Frequency Limits - the IAM may be rate-limited
* Ensure user meets Targeting Rules (if any)
* Check console logs for OneSignal trigger events
* Verify In-App Messaging consent has been granted (if required)

***

## Next steps

* Announce new features using banner In-App Messages
* Create a full onboarding experience with card or carousel IAMs
* Segment users to show different onboarding messages based on experience level
* [A/B test](./journeys-actions#abn-tests-multivariate-testing) different banner messages to optimize engagement


# Target certain Android manufacturers and devices
Source: https://documentation.onesignal.com/docs/en/example-target-certain-android-manufacturers-and-devices

Use OneSignal in-app messages to coach Android users on Samsung, Xiaomi, and similar devices that block push delivery when apps are force-stopped or have notification categories disabled.

Some Android manufacturers — including Samsung, Xiaomi, Huawei, Oppo, Vivo, and OnePlus — restrict background activity for non-system apps. When users swipe these apps away from the recents list, the OS force-stops the app and blocks push delivery until the user reopens it. See [Android Force Stop](./notifications-show-successful-but-are-not-being-shown#android-force-stop) for the underlying cause.

Push delivery from OneSignal succeeds, but the device suppresses the notification. You can detect these devices from your Android app and trigger a OneSignal in-app message that walks the user through enabling the right settings.

<Note>
  This pattern applies only to Android apps. iOS and web do not have an equivalent OS-level restriction that requires user remediation.
</Note>

## Prerequisites

* An Android app integrated with the OneSignal SDK V5 or later. See [Mobile SDK setup](./mobile-sdk-setup).
* An in-app message you can build in the dashboard. See [In-app messages setup](./in-app-messages-setup).
* Familiarity with [in-app triggers](./iam-triggers) and the [`addTrigger` method](./mobile-sdk-reference#in-app-messages).

***

## Set up the message and trigger

<Steps>
  <Step title="Create the in-app message in the dashboard.">
    In **Messages > In-App > New In-App**, build the message you want to show. The body should give users clear, copy-paste-friendly steps to allow background activity on their device.

    Set the audience to **Subscribed Users** with platform filter **Android**. Other audience filters work too, as long as the user is in the audience *before* a new session starts — otherwise the trigger will not fire. See the [in-app trigger requirements](./iam-triggers#important-in-app-trigger-requirements).

    In **Trigger**, choose **Custom trigger** and set:

    * **Key**: `device_manufacturer`
    * **Operator**: `is`
    * **Value**: `restricted`

    <Frame>
      <img alt="OneSignal dashboard in-app message trigger panel with key device_manufacturer set to value restricted" />
    </Frame>
  </Step>

  <Step title="Detect the device manufacturer in your Android app.">
    Read `android.os.Build.MANUFACTURER` early in your app's lifecycle — for example in `Application.onCreate()` or immediately after OneSignal initialization. If the value matches your list of restricted manufacturers, call `addTrigger` with the same key and value you set in the dashboard.

    <CodeGroup>
      ```kotlin Kotlin theme={null}
      val restrictedManufacturers = setOf(
        "samsung", "huawei", "xiaomi", "oppo", "vivo",
        "oneplus", "honor", "realme", "meizu", "asus"
      )

      if (Build.MANUFACTURER?.lowercase(Locale.ROOT) in restrictedManufacturers) {
        OneSignal.InAppMessages.addTrigger("device_manufacturer", "restricted")
      }
      ```

      ```java Java theme={null}
      Set<String> restrictedManufacturers = new HashSet<>(Arrays.asList(
        "samsung", "huawei", "xiaomi", "oppo", "vivo",
        "oneplus", "honor", "realme", "meizu", "asus"
      ));

      String manufacturer = Build.MANUFACTURER != null
        ? Build.MANUFACTURER.toLowerCase(Locale.ROOT)
        : "";

      if (restrictedManufacturers.contains(manufacturer)) {
        OneSignal.getInAppMessages().addTrigger("device_manufacturer", "restricted");
      }
      ```
    </CodeGroup>

    <Tip>
      Keep the manufacturer list in remote config (Firebase Remote Config, your own backend, or feature flags) so you can update it without shipping a new app release. [dontkillmyapp.com](https://dontkillmyapp.com/) maintains a community-sourced list of OEMs with restrictive battery policies.
    </Tip>
  </Step>

  <Step title="Point users to the correct settings.">
    Settings paths vary by manufacturer and OS version, so generic instructions break quickly. Two approaches that age well:

    * **Recommended.** Link to the manufacturer's page on [dontkillmyapp.com](https://dontkillmyapp.com/) (for example, `https://dontkillmyapp.com/samsung`) from the in-app message CTA. The site has up-to-date, per-OEM walkthroughs in multiple languages.
    * **Advanced.** Deep-link to the Android battery optimization screen from your IAM click handler using `Intent.ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS`. This skips the settings hunt entirely on most devices.

    If you prefer to include settings copy directly in the message, scope it to the dominant manufacturer in your install base and refresh it when you see drop-off in delivery.

    <Accordion title="Example message copy for Samsung">
      > Your device may not be receiving our notifications. To make sure you stay updated:
      >
      > Settings > Apps > \[Your app] > Battery > **Allow background activity**
      >
      > Settings > Apps > \[Your app] > Notifications > **Allow notifications** and verify all categories are on.

      <Frame>
        <img alt="OneSignal in-app message editor previewing a warning that the device may not be receiving notifications, with Samsung-specific settings steps" />
      </Frame>
    </Accordion>
  </Step>

  <Step title="Test on a target device.">
    1. Install a debug build on a Samsung (or other restricted-manufacturer) device.
    2. Force-close and reopen the app to start a new session.
    3. Confirm in logcat that `addTrigger` is being called with the expected key and value.
    4. Verify the in-app message displays. If it does not, see [In-app message troubleshooting](./in-app-message-troubleshooting).
  </Step>
</Steps>

***

## Detect Samsung notification category restrictions

Samsung One UI 6.1 silently disables notification categories for many apps after install, which suppresses notifications even when the OS otherwise allows them. You can target this case with the same pattern by adding a second trigger and a second in-app message.

```kotlin theme={null}
if (Build.MANUFACTURER.equals("samsung", ignoreCase = true)) {
  OneSignal.InAppMessages.addTrigger("samsung_category_check", "show")
}
```

Configure a separate in-app message that explains how to re-enable categories at **Settings > Notifications > Your app**. See [Android notification categories disabled](./notifications-show-successful-but-are-not-being-shown#android-notification-categories-disabled) for background on this issue.

***

## FAQ

### Why isn't my in-app message firing?

The most common cause is calling `addTrigger` after the user is already past the start of their session. In-app messages evaluate triggers when a session begins. Call `addTrigger` early in your app launch flow — before any user interaction — or instruct the user to relaunch the app.

A second common cause is the user being excluded from the message audience. Confirm the message audience includes the test user's subscription and platform.

### Will the message show on every app launch?

By default, every launch where the trigger matches will fire the message. To limit frequency, configure [display frequency](./in-app-messages-setup#display-frequency) on the in-app message (for example, "Show only once").

### Does this work on iOS?

No. iOS does not allow third-party apps to be force-stopped by the OS or by user swipe, so the underlying problem does not exist. You do not need to ship this pattern on iOS.

### Does this work on React Native, Flutter, or Cordova?

Yes. The `addTrigger` API is identical across [supported SDKs](./mobile-sdk-reference#in-app-messages). To read the device manufacturer, use a platform package such as `react-native-device-info` (`getManufacturer()`) or `device_info_plus` (`AndroidDeviceInfo.manufacturer`), then call `OneSignal.InAppMessages.addTrigger("device_manufacturer", "restricted")` when the value matches your list.

### Can OneSignal detect the manufacturer for me?

No. The OneSignal SDK does not expose `Build.MANUFACTURER` directly. You read it from the Android `Build` class in your own code and pass the result to `addTrigger`.

### Where can I see if the trigger is firing?

Trigger state is local to the SDK and is not a user-level property, so it does not appear in the OneSignal dashboard. To confirm it ran, add a log statement next to your `addTrigger` call, then watch logcat or check whether the IAM displayed for the test user.

***

## Related pages

<Columns>
  <Card title="Notifications successful but not shown" icon="bell-slash" href="./notifications-show-successful-but-are-not-being-shown">
    Diagnose Force Stop, disabled categories, Doze mode, and other reasons Android delivery succeeds but the user sees nothing.
  </Card>

  <Card title="In-app triggers" icon="bolt" href="./iam-triggers">
    Audience and trigger requirements, including the session-start rule that catches most setup mistakes.
  </Card>

  <Card title="In-app messages setup" icon="message" href="./in-app-messages-setup">
    Build the message itself in the OneSignal dashboard, including audience, display options, and frequency.
  </Card>

  <Card title="Mobile SDK reference: addTrigger" icon="code" href="./mobile-sdk-reference#in-app-messages">
    Full cross-platform reference for `addTrigger`, `addTriggers`, `removeTrigger`, and `clearTriggers`.
  </Card>
</Columns>


# Send verification, magic link, OTP, and double opt-in messages
Source: https://documentation.onesignal.com/docs/en/example-verification-magic-link-otp

Examples of email and SMS verification messages using OneSignal, including one-time passwords, magic links, and double opt-in flows with templates and API examples.

Whether you need account authentication, registering new users/passwords, or confirming a transaction, you sometimes just need to send a one-time password, magic link, or registration URL to someone. Email verification is a good example and a way to prevent fake or inactive email addresses. Following this guide will help make sure your users can actually receive the emails you send while also increasing your sender's reputation and deliverability.

## Requirements

* A server to generate and send the OTP or confirmation code.

## Sending `custom_data` through the API

Our [Create message API](/reference/create-message) has the `custom_data` property which you can use to pass data from your server into the message.

Depending on how you generate the confirmation code, magic link, or custom URL, once you do, you can pass it into the `custom_data` object when sending a message to your users. For example:

<CodeGroup>
  ```Text JSON theme={null}
  "custom_data": {
      "user": {
          "first_name": "George"
      },
      "verify": {
          "URL" : "https://yourdomain.com/users/confirm?confirmation_token=OS4EVA",
          "otp" : "OS4EVA"
      }
  }
  ```
</CodeGroup>

## Verification Email Template

This email template example will demonstrate how to display the user's name, a one-time passcode, and a button with a link to confirm their email address.

<Frame>
  <img alt="" />
</Frame>

### Email Template Setup

Navigate to **Messages > Templates > New Email Template** and use the **Drag & Drop Editor**.

Create 1 row and drag in the following blocks:

* **Title** block
* **Paragraph** block
* **Button** block

<Frame>
  <img alt="" />
</Frame>

### Display user's name in email

This is optional, but you can make the message more personalized by adding the user's name. If you may not have the name, you can omit it or set a default.

Within our template **Title** block, set your copy as desired. Example:

```
Hey {{ message.custom_data.user.first_name | default: "there" }},
```

### Display one-time password in email

This example shows both the option to send a one-time password and a button with confirmation URL. Depending on how you want to setup, set your copy within the **Paragraph** block as desired. Example:

```
To join the squirrel crew, verify your email with the One Time Password:
{{message.custom_data.verify.otp}}

Or use the link below!
```

You can use more than one **Paragraph** or **Text** blocks if you want to make the password larger or distinct from the text. In this example, we made it bold:

<Frame>
  <img alt="" />
</Frame>

### Add a custom URL in email

There are several ways to setup the verification URL. In this example we pass in the full URL with confirmation code to `custom_data`.

In the **Button** block > Content Properties > Action > Url, set:

* `{{message.custom_data.verify.URL}}`

<Frame>
  <img alt="" />
</Frame>

## Update the email template and send the message

See [Design Emails with Drag and Drop](./design-emails-with-drag-and-drop) for more details on customizing the template.

Example API request JSON:

<CodeGroup>
  ```Text JSON theme={null}
  {
      "include_email_tokens": [
          "Email Address"
      ],
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_TEMPLATE_ID",
      "custom_data": {
          "user": {
              "first_name": "George"
          },
          "verify": {
              "URL" : "https://yourdomain.com/users/confirm?confirmation_token=OS4EVA",
              "otp" : "OS4EVA"
          }
      }
  }
  ```
</CodeGroup>

<Check>
  When ready, you can use the `template_id` within your [Create notification](/reference/create-message) API requests with `custom_data` property.
</Check>

## Verification SMS Template

This SMS template example will demonstrate how to display a one-time passcode.

### SMS Template Setup

SMS should only be sent with a limited amount of data to reduce charges.

Navigate to **Messages > Templates > New SMS Template**.

Name the template something memorable like `OTP Template`.

### Display OTP in SMS template

In the template **Message** field, add the following copy:

* `{{message.custom_data.verify.otp}} is your OneSignal verification code.`

We recommend changing "OneSignal" to the name of your app.

### Update the SMS template and send the message

Once you have the template created, you can generate your one time passwords and pass them to OneSignal using the following example API request JSON:

<CodeGroup>
  ```Text JSON theme={null}
  {
      "include_phone_numbers": ["+19999999999"],
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_TEMPLATE_ID",
      "custom_data": {
          "verify": {
              "otp" : "OS4EVA"
          }
      }
  }
  ```
</CodeGroup>

<Check>
  When ready, you can use the `template_id` within your [Create notification](/reference/create-message) API requests with `custom_data` property.
</Check>

## Setting Up Email Double Opt-In

Double opt-in is a process that requires users to confirm their email subscriptions to enhance email list quality and comply with regulations.

### 1. Adding Email Addresses to OneSignal

When adding email addresses to OneSignal, they are automatically subscribed by default. However, for double opt-in, refrain from [adding users via our Create user API](/reference/create-user) until they click the verification link sent via email.

### 2. Sending Verification Emails

OneSignal allows you to send verification emails to recipients using our [Create notification API](/reference/create-message). The endpoint will send the email and add the address to OneSignal as an email subscription if it doesnt already exist in the app.

#### API Endpoint: Sending a Verification Email

* Utilize the [Create notification endpoint](/reference/create-message) to create and send a [verification email](./example-verification-magic-link-otp) to the recipient.

### 3. Handling Verification Responses

Depending on the recipient's response to the verification link, follow these steps:

**For Non-Subscribers**

1. Target the email recipient with a custom data notification via our [Create notification API](/reference/create-message).
2. If the user clicks the verification link, use the API's "[Create user](/reference/create-user)" endpoint to add them as a subscription.

**For Existing Subscribers**

1. Target existing subscribers separately with a verification email.
2. Monitor the recipients' responses to the verification link over a predefined period.

**If They Don't Respond**

* [Update the subscription](/reference/update-subscription) to unsubscribe or [delete it altogether](/reference/delete-subscription) via the API.

**If They Click the Verification Link**

* Do nothing - they are already subscribed to OneSignal.

### In summary, setting up double opt-in with OneSignal involves the following steps:

#### For Email Addresses Not Currently in Your Audience

1. Send a verification email to the recipient via the API.
2. If the recipient clicks the verification link, use the "create user" API endpoint to create the subscription.

#### For Email Addresses Already in OneSignal

1. Send a verification email to existing subscribers via the API.
2. Monitor their response to the verification link.
3. If they don't respond within a specified period, update their subscription to unsubscribe or delete it.
4. If they've clicked the verification link, take no action as they are already subscribed.

By following these steps, you can effectively implement double opt-in functionality in your email subscription process while ensuring compliance and maintaining a high-quality email list.

***


# Financial and fintech strategies
Source: https://documentation.onesignal.com/docs/en/financial-fintech-industry

Implementation hub for financial and fintech messaging — user IDs, KYC and security Tags, product-holding and transaction Custom Events, segments, and Journey playbooks for compliance, verification, cross-sell, and retention.

A financial and fintech messaging strategy targets apps where success depends on completed verification, secure account behavior, and sustained transaction activity. If your product handles deposits, trades, payments, or any user-attached financial data, this guide is for you.

This page is the implementation hub: which user identifier to set, what compliance and behavioral data to capture, which segments to build, and which Journeys drive verification, security, conversion, and retention. Each section links to the canonical docs for deeper detail.

<Note>
  Many fintech messages carry regulatory or jurisdictional disclosure requirements (e.g., Reg E, SEC, FINRA, GDPR financial data). Treat copy and frequency as compliance surfaces — review with your legal team before launching new flows. Nothing in this guide is legal advice.
</Note>

## Implementation roadmap

Work through these steps in order. Each one links to its section below.

<Steps>
  <Step title="Assign External IDs">
    Set a stable, app-side identifier on every authenticated user so push, email, and SMS tie to one profile across reinstalls. Critical for tying account, balance, and transaction data to messaging. [Jump to section](#identify-your-users-with-external-ids).
  </Step>

  <Step title="Add account properties as Tags">
    Start with `account_status`, `kyc_completed`, `2fa_enabled`, and `first_name`. They power every compliance and security Journey. [Jump to section](#tags).
  </Step>

  <Step title="Send user actions as Custom Events">
    Fire `signup_completed`, `verification_completed`, `first_transaction_completed`, and `transaction_completed` from your app or backend. [Jump to section](#custom-events).
  </Step>

  <Step title="Build lifecycle Segments">
    Compliance and growth audiences such as Unverified Users, 2FA disabled, Active Traders, and Dormant Accounts. [Jump to section](#segments).
  </Step>

  <Step title="Create lifecycle Journeys">
    Verification, 2FA setup, first-action promotions, transactional alerts, cross-sell and feature adoption, and re-engagement. [Jump to section](#journey-examples).
  </Step>
</Steps>

## Identify your users with External IDs

External IDs preserve identity across installs and tie push, email, and SMS to one customer profile. Use the unique identifier from your authentication, KYC, or core banking platform — for example, a Cognito or Auth0 `uid`, or your internal `customer_id`.

Set the External ID at signup, on every login, and on session resume. The OneSignal SDK does not assign it for you, and assigning it late or sporadically breaks attribution between messaging, KYC outcomes, and downstream transactions — making compliance audits and funnel analytics unreliable.

<Card title="External ID setup" icon="id-card" href="./users#external-id">
  Assign a unique identifier to each user so account state, verification status, and notifications follow them across devices and reinstalls.
</Card>

## Recommended data

Tags persist on the user profile (current state); Custom Events record discrete moments (what just happened). Use both — Tags drive compliance-aware segmentation and personalization, Custom Events trigger Journey entry and Wait Until conditions.

Fintech leans heavily on Tags for state (`account_status`, `kyc_completed`, `2fa_enabled`) because so much messaging is gated on whether the user is in a particular regulatory or onboarding stage. Custom Events handle the moments — verification submission, transactions, security changes — that move users between those states.

### Tags

Tags persist on the user profile and are used for segmentation and personalization. For boolean-style signals, set the Tag to `1` when true and **remove it** when false — segment with "tag exists" rather than storing `0`/`false` values.

<Tip>
  If you only set up four Tags, start with `account_status`, `kyc_completed`, `2fa_enabled`, and `first_name`. They power every compliance and security Journey.
</Tip>

#### Account and compliance state

| Tag              | Values                                              | Use                                                                                                                                                                                                                                                                                                                   |
| :--------------- | :-------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_status` | `unverified` / `pending` / `verified` / `suspended` | Lifecycle state — drives Journey entry, exit, and audience filters. Suspended users typically receive only transactional and account-recovery messages.                                                                                                                                                               |
| `kyc_completed`  | `1` (set when verified)                             | Confirms identity verification. Absence is your highest-priority compliance segment.                                                                                                                                                                                                                                  |
| `account_type`   | `personal` / `joint` / `business` / `trust`         | Account ownership structure. Drives disclosure and consent copy — joint, business, and trust accounts have different signing, authority, and notice requirements than personal accounts. For *which products* a user holds (checking, savings, credit card, etc.), use [Product holdings](#product-holdings) instead. |
| `risk_tier`      | `low` / `medium` / `high`                           | Drive frequency of security messaging and compliance disclosures based on risk classification. Powers the High-Risk Users segment for tighter security cadences.                                                                                                                                                      |
| `jurisdiction`   | ISO 3166-2 code (e.g., `US-CA`, `GB`, `DE`)         | Tailor disclosure copy, frequency caps, and channel choices by regulatory region. Use a coarser bucket (`us` / `eu` / `apac`) if your messaging policy doesn't vary at the state/province level.                                                                                                                      |
| `signup_date`    | Unix timestamp (seconds)                            | Account creation moment. Use [time operators](./time-operators) to trigger tenure-based Journeys — for example, "90 days after signup, send a credit card cross-sell" or "365 days, send an anniversary email."                                                                                                       |

#### Security and trust

| Tag                       | Values                                    | Use                                                                                                                    |
| :------------------------ | :---------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
| `2fa_enabled`             | `1` (set when enabled)                    | Security state. Absence is the entry segment for the 2FA setup Journey.                                                |
| `email_verified`          | `1` (set when confirmed)                  | Required before sending any marketing or transactional email.                                                          |
| `phone_verified`          | `1` (set when confirmed)                  | Required before sending any SMS.                                                                                       |
| `password_last_changed`   | Unix timestamp (seconds)                  | Use [time operators](./time-operators) to prompt password rotation on policy intervals.                                |
| `marketing_consent_email` | `1` (set when granted, removed on revoke) | Required filter on every marketing email Journey. Absence excludes the user — transactional flows are unaffected.      |
| `marketing_consent_sms`   | `1` (set when granted, removed on revoke) | Required filter on every marketing SMS Journey. Especially important under TCPA and similar SMS-marketing regulations. |

#### Engagement and value

| Tag                           | Values                                                | Use                                                                  |
| :---------------------------- | :---------------------------------------------------- | :------------------------------------------------------------------- |
| `first_transaction_completed` | `1` (set when complete)                               | Confirms activation. Absence is the highest-leverage growth segment. |
| `last_transaction_date`       | Unix timestamp (seconds)                              | Drives recency-based win-back and dormancy messaging.                |
| `total_balance_cents`         | integer (as string)                                   | Power high-value-customer segments for premium offers.               |
| `customer_tier`               | `retail` / `premium` / `accredited` / `institutional` | Tailor copy, offers, and disclosures by customer classification.     |

#### Product holdings

Track which products and features a user has adopted. These Tags do double duty: as **filters** for cross-sell audiences ("checking but no card"), and as **exclusions** so you never pitch a product the user already owns.

| Tag                      | Values                                                       | Use                                                                                                                        |
| :----------------------- | :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `has_checking`           | `1` (set when active)                                        | Foundation product — most cross-sell flows assume this is set.                                                             |
| `has_savings`            | `1` (set when active)                                        | Cross-sell anchor for higher-tier savings, money-market, or CD products.                                                   |
| `has_credit_card`        | `1` (set when active)                                        | Excludes user from credit-card promotion Journeys; enables card-specific campaigns (rewards, statement reminders).         |
| `has_investment_account` | `1` (set when active)                                        | Cross-sell from cash to brokerage, robo-advisor, or self-directed investing.                                               |
| `has_loan`               | `1` (set when active)                                        | Eligibility for loan-management messaging and refi offers.                                                                 |
| `direct_deposit_active`  | `1` (set when an incoming payroll-class deposit is detected) | Strongest engagement signal in banking. Powers "set up direct deposit" Journey audiences and primary-bank retention flows. |

#### Personalization

| Tag                  | Values                                      | Use                                                        |
| :------------------- | :------------------------------------------ | :--------------------------------------------------------- |
| `first_name`         | string                                      | Personalize message content (e.g., `Hi {{ first_name }}`). |
| `acquisition_source` | `referral` / `organic` / `paid` / `partner` | Tailor onboarding messaging to where the user came from.   |

<Card title="Add user data tags" icon="tags" href="./add-user-data-tags">
  Add key-value pairs to user profiles for segmentation and personalization.
</Card>

### Custom Events

Send a Custom Event for each moment you want to react to. Events are stored shorter-term than Tags but can carry properties (transaction amount, currency, transaction type), making them ideal for Journey entry triggers, Wait Until conditions, and Liquid personalization. Use lowercase `snake_case` for event names and keep them consistent across your app and backend.

| Event                               | Use case                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signup_completed`                  | Welcome and verification Journey entry. Carry `acquisition_source` if you Tag it so onboarding copy can vary by channel (paid vs organic vs referral).                                                                                                                                                                                 |
| `verification_started`              | Wait Until anchor — branch on whether the user finishes KYC inside an expiration window.                                                                                                                                                                                                                                               |
| `verification_completed`            | Exit verification Journey; thank-you and next-step message.                                                                                                                                                                                                                                                                            |
| `2fa_enabled`                       | Exit 2FA setup Journey; security-confirmation message.                                                                                                                                                                                                                                                                                 |
| `first_transaction_completed`       | Exit onboarding promotion Journey; first-action celebration. Carry `type` (e.g., `deposit` / `trade` / `payment`) and `amount` as properties so the celebration message can reference the specific action the user took.                                                                                                               |
| `transaction_completed`             | Transactional receipt push and email. Carry `amount`, `currency`, `transaction_type`, and `is_first` as properties so receipt copy renders with the right values and first-transaction Journeys branch on the same event.                                                                                                              |
| `transaction_failed`                | Trigger a recovery message with a clear retry path. Carry `failure_reason` (`insufficient_funds`, `card_declined`, `compliance_hold`, etc.) and `retry_url` so the message can deep-link the user to the right resolution.                                                                                                             |
| `large_transaction`                 | Optional fraud-aware confirmation — "Was this you?" with a quick deny path. Carry `amount`, `currency`, and `merchant` (or counterparty) as properties; threshold the trigger by `risk_tier` if you have it.                                                                                                                           |
| `device_added` / `password_changed` | Security event confirmations. Required by many regulators. Carry `device_name` / `ip_country` (for `device_added`) or `change_method` (for `password_changed`) so the confirmation message can describe what happened.                                                                                                                 |
| `application_started`               | User opened an application for a new product (credit card, loan, additional account). Wait Until anchor — branch on completion vs abandonment with a 7-day expiration. Carry `product` (e.g., `credit_card`, `loan`, `savings`) as a property.                                                                                         |
| `feature_enrolled`                  | User signed up for or activated a new product or feature. Exit cross-sell Journey; trigger a thank-you and next-step message. Carry `feature` (e.g., `credit_card`, `direct_deposit`, `auto_invest`) as a property. After firing, also set the corresponding `has_*` Tag so the user is excluded from future pitches for that product. |
| `promotion_redeemed`                | User claimed a promotional offer (signup bonus, referral reward, seasonal promo). Carry `promo_code` and `value_cents` as properties.                                                                                                                                                                                                  |

<Card title="Custom Events" icon="bolt" href="./custom-events">
  Capture user actions and use them to trigger Journeys or Wait Until steps.
</Card>

### Segments

Combine Tags and Custom Events into segments. Start with these eleven:

| Segment                          | Definition                                                                                                                                          |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unverified Users                 | `kyc_completed` does not exist. Highest-priority compliance segment.                                                                                |
| Pending verification             | `account_status = "pending"`. In-flight KYC submissions awaiting review.                                                                            |
| 2FA disabled                     | `2fa_enabled` does not exist AND `account_status = "verified"`. Security uplift segment.                                                            |
| New Users — first action pending | `account_status = "verified"` AND `first_transaction_completed` does not exist. Onboarding promotion target.                                        |
| Active Traders                   | `transaction_completed` in the last 7 days, with N+ events. Engaged core.                                                                           |
| Cross-sell — credit card         | `has_checking = "1"` AND `has_credit_card` does not exist AND `Last Session < 30 days`. Active customers eligible for credit-card promotion.        |
| Direct-deposit candidates        | `has_checking = "1"` AND `direct_deposit_active` does not exist. Highest-leverage engagement and primary-bank uplift in retail banking.             |
| Dormant Accounts                 | `Last Session > 30 days` AND `account_status = "verified"`. Re-engagement target.                                                                   |
| High-Value Customers             | `customer_tier = "premium"` OR `total_balance_cents > 5000000`. Premium offer audience.                                                             |
| High-Risk Users                  | `risk_tier = "high"`. Tighter security cadence — faster `device_added` / `password_changed` confirmations and lower `large_transaction` thresholds. |
| Suspended                        | `account_status = "suspended"`. Restrict to account-recovery and required regulatory messages only.                                                 |

<Note>
  Mature fintech setups run 20+ segments split by jurisdiction, product holdings, and regulatory classification. Start with the eleven above, then add depth (additional product-holding combinations, market-data permissions, accredited-investor flags) as your Journeys grow.
</Note>

<Card title="Segmentation" icon="users" href="./segmentation">
  Group users by shared characteristics to target Journeys and campaigns.
</Card>

## Journey examples

With Tags, Custom Events, and segments in place, build Journeys against them. Fintech Journeys mix channels by intent — push and in-app for in-the-moment nudges, email for receipts, statements, and longer-form content, and SMS for high-trust moments like verification, 2FA codes, and large-transaction confirmations. The lifecycle has six core flows:

<Columns>
  <Card title="New user verification" icon="id-card" href="./event-driven-journeys">
    Multi-channel KYC reminders across push, email, and SMS in the first 48 hours, entered on `signup_completed` and exited on `verification_completed`.
  </Card>

  <Card title="2FA setup" icon="lock" href="./event-driven-journeys">
    Identify users without `2fa_enabled` and run a security-uplift Journey before their first transaction.
  </Card>

  <Card title="First transaction promotion" icon="circle-dollar-to-slot" href="./mobile-first-journeys#welcome-journeys">
    Day 1 / 2 / 4 / 6 onboarding cadence to drive the first deposit, trade, or payment.
  </Card>

  <Card title="Feature adoption / cross-sell" icon="layer-group" href="./event-driven-journeys">
    Identify customers with product-holding gaps (e.g., checking but no card) and run targeted cross-sell Journeys, exited on `feature_enrolled` or `application_started`.
  </Card>

  <Card title="Transactional alerts" icon="bell" href="./transactional-messages">
    Real-time receipts, balance updates, and security confirmations.
  </Card>

  <Card title="Re-engagement (Dormant Accounts)" icon="rotate-left" href="./mobile-first-journeys#retention-journeys">
    Catch users with no activity in 30+ days before they fully disengage.
  </Card>
</Columns>

<Frame>
  <iframe title="Multi-channel new user verification for fintech" />
</Frame>

### Common fintech patterns

* **Multi-channel verification.** Don't rely on email alone for KYC reminders — bounce rates and inbox placement vary, and verification has a hard time window. A push + email + SMS cadence across the first 48 hours measurably lifts completion. Trigger from `signup_completed` and exit on `verification_completed`.
* **2FA setup uplift.** Identify users with `2fa_enabled` absent and run a 7-day Journey of in-app messages and emails framing 2FA as account protection, not friction. Pair with a hard gate on high-risk actions (transfers above a threshold) to make the upside concrete.
* **First-action promotion.** A common new-user cadence is **Day 1, Day 2, Day 4, Day 6** following verification, each surfacing a specific first action — deposit, trade, payment — with a small incentive ("\$10 toward your first trade") to clear the activation hurdle. Exit on `first_transaction_completed`.
* **Feature adoption and cross-sell.** Use [Product holdings](#product-holdings) Tags as exclusion segments — never pitch a product the user already owns. Trigger cross-sell Journeys from a lifecycle moment (90 days after `signup_date`, or post-`first_transaction_completed`) and use `application_started` as a Wait Until anchor with a 7-day expiration to branch on whether the user finishes the application. Exit on `feature_enrolled`, and have your backend set the matching `has_*` Tag so the user is permanently excluded from that pitch.
* **Promotional offers.** Pair a `promotion_redeemed` event with a `promo_code` property to measure each campaign's funnel and to attribute downstream activity. Exclude users who already redeemed a promo from re-targeted versions of the same offer to avoid awkward repeat pitches.
* **Transactional alerts.** Status, money received, balance changes, payments, and identity-verification confirmations should all flow as transactional messages. Send these via the [Transactional messages API](./transactional-messages) so they bypass marketing-consent gates and meet delivery-time expectations.
* **Security event confirmations.** `device_added`, `password_changed`, and `large_transaction` events should trigger immediate confirmation messages. Many regulators require these; users expect them as a sign of a trustworthy product.
* **Risk-tier-aware cadence.** Use the `risk_tier` Tag to scale security and disclosure messaging. The High-Risk Users segment gets tighter cadences on `device_added` and `password_changed` confirmations, lower `large_transaction` thresholds, and faster expirations on Wait Until branches that gate sensitive actions.
* **Jurisdiction-aware copy.** Use the `jurisdiction` Tag to vary disclosure language, frequency caps, and channel choice — for example, holding back marketing SMS in TCPA-heavy regions or swapping in EU-specific privacy copy for `eu` users. See [Liquid syntax](./using-liquid-syntax) for how to branch message content on Tag values.
* **Marketing-consent gating.** Filter every marketing Journey on `marketing_consent_email = "1"` (or `marketing_consent_sms = "1"`). Transactional Journeys via the [Transactional messages API](./transactional-messages) are exempt — they aren't marketing messages and shouldn't be gated by consent.

<Frame>
  <iframe title="Driving 2FA setup with messaging in fintech" />
</Frame>

Measure success by KYC completion rate (within 48 hours), 2FA enablement rate, time-to-first-transaction, and Active Traders retention — not just opens or CTR.

## FAQ

### How is this different from the Mobile-first strategy?

[Mobile-first](./mobile-first) targets subscription, freemium, and trial-driven apps where success is measured by trial-to-paid conversion. Fintech overlaps on the data foundation (External IDs, Tags, Custom Events, segments) but adds compliance state (`kyc_completed`, `account_status`), security state (`2fa_enabled`), and transactional moments as first-class concepts. The lifecycle is shaped around verification, security, and recurring transactions — not trial conversion.

### Should I send marketing and transactional messages from the same Journey?

No. Keep transactional flows (receipts, security alerts, verification confirmations) separate from marketing flows (promotions, upsells, re-engagement). Mixing them creates compliance risk — marketing-consent revocations should not silence transactional notices, and transactional messages should not be subject to marketing-frequency caps. Use the [Transactional messages API](./transactional-messages) for the former and standard Journeys for the latter.

### How do I handle messaging for suspended or restricted accounts?

Build a **Suspended** segment on `account_status = "suspended"` and use it as an **exclusion** segment on every marketing Journey. Transactional and account-recovery messages can still send — those are typically required regardless of marketing status — but promotional and engagement nudges should never reach users in a restricted state.

### When should I use SMS over push?

SMS is appropriate for high-trust, time-sensitive moments where push delivery is unreliable or the user isn't logged in: verification codes, 2FA codes, suspicious-activity alerts, and large-transaction confirmations. It's also the right channel when the user might be locked out of the app. Avoid SMS for marketing — the cost-per-message is high, opt-out rates are punishing, and many jurisdictions have strict marketing-SMS regulations.

### Do I need data integrations to use these Journeys?

No. You can build basic verification reminders and re-engagement using dashboard-only segments like "First Session" and "Last Session." Custom Events and Tags give you precise compliance-aware triggers and exit conditions, but they are not required to ship the first version.

### What about apps that mix banking with other products (e.g., insurance, lending)?

The data foundation extends naturally. Use the [Product holdings](#product-holdings) Tags as filters and exclusion segments on top of the base lifecycle audiences — and add product-specific Tags (`has_insurance`, `has_mortgage`) and Custom Events as you launch new lines. Each product line typically gets its own Journey set with the shared compliance and security flows running underneath.

## Related pages

<Columns>
  <Card title="Mobile-first strategies" icon="mobile" href="./mobile-first">
    Sister hub for subscription, freemium, and trial-driven mobile apps.
  </Card>

  <Card title="Mobile-first lifecycle Journeys" icon="route" href="./mobile-first-journeys">
    Welcome, event-driven, and retention Journey patterns adaptable to fintech onboarding and dormancy.
  </Card>

  <Card title="Transactional messages" icon="paper-plane" href="./transactional-messages">
    Send receipts, balance updates, and security confirmations through the API.
  </Card>

  <Card title="Event-driven Journeys" icon="bolt" href="./event-driven-journeys">
    Trigger Journeys from `transaction_completed`, `verification_completed`, and other lifecycle events.
  </Card>

  <Card title="Magic link and OTP verification" icon="key" href="./example-verification-magic-link-otp">
    Send one-time passwords, magic links, and verification emails for KYC, sign-in, and high-trust actions.
  </Card>

  <Card title="Push fallback to email or SMS" icon="arrows-rotate" href="./push-fallback-method">
    Reach users via email or SMS when push delivery fails for security and high-priority moments.
  </Card>
</Columns>


# Flash sale Journey
Source: https://documentation.onesignal.com/docs/en/flash-sale

Build an automated flash sale campaign that drives conversions during a time-limited promotion, from a simple time-based flow to a fully personalized Journey with VIP early access and buyer suppression.

This tutorial walks through a complete flash sale Journey using **Black Friday** as the running example (40% off sitewide, midnight to midnight). The pattern applies to any time-limited promotion.

* **Case 1 – Basic:** Pure time-based, no tags. Everyone receives the same messages at scheduled times. Good for your first flash sale or teams without tag infrastructure.
* **Case 2 – Advanced:** Uses tags (`vip_customer`, `wishlist_count`, `last_purchase_date`) for VIP early access, wishlist personalization, and buyer suppression. Start with Case 1 and layer in Case 2 targeting as your data matures.

***

## At a glance

Setup is the same for both cases. The only difference is how targeting and branching are applied.

1. Define the [entry segment](#segments).
2. Build the [push, email, and in-app message templates](#templates).
3. Configure [Journey entry, exit, and re-entry rules](#journey-settings).
4. Wire up the Journey steps:
   * **Case 1:** [Linear flow with Wait nodes](#case-1-basic-time-based-journey), everyone gets the same messages.
   * **Case 2:** [Add VIP branch, wishlist branch, and buyer suppression](#case-2-advanced-tag-based-journey).

***

## Campaign goals

| Goal                                       | How this campaign achieves it                                   |
| ------------------------------------------ | --------------------------------------------------------------- |
| **Build pre-sale anticipation**            | Email + in-app message before the sale                          |
| **Remind users the day before**            | Push the day before to keep the sale top of mind                |
| **Announce the sale launch**               | Email + in-app message when the sale goes live                  |
| **Re-engage mid-sale**                     | Push a few hours after launch for non-visitors                  |
| **Final email reminder**                   | Email halfway through to recover non-purchasers                 |
| **Last-chance urgency**                    | Push 2 hours before the sale ends                               |
| **Personalize and protect trust** (Case 2) | VIP early access, wishlist push, and buyer suppression via tags |

***

## Prerequisites

* A OneSignal account with push notifications set up for your app or site
* Push permission enabled for your users
* Familiarity with [Journeys](./journeys-overview) concepts (entry/exit rules, message and action steps, etc.)
* Email channel set up if you want to send emails (see [Email setup](./email-setup))
* In-app messaging enabled if you want to show banners during the sale window (see [In-app messages setup](./in-app-messages-setup))

Case 2 also requires tags maintained by your backend. See [Case 2: Advanced tag-based Journey](#case-2-advanced-tag-based-journey).

## Segments

**Entry segment (both cases):**

* Name: "Total Subscriptions"
* Built-in, no setup needed. All push-subscribed users enter the Journey.

**VIP segment (Case 2 only):**

* Name: "VIP Customers"
* Filter: **User Tag** `vip_customer` · operator **is** · value `true`

**Wishlist segment (Case 2 only):**

* Name: "Wishlist Users"
* Filter: **User Tag** `wishlist_count` · operator **greater than** · value `0`

## Templates

These templates are starting points: clone, edit, and re-use them in your own Journey. They use [Liquid syntax](./using-liquid-syntax) for personalization.

<Tabs>
  <Tab title="Push Notification templates">
    | When                                 | Name             | Title                                 | Message                                                                                         |
    | ------------------------------------ | ---------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------- |
    | Day before sale                      | Sale tomorrow    | 🛍️ Tomorrow only. 40% off sitewide.  | Your Black Friday sale starts at midnight tonight. Don't miss it.                               |
    | Mid-sale                             | Mid-sale nudge   | ⏰ Still going, 40% off ends tonight   | The Black Friday sale is still live. Don't leave your items behind.                             |
    | 2 hours before close                 | Last chance      | 🔥 2 hours left, last chance          | The Black Friday sale closes at midnight. This is your last chance.                             |
    | Sale launch, VIPs (Case 2)           | VIP early access | 🎉 You're in early, \{\{first\_name}} | VIP early access is live. 40% off everything, shop before everyone else.                        |
    | Sale launch + 1 hour (Case 2)        | Sale launch      | 🛍️ Black Friday is LIVE              | 40% off sitewide, ends tonight at midnight. Shop now.                                           |
    | Sale launch, wishlist users (Case 2) | Wishlist on sale | 💜 Your saved items are 40% off       | You have \{\{user.tags.wishlist\_count}} items on your wishlist. They're all on sale right now. |

    <Columns>
      <Card title="Templates" icon="clone" href="./templates">
        Create and manage reusable message templates.
      </Card>

      <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
        Overview of all personalization options available in OneSignal.
      </Card>
    </Columns>
  </Tab>

  <Tab title="Email templates">
    Emails carry the long-form moments of the Journey. Three emails fire: pre-sale excitement, sale launch, and a halfway reminder.

    **Pre-sale excitement (2 days before)**

    *Purpose:* Build anticipation and drive wishlist adds before the sale opens.

    *Suggested subject:* Black Friday is almost here 🛍️

    *Content outline:*

    * A teaser of what's coming (40% off everything)
    * Preview of featured products or categories
    * CTA to browse and add items to wishlist
    * Countdown to sale start

    **Sale is live (sale day)**

    *Purpose:* Announce the sale launch and drive immediate traffic.

    *Suggested subject:* Black Friday is LIVE, 40% off everything

    *Content outline:*

    * Bold announcement that the sale has started
    * Featured deals and product highlights
    * Clear CTA to shop now
    * Sale end time prominently displayed

    **Final reminder (halfway through sale)**

    *Purpose:* Recover users who haven't purchased yet.

    *Suggested subject:* Don't miss out, sale ends tonight

    *Content outline:*

    * Reminder that time is running out
    * Highlight top-selling or low-stock items
    * Urgency messaging with countdown
    * CTA to complete purchase

    <Columns>
      <Card title="Email messaging" icon="envelope" href="./email-messaging">
        Create and send email campaigns.
      </Card>

      <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
        Overview of all personalization options available in OneSignal.
      </Card>
    </Columns>
  </Tab>

  <Tab title="In-App Message templates">
    In-app messages fire when users open your app. Two are included: a pre-sale teaser and a sale-day banner.

    **Pre-sale excitement (2 days before)**

    Use a banner or modal to build anticipation:

    * Headline: "Black Friday is coming!"
    * Body: "40% off everything starts Friday at midnight. Add items to your wishlist now."
    * CTA: Deep link to wishlist or sale preview page

    **Sale is live banner (sale day)**

    Show a banner when users open the app during the sale:

    * Headline: "Black Friday is LIVE"
    * Body: "40% off sitewide, ends at midnight"
    * CTA: Deep link to sale page

    <Columns>
      <Card title="Design your in-app message" icon="pen-ruler" href="./design-your-in-app-message">
        Full reference for the in-app message editor.
      </Card>

      <Card title="Deep linking" icon="arrow-up-right-from-square" href="./deep-linking">
        Route users to the correct page.
      </Card>
    </Columns>
  </Tab>
</Tabs>

## Journey configuration

Both cases share the same Journey settings. Define them once and use them for either case.

### Journey settings

| Setting      | Value                                             |
| ------------ | ------------------------------------------------- |
| **Entry**    | Audience Segment: "Total Subscriptions"           |
| **Exit**     | User reaches the end of the flow                  |
| **Re-entry** | No, users receive this Journey only once per sale |

***

## Case 1: Basic time-based Journey

This Journey runs entirely on time-based **Wait** nodes. No tags, no targeting. Everyone receives the same messages at scheduled times. Set it live 2 days before the sale opens.

### Journey timing

The campaign progresses through anticipation (2 days before through the day before), launch (sale day), and urgency (afternoon through close):

| Step | When                          | Channel     | Purpose              |
| ---- | ----------------------------- | ----------- | -------------------- |
| 1    | 2 days before sale (on entry) | Email + IAM | Build excitement     |
| 2    | Day before sale               | Push        | Sale starts tomorrow |
| 3    | Sale launch                   | Email + IAM | Sale is live         |
| 4    | A few hours after launch      | Push        | Mid-sale nudge       |
| 5    | Halfway through sale          | Email       | Final email reminder |
| 6    | 2 hours before close          | Push        | Last chance          |

### Basic Journey steps

<Steps>
  <Step title="Email + In-App Message: Pre-sale excitement (2 days before)">
    **Goal:** Build anticipation a few days before the sale.

    Add an **Email** node as the first step, then an **In-App Message** node immediately after.

    The email lands when the user enters the Journey. The IAM is queued and displays the next time they open your app.
  </Step>

  <Step title="Wait: 1 day">
    **Goal:** Advance to the day before the sale.

    Add a **Wait** node set to **1 day**.
  </Step>

  <Step title="Push Notification: Sale starts tomorrow (day before)">
    **Goal:** Reminder the day before.

    Add a **Push Notification** node.

    | Field          | Value                                                               |
    | -------------- | ------------------------------------------------------------------- |
    | **Title**      | `Tomorrow only. 40% off sitewide.`                                  |
    | **Body**       | `Your Black Friday sale starts at midnight tonight. Don't miss it.` |
    | **Launch URL** | Your sale landing page                                              |
  </Step>

  <Step title="Wait: 1 day">
    **Goal:** Advance to sale day.

    Add a **Wait** node set to **1 day**.
  </Step>

  <Step title="Email + In-App Message: Sale is live (sale day)">
    **Goal:** Announce the sale launch.

    Add an **Email** node, then an **In-App Message** node.

    The email announces the sale is live. The IAM displays a sale banner when users open the app.
  </Step>

  <Step title="Wait: a few hours">
    **Goal:** Give users time to see the launch messages before the mid-sale nudge.

    Add a **Wait** node set to **3–4 hours** (adjust based on your sale duration).
  </Step>

  <Step title="Push Notification: Mid-sale nudge">
    **Goal:** Re-engage users who haven't visited yet.

    Add a **Push Notification** node.

    | Field          | Value                                                                 |
    | -------------- | --------------------------------------------------------------------- |
    | **Title**      | `Still going, 40% off ends tonight`                                   |
    | **Body**       | `The Black Friday sale is still live. Don't leave your items behind.` |
    | **Launch URL** | Your sale page                                                        |
  </Step>

  <Step title="Wait: until halfway through sale">
    **Goal:** Advance to the halfway point.

    Add a **Wait** node. For a 24-hour sale that started at midnight, set this to **6–8 hours** to land around midday/afternoon.
  </Step>

  <Step title="Email: Final reminder">
    **Goal:** Last email push to recover non-purchasers.

    Add an **Email** node with urgency messaging and countdown.
  </Step>

  <Step title="Wait: until 2 hours before end">
    **Goal:** Advance to the final urgency window.

    Add a **Wait** node to land **2 hours before the sale ends**. For a midnight-to-midnight sale, this is around 10 PM.
  </Step>

  <Step title="Push Notification: Last chance">
    **Goal:** Final urgency push.

    Add a **Push Notification** node.

    | Field          | Value                                                                 |
    | -------------- | --------------------------------------------------------------------- |
    | **Title**      | `2 hours left, last chance`                                           |
    | **Body**       | `The Black Friday sale closes at midnight. This is your last chance.` |
    | **Launch URL** | Your sale page or cart                                                |
  </Step>
</Steps>

### Best practices for Case 1

* **Set the Journey live 2 days before the sale.** The pre-sale email fires immediately for users who enter.
* **Respect quiet hours.** Avoid sending pushes between 10 PM and 7 AM in the user's timezone. Adjust Wait nodes if needed.
* **Pause the Journey if the sale ends early.** From the dashboard, pause stops remaining Wait nodes and prevents any remaining messages from firing.
* **[Deep-link](./deep-linking) every message to the right page.** Tapping a push should land users on the sale page, not the app home.

***

## Case 2: Advanced tag-based Journey

Case 2 builds on Case 1 by adding targeting with tags. The timing is the same, but you add:

* **VIP early access:** VIPs get a 1-hour head start at sale launch
* **Wishlist personalization:** Users with wishlist items get a personalized push
* **Buyer suppression:** Filter out buyers from urgency messages

### Required tags

| Tag                  | Type                     | Description                                                                                |
| -------------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
| `vip_customer`       | Boolean                  | `true` if the user is a VIP customer                                                       |
| `wishlist_count`     | Number                   | Count of items in the user's wishlist                                                      |
| `last_purchase_date` | Unix timestamp (seconds) | Time of the user's most recent purchase, stored as a Unix timestamp in seconds (10 digits) |

These tags must be maintained by your backend and synced to OneSignal. See [Tags](./add-user-data-tags) for setup.

<Note>
  The `time elapsed greater than` operator compares the current time to a Unix timestamp stored on the tag. Store `last_purchase_date` as a **Unix timestamp in seconds** (10 digits), not milliseconds or a formatted date. See [Tags: Time Operators](./time-operators) for details.
</Note>

### Advanced Journey steps

Case 2 follows the same overall timing as Case 1, but adds a VIP branch at launch, a wishlist branch right after, and a buyer-suppression filter on every urgency message.

<Steps>
  <Step title="Email + In-App Message: Pre-sale excitement (2 days before)">
    **Goal:** Build anticipation a few days before the sale.

    Add an **Email** node as the first step, then an **In-App Message** node immediately after.

    The email lands when the user enters the Journey. The IAM is queued and displays the next time they open your app.
  </Step>

  <Step title="Wait: 1 day">
    **Goal:** Advance to the day before the sale.

    Add a **Wait** node set to **1 day**.
  </Step>

  <Step title="Push Notification: Sale starts tomorrow (day before)">
    **Goal:** Reminder the day before.

    Add a **Push Notification** node.

    | Field          | Value                                                               |
    | -------------- | ------------------------------------------------------------------- |
    | **Title**      | `Tomorrow only. 40% off sitewide.`                                  |
    | **Body**       | `Your Black Friday sale starts at midnight tonight. Don't miss it.` |
    | **Launch URL** | Your sale landing page                                              |
  </Step>

  <Step title="Wait: 1 day">
    **Goal:** Advance to sale day.

    Add a **Wait** node set to **1 day**.
  </Step>

  <Step title="Branch: VIP / General split (sale launch)">
    **Goal:** Give VIPs a 1-hour head start.

    Add a **Yes/No Branch** node:

    * **Condition:** **User Tag** `vip_customer` · operator **is** · value `true`

    **Yes branch (VIP):** Add a **Push Notification** node immediately:

    | Field          | Value                                                                      |
    | -------------- | -------------------------------------------------------------------------- |
    | **Title**      | `You're in early, {{first_name}} 🎉`                                       |
    | **Body**       | `VIP early access is live. 40% off everything, shop before everyone else.` |
    | **Launch URL** | Your sale page                                                             |

    **No branch (general):** Add a **Wait** node set to **1 hour**, then a **Push Notification** node:

    | Field          | Value                                                   |
    | -------------- | ------------------------------------------------------- |
    | **Title**      | `Black Friday is LIVE 🛍️`                              |
    | **Body**       | `40% off sitewide, ends tonight at midnight. Shop now.` |
    | **Launch URL** | Your sale page                                          |
  </Step>

  <Step title="Email + In-App Message: Sale is live">
    **Goal:** Announce the sale to everyone.

    Connect both branches into the same next node. Add an **Email** node, then an **In-App Message** node. The email announces the sale is live and the IAM displays a sale banner when users open the app.
  </Step>

  <Step title="Branch: Wishlist personalization">
    **Goal:** Send a personalized push to wishlist users.

    Add a **Yes/No Branch** node:

    * **Condition:** **User Tag** `wishlist_count` · operator **greater than** · value `0`

    **Yes branch (wishlist users):** Add a **Push Notification** node:

    | Field          | Value                                                                                          |
    | -------------- | ---------------------------------------------------------------------------------------------- |
    | **Title**      | `Your saved items are 40% off`                                                                 |
    | **Body**       | `You have {{user.tags.wishlist_count}} items on your wishlist. They're all on sale right now.` |
    | **Launch URL** | Your wishlist page                                                                             |

    **No branch (no wishlist):** Continue with no message.

    Connect both branches into the next step.
  </Step>

  <Step title="Wait: a few hours">
    **Goal:** Give users time before the mid-sale nudge.

    Add a **Wait** node set to **3–4 hours**.
  </Step>

  <Step title="Branch + Push: Mid-sale nudge (buyer suppression)">
    **Goal:** Nudge non-buyers only.

    Add a **Yes/No Branch** node. Match **any** of these filters:

    * **User Tag** `last_purchase_date` · operator **time elapsed greater than** · value `4 hours`
    * **User Tag** `last_purchase_date` · operator **does not exist**

    Adjust the `4 hours` value based on how long after sale launch this step fires in your Journey.

    **Yes branch (non-buyers):** Add a **Push Notification** node:

    | Field          | Value                                                                 |
    | -------------- | --------------------------------------------------------------------- |
    | **Title**      | `Still going, 40% off ends tonight`                                   |
    | **Body**       | `The Black Friday sale is still live. Don't leave your items behind.` |
    | **Launch URL** | Your sale page                                                        |

    **No branch (buyers):** Skip the push, route directly to the next step.
  </Step>

  <Step title="Wait: until halfway through sale">
    Add a **Wait** node to reach the halfway point.
  </Step>

  <Step title="Branch + Email: Final reminder (buyer suppression)">
    **Goal:** Email non-buyers only.

    Add a **Yes/No Branch** node. Match **any** of these filters:

    * **User Tag** `last_purchase_date` · operator **time elapsed greater than** · value `12 hours` (halfway through a 24-hour sale)
    * **User Tag** `last_purchase_date` · operator **does not exist**

    **Yes branch (non-buyers):** Add an **Email** node with urgency messaging.

    **No branch (buyers):** Skip the email.
  </Step>

  <Step title="Wait: until 2 hours before end">
    Add a **Wait** node to reach the final urgency window.
  </Step>

  <Step title="Branch + Push: Last chance (buyer suppression)">
    **Goal:** Final push to non-buyers only.

    Add a **Yes/No Branch** node. Match **any** of these filters:

    * **User Tag** `last_purchase_date` · operator **time elapsed greater than** · value `22 hours` (two hours before a midnight close)
    * **User Tag** `last_purchase_date` · operator **does not exist**

    **Yes branch (non-buyers):** Add a **Push Notification** node:

    | Field          | Value                                                                 |
    | -------------- | --------------------------------------------------------------------- |
    | **Title**      | `2 hours left, last chance`                                           |
    | **Body**       | `The Black Friday sale closes at midnight. This is your last chance.` |
    | **Launch URL** | Your sale page or cart                                                |

    **No branch (buyers):** End of Journey.
  </Step>
</Steps>

<Warning>
  The `last_purchase_date` filter only suppresses buyers if your backend updates the tag in **near-real-time**. If your stack updates the tag nightly, buyers in the early hours of the sale will still receive urgency messages later that day. Verify the sync cadence before launch.
</Warning>

### Best practices for Case 2

* **Apply buyer suppression to every urgency message.** Without it, users who bought early still receive "last chance" pushes, which is the most common cause of unsubscribes after a flash sale.
* **Verify tag freshness** before launch by simulating a purchase and confirming the `last_purchase_date` tag updates within minutes.
* **All Case 1 best practices still apply.** Quiet hours, deep linking, and pausing the Journey if the sale ends early.
* **Be aware of message volume.** A VIP wishlist user who never buys can receive up to 4 pushes and 3 emails across the full sequence. Make sure that volume feels appropriate for your audience before launch.

***

## Compare Case 1 and Case 2

Both cases share the same entry segment, Journey settings, and templates. Case 2 adds targeting.

|                              | Case 1: Basic                              | Case 2: Advanced                                             |
| ---------------------------- | ------------------------------------------ | ------------------------------------------------------------ |
| **Data required**            | None                                       | Tags: `vip_customer`, `wishlist_count`, `last_purchase_date` |
| **Setup effort**             | Low, no tag infrastructure needed          | Medium, requires backend tag sync                            |
| **VIP early access**         | No, everyone gets sale launch at same time | Yes, VIPs get 1-hour head start                              |
| **Wishlist personalization** | No                                         | Yes, "your saved items are on sale" push                     |
| **Buyer suppression**        | No, everyone gets urgency messages         | Yes, filter out buyers via `last_purchase_date`              |
| **Best for**                 | First flash sale, no tag infrastructure    | Teams with existing tags, better UX                          |

***

## Where to go from here

Start with Case 1 if you're running your first flash sale or don't have tag infrastructure in place. As you add tags to your data layer, upgrade to Case 2 by adding the VIP branch, wishlist branch, and buyer-suppression filters. The VIP early access alone is worth the effort: it rewards your best customers and creates social proof when they share their finds.

After this Journey is live, consider adding SMS for the final urgency push (see [SMS messaging](./sms-messaging)) or extending the pattern to other time-limited promotions like summer sales, anniversary events, or new product launches.

***

## Related pages

<Columns>
  <Card title="Journeys overview" icon="route" href="./journeys-overview">
    Learn how to build, branch, and manage automated message flows.
  </Card>

  <Card title="Message personalization" icon="user" href="./message-personalization">
    Use Liquid tags to personalize message copy with user data.
  </Card>

  <Card title="Segments" icon="filter" href="./segmentation">
    Build reusable audiences based on tags, behavior, and more.
  </Card>

  <Card title="In-app messages" icon="mobile" href="./in-app-messages-setup">
    Create banners and modals to reach users inside your app.
  </Card>

  <Card title="Email setup" icon="envelope" href="./email-setup">
    Configure email messaging for your campaigns.
  </Card>

  <Card title="Tags" icon="tag" href="./add-user-data-tags">
    Add custom data to user profiles for targeting and personalization.
  </Card>
</Columns>


# Flutter SDK setup
Source: https://documentation.onesignal.com/docs/en/flutter-sdk-setup

Instructions for adding the OneSignal Flutter SDK to your Flutter app for iOS and Android

<SdkReleasesIframe />

## Overview

This guide explains how to integrate OneSignal push notifications into a Flutter application. It covers everything from installation to configuration and service worker management.

### Requirements

* Flutter 3.29.0+
* Configured OneSignal app and platform

**iOS Requirements**

* macOS with Xcode 14+ (setup instructions use Xcode 16.2)
* Device with iOS 12+, iPadOS 12+, or Xcode simulator running iOS 16.2+
* Swift Package Manager (requires opt-in) or CocoaPods 1.16.2+

**Android Requirements**

* Android 7.0+ device or emulator with Google Play Store (Services) installed

### Configure your OneSignal app and platform

Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).

<Note>
  If your organization already has a OneSignal account, [ask to be invited](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Step-by-step setup instructions" icon="circle-chevron-down">
  <Steps>
    <Step title="Create or select your app">
      Create a new app by clicking **New App/Website**, or add a platform to an existing app in **Settings > Push & In-App**. Select the platform(s) you want to configure and click **Next: Configure Your Platform**.

      <Frame>
        <img alt="OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection" />
      </Frame>
    </Step>

    <Step title="Configure platform credentials">
      Enter the credentials for your platform:

      * **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
      * **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
      * **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
      * **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)

      Click **Save & Continue** after entering your credentials.
    </Step>

    <Step title="Save your App ID and install the SDK">
      Your **App ID** is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.

      <Frame>
        <img alt="OneSignal dashboard showing the App ID and team invite option after setup" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

***

## SDK setup

### 1. Add SDK

Add the `onesignal_flutter` package to your `pubspec.yaml` file under `dependencies`:

```yaml pubspec.yaml theme={null}
  dependencies:
  	onesignal_flutter: ^5.1.2
```

Run `flutter pub get` to install the SDK.

<Note>
  **Swift Package Manager (SPM):** Starting with version 5.5.0, the OneSignal Flutter SDK supports SPM for iOS. SPM is not enabled by default — you must opt in by running `flutter config --enable-swift-package-manager`. Once enabled, Flutter handles SPM integration automatically.

  If your project previously used CocoaPods and you want to migrate to SPM:

  1. Run `flutter config --enable-swift-package-manager`
  2. Delete `Podfile`, `Podfile.lock`, and `Pods/` directory
  3. Remove CocoaPods include lines from `ios/Flutter/Debug.xcconfig` and `ios/Flutter/Release.xcconfig`
  4. Run `flutter run`
</Note>

### Optional: Disable the location module

Starting with `onesignal_flutter` 5.6.0, you can exclude OneSignal's native location module from iOS and Android builds when your app does not use `OneSignal.Location`.

Set `ONESIGNAL_DISABLE_LOCATION=true` before resolving or building dependencies for Swift Package Manager (SPM), CocoaPods, and Android Gradle builds. The value is case-insensitive. You can also set it to `1`.

In GitHub Actions, set the variable once at the job or step level so SPM, CocoaPods, and Gradle builds inherit it:

```yaml theme={null}
env:
  ONESIGNAL_DISABLE_LOCATION: true
```

With the location module disabled, calls to `OneSignal.Location` are ignored on Android. `OneSignal.Location.isShared()` returns `false`.

#### Apply the change after packages are cached

The environment variable is only read when dependencies are resolved, and each platform caches the resolved set. If you change the variable in an existing project, clear the relevant cache and re-resolve dependencies in a shell where the variable is exported. Otherwise, a stale build can keep or drop the location module regardless of the new value.

<Warning>
  When using Xcode or Android Studio, launch the IDE from a terminal where `ONESIGNAL_DISABLE_LOCATION` is exported. IDEs launched from the Dock or Finder do not inherit variables set only in your shell profile.
</Warning>

### 2. Initialize SDK

In your `main.dart` file initialize OneSignal in your App's root component with the provided methods.

Replace `YOUR_APP_ID` with your OneSignal App ID found in your OneSignal dashboard **Settings > [Keys & IDs](./keys-and-ids)**.

<Note>
  If you don't have access to the OneSignal app, ask your [Team Members](./manage-team-members) to invite you.
</Note>

```javascript main.dart theme={null}
// Include the OneSignal package
import 'package:onesignal_flutter/onesignal_flutter.dart';

void main() {
  runApp(const MyApp());

  // Enable verbose logging for debugging (remove in production)
  OneSignal.Debug.setLogLevel(OSLogLevel.verbose);
  // Initialize with your OneSignal App ID
  OneSignal.initialize("YOUR_APP_ID");
  // Use this method to prompt for push notifications.
  // We recommend removing this method after testing and instead use In-App Messages to prompt for notification permission.
  OneSignal.Notifications.requestPermission(false);

}
```

<Warning>
  When implementing the [Push Notification Click Listener](./mobile-sdk-reference#push-notification-events), if the app is force-closed and you click a notification, the app will not open and the Click Listener will not register in `Debug` mode. To fix this, you can either:

  * Use a release build via flutter e.g. `flutter run --release` (requires a physical device)
  * Update the Xcode scheme to be `Release` not `Debug`
</Warning>

***

## Android setup

Make sure your OneSignal app is configured for the Android platform using your [Firebase credentials](/docs/en/android-firebase-credentials).

Set up your [notification icons](/docs/en/notification-icons) to match your app’s branding. If this step is skipped, a default bell icon will display for your push notifications.

**Build for Android**

At this point, you should be able to build and run your app on a physical Android device or emulator without issues.

<Check>
  After confirming that your Android build works:

  * Continue with the [iOS setup](#ios-setup), if applicable.
  * Or jump ahead to [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## iOS setup

Make sure your OneSignal app is configured for the iOS platform using either the [p8 Token (Recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 Certificate](/docs/en/ios-p12-generate-certificates).

Follow these steps to add push notifications to your iOS app, including support for [Badges](/docs/en/badges), [Confirmed receipt](/docs/en/confirmed-delivery), and images.

### 1. Add Push Notifications capability to app target

The [Push Notifications capability](https://developer.apple.com/documentation/UserNotifications/registering-your-app-with-apns#Enable-the-push-notifications-capability) allows your app to register a push token and receive notifications.

1. Open your app’s `.xcworkspace` file in Xcode.
2. Select **your app target > Signing & Capabilities**
3. Click **+ Capability** and add **Push Notifications** capability

<Frame>
  <img />
</Frame>

### 2. Add Background Modes capability to app target

This enables your app to wake in the background when push notifications arrive.

1. Add [Background Modes](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app) capability
2. Enable **Remote notifications**

<Frame>
  <img />
</Frame>

### 3. Add app target to App Group

[App Groups](https://developer.apple.com/documentation/xcode/configuring-app-groups/#Create-App-Groups-for-all-other-platforms) allow data sharing between your app and the Notification Service Extension. Required for confirmed receipt and Badges.

<Tabs>
  <Tab title="If you do NOT have an App Group configured">
    1. Add **App Groups** capability
    2. In the App Groups capability click **+**
    3. Add a new container ID in format: `group.your_bundle_id.onesignal`

    * Keep **group.** and **.onesignal** prefix and suffix. Replace **`your_bundle_id`** with your app's bundle identifier.
    * For example, bundle identifier `com.onesignal.MyApp`, will have the container name `group.com.onesignal.MyApp.onesignal`.

    <Frame>
      <img />
    </Frame>

    <Warning> Your App Group name must exactly match your bundle ID’s spelling and capitalization across all targets. </Warning>
  </Tab>

  <Tab title="If you DO have an App Group">
    1. Open your **App Target** and **OneSignalNotificationServiceExtension Target's** `Info.plist`
    2. Add a new property to the `Info.plist` for both targets:

    * **Key:** `OneSignal_app_groups_key`
    * **Value:** Your existing App Group name (e.g., `group.your-custom-group-id`)

    ```xml XML theme={null}
    <key>OneSignal_app_groups_key</key>
    <string>group.your-custom-group-id</string>
    ```

    <Frame>
      <img />
    </Frame>

    <Warning>
      Make sure to update the `OneSignal_app_groups_key` in **both** the App Target **and** OneSignalNotificationServiceExtension Target's `Info.plist`!
    </Warning>
  </Tab>
</Tabs>

### 4. Add Notification Service Extension

The [Notification Service Extension (NSE)](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications) enables rich notifications and confirmed receipt analytics.

1. In Xcode: **File > New > Target...**
2. Select **Notification Service Extension**, then **Next**.
3. Set the product name to `OneSignalNotificationServiceExtension` and press **Finish**.
4. Press **Don't Activate** on the Activate scheme prompt.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

Set the OneSignalNotificationServiceExtension **Minimum Deployment Target** to match your main app (iOS 15+ recommended).

<Info> If you're using CocoaPods, set the deployment version in your Podfile as well. </Info>

<Frame>
  <img />
</Frame>

### 5. Add NSE target to app group

Use the same App Group ID you added in step 3.

1. Go to **OneSignalNotificationServiceExtension > Signing & Capabilities**
2. Add **App Groups**
3. Add the exact same group ID

<Warning>
  If you are using a custom App Group name and not `group.your_bundle_id.onesignal` then make sure to add your App Group ID to both the App Target and OneSignalNotificationServiceExtension Target's `Info.plist`! See [step 3](#3-add-app-target-to-app-group) for more information.
</Warning>

<Frame>
  <img />
</Frame>

### 6. Update NSE code

1. Navigate to the **OneSignalNotificationServiceExtension** folder
2. Replace the contents of the `NotificationService.swift` or `NotificationService.m` file with the following:

<Frame>
  <img />
</Frame>

<CodeGroup>
  ```swift Swift theme={null}
  import UserNotifications
  import OneSignalExtension

  class NotificationService: UNNotificationServiceExtension {
      var contentHandler: ((UNNotificationContent) -> Void)?
      var receivedRequest: UNNotificationRequest!
      var bestAttemptContent: UNMutableNotificationContent?

      // Note this extension only runs when `mutable_content` is set
      // Setting an attachment or action buttons automatically sets the property to true
      override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
          self.receivedRequest = request
          self.contentHandler = contentHandler
          self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

          if let bestAttemptContent = bestAttemptContent {
              // DEBUGGING: Uncomment the 2 lines below to check this extension is executing
  //            print("Running NotificationServiceExtension")
  //            bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

              OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
          }
      }

      override func serviceExtensionTimeWillExpire() {
          // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
          if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
              OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
              contentHandler(bestAttemptContent)
          }
      }
  }
  ```

  ```objectivec Objective-C theme={null}
  #import <OneSignalExtension/OneSignalExtension.h>
  #import "NotificationService.h"

  @interface NotificationService ()

  @property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
  @property (nonatomic, strong) UNNotificationRequest *receivedRequest;
  @property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

  @end

  @implementation NotificationService

  // Note, this extension only runs when mutable-content is set
  // Setting an attachment or action buttons automatically adds this
  - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
      self.receivedRequest = request;
      self.contentHandler = contentHandler;
      self.bestAttemptContent = [request.content mutableCopy];

      // DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is executing
  //     NSLog(@"Running NotificationServiceExtension");
  //     self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];

      [OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
                         withMutableNotificationContent:self.bestAttemptContent
                                     withContentHandler:self.contentHandler];
  }

  - (void)serviceExtensionTimeWillExpire {
      // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.

      [OneSignalExtension serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];

      self.contentHandler(self.bestAttemptContent);
  }

  @end
  ```
</CodeGroup>

You should see an error because the OneSignal package is not installed. This will be resolved in the next step.

<Frame>
  <img />
</Frame>

### 7. Add OneSignal to the NSE target

<Note>
  If your SDK uses Swift Package Manager (SPM) for iOS dependencies, you can skip this step. The OneSignal package is already resolved and available to all targets.
</Note>

Update your `ios/Podfile` to include:

<CodeGroup>
  ```ruby Podfile theme={null}
  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```

  ```ruby Example theme={null}
  target 'MyApp' do
    config = use_native_modules!

    use_react_native!(
      :path => config[:reactNativePath],
      # An absolute path to your application root.
      :app_path => "#{Pod::Config.instance.installation_root}/.."
    )

    post_install do |installer|
      # https://github.com/facebook/react-native/blob/main/packages/react-native/scripts/react_native_pods.rb#L197-L202
      react_native_post_install(
        installer,
        config[:reactNativePath],
        :mac_catalyst_enabled => false,
        # :ccache_enabled => true
      )
    end
  end

  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```
</CodeGroup>

Open your project in the terminal and run:

```shell shell  theme={null}
cd ios pod install cd .. 
```

#### Common pod install errors

You may run into the following errors, here is how you can resolve them.

<Accordion
  title="ArgumentError - \[Xcodeproj] Unable to find compatibility version string for
object version `70`."
>
  CocoaPods relies on the `xcodeproj` Ruby gem to read your Xcode project files. As of now, the latest `xcodeproj` release does not recognize object version 70, which was introduced by Xcode 16. So when CocoaPods tries to open your `.xcodeproj` file, it crashes with this error.

  1. Close Xcode.
  2. Navigate to your project's `ios/<your-app>.xcodeproj/project.pbxproj` file.
  3. Change this line: `objectVersion = 70;`
  4. Replace it with: `objectVersion = 55;`
  5. Save, close, and rerun `cd ios pod install cd ..`
</Accordion>

### Build for iOS

You should now be able to build and run your app on a real iOS device or iOS simulator (16.2+).

#### Common iOS build errors

<Accordion title="commandPhaseScript Execution exited with a non-zero code">
  1. Delete your Podfile.lock
  2. Delete your Pods folder
  3. Delete your .xcworkspace
  4. Pod install
  5. Cmd + Shift + K to Clean the build and then retry building

  If these steps do not resolve the error, build directly from the Xcode, then find the build error in the report navigator pictured below.

  <img />
</Accordion>

<Accordion title="Cycle Inside... building could produce unreliable results.">
  You may see this error when building with Xcode 15+, due to a default configuration change affecting cross platform systems.

  1. Open your `.xcworkspace` folder in Xcode and navigate to **your app target > Build Phases**.
  2. You should have a phase called **"Embed Foundation Extensions"** or **"Embed App Extensions"**.
  3. Drag and move this build phase to *above* **"Run Script"**.
  4. Build and run your app. The error should be resolved.

  <Frame>
    <img />
  </Frame>

  <Frame>
    <img />
  </Frame>
</Accordion>

<Accordion title="PBXGroup Error">
  <Info>
    RuntimeError - `PBXGroup` attempted to initialize an object with unknown ISA `PBXFileSystemSynchronizedRootGroup` from attributes: `{"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}`
  </Info>

  Fix:

  1. Find the folder listed under "path" in the error
  2. In Xcode project sidebar, right-click the folder
  3. Select **Convert to Group**

  <Frame>
    <img />
  </Frame>

  <br />

  <Frame>
    <img />
  </Frame>
</Accordion>

<Check>
  After confirming that your iOS build works, continue with [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications, subscription registration, and in-app messaging.

<Warning>
  If you are testing with an Android emulator, it should start with a cold boot.

  1. Go to **Device Manager** in Android Studio.
  2. Select your emulator device and click **Edit**.
  3. Go to **Additional Settings** or **More**.
  4. Set the **Boot option** to **Cold Boot**.
  5. Save changes and restart the emulator.
</Warning>

### Check mobile subscriptions

<Steps>
  <Step title="Launch your app on a test device.">
    The native push permission prompt should appear automatically if you added the `requestPermission` method during initialization.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    Before accepting the prompt, check the OneSignal dashboard:

    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status "Never Subscribed".

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Return to the app and tap Allow on the prompt." />

  <Step title="Refresh the OneSignal dashboard Subscription's page.">
    The subscription's status should now show **Subscribed**.

    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a [mobile subscription](/docs/en/subscriptions).
    Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a segment of test users.
    We can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

    ```curl theme={null}
    curl -X \
    POST --url 'https://api.onesignal.com/notifications' \
     --header 'content-type: application/json; charset=utf-8' \
     --header 'authorization: Key YOUR_APP_API_KEY' \
     --data \
     '{
      "app_id": "YOUR_APP_ID",
      "target_channel": "push",
      "name": "Testing basic setup",
      "headings": {
      	"en": "👋"
      },
      "contents": {
        "en": "Hello world!"
      },
      "included_segments": [
        "Test Users"
      ],
      "ios_attachments": {
        "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      },
      "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
    }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification with an image included:

    <Frame>
      <img />
    </Frame>

    <Info>Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Info>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats.

    You should see the **confirmed** stat, meaning the device received the push.
    <Check>You have successfully sent a notification via our API to a segment.</Check>

    <Warning>
      * No image received? Your [Notification Service Extension](#ios-setup) might be missing.
      * No confirmed receipt? Review the troubleshooting guide [here](/docs/en/confirmed-delivery#troubleshooting-confirmed-delivery).
      * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
    </Warning>
  </Step>
</Steps>

### Send an in-app message

[In-app messages](/docs/en/in-app-messages-setup) let you communicate with users while they are using your app.

<Steps>
  <Step title="Close or background your app on the device.">
    This is because users must meet the in-app audience criteria *before* a new session starts. In OneSignal, a new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds. For more details, see our guide on [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
  </Step>

  <Step title="Create an in-app message.">
    * In your OneSignal dashboard, navigate to **Messages > In-App > New In-App**.
    * Find and select the **Welcome** message.
    * Set your Audience as the **Test Users** segment we used previously.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Customize the message content if desired.">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Set Trigger to 'On app open'." />

  <Step title="Schedule frequency.">
    Under **Schedule > How often do you want to show this message?** select **Every time trigger conditions are satisfied**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Make message live.">
    Click **Make Message Live** so it is available to your Test Users each time they open the app.
  </Step>

  <Step title="Open the app and see the message.">
    After the in-app message is live, open your app. You should see it display:

    <Frame>
      <img />
    </Frame>

    <Warning>
      Not seeing the message?

      * Start a new session
        * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
        * For more, see [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
      * Still in the `Test Users` segment?
        * If you reinstalled or switched devices, re-add the device to [Test Users](#set-up-test-users) and confirm it's part of the Test Users segment.
      * Having issues?
        * Follow [Getting a Debug Log](/docs/en/capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
    </Warning>
  </Step>
</Steps>

<Check>
  You have successfully setup the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](/docs/en/subscriptions), setting [Test Users](/docs/en/find-set-test-subscriptions), and creating [Segments](/docs/en/segmentation).
  * Sending [Push](/docs/en/push) with images and [Confirmed receipt](/docs/en/confirmed-delivery) using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](/docs/en/in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

***

## User identification

Previously, we demonstrated how to create mobile [Subscriptions](/docs/en/subscriptions). Now we'll expand to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We'll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with our SDK's [`login` method](/docs/en/mobile-sdk-reference#login-external-id) each time they are identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with our SDK [`addTag` and `addTags` methods](/docs/en/mobile-sdk-reference#data-tags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img />
</Frame>

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

### Add email and/or SMS subscriptions

Earlier we saw how our SDK creates mobile subscriptions to send push and in-app messages. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/mobile-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/mobile-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/mobile-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/mobile-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

See our Privacy & security docs for more on:

* [Data collected by the SDK](/docs/en/data-collected-by-the-onesignal-sdk)
* [Handling personal data](/docs/en/handling-personal-data)

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](/docs/en/prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners for you to hook into. See our [SDK reference guide](/docs/en/mobile-sdk-reference) for more details.

### Push notification events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-push): Detect when a notification is tapped. Helpful for [Deep Linking](/docs/en/deep-linking).
* [`addForegroundLifecycleListener()`](/docs/en/mobile-sdk-reference#addforegroundlifecyclelistener-push): Control how notifications behave in foreground.

For full customization, see [Mobile Service Extensions](/docs/en/service-extensions).

### User state changes

* [`addObserver()` for user state](/docs/en/mobile-sdk-reference#addobserver-user-state): Detect when the External ID is set.
* [`addPermissionObserver()`](/docs/en/mobile-sdk-reference#addpermissionobserver-push): Track the user's specific interaction with the native push permission prompt.
* [`addObserver()` for push subscription](/docs/en/mobile-sdk-reference#addobserver-push-subscription-changes): Track when the push subscription status changes.

### In-app message events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Handle in-app click actions. Ideal for deep linking or tracking events.
* [`addLifecycleListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Track full lifecycle of in-app messages (shown, clicked, dismissed, etc.).

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

* [🔁 Migrating to OneSignal from another service](/docs/en/migrating-to-onesignal)
* [🌍 Location tracking](/docs/en/mobile-sdk-reference#location)
* [🔗 Deep Linking](/docs/en/deep-linking)
* [🔌 Integrations](/docs/en/integrations)
* [🧩 Mobile Service Extensions](/docs/en/service-extensions)
* [🛎️ Action buttons](/docs/en/action-buttons)
* [🌐 Multi-language messaging](/docs/en/multi-language-messaging)
* [🛡️ Identity Verification](/docs/en/identity-verification)
* [📊 Custom Outcomes](/docs/en/custom-outcomes)
* [📲 Live Activities](/docs/en/live-activities)

### Mobile SDK setup & reference

Make sure you've enabled all key features by reviewing the [Mobile push setup](/docs/en/mobile-push-setup) guide.

For full details on available methods and configuration options, visit the [Mobile SDK reference](/docs/en/mobile-sdk-reference).

<Check>Congratulations! You've successfully completed the Mobile SDK setup guide.</Check>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Flutterflow SDK setup
Source: https://documentation.onesignal.com/docs/en/flutterflow-sdk-setup

Instructions for adding the OneSignal Flutter SDK to your Flutterflow app for iOS and Android

<SdkReleasesIframe />

This guide is for Flutterflow mobile app setup. If you have a Flutterflow site, please see our [Web SDK setup](./web-sdk-setup) guide.

## Requirements

* Flutterflow plan: Standard or higher
* Configured OneSignal app and platform

**iOS Requirements**

* macOS with Xcode 14+ (setup instructions use Xcode 16.2)
* Device with iOS 12+, iPadOS 12+, or Xcode simulator running iOS 16.2+
* CocoaPods 1.16.2+

**Android Requirements**

* Android 7.0+ device or emulator with Google Play Store (Services) installed

### Configure your OneSignal app and platform

Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).

<Note>
  If your organization already has a OneSignal account, [ask to be invited](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Step-by-step setup instructions" icon="circle-chevron-down">
  <Steps>
    <Step title="Create or select your app">
      Create a new app by clicking **New App/Website**, or add a platform to an existing app in **Settings > Push & In-App**. Select the platform(s) you want to configure and click **Next: Configure Your Platform**.

      <Frame>
        <img alt="OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection" />
      </Frame>
    </Step>

    <Step title="Configure platform credentials">
      Enter the credentials for your platform:

      * **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
      * **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
      * **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
      * **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)

      Click **Save & Continue** after entering your credentials.
    </Step>

    <Step title="Save your App ID and install the SDK">
      Your **App ID** is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.

      <Frame>
        <img alt="OneSignal dashboard showing the App ID and team invite option after setup" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

***

## Setup

### 1. Create a new custom action

In your Flutterflow project, navigate to Custom Code, then click the +Add button and select Action.

<Frame>
  <img />
</Frame>

Under Action settings on the right-hand toolbar, click Add Dependency and enter the following dependency and click refresh to add it to the action:

```yaml dependency theme={null}
  dependencies:
  	onesignal_flutter: ^5.1.2
```

<Frame>
  <img />
</Frame>

In the Action Code, under the pre-loaded code add the following, then save and compile your action.

Replace `YOUR_APP_ID` with your OneSignal App ID found in your OneSignal dashboard **Settings > [Keys & IDs](./keys-and-ids)**.

<Note>
  If you don't have access to the OneSignal app, ask your [Team Members](./manage-team-members) to invite you.
</Note>

```javascript Flutter theme={null}
  import 'package:onesignal_flutter/onesignal_flutter.dart';

  Future onesignal() async {
    //Remove this method to stop OneSignal Debugging
    OneSignal.Debug.setLogLevel(OSLogLevel.verbose);

    OneSignal.initialize("YOUR_APP_ID");

    // The promptForPushNotificationsWithUserResponse function will show the iOS or Android push notification prompt. We recommend removing the following code and instead using an In-App Message to prompt for notification permission
    OneSignal.Notifications.requestPermission(true);
  }
```

Next, click on the main.dart file in the left-hand tool bar and click the + icon next to Initial Actions in the right-hand bar and click on the `onesignal` action that has just been created.

<Frame>
  <img />
</Frame>

This will add the action to you app and cause the OneSignal SDK to be initialised when the app runs:

<Frame>
  <img />
</Frame>

### 2. Exporting the project

<Tabs>
  <Tab title="APK download (Android only)">
    Open the Developer Menu and download the APK:

    <Frame>
      <img />
    </Frame>

    Once the APK has downloaded, you can test the app by dragging the APK into an Android emulator to install it. Push capabilities should work immediately and you can send push notifications to the device as soon as you provide push permissions through the native prompt.
  </Tab>

  <Tab title="Full project download (iOS and Android)">
    Open the Developer Menu and download the project code:

    <Frame>
      <img />
    </Frame>
  </Tab>
</Tabs>

### 3. iOS Setup

The downloaded project will likely not be ready to launch in iOS. Before setting up the OneSignal specific additions, you will need to make sure that the project is fully built. To do so:

* Open up a Terminal window, cd (change directory) to the `ios` folder of your downloaded project.
* In Terminal type `flutter build ios`and press enter. Wait for the build to complete, this may take some time depending on the size of your project.
* Still in Terminal type `pod install` and press enter. Wait for the pod install to complete.

Open the `.xcworkspace` file in Xcode located your project's ios folder.

Select the **root project > your main app target > Signing & Capabilities**.

If you do not see Push Notifications enabled, click **+ Capability** and add **Push Notifications**. Ensure that you enter the correct details for your Team and Bundle Identifier.

<Frame>
  <img />
</Frame>

Click **+ Capability** again and add **Background Modes**. Then check **Remote notifications**.

<Frame>
  <img />
</Frame>

#### Add Notification Service Extension

The OneSignalNotificationServiceExtension allows your iOS application to receive rich notifications with images, buttons, and badges. It's also required for OneSignal's confirmed receipt analytics features.

In Xcode Select **File > New > Target...**

Select **Notification Service Extension** then **Next**.

<Frame>
  <img />
</Frame>

Enter the product name as `OneSignalNotificationServiceExtension` and press **Finish**.

<Frame>
  <img />
</Frame>

Do not activate the scheme on the dialog that is shown after selecting **Finish**.

Press **Cancel** on the "Activate scheme" prompt.

<Frame>
  <img />
</Frame>

Select the **OneSignalNotificationServiceExtension** target and **General** settings.

Set **Minimum Deployments** to be the **same value as your Main Application Target**. This should be iOS 11 or higher.

<Frame>
  <img />
</Frame>

#### Add App Groups

App Groups allow your app and the OneSignalNotificationServiceExtension to communicate when a notification is received, even if your app is not active. This is required for badges and Confirmed Deliveries.

Select your **Main App Target > Signing & Capabilities > + Capability > App Groups**.

<Frame>
  <img />
</Frame>

Within **App Groups**, click the **+** button.

Set the App Groups container to be `group.YOUR_BUNDLE_IDENTIFIER.onesignal` where `YOUR_BUNDLE_IDENTIFIER` is the same as your Main Application "Bundle Identifier".

<Frame>
  <img />
</Frame>

Press **OK** and repeat for the OneSignalNotificationServiceExtension Target.

Select the **OneSignalNotificationServiceExtension Target > Signing & Capabilities > + Capability > App Groups**.

<Frame>
  <img />
</Frame>

Within **App Groups**, click the **+** button.

Set the App Groups container to be `group.YOUR_BUNDLE_IDENTIFIER.onesignal` where `YOUR_BUNDLE_IDENTIFIER` is the same as **your Main Application "Bundle Identifier"**.

**DO NOT INCLUDE** `OneSignalNotificationServiceExtension`.

<Frame>
  <img />
</Frame>

<Accordion title="Optional instructions to setup custom App Group Name">
  This step is only required if you **do not** want to use the default app group name (which is `group.{your_bundle_id}.onesignal`).

  Open your `Info.plist` file and add a new `OneSignal_app_groups_key` as a `String` type.

  Enter the group name you checked in the last step as it's value.

  Make sure to do the same for the `Info.plist` under the `OneSignalNotificationServiceExtension` folder.
</Accordion>

#### Add OneSignal SDK to the OneSignalNotificationServiceExtension

Update your `ios/Podfile` to include:

<CodeGroup>
  ```ruby Podfile theme={null}
  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```

  ```ruby Example theme={null}
  target 'MyApp' do
    config = use_native_modules!

    use_react_native!(
      :path => config[:reactNativePath],
      # An absolute path to your application root.
      :app_path => "#{Pod::Config.instance.installation_root}/.."
    )

    post_install do |installer|
      # https://github.com/facebook/react-native/blob/main/packages/react-native/scripts/react_native_pods.rb#L197-L202
      react_native_post_install(
        installer,
        config[:reactNativePath],
        :mac_catalyst_enabled => false,
        # :ccache_enabled => true
      )
    end
  end

  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```
</CodeGroup>

At the top of your `Podfile` make sure you have `platform :ios, '11.0'`. - Or a newer iOS version if your app requires it.

<CodeGroup>
  ```Text Podfile theme={null}
  # Uncomment this line to define a global platform for your project
  platform :ios, '11.0'
  ```
</CodeGroup>

Open terminal, `cd` to the `ios` directory, and run `pod install`.

If you see the error below, add `use_frameworks!` to the top of your podfile and try again.

```
- Runner (true) and OneSignalNotificationServiceExtension (false) do not both set use_frameworks!.
```

#### OneSignalNotificationServiceExtension Code

In the Xcode project navigator, select the **OneSignalNotificationServiceExtension folder** and open the `NotificationService.m` or `NotificationService.swift` file.

Replace the whole file's contents with the following code.

<CodeGroup>
  ```swift Swift theme={null}
  import UserNotifications

  import OneSignalExtension

  class NotificationService: UNNotificationServiceExtension {

      var contentHandler: ((UNNotificationContent) -> Void)?
      var receivedRequest: UNNotificationRequest!
      var bestAttemptContent: UNMutableNotificationContent?

      override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
          self.receivedRequest = request
          self.contentHandler = contentHandler
          self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

          if let bestAttemptContent = bestAttemptContent {
              /* DEBUGGING: Uncomment the 2 lines below to check this extension is executing
                            Note, this extension only runs when mutable-content is set
                            Setting an attachment or action buttons automatically adds this */
              // print("Running NotificationServiceExtension")
              // bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

              OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
          }
      }

      override func serviceExtensionTimeWillExpire() {
          // Called just before the extension will be terminated by the system.
          // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
          if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
              OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
              contentHandler(bestAttemptContent)
          }
      }
  }
  ```

  ```c objective-c theme={null}
  #import <OneSignalExtension/OneSignalExtension.h>

  #import "NotificationService.h"

  @interface NotificationService ()

  @property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
  @property (nonatomic, strong) UNNotificationRequest *receivedRequest;
  @property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

  @end

  @implementation NotificationService

  - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
      self.receivedRequest = request;
      self.contentHandler = contentHandler;
      self.bestAttemptContent = [request.content mutableCopy];

      /* DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is executing
                    Note, this extension only runs when mutable-content is set
                    Setting an attachment or action buttons automatically adds this */
      // NSLog(@"Running NotificationServiceExtension");
      // self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];

      [OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
                         withMutableNotificationContent:self.bestAttemptContent
                                     withContentHandler:self.contentHandler];
  }

  - (void)serviceExtensionTimeWillExpire {
      // Called just before the extension will be terminated by the system.
      // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.

      [OneSignalExtension serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];

      self.contentHandler(self.bestAttemptContent);
  }

  @end
  ```
</CodeGroup>

<Frame>
  <img />
</Frame>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications, subscription registration, and in-app messaging.

<Warning>
  If you are testing with an Android emulator, it should start with a cold boot.

  1. Go to **Device Manager** in Android Studio.
  2. Select your emulator device and click **Edit**.
  3. Go to **Additional Settings** or **More**.
  4. Set the **Boot option** to **Cold Boot**.
  5. Save changes and restart the emulator.
</Warning>

### Check mobile subscriptions

<Steps>
  <Step title="Launch your app on a test device.">
    The native push permission prompt should appear automatically if you added the `requestPermission` method during initialization.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    Before accepting the prompt, check the OneSignal dashboard:

    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status "Never Subscribed".

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Return to the app and tap Allow on the prompt." />

  <Step title="Refresh the OneSignal dashboard Subscription's page.">
    The subscription's status should now show **Subscribed**.

    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a [mobile subscription](/docs/en/subscriptions).
    Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a segment of test users.
    We can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

    ```curl theme={null}
    curl -X \
    POST --url 'https://api.onesignal.com/notifications' \
     --header 'content-type: application/json; charset=utf-8' \
     --header 'authorization: Key YOUR_APP_API_KEY' \
     --data \
     '{
      "app_id": "YOUR_APP_ID",
      "target_channel": "push",
      "name": "Testing basic setup",
      "headings": {
      	"en": "👋"
      },
      "contents": {
        "en": "Hello world!"
      },
      "included_segments": [
        "Test Users"
      ],
      "ios_attachments": {
        "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      },
      "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
    }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification with an image included:

    <Frame>
      <img />
    </Frame>

    <Info>Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Info>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats.

    You should see the **confirmed** stat, meaning the device received the push.
    <Check>You have successfully sent a notification via our API to a segment.</Check>

    <Warning>
      * No image received? Your [Notification Service Extension](#ios-setup) might be missing.
      * No confirmed receipt? Review the troubleshooting guide [here](/docs/en/confirmed-delivery#troubleshooting-confirmed-delivery).
      * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
    </Warning>
  </Step>
</Steps>

### Send an in-app message

[In-app messages](/docs/en/in-app-messages-setup) let you communicate with users while they are using your app.

<Steps>
  <Step title="Close or background your app on the device.">
    This is because users must meet the in-app audience criteria *before* a new session starts. In OneSignal, a new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds. For more details, see our guide on [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
  </Step>

  <Step title="Create an in-app message.">
    * In your OneSignal dashboard, navigate to **Messages > In-App > New In-App**.
    * Find and select the **Welcome** message.
    * Set your Audience as the **Test Users** segment we used previously.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Customize the message content if desired.">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Set Trigger to 'On app open'." />

  <Step title="Schedule frequency.">
    Under **Schedule > How often do you want to show this message?** select **Every time trigger conditions are satisfied**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Make message live.">
    Click **Make Message Live** so it is available to your Test Users each time they open the app.
  </Step>

  <Step title="Open the app and see the message.">
    After the in-app message is live, open your app. You should see it display:

    <Frame>
      <img />
    </Frame>

    <Warning>
      Not seeing the message?

      * Start a new session
        * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
        * For more, see [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
      * Still in the `Test Users` segment?
        * If you reinstalled or switched devices, re-add the device to [Test Users](#set-up-test-users) and confirm it's part of the Test Users segment.
      * Having issues?
        * Follow [Getting a Debug Log](/docs/en/capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
    </Warning>
  </Step>
</Steps>

<Check>
  You have successfully setup the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](/docs/en/subscriptions), setting [Test Users](/docs/en/find-set-test-subscriptions), and creating [Segments](/docs/en/segmentation).
  * Sending [Push](/docs/en/push) with images and [Confirmed receipt](/docs/en/confirmed-delivery) using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](/docs/en/in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

***

## User identification

Previously, we demonstrated how to create mobile [Subscriptions](/docs/en/subscriptions). Now we'll expand to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We'll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with our SDK's [`login` method](/docs/en/mobile-sdk-reference#login-external-id) each time they are identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with our SDK [`addTag` and `addTags` methods](/docs/en/mobile-sdk-reference#data-tags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img />
</Frame>

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

### Add email and/or SMS subscriptions

Earlier we saw how our SDK creates mobile subscriptions to send push and in-app messages. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/mobile-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/mobile-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/mobile-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/mobile-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

See our Privacy & security docs for more on:

* [Data collected by the SDK](/docs/en/data-collected-by-the-onesignal-sdk)
* [Handling personal data](/docs/en/handling-personal-data)

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](/docs/en/prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners for you to hook into. See our [SDK reference guide](/docs/en/mobile-sdk-reference) for more details.

### Push notification events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-push): Detect when a notification is tapped. Helpful for [Deep Linking](/docs/en/deep-linking).
* [`addForegroundLifecycleListener()`](/docs/en/mobile-sdk-reference#addforegroundlifecyclelistener-push): Control how notifications behave in foreground.

For full customization, see [Mobile Service Extensions](/docs/en/service-extensions).

### User state changes

* [`addObserver()` for user state](/docs/en/mobile-sdk-reference#addobserver-user-state): Detect when the External ID is set.
* [`addPermissionObserver()`](/docs/en/mobile-sdk-reference#addpermissionobserver-push): Track the user's specific interaction with the native push permission prompt.
* [`addObserver()` for push subscription](/docs/en/mobile-sdk-reference#addobserver-push-subscription-changes): Track when the push subscription status changes.

### In-app message events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Handle in-app click actions. Ideal for deep linking or tracking events.
* [`addLifecycleListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Track full lifecycle of in-app messages (shown, clicked, dismissed, etc.).

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

* [🔁 Migrating to OneSignal from another service](/docs/en/migrating-to-onesignal)
* [🌍 Location tracking](/docs/en/mobile-sdk-reference#location)
* [🔗 Deep Linking](/docs/en/deep-linking)
* [🔌 Integrations](/docs/en/integrations)
* [🧩 Mobile Service Extensions](/docs/en/service-extensions)
* [🛎️ Action buttons](/docs/en/action-buttons)
* [🌐 Multi-language messaging](/docs/en/multi-language-messaging)
* [🛡️ Identity Verification](/docs/en/identity-verification)
* [📊 Custom Outcomes](/docs/en/custom-outcomes)
* [📲 Live Activities](/docs/en/live-activities)

### Mobile SDK setup & reference

Make sure you've enabled all key features by reviewing the [Mobile push setup](/docs/en/mobile-push-setup) guide.

For full details on available methods and configuration options, visit the [Mobile SDK reference](/docs/en/mobile-sdk-reference).

<Check>Congratulations! You've successfully completed the Mobile SDK setup guide.</Check>

***

***


# Gaming strategies
Source: https://documentation.onesignal.com/docs/en/gaming-industry

Implementation hub for gaming messaging — player IDs, lifecycle Tags, behavioral Custom Events, segments, and Journey playbooks for mobile and live-service games.

A gaming strategy targets apps where the experience is play-driven — from casual mobile games to RPGs and live-service titles. If your success depends on session frequency, in-app spend, and player retention curves, this guide is for you.

This page is the implementation hub: which player identifier to set, what gameplay data to capture, which segments to build, and which Journeys drive onboarding, retention, and monetization. Each section links to the canonical docs for deeper detail.

<Columns>
  <Card title="Onboard" icon="door-open" href="./welcome-journey-mobile-gaming">
    Maximize push opt-ins and guide new players to their first meaningful in-game action with a 7-day Welcome Journey.
  </Card>

  <Card title="Engage" icon="gamepad" href="#common-gaming-patterns">
    Drive sessions, DAU, and MAU with event-driven milestones, content updates, and VIP-tier messaging.
  </Card>

  <Card title="Re-engage" icon="rotate-left" href="./mobile-first-journeys#retention-journeys">
    Win back lapsed players on a Day 1, 3, 7, 14 cadence before they cross into churn.
  </Card>
</Columns>

## Implementation roadmap

Work through these steps in order. Each one links to its section below.

<Steps>
  <Step title="Assign External IDs to players">
    Set a stable player ID on every authenticated player so push, email, and SMS tie to one profile across devices and reinstalls. [Jump to section](#identify-your-players-with-external-ids).
  </Step>

  <Step title="Add player properties as Tags">
    Start with `player_name`, `current_level`, `tutorial_completed`, and `vip_status`. They power most starter Journeys. [Jump to section](#tags).
  </Step>

  <Step title="Send player actions as Custom Events">
    Fire `tutorial_completed`, `level_completed`, `daily_session`, and `purchase_completed` from your game client or backend. [Jump to section](#custom-events).
  </Step>

  <Step title="Build lifecycle Segments">
    Player audiences such as New Players, Active Players, High-Value Players, and Churned Players. [Jump to section](#segments).
  </Step>

  <Step title="Create lifecycle Journeys">
    Welcome onboarding, re-engagement, milestone celebrations, and VIP/spend-based flows. [Jump to section](#journey-examples).
  </Step>
</Steps>

<Frame>
  <iframe title="Onboarding game players to maximize push opt-in" />
</Frame>

## Identify your players with External IDs

External IDs preserve identity across installs and tie push, email, and SMS to one player profile. Use the unique identifier from your account, auth, or game-services platform — for example, your game's player ID, an Auth0 `uid`, or a PlayFab/Game Center identifier.

Set the External ID at signup, on every login, and on session resume. The OneSignal SDK does not assign it for you, and assigning it late or sporadically breaks reinstall-to-reward attribution.

<Card title="External ID setup" icon="id-card" href="./users#external-id">
  Assign a unique player identifier so progression, purchases, and notifications follow the player across devices and reinstalls.
</Card>

## Recommended data

Tags persist on the player profile (current state); Custom Events record discrete moments (what just happened). Use both — Tags drive segmentation and personalization, Custom Events trigger Journey entry and Wait Until steps.

Gaming leans heavily on both. A player's `current_level` and `vip_status` are Tags you segment on, while `level_completed` and `purchase_completed` are events that trigger celebration or upsell Journeys.

### Tags

Tags persist on the player profile and are used for segmentation and personalization. For boolean-style signals, set the Tag to `1` when true and **remove it** when false — segment with "tag exists" rather than storing `0`/`false` values.

<Tip>
  If you only set up four Tags, start with `player_name`, `current_level`, `tutorial_completed`, and `vip_status`. They power most starter Journeys.
</Tip>

#### Lifecycle and progression

| Tag                  | Values                                                             | Use                                                                                                                                                                                                                                                       |
| :------------------- | :----------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `current_level`      | integer (as string)                                                | Track progression. Drives content gating, level-up celebration Journeys, and difficulty-tuned messaging.                                                                                                                                                  |
| `rank_tier`          | `bronze` / `silver` / `gold` / `platinum` / `diamond` (your tiers) | Competitive ranking. Drives rank-up celebration Journeys and tier-specific content, balance, and event messaging. Distinct from `loyalty_tier`, which tracks points-based loyalty program tiers (see [Loyalty Journey](./loyalty-journey-mobile-gaming)). |
| `tutorial_completed` | `1` (set when finished)                                            | Confirms onboarding completion. Absence is the highest-leverage adoption segment.                                                                                                                                                                         |
| `account_type`       | `free` / `paid` / `lapsed`                                         | Lifecycle state for free-to-play conversion and lapsed-player win-back.                                                                                                                                                                                   |
| `vip_status`         | `1` (set for VIPs)                                                 | Identifies high-value players for premium offers, early access, and concierge messaging.                                                                                                                                                                  |

#### Engagement and spend

| Tag                      | Values                                     | Use                                                                                                                                                                                                                                  |
| :----------------------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `total_spend_cents`      | integer (as string)                        | Lifetime value. Power whale and high-spender segments.                                                                                                                                                                               |
| `last_purchase_date`     | Unix timestamp (seconds)                   | Spend recency. Use [time operators](./time-operators) to send win-back offers a fixed number of days after the last purchase.                                                                                                        |
| `streak_count`           | integer (as string)                        | Daily login or play streak. Drives streak-protect reminders and milestone rewards.                                                                                                                                                   |
| `claimed_new_user_offer` | `1` (set when claimed)                     | Tracks whether the player has redeemed a starter pack or new-user bundle. Use to gate IAMs (e.g., the [Day 3 new-player loot box](./welcome-journey-mobile-gaming#in-app-message-templates)) so redeemers don't see the offer twice. |
| `favorite_game_mode`     | string (e.g., `pvp`, `campaign`, `casual`) | Personalize content recommendations and event invitations.                                                                                                                                                                           |

#### Personalization

| Tag                  | Values                                                             | Use                                                                                                                                                                                                     |
| :------------------- | :----------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `player_name`        | string                                                             | Personalize message copy (e.g., `Hey {{ player_name \| default: 'hero' }}`).                                                                                                                            |
| `clan_name`          | string                                                             | Reference the player's clan, guild, or team in social and event copy.                                                                                                                                   |
| `acquisition_source` | string (e.g., `paid_social`, `organic`, `referral`, `cross_promo`) | *Optional but high-value for UA-driven games.* Vary onboarding copy by acquisition channel — paid social users respond differently than organic, and cross-promo installs may already know your studio. |

<Card title="Add user data tags" icon="tags" href="./add-user-data-tags">
  Add key-value pairs to player profiles for segmentation and personalization.
</Card>

### Custom Events

Send a Custom Event for each gameplay moment you want to react to. Events are stored shorter-term than Tags but can carry properties, making them ideal for Journey entry triggers and Wait Until conditions. Use lowercase `snake_case` for event names and keep them consistent across your client and backend.

| Event                              | Use case                                                                                                                                                                                                                                                                              |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tutorial_completed`               | Exit onboarding Journey; confirm first-session activation.                                                                                                                                                                                                                            |
| `level_completed`                  | Discrete event fired each time a player completes a level — separate from the persistent `current_level` Tag. Use as a Journey entry rule or Wait Until anchor for milestone celebrations. Carry `level_number`, `score`, and `time_to_complete` as properties for personalized copy. |
| `achievement_unlocked`             | Milestone celebration. Use as a Journey entry rule and carry `achievement_id`, `achievement_name`, and `rarity` (e.g., `common` / `rare` / `legendary`) as properties for personalized copy and rarity-tier targeting.                                                                |
| `daily_session`                    | Wait Until anchor for daily re-engagement loops. **Dedupe to once per calendar day** in the player's timezone.                                                                                                                                                                        |
| `reward_claimed`                   | Stronger signal than `daily_session` for retention loops — fires only when the player actually claimed the daily reward. Use as the Wait Until anchor in the [Welcome Journey: Mobile gaming](./welcome-journey-mobile-gaming) when your game has an explicit "Claim" action.         |
| `purchase_completed`               | In-game purchase. Drives thank-you push, receipt email, and upsell-timing refresh. Carry `product_id`, `price`, `currency`, and `is_first_purchase` as properties so messages can reference what was bought and trigger first-purchase Journeys.                                      |
| `streak_reached`                   | Reward push referencing the achievement.                                                                                                                                                                                                                                              |
| `cart_abandoned`                   | Recovery push on the expiration branch of a Wait Until.                                                                                                                                                                                                                               |
| `friend_invited` / `friend_joined` | Social moments; cross-promote viral mechanics. See [Social activity](./social-activity) for the broader pattern — likes, mentions, comments, follows, and direct user-to-user messages.                                                                                               |
| `live_event_started`               | Live-service event launch (raids, festivals, limited-time modes). Drives launch broadcasts to active and at-risk players, and reminders 1–2 days before the event ends. Carry `event_id`, `event_name`, and `ends_at` as properties.                                                  |

<Card title="Custom Events" icon="bolt" href="./custom-events">
  Capture player actions and use them to trigger Journeys or Wait Until steps.
</Card>

### Segments

Combine Tags and Custom Events into segments. Start with these nine:

| Segment             | Definition                                                                                                                                                                                                                         |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New Players         | `First Session < 7 days ago`. Entry audience for onboarding and welcome flows.                                                                                                                                                     |
| Tutorial incomplete | `tutorial_completed` does not exist. Highest-priority activation segment.                                                                                                                                                          |
| Active Players      | `Last Session < 3 days ago`. Daily-active core for live events and content drops.                                                                                                                                                  |
| Progressing Players | `level_completed` Custom Event fired in the last 7 days. Players actively advancing through content — distinct from Active Players, which only measures session recency. Reward with content drops and difficulty-tuned messaging. |
| Power Players       | Active Players AND `streak_count > 5`. Reward and retention-protect targets.                                                                                                                                                       |
| High-Level Players  | `current_level >= 50` (use whatever level marks your endgame). Endgame audience for advanced tips, mentor programs, beta access, and late-game content drops.                                                                      |
| At-Risk Players     | `Last Session > 7 days ago` AND `Last Session < 14 days ago`. The window where re-engagement still works.                                                                                                                          |
| Churned Players     | `Last Session > 14 days ago`. Win-back territory; back off general messaging.                                                                                                                                                      |
| High-Value Players  | `vip_status = "1"` OR `total_spend_cents > 5000`. Premium offer audience — also referred to as VIPs or whales.                                                                                                                     |

<Note>
  Mature gaming setups run 15+ segments split by game mode, content preferences, region, and platform. Start with the nine above, then add depth (push opt-in status, hardware tier, content pack ownership) as your Journeys grow.
</Note>

<Card title="Segmentation" icon="users" href="./segmentation">
  Group players by shared characteristics to target Journeys and campaigns.
</Card>

## Journey examples

With Tags, Custom Events, and segments in place, build Journeys against them. Gaming Journeys mix channels by intent — push and in-app for in-the-moment nudges, email for recaps and milestone moments, and SMS sparingly for high-intent moments like VIP launches or limited-time events. The lifecycle has four core flows:

<Columns>
  <Card title="Welcome Journey: Mobile gaming" icon="gamepad" href="./welcome-journey-mobile-gaming">
    7-day onboarding Journey using `daily_session` and `player_name` — Basic and Advanced paths.
  </Card>

  <Card title="Re-engagement (Day 1, 3, 7, 14)" icon="rotate-left" href="./mobile-first-journeys#retention-journeys">
    Catch inactive players with cadenced re-engagement before they churn.
  </Card>

  <Card title="Event-driven milestones" icon="trophy" href="./event-driven-journeys">
    Trigger Journeys from `level_completed`, `achievement_unlocked`, `streak_reached`, and other gameplay events.
  </Card>

  <Card title="VIP and high-value players" icon="crown" href="./event-driven-journeys">
    Run a parallel high-touch Journey for the High-Value Players segment — exclusive offers, early access, and `purchase_completed`-driven upsells.
  </Card>
</Columns>

<Frame>
  <iframe title="Increasing sessions, duration, DAU, and MAU" />
</Frame>

### Common gaming patterns

* **Communicate game updates.** Studios ship new levels, content, and gameplay regularly, but automatic OS updates mean players often don't know. Push and in-app messaging surface what's new and entice players to explore. Time updates to your Active Players segment, not your full audience. For implementation patterns, see [App version update prompts](./app-version-update) and [Targeting Android manufacturers that restrict push delivery](./example-target-certain-android-manufacturers-and-devices).
* **Celebrate player achievements.** Trigger event-driven Journeys on `level_completed`, `achievement_unlocked`, `streak_reached`, or other progression Custom Events. Personalize copy with `player_name`, `current_level`, and `clan_name` to make the moment feel earned. For `achievement_unlocked`, use the `rarity` property to scale message intensity — a `legendary` unlock deserves a louder push than a `common` one.
* **App store review prompts.** Ask for App Store and Google Play reviews at peak moments — immediately after a hard-won boss kill, a major level milestone, or an `achievement_unlocked` event with `rarity = "legendary"`. The post-win window is the highest-converting time to ask. Use the native iOS and Android review modals via in-app messages so players never leave the game. See [Get more app store reviews](./example-app-store-review).
* **VIP and whale messaging.** The High-Value Players segment (`vip_status = "1"` OR `total_spend_cents > 5000`) is your VIP/whale audience. Run a parallel high-touch Journey for those players — exclusive offers, early access, `purchase_completed`-driven thank-yous, and concierge channels.
* **Re-engagement cadence.** A common cadence is **Day 1, Day 3, Day 7, Day 14** of inactivity. The first three windows still convert; Day 14 is the boundary between re-engagement and win-back. See [Retention Journeys](./mobile-first-journeys#retention-journeys) for the implementation. Effective re-engagement messages give players a concrete reason to return — a new level or content drop with a specific hint about what's new, a free in-game item (coins, tokens, energy), a limited-time offer, an upcoming seasonal or sponsored live event, or a streak-protect reminder. When push delivery fails (uninstalled, opted out, sleeping device), [fall back to email or SMS](./push-fallback-method) for the highest-priority moments.

<Frame>
  <iframe title="Re-engaging churned game players" />
</Frame>

Measure success by Day 1 / Day 7 / Day 30 retention, ARPDAU (average revenue per daily active user), and push CTR by lifecycle stage — not just opens.

## FAQ

### How is this different from the Mobile-first strategy?

[Mobile-first](./mobile-first) targets subscription, freemium, and trial-driven apps where success is measured by trial-to-paid conversion and recurring engagement. Gaming is mobile-first by definition, but the lifecycle is shaped around session frequency, progression, and in-app purchases rather than trial conversion. The data foundation (External IDs, Tags, Custom Events, segments) is the same; the audiences and Journey shapes differ.

### Should I use a Tag or a Custom Event for a given gameplay signal?

Use a **Custom Event** when you want to trigger a Journey or count an occurrence (e.g., `level_completed`, `purchase_completed`). Use a **Tag** when you want to segment on the player's current state (e.g., `current_level = "10"`, `vip_status = "1"`). Many signals deserve both — fire the event in the moment, then update the Tag to reflect the new state.

### How often should I message active players?

Daily push is acceptable for active players inside a structured Journey (welcome, re-engagement, live event), but each push needs to carry value — a content drop, a milestone, an offer, or a personalized progression cue. Generic "come back" pushes burn opt-in. Watch your push opt-out rate by Journey step; that's the earliest signal you're being too aggressive.

### How do I personalize messages with player progress or items?

Use [Liquid syntax](./using-liquid-syntax) to pull Tag values into push, email, and IAM copy. Common gaming patterns: `Hey {{ player_name \| default: 'hero' }}`, `Your level {{ current_level }} reward is ready`, `{{ clan_name }} is calling`. For event-driven Journeys, the Custom Event payload is also available — see [Personalization with Custom Events](./personalization-custom-event).

### How do I maximize push opt-in for new players?

Don't trigger the OS prompt at install. Capture push opt-in via an in-app message *after* onboarding (signup, tutorial, profile setup) so the prompt arrives at a natural beat with context. Use a benefit-led message ("Get notified when daily rewards drop") rather than the generic OS prompt. See [Prompt for push permission with in-app messages](./prompt-for-push-permissions).

### What about apps that mix gaming with other surfaces (e.g., a companion web app)?

The patterns here apply, but the channel mix shifts. Companion web surfaces should layer in [web push](./web-push-setup) and additional segments for cross-platform players on top of this mobile-gaming foundation.

## Related pages

<Columns>
  <Card title="Welcome Journey: Mobile gaming" icon="gamepad" href="./welcome-journey-mobile-gaming">
    Worked end-to-end onboarding Journey with both basic and advanced data paths.
  </Card>

  <Card title="Loyalty Journey: Mobile gaming" icon="trophy" href="./loyalty-journey-mobile-gaming">
    Pre-built Journey for rewarding player loyalty and driving tier progression.
  </Card>

  <Card title="Mobile-first lifecycle Journeys" icon="route" href="./mobile-first-journeys">
    Welcome, event-driven, and retention Journey patterns shared across mobile-first apps.
  </Card>

  <Card title="Event-driven Journeys" icon="bolt" href="./event-driven-journeys">
    Trigger Journeys from gameplay events with Wait Until and Event Matching.
  </Card>

  <Card title="Prompt for push permissions" icon="bell" href="./prompt-for-push-permissions">
    Ask for push opt-in with a benefit-led in-app message before the OS prompt.
  </Card>

  <Card title="Onboarding carousel" icon="circle-dot" href="./in-app-onboarding-carousel-tutorial">
    Multi-step HTML in-app message with button navigation for tutorial flows.
  </Card>

  <Card title="iOS image carousel push" icon="images" href="./ios-image-carousel-push-notifications">
    Add rich image carousels to iOS push for milestone celebrations and content drops.
  </Card>

  <Card title="App version update prompts" icon="rotate" href="./app-version-update">
    Target players on outdated app versions and prompt them to update via in-app messages.
  </Card>

  <Card title="Push fallback to email or SMS" icon="rotate" href="./push-fallback-method">
    Reach players via email or SMS when push delivery fails for high-priority moments.
  </Card>

  <Card title="Social activity" icon="user-group" href="./social-activity">
    Push patterns for friend invites, clan and guild activity, mentions, and direct messages.
  </Card>

  <Card title="Get more app store reviews" icon="star" href="./example-app-store-review">
    Trigger native iOS and Android review prompts via in-app messages at peak gameplay moments.
  </Card>

  <Card title="Daily streaks" icon="fire" href="./daily-streak">
    Build streak mechanics that drive daily logins and reward player consistency.
  </Card>

  <Card title="Mobile-first strategies" icon="mobile" href="./mobile-first">
    Sister hub for subscription, freemium, and trial-driven mobile apps.
  </Card>
</Columns>


# Google Tag Manager setup
Source: https://documentation.onesignal.com/docs/en/google-tag-manager

Add OneSignal Web Push to your website using Google Tag Manager (GTM), including service worker setup, initialization, and sending Tags safely.

This guide shows you how to load and initialize the OneSignal Web SDK using Google Tag Manager (GTM), then optionally set an External ID and send OneSignal Tags after initialization.

## Prerequisites

* A site that supports HTTPS.
* You can publish changes in GTM for the site's container.
* You've completed the OneSignal [Web SDK setup](./web-sdk-setup) flow until **Add Code to Site**. This gives you:
  * A OneSignal Web Push app and App ID.
  * The [OneSignal Service Worker](./onesignal-service-worker) setup.

## Setup

### 1. Set up your OneSignal web app

Follow [Web SDK setup](./web-sdk-setup) until you reach **Add Code to Site**. This is where you will get the OneSignal App ID.

<Frame>
  <img alt="Add Code to Site step in OneSignal Web SDK setup dashboard" />
</Frame>

<Warning>
  You must upload the OneSignal Service Worker file to your server directly. See [OneSignal Service Worker](./onesignal-service-worker).
</Warning>

### 2. Create GTM variables

Create GTM variables for values you reference across tags. This avoids hardcoding and makes your setup easier to maintain.

**Create a `ONESIGNAL_APP_ID` variable**

1. In GTM, go to **Variables > New**.
2. Choose **Constant**.
3. Name it `ONESIGNAL_APP_ID`
4. Set the value to your OneSignal App ID.
5. Save

<Frame>
  <img alt="Creating a OneSignal App ID variable in Google Tag Manager" />
</Frame>

<Check>
  You can now reference your App ID anywhere in GTM using `{{ ONESIGNAL_APP_ID }}`.
</Check>

**Create an `ONESIGNAL_EXTERNAL_ID` variable (Recommended)**

Use this if you associate users with an external identifier (for example, a user ID from your database or auth system).

Choose a variable type based on where the value lives on your site. Common options:

* Data Layer Variable (recommended)
* First-Party Cookie
* DOM Variable (advanced)

### 3. Create the OneSignal init tag

1. In GTM, go to **Tags > New**
2. Name the tag: `OneSignal - Init`
3. Tag Type: **Custom HTML**
4. Paste the below code.
5. Under **Advanced Settings > Tag firing options**, set **Once per page**.
6. Under **Triggering**, select **Initialization - All Pages**.

```html HTML theme={null}
<!--
  OneSignal – Web SDK initialization using Google Tag Manager

  This snippet:
  - Loads the OneSignal Web SDK
  - Initializes OneSignal with your App ID
  - Enables the Subscription Bell (notifyButton)

  Works for most sites out of the box.
-->

<!-- 1. Load the OneSignal Web SDK (v16) -->
<!-- This script must load on every page where you want OneSignal available -->
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>

<script>
  // Ensure the GTM dataLayer exists
  // Used here only to optionally push a "OneSignalInitialized" event
  window.dataLayer = window.dataLayer || [];

  // OneSignalDeferred is a queue that runs once the SDK is fully loaded
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  // 2. Initialize OneSignal once the SDK is ready
  window.OneSignalDeferred.push(function (OneSignal) {

    OneSignal.init({
      /*
        REQUIRED
        It is recommended to set the OneSignal App ID as a GTM variable.
        You can find this in your OneSignal Dashboard under:
        Settings > Keys & IDs
      */
      appId: "{{ONESIGNAL_APP_ID}}",

      /*
        OPTIONAL – ONLY NEEDED IF YOUR SERVICE WORKER IS NOT AT THE ROOT

        If your service worker is hosted at:
          /OneSignalSDKWorker.js

        …then you should NOT set serviceWorkerPath or serviceWorkerParam.

        Uncomment and update the options below ONLY if your service worker
        is hosted in a subdirectory (for example: /push/onesignal/).
      */

      //serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      //serviceWorkerParam: { scope: "/push/onesignal/" },

      /*
        OPTIONAL
        Enable the OneSignal Subscription Bell (notifyButton),
        which allows users to subscribe or unsubscribe from notifications.
        For more prompt options, see: https://documentation.onesignal.com/docs/en/permission-requests
      */
      notifyButton: {
        enable: true
      }
    })
    .then(function () {
      // OneSignal initialized successfully
      console.log("[OneSignal] init success");

      // Recommended: push an event to GTM for triggering other tags
      window.dataLayer.push({
        event: "OneSignalInitialized"
      });
    })
    .catch(function (e) {
      // Initialization failed (invalid App ID, missing service worker, etc.)
      console.log("[OneSignal] init failed", e);
    });
  });
</script>
```

<Frame>
  <img alt="Configuring the OneSignal - Init tag in Google Tag Manager" />
</Frame>

<Warning>
  If you use a consent banner / CMP, see [Consent Mode and privacy considerations](#consent-mode-and-privacy-considerations) options below.
</Warning>

### 4. Set External ID and tags

Setting the [External ID](./users#external-id) is optional but recommended because it allows you to identify users across devices and syncs with your backend.

**Push `ONESIGNAL_EXTERNAL_ID` into the dataLayer**

This example shows how you might push a user ID into the dataLayer so GTM can read it via the `ONESIGNAL_EXTERNAL_ID` variable (created in step 2).

```html HTML theme={null}
<script>
  window.dataLayer = window.dataLayer || [];

  // Get your user ID from your database or auth system.
  // Ensure this is a string value.
  var userId = "your_user_id_here";

  dataLayer.push({
    ONESIGNAL_EXTERNAL_ID: String(userId),
  });
</script>
```

**Create a GTM Tag to set the External ID**
Tag configuration:

* Tag name: `OneSignal – Set External ID`
* Tag type: **Custom HTML**
* Tag firing options: **Once per page**
* Trigger:
  * Create a custom event trigger for `OneSignalInitialized` (set in the above **OneSignal - Init** tag) and
  * Optionally if you know the user ID is available on the page load.

<Warning>
  The required method to set the External ID is `OneSignal.login(externalId)` where `externalId` is a string.

  If `{{ONESIGNAL_EXTERNAL_ID}}` is empty (or GTM substitutes "undefined" / "null"), the login call will be skipped and the External ID will not be set. This is a common GTM timing issue.
</Warning>

```html HTML theme={null}
<script>
  // OneSignalDeferred ensures this runs after the OneSignal SDK is ready
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  window.OneSignalDeferred.push(function (OneSignal) {
    // Read the External ID from the GTM variable created in step 2
    var externalId = "{{ONESIGNAL_EXTERNAL_ID}}";

    console.log("[OneSignal] raw external ID from GTM:", externalId);

    // GTM may substitute undefined/null as literal strings — skip login if invalid
    if (!externalId || externalId === "undefined" || externalId === "null") {
      console.log("[OneSignal] External ID missing, skipping login");
      return;
    }

    // Ensure the External ID is a clean string
    externalId = String(externalId).trim();

    console.log("[OneSignal] Calling OneSignal.login with External ID:", externalId);

    /*
      Log the user into OneSignal using the External ID.
      This links the current browser/device to this user.
    */
    OneSignal.login(externalId)
  });
</script>
```

<Accordion title="Advanced example with retry logic (use if External ID is not being set)">
  ```html HTML theme={null}
  <script>
    window.dataLayer = window.dataLayer || [];
    window.OneSignalDeferred = window.OneSignalDeferred || [];

    OneSignalDeferred.push(function (OneSignal) {
      var rawExternalId = "{{ONESIGNAL_EXTERNAL_ID}}";

      // ---- Helpers ----
      function log() {
        console.log.apply(console, ["[OneSignal External ID]"].concat([].slice.call(arguments)));
      }

      function normalizeExternalId(v) {
        // GTM commonly substitutes these as strings
        if (
          v === undefined ||
          v === null ||
          v === "undefined" ||
          v === "null"
        ) return null;

        var s = String(v).trim();
        if (!s.length) return null;

        return s;
      }

      function pushDL(eventName, extra) {
        try {
          var payload = Object.assign({ event: eventName }, extra || {});
          window.dataLayer.push(payload);
        } catch (e) {
          // no-op
        }
      }

      function readStateSnapshot() {
        var snapshot = {
          onesignalId: null,
          externalId: null,
          pushSubscriptionId: null
        };

        try {
          snapshot.onesignalId = OneSignal.User && OneSignal.User.onesignalId;
          snapshot.externalId = OneSignal.User && OneSignal.User.externalId;
          snapshot.pushSubscriptionId =
            OneSignal.User &&
            OneSignal.User.PushSubscription &&
            OneSignal.User.PushSubscription.id;
        } catch (e) {
          log("Error reading OneSignal.User state", e);
        }

        return snapshot;
      }

      function isExternalIdApplied(targetExternalId) {
        var current = normalizeExternalId(OneSignal.User && OneSignal.User.externalId);
        return current === targetExternalId;
      }

      // ---- Initial logging ----
      log("Tag fired. rawExternalId:", rawExternalId, "type:", typeof rawExternalId);

      var externalId = normalizeExternalId(rawExternalId);
      log("Normalized externalId:", externalId, "type:", typeof externalId);

      if (!externalId) {
        log("Not calling login(): externalId missing/invalid");
        pushDL("OneSignalExternalIdMissing", { reason: "invalid_or_missing_external_id" });
        return;
      }

      // Optional: enable verbose OneSignal logs during testing
      if (OneSignal.Debug && OneSignal.Debug.setLogLevel) {
        OneSignal.Debug.setLogLevel("trace");
        log("Enabled OneSignal Debug log level: trace");
      }

      // ---- Attach User State observer ----
      var changeFired = false;

      OneSignal.User.addEventListener("change", function (event) {
        changeFired = true;

        log("User change event fired:", event);

        var snapshot = readStateSnapshot();
        log("User state snapshot:", snapshot);

        // Helpful: push snapshot-ish DL event (optional)
        pushDL("OneSignalUserStateChanged", {
          onesignal_id: snapshot.onesignalId || "",
          external_id: normalizeExternalId(snapshot.externalId) || "",
          push_subscription_id: snapshot.pushSubscriptionId || ""
        });
      });

      // ---- Login + confirm + retry ----
      var attempt = 0;
      var MAX_RETRIES = 3;
      var CONFIRM_WINDOW_MS = 1500;
      var BASE_BACKOFF_MS = 500;

      function doLogin() {
        attempt += 1;
        changeFired = false;

        log("Calling OneSignal.login()", { externalId: externalId, attempt: attempt });

        OneSignal.login(externalId)
          .then(function () {
            log("OneSignal.login() promise resolved");
            waitForConfirmation();
          })
          .catch(function (e) {
            log("OneSignal.login() promise rejected", e);
            retry("promise_rejected");
          });
      }

      function waitForConfirmation() {
        var start = Date.now();

        (function check() {
          if (isExternalIdApplied(externalId)) {
            log("Confirmed externalId applied via state check:", externalId);

            var snapshot = readStateSnapshot();
            log("Final state snapshot:", snapshot);

            pushDL("OneSignalExternalIdSet", {
              external_id: externalId,
              attempt: attempt,
              push_subscription_id: snapshot.pushSubscriptionId || ""
            });

            return;
          }

          if (changeFired) {
            log("Change event observed but externalId not yet reflected; waiting...");
          }

          if (Date.now() - start >= CONFIRM_WINDOW_MS) {
            log("No confirmation within window", {
              attempt: attempt,
              changeFired: changeFired,
              currentExternalId: normalizeExternalId(OneSignal.User && OneSignal.User.externalId)
            });

            retry("no_confirmation");
            return;
          }

          setTimeout(check, 100);
        })();
      }

      function retry(reason) {
        if (attempt >= MAX_RETRIES) {
          log("Giving up after max retries", { attempts: attempt, reason: reason });

          var snapshot = readStateSnapshot();
          log("State at give-up:", snapshot);

          pushDL("OneSignalExternalIdSetFailed", {
            external_id: externalId,
            reason: reason,
            attempts: attempt,
            push_subscription_id: snapshot.pushSubscriptionId || ""
          });

          return;
        }

        var delay = BASE_BACKOFF_MS * Math.pow(2, attempt - 1);
        log("Retrying login after delay", { delayMs: delay, reason: reason, nextAttempt: attempt + 1 });

        setTimeout(doLogin, delay);
      }

      // If already applied, don't spam login()
      if (isExternalIdApplied(externalId)) {
        log("ExternalId already applied; skipping login.", externalId);

        var snapshot = readStateSnapshot();
        log("Current state snapshot:", snapshot);

        pushDL("OneSignalExternalIdAlreadySet", {
          external_id: externalId,
          push_subscription_id: snapshot.pushSubscriptionId || ""
        });

        return;
      }

      // Kick it off
      doLogin();
    });
  </script>
  ```
</Accordion>

#### Set tags

This sends [OneSignal Tags](./add-user-data-tags) using our Web SDK.

Tag configuration:

* Name: `OneSignal - Add Tags`
* Tag Type: **Custom HTML**
* Tag firing options: **Once per page**
* Trigger:
  * `OneSignalInitialized`, and
  * Your condition for when tag data is available (for example: after login, on a profile page, after purchase).

Paste this code and replace `TAG_1`/`TAG_2` and `VALUE_1`/`VALUE_2` with your tag names and values.

```html HTML theme={null}
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  window.OneSignalDeferred.push(function (OneSignal) {
    OneSignal.User.addTags({
      TAG_1: "VALUE_1",
      TAG_2: "VALUE_2",
    });
  });
</script>
```

<Note> Only send tags when you actually have the user data available (for example: after login, after a profile loads, or after a known conversion event). </Note>

#### Listen for push subscription changes

You can monitor push subscription state changes (opt-in, opt-out, token updates) by adding an event listener. This is useful for syncing subscription status with your analytics or backend systems via the GTM dataLayer.

Tag configuration:

* Name: `OneSignal - Push Subscription Listener`
* Tag Type: **Custom HTML**
* Tag firing options: **Once per page**
* Trigger: `OneSignalInitialized`

```html HTML theme={null}
<script>
  /*
    Callback fired whenever the push subscription state changes.
    The event object contains previous and current snapshots so you
    can detect opt-ins, opt-outs, and token refreshes.
  */
  function pushSubscriptionChangeListener(event) {
    // Subscription ID before and after the change
    console.log("event.previous.id", event.previous.id);
    console.log("event.current.id", event.current.id);

    // Push token (device token) before and after the change
    console.log("event.previous.token", event.previous.token);
    console.log("event.current.token", event.current.token);

    // Whether the user was/is opted in to push notifications
    console.log("event.previous.optedIn", event.previous.optedIn);
    console.log("event.current.optedIn", event.current.optedIn);
  }

  // Ensure the OneSignalDeferred queue exists
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  OneSignalDeferred.push(function(OneSignal) {
    // Register the listener on the PushSubscription object
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });
</script>
```

### Consent Mode and privacy considerations

If your site uses Consent Mode / a CMP, decide whether OneSignal should load:

* Only after consent (common for EU/UK), or
* Immediately (common where "functional" storage is allowed by default).

GTM supports a Consent Initialization trigger and tag-level consent controls to manage tag behavior based on user consent. However, OneSignal also provides privacy consent methods to control when the SDK loads.

* [Handling personal data](./handling-personal-data)
* [Web SDK Privacy Methods](./web-sdk-reference#privacy)

***

## Testing

1. In GTM, open Preview mode.
2. Load your site and confirm:
   * `OneSignal - Init` fires once.
   * `OneSignalInitialized` appears in the GTM event timeline (if you kept the event push).
3. Subscribe to your website. See [Web permission prompts](./permission-requests) for prompting details.
4. In the OneSignal dashboard, go to **Audience > Subscriptions** and confirm:
   * A Subscription appears after you opt in.
   * An External ID is visible if you set one.
5. Send a test push from **Messages > New Push**.

<Check> If initialization is working, you’ll see subscriptions appearing in OneSignal after opt-in. </Check>

### Troubleshooting

* Init tag fires, but SDK never loads
  * Check for Content Security Policy (CSP) blocking `https://cdn.onesignal.com`.
  * Check for ad blockers/script blockers.

* `dataLayer` errors
  * Ensure `window.dataLayer = window.dataLayer || []` is set before any `dataLayer.push()` calls.

* Duplicate prompts / duplicate SDK load
  * Make sure you are not also loading OneSignal via site code, a CMS plugin, or another GTM tag.

* Add Tags runs but doesn’t appear in OneSignal
  * Confirm the Trigger Group waits for `OneSignalInitialized`.
  * Confirm your user action trigger actually fires.
  * Confirm tags are valid key/value pairs and within [Plan limits](https://onesignal.com/pricing).

<Note>
  For additional help, see [Web SDK troubleshooting](./troubleshooting-web-push).
</Note>

## FAQ

### Does OneSignal work with GTM Consent Mode?

Yes. You can control when OneSignal loads using GTM's consent controls or OneSignal's own privacy methods. If your site requires consent before loading scripts, configure the init tag's trigger to fire only after consent is granted, or use OneSignal's `setConsentRequired` and `setConsentGiven` methods. See [Handling personal data](./handling-personal-data) for details.

### Why isn't my External ID being set?

The most common cause is a GTM timing issue where `{{ONESIGNAL_EXTERNAL_ID}}` resolves to `"undefined"` or `"null"` because the dataLayer variable isn't populated yet when the tag fires. Verify the variable has a value in GTM Preview mode before the tag executes. If the value loads asynchronously, use the [advanced example with retry logic](#4-set-external-id-and-tags).

### Can I load OneSignal through both GTM and site code?

No. Loading the OneSignal SDK more than once causes duplicate prompts and unpredictable behavior. Use either GTM or direct site code, not both. Also check for CMS plugins that may inject OneSignal separately.

***

## Related pages

<Columns>
  <Card title="Web permission prompts" icon="bell" href="./permission-requests">
    Configure how and when to prompt visitors for web push permission.
  </Card>

  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Set key-value data on Users for personalization and segmentation.
  </Card>

  <Card title="Web SDK reference" icon="globe" href="./web-sdk-reference">
    Full method and event reference for the OneSignal Web SDK.
  </Card>

  <Card title="Handling personal data" icon="shield-halved" href="./handling-personal-data">
    Manage user consent and control which data the OneSignal SDK collects.
  </Card>
</Columns>


# Huawei SDK setup
Source: https://documentation.onesignal.com/docs/en/huawei-sdk-setup

OneSignal Huawei SDK Setup Guide for Android Studio.

## Overview

This guide explains how to integrate OneSignal push notifications into a Huawei app distributed on the Huawei AppGallery.

These instructions are for native apps written in Java or Kotlin. For other supported SDKs see:

<Columns>
  <Card title="Ionic/Cordova/Capacitor" href="./huawei-cordova-sdk-setup" />

  <Card title="Flutter" href="./huawei-flutter-sdk-setup" />

  <Card title="React Native" href="./huawei-react-native-sdk-setup" />

  <Card title="Unity" href="./huawei-unity-sdk-setup" />
</Columns>

***

## Requirements

* [Android Studio](https://developer.android.com/studio)
* A Huawei device with "Huawei App Gallery" installed
* Configured OneSignal App and Platform

***

### Configure your OneSignal app and platform

Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).

<Note>
  If your organization already has a OneSignal account, [ask to be invited](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Step-by-step setup instructions" icon="circle-chevron-down">
  <Steps>
    <Step title="Create or select your app">
      Create a new app by clicking **New App/Website**, or add a platform to an existing app in **Settings > Push & In-App**. Select the platform(s) you want to configure and click **Next: Configure Your Platform**.

      <Frame>
        <img alt="OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection" />
      </Frame>
    </Step>

    <Step title="Configure platform credentials">
      Enter the credentials for your platform:

      * **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
      * **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
      * **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
      * **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)

      Click **Save & Continue** after entering your credentials.
    </Step>

    <Step title="Save your App ID and install the SDK">
      Your **App ID** is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.

      <Frame>
        <img alt="OneSignal dashboard showing the App ID and team invite option after setup" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

***

## Setup

### 1. Setup the OneSignal SDK

<Card title="OneSignal Android SDK setup" href="./android-sdk-setup">
  Follow the OneSignal Android SDK setup guide to implement our SDK into your app.
  Note that Firebase/Google setup is not required for app builds released to the Huawei AppGallery.
</Card>

### 2. Huawei configuration (agconnect-services.json)

<Info>
  You can skip this step if you already have a Huawei `agconnect-services.json` in your Android Studio Project from setting up a different Huawei service.
</Info>

From the [AppGallery Connect Project List](https://developer.huawei.com/consumer/en/service/josp/agc/index.html#/myProject) select your app.

Click on the "agconnect-services.json" button to download this file.

<Frame>
  <img />
</Frame>

Place this file in your app directory in Android Studio.

<Frame>
  <img />
</Frame>

### 3. Generating a signing certificate fingerprint

<Info>
  You can skip this step if you already have added your SHA-256 certificate fingerprint to Huawei's dashboard for a different Huawei service.
</Info>

From your Android Studio go to **View > Tool Windows > Gradle**.

<Frame>
  <img />
</Frame>

From here select **app > Tasks > android > signingReport**.

<Frame>
  <img />
</Frame>

Copy your `SHA-256` for your `release` variant.

* Optional but recommended for quicker testing is the `SHA-256` for your `debug` variant too.
* You may have other custom variants in your project, if you need push support for them copy these as well.

<Frame>
  <img />
</Frame>

From the [AppGallery Connect Project List](https://developer.huawei.com/consumer/en/service/josp/agc/index.html#/myProject) select your app.

Scroll to the bottom to find the "SHA-256 certificate fingerprint" field were you should enter your keys.

<Frame>
  <img />
</Frame>

### 4. Add Huawei gradle plugin and dependencies

<Tabs>
  <Tab title="Groovy + AGP 7.x">
    Open your root `build.gradle` (Project: ) in Android Studio and add ` maven {url 'https://developer.huawei.com/repo/'}` under `buildscript { repositories }` and `allprojects { repositories }`
  </Tab>

  <Tab title="Kotlin + AGP 8.x">
    Open your `settings.gradle.kts` file and add `maven {url 'https://developer.huawei.com/repo/'}` under `pluginManagement { repositories }` and `dependencyResolutionManagement { repositories }`
  </Tab>
</Tabs>

Under `buildscript { dependencies }` add `classpath 'com.huawei.agconnect:agcp:1.9.1.301'`

You should have in total 3 new lines in your root `build.gradle`, highlighted below.

<Frame>
  <img />
</Frame>

Open your `app/build.gradle` file and add `implementation 'com.huawei.hms:push:6.3.0.304'` under the `dependencies` section.

Also to the `app/build.gradle` file add `apply plugin: 'com.huawei.agconnect'` to the very bottom of the file.

You should have in total 2 new lines in your `app/build.gradle`, highlighted below.

<Tip>
  Make sure to press "Sync Now" on the banner that pops up after saving!
</Tip>

<Frame>
  <img />
</Frame>

***

## Additional configuration steps

### Compatibility with other HMS push libraries or your own `HmsMessageService` class

Required if:

* You have another HMS push SDK/Library in your app in-addition to OneSignal
* You have your own `HmsMessageService`

<Accordion title="More details...">
  Create a class that extends from `HmsMessageService`, if you don't have one already and add the following methods.

  <Warning>
    If you already had a class that extends `HmsMessageService` please add the two
    new `OneSignalHmsEventBridge` lines instead of creating another class.
  </Warning>

  ```java Java theme={null}
  public class YourHmsMessageService extends HmsMessageService {
    public void onNewToken(String token) {
        // ...
        // Forward event on to OneSignal SDK
        OneSignalHmsEventBridge.onNewToken(this, token);
    }

    @Override
    public void onMessageReceived(RemoteMessage message) {
        // ...
        // Forward event on to OneSignal SDK
        OneSignalHmsEventBridge.onMessageReceived(this, message);
    }
  }
  ```

  This is to forward `onNewToken` and `onMessageReceived` to OneSignal via the `OneSignalHmsEventBridge`.

  If you didn't have a class that extended `HmsMessageService` before make sure to add it to your `AndroidManifest.xml` under the `<application>` tag.

  ```xml AndroidManifest.xml theme={null}
  <application>
      ...

      <!--
        Ensure you only have one intent-filter for "com.huawei.push.action.MESSAGING_EVENT".
        HMS only supports one per app.
      -->
      <service
          android:name=".YourHmsMessageService"
          android:exported="false">
          <intent-filter>
              <action android:name="com.huawei.push.action.MESSAGING_EVENT" />
          </intent-filter>
      </service>

      ...
  </application>
  ```
</Accordion>

### Omit Google libraries for Huawei AppGallery builds (optional)

<Accordion title="More details...">
  <Tabs>
    <Tab title="Option 1">
      If your app will only be available on the Huawei AppGallery and you want to omit any Google related dependencies that OneSignal includes you can use `exclude` with `implementation` in your `app/build.gradle`.

      <CodeGroup>
        ```groovy app/build.gradle theme={null}
        implementation('com.onesignal:OneSignal:[5.4.0, 5.99.99]') {
            exclude group: 'com.google.android.gms'
            exclude group: 'com.google.firebase'
        }
        ```
      </CodeGroup>
    </Tab>

    <Tab title="Option 2">
      If your app will be for both the Google Play Store and Huawei AppGallery and you want to be selective on which libraries you will include to make your APK smaller you can add dependencies based on buildTypes or variants. Example:

      <CodeGroup>
        ```groovy app/build.gradle theme={null}
        android {
          // ...
           buildTypes {
               debug {
               }
               release {
               }
               // **** Add your custom hauwei buildType here
               huawei {
               }
           }
        }

        dependencies {
        // \*\*\*\* Use the full OneSignal dependencies for Google Play Store builds
        debugImplementation 'com.onesignal:OneSignal:[5.0.0, 5.99.99]'
        releaseImplementation 'com.onesignal:OneSignal:[5.0.0, 5.99.99]'

            // **** Only include hms:push for your Huawei AppGallery builds.
            huaweiImplementation 'com.huawei.hms:push:6.3.0.304'
            // Omit Google / Firebase libraries for Huawei builds.
            huaweiImplementation('com.onesignal:OneSignal:[5.0.0, 5.99.99]') {
                exclude group: 'com.google.android.gms'
                exclude group: 'com.google.firebase'
            }

        }

        ```
      </CodeGroup>
    </Tab>
  </Tabs>
</Accordion>

### Prefer HMS over FCM (optional)

<Accordion title="More details...">
  ***If you have [omitted Google Libraries](./huawei-sdk-setup#omit-google-libraries-for-huawei-appgallery-builds-optional) for Huawei AppGallery build above, this step doesn't apply.***

  By default OneSignal prefers using FCM over HMS if both are included in your app. If you like to change this to prefer HMS instead you can add the following to your `AndroidManifest.xml`:

  <CodeGroup>
    ```xml xml theme={null}
    <application>
            ...
            <meta-data android:name="com.onesignal.preferHMS" android:value="true"/>
            ...
     </application>
    ```
  </CodeGroup>
</Accordion>

***

## Huawei troubleshooting

While testing, make sure to keep the [OneSignal setLogLevel method](./mobile-sdk-reference#setloglevel) set to VERBOSE.

Check the logs to see any errors being thrown and [Huawei Common Error Codes](https://developer.huawei.com/consumer/en/doc/development/HMS-2-References/hmssdk_huaweipush_api_reference_errorcode).

<Accordion title="6003 error">
  You may need to create a debug or release keystore signature (choose the correct app build path, `debug` or `release`) so that a `6003` error is avoided when registering for Huawei `pushToken` with the OneSignal SDK. See ["Configure a Signature" section](https://developer.huawei.com/consumer/en/doc/HMS-Guides/Preparations#h2-1584707362385)
</Accordion>

<Accordion title="notification_types: -25">
  `"notification_types":-25` means OneSignal timed out waiting for a response from Huawei's HMS to get a push token. This is most likely due to another 3rd-party HMS push SDK or your own HmsMessageService getting this event instead of OneSignal.

  Please review [step on how to check this and forward the event if this is the case](#compatibility-with-other-hms-push-libraries-or-your-own-hmsmessageservice-class).
</Accordion>

<Accordion title="notification_types: -28">
  This means there is a class HMS is missing from the app that is needed for push. Just having `com.huawei.hms:push` in the `build.gradle` will cause this specific error not to happen any more. However, if you have some aggressive Proguard or R8 settings, this might cause issues. We recommend turn off `minifyEnabled` temporary if you have it to see if that is the root of the issue.

  Also, you shouldn't mix and match major release versions of other HMS libraries. Start with either 4 or 5. Make sure not to have a mixture from 3 to 5 which is going to create other errors
</Accordion>

<Accordion title="Error getting Huawei push token">
  ```
  E/OneSignal: HMS ApiException getting Huawei push token!
      com.huawei.hms.common.ApiException: -5: Core error
  ```

  Check your Proguard or R8 rules to make sure they are setup properly. Possibly disable it temporarily to see if it is related. If it fixes the issue after disabling Proguard or R8 then you can follow this guide and turn it back on See ["Configure a Signature" section](https://developer.huawei.com/consumer/en/doc/HMS-Guides/Preparations#h2-1584707362385)
</Accordion>

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications, subscription registration, and in-app messaging.

<Warning>
  If you are testing with an Android emulator, it should start with a cold boot.

  1. Go to **Device Manager** in Android Studio.
  2. Select your emulator device and click **Edit**.
  3. Go to **Additional Settings** or **More**.
  4. Set the **Boot option** to **Cold Boot**.
  5. Save changes and restart the emulator.
</Warning>

### Check mobile subscriptions

<Steps>
  <Step title="Launch your app on a test device.">
    The native push permission prompt should appear automatically if you added the `requestPermission` method during initialization.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    Before accepting the prompt, check the OneSignal dashboard:

    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status "Never Subscribed".

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Return to the app and tap Allow on the prompt." />

  <Step title="Refresh the OneSignal dashboard Subscription's page.">
    The subscription's status should now show **Subscribed**.

    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a [mobile subscription](/docs/en/subscriptions).
    Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a segment of test users.
    We can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

    ```curl theme={null}
    curl -X \
    POST --url 'https://api.onesignal.com/notifications' \
     --header 'content-type: application/json; charset=utf-8' \
     --header 'authorization: Key YOUR_APP_API_KEY' \
     --data \
     '{
      "app_id": "YOUR_APP_ID",
      "target_channel": "push",
      "name": "Testing basic setup",
      "headings": {
      	"en": "👋"
      },
      "contents": {
        "en": "Hello world!"
      },
      "included_segments": [
        "Test Users"
      ],
      "ios_attachments": {
        "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      },
      "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
    }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification with an image included:

    <Frame>
      <img />
    </Frame>

    <Info>Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Info>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats.

    You should see the **confirmed** stat, meaning the device received the push.
    <Check>You have successfully sent a notification via our API to a segment.</Check>

    <Warning>
      * No image received? Your [Notification Service Extension](#ios-setup) might be missing.
      * No confirmed receipt? Review the troubleshooting guide [here](/docs/en/confirmed-delivery#troubleshooting-confirmed-delivery).
      * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
    </Warning>
  </Step>
</Steps>

### Send an in-app message

[In-app messages](/docs/en/in-app-messages-setup) let you communicate with users while they are using your app.

<Steps>
  <Step title="Close or background your app on the device.">
    This is because users must meet the in-app audience criteria *before* a new session starts. In OneSignal, a new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds. For more details, see our guide on [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
  </Step>

  <Step title="Create an in-app message.">
    * In your OneSignal dashboard, navigate to **Messages > In-App > New In-App**.
    * Find and select the **Welcome** message.
    * Set your Audience as the **Test Users** segment we used previously.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Customize the message content if desired.">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Set Trigger to 'On app open'." />

  <Step title="Schedule frequency.">
    Under **Schedule > How often do you want to show this message?** select **Every time trigger conditions are satisfied**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Make message live.">
    Click **Make Message Live** so it is available to your Test Users each time they open the app.
  </Step>

  <Step title="Open the app and see the message.">
    After the in-app message is live, open your app. You should see it display:

    <Frame>
      <img />
    </Frame>

    <Warning>
      Not seeing the message?

      * Start a new session
        * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
        * For more, see [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
      * Still in the `Test Users` segment?
        * If you reinstalled or switched devices, re-add the device to [Test Users](#set-up-test-users) and confirm it's part of the Test Users segment.
      * Having issues?
        * Follow [Getting a Debug Log](/docs/en/capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
    </Warning>
  </Step>
</Steps>

<Check>
  You have successfully setup the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](/docs/en/subscriptions), setting [Test Users](/docs/en/find-set-test-subscriptions), and creating [Segments](/docs/en/segmentation).
  * Sending [Push](/docs/en/push) with images and [Confirmed receipt](/docs/en/confirmed-delivery) using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](/docs/en/in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

***

## User identification

Previously, we demonstrated how to create mobile [Subscriptions](/docs/en/subscriptions). Now we'll expand to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We'll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with our SDK's [`login` method](/docs/en/mobile-sdk-reference#login-external-id) each time they are identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with our SDK [`addTag` and `addTags` methods](/docs/en/mobile-sdk-reference#data-tags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img />
</Frame>

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

### Add email and/or SMS subscriptions

Earlier we saw how our SDK creates mobile subscriptions to send push and in-app messages. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/mobile-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/mobile-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/mobile-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/mobile-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

See our Privacy & security docs for more on:

* [Data collected by the SDK](/docs/en/data-collected-by-the-onesignal-sdk)
* [Handling personal data](/docs/en/handling-personal-data)

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](/docs/en/prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners for you to hook into. See our [SDK reference guide](/docs/en/mobile-sdk-reference) for more details.

### Push notification events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-push): Detect when a notification is tapped. Helpful for [Deep Linking](/docs/en/deep-linking).
* [`addForegroundLifecycleListener()`](/docs/en/mobile-sdk-reference#addforegroundlifecyclelistener-push): Control how notifications behave in foreground.

For full customization, see [Mobile Service Extensions](/docs/en/service-extensions).

### User state changes

* [`addObserver()` for user state](/docs/en/mobile-sdk-reference#addobserver-user-state): Detect when the External ID is set.
* [`addPermissionObserver()`](/docs/en/mobile-sdk-reference#addpermissionobserver-push): Track the user's specific interaction with the native push permission prompt.
* [`addObserver()` for push subscription](/docs/en/mobile-sdk-reference#addobserver-push-subscription-changes): Track when the push subscription status changes.

### In-app message events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Handle in-app click actions. Ideal for deep linking or tracking events.
* [`addLifecycleListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Track full lifecycle of in-app messages (shown, clicked, dismissed, etc.).

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

* [🔁 Migrating to OneSignal from another service](/docs/en/migrating-to-onesignal)
* [🌍 Location tracking](/docs/en/mobile-sdk-reference#location)
* [🔗 Deep Linking](/docs/en/deep-linking)
* [🔌 Integrations](/docs/en/integrations)
* [🧩 Mobile Service Extensions](/docs/en/service-extensions)
* [🛎️ Action buttons](/docs/en/action-buttons)
* [🌐 Multi-language messaging](/docs/en/multi-language-messaging)
* [🛡️ Identity Verification](/docs/en/identity-verification)
* [📊 Custom Outcomes](/docs/en/custom-outcomes)
* [📲 Live Activities](/docs/en/live-activities)

### Mobile SDK setup & reference

Make sure you've enabled all key features by reviewing the [Mobile push setup](/docs/en/mobile-push-setup) guide.

For full details on available methods and configuration options, visit the [Mobile SDK reference](/docs/en/mobile-sdk-reference).

<Check>Congratulations! You've successfully completed the Mobile SDK setup guide.</Check>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Build a button-driven onboarding carousel
Source: https://documentation.onesignal.com/docs/en/in-app-onboarding-carousel-tutorial

Create a multi-step onboarding flow using HTML In-App Messages with button navigation and automatic dismissal.

## Overview

This tutorial shows you how to create a **multi-step onboarding carousel** using a single HTML In-App Message. Unlike traditional carousels that rely on swipe gestures, this approach uses **button-driven navigation** and keeps all steps within one message.

**What you'll build:**

* A two-step onboarding flow with images, text, and buttons
* Button navigation (tap "Next" to advance, tap "Get Started" to dismiss)
* Progress indicator dots
* Smooth fade transitions between steps

<Frame>
  <img alt="Onboarding carousel showing welcome screen with image, text, and Next button" />
</Frame>

**Use this approach when you want to:**

* Guide users through a **short onboarding or education flow** (2-5 steps)
* Require users to **explicitly tap a button** to continue (no swipe gestures)
* Keep everything inside **one HTML In-App Message** for simplicity
* Automatically dismiss the message when the flow is complete

<Info>
  This guide uses an HTML In-App Message for full control. You can also [build card-based onboarding flows with the drag-and-drop editor](./design-your-in-app-message#carousels)—those cards are swipable but offer less customization.
</Info>

***

## Prerequisites

Before you begin, make sure you have:

* An active OneSignal app with In-App Messages enabled
* [Permission to create or edit HTML In-App Messages](./manage-team-members#team-members)
* [Mobile SDK](./mobile-sdk-setup) installed in your mobile app
* Basic understanding of HTML, CSS, and JavaScript

***

## How the multi-step flow works

Before diving into the code, it's important to understand the technical approach. This implementation uses **one HTML In-App Message** that switches between steps by **showing and hiding content**, not by loading multiple separate messages.

The architecture relies on **four core components**:

<Steps>
  <Step title="Card containers for each step">
    Each step is wrapped in a `<div>` with the `card` class and a unique ID:

    ```html theme={null}
    <div id="card-0" class="card active">...</div>
    <div id="card-1" class="card">...</div>
    ```

    * All cards exist in the DOM simultaneously
    * Only one card is visible at a time (controlled by the `active` class)
  </Step>

  <Step title="CSS visibility control">
    CSS handles the show/hide logic using opacity and pointer events:

    ```css theme={null}
    .card {
      opacity: 0;
      pointer-events: none;  /* Prevents interaction with hidden cards */
      transition: opacity .25s ease;
    }

    .card.active {
      opacity: 1;
      pointer-events: auto;  /* Allows interaction with visible card */
    }
    ```

    **Why this matters:**

    * `opacity: 0` hides the card visually but keeps it in the layout
    * `pointer-events: none` prevents accidental clicks on hidden cards
    * `transition` creates smooth fade effects
  </Step>

  <Step title="JavaScript state management">
    The `setActive(i)` function controls which card is visible:

    ```javascript theme={null}
    function setActive(i) {
      // Update card visibility
      document.getElementById("card-0").className = i === 0 ? "card active" : "card";
      document.getElementById("card-1").className = i === 1 ? "card active" : "card";
      
      // Update progress dots
      var dots = document.getElementById("dots").children;
      dots[0].classList.toggle("active", i === 0);
      dots[1].classList.toggle("active", i === 1);
    }
    ```

    This function:

    * Removes `active` from all cards
    * Adds `active` to the target card
    * Updates progress indicator dots
  </Step>

  <Step title="Button event listeners">
    Buttons trigger navigation or dismissal:

    ```javascript theme={null}
    // Advance to next step
    document.getElementById("next-0").addEventListener("click", function () {
      setActive(1);
    });

    // Dismiss the In-App Message
    document.getElementById("done").addEventListener("click", function (e) {
      if (window.OneSignalIamApi && OneSignalIamApi.close) {
        OneSignalIamApi.close(e);
      }
    });
    ```

    **Important:** `OneSignalIamApi.close(e)` is the OneSignal SDK method that dismisses the In-App Message from within the HTML.
  </Step>
</Steps>

<Note>
  **Key insight:** This is a **single-page application (SPA)** pattern within an In-App Message. All content is loaded once, and JavaScript manages state changes without reloading.
</Note>

***

## Step 1: Create a new HTML In-App Message

1. In the OneSignal dashboard, go to **Messages → In-App Messages**
2. Click **New In-App Message**
3. Select **HTML** as the message type
4. Choose **Full Screen** or **Large** layout (recommended for onboarding to maximize visual impact)
5. Continue to the HTML editor

<Note>
  The HTML editor preview may not fully reflect runtime behavior. Always test on a real device or test user to verify animations, button behavior, and the dismiss action.
</Note>

***

## Step 2: Add the HTML template

Replace the editor contents with the template below. This template includes:

* **Self-contained code:** All HTML, CSS, and JavaScript in one file
* **Button-driven navigation:** No swipe gestures (more reliable across devices)
* **Fade transitions:** Smooth opacity changes between steps
* **OneSignal SDK integration:** Uses `OneSignalIamApi.close(e)` to dismiss the message
* **Mobile-optimized:** Responsive layout with viewport meta tag

<Accordion title="View complete HTML template">
  ```html theme={null}
  <!doctype html>
  <html>
  <head>
    <meta charset="UTF-8" />
    <!-- viewport-fit=cover ensures safe area coverage on notched devices -->
    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
    <style>
      /* Base styles - reset and system font */
      html, body {
        margin: 0;
        padding: 0;
        background: #ffffff;
        font-family: -apple-system, system-ui;
      }

      /* Main container with padding */
      .wrap { 
        padding: 28px 22px 24px; 
      }

      /* Stage container - holds all cards in same position */
      .stage {
        position: relative;
        min-height: 74vh;  /* Ensures enough vertical space */
      }

      /* Card - each step of the onboarding flow */
      .card {
        position: absolute;  /* All cards overlap in same position */
        inset: 0;            /* Full coverage of stage */
        display: flex;
        flex-direction: column;
        align-items: center;
        opacity: 0;               /* Hidden by default */
        pointer-events: none;     /* Prevents clicks when hidden */
        transition: opacity .25s ease;  /* Smooth fade effect */
      }

      /* Active card is visible and interactive */
      .card.active {
        opacity: 1;
        pointer-events: auto;
      }

      /* Typography */
      h1 {
        margin: 44px 0 12px;
        font-size: 26px;
        text-align: center;
      }

      p {
        margin: 0;
        color: #6b7280;
        text-align: center;
        max-width: 260px;
        line-height: 1.35;
      }

      /* Image container - square with rounded corners */
      .image {
        width: 240px;
        height: 240px;
        border-radius: 16px;
        margin: 24px 0 12px;
        background-size: cover;
        background-position: center;
      }

      /* Primary button */
      .btn {
        margin-top: auto;  /* Pushes button to bottom of card */
        width: 100%;
        max-width: 260px;
        height: 52px;
        border: 0;
        border-radius: 12px;
        background: #3b82f6;  /* Blue - customize to match your brand */
        color: #fff;
        font-size: 18px;
        font-weight: 600;
      }

      /* Progress indicator dots */
      .dots {
        display: flex;
        justify-content: center;
        gap: 8px;
        padding: 12px 0 8px;
      }

      .dot {
        width: 8px;
        height: 8px;
        border-radius: 999px;
        background: #d1d5db;  /* Inactive dot color */
      }

      .dot.active {
        background: #6b7280;  /* Active dot color */
        transform: scale(1.15);  /* Slightly larger when active */
      }
    </style>
  </head>

  <body>
    <div class="wrap">
      <div class="stage">

        <!-- STEP 1: Welcome card (starts visible with "active" class) -->
        <div id="card-0" class="card active">
          <h1>Welcome</h1>
          <div
            class="image"
            style="background-image: url('https://images.pexels.com/photos/6153129/pexels-photo-6153129.jpeg');">
          </div>
          <p>Build a calm daily habit in minutes.</p>
          <button
            id="next-0"
            class="btn"
            data-onesignal-unique-label="onboarding_next_0">
            Next
          </button>
        </div>

        <!-- STEP 2: Breathe card (starts hidden, shown when user taps "Next") -->
        <div id="card-1" class="card">
          <h1>Breathe</h1>
          <div
            class="image"
            style="background-image: url('https://images.pexels.com/photos/417173/pexels-photo-417173.jpeg');">
          </div>
          <p>Guided breathing whenever you need a reset.</p>
          <button
            id="done"
            class="btn"
            data-onesignal-unique-label="onboarding_done">
            Get Started
          </button>
        </div>

      </div>

      <!-- Progress indicator: 2 dots, first one starts active -->
      <div class="dots" id="dots">
        <div class="dot active"></div>
        <div class="dot"></div>
      </div>
    </div>

    <script>
      (function () {
        /**
         * Switch between cards by toggling "active" class
         * @param {number} i - Index of card to show (0 or 1)
         */
        function setActive(i) {
          // Update card visibility
          document.getElementById("card-0").className = i === 0 ? "card active" : "card";
          document.getElementById("card-1").className = i === 1 ? "card active" : "card";

          // Update progress dots
          var dots = document.getElementById("dots").children;
          dots[0].classList.toggle("active", i === 0);
          dots[1].classList.toggle("active", i === 1);
        }

        // Button: Next (card 0 → card 1)
        document.getElementById("next-0").addEventListener("click", function () {
          setActive(1);
        });

        // Button: Get Started (dismisses the In-App Message)
        document.getElementById("done").addEventListener("click", function (e) {
          // Check if OneSignal IAM API is available
          if (window.OneSignalIamApi && OneSignalIamApi.close) {
            OneSignalIamApi.close(e);  // Dismiss the message
          }
        });
      })();
    </script>
  </body>
  </html>
  ```
</Accordion>

***

## Step 3: Customize your content

### Safe to customize

You can modify these elements without breaking functionality:

**Content:**

* Headline text in `<h1>` tags
* Body copy in `<p>` tags
* Button labels (`Next`, `Get Started`)
* Image URLs in the `background-image: url('...')` styles

**Visual styling:**

* Colors: Change `.btn` background, text color, or dot colors
* Spacing: Adjust padding and margins
* Typography: Modify font-family, font-size, font-weight
* Border radius: Update `border-radius` values for buttons and images

### Adding more steps

To add a third step, follow this pattern:

1. **Add the HTML card:**

```html theme={null}
<div id="card-2" class="card">
  <h1>Your Title</h1>
  <div class="image" style="background-image: url('your-image-url');"></div>
  <p>Your description</p>
  <button id="next-2" class="btn">Next</button>
</div>
```

2. **Add a progress dot:**

```html theme={null}
<div class="dots" id="dots">
  <div class="dot active"></div>
  <div class="dot"></div>
  <div class="dot"></div> <!-- New dot -->
</div>
```

3. **Update the `setActive()` function:**

```javascript theme={null}
function setActive(i) {
  document.getElementById("card-0").className = i === 0 ? "card active" : "card";
  document.getElementById("card-1").className = i === 1 ? "card active" : "card";
  document.getElementById("card-2").className = i === 2 ? "card active" : "card"; // New card
  
  var dots = document.getElementById("dots").children;
  dots[0].classList.toggle("active", i === 0);
  dots[1].classList.toggle("active", i === 1);
  dots[2].classList.toggle("active", i === 2); // New dot
}
```

4. **Update the previous step's button ID:**
   Change `id="done"` to `id="next-1"` on card 1's button, then add a click listener:

```javascript theme={null}
document.getElementById("next-1").addEventListener("click", function () {
  setActive(2);
});
```

5. **Add the dismiss button to the new last card (card-2):**

```javascript theme={null}
document.getElementById("done").addEventListener("click", function (e) {
  if (window.OneSignalIamApi && OneSignalIamApi.close) {
    OneSignalIamApi.close(e);
  }
});
```

<Warning>
  Keep onboarding flows short (2-4 steps maximum). Users drop off quickly in longer flows. Test completion rates with [click tracking](./in-app-message-api#click-name).
</Warning>

***

## Step 4: Test the In-App Message

### Testing checklist

1. **Save** the message in the OneSignal dashboard
2. **Configure delivery settings:**
   * Set trigger conditions (e.g., session start, specific page view)
   * Choose your target audience or select a test user
3. **Send to a test device:**
   * Use [Test Users](./test-users) to preview without affecting production users
   * Install your app on a physical device (recommended over simulators for accurate behavior)
4. **Verify functionality:**
   * ✓ First card appears with correct content
   * ✓ "Next" button advances to card 2
   * ✓ Progress dots update correctly
   * ✓ Fade transitions are smooth
   * ✓ "Get Started" button dismisses the message
   * ✓ Message doesn't reappear immediately (check frequency capping settings)

<Note>
  Simulators/emulators may not accurately reflect real device behavior, especially for touch interactions and SDK integrations. Always test on physical devices before launching to production.
</Note>

### Troubleshooting common issues

| Issue                             | Likely cause                     | Solution                                                                                     |
| --------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- |
| Message doesn't appear            | Trigger conditions not met       | Check [In-App Message Triggers](./iam-triggers) and verify your test user meets the criteria |
| Buttons don't work                | JavaScript errors or ID mismatch | Check browser console for errors; verify button IDs match event listener IDs                 |
| Images don't load                 | CORS issues or invalid URLs      | Use HTTPS URLs; test image URLs in a browser first                                           |
| Message appears but won't dismiss | OneSignal SDK not loaded         | Verify [Mobile SDK setup](./mobile-sdk-setup) is complete                                    |

***

## Next steps

**Track user engagement:**

* Add click tracking using [`data-onesignal-unique-label`](./in-app-message-api#click-name) attributes (already included in the template) to measure drop-off between steps
* View click analytics in **Messages → In-App Messages → \[Your Message] → Analytics**

**Personalize the experience:**

* [Tag users](./in-app-message-api#tag-user) who complete onboarding (e.g., `onboarding_completed: true`)
* Use tags to [segment users](./segmentation) and prevent re-showing the onboarding flow
* [Add user data](./add-user-data-tags) to personalize content in future messages

**Advanced customization:**

* [Deep link](./deep-linking#send-in-app-messages-with-deep-links) users to a specific screen after dismissal
* Use [Liquid syntax](./using-liquid-syntax) to personalize headlines with user names or attributes
* Implement A/B testing with different onboarding flows to optimize completion rates


# iOS: Image Carousel Push Notifications
Source: https://documentation.onesignal.com/docs/en/ios-image-carousel-push-notifications

How to implement an image carousel in OneSignal iOS push notifications using Swift.

iOS provides a [UNNotificationContentExtension](https://developer.apple.com/documentation/usernotificationsui/unnotificationcontentextension?language=objc) protocol as the entry point for a notification content app extension. This can be used to display a custom interface for your app’s notifications. This example guide explains how to use this for creating a carousel within an iOS notification.

<Frame>
  <img />
</Frame>

## 1. Add a notification content extension

<Card>
  In Xcode, select File > New > Target...
</Card>

<Card>
  Select "Notification Content Extension"
</Card>

<Card>
  Confirm the selection on the window that pops up
</Card>

<Card>
  Select activate to debug
</Card>

## 2. Add code to your app

[Download the OSNotificationContentExtension](https://github.com/dombartenope/OSNotificationContentExtension) from Github and replace the `OSNotificationContentExtension` in your Xcode Project with the same file from Github.

You should see the following files added:

<Frame>
  <img />
</Frame>

## 3. Set your notification category

This example [Declares The Actionable Notification Type](https://developer.apple.com/documentation/usernotifications/declaring_your_actionable_notification_types) within the AppDelegate.swift `didFinishLaunchingWithOptions`.

<CodeGroup>
  ```swift Swift theme={null}
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

      //START Authorize OS Notification Carousel Category
      if #available(iOS 10.0, *) {
          let options: UNAuthorizationOptions = [.alert]
          UNUserNotificationCenter.current().requestAuthorization(options: options) { (authorized, error) in
              if authorized {
                  let categoryIdentifier = "OSNotificationCarousel"
                  let carouselNext = UNNotificationAction(identifier: "OSNotificationCarousel.next", title: "👉", options: [])
                  let carouselPrevious = UNNotificationAction(identifier: "OSNotificationCarousel.previous", title: "👈", options: [])
                  let carouselCategory = UNNotificationCategory(identifier: categoryIdentifier, actions: [carouselNext, carouselPrevious], intentIdentifiers: [], options: [])
                  UNUserNotificationCenter.current().setNotificationCategories([carouselCategory])
              }
          }
      }
      //END Authorize OS Notification Carousel Category

      return true
  }
  ```
</CodeGroup>

## 4. Send your push notification

When [Sending Push Messages](./push) you can set the iOS Category and custom Data.

### iOS category

Use `OSNotificationCarousel` as the iOS Category:

<Tabs>
  <Tab title="Dashboard">
    Set under "Platform Settings" > **Send to Apple iOS** > "Category"

    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="API">
    Set with the `ios_category` [API Parameter](/reference/push-notification).
  </Tab>
</Tabs>

### Custom data

OneSignal doesn't have an option to upload multiple images per notification.

Instead you must list the Image URLs separated by a comma `,`

<Tabs>
  <Tab title="Dashboard">
    Set under "Advanced Settings" > "Additional Data"

    For the "Key" set `images` and the "Value" set the list of comma separated URLs without quotes.

    <Frame>
      <img />
    </Frame>

    Example, copy paste:

    <CodeGroup>
      ```text text theme={null}
      https://cdn.pixabay.com/photo/2015/12/01/20/28/road-1072823_960_720.jpg,https://cdn.pixabay.com/photo/2013/11/28/10/36/road-220058_960_720.jpg,https://cdn.pixabay.com/photo/2012/08/27/14/19/mountains-55067_960_720.png,https://cdn.pixabay.com/photo/2015/01/28/23/35/landscape-615429_960_720.jpg,https://cdn.pixabay.com/photo/2016/05/05/02/37/sunset-1373171_960_720.jpg
      ```
    </CodeGroup>
  </Tab>

  <Tab title="API">
    Use the `data` [API Parameter](/reference/push-notification) like this:

    <CodeGroup>
      ```json json theme={null}
      data: {
        "images" : "https://cdn.pixabay.com/photo/2015/12/01/20/28/road-1072823_960_720.jpg,https://cdn.pixabay.com/photo/2013/11/28/10/36/road-220058_960_720.jpg,https://cdn.pixabay.com/photo/2012/08/27/14/19/mountains-55067_960_720.png,https://cdn.pixabay.com/photo/2015/01/28/23/35/landscape-615429_960_720.jpg,https://cdn.pixabay.com/photo/2016/05/05/02/37/sunset-1373171_960_720.jpg"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Send the push

Once you receive the push, you will need to long press or swipe left and click "View" to expand the notification depending on the iOS version.

### Troubleshooting

The code sample on the Github page has lines that are commented out which show debug positions and print statements to help identify any issues. Uncomment those lines and you should be able to see if the Notification Content Extension is being instantiated. If not, please check that you have not missed any steps in the setup process. If you continue to have issues, please reach out to [support@onesignal.com](mailto:support@onesignal.com)

### Further reading

* [Apple's Docs to Declare Your Actionable Notification Types](https://developer.apple.com/documentation/usernotifications/declaring_your_actionable_notification_types)
* [Helpful Medium Post by Ahmet Keskin](https://medium.com/nsistanbul/carousel-notification-in-ios-5a1e8239d786)

***


# iOS SDK setup
Source: https://documentation.onesignal.com/docs/en/ios-sdk-setup

Add push notifications and in-app messages to your iOS app using OneSignal's iOS SDK.

<SdkReleasesIframe />

This guide walks you through adding OneSignal to your iOS app using Xcode. You'll install our SDK, setup push and in-app messages, and send test messages to confirm everything is working.

If this is your first time using OneSignal, follow the steps in order. If you're experienced, feel free to jump to the sections you need.

<Info>
  **Using an AI coding assistant?**
  For AI-driven installation, use this prompt:

  ```
  Integrate the OneSignal iOS SDK into this codebase.

  Follow the instructions at:
  https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/ios/ai-prompt.md
  ```
</Info>

## Step 0. Configure APNs in OneSignal (required to deliver push)

You can install and initialize the OneSignal iOS SDK without completing this step. However, **push notifications will not deliver** until APNs credentials are configured in your OneSignal app.

<Note>
  If your company already has a OneSignal account, [ask to be invited as an admin role](./manage-team-members) to configure the app. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Steps to configure your OneSignal app.">
  These steps connect your OneSignal app to Apple Push Notification service (APNs). You only need to do this once per app.

  1. Login to [https://onesignal.com](https://onesignal.com) and create or select your App.
  2. Navigate to **Settings > Push & In-App**.
  3. Select **Apple iOS (APNs)** and **Continue** through the setup wizard.
  4. Input your [p8 Auth Key (Recommended)](./ios-p8-token-based-connection-to-apns) or [p12 Certificate](./ios-p12-generate-certificates) details.
  5. Continue through the setup wizard to get your App ID. This will be used to initialize the SDK.

  <Info>For full setup instructions, see our [Mobile push setup](./mobile-push-setup) guide.</Info>
</Accordion>

***

## Setup contract & requirements

This section summarizes the tools, versions, and assumptions used throughout the guide.

* **SDK version:** `5.4.0+` (latest: check [releases](https://github.com/OneSignal/OneSignal-XCFramework/releases))
* **AI setup instructions:** `https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/ios/ai-prompt.md`
* **SDK repo:** `https://github.com/OneSignal/OneSignal-XCFramework`
* **Xcode:** 16.0+
* **iOS:** 12.0+ minimum, 16.2+ recommended
* **Simulator:** iOS 16.2+ required for push testing
* **App target packages:** `OneSignalFramework` (required), `OneSignalInAppMessages` (recommended), `OneSignalLocation` (optional)
* **Notification Service Extension (NSE) target name:** `OneSignalNotificationServiceExtension`
* **Notification Service Extension (NSE) target package:** `OneSignalExtension`
* **App Group format:** `group.YOUR_MAIN_APP_BUNDLE_ID.onesignal`
* **App ID format:** 36-character UUID (example: `12345678-1234-1234-1234-123456789012`) — find at OneSignal Dashboard > Settings > Keys & IDs
* **Initialize:** `OneSignal.initialize("YOUR_APP_ID", withLaunchOptions: launchOptions)`
* **Requires NSE + App Group:** images, confirmed receipt, badges
* **confirmed receipt:** Requires an eligible plan (not available on free plans)
* **Recommended:** Assign External ID via `OneSignal.login("user_id")` to unify users across devices

***

## iOS setup steps

By the end of the steps below, you will have:

* The OneSignal SDK installed and initialized in your iOS app
* Push notification permissions prompting correctly on a real device
* A test push and in-app message successfully delivered

<Info>
  If you skipped **Step 0 (Configuring APNs in OneSignal)**, you can still complete the Xcode setup below. Complete Step 0 before you test or send push notifications.
</Info>

### Step 1. Enable Push Notifications and Background Modes

1. Open your `.xcodeproj` in Xcode (or `.xcworkspace` if using CocoaPods)
2. Select **app target** > **Signing & Capabilities**
3. Click **+ Capability** > add **Push Notifications**
4. Click **+ Capability** > add **Background Modes**
5. Enable **Remote notifications** checkbox

<Frame>
  <img alt="Xcode showing the app target with Push Notifications and Background Modes capabilities." />
</Frame>

### Step 2. Add a Notification Service Extension (NSE)

The NSE enables rich notifications (images) and confirmed receipt analytics.

**Create the target:**

1. **File > New > Target...**
2. Select **Notification Service Extension** > **Next**
3. Product name: `OneSignalNotificationServiceExtension`
4. Click **Finish** > click **Don't Activate** when prompted

<Frame>
  <img alt="Xcode showing how to createthe Notification Service Extension target." />
</Frame>

<Frame>
  <img alt="Xcode showing how to name the Notification Service Extension and use the following options if your app is written in Swift." />
</Frame>

<Frame>
  <img alt="Xcode showing how to not activate the NSE Scheme." />
</Frame>

**Configure the target:**

1. Select **OneSignalNotificationServiceExtension** target > **General**
2. Set **Minimum Deployments** to match your app target

<Frame>
  <img alt="Xcode showing how to set the OneSignalNotificationServiceExtension Minimum Deployments target to be the same as your main App target." />
</Frame>

<Frame>
  <img alt="Xcode showing how to set the App target Minimum Deployments target to be the same as your OneSignalNotificationServiceExtension target." />
</Frame>

**Update NSE code:**

1. Navigate to **OneSignalNotificationServiceExtension/NotificationService.swift**
2. Replace the contents with the code below:

<CodeGroup>
  ```swift Swift theme={null}
  // FILE: OneSignalNotificationServiceExtension/NotificationService.swift
  // PURPOSE: Enables rich notifications (images) and confirmed receipt analytics
  // REQUIREMENT: This extension must share an App Group with the main app target (configured in next steps)
  // WHEN IT RUNS: iOS calls this extension when a push has "mutable-content": true
  //               (automatically set when you include images or action buttons)

  import UserNotifications
  import OneSignalExtension

  class NotificationService: UNNotificationServiceExtension {
      
      // Callback to deliver the modified notification to iOS
      var contentHandler: ((UNNotificationContent) -> Void)?
      
      // The original push request from APNs
      var receivedRequest: UNNotificationRequest!
      
      // A mutable copy of the notification we can modify (add images, etc.)
      var bestAttemptContent: UNMutableNotificationContent?

      // Called when a push notification arrives with mutable-content: true
      // You have ~30 seconds to modify the notification before iOS displays it
      override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
          self.receivedRequest = request
          self.contentHandler = contentHandler
          self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

          if let bestAttemptContent = bestAttemptContent {
              // DEBUGGING: Uncomment to verify NSE is running
              // bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

              // OneSignal processes the notification:
              // - Downloads and attaches images
              // - Reports confirmed receipt to dashboard
              // - Handles action buttons
              OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
          }
      }

      // Called if didReceive() takes too long (~30 seconds)
      // Delivers whatever content we have so the notification isn't lost
      override func serviceExtensionTimeWillExpire() {
          if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
              OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
              contentHandler(bestAttemptContent)
          }
      }
  }
  ```

  ```objc Objective-C theme={null}
  // FILE: OneSignalNotificationServiceExtension/NotificationService.m
  // PURPOSE: Enables rich notifications (images) and confirmed receipt analytics
  // REQUIREMENT: This extension must share an App Group with the main app target (configured in next steps)
  // WHEN IT RUNS: iOS calls this extension when a push has "mutable-content": true
  //               (automatically set when you include images or action buttons)

  #import <OneSignalExtension/OneSignalExtension.h>
  #import "NotificationService.h"

  @interface NotificationService ()

  @property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver); // Callback to deliver modified notification
  @property (nonatomic, strong) UNNotificationRequest *receivedRequest;                          // Original push request from APNs
  @property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;                // Mutable copy we can modify

  @end

  @implementation NotificationService

  // Called when a push arrives with mutable-content: true
  // You have ~30 seconds to modify the notification before iOS displays it
  - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request
                     withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
      
      self.receivedRequest = request;
      self.contentHandler = contentHandler;
      self.bestAttemptContent = [request.content mutableCopy];

      // DEBUGGING: Uncomment to verify NSE is running
      // NSLog(@"Running NotificationServiceExtension");
      // self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];

      // OneSignal downloads images, reports confirmed receipt, handles action buttons
      [OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
                                  withMutableNotificationContent:self.bestAttemptContent
                                              withContentHandler:self.contentHandler];
  }

  // Called if didReceiveNotificationRequest() takes too long (~30 seconds)
  // Delivers whatever content we have so the notification isn't lost
  - (void)serviceExtensionTimeWillExpire {
      [OneSignalExtension serviceExtensionTimeWillExpireRequest:self.receivedRequest
                                     withMutableNotificationContent:self.bestAttemptContent];
      self.contentHandler(self.bestAttemptContent);
  }

  @end
  ```
</CodeGroup>

<Danger>
  Don't panic! Build errors will resolve after installing the SDK.
</Danger>

<Frame>
  <img alt="Xcode showing the updated NSE code with error that will resolve after installing the SDK." />
</Frame>

### Step 3. Create an App Group

App Groups enable data sharing between your app and the NSE. Required for [Confirmed receipt](./confirmed-delivery), badges, and images.

**Add the App Group to your main app target:**

1. Select your **main app target** > **Signing & Capabilities**
2. Click **+ Capability** > add **App Groups**
3. Click **+** and enter: `group.YOUR_MAIN_APP_BUNDLE_ID.onesignal` - Replace `YOUR_MAIN_APP_BUNDLE_ID` with your **main app target's** Bundle Identifier (found at **app target > General > Identity**).

**Add the same App Group to the NSE target:**

4. Select **OneSignalNotificationServiceExtension** target > **Signing & Capabilities**
5. Click **+ Capability** > add **App Groups**
6. Select the **same** App Group ID you created above: `group.YOUR_MAIN_APP_BUNDLE_ID.onesignal`

<Warning>
  Use your **main app target's** Bundle Identifier — not the NSE's.

  * **Correct:** `group.com.example.myapp.onesignal`
  * **Wrong:** `group.com.example.myapp.OneSignalNotificationServiceExtension.onesignal`

  Both targets must have the **exact same** App Group. If they don't match, confirmed receipt, badges, and images will not work. See [Troubleshooting confirmed receipt](./confirmed-delivery#ios) for a full verification checklist.
</Warning>

<Frame>
  <img alt="Xcode showing the main app target is part of the group.YOUR_MAIN_APP_BUNDLE_ID.onesignal App Group." />
</Frame>

<Frame>
  <img alt="Xcode showing the OneSignalNotificationServiceExtension target is part of the same group.YOUR_MAIN_APP_BUNDLE_ID.onesignal App Group." />
</Frame>

<Note>
  If you need OneSignal to use an existing App Group instead of creating a new one, add this key to the `Info.plist` of **BOTH** your main app target and NSE target. Replace `group.your-existing-group-id` with your existing App Group ID.

  ```xml theme={null}
  <key>OneSignal_app_groups_key</key>
  <string>group.your-existing-group-id</string>
  ```

  Without this key in both `Info.plist` files, the SDK defaults to looking for `group.YOUR_MAIN_APP_BUNDLE_ID.onesignal` and will not find your custom App Group.
</Note>

<Frame>
  <img alt="Xcode showing the OneSignal_app_groups_key in the Info.plist for BOTH the main app target and the OneSignalNotificationServiceExtension target." />
</Frame>

### Step 4. Install the OneSignal SDK

**Swift Package Manager (recommended):**

1. Select **Your project file > Package Dependencies > +**
2. Enter: `https://github.com/OneSignal/OneSignal-XCFramework`
3. Click **Add Package**
4. Assign packages:

| Package                  |                 Target                |   Required  |
| ------------------------ | :-----------------------------------: | :---------: |
| `OneSignalExtension`     | OneSignalNotificationServiceExtension |      ✅      |
| `OneSignalFramework`     |                  App                  |      ✅      |
| `OneSignalInAppMessages` |                  App                  | Recommended |
| `OneSignalLocation`      |                  App                  |   Optional  |

<Frame>
  <img alt="Xcode showing how to add the onesignal-xcframework package." />
</Frame>

<Frame>
  <img alt="Xcode showing the example shows adding the correct packages to the correct targets omitting Location. If you want location tracking, add it to the main app target." />
</Frame>

<Warning>
  **Most common install mistake (SPM): products added to the wrong target**

  Double-check product-to-target mapping:

  * **App target** must include: `OneSignalFramework` (and optionally `OneSignalInAppMessages`, `OneSignalLocation`)
  * **OneSignalNotificationServiceExtension target** must include: `OneSignalExtension`

  If you see `No such module 'OneSignalFramework'`, it usually means the **app target** is missing `OneSignalFramework`.
  If you see `No such module 'OneSignalExtension'`, it usually means the **NSE target** is missing `OneSignalExtension`.
</Warning>

<Info>
  **Where to verify in Xcode:** select the target → **Build Phases** → confirm the correct OneSignal products appear under “Link Binary With Libraries”.
</Info>

<Accordion title="CocoaPods alternative">
  Requires CocoaPods 1.16.2+. Add to `Podfile`:

  ```ruby Podfile theme={null}
  # If platform is uncommented, set to the same value as your minimum deployments target in Xcode
  # platform :ios, '15.0'

  target 'YourAppName' do
    pod 'OneSignal/OneSignal', '>= 5.2.9', '< 6.0'
    pod 'OneSignal/OneSignalInAppMessages', '>= 5.2.9', '< 6.0'
    pod 'OneSignal/OneSignalLocation', '>= 5.2.9', '< 6.0'  # Optional
  end

  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignal/OneSignal', '>= 5.2.9', '< 6.0'
  end
  ```

  Run `pod repo update && pod install`, then open `.xcworkspace` (not `.xcodeproj`).

  **Common error:** ArgumentError - \[Xcodeproj] Unable to find compatibility version string for object version `70`.

  CocoaPods relies on the `xcodeproj` Ruby gem to read your Xcode project files. As of now, the latest `xcodeproj` release does not recognize object version 70, which was introduced by Xcode 16. So when CocoaPods tries to open your `.xcodeproj` file, it crashes with this error.

  1. Close Xcode.
  2. Navigate to your project's `ios/<your-app>.xcodeproj/project.pbxproj` file.
  3. Change this line: `objectVersion = 70;`
  4. Replace it with: `objectVersion = 55;`
  5. Save, close, and rerun `cd ios && pod install && cd ..`
</Accordion>

<Check>
  Verify that the build succeeds without "No such module" errors.
</Check>

### Step 5. Initialize OneSignal

Add the following initialization code to your app's main file.

Replace `YOUR_APP_ID` with your actual OneSignal App ID from the Dashboard > Settings > [Keys & IDs](./keys-and-ids).

**SwiftUI:**

Open your main app file (typically `YourAppNameApp.swift`) and add:

```swift Swift theme={null}
// FILE: {AppName}App.swift
// PURPOSE: Initialize OneSignal when your app launches

import SwiftUI
import OneSignalFramework

@main
struct YourAppNameApp: App {
    // SwiftUI apps don't have an AppDelegate by default
    // This adapter lets us use UIApplicationDelegate methods like didFinishLaunchingWithOptions
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class AppDelegate: NSObject, UIApplicationDelegate {
    
    // Called once when the app finishes launching
    // This is the earliest point to initialize SDKs
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        
        // Enable verbose logging to debug issues (remove in production)
        OneSignal.Debug.setLogLevel(.LL_VERBOSE)
        
        // Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
        OneSignal.initialize("YOUR_APP_ID", withLaunchOptions: launchOptions)
        
        // Prompt user for push notification permission
        // In production, consider using an in-app message instead for better opt-in rates
        // fallbackToSettings: if previously denied, opens iOS Settings to re-enable
        OneSignal.Notifications.requestPermission({ accepted in
            print("User accepted notifications: \(accepted)")
        }, fallbackToSettings: false)
        
        return true
    }
}
```

<Accordion title="UIKit (Storyboard) alternative">
  <CodeGroup>
    ```swift Swift theme={null}
    // FILE: AppDelegate.swift
    // PURPOSE: Initialize OneSignal when your app launches

    import UIKit
    import OneSignalFramework

    @UIApplicationMain
    class AppDelegate: UIResponder, UIApplicationDelegate {

        // Called once when the app finishes launching
        // This is the earliest point to initialize SDKs
        func application(_ application: UIApplication,
                         didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

            // Enable verbose logging to debug issues (remove in production)
            OneSignal.Debug.setLogLevel(.LL_VERBOSE)
            
            // Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
            OneSignal.initialize("YOUR_APP_ID", withLaunchOptions: launchOptions)

            // Prompt user for push notification permission
            // In production, consider using an in-app message instead for better opt-in rates
            // fallbackToSettings: if previously denied, opens iOS Settings to re-enable
            OneSignal.Notifications.requestPermission({ accepted in
                print("User accepted notifications: \(accepted)")
            }, fallbackToSettings: false)

            return true
        }
    }
    ```

    ```objc Objective-C theme={null}
    // FILE: AppDelegate.m
    // PURPOSE: Initialize OneSignal when your app launches

    #import <OneSignalFramework/OneSignalFramework.h>

    @implementation AppDelegate

    // Called once when the app finishes launching
    // This is the earliest point to initialize SDKs
    - (BOOL)application:(UIApplication *)application
            didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

        // Enable verbose logging to debug issues (remove in production)
        [OneSignal.Debug setLogLevel:ONE_S_LL_VERBOSE];
        
        // Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
        [OneSignal initialize:@"YOUR_APP_ID" withLaunchOptions:launchOptions];
        
        // Prompt user for push notification permission
        // In production, consider using an in-app message instead for better opt-in rates
        // fallbackToSettings: if previously denied, opens iOS Settings to re-enable
        [OneSignal.Notifications requestPermission:^(BOOL accepted) {
            NSLog(@"User accepted notifications: %d", accepted);
        } fallbackToSettings:false];

        return YES;
    }

    @end
    ```
  </CodeGroup>
</Accordion>

<Check>
  Verify the app builds, runs, and shows the push permission prompt.
</Check>

### Step 6. Test the integration

**Verify Subscription creation:**

1. Launch app on device
2. Check Dashboard > **Audience > Subscriptions** — status shows "Never Subscribed"
3. Accept the permission prompt
4. Refresh dashboard — status changes to "Subscribed"

<Frame>
  <img alt="Example of the iOS and Android push permission prompts." />
</Frame>

<Frame>
  <img alt="Dashboard showing Subscription with 'Never Subscribed' status." />
</Frame>

<Frame>
  <img alt="After allowing push permissions, refresh the dashboard to see the Subscription status update to 'Subscribed'." />
</Frame>

<Check>
  You have successfully created a [mobile Subscription](./subscriptions).
  Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.
</Check>

#### Create test user and segment

1. Click **⋮** next to the Subscription > **Add to Test Users** > name it
2. Go to **Audience > Segments > New Segment**
3. Name: `Test Users`, add filter **Test Users** > **Create Segment**

<Frame>
  <img alt="Add a test user." />
</Frame>

<Frame>
  <img alt="Create a 'Test Users' segment with the Test Users filter." />
</Frame>

<Check>
  You have successfully created a segment of test users.

  We can now test sending messages to this individual device and groups of test users.
</Check>

#### Send test push via API

1. Navigate to **Settings > [Keys & IDs](./keys-and-ids)**.
2. In the provided code, replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

```bash theme={null}
curl -X POST 'https://api.onesignal.com/notifications' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Key YOUR_APP_API_KEY' \
  -d '{
    "app_id": "YOUR_APP_ID",
    "target_channel": "push",
    "name": "Testing basic setup",
    "headings": { "en": "👋" },
    "contents": {"en": "Hello world!"},
    "included_segments": ["Test Users"],
    "ios_attachments": {"onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"}
  }'
```

<Frame>
  <img alt="Images in push notifications appear small in the collapsed notification view. Expand the notification to see the full image." />
</Frame>

<Frame>
  <img alt="Delivery stats showing confirmed receipt (unavailable on free plans)." />
</Frame>

<Check>
  Verify the test device received a notification with:

  * An image.
  * Dashboard > **Delivery > Sent Messages** shows "Confirmed" status (unavailable on free plans).
</Check>

<Warning>
  * No image received? Your Notification Service Extension might be missing or incomplete setup.
  * No confirmed receipt? Review the troubleshooting guide [here](./confirmed-delivery#troubleshooting-confirmed-delivery).
  * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
</Warning>

#### Test in-app messages

1. Close app for 30+ seconds
2. Dashboard > **Messages > In-App > New In-App** > select **Welcome** template
3. Audience: **Test Users** segment
4. Trigger: **On app open**
5. Schedule: **Every time trigger conditions are satisfied**
6. Click **Make Message Live**
7. Open app

<Frame>
  <img alt="Targeting the 'Test Users' segment with an in-app message." />
</Frame>

<Frame>
  <img alt="Example customization of in-app Welcome message." />
</Frame>

<Frame>
  <img alt="In-app message scheduling options." />
</Frame>

<Frame>
  <img alt="Welcome in-app message shown on devices." />
</Frame>

<Check>
  Verify the test device received an in-app message. See the [In-app messages setup](./in-app-messages-setup) guide for more details.
</Check>

<Warning>
  Not seeing the message?

  * Start a new session
    * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
    * For more, see [how in-app messages are displayed](./in-app-messages-setup#how-are-iams-displayed%3F).
  * Still in the `Test Users` segment?
    * If you reinstalled or switched devices, re-add the device to [Test Users](./test-users) and confirm it's part of the Test Users segment.
  * Having issues?
    * Follow [Getting a Debug Log](./capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
</Warning>

<Check>
  You have successfully set up the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](./subscriptions), setting [Test Users](./test-users), and creating [Segments](./segmentation).
  * Sending [Push](./push) with images and [Confirmed receipt](./confirmed-delivery) using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](./in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

### Common Errors & Fixes

| Error / Symptom                       | Cause                                                             | Fix                                                                                                      |
| ------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `No such module 'OneSignalFramework'` | Package not added to app target                                   | Add `OneSignalFramework` via File > Add Package Dependencies. Clean and build the project.               |
| `No such module 'OneSignalExtension'` | Package not added to NSE                                          | Add `OneSignalExtension` to `OneSignalNotificationServiceExtension` target. Clean and build the project. |
| Push received but no image            | NSE not running                                                   | Verify NSE deployment target matches app; confirm code is updated                                        |
| No confirmed receipt stat             | App Group mismatch                                                | App Group ID must be identical in both targets                                                           |
| Badges not updating                   | App Group missing                                                 | Add App Groups capability to both targets                                                                |
| In-app not showing                    | Session not started or missing `OneSignalInAppMessages` framework | Check the framework is added, then close app 30+ seconds before reopening                                |
| Can't diagnose issue                  | Not enough log info                                               | Add `OneSignal.Debug.setLogLevel(.LL_VERBOSE)` before initialize, then reproduce the issue to get a log  |

***

## User management

Previously, we demonstrated how to create mobile [Subscriptions](./subscriptions). Now we'll expand to identifying [Users](./users) across all their Subscriptions (including push, email, and SMS) using the OneSignal SDK.

### Assign External ID (recommended)

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems. See our [Mobile SDK reference](./mobile-sdk-reference) for more details and Objective-C code examples.

```swift Swift theme={null}
// Call when user logs in or is identified, safe to call multiple times
// Typically used in a login completion handler, or on app launch if already authenticated
func onUserAuthenticated(userId: String) {
    OneSignal.login(userId)
}

// If you want to remove the External ID from the Subscription, setting it to an anonymous user
func onUserLoggedOut() {
    OneSignal.logout()
}
```

<Note>
  OneSignal generates unique read-only IDs for Subscriptions (Subscription ID) and Users (OneSignal ID).

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.

  Learn more about the [`login` method](./mobile-sdk-reference#login-external-id) in the SDK reference guide.
</Note>

### Add Tags & Custom Events

Tags and Custom Events are both ways to add data to your users. Tags are `key-value` strings and are generally associated with user properties (like `username`, `role`, or `status`) while Custom Events have a JSON format and are usually associated with actions (like `new_purchase`, `abandoned_cart`, and associated properties). Both can be used to power advanced [Message Personalization](./message-personalization) and Journeys. See our [Mobile SDK reference](./mobile-sdk-reference) for more details and Objective-C code examples.

```swift Swift theme={null}
// Add a tag when the user's name is set
OneSignal.User.addTag(key: "username", value: "john_doe")

// Create a custom event when user abandoned a cart
let myProperties = [
  "product_id": "123456",
  "product_name": "Product Name",
  "product_price": 100,
  "product_quantity": 1
]
OneSignal.User.trackEvent(name: "abandoned_cart", properties: myProperties as [String: Any])
```

<Note>
  More details on how to use Tags and Custom Events in the [Tags](./add-user-data-tags) and [Custom Events](./custom-events) guides.
</Note>

### Add email and/or SMS subscriptions

You can reach users through email and SMS channels in addition to push notifications. If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user — it will not create duplicates. See our [Mobile SDK reference](./mobile-sdk-reference) for more details and Objective-C code examples.

```swift Swift theme={null}
// Add email subscription
// Call when user provides their email (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addEmail("user@example.com")

// Add SMS subscription
// Use E.164 format: + country code + number
// Call when user provides their phone number (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addSms("+15551234567")
```

<Frame>
  <img alt="A user profile with push, email, and SMS subscriptions unified by External ID." />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods. See our [Mobile SDK reference](./mobile-sdk-reference) for more details and Objective-C code examples.

```swift Swift theme={null}
// In AppDelegate, BEFORE OneSignal.initialize()
// Use this if your app requires GDPR or other privacy consent before data collection
OneSignal.setConsentRequired(true)

// Later, after user grants consent (e.g., taps "I Agree" on your consent screen)
OneSignal.setConsentGiven(true)
```

<Note>
  See our Privacy & security docs for more on:

  * [Data collected by the SDK](./data-collected-by-the-onesignal-sdk)
  * [Handling personal data](./handling-personal-data)
</Note>

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](./prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes. Add these in your AppDelegate after `OneSignal.initialize()`.

### Push notification events

Example shows how to use the push click listener. Other push notification events like the foreground lifecycle listener to control how notifications behave in foreground are available in the [Mobile SDK Reference](./mobile-sdk-reference#push-notification-events).

```swift Swift theme={null}
// The OSNotificationClickListener is used to detect push click events
class AppDelegate: NSObject, UIApplicationDelegate, OSNotificationClickListener {

  // Add the required onClick method for OSNotificationClickListener
  func onClick(event: OSNotificationClickEvent) {
    print("Notification clicked: \(event.jsonRepresentation())")
    let notification = event.notification
    // Access notification data
    let title = notification.title ?? ""
    let additionalData = notification.additionalData // Custom key-value pairs you sent
    // Example: Deep link based on custom data
    if let screenName = additionalData?["screen"] as? String {
        // Navigate to the specified screen
    }
  }

  // Reference the listeners in your AppDelegate
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    // For the OSNotificationClickListener
    OneSignal.Notifications.addClickListener(self)

    return true
  }
}
```

### User state changes

Example shows how to use push subscription observer. Other user state events like the user state observer and notification permission observer are available in the [Mobile SDK Reference](./mobile-sdk-reference).

```swift Swift theme={null}
// The OSPushSubscriptionObserver is used to detect push subscription changes (token changes, opt-out, etc.)
class AppDelegate: NSObject, UIApplicationDelegate, OSNotificationPermissionObserver, OSPushSubscriptionObserver {

  // Add the onPushSubscriptionChanged method for OSPushSubscriptionObserver
  func onPushSubscriptionChanged(state: OSPushSubscriptionChangedState) {
    print("Push subscription changed: \(state.jsonRepresentation())")
    print(state.current.optedIn)
    print(state.current.token)
    // This is a good spot to update your UI or analytics
  }

  // Reference the observer in your AppDelegate
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    // For the OSPushSubscriptionObserver
    OneSignal.User.pushSubscription.addObserver(self)

    return true
  }
}

```

### In-app message events

Additional in-app message methods are available in the [Mobile SDK Reference](./mobile-sdk-reference).

```swift Swift theme={null}
// The OSInAppMessageClickListener is used to detect in-app message button clicks
class AppDelegate: NSObject, UIApplicationDelegate, OSInAppMessageClickListener {
  // Add the onClick method for OSInAppMessageClickListener
  func onClick(event: OSInAppMessageClickEvent) {
    let result: OSInAppMessageClickResult = event.result
    print("In-app message clicked: \(result.jsonRepresentation())")
    let actionId = result.actionId
    print("Action ID: \(actionId ?? "no actionId")")
    // Example: Deep link based on the actionId
    if let screenName = actionId {
        // Navigate to the specified screen
    }
  }

  // Reference the listeners in your AppDelegate
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    // For the OSInAppMessageClickListener
    OneSignal.InAppMessages.addClickListener(self)

    return true
  }
}
```

***

## Disable method swizzling (optional)

By default, the OneSignal SDK uses method swizzling to automatically handle push notification delegate methods. If your app needs to disable swizzling (for example, to avoid conflicts with other SDKs or to maintain full control over notification delegate methods), you can opt out via `Info.plist`.

When swizzling is disabled, you must manually forward notification delegate methods to the OneSignal SDK. All other SDK features (listeners, observers, in-app messages, outcomes, etc.) continue to work normally.

### Step 1. Add the Info.plist flag

Add the following to your app's `Info.plist`:

```xml theme={null}
<key>OneSignal_disable_swizzling</key>
<true/>
```

When the SDK detects this flag, it skips all method swizzling at startup and logs a warning reminding you to implement manual forwarding.

### Step 2. Set the UNUserNotificationCenter delegate

Set your `AppDelegate` as the `UNUserNotificationCenter` delegate **before** calling `OneSignal.initialize`. Without this, foreground notification display and notification tap handling will not work.

<CodeGroup>
  ```swift Swift theme={null}
  // In application(_:didFinishLaunchingWithOptions:), BEFORE OneSignal.initialize()
  UNUserNotificationCenter.current().delegate = self
  ```

  ```objc Objective-C theme={null}
  // In application:didFinishLaunchingWithOptions:, BEFORE [OneSignal initialize:]
  [UNUserNotificationCenter currentNotificationCenter].delegate = self;
  ```
</CodeGroup>

### Step 3. Forward notification delegate methods

Implement the following methods in your `AppDelegate`. All methods call through `OneSignal.Notifications`.

**Token registration:**

<CodeGroup>
  ```swift Swift theme={null}
  func application(_ application: UIApplication,
                   didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
      OneSignal.Notifications.didRegisterForRemoteNotifications(deviceToken: deviceToken)
  }

  func application(_ application: UIApplication,
                   didFailToRegisterForRemoteNotificationsWithError error: Error) {
      OneSignal.Notifications.didFailToRegisterForRemoteNotifications(error: error as NSError)
  }
  ```

  ```objc Objective-C theme={null}
  - (void)application:(UIApplication *)application
      didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
      [OneSignal.Notifications didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
  }

  - (void)application:(UIApplication *)application
      didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
      [OneSignal.Notifications didFailToRegisterForRemoteNotificationsWithError:error];
  }
  ```
</CodeGroup>

**Background / silent notifications:**

<CodeGroup>
  ```swift Swift theme={null}
  func application(_ application: UIApplication,
                   didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                   fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
      OneSignal.Notifications.didReceiveRemoteNotification(userInfo: userInfo,
                                                          completionHandler: completionHandler)
  }
  ```

  ```objc Objective-C theme={null}
  - (void)application:(UIApplication *)application
      didReceiveRemoteNotification:(NSDictionary *)userInfo
      fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
      [OneSignal.Notifications didReceiveRemoteNotification:userInfo
                                          completionHandler:completionHandler];
  }
  ```
</CodeGroup>

**Foreground notification display:**

The SDK calls your completion block with an `OSNotification` object. If non-nil, the SDK wants the notification displayed — pass your preferred presentation options. If nil (e.g., an IAM preview), pass no presentation options.

<CodeGroup>
  ```swift Swift theme={null}
  func userNotificationCenter(_ center: UNUserNotificationCenter,
                              willPresent notification: UNNotification,
                              withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
      OneSignal.Notifications.willPresentNotification(
          payload: notification.request.content.userInfo
      ) { notif in
          if notif != nil {
              if #available(iOS 14.0, *) {
                  completionHandler([.banner, .list, .sound])
              } else {
                  completionHandler([.alert, .sound])
              }
          } else {
              completionHandler([])
          }
      }
  }
  ```

  ```objc Objective-C theme={null}
  - (void)userNotificationCenter:(UNUserNotificationCenter *)center
         willPresentNotification:(UNNotification *)notification
           withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
      [OneSignal.Notifications
          willPresentNotificationWithPayload:notification.request.content.userInfo
          completion:^(OSNotification *notif) {
              if (notif) {
                  if (@available(iOS 14.0, *)) {
                      completionHandler(UNNotificationPresentationOptionBanner |
                                        UNNotificationPresentationOptionList |
                                        UNNotificationPresentationOptionSound);
                  } else {
                      completionHandler(UNNotificationPresentationOptionAlert |
                                        UNNotificationPresentationOptionSound);
                  }
              } else {
                  completionHandler(UNNotificationPresentationOptionNone);
              }
          }];
  }
  ```
</CodeGroup>

<Note>
  The `onWillDisplayNotification` lifecycle listener and `preventDefault` / `display` APIs continue to work with manual forwarding. The SDK invokes your listeners from within `willPresentNotification`.
</Note>

**Notification tap / action:**

<CodeGroup>
  ```swift Swift theme={null}
  func userNotificationCenter(_ center: UNUserNotificationCenter,
                              didReceive response: UNNotificationResponse,
                              withCompletionHandler completionHandler: @escaping () -> Void) {
      OneSignal.Notifications.didReceiveNotificationResponse(response)
      completionHandler()
  }
  ```

  ```objc Objective-C theme={null}
  - (void)userNotificationCenter:(UNUserNotificationCenter *)center
      didReceiveNotificationResponse:(UNNotificationResponse *)response
               withCompletionHandler:(void (^)(void))completionHandler {
      [OneSignal.Notifications didReceiveNotificationResponse:response];
      completionHandler();
  }
  ```
</CodeGroup>

### Optional: Set badge count

When swizzling is disabled, the SDK cannot intercept badge changes. Use this method to set the badge count and keep OneSignal's internal badge cache in sync:

<CodeGroup>
  ```swift Swift theme={null}
  OneSignal.Notifications.setBadgeCount(5)
  ```

  ```objc Objective-C theme={null}
  [OneSignal.Notifications setBadgeCount:5];
  ```
</CodeGroup>

### SwiftUI apps

SwiftUI apps don't have an `AppDelegate` by default. Use `@UIApplicationDelegateAdaptor` to add one, then implement all the forwarding methods shown above:

```swift Swift theme={null}
@main
struct YourApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class AppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        UNUserNotificationCenter.current().delegate = self
        OneSignal.initialize("YOUR_APP_ID", withLaunchOptions: launchOptions)
        return true
    }

    // Implement all the forwarding methods shown above
}
```

### API reference

| Swift                                                       | Objective-C                                         | Purpose                                 |
| ----------------------------------------------------------- | --------------------------------------------------- | --------------------------------------- |
| `didRegisterForRemoteNotifications(deviceToken:)`           | `didRegisterForRemoteNotificationsWithDeviceToken:` | Forward APNs device token               |
| `didFailToRegisterForRemoteNotifications(error:)`           | `didFailToRegisterForRemoteNotificationsWithError:` | Forward APNs registration failure       |
| `didReceiveRemoteNotification(userInfo:completionHandler:)` | `didReceiveRemoteNotification:completionHandler:`   | Forward background/silent notifications |
| `willPresentNotification(payload:completion:)`              | `willPresentNotificationWithPayload:completion:`    | Forward foreground notification         |
| `didReceiveNotificationResponse(_:)`                        | `didReceiveNotificationResponse:`                   | Forward notification tap/action         |
| `setBadgeCount(_:)`                                         | `setBadgeCount:`                                    | Set badge count and sync cache          |

***

## Advanced setup & capabilities

* [Deep Linking](./deep-linking) — Navigate users to specific screens from notifications
* [Action Buttons](./action-buttons) — Add interactive buttons to notifications
* [Live Activities](./live-activities) — iOS Live Activities support
* [Service Extensions](./service-extensions) — Advanced notification customization
* [Identity Verification](./identity-verification) — Secure user identification
* [Location Tracking](./mobile-sdk-reference#location) — Location-based targeting
* [Integrations](./integrations) — Connect with analytics and data platforms
* [Multi-language Messaging](./multi-language-messaging) — Localized notifications

For full SDK method documentation, visit the [Mobile SDK Reference](./mobile-sdk-reference).

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# Live Activities developer setup
Source: https://documentation.onesignal.com/docs/en/live-activities-developer-setup

Set up iOS Live Activities with OneSignal to display real-time updates on the lock screen and Dynamic Island.

Live Activities let your iOS app show real-time updates directly on the lock screen and Dynamic Island. Ideal for delivery tracking, sports scores, or time-sensitive transactional updates, they keep users informed without opening the app.

<Note>
  Android has a similar feature called [Android Live Notifications](./android-live-notifications).
</Note>

## Requirements

* Follow the [iOS SDK setup](./ios-sdk-setup) if using native iOS (Swift/Objective-C).
  * If using a wrapper SDK (React Native, Flutter, Unity, etc.) follow [Mobile SDK setup](./mobile-sdk-setup) and then [Cross-platform Live Activity SDK Setup](./cross-platform-live-activity-setup).
* OneSignal iOS SDK version 5.2.0+ for **push-to-start** support ([see release notes](https://github.com/OneSignal/OneSignal-iOS-SDK/releases/tag/5.2.0)).
* OneSignal iOS SDK version 5.2.15+ for **click tracking** and **confirmed receipt**.
* iOS 16.1+ and iPadOS 17+.
* A [.p8 APNs key](./ios-p8-token-based-connection-to-apns). Apple does not support p12 certificates with Live Activities.
* Xcode 14 or higher.

***

## Setup

These steps walk you through setting up Live Activities quickly. For more details and design customizations, see [Apple's Live Activities Developer docs](https://developer.apple.com/design/human-interface-guidelines/live-activities).

### 1. Add a Widget Extension

In Xcode, go to **File > New > Target... > Widget Extension**.

<Frame>
  <img alt="Xcode new target dialog with Widget Extension selected" />
</Frame>

Select and press **Next**.

Configure the Widget Extension by providing a name (example: `OneSignalWidget`) and ensure **Include Live Activity** is selected. Then click **Finish**.

<Frame>
  <img alt="Widget Extension configuration with Include Live Activity checkbox selected" />
</Frame>

Click **Don't Activate** if prompted to activate the scheme.

<Frame>
  <img alt="Xcode scheme activation dialog for the Widget Extension" />
</Frame>

### 2. Update `Info.plist`

In your main target's `Info.plist`, add the key `Supports Live Activities` as **Boolean**, and set it to `YES`.

<Frame>
  <img alt="Xcode Info.plist editor showing Supports Live Activities set to YES" />
</Frame>

If you set it programmatically, it should look like this:

```xml Info.plist theme={null}
<key>NSSupportsLiveActivities</key>
<true/>
```

<Note>
  When updating Live Activities, you can set a `priority` that Apple uses to determine urgency. Apple throttles requests that use high priority (`10`) too frequently.

  If your use case requires more frequent high-priority updates, add the key `NSSupportsLiveActivitiesFrequentUpdates` to your `Info.plist` as a Boolean set to `YES`. See [Apple's Developer Docs](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency) for details. When the push budget is exceeded, iOS prompts the user to allow additional updates.
</Note>

### 3. Add SDK

<Tabs>
  <Tab title="Package Manager">
    <Note>
      If you are using a wrapper SDK (e.g. **Flutter**) with SPM enabled, you can skip this step. The OneSignal package is already resolved and available to all targets.
    </Note>

    In your Widget Extension target, add the `OneSignalFramework` under **General > Frameworks, Libraries and Embedded Content**:

    <Frame>
      <img alt="Xcode Frameworks and Libraries section with OneSignalFramework added" />
    </Frame>
  </Tab>

  <Tab title="Cocoapods">
    Find the name of your widget extension target in your project's Targets list. Example's name is `OneSignalWidgetExtension`.

    <Frame>
      <img alt="Xcode Targets list showing the widget extension target name" />
    </Frame>

    Open your `Podfile` and add the following code. Replace `OneSignalWidgetExtension` with the name of your widget extension target.

    <CodeGroup>
      ```ruby Podfile theme={null}
      target 'OneSignalWidgetExtension' do
        use_frameworks!
        pod 'OneSignal/OneSignal', '>= 5.0.0', '< 6.0'
      end
      ```

      ```ruby Full Podfile example theme={null}
      # Uncomment the next line to define a global platform for your project
      # platform :ios, '9.0'

      target 'Demo Momenta' do
        # Comment the next line if you don't want to use dynamic frameworks
        use_frameworks!
        pod 'OneSignal/OneSignal', '>= 5.0.0', '< 6.0'
        pod 'OneSignal/OneSignalInAppMessages', '>= 5.0.0', '< 6.0'
      end

      target 'OneSignalNotificationServiceExtension' do
        use_frameworks!
        pod 'OneSignal/OneSignal', '>= 5.0.0', '< 6.0'
      end

      target 'OneSignalWidgetExtension' do
        use_frameworks!
        pod 'OneSignal/OneSignal', '>= 5.0.0', '< 6.0'
      end
      ```
    </CodeGroup>

    Close Xcode and run `pod repo update && pod install` to install the `OneSignalLiveActivities` pod.

    If you continue to see the error "No such module 'OneSignalLiveActivities'" after doing this, you can add the dependency manually by going to your **"Widget Extension Target" > General > Frameworks and Libraries > + icon**. Select the `OneSignalLiveActivities` framework:

    <Frame>
      <img alt="Xcode Frameworks and Libraries dialog with OneSignalLiveActivities selected" />
    </Frame>
  </Tab>
</Tabs>

### 4. Define widget attributes and UI

Open the `your-nameLiveActivity.swift` file (example: `OneSignalWidgetLiveActivity.swift`) to define the properties of the struct and to make changes to the widget UI.

* `your-nameAttributes` describes the static content of your Live Activity.
* `ContentState` describes the dynamic content of your Live Activity.

If you are following the example, copy-paste the code below into your `OneSignalWidgetLiveActivity.swift` file.

```swift your-nameLiveActivity.swift theme={null}
import ActivityKit
import WidgetKit
import SwiftUI
// Import the OneSignalLiveActivities module
// If you get an error about the module not being found, return to step 3 and ensure you have added the OneSignalLiveActivities pod correctly.
import OneSignalLiveActivities

// Update to inherit from OneSignalLiveActivityAttributes
// This will be used in your API requests to start a Live Activity
struct OneSignalWidgetAttributes: OneSignalLiveActivityAttributes  {
    // Update to inherit from OneSignalLiveActivityContentState
    public struct ContentState: OneSignalLiveActivityContentState {
        // Dynamic stateful properties about your activity go here!
        var emoji: String
        // Add a reference to OneSignalLiveActivityContentStateData?
        var onesignal: OneSignalLiveActivityContentStateData?
    }
    // Fixed non-changing properties about your activity go here!
    var name: String
    // Add a reference to OneSignalLiveActivityAttributeData
    var onesignal: OneSignalLiveActivityAttributeData
}

struct OneSignalWidgetLiveActivity: Widget {
    var body: some WidgetConfiguration {
      // Update to use `for: the-name-of-your-attributes-struct`
      // This will be used in your API requests to start a Live Activity
        ActivityConfiguration(for: OneSignalWidgetAttributes.self) { context in
            // Lock screen/banner UI goes here
            // Update to show the attributes sent via the payload
            VStack {
                Text("Hello \(context.attributes.name) \(context.state.emoji)")
            }
            .activityBackgroundTint(Color.cyan)
            .activitySystemActionForegroundColor(Color.black)

        } dynamicIsland: { context in
            DynamicIsland {
                // Expanded UI goes here.  Compose the expanded UI through
                // various regions, like leading/trailing/center/bottom
                DynamicIslandExpandedRegion(.leading) {
                    Text("Leading")
                }
                DynamicIslandExpandedRegion(.trailing) {
                    Text("Trailing")
                }
                DynamicIslandExpandedRegion(.bottom) {
                    Text("Bottom \(context.state.emoji)")
                    // more content
                }
            } compactLeading: {
                Text("L")
            } compactTrailing: {
                Text("T \(context.state.emoji)")
            } minimal: {
                Text(context.state.emoji)
            }
            .widgetURL(URL(string: "http://www.apple.com"))
            .keylineTint(Color.red)
        }
    }
}
```

### 5. Allow main target membership

<Note>
  This step is only required when using custom attributes (e.g., `OneSignalWidgetAttributes`). If you are using `DefaultLiveActivityAttributes`, skip this step — the type is provided by the OneSignal SDK and is already accessible from your main app target.
</Note>

Add your main app target to the **Target Membership** list in the `your-nameLiveActivity.swift` file. This is necessary so the main app target can reference your custom attributes struct in the setup call (Step 6).

In Xcode, open the Inspector panel on the right side of the screen. Within **Target Membership**, click the **+** button and select your main app target containing the `ContentView` and your OneSignal initialization code.

<Frame>
  <img alt="Xcode Inspector panel showing Target Membership with the main app target checked" />
</Frame>

### 6. Add the setup method to your AppDelegate

Call `OneSignal.LiveActivities.setup` in your `AppDelegate`, after OneSignal SDK initialization.

Replace `OneSignalWidgetAttributes` with the name of your Live Activity attributes struct.

```swift AppDelegate theme={null}
// Import the OneSignalLiveActivities module
import OneSignalLiveActivities

// This should be added after initializing the OneSignal SDK
if #available(iOS 16.1, *) {
	OneSignal.LiveActivities.setup(OneSignalWidgetAttributes.self)
  // If you have multiple Live Activities, you can add them here with the setup method
  // OneSignal.LiveActivities.setup(LiveActivityWidgetAttributes-2.self)
}
```

This manages and reports updates using ActivityKit async sequences.

<Warning>
  If you also consume any of the following sequences directly in your app, it may interfere with OneSignal Live Activity behavior:

  * activityStateUpdates
  * pushTokenUpdates
  * pushToStartTokenUpdates
  * activityUpdates
</Warning>

***

## Starting a Live Activity

There are 2 options to start a Live Activity on a device:

<Tabs>
  <Tab title="Push-to-start">
    Send a [Push To Start API request](/reference/start-live-activity). Be sure all names and IDs match your widget's configuration exactly (parameters are case-sensitive). If anything is missing or incorrectly added, you may encounter issues when trying to launch the widget.

    Here is an example request that will work for the example above.

    Replace:

    * `YOUR_APP_ID` with your OneSignal App ID.
    * `YOUR_APP_API_KEY` with your OneSignal API key.
    * `OneSignalWidgetAttributes` with the name of your Widget Attributes struct.

      ```bash theme={null}
      curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/activities/activity/OneSignalWidgetAttributes' \
      --header 'Authorization: key YOUR_APP_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
          "event": "start",
          "activity_id": "push-to-start",
          "included_segments": [
              "Subscribed Users"
          ],
          "event_attributes": {
              "name": "World"
          },
          "event_updates": {
              "emoji":"🤩"
          },
          "name": "Live Activities Test",
          "contents": {
              "en": "A push started this Live Activity"
          },
          "headings": {
            "en": "Live Activity Started"
          }
        }'
      ```

    If you are following the example code provided, you should see the Live Activity on your device's lock screen.

    <Frame>
      <img alt="iPhone lock screen displaying a Live Activity started via push-to-start" />
    </Frame>

    <Check>
      You successfully started a Live Activity with push-to-start!

      Users will need to select "Allow" to continue getting updates.
    </Check>
  </Tab>

  <Tab title="Trigger-in-app">
    You can have a user trigger a Live Activity while interacting with your app.

    For example, when a user has an active event going on (they placed an order, a game is in progress, an event is about to start, etc.) and opens your app, you can display a Live Activity automatically.

    This example uses a button to start the Live Activity manually.

    ```swift theme={null}
    import SwiftUI
    import ActivityKit
    import OneSignalFramework
    import OneSignalLiveActivities

    struct ContentView: View {
      @StateObject private var viewModel = LiveActivityViewModel()

      var body: some View {
        VStack {
          Button("Start Live Activity") {
            viewModel.startLiveActivity()
          }
        }
      }
    }

    class LiveActivityViewModel: ObservableObject {

      func startLiveActivity() {
        let osAttributes = OneSignalLiveActivityAttributeData.create(activityId: "click-to-start")
        let attributes = OneSignalWidgetAttributes(name: "OneSignal", onesignal: osAttributes)
        let contentState = OneSignalWidgetAttributes.ContentState(emoji:"🤩", onesignal: nil)
        do {
            let activity = try Activity<OneSignalWidgetAttributes>.request(
                attributes: attributes,
                contentState: contentState,
                pushType: .token)
        } catch {
            print(error.localizedDescription)
        }
      }
    }
    ```

    Upon clicking the button it will launch the Live Activity.
  </Tab>
</Tabs>

***

## Tracking Live Activity clicks

Track when users tap on your Live Activities and Dynamic Islands by implementing OneSignal's click tracking. This enables you to measure engagement and optionally deep link users to specific content in your app.

### Step 1: Add Click Tracking to Your Widget

Add the `.onesignalWidgetURL()` modifier to any UI component in your Live Activity widget that you want to track clicks on:

```swift theme={null}
import OneSignalLiveActivities

struct ExampleAppFirstWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: ExampleAppFirstWidgetAttributes.self) { context in
            VStack {
                Spacer()
                Text("Sample Text " + context.attributes.title).font(.headline)
                // Other UI code
            }
            .onesignalWidgetURL(URL(string: "myapp://settings"), context: context)
            // Pass nil if you don't need deep linking: .onesignalWidgetURL(nil, context: context)
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.leading) {
                    Text("Leading")
                }
                // Other Dynamic Island regions
            } compactLeading: {
                Text("L")
            } compactTrailing: {
                Text("T")
            } minimal: {
                Text("Min")
            }
            .onesignalWidgetURL(URL(string: "myapp://settings"), context: context)
            // Optional: Track Dynamic Island clicks separately
        }
    }
}
```

**Important Considerations:**

* You can pass a URL for deep linking or `nil` if you only want click tracking without navigation
* The view hierarchy **cannot include** Apple's `.widgetURL()` modifier if you're using `.onesignalWidgetURL()`
* Apply the modifier to both the main Live Activity view and Dynamic Island if you want to track clicks on both

### Step 2: Handle URLs in Your App

Add URL handling in your app to track clicks and route users appropriately:

```swift theme={null}
import OneSignalLiveActivities

// AppDelegate example:
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)
    
    // Handle the original URL and navigate user
    if let url = originalURL {
        // Your custom URL routing logic
        return handleDeepLink(url)
    }
    return false
}

// SceneDelegate example:
func scene(_ scene: UIScene, openURLContexts URLContexts: Set) {
    guard let url = URLContexts.first?.url else { return }
    
    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)
    
    if let url = originalURL {
        // Your custom URL routing logic
        handleDeepLink(url)
    }
}

// SwiftUI example:
.onOpenURL { url in
    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)
    
    if let url = originalURL {
        // Your custom URL routing logic
        handleDeepLink(url)
    }
}
```

The `trackClickAndReturnOriginal()` method automatically tracks the click with OneSignal and returns the original URL you specified in the widget for your app to handle.

***

## Updating a Live Activity

Use the [Update Live Activity API](/reference/update-live-activity-api) to update active widgets.

Match the `activity_id` used when starting the activity.

This example request updates the push-to-start widget because it has the `activity_id` of `push-to-start` defined when starting the activity.
To update the click-to-start widget, update the request path to use `click-to-start` instead of `push-to-start`.

```bash theme={null}
curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/live_activities/push-to-start/notifications' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: key YOUR_API_KEY' \
--data '{
    "event": "update",
    "event_updates": {
        "emoji": "😎"
    },
    "contents": {
        "en": "A push updated this Live Activity"
    },
    "name": "Live Activity Updated"
}'
```

<Frame>
  <img alt="iPhone lock screen showing an updated Live Activity with new content" />
</Frame>

<Check>
  You successfully updated a Live Activity!

  Check out the [Update Live Activity API](/reference/update-live-activity-api) for more information on updating a Live Activity.
</Check>

***

## Ending a Live Activity

Using the same [Update Live Activity API](/reference/update-live-activity-api), you can end a Live Activity by setting `"event": "end"`.

```bash theme={null}
curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/live_activities/my_activity_id/notifications' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: key YOUR_API_KEY' \
--data '{
    "event": "end",
    "event_updates": {
        "emoji": "👋"
    },
    "contents": {
        "en": "A push ended this Live Activity"
    },
    "name": "Live Activity Ended"
}'
```

Other ways a Live Activity can end:

* Use our SDK [`exit()` method](./mobile-sdk-reference#exit).
* User manually swipes the Live Activity away.
* User revokes permission for Live Activities in their iOS Settings.

<Frame>
  <img alt="iPhone lock screen showing an ended Live Activity" />
</Frame>

<Check>
  You successfully ended the Live Activity and completed the example!
</Check>

***

## Best practices & recommendations

### Design considerations

* Follow Apple's [Live Activities Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/live-activities).
  * Prioritize important information to make it easy to understand at a quick glance.
  * Don't add elements to your app that draw attention to the Dynamic Island.
  * Use margins and maintain space between elements.
  * Use a bold color for the background. Design for both Light and Dark mode.

### Functionality

* Apple requires each [Live Activity presentation](https://developer.apple.com/documentation/activitykit/displaying-live-data-with-live-activities#Review-Live-Activity-presentations) to be supported.
  * [Compact](https://developer.apple.com/design/human-interface-guidelines/live-activities#Compact-presentation)
  * [Minimal](https://developer.apple.com/design/human-interface-guidelines/live-activities#Minimal-presentation)
  * [Expanded](https://developer.apple.com/design/human-interface-guidelines/live-activities#Expanded-presentation)
  * [Lock Screen](https://developer.apple.com/design/human-interface-guidelines/live-activities#The-Lock-Screen)
* Test your [deep links](https://developer.apple.com/design/human-interface-guidelines/live-activities#Offering-interactivity).
* Review Apple's guide on [Displaying Live Data with Live Activities](https://developer.apple.com/documentation/activitykit/displaying-live-data-with-live-activities).
* Avoid displaying sensitive information in a Live Activity.

### Setting a fallback message

If a user cannot receive an update after a Live Activity has started, opening the app should refresh the activity. Set the [stale date](/reference/start-live-activity#body-stale-date) to a point in the future after you expect to have sent the first update. Users who have not received the update are shown the fallback message instead.

You can listen for the "stale" state in your widget UI to show a fallback message:

<Frame>
  <img alt="Live Activity widget displaying a fallback message prompting the user to tap to refresh" />
</Frame>

```swift theme={null}
struct ptsLiveActivity: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: ptsAttributes.self) { context in
            //This will flip to true after the stale date
            let isStale = context.isStale 
            if !isStale{
                VStack {
                    Text("\(context.attributes.name) \(context.state.emoji)")
                        .activityBackgroundTint(Color.cyan)
                        .activitySystemActionForegroundColor(Color.black)
                }
            }  else {
            //If the message is stale, we request the user clicks the widget to open the app
                VStack {
                    Text("Something went wrong, please click to refresh")
                }
            }
            // ... Rest of the widget UI
        }
    }
}
```

### Live Activity permission observer

When a user first sees a Live Activity, iOS prompts them to allow or disallow updates. If they select "Don't Allow", they do not receive further updates. Use an observer to listen for changes in the user's Live Activity permission status.

<Frame>
  <img alt="iOS prompt asking the user to allow or disallow Live Activity updates" />
</Frame>

```swift theme={null}
import OneSignalLiveActivities

@available(iOS 16.1, *)
private func observeLiveActivityPermissionChanges() {
    let authInfo = ActivityAuthorizationInfo()
    Task.detached(priority: .background) {
        for await enabled in authInfo.activityEnablementUpdates {
            if enabled {
                print("User Clicked Allow")
            } else {
                print("User Clicked Don't Allow")
            }
        }
    }
}
```

***

## FAQ

### What is the budget for high-priority updates?

Apple does not provide a fixed limit for high-priority (`priority: 10`) updates, but they do enforce a dynamic system-level budget. Sending too many high-priority updates in a short period may result in throttling, where updates are delayed or dropped.

To reduce the risk of throttling:

* Use a mix of priority levels: Apple recommends using both `priority: 5` (standard) and `priority: 10` (high) for balance.
* Reserve `priority: 10` for time-sensitive or critical updates only (e.g., order status changes, game scores).

If your use case requires frequent updates:

* Add the key `NSSupportsLiveActivitiesFrequentUpdates` to your app's `Info.plist` file, set as a Boolean `YES`.
* When this budget is exceeded, iOS may prompt the user to allow additional updates. If the user agrees, Apple will automatically expand the allowed update limit to maintain a seamless experience.

For more details, refer to [Apple's Developer Docs](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency).

### Can I read Live Activity updates from the main app?

Yes. You can observe updates for debugging or UI sync:

```swift theme={null}
Task {
    for await content in activity.contentUpdates {
        print("LA activity id: \(activity.id), content update: \(content.state)")
    }
}
// Example output:
// LA activity id: EFE6D54D-F7E1-45EF-9514-4C2598F8DED2, content update: ContentState(message: "My message from payload")
```

Track lifecycle changes:

```swift theme={null}
Task {
    for await state in activity.activityStateUpdates {
        print("LA state update: \(state)")
        //If you wanted to do something based on the state, you would use this:
      	if state != ActivityState.active {
            //Do something here
        }
    }
}

// Example output 1 - LA ended, but still visible
// LA state update: active

/* State can be equal to 4 possible values on the ActivityState enum
active, dismissed, ended, and stale
*/
```

### The API returned a 400 with an error message stating I'm over the subscriber limit. What do I do?

If your push subscriber count exceeds your plan's limit, upgrade your account to the next plan or contact `support@onesignal.com`. See the [Pricing page](https://onesignal.com/pricing) for plan details.

### How do I avoid sending both push and Live Activities?

Your application may already send a series of Push Notifications, where your designed Live Activity replaces the need for these Push Notifications. For example, if you send score updates via Push, you could replace this through a Live Activity.

When a user opts in for a Live Activity, add a [data tag](./add-user-data-tags) to their profile. You can then exclude users with that tag from push messages that contain the same or similar content using [Segments](./segmentation).

***

## Troubleshooting

### No recipients

For users to be found when starting or updating a Live Activity, the activity type, widget, and API request must all have matching values.

1. Check the path parameters in your request to ensure that you are sending a correctly formatted request to the server. The App ID must match your App ID used in the `OneSignal.Initialize` method and the activity type must match that of the type you've defined in your Live Activity file.

2. In the body of the [Push To Start API request](/reference/start-live-activity), you should have the following parameters:

* `event`: `"start"`
* `event_updates`: The dynamic data you have defined in your struct under activity type and that is used in your widget. Ensure the letter casing and variables all match between the request, the type, and the widget.
* `event_attributes`: Static data follows the same logic as Event Updates and must include all variables in use, and must match across all parts of the live activity and the request
* `activity_id`: This will assign an ID to the widget and is what will be used to update the activity after it has been launched on the user's device.
* `name`: The Live Activity Name.
* `contents`: The message content required for sending push.
* `headings`: The message heading required for sending push.
* A targeting parameter like `included_segments`. [Available options](/reference/create-message).

### Activity sent, but not received

1. Ensure that the request is formatted correctly. If any fields that are used in the Widget are omitted, the activity may not launch or update as expected.

2. In your API request, determine the `priority` level you are setting. If you are setting this to `10` (highest priority), try lowering it to `5` and test again. Apple will throttle requests being sent out too frequently per their own internal rate limits.

If your use case relies on more frequent updates, add the key `NSSupportsLiveActivitiesFrequentUpdates` to your `Info.plist` as a Boolean set to `YES`. See [Apple's Developer Docs](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency) for details. When the push budget is exceeded, iOS prompts the user to allow additional updates.

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Request location permissions with in-app messages
Source: https://documentation.onesignal.com/docs/en/location-opt-in-prompt

Guide users to enable location tracking in your mobile app using a soft pre-prompt in OneSignal before triggering the native Android or iOS location permission request.

Easily request location access from users by using a OneSignal in-app message as a soft pre-prompt before showing the required native system-level location permission dialog. This improves opt-in rates and gives you more control over when and how to ask. Alternatively, you can directly trigger the system prompt using our [Mobile SDK location methods](./mobile-sdk-reference#location).

***

## Requirements

Before creating your in-app message:

* Add location tracking permissions to your app (for both Android and iOS).
  * Refer to our [Mobile SDK location reference](./mobile-sdk-reference#location) for platform-specific setup instructions.
* Enable location sharing with OneSignal in your app code.

***

## Create your message

<Steps>
  <Step title="Create your message">
    In the OneSignal dashboard, go to: **Messages > In-App > New In-App**
  </Step>

  <Step title="Audience">
    * If all users should see the prompt, select **Show to all users**.
    * Otherwise, target a specific Segment.
  </Step>

  <Step title="Message design">
    * Clearly explain why location access benefits the user. E.g., "Enable location to receive relevant local updates."
    * Be concise but specific to increase opt-in likelihood.

    <Frame>
      <img />
    </Frame>
  </Step>
</Steps>

***

## Add the Location Permission Prompt Click Action

<Steps>
  <Step title="Add a button or image">
    Add a button or image with a clear call to action (e.g., “Enable Location”).
  </Step>

  <Step title="Add a click action">
    In the options:

    * Click **Add Click Action**
    * Select **Location Permission Prompt**

    When clicked, OneSignal will trigger the native, required system-level location prompt.

    **If location is already enabled, the message won’t show to avoid unnecessary prompts.**

    <Info>
      Both Android and iOS limit how frequently system-level prompts can appear. Using this soft pre-prompt helps avoid those limitations and allows for repeat attempts if needed.
    </Info>

    <Frame>
      <img />
    </Frame>
  </Step>
</Steps>

***

## Trigger the in-app message

You can control when and how the prompt is shown.

### Option 1: Time-based triggers

Show the message after a user has been in the app for a set amount of time (e.g., after 30 seconds).

<Frame>
  <img />
</Frame>

### Option 2: Programmatic triggers

Control exactly when the prompt appears via the SDK:

<Steps>
  <Step title="Add the trigger code to the app.">
    Use our SDK's [`addTrigger` method](./mobile-sdk-reference#in-app-messages) to set a key like `location_prompt` and value like `true`. Then call this whenever you want inside your app.
  </Step>

  <Step title="Add the trigger to the message">
    Set the same trigger key (`location_prompt`) and value (`true`) in your in-app message settings.

    <Frame>
      <img />
    </Frame>
  </Step>
</Steps>

***

## Set the message frequency

To avoid spamming users:

* Choose **Multiple times**
* Set a number of times to show the message
* Set a gap between each attempt

Example setting: show up to 5 times, with a 4-week gap between each attempt

This allows monthly reminders for up to 5 months, striking a balance between persistence and user experience.

<Frame>
  <img />
</Frame>

***

## Best Practices

* Always explain the benefit of location access to users.
* Use segmentation or triggers to avoid asking at a bad time.
* Pre-prompts increase opt-in rates and avoid operating system limits.
* Ensure location permissions are correctly configured in your app before triggering the in-app message.

***

<Check>
  You will start to see location points being tracked in your Users and Subscriptions pages.

  Create [Location-triggered messages](./location-triggered-event).
</Check>

***


# Location-based messages
Source: https://documentation.onesignal.com/docs/en/location-triggered-event

Segment users by country, GPS coordinates, or geofence and send location-triggered push notifications with OneSignal.

Send messages to users based on where they are. OneSignal can segment users by country, GPS coordinates, or custom tags so you can create timely, relevant outreach based on physical location.

As users interact with your app and location tracking is enabled, their coordinates update periodically (approximately every 5 minutes while the app is in use) and can be used to send messages via [Journeys](./journeys-overview) or any message creation tool.

<Warning>
  **OneSignal does not track GPS location by default.** The SDK only collects latitude and longitude when all three of these conditions are met:

  1. Your app has the correct location permissions and dependencies.
  2. Your app explicitly enables sharing with OneSignal. Without this, your app may collect location data but will not share it with OneSignal.
  3. The user grants location permission at the system prompt.

  See [Location tracking setup](#location-tracking-setup) for configuration. For background on the SDK's location behavior, see [You're in Control: How Location Actually Works in OneSignal's SDK](https://onesignal.com/blog/youre-in-control-how-location-actually-works-in-onesignals-sdk/).
</Warning>

***

## Target by country

Country is determined by the device's IP address and updates automatically each time the user opens your app. The value uses the ISO 3166-1 Alpha-2 two-letter country code (for example, `US`, `GB`, `CA`).

Target by country using the `country` field in [Segments](./segmentation) or in the `filters` parameter of the [Create segment API](/reference/create-segments):

```json theme={null}
"filters": [
  { "field": "country", "relation": "=", "value": "US" }
]
```

***

## Target by location (latitude, longitude, and radius)

If your mobile app collects GPS location and shares it with OneSignal, the SDK updates the user's coordinates approximately every 5 minutes (based on permission and system rules). If the app is force-stopped, location cannot be tracked until the user opens it again.

### Location tracking setup

Location tracking is configured in your mobile app's code, not in the OneSignal Dashboard. At a minimum, your app must:

* Add native location permissions and dependencies for iOS and Android.
* Enable the `Location.isShared` flag to share coordinates with OneSignal.
* Request the system location permission, or use an [in-app message as a soft pre-prompt](./location-opt-in-prompt) for better opt-in rates.

<Card title="Mobile SDK location reference" icon="location-dot" href="./mobile-sdk-reference#location">
  Full setup and per-platform code for iOS, Android, React Native, Flutter, Unity, and Cordova/Ionic.
</Card>

<Check>
  Once location tracking is enabled, you can create segments or send messages via our API using the `location` filter.
</Check>

<Frame>
  <img alt="OneSignal segment builder showing the location radius filter with latitude, longitude, and radius fields" />
</Frame>

***

## Web push latitude and longitude tracking

OneSignal **does not collect** latitude/longitude for web. However, you can use tags to set the location from your web app or use the [Update User API](/reference/update-user) to set the location from your server.

**Tagging example:**

1. Request location access in your web app using the browser's [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API).
2. Use JavaScript to detect the user's coordinates.
3. Send those coordinates to OneSignal using [tags](./add-user-data-tags).

```javascript theme={null}
OneSignal.User.addTags({
  lat: "37.160",
  long: "-117.773"
});
```

Once the tags are set, create a geofenced segment by combining tag range filters. For example, to target users inside the bounding box `37° ≤ lat < 38°` and `-118° ≤ long < -117°`, add these four filters in the segment builder:

* Tag `lat` greater than `37`
* Tag `lat` less than `38`
* Tag `long` greater than `-118`
* Tag `long` less than `-117`

***

## Target by city or custom location

OneSignal does not natively detect city or area codes. To target by city or custom location:

* Let users input a city or region in a form.
* Or use JavaScript with reverse geocoding (e.g., Google Maps API) to infer city from coordinates.
* Send the city name as a [data tag](./add-user-data-tags).

```javascript theme={null}
OneSignal.User.addTag("city", "San Francisco");
```

***

## FAQ

### Does location tracking work on web?

Not natively. OneSignal's Web SDK does not collect GPS coordinates. To use location-based segments for web push, collect coordinates yourself from the browser's [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API) and send them to OneSignal as [tags](./add-user-data-tags), then build range-filter segments on those tags. See [Web push latitude and longitude tracking](#web-push-latitude-and-longitude-tracking).

### Why is my app not tracking location?

Verify all three setup conditions are met: your app has the correct location permissions and dependencies installed, `Location.isShared` is set to `true`, and the user has granted location permission at the system prompt. See the [Mobile SDK location reference](./mobile-sdk-reference#location) for platform-specific setup and common fixes, including the Android `play-services-location` dependency.

### How often does the SDK update location?

When location tracking is enabled, the SDK updates coordinates approximately every 5 minutes while the app is in use. If the app is force-stopped, location updates pause until the user opens the app again.

### Can I target users by city?

Not natively. OneSignal tracks country (via IP address) and GPS coordinates (via the SDK), but not city or area code. You can infer city from coordinates using a reverse geocoding service and store it as a tag. See [Target by city or custom location](#target-by-city-or-custom-location).

***

## Related pages

<Columns>
  <Card title="Location opt-in prompt" icon="message" href="./location-opt-in-prompt">
    Use an in-app message as a soft pre-prompt before requesting native location permission.
  </Card>

  <Card title="Segments" icon="users" href="./segmentation">
    Create audience segments using location filters, tags, and user properties.
  </Card>
</Columns>


# Loyalty Journey
Source: https://documentation.onesignal.com/docs/en/loyalty-journey

Build automated loyalty messaging that keeps customers informed about their points balance, notifies them when rewards unlock and drives repeat purchases with measurable ROI.

A Loyalty Journey is an automated email flow that keeps customers informed about their points balance and engaged with your rewards program. It connects your existing loyalty system to OneSignal so personalized, data-driven messages go out automatically without manual campaign sends each week.

This tutorial covers two implementation cases:

* **Case 1 – Basic:** Sync three loyalty tags to OneSignal via API and send weekly point reminder emails and reward-unlock notifications. No purchase event tracking required.
* **Case 2 – Advanced:** Same tag sync as Case 1. Adds post-purchase points confirmation emails, a multi-step lapsed customer winback series and a webhook to confirm redemptions with your loyalty backend.

Start with Case 1 to prove ROI quickly. Upgrade to Case 2 when you're ready to connect messaging directly to purchase behavior.

***

## Overview

Your loyalty system is the source of truth for points and rewards. OneSignal stores a copy of each customer's loyalty state as data tags and uses those tags to personalize and trigger messages automatically.

1. Your loyalty system updates OneSignal tags via the [Update user API endpoint](/reference/update-user) whenever a customer earns points, redeems a reward or crosses a threshold
2. OneSignal segments update in real time as tag values change
3. Journeys are triggered by segment entry or custom event, using Liquid to pull each customer's points data into the message
4. You track email opens, clicks and downstream purchases to measure ROI

***

## Prerequisites

**For both cases:**

* OneSignal app with [email](./email-messaging) configured
* An external loyalty system that stores points balances, reward thresholds and redemption status
* API access to sync loyalty data to OneSignal as tags (see [Update user API endpoint](/reference/update-user))
* A customer list with email addresses matched to OneSignal profiles via [External ID](./users#external-id)
* Familiarity with [Journeys overview](./journeys-overview) concepts

**For Case 1, you also need:**

* Tags `points_balance`, `points_to_next_reward` and `rewards_available` synced to each customer's profile

**For Case 2, you also need:**

* Tags `last_purchase_date` and `lifetime_spend` synced to each customer's profile
* [Custom events](./custom-events) firing from your loyalty system when a purchase completes
* [Journey webhooks](./journeys-webhook) enabled on your account (contact OneSignal sales for access)

***

## Loyalty data setup

Your loyalty system syncs each customer's state to OneSignal as data tags. The journey reads these tags to decide what to send and what to say.

### Tags to sync

| Tag                     | Type   | Description                                         | When to update                                  |
| ----------------------- | ------ | --------------------------------------------------- | ----------------------------------------------- |
| `points_balance`        | Number | Customer's current point total                      | After every point-earning or redemption event   |
| `points_to_next_reward` | Number | Points needed to unlock the next reward             | After every point-earning event                 |
| `rewards_available`     | Number | Number of rewards the customer can currently redeem | After points are earned or rewards are redeemed |
| `last_purchase_date`    | Date   | Unix timestamp of the most recent purchase          | After each purchase                             |
| `lifetime_spend`        | Number | Total spend in cents                                | After each purchase                             |

Tags are synced from your loyalty backend via the [Update user API endpoint](/reference/update-user) because points and rewards are calculated server-side after each transaction. Match customers to OneSignal profiles using [External ID](./users#external-id) so tags land on the correct profile regardless of device or channel. If your app receives updated loyalty data directly, you can also set tags via the [mobile SDK `addTags` method](./mobile-sdk-reference#addtag-addtags).

<Tip>
  Your loyalty system is the source of truth. OneSignal stores a copy of each customer's loyalty state used only for targeting and personalization. Never calculate points or rewards inside OneSignal.
</Tip>

***

## Case 1: Basic loyalty journey

Send weekly point reminders and reward-unlock notifications using three synced tags. No purchase event tracking required.

### Overview

Two journeys run in parallel for each enrolled customer:

1. **Weekly points reminder:** Re-enters every 7 days and sends a personalized email with the customer's current balance and progress toward their next reward.
2. **Reward ready notification:** Triggers when a customer newly qualifies for a reward and sends an email prompting redemption before it goes unused.

### Journey 1: Weekly points reminder

#### Journey settings

Configure these settings on the **Settings** tab before building the steps. See [Journey settings](./journeys-settings) for full reference.

| Setting                                | Value                                                                                                                                             |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entry rules: Audience segment**      | `points_balance` exists AND has email subscription                                                                                                |
| **Entry rules: Future additions only** | Unchecked. All enrolled loyalty members enter when the journey launches.                                                                          |
| **Re-entry rules**                     | Enabled. Allow re-entry after **7 days**. Each customer exits after the email send, re-enters 7 days later and receives the next week's reminder. |
| **Exit rules**                         | None.                                                                                                                                             |

#### Required segments

| Segment name              | Filters                                            |
| ------------------------- | -------------------------------------------------- |
| Loyalty email subscribers | `points_balance` exists AND has email subscription |

#### Journey steps

<Steps>
  <Step title="Time Window">
    **Tuesday through Thursday, 10 AM to 2 PM** in the user's timezone. This limits delivery to mid-week, mid-morning windows when retail loyalty emails tend to see higher open and click rates.
  </Step>

  <Step title="Email: Weekly points summary">
    Use [Liquid syntax](./using-liquid-syntax) to pull each customer's loyalty data into the email. Include the current balance, points needed for the next reward and a clear call to action to visit or purchase.

    Subject: *"You have \{\{ points\_balance }} points. Your next reward is \{\{ points\_to\_next\_reward }} points away."*

    Body highlights:

    * Current balance: **\{\{ points\_balance }} points**
    * Points to next reward: **\{\{ points\_to\_next\_reward }} to go**
    * Progress bar visual (built in your email template)
    * CTA: "Order now to earn more points"
  </Step>
</Steps>

The journey ends here. Re-entry (enabled in Journey settings) brings the customer back through this same flow 7 days later.

### Journey 2: Reward ready notification

This journey fires once each time a customer newly qualifies for a reward so they know to redeem it before it goes unused.

#### Journey settings

| Setting                                | Value                                                                                                                                                                                                                                        |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entry rules: Audience segment**      | `rewards_available` > 0                                                                                                                                                                                                                      |
| **Entry rules: Future additions only** | Checked. Only customers who newly enter this segment receive the notification. Customers who already qualify at launch are excluded permanently. Even if they leave the segment and re-enter later, they will not receive this notification. |
| **Re-entry rules**                     | Enabled. Allow re-entry after **30 days**. This lets the journey fire again the next time a customer earns a new reward after redeeming a previous one.                                                                                      |
| **Exit rules**                         | None.                                                                                                                                                                                                                                        |

#### Required segments

| Segment name          | Filters                 |
| --------------------- | ----------------------- |
| Has redeemable reward | `rewards_available` > 0 |

#### Journey steps

<Steps>
  <Step title="Time Window">
    **Any day, 10 AM to 6 PM** in the user's timezone.
  </Step>

  <Step title="Email: Reward unlocked">
    Subject: *"You've earned a reward. Ready to redeem?"*

    Body highlights:

    * Rewards available: **\{\{ rewards\_available }}**
    * What the reward covers (pulled from a tag or hardcoded based on your program's structure)
    * CTA: "Redeem now"
    * Secondary message: current balance and points to the next reward threshold
  </Step>

  <Step title="Wait: 3 days">
    Give your loyalty system time to calculate and sync updated tag values to OneSignal before the email sends.
  </Step>

  <Step title="Yes/No Branch">
    Condition: user is in **Has redeemable reward** segment.

    * **Yes (reward still unused):** Continue to the reminder email below.
    * **No (redeemed):** Exit the journey. No reminder needed.
  </Step>

  <Step title="Time Window">
    **Any day, 10 AM to 6 PM** in the user's timezone.
  </Step>

  <Step title="Email: Reward reminder">
    Subject: *"Your reward is still waiting. \{\{ rewards\_available }} available."*

    Body highlights:

    * Reminder of the unredeemed reward
    * CTA: "Redeem before it expires"
  </Step>
</Steps>

### Success metrics to track

* Weekly email open rate and click-to-open rate
* Reward redemption rate within 7 days of the unlock notification
* Purchase frequency lift for customers in the journey vs. a holdout group
* Revenue per email sent

### Best practices for Case 1

* **Let Liquid do the personalization.** A subject line that shows the customer's point balance outperforms a generic "Check your rewards" subject. Every customer sees their own number, which makes the email feel relevant rather than bulk.
* **Keep the weekly email focused.** One primary message: here is your balance and here is how close you are to a reward. Avoid adding promotions or unrelated offers. The loyalty summary email performs better when it stays on topic.
* **Sync tags frequently.** The weekly email is only as accurate as the tag data behind it. Sync `points_balance` and `points_to_next_reward` after every point-earning event so the email reflects the customer's real state at send time.

***

## Case 2: Advanced loyalty journey

Same two journeys as Case 1, plus a post-purchase points confirmation email and a lapsed customer winback series.

### Overview

Case 2 adds two journeys to the two in Case 1:

3. **Post-purchase follow-up:** Triggered by a `purchase_complete` event. Sends a points credit confirmation shortly after the transaction and shows the customer how close they are to their next reward.
4. **Lapsed customer winback:** Triggered when `last_purchase_date` indicates inactivity. Sends a two-step email series with escalating incentives to bring the customer back.

Case 2 also adds a Webhook step to Journey 2 so your loyalty backend is notified each time a reward-unlock notification is sent.

### Required data

#### Additional tags for Case 2

Tags `last_purchase_date` and `lifetime_spend` are required in addition to the Case 1 tags. See [Loyalty data setup](#loyalty-data-setup) for sync instructions.

#### Events to track

| Event               | Description                   | How to trigger                                                                        |
| ------------------- | ----------------------------- | ------------------------------------------------------------------------------------- |
| `purchase_complete` | Customer completes a purchase | Fire from your loyalty system backend with `amount` and `points_earned` as properties |

#### Required segments

In addition to Case 1 segments, create:

| Segment name       | Filters                             |
| ------------------ | ----------------------------------- |
| Lapsed 30 days     | `last_purchase_date` > 29 days ago  |
| Lapsed 60 days     | `last_purchase_date` > 59 days ago  |
| Purchased recently | `last_purchase_date` \< 30 days ago |

### Journey 2 update: Add a Webhook step

In Case 2, add a Webhook step to Journey 2 immediately after the "Email: Reward unlocked" step. This notifies your loyalty backend each time a reward-unlock notification sends so it can track delivery and flag unredeemed rewards.

<Steps>
  <Step title="Webhook">
    Send the customer's `external_id` and `rewards_available` count to your loyalty backend. Place this step directly after the "Email: Reward unlocked" step. The updated step sequence for Journey 2 becomes: Time Window → Email: Reward unlocked → Webhook → Wait 3 days → Yes/No Branch → ...
  </Step>
</Steps>

### Journey 3: Post-purchase points confirmation

#### Journey settings

| Setting            | Value                                                                                                                           |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Entry trigger**  | Custom event: `purchase_complete`                                                                                               |
| **Re-entry rules** | Automatic. Custom event journeys always allow re-entry. Each `purchase_complete` event triggers a new run through this journey. |
| **Exit rules**     | None.                                                                                                                           |

#### Journey steps

<Steps>
  <Step title="Wait: 15 minutes">
    Give your loyalty system time to calculate and sync updated tag values to OneSignal before the email sends.
  </Step>

  <Step title="Email: Points credited">
    Subject: *"Your points are in. \{\{ points\_balance }} total."*

    Body highlights:

    * Points earned on this purchase
    * Updated balance: **\{\{ points\_balance }} points**
    * Points to next reward: **\{\{ points\_to\_next\_reward }} to go**
    * Progress bar visual
    * CTA: "View your rewards"
  </Step>
</Steps>

### Journey 4: Lapsed customer winback

#### Journey settings

| Setting                                | Value                                                                                                                                               |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entry rules: Audience segment**      | `Lapsed 30 days`                                                                                                                                    |
| **Entry rules: Future additions only** | Checked. Only customers who newly cross 30 days inactive enter.                                                                                     |
| **Re-entry rules**                     | Not enabled. A customer receives one winback series per lapse period.                                                                               |
| **Exit rules**                         | Exit when user enters **Purchased recently** segment. This removes them from the series if they make a purchase before the 60-day escalation sends. |

#### Journey steps

<Steps>
  <Step title="Time Window">
    **Tuesday through Thursday, 10 AM to 2 PM** in the user's timezone.
  </Step>

  <Step title="Email: We miss you">
    Subject: *"You have \{\{ points\_balance }} points waiting. Come back and use them."*

    Body highlights:

    * Points balance and how close the customer is to a reward
    * A reminder of what their rewards can get them
    * CTA: "Order now"
  </Step>

  <Step title="Wait: 14 days">
    Give your loyalty system time to calculate and sync updated tag values to OneSignal before the email sends.
  </Step>

  <Step title="Yes/No Branch">
    Condition: user is in **Lapsed 60 days** segment.

    * **No:** Exit the journey. The customer hasn't reached 60 days inactive and doesn't need the escalation email. Any customer who made a purchase during the journey would have already exited via the exit rule.
    * **Yes (still lapsed):** Continue to the escalation email below.
  </Step>

  <Step title="Time Window">
    **Tuesday through Thursday, 10 AM to 2 PM** in the user's timezone.
  </Step>

  <Step title="Email: Escalation with incentive">
    Subject: *"Still \{\{ points\_balance }} points waiting. Here's a reason to come back."*

    Body highlights:

    * Points balance (still theirs, not expiring)
    * A limited time bonus offer or discount to incentivize the first purchase back
    * Clear expiry on the offer to create urgency
    * CTA: "Claim your offer"
  </Step>
</Steps>

### Success metrics to track

In addition to Case 1 metrics:

* Post-purchase email open rate and influence on next-visit return rate
* Winback email conversion rate at 30-day and 60-day lapse
* Revenue recovered from lapsed customers per 1,000 emails sent
* Redemption webhook delivery rate (confirms your backend is receiving events)

### Best practices for Case 2

* **Send the post-purchase email fast.** A points credit confirmation sent within minutes of a transaction reinforces the earning behavior and shows the customer their loyalty is being tracked. The 15-minute Wait accounts for tag sync time while keeping the email timely.
* **Make the winback offer specific.** A generic "we miss you" email without an offer underperforms one with a concrete, time-limited incentive. Tie the offer value to the customer's points balance or spend history so high-value lapsed customers get a stronger reason to return.
* **Exit customers who return mid-series.** The exit rule on the winback journey removes customers who make a purchase before the 60-day escalation. Avoid sending a discount to someone who already returned without one.

***

## Case 1 vs. Case 2 at a glance

|                     | Case 1: Basic                                                      | Case 2: Advanced                                                                                      |
| ------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| **Tags required**   | 3 (`points_balance`, `points_to_next_reward`, `rewards_available`) | 5 (adds `last_purchase_date`, `lifetime_spend`)                                                       |
| **Events required** | None                                                               | `purchase_complete`                                                                                   |
| **Journeys**        | 2 (weekly reminder, reward unlock)                                 | 4 (adds post-purchase confirmation, lapsed winback)                                                   |
| **Primary channel** | Email                                                              | Email                                                                                                 |
| **Personalization** | Points balance, reward proximity                                   | All Case 1 fields, plus points earned per transaction                                                 |
| **Winback**         | None                                                               | Two-step email series at 30 and 60 days inactive                                                      |
| **Backend sync**    | One way. Loyalty system writes tags to OneSignal.                  | Adds webhook step in Journey 2 to notify your loyalty backend when a reward-unlock notification sends |
| **Best for**        | Teams proving loyalty email ROI for the first time                 | Teams ready to connect messaging directly to purchase behavior                                        |

***

## Getting started

Start with Case 1. Set up the three core tags, build the two journeys and let them run for four weeks before evaluating. The weekly reminder and reward-unlock notification together give you enough data to measure whether loyalty messaging is driving incremental purchases.

Once you have baseline data, add Case 2 journeys one at a time. The post-purchase points confirmation is the highest-ROI addition since it arrives immediately after a transaction and reinforces the earning behavior at exactly the right moment.

***

## Industry-specific versions

This tutorial covers a general loyalty program structure. For a version tailored to mobile gaming, including in-app tier celebrations, session-based entry and push as the primary channel, see the mobile gaming edition.

<Card title="Loyalty Journey: Mobile Gaming" icon="gamepad" href="./loyalty-journey-mobile-gaming">
  Reward continued play, move players through loyalty tiers and turn retained players into advocates.
</Card>

***

## Track performance

<Card title="Goals" icon="bullseye" href="./goals">
  Set a target metric on your journey and track progress in real time on the Journey report.
</Card>


# macOS app setup
Source: https://documentation.onesignal.com/docs/en/macos-app-setup

Learn how to integrate OneSignal into your macOS app, whether using Mac Catalyst or direct API access. Step-by-step guidance for configuring platforms and sending push notifications.

## Configure your OneSignal app and platform

To send push notifications on macOS, your OneSignal app must be configured with Apple (APNs).

<Note>
  If your team already has a OneSignal account, [ask to be invited as an admin role](./manage-team-members) so you can configure the app. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

### 1. Create or select your app

* Select your app and go to **Settings > Push & In-App**.
* Or create a new app by clicking **New App/Website**.

<Frame>
  <img />
</Frame>

### 2. Set up and activate macOS platform

* Choose a recognizable app and organization name.
* Select (More Options) macOS as the platform to activate.
* Click **Next: Configure Your Platform**.

<Frame>
  <img />
</Frame>

### 3. Configure credentials

Follow the prompts to add either:

* [p8 Auth Key (Recommended)](./ios-p8-token-based-connection-to-apns)
* Or [p12 Certificate](./ios-p12-generate-certificates)

<Frame>
  <img />
</Frame>

Click **Save & Continue** after entering your credentials.

### 4. Save your App ID

You’ll be shown your OneSignal App ID — make sure to save it, as you’ll need it during setup.

<Frame>
  <img />
</Frame>

***

## Setup

If your macOS app was built with Mac Catalyst, you can integrate our iOS SDK directly. Otherwise, you can leverage our APIs to manage users and notifications.

<Tabs>
  <Tab title="Mac Catalyst">
    If you built your app with Mac Catalyst, you can integrate our [iOS SDK](./ios-sdk-setup) directly.
  </Tab>

  <Tab title="API-only integration">
    If you're not using Mac Catalyst, or need full control, you can integrate via the OneSignal REST API.

    <Steps>
      <Step title="Obtain a macOS push token">
        Follow [Apple's documentation](https://developer.apple.com/notifications/) to implement native push support and retrieve the APNs token from your macOS app.
      </Step>

      <Step title="Register a macOS Subscription with OneSignal">
        Call our [Create user API](/reference/create-user) to set the `subscription` object:

        * `type` of `macOSPush`
        * `token` of the APNs token
        * Include all other user data, especially `external_id` to track the user in OneSignal.
      </Step>

      <Step title="Updating users">
        Use the [Create user](/reference/create-user) or [Update user](/reference/update-user) APIs with the `external_id` to update user and subscription data.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

<Check>
  macOS setup complete!
  Recommended next steps:

  * Understand [Users](./users) and [Subscriptions](./subscriptions)
  * [Create message API](/reference/create-message) to send notifications
</Check>

***


# Mobile-first strategies
Source: https://documentation.onesignal.com/docs/en/mobile-first

Implementation hub for mobile-first messaging: External IDs, Tags, Custom Events, segments, and lifecycle Journeys for subscription, freemium, and trial-driven apps.

Follow this guide if most of your app's user experience lives on a phone. The use cases here move your highest-leverage metrics: activation, trial-to-paid conversion, and Day 7/14/30 retention.

<Note>
  This guide picks up after you've installed the OneSignal [Mobile SDK](./mobile-sdk-setup) and confirmed users are flowing into your OneSignal dashboard [Users](./users) tab. If you haven't, complete SDK setup first.
</Note>

## Implementation roadmap

To get the most out of your implementation, work through these steps in order.

<Steps>
  <Step title="Unify user identity across devices with External IDs">
    The External ID binds push, email, SMS, and in-app behavior to one user across devices and reinstalls. It also merges anonymous pre-signup activity with the authenticated profile, so retention analytics count returning users correctly and trial-to-paid attribution stays accurate.

    Set the External ID at signup, every login, and session resume. Common identifiers include your auth or billing ID (Auth0 `uid`, `user_id`, or Stripe `customer_id`).

    <Card title="Users & External IDs" icon="id-card" href="./users">
      Assign a unique identifier to each user so data follows them across devices and reinstalls.
    </Card>
  </Step>

  <Step title="Maximize push opt-in">
    For users to receive full-visibility push notifications (banner, sound, lock-screen alert), they must accept a system-level permission prompt. iOS supports [provisional authorization](./ios-provisional-push-notifications), which delivers notifications quietly to the Notification Center without a prompt.

    A poorly timed prompt can cost you a subscriber permanently. iOS only shows the prompt once per install, and a denied user must re-enable notifications in system settings. Delay the prompt until after the first Aha moment, and precede it with an in-app message that explains what they'll receive and why.

    <Card title="Prompt for push permissions" icon="bell" href="./prompt-for-push-permissions">
      Configure when and how the OS push permission prompt appears using in-app messages.
    </Card>
  </Step>

  <Step title="Add user properties as Tags">
    Tags capture longer-lived user properties so you can target each user precisely. Set `account_type` for lifecycle stage, `trial_end_date` for time-based Journeys, and `core_feature_used` for activation tracking. Update them whenever user state changes. See [recommended Tags](#tags) below.

    <Card title="Tags" icon="tags" href="./add-user-data-tags">
      Add key-value pairs to user profiles for segmentation and personalization.
    </Card>
  </Step>

  <Step title="Send user actions as Custom Events">
    Custom Events let you deliver messages at key moments in the customer lifecycle. Use `trial_started` to time trial-conversion Journeys, `payment_failed` to trigger dunning communication, and `core_feature_used` to mark activation. See [recommended Custom Events](#custom-events) below.

    <Card title="Custom Events" icon="bolt" href="./custom-events">
      Capture user actions to trigger Journeys and Wait Until steps.
    </Card>
  </Step>

  <Step title="Build segments">
    Segments are how you send the right message to the right group. Combine Tags and Custom Events into lifecycle audiences like Active Trial, Trial Expiring, and Core feature untouched. See [recommended segments](#segments) below.

    <Card title="Segments" icon="users" href="./segmentation">
      Group users by shared characteristics to target Journeys and campaigns.
    </Card>
  </Step>

  <Step title="Capture emails and phone numbers for new users">
    For high-priority moments like trial expiration, payment failures, and win-back, push alone reaches only opted-in users on the lock screen. Add the user's email address and phone number as Subscriptions on the user profile so your Journeys can also send email, SMS, RCS, and MMS. You can add them via:

    * The SDK `addEmail` and `addSms` [methods](./mobile-sdk-reference)
    * The REST API [Create Subscription](/reference/create-subscription) endpoint
    * The dashboard [CSV Importer](./import)

    <Card title="Subscriptions" icon="address-book" href="./subscriptions">
      Manage push, email, and SMS Subscriptions on a user profile.
    </Card>
  </Step>

  <Step title="Automate lifecycle Journeys and other use cases">
    Journeys turn data into outcomes: trial-to-paid conversions, retained subscribers, recovered failed payments. Each Journey reacts to user behavior in real time so you're not hand-sending campaigns. Build Welcome, conversion, retention, and win-back Journeys against your segments. Some use cases (like prompting for push permissions) don't require a Journey at all. See [Lifecycle Journeys](#lifecycle-journeys) below.

    <Card title="Journeys" icon="route" href="./mobile-first-journeys">
      Build automated, multi-step messaging flows triggered by user behavior.
    </Card>
  </Step>
</Steps>

## Recommended data

Tags and Custom Events are case-sensitive. Keep names consistent across your app and backend.

### Tags

Tags are how you target the right user with the right message: segments filter on them, Journeys exit on them, and Liquid personalizes from them. Set Tags whenever user state changes. For boolean-style signals, set the Tag to `1` when true and **remove it** when false; segment with "tag exists" rather than storing `0`/`false` values.

<Tip>
  If you only set up three Tags, start with `account_type`, `trial_end_date`, and `core_feature_used`. They power every starter segment below.
</Tip>

#### Lifecycle state

| Tag                         | Values                                      | Use                                                                                                                                                                 |
| :-------------------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `account_type`              | `free` / `trial` / `paid` / `lapsed`        | Lifecycle state that drives Journey entry, exit, and audience filters.                                                                                              |
| `plan_tier`                 | `basic` / `pro` / `enterprise` (your tiers) | Tailor upsell, renewal, and feature messaging by plan tier.                                                                                                         |
| `trial_end_date`            | Unix timestamp (seconds)                    | Trigger time-based conversion Journeys. Use OneSignal [time operators](./time-operators) to compare against the current time and send N days before the trial ends. |
| `subscription_start_date`   | Unix timestamp (seconds)                    | Drive anniversary and tenure-based messaging for paid users. Pair with [time operators](./time-operators).                                                          |
| `subscription_renewal_date` | Unix timestamp (seconds)                    | Drive renewal-window messaging (e.g., "renews in 7 days") and post-expiration win-back. Pair with [time operators](./time-operators).                               |
| `subscription_auto_renew`   | `1` (set when auto-renew is on)             | Suppress renewal-prompt messaging for subscribers who will auto-renew. Removing the Tag flags the highest-priority retention moment.                                |

#### Engagement

| Tag                  | Values                                          | Use                                                                                                                                                                                                                                                                |
| :------------------- | :---------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `core_feature_used`  | `1` (set when used)                             | Confirms the user has hit their Aha moment. Absence is your highest-leverage adoption segment; these users carry the highest churn risk.                                                                                                                           |
| `weekly_active_user` | `1` (set when WAU)                              | Identify Power Users for upsell or annual-plan offers.                                                                                                                                                                                                             |
| `most_used_feature`  | string (e.g., `dashboard`, `goals`, `tracking`) | The user's most-used feature over the last 30 days. Personalize re-engagement copy ("It's been a week since your last `{{ most_used_feature }}` session") with a Tag the user actually cares about. Set from your analytics pipeline on a daily or weekly cadence. |

#### Personalization and preferences

| Tag                       | Values                                     | Use                                                                                                                                                     |
| :------------------------ | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `first_name`              | string                                     | Personalize message content (e.g., `Hi {{ first_name \| default: 'there' }}`).                                                                          |
| `acquisition_source`      | `referral` / `social` / `organic` / `paid` | Tailor onboarding messaging to where the user came from.                                                                                                |
| `content_pref_<category>` | `1`                                        | Per-category content preferences (e.g., `content_pref_marketing`, `content_pref_entertainment`). Set when the user opts in; absence means not opted in. |

### Custom Events

Custom Events are how Journeys react in the moment a trigger happens. Send a Custom Event for each moment you want to react to. Events can carry properties, making them ideal for Journey entry triggers and conversion tracking. Use lowercase `snake_case` for event names.

| Event                                 | Use case                                                                                                                                                                                              |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signup_completed`                    | Welcome Journey entry. Carry `acquisition_source` as a property for source-aware copy.                                                                                                                |
| `trial_started`                       | Trial onboarding Journey entry.                                                                                                                                                                       |
| `onboarding_completed`                | Exit onboarding Journeys; confirm setup is finished.                                                                                                                                                  |
| `core_feature_used`                   | Confirm activation; exit feature-education Journeys. Fired alongside the `core_feature_used` Tag; the event triggers Journey logic in the moment while the Tag persists state for later segmentation. |
| `aha_moment_reached`                  | Distinct activation milestone when "first use" and "real value realized" differ (e.g., first export, first invite sent, first habit logged). Use as a stronger Journey exit than `core_feature_used`. |
| `trial_converted`                     | Exit trial-to-paid conversion Journeys; thank-you message.                                                                                                                                            |
| `plan_upgraded`                       | Exit upsell Journeys; expansion thank-you.                                                                                                                                                            |
| `plan_downgraded`                     | Retention check-in trigger; precedes churn for many users.                                                                                                                                            |
| `subscription_renewed`                | Renewal thank-you, retention checkpoint, and dunning Journey exit.                                                                                                                                    |
| `payment_failed`                      | Dunning Journey entry. Carry `failure_reason` (e.g., `card_expired`, `insufficient_funds`) as a property for tailored copy.                                                                           |
| `payment_succeeded`                   | Dunning Journey exit; renewal confirmation.                                                                                                                                                           |
| `subscription_cancelled`              | Win-back Journey entry. Carry `cancel_reason` as a property when your billing platform captures it.                                                                                                   |
| `support_contacted`                   | Proactive outreach trigger; suppress promotional messaging while the ticket is open.                                                                                                                  |
| `referral_sent` / `referral_redeemed` | Viral-loop Journeys: thank the sender on send, and onboard the redeemer with referral-aware copy.                                                                                                     |

### Segments

Segments turn Tags and Custom Events into messaging audiences. Combine them into the ten starter segments below.

| Segment                | Definition                                                                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| New Trialists          | `trial_started` event in the last 3 days. Onboarding-burst entry distinct from the broader Active Trial.                                   |
| Active Trial           | `account_type = "trial"` AND `trial_end_date` more than 3 days from now.                                                                   |
| Trial Expiring         | `account_type = "trial"` AND `trial_end_date` within the next 3 days.                                                                      |
| Core feature untouched | `core_feature_used` does not exist. The user hasn't hit their Aha moment, making this the highest-leverage activation segment.             |
| Paid Users             | `account_type = "paid"`.                                                                                                                   |
| Power Users            | Paid Users AND `weekly_active_user = "1"`. Annual-plan upsell and advocacy targets.                                                        |
| Failed Payment         | `payment_failed` event in the last 7 days AND `account_type = "paid"`. Dunning entry.                                                      |
| At-Risk Subscribers    | `account_type = "paid"` AND `Last Session > 14 days ago`. Distinct from generic re-engagement; the offer and tone differ for paying users. |
| Lapsed                 | `account_type = "lapsed"`. Keep active for 60 days post-cancellation, then exit users to a long-tail dormant list.                         |
| Re-engagement          | OneSignal's built-in `Last Session` filter: more than 7 days for trial users, more than 14 days for free users.                            |

<Note>
  Mature mobile-first lifecycle setups run 15+ segments. Start with the ten above, then add depth (preferred channel, locale, session frequency) as your Journeys grow.
</Note>

<Frame>
  <img alt="Segment list in the OneSignal dashboard showing Active Trial, Trial Expiring, and Core feature untouched audiences." />
</Frame>

## Lifecycle Journeys

Most mobile-first revenue and churn happens at five lifecycle transitions, and a different Journey drives each one. With Tags, Custom Events, and segments in place, build messaging flows against them. Mobile-first apps mix channels by intent: push and in-app for real-time nudges, email for deeper conversion content, and SMS for high-intent moments like trial expiration and renewal. Most use cases below are Journeys, but some (like prompting for push permissions) use in-app messages alone.

Most mobile-first users move through five lifecycle stages, with a different Journey driving each transition:

```mermaid theme={null}
flowchart LR
    A[New user] -->|Welcome| B[Active trial]
    B -->|Trial-to-paid| C[Paid user]
    C -. 14+ days inactive .-> D[At-risk]
    D -. Cancellation .-> E[Lapsed]
    E -. Win-back .-> C
```

The lifecycle above has four Journey flows driving its transitions, plus a fifth event-driven category for cross-cutting moments:

<Columns>
  <Card title="Welcome and onboarding" icon="hand-wave" href="./mobile-first-journeys#welcome-journeys">
    Engage new users immediately and drive them to their Aha moment before the trial expires.
  </Card>

  <Card title="Trial-to-paid conversion" icon="circle-check" href="./mobile-first-journeys#trial-to-paid-conversion">
    Convert trialists with time-based sequences that ramp up urgency as the trial ends.
  </Card>

  <Card title="Retention and re-engagement" icon="rotate-left" href="./mobile-first-journeys#retention-journeys">
    Catch at-risk users with `Last Session` thresholds before they fully disengage.
  </Card>

  <Card title="Win-back" icon="arrow-rotate-right" href="./mobile-first-journeys#win-back-journeys">
    Re-engage churned subscribers with a value reminder rather than a discount.
  </Card>

  <Card title="Event-driven" icon="bolt" href="./mobile-first-journeys#event-driven-journeys">
    React to user actions in real time, like purchase confirmation, milestones, and dunning.
  </Card>
</Columns>

### More use cases

Beyond the lifecycle Journeys, mobile-first apps commonly run these standalone use cases:

<Columns>
  <Card title="Daily streaks" icon="fire" href="./daily-streak">
    Reward consistent engagement with daily streak reminders that drive habit formation.
  </Card>

  <Card title="Get more app store reviews" icon="star" href="./example-app-store-review">
    Prompt satisfied users for App Store and Google Play reviews at peak moments.
  </Card>

  <Card title="App version update prompts" icon="circle-up" href="./app-version-update">
    Target users on outdated app versions and nudge them to update via in-app messages.
  </Card>

  <Card title="Push fallback to email or SMS" icon="arrows-rotate" href="./push-fallback-method">
    Reach users via email or SMS when push delivery fails for high-priority moments.
  </Card>
</Columns>

## Best practices

* **Don't trigger the system-level push prompt at install.** Capture push opt-in via an in-app message *after* signup, the tutorial, or first Aha moment so the prompt arrives at a natural beat with context. Use a benefit-led message ("Get notified when your trial features unlock") rather than a generic prompt. See [Prompt for push permission with in-app messages](./prompt-for-push-permissions).
* **Time conversion pushes to the user's local time.** Trial-ending pushes scheduled in server time fire at 3 a.m. for half your audience. Use [Intelligent Delivery or Custom time per timezone](./push#delivery-schedule-and-optimization) so reminders land in waking hours.
* **Use `core_feature_used` as a Journey exit, not just an entry.** The single biggest welcome-Journey mistake is messaging users who already activated. Add the `core_feature_used` event (or Tag) as an exit on every onboarding Journey so converted users stop receiving feature-education pushes.
* **Cap trial-Journey frequency at one per day.** Trials are 7–14 days for most apps. Two pushes a day for that window will burn through your hard-won opt-in. Use a Journey-level frequency cap and let in-app messages carry the higher-frequency nudges.
* **Suppress promotional messaging during open support tickets.** Listen for `support_contacted` and add a suppression filter (e.g., "no `support_resolved` event in last 3 days") to upsell and renewal Journeys. A renewal nudge during an active complaint reads as tone-deaf.
* **Deep link every push to a specific screen.** A notification that opens the app home screen instead of the relevant content squanders most of the conversion value. Set a deep link on every Journey message so tapping the notification takes the user directly to the intended destination. See [Deep linking](./deep-linking).

### Measure success

Measure success by these metrics, not just opens or CTR:

* **Core action completion rate** of new users (`core_feature_used` Tag set)
* **Trial-to-paid conversion rate** (`trial_converted` over `trial_started`)
* **Weekly Active Users (WAU)** trend over time
* **Retention curve** at Day 7 / 14 / 30 from signup

## FAQ

### Should I use a Tag or a Custom Event for a given signal?

Use a **Custom Event** when you want to trigger a Journey or count an occurrence (e.g., `trial_started`, `core_feature_used`). Use a **Tag** when you want to segment on the user's current state or set a Journey exit condition (e.g., `account_type = "trial"`, `core_feature_used = "1"`). Many signals deserve both: fire the event in the moment, then update the Tag to reflect the new state.

### How often should I message trial users?

At most one push per day during the trial window, plus in-app messages. Trials are short (typically 7–14 days), and over-messaging during the trial is the fastest way to lose hard-won opt-in. Use a Journey-level frequency cap to enforce this, and watch your push opt-out rate by Journey step; a step with disproportionate opt-outs is the earliest signal you're being too aggressive.

### How do I keep converted users out of conversion Journeys?

Add an exit condition to every conversion Journey on either the `trial_converted` Custom Event or `account_type = "paid"`. Without an exit, converted users continue receiving "your trial ends in 2 days" pushes, the most common and most damaging onboarding mistake. The same pattern applies to onboarding Journeys: exit on `core_feature_used` or `onboarding_completed` so activated users stop seeing feature-education content.

### Do I need data integrations to use lifecycle Journeys?

No. You can build effective welcome and retention Journeys using dashboard-only segments like "First Session" and "Last Session." Custom Events and Tags give you more precise triggers and exit conditions, but they are not required to get started.

### Does this guide apply to apps with a web or desktop surface?

The patterns here apply to any subscription or freemium product, but the channel mix shifts. Apps with a meaningful web or desktop surface should layer in web push and additional segments for cross-platform users on top of this mobile-first foundation.

### What about apps with one-time purchases or downloadable content (DLC) instead of subscriptions?

The patterns apply, but the trial-specific Tags and Custom Events do not. Swap `trial_end_date` for `last_purchase_date`, `trial_started` and `trial_converted` for `first_purchase_completed`, and the **Trial Expiring** segment for an at-risk segment based on `Last Session`. For high-value users, replace `weekly_active_user` with a spend-based Tag like `total_spend_cents` or `purchase_count`. See [Welcome Journey: Mobile gaming](./welcome-journey-mobile-gaming) for an end-to-end Journey shaped around purchases instead of subscriptions.


# Mobile-first lifecycle Journeys
Source: https://documentation.onesignal.com/docs/en/mobile-first-journeys

Welcome, trial-to-paid, event-driven, retention, and win-back Journey playbooks for mobile-first apps, with both basic and advanced data integrations covered.

This guide implements the [Mobile-first strategy](./mobile-first) as five lifecycle Journeys: welcome, trial-to-paid conversion, event-driven, retention, and win-back. Each Journey supports two implementation paths so you can ship value before all your Custom Event tracking is in place:

* **Case 1 – Basic:** Use only the data the OneSignal SDK collects automatically — `First session`, `Last session`, and built-in Subscription attributes. No Custom Events or Tags required.
* **Case 2 – Advanced:** Use [Custom Events](./custom-events) and [Tags](./add-user-data-tags) for behavior-triggered, per-user personalization.

Start with Case 1 and layer in Case 2 components as your data integrations mature.

<Note>
  This page covers the five core mobile-first Journey shapes. More examples can be found in [Tutorials](./tutorials).
</Note>

## Prerequisites

Work through the [Mobile-first strategy implementation roadmap](./mobile-first#implementation-roadmap) before building Journeys here. The strategy page defines the data foundation; this page implements it.

**Required:**

* **External IDs** assigned at signup, login, and session resume — see [External ID setup](./users#external-id).
* Access to [Journeys](./journeys-overview) in your OneSignal dashboard.
* At least one configured channel: push (with permission prompted), email, or SMS.

**Recommended:**

* An [in-app message that prompts for push permission](./prompt-for-push-permissions) — required for the Case 1 welcome flow's first step.
* **Case 2 only:**
  * **Core Tags**: `account_type`, `core_feature_used`, `trial_end_date` — see [Tags](./mobile-first#tags).
  * **Core Custom Events**: `signup_completed`, `core_feature_used`, `trial_converted`, `subscription_cancelled` — see [Custom Events](./mobile-first#custom-events).
  * **Starter segments**: Active Trial, Trial Expiring, Core feature untouched, At-Risk Subscribers, Lapsed — see [Segments](./mobile-first#segments).

If you don't have Custom Events yet, build the Case 1 versions of welcome, retention, and win-back while your event tracking comes online. Trial-to-paid conversion requires a `trial_end_date` Tag in both cases.

## Welcome Journeys

The welcome Journey's job is to set new users up for success: drive them to their Aha moment before they churn. The first 7 days determine whether a new user becomes a long-term customer or a churn statistic, so the welcome Journey runs across the full week with gentle daily nudges. Four principles drive the structure:

1. **Capture permissions early.** Drive push opt-in via a Day 1 in-app message during or right after onboarding. Without push permission, every later welcome step that uses push goes unread.
2. **Introduce the product.** Pair the IAM with a Day 1 email for consenting users that introduces what the product does, what to do next, and what messages to expect from you.
3. **Nudge toward the core feature daily.** Days 2–6 each carry a single, gentle reminder tied to a feature, use case, or setup step — never a streak claim or a hollow "we miss you."
4. **End the week deliberately.** A Day 7 closing email recaps the user's first week and transitions them from "trying the product" to "part of the community."

<Note>
  The "Aha moment" is the single core action most predictive of conversion or retention in your app. Identify it before you build the Journey. For a workout app it might be logging the first session; for a finance app, linking the first account.
</Note>

### Welcome Journey configuration

Both cases share segments, templates, and Journey settings. Build them once and reference from either case.

#### Welcome Journey segments

**Entry:**

* **Case 1**: Built-in segment `First Session < 1 day ago` AND `Last Session > 4 hours ago`. The user matches the moment they cross 4 hours of inactivity inside their first day — exactly when the Day 1 message sequence should fire, not the moment of signup.
* **Case 2**: Custom Event entry on `signup_completed` (or `trial_started` for trial-based apps), then a 4-hour Wait so the first message lands after the user finishes their initial session.

**Recent activity check (Case 1 only):**

* **Name:** "Active in the last 12 hours"
* **Filter:** `Last Session < 12 hours ago`

The Day 2–7 Yes/No branches use this segment to skip the daily push if the user has already been active. Twelve hours is a deliberate compromise — long enough that the user feels like they "just used" the app, short enough that yesterday's evening session doesn't suppress today's nudge.

**Exit conditions:**

* **Case 1**: Time-based — Journey completes after the Day 7 closing email.
* **Case 2**: Event-based — exit on `core_feature_used = "1"` or `onboarding_completed`. Users who activate stop receiving feature-nudge messages.

#### Welcome Journey templates

These templates are starting points — clone, edit, and re-use them in your own Journey. They use [Liquid syntax](./using-liquid-syntax) for personalization.

<Tabs>
  <Tab title="Push templates">
    | Day | Name                 | Purpose                                            |
    | :-: | -------------------- | -------------------------------------------------- |
    |  1  | Day 1 — First action | Deep link to the highest-leverage first action     |
    |  2  | Day 2 — Quick win    | 60-second action that reinforces value             |
    |  3  | Day 3 — Feature tip  | A useful capability most users miss in week one    |
    |  4  | Day 4 — Use case     | Connect the product to a realistic outcome         |
    |  5  | Day 5 — Setup nudge  | Incomplete-profile or preferences reminder         |
    |  6  | Day 6 — Community    | Soft invite to community, social, or share moments |
    |  7  | Day 7 — Week 1 wrap  | Final value reminder before the closing email      |

    Keep copy short and benefit-led. Deep-link every push to the exact screen where the user can take the action — see [Deep linking](./deep-linking).

    <Columns>
      <Card title="Templates" icon="clone" href="./templates">
        Create and manage reusable message templates.
      </Card>

      <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
        Pull Tag values into push, email, and IAM copy with Liquid.
      </Card>
    </Columns>
  </Tab>

  <Tab title="Email templates">
    Two emails fire — one on Day 1, one on Day 7 — each playing a distinct role. See [Email messaging](./email-messaging) for setup.

    **Day 1 — Welcome and push opt-in**

    *Purpose:* Open the Journey with a value-led welcome that also drives push opt-in for users who declined the install-time prompt.

    *Content outline:*

    * A short welcome and product framing — what the user can do, not a feature tour.
    * 1–2 next-step CTAs deep-linking into the app (e.g., complete profile, try the core feature).
    * A **turn-on-notifications** CTA that deep-links to your in-app preference center or notification settings screen. This catches users who declined install-time push without forcing a fresh OS prompt — see [Prompt for push permission with in-app messages](./prompt-for-push-permissions) for the in-app prompt pattern that pairs with this CTA.
    * Expectation-setting on what messages they'll receive and how often.
    * Help center or support links so users don't have to email you with questions.

    **Day 7 — First week recap and what's next**

    The closing email at the end of the Journey. Where Day 1 welcomes the user into the product, this email transitions them from "trying the product" to "part of the community."

    *Purpose:* Reinforce progress, surface what's still unexplored, and give the user a reason to look forward to Week 2.

    *Content outline:*

    * A first-week recap — actions completed, key features used. Personalize via Tags or [Liquid syntax](./using-liquid-syntax) where you have the data.
    * A **next chapter** section: 2–3 things to try in Week 2 (advanced features, integrations, settings).
    * A community or social CTA — Discord, X, blog, or your customer community.
    * A teaser for what's coming next (upcoming feature, content drop, or a Day 14 milestone).

    <Columns>
      <Card title="Templates" icon="clone" href="./templates">
        Create and manage reusable message templates.
      </Card>

      <Card title="Email warm-up" icon="envelope" href="./email-warm-up">
        Required if you're sending Welcome email at scale on a new domain.
      </Card>
    </Columns>
  </Tab>

  <Tab title="In-app message templates">
    In-app messages fire when the user is *already in the app* — the highest-leverage moment to drive setup completion, push opt-in, and feature engagement. Three IAMs cover the Journey's main inflection points.

    **Day 1 — Onboarding flow**

    Use a multi-card or carousel IAM to funnel new users into the two highest-leverage setup steps:

    1. Profile / preferences completion
    2. Push opt-in via a **Push Permission Prompt** click action

    Users who finish both are dramatically more likely to stick. Profile investment creates sunk-cost attachment, and without push opt-in, the rest of this Journey can't reach them outside the app.

    <Info>
      A **Push Permission Prompt** IAM will not display if the user has already granted push permission, so it's safe to leave the prompt in even for users who opted in elsewhere.
    </Info>

    **Day 3 — Feature spotlight**

    A single-card IAM that highlights one secondary feature most users miss in their first week. Pick a feature with high adoption-to-retention correlation (e.g., the second tier of the core workflow, an integration, or a personalization setting).

    1. A specific benefit ("Save 10 minutes a week with \[feature]")
    2. A primary CTA that deep-links to the feature
    3. A dismiss action that doesn't re-show on the same session

    **Day 6 — Community and share**

    A soft-invite IAM that introduces the user to your broader community. Pick whichever touchpoint is most natural for your product:

    * Join a community channel (Discord, Slack, Reddit, customer forum).
    * Share a milestone or referral code with friends.
    * Follow your social accounts for tips and updates.

    Keep the ask low-stakes — this is the inflection from "user" to "community member," not a hard upsell.

    <Columns>
      <Card title="Design your in-app message" icon="pen-ruler" href="./design-your-in-app-message">
        Full reference for the IAM editor, blocks, and Carousel.
      </Card>

      <Card title="Prompt for push permission" icon="bell" href="./prompt-for-push-permissions">
        Configure a **Push Permission Prompt** click action on a Day 1 IAM.
      </Card>
    </Columns>
  </Tab>
</Tabs>

#### Welcome Journey settings

Entry and exit rules are covered in [Welcome Journey segments](#welcome-journey-segments) above. In addition, configure these Journey-level settings:

* **Future additions only**: **Checked** — so existing users aren't bulk-enrolled the moment the Journey is saved.
* **Re-entry rules**: **Disabled** — each user receives this Journey only once.

#### Daily timing: Wait + Time Window (Case 1)

Case 1 uses two Journey actions together to deliver a daily nudge during the user's most likely engagement window:

1. **[Wait](./journeys-actions#wait):** A fixed delay between days.
2. **[Time Window](./journeys-actions#time-window):** A delivery window in the user's local timezone (default: 6 PM – 10 PM). Each day's push is held until the window opens.

Set the Wait to the **Time Window duration + a 2-hour buffer**. For a 4-hour evening window, the Wait is **6 hours** — the buffer guarantees the Wait always expires after the window closes, so the next push is held for the *following* day rather than re-firing the same evening. See [Welcome Journey: Mobile gaming](./welcome-journey-mobile-gaming#daily-timing-wait--time-window) for the full timing math.

<Tip>
  Adjust the Time Window to your audience. B2B productivity apps may prefer a 9 AM – 12 PM weekday window; consumer wellness apps may prefer 7 AM – 9 AM. Evening is a strong default for general consumer apps but worth A/B testing against your usage data.
</Tip>

<Tabs>
  <Tab title="Case 1 – Basic">
    The Basic flow uses time-based delays and the recent-activity Yes/No branch — a "set it and forget it" 7-day welcome that requires no Custom Events or Tags.

    ##### Day 1

    <Steps>
      <Step title="Email: Day 1 — Welcome and push opt-in">
        **Goal:** Open the Journey with an appreciative, value-led email that also drives push opt-in.

        Because this is the first message step, the email lands 4 hours after the user's first session ends (per the entry segment) — less needy, more deliberate. The email's push opt-in CTA also catches users who declined the install-time permission prompt, deep-linking them to the in-app preference center.
      </Step>

      <Step title="In-App Message: Day 1 — Onboarding flow">
        **Goal:** Drive profile completion and push opt-in the next time the user opens the app.

        Queue the Day 1 onboarding IAM so it displays on the user's next session. The flow funnels them into:

        1. Profile / preferences completion
        2. Push opt-in via a **Push Permission Prompt** click action

        <Warning>
          Make sure this IAM doesn't overlap with other [push permission prompt strategies](./prompt-for-push-permissions) outside the Journey. Two prompts firing back-to-back leads to one being silently skipped — better to remove it from this IAM than have both trigger.
        </Warning>
      </Step>

      <Step title="Time Window: 6 PM – 10 PM">
        **Goal:** Hold the Day 1 push until the evening engagement window.

        The entry segment can trigger overnight or early morning. Without the Time Window, an inactivity threshold crossed at 2 AM would push at 6 AM. This holds the push until 6 PM in the user's timezone.
      </Step>

      <Step title="Push Notification: Day 1 — First action">
        **Goal:** Drive a second session by deep-linking to the highest-leverage first action.

        Keep copy short and benefit-driven — "Here's the one thing to try first" works as a starting point. Deep-link to the exact screen where the user can take that action, not the app home.
      </Step>
    </Steps>

    ##### Day 2

    <Steps>
      <Step title="Wait: 6 hours">
        **Goal:** Push the next Time Window evaluation past 10 PM so the window snaps to the next day rather than re-firing the same evening. See [Daily timing](#daily-timing-wait--time-window-case-1) for the math.
      </Step>

      <Step title="Time Window: 6 PM – 10 PM">
        **Goal:** Hold the next push until the evening engagement window.
      </Step>

      <Step title="Yes/No branch: Active in the last 12 hours">
        **Goal:** Skip the push if the user has already returned to the app.

        **Setup:** Segment membership: "Active in the last 12 hours."

        This creates two branches:

        * **Yes:** User was active in the last 12 hours → skip the push and continue to the next day's Wait.
        * **No:** User has not returned → send the Day 2 push on the No branch.
      </Step>

      <Step title="Push Notification: Day 2 — Quick win">
        **Goal:** Bring the user back with a 60-second action that reinforces value.

        Add this to the **No** branch of the Yes/No step.
      </Step>
    </Steps>

    ##### Days 3–6

    Each day repeats the Day 2 pattern — **Wait 6 hours → Time Window 6 PM – 10 PM → Yes/No branch → push on the No branch**. Drop in the per-day push template (`Day 3 — Feature tip`, `Day 4 — Use case`, `Day 5 — Setup nudge`, `Day 6 — Community`).

    Insert the **Day 3 feature spotlight** and **Day 6 community/share** IAM steps *before* their corresponding day's 6-hour Wait, so the IAM is queued and ready to display the next time the user opens the app.

    ##### Day 7

    Day 7 follows the same four-step pattern as Days 2–6, then adds the closing email after the branches converge:

    <Steps>
      <Step title="Wait: 6 hours">
        **Goal:** Push the next Time Window evaluation past 10 PM so the window snaps to the next day.
      </Step>

      <Step title="Time Window: 6 PM – 10 PM">
        **Goal:** Hold the Day 7 push until the evening engagement window.
      </Step>

      <Step title="Yes/No branch: Active in the last 12 hours">
        **Goal:** Skip the push if the user has already returned to the app.

        **Setup:** Segment membership: "Active in the last 12 hours."

        * **Yes:** User was active in the last 12 hours → skip the push and continue to the closing email.
        * **No:** User has not returned → send the Day 7 push on the No branch, then continue to the closing email.
      </Step>

      <Step title="Push Notification: Day 7 — Week 1 wrap (No branch)">
        **Goal:** Send a final value reminder before the closing email lands.

        Add this to the **No** branch of the Yes/No step.
      </Step>

      <Step title="Email: Day 7 — First week recap and what's next">
        **Goal:** Transition the user from "trying the product" to "part of the community."

        Add this email step *after* the Yes/No branch's two paths converge — not on either branch. Placing it after convergence means active and inactive users both receive the milestone email, regardless of whether they took the Day 7 push.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Case 2 – Advanced">
    Case 2 is structurally identical to Case 1 — same Day 1 setup, same Day 3 and Day 6 IAMs, same Day 7 closing email. The only change is from Day 2 onward: replace Case 1's **Wait + Yes/No branch** with a single [Wait Until](./journeys-actions#wait-until) node that listens for `core_feature_used` (or another high-signal Custom Event). The Time Window stays.

    This swaps a time-based heuristic ("did the user open the app in the last 12 hours?") for a behavioral fact ("did the user actually do the thing the Journey is nudging?"). Users who hit the event take the event branch and continue silently — no push lands on top of an active session, and active users still receive the closing Day 7 email.

    ##### Required data

    | Type         | Name                 | Description                                                                                                                                                                        |
    | ------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Custom Event | `core_feature_used`  | Fires when the user takes the Aha-moment action. Dedupe to **once per calendar day in the user's timezone** so same-day repeats don't advance the Journey through subsequent days. |
    | Tag (string) | `first_name`         | *Recommended.* Used by the email and push templates for `{{ first_name \| default: 'there' }}` personalization.                                                                    |
    | Tag (string) | `acquisition_source` | *Optional.* Lets you vary Day 1 push and email copy by acquisition channel.                                                                                                        |

    ##### Day 1

    Identical to Case 1: Email → IAM → Time Window → Push. The only difference is the entry rule — Case 2 enters on the `signup_completed` Custom Event with a 4-hour Wait, instead of the inactivity-based segment. Switch to the **Case 1 – Basic** tab above to see the full Day 1 step list.

    ##### Days 2–6

    Days 2 through 6 share a single pattern. Each day uses a Wait Until node in place of Case 1's Wait + Yes/No combo. The Time Window and the day's push move onto the expiration branch; the event branch stays silent.

    <Steps>
      <Step title="Wait Until: core_feature_used">
        **Goal:** Branch on whether the user has hit their Aha moment in the last day.

        **Condition:** `core_feature_used` Custom Event fires.
        **Expiration:** **22 hours**.

        * **Event branch** — user activated on their own. Continue silently; no push, no email.
        * **Expiration branch** — no activation in 22 hours. Continue to the Time Window and the day's push.

        <Tip>
          **Scope each Wait Until to a specific day with an event property.** Fire `core_feature_used` with a property like `day` that increments per session day, and have each day's Wait Until match the corresponding value. This prevents a late-arriving event from an earlier day from satisfying a later day's Wait Until and gives you cleaner per-day funnel analytics. See [Event Matching](./journeys-actions#event-matching).
        </Tip>
      </Step>

      <Step title="Time Window: 6 PM – 10 PM (expiration branch only)">
        **Goal:** Hold the day's push until the evening engagement window.

        On the expiration branch only. Same Time Window pattern as Case 1, kept here so the push always lands in the evening regardless of when the Wait Until expired.
      </Step>

      <Step title="Push Notification: day's template (expiration branch only)">
        **Goal:** Send the day's nudge — `Day 2 — Quick win`, `Day 3 — Feature tip`, etc.

        After this step, both branches converge and continue to the next day's Wait Until.
      </Step>
    </Steps>

    **IAM placement.** Insert the **Day 3 feature spotlight** and **Day 6 community/share** IAM steps *before* their corresponding day's Wait Until node, so the IAM is queued and ready to display the next time the user opens the app.

    ##### Day 7

    Day 7 follows the same Wait Until pattern as Days 2–6 and adds the closing email after the branches converge:

    <Steps>
      <Step title="Wait Until + Time Window + Push (expiration branch)">
        Same shape as Days 2–6: a Wait Until on `core_feature_used` with a 22-hour expiration, then the Time Window and `Day 7 — Week 1 wrap` push on the expiration branch. The event branch stays silent.
      </Step>

      <Step title="Email: Day 7 — First week recap and what's next">
        **Goal:** Transition the user from "trying the product" to "part of the community."

        Add this email step *after* both branches converge — not on either branch. Active and inactive users both receive the milestone email, regardless of whether the push fired. Personalize the recap section using Tags you've collected during the week (`core_feature_used`, completed-setup signals, etc.).
      </Step>
    </Steps>

    ##### Optional: route activated users to a separate post-activation Journey

    If you want to do more than fall silent on activation, configure the Journey **exit rule** to fire on `core_feature_used = "1"` and use that Tag (or a `welcome_completed = "true"` Tag set in a Tag User step) as the entry filter for a follow-up Journey focused on adoption depth — second-tier features, integrations, or expansion offers.
  </Tab>
</Tabs>

<Tip>
  **Track time-to-Aha**, not just open rate. The single best indicator of welcome Journey health is how quickly new users hit your core feature for the first time. Compare your control group to users who completed the welcome Journey to measure lift.
</Tip>

## Trial-to-paid conversion

The trial-to-paid Journey converts trial users to paying subscribers in the days before their trial ends. Where the Welcome Journey teaches the product, this Journey closes the deal — value reminders, time pressure, and a clear upgrade ask calibrated to where the user is in the trial. Three principles drive the structure:

1. **Time pressure beats discount.** A trial-ending reminder converts higher than a blanket "20% off" email. Use `trial_end_date` for a real countdown; reserve discounts for the final day or the win-back Journey.
2. **Activation status changes the message.** A trial user who hit the core feature gets "Keep going — your data and progress carry over"; one who didn't gets "Try `{{ core_feature_name }}` before your trial ends — it's the part most subscribers love." Same Journey, branched copy.
3. **Exit on conversion, immediately.** Add an exit on `trial_converted` (or `account_type = "paid"`) so converted users stop receiving "trial ending" pushes. This is the single most damaging conversion-Journey mistake — see the [mobile-first FAQ](./mobile-first#faq) for the suppression pattern.

### Trial-to-paid configuration

**Entry rules:**

* **Case 1**: `account_type = "trial"` AND `trial_end_date` within the next 7 days (the **Trial Expiring** segment from the strategy page, with the threshold widened from 3 days to 7).
* **Case 2**: Custom Event entry on `trial_started` with a Wait until 7 days before `trial_end_date` using [time operators](./time-operators). Cleaner attribution — entry timestamp matches the trial's actual start, not the moment OneSignal evaluated the segment.

**Exit rules:**

* **Both cases**: Exit when `trial_converted` Custom Event fires *or* `account_type = "paid"`. Whichever your billing pipeline updates first triggers the exit.
* **Both cases**: Also exit on `subscription_cancelled` so users who explicitly cancel their trial don't get further reminders.

**Re-entry rules:** No — most trials are single-use. Apps that offer trial extensions should set re-entry per business policy.

**Future additions only:** **Checked** — keep this on so users mid-trial when the Journey is created don't get bulk-enrolled into a 7-day cadence partway through.

### Trial-to-paid templates

| Days before end | Channel          | Purpose                                                                                             |
| :-------------: | ---------------- | --------------------------------------------------------------------------------------------------- |
|        7        | Push             | Soft heads-up. "Your trial ends `{{ days_remaining }}` days from now" framing.                      |
|        5        | Email            | Feature recap + upgrade CTA. Personalize the recap with what the user already used.                 |
|        3        | Push + IAM       | Activation-aware nudge. Deep-link to the upgrade screen, or the core feature for unactivated users. |
|        1        | Push             | Last call — concrete time remaining. "Your trial ends tomorrow at `{{ trial_end_time }}`."          |
|   0 (last day)  | SMS *(optional)* | High-intent SMS-opted-in users only. Keep copy short and include the upgrade deep link.             |

Keep every push and email deep-linked to the upgrade screen — see [Deep linking](./deep-linking). The fewer taps between message and conversion, the higher the rate.

<Tabs>
  <Tab title="Case 1 – Basic">
    The Basic flow uses the `trial_end_date` Tag with [time operators](./time-operators) to schedule each day's message a fixed number of days before the trial ends.

    <Steps>
      <Step title="Entry: Trial Expiring (widened to 7 days)">
        **Goal:** Catch every trial user 7 days before their trial ends.

        **Setup:** Build a segment `account_type = "trial"` AND `trial_end_date` within the next 7 days. Use this as the Journey entry audience.
      </Step>

      <Step title="Push: Day-7 heads-up">
        **Goal:** Open the Journey with a non-pushy reminder that the trial is ending.

        Lead with what the user has already done, not what they'll lose. "You've logged 6 sessions — keep your streak going past `{{ trial_end_date | date: '%b %-d' }}`" outperforms "Your trial expires soon."
      </Step>

      <Step title="Wait Until: 5 days before trial_end_date">
        **Goal:** Hold until the next milestone.

        Use a [time operator](./time-operators) Wait Until: `trial_end_date - 5 days`. This is more precise than a fixed 2-day Wait, because it anchors to the actual trial end date for users who entered partway through their trial.
      </Step>

      <Step title="Email: Day-5 feature recap and upgrade CTA">
        **Goal:** Surface a longer-form value reminder with a primary CTA to upgrade.

        Recap features used during the trial (where you have the data) and pair the recap with a single upgrade CTA. Email is where the longer-form value case lives — push and IAM carry the urgency.
      </Step>

      <Step title="Wait Until: 3 days before trial_end_date">
        **Goal:** Hold until the Day-3 push window.
      </Step>

      <Step title="Push: Day-3 nudge">
        **Goal:** Re-engage users who haven't yet upgraded.

        Reference time concretely: "3 days left." Deep-link to the upgrade screen.
      </Step>

      <Step title="Wait Until: 1 day before trial_end_date">
        **Goal:** Hold until the final-day push.
      </Step>

      <Step title="Push: Last call">
        **Goal:** A clear, concrete final ask.

        "Your trial ends tomorrow at `{{ trial_end_date | date: '%-l %p' }}`." Keep the copy tight; this is the highest-intent moment in the Journey.
      </Step>

      <Step title="Exit on trial_converted or account_type = paid">
        **Goal:** Stop the Journey the moment the user converts.

        Configure as a Journey-level exit rule, not a step. Exit also on `subscription_cancelled` so cancelled users don't continue to receive trial-ending reminders.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Case 2 – Advanced">
    Case 2 is structurally identical to Case 1, with two additions: an entry rule on `trial_started` (cleaner attribution than segment entry), and an activation branch that varies copy based on whether the user has hit `core_feature_used`.

    ##### Required data

    | Type            | Name                | Description                                                                                                            |
    | --------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
    | Tag (timestamp) | `trial_end_date`    | Unix timestamp set at trial start. Required for time-operator Waits.                                                   |
    | Tag (string)    | `account_type`      | `trial` / `paid` / `lapsed`. Drives Journey entry and exit.                                                            |
    | Tag (`1`)       | `core_feature_used` | Drives the activation branch. Users with the Tag get "keep going" copy; users without get "try the core feature" copy. |
    | Custom Event    | `trial_started`     | Journey entry event.                                                                                                   |
    | Custom Event    | `trial_converted`   | Exit event.                                                                                                            |

    ##### Activation branch

    The key Case 2 enhancement is a Yes/No branch on `core_feature_used` before each push, so the same Journey delivers two parallel cadences:

    * **Activated users** (`core_feature_used = "1"`): "You're on track — `{{ core_feature_name }}` is what most subscribers stay for. Keep going past `{{ trial_end_date | date: '%b %-d' }}`."
    * **Unactivated users** (Tag does not exist): "Try `{{ core_feature_name }}` before `{{ trial_end_date | date: '%b %-d' }}`. It's the part most subscribers love."

    Both branches deep-link to the upgrade screen; the activation branch additionally references the feature in a positive frame, while the unactivated branch deep-links to the core feature itself on the Day-3 push to give the user one last shot at activation before asking for the upgrade.

    ##### Day-by-day shape

    Identical to Case 1's step list, with the activation branch inserted before each push step (Day 7, Day 3, Day 1, and the optional Day 0 SMS). The Day-5 email gets the same activation-aware variation via Liquid conditionals — see [Liquid syntax](./using-liquid-syntax).
  </Tab>
</Tabs>

<Tip>
  **Measure trial-to-paid conversion rate by activation status.** Activated users should convert at materially higher rates than unactivated users. If they don't, the issue is upstream — your Welcome Journey isn't hitting the right Aha moment, not your conversion copy.
</Tip>

## Event-driven Journeys

Event-driven Journeys react to specific actions in real time. They're entirely Case 2 territory — you need [Custom Events](./custom-events) flowing into OneSignal to use them.

Common mobile-first event-driven patterns:

| Pattern                     | Trigger event                                                    | What the Journey does                                  |
| --------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
| Purchase confirmation       | `purchase_completed`                                             | Thank-you push and email receipt with cross-sell items |
| Milestone celebration       | `level_completed`, `streak_reached`, `loyalty_milestone_reached` | Reward push referencing what was achieved              |
| Cart or upgrade abandonment | `checkout_started` (with Wait Until on `purchase_completed`)     | Recovery push on the expiration branch                 |
| Social moments              | `friend_invited`, `friend_joined`                                | Confirmation message and prompt for additional invites |
| Payment recovery (dunning)  | `payment_failed` (with Wait Until on `payment_succeeded`)        | Card-update push and email on the expiration branch    |

### Dunning: payment recovery

A representative event-driven shape that almost every subscription app needs. Failed renewal payments are involuntary churn — most users want to keep paying but have an expired card or a temporary decline. A short dunning Journey recovers the majority of these.

<Steps>
  <Step title="Entry: payment_failed Custom Event">
    **Goal:** Catch failed renewal charges the moment your billing platform reports them.

    Fire `payment_failed` from your backend with `failure_reason` (e.g., `card_expired`, `insufficient_funds`) as a property. Filter the entry rule to `account_type = "paid"` so failed checkout attempts on free accounts don't enter the dunning Journey.
  </Step>

  <Step title="Wait Until: payment_succeeded">
    **Goal:** Exit the Journey the moment the customer's card processes successfully.

    **Condition:** `payment_succeeded` Custom Event fires.
    **Expiration:** **48 hours** — most card retries succeed within 24–48 hours of the original failure.

    * **Event branch** — payment succeeded. Continue silently; no recovery message needed.
    * **Expiration branch** — payment still failing. Continue to the recovery push and email.
  </Step>

  <Step title="Push Notification: card-update reminder (expiration branch)">
    **Goal:** Surface a one-tap deep link to the billing or payment-method screen.

    Use Liquid to vary copy by `failure_reason` — "Your card on file expired" lands much better than a generic "We couldn't process your payment." Deep-link straight to the card-update screen so the user doesn't have to navigate.
  </Step>

  <Step title="Email: detailed dunning notice (expiration branch)">
    **Goal:** Give the customer a longer-form explanation and a self-serve recovery path.

    Send 1–2 hours after the push so they aren't simultaneous. Include the amount, the SKU or plan name, the failure reason, and a primary CTA to update payment. Email is also where the legal/billing detail lives that doesn't fit in a push.
  </Step>

  <Step title="Exit: subscription_cancelled or 7-day timeout">
    **Goal:** Stop dunning if the customer cancels or never recovers.

    Add an explicit **exit on `subscription_cancelled`** so a cancellation routes the user into the [Win-back Journey](#win-back-journeys) instead of continuing to receive payment-update reminders. After 7 days without success, the customer flips to `account_type = "lapsed"` via your billing webhook and exits naturally.
  </Step>
</Steps>

The full pattern guide — entry rules, Wait Until with Event Matching, threshold modeling, and Liquid personalization — lives on [Event-driven Journeys](./event-driven-journeys). For mobile-specific welcome and retention shapes that include event-driven steps, see Case 2 in the Welcome and Retention sections on this page.

<Card title="Event-driven Journeys" icon="bolt" href="./event-driven-journeys">
  Three end-to-end patterns plus the design rules for events, properties, and Wait Until matching.
</Card>

## Retention Journeys

Retention catches active users who are slipping before they fully disengage. Two triggers matter for mobile-first apps:

* **Inactivity** — the user hasn't opened the app in N days
* **Core feature dormancy** — the user is opening the app, but hasn't engaged with the core feature in N days (Case 2 only — needs the `core_feature_used` Tag)

<Note>
  Retention catches users who are still **active subscribers but slipping**. Once a user explicitly cancels or expires, they belong in the [Win-back Journey](#win-back-journeys), not this one. The two share Tags and segments but have different goals — retention prevents churn, win-back recovers churned users.
</Note>

### Retention Journey configuration

Both cases share segment shape; the difference is granularity.

**Entry trigger:**

* **Case 1**: Built-in segment `Last Session > 7 days`.
* **Case 2**: Combine `Last Session > 7 days` with `account_type` to split trial users (7 days) from paid users (14 days). Optionally add a parallel `Core feature untouched` segment for feature-dormant users.

**Cadence (both cases):**

| Day     | Channel | Purpose                                          |
| ------- | ------- | ------------------------------------------------ |
| 7 / 14  | Push    | Reminder of value the user has already seen      |
| 10 / 17 | Email   | Tip or use case the user may not have discovered |
| 14 / 21 | Push    | One clear action to bring them back              |

**Exit conditions:**

* **Both cases**: Auto-exit when the user opens the app (segment membership ends).
* **Case 2**: Also exit on `subscription_cancelled` event so the user moves to the win-back funnel without overlap.

<Tabs>
  <Tab title="Case 1 – Basic">
    The Basic retention flow uses OneSignal's built-in `Last Session` filter to target both trial and paying users with a single cadence.

    <Steps>
      <Step title="Entry: Last Session > 7 days segment">
        **Goal:** Catch users the moment they cross the inactivity threshold.

        Built-in segment using OneSignal's `Last Session` filter. Adjust the threshold based on your app's expected usage cadence — daily-use apps may want 3–4 days, weekly-use apps may want 10–14.
      </Step>

      <Step title="Push Notification: Day 7 — Value reminder">
        **Goal:** Surface a short, benefit-led nudge that reminds the user what they're missing.

        Lead with the benefit, not a feature list. "Your week-in-review is ready" outperforms "Don't forget to use feature X" because it implies the user has earned something. Deep-link directly to the relevant screen — see [Deep linking](./deep-linking).
      </Step>

      <Step title="Email: Day 10 — Feature tip">
        **Goal:** Re-engage users who didn't respond to the Day 7 push with a longer-form value message.

        Email lets you carry more context than push. Highlight a feature, walkthrough, or use case the user may not have discovered. Keep it scannable — most reads happen in under 30 seconds.
      </Step>

      <Step title="Push Notification: Day 14 — Final CTA">
        **Goal:** Send one last clear action before the user fully disengages.

        Lead with a concrete next step rather than a guilt trip. "Pick up where you left off" works better than "We miss you."
      </Step>

      <Step title="Exit: on app open">
        **Goal:** Remove returning users from the Journey automatically.

        Because the entry segment depends on `Last Session`, the user falls out of segment membership when they open the app — no explicit exit rule needed. Make sure the Journey's [re-entry rules](./journeys-settings#re-entry-rules) allow re-entry after exit so the next inactivity period catches them again.
      </Step>
    </Steps>

    <Tip>
      **Track 14-day return rate as the headline retention metric.** A return rate above 8% on the Day-14 push is healthy for most subscription apps; below 4%, the inactivity threshold or message copy needs tuning before the cadence itself is the problem.
    </Tip>
  </Tab>

  <Tab title="Case 2 – Advanced">
    The Advanced retention flow uses `account_type` to split cadences between trial and paying users.

    <Steps>
      <Step title="Entry: split by account_type">
        **Goal:** Apply different inactivity thresholds for trial users vs paying users.

        * **Trial users:** `account_type = "trial"` AND `Last Session > 7 days`. Trial users have a short window before churn — react fast.
        * **Paid users:** `account_type = "paid"` AND `Last Session > 14 days`. The longer window accounts for normal usage variation in users who have already converted.

        Build these as two separate segments and run two parallel Journeys, or build one Journey with two entry rules — whichever your team can maintain more easily.
      </Step>

      <Step title="Push Notification: Day 7 / 14 — Personalized reminder">
        **Goal:** Bring the user back with a message that references something they already care about.

        If you have a `most_used_feature` Tag, mention it specifically: "It's been a week since your last `{{ most_used_feature }}` session." This lands meaningfully better than generic "We miss you" copy.
      </Step>

      <Step title="Email: Day 10 / 17 — Feature highlight">
        **Goal:** Email users who didn't respond to push with a longer-form re-engagement message.

        Highlight a feature or use case they haven't explored. Pull from the same `most_used_feature` Tag for personalization — "You've mastered `{{ most_used_feature }}`. Here's what to try next."
      </Step>

      <Step title="Push Notification: Day 14 / 21 — Final CTA">
        **Goal:** Make a clear final ask before the user fully disengages.

        If the user is still in trial, reference time remaining via `trial_end_date` — "Only 3 days left to set up your account." Trial-aware copy materially outperforms generic re-engagement at the end of the funnel.
      </Step>

      <Step title="Exits: app open or subscription_cancelled">
        **Goal:** Remove returning users automatically and route churned users to the win-back funnel.

        * **App open:** segment membership ends naturally when the user opens the app.
        * **`subscription_cancelled` event:** explicit exit rule that moves the user out of retention and into win-back without overlap. See [Mobile-first strategy](./mobile-first#lifecycle-journeys) for the win-back playbook.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Tip>
  **Use SMS sparingly.** SMS is most effective for high-intent moments — trial expiration, payment failures, account verification. Avoid using it for general re-engagement; the cost-per-message is high and the unsubscribe risk is real.
</Tip>

### Core feature dormancy (Case 2 only)

A user who's actively opening the app but never touching the core feature is a different kind of risk than one who's just inactive. They've passed the install hurdle but stalled before activation — re-engagement copy aimed at "we miss you" misses the actual problem.

Use the **Core feature untouched** segment from [Mobile-first strategy](./mobile-first#segments) — `core_feature_used` does not exist — combined with `Last Session < 7 days` so you only message users who *are* opening the app.

<Steps>
  <Step title="In-App Message: Core feature pointer">
    **Goal:** When the user is in the app, redirect their attention to the core feature.

    The IAM should include:

    1. A single, specific benefit tied to the core feature ("Set up your first goal in 60 seconds").
    2. A primary CTA that **deep-links** to the core feature screen.
    3. A dismiss action that doesn't re-show on the same session.

    Target the IAM at *Segment is "Core feature untouched"* AND *Last Session \< 24 hours* so it shows on the user's next visit while the moment is still fresh.
  </Step>

  <Step title="Push Notification: Core feature CTA">
    **Goal:** Catch the user when they're outside the app.

    Send a single push that deep-links to the core feature, no more than once per dormancy period. If they still haven't engaged after 7 more days, they fall into the inactivity track above naturally — don't double up.
  </Step>
</Steps>

## Win-back Journeys

Win-back targets users who have **already churned** — cancelled, lapsed, or expired — and aims to bring them back. The audience and goal are different from Retention: retention prevents churn for users still on a paid plan, while win-back recovers users who are no longer paying. Run them as separate Journeys with different exit conditions so a user can't sit in both at once.

Three principles drive the structure:

1. **Lead with value, not discount.** A "what you've been missing" message converts higher than a generic discount the first time. Reserve discounts for the second touch — discounting on day one trains users to cancel and wait for a coupon.
2. **Cap the active window.** Run win-back for 60 days post-cancellation, then exit users to a long-tail dormant list. Past 60 days, the unsubscribe risk outweighs the recovery upside.
3. **Differentiate by past value.** A high-LTV churned user (former VIP, long tenure, high spend) deserves a richer offer than a one-month trial that lapsed. Case 2 splits the cadence by `total_spend_cents` or tenure.

### Win-back configuration

**Entry rules:**

* **Case 1**: Built-in segment `account_type = "lapsed"`. Most billing pipelines flip the Tag from `paid` to `lapsed` on the cancellation date or at the end of the paid period.
* **Case 2**: Custom Event entry on `subscription_cancelled`, with a 7-day Wait before the first message. The 7-day buffer lets the immediate-regret cancellations pass — those users either resubscribe on their own or were never going to come back.

**Exit rules:**

* **Both cases**: Exit when `account_type` returns to `paid`, OR when `trial_started` or `subscription_renewed` Custom Event fires. Any of these mean the user is back; stop messaging.
* **Both cases**: Hard exit at 60 days post-entry. Configure as a final step or a Journey-level timeout — depending on your dashboard, this might be a `Wait: 60 days` followed by a Tag User step that adds `winback_completed = "1"` so the user can be excluded from re-entry.

**Re-entry rules:** Allow re-entry — a user who churns, returns, then churns again should re-enter the Journey on the new cancellation.

### Win-back templates

| Day | Channel | Purpose                                                                                                  |
| :-: | ------- | -------------------------------------------------------------------------------------------------------- |
|  7  | Email   | "Here's what you've been missing." Value reminder, no discount, no urgency.                              |
|  14 | Push    | One specific feature or content drop the user hasn't seen. Deep-link to it.                              |
|  30 | Email   | Return offer — first month at 50%, free trial extension, or feature unlock. First time discount appears. |
|  45 | Push    | Final low-key reminder of the offer. Use `{{ first_name \| default: 'there' }}` to personalize.          |
|  60 | (none)  | Hard exit. User flips to `winback_completed`.                                                            |

<Tabs>
  <Tab title="Case 1 – Basic">
    The Basic flow uses `account_type = "lapsed"` and a fixed 7 / 14 / 30 / 45 / 60-day cadence. Suitable for any app where your billing webhook updates `account_type` on cancellation.

    <Steps>
      <Step title="Entry: account_type = lapsed">
        **Goal:** Catch every lapsed user automatically the moment your billing pipeline flips the Tag.

        **Setup:** Built-in segment using the `account_type` Tag. Confirm your billing webhook fires reliably on the cancellation date or at the end of the paid period — without that, the Journey won't have an audience.
      </Step>

      <Step title="Wait: 7 days">
        **Goal:** Hold the first touch a week post-cancellation.

        Skipping the first week filters out immediate-regret cancellations and avoids the "we just got your cancellation" tone that reads as either tone-deaf or pushy.
      </Step>

      <Step title="Email: Day 7 — What you've been missing">
        **Goal:** A value reminder, no discount.

        Recap recent product updates, content drops, or feature releases since the user cancelled. Keep the tone neutral and informative — the user hasn't asked to be back yet.
      </Step>

      <Step title="Wait: 7 days (to Day 14)">
        **Goal:** Hold until the Day 14 push.
      </Step>

      <Step title="Push: Day 14 — Specific feature">
        **Goal:** Surface one feature or content drop tailored to the user's past usage.

        Deep-link directly to the relevant screen behind the auth wall — the user will hit a "log in or restart subscription" prompt, which is exactly the moment for an upgrade.
      </Step>

      <Step title="Wait: 16 days (to Day 30)">
        **Goal:** Hold until the offer touch.
      </Step>

      <Step title="Email: Day 30 — Return offer">
        **Goal:** First time the Journey introduces a discount or extension.

        Common offers: first month at 50%, two-week free trial extension, or a feature unlock. Whatever you choose, make the offer concrete, time-bound (e.g., expires in 14 days), and deep-link to a one-tap restart flow.
      </Step>

      <Step title="Wait: 15 days (to Day 45)">
        **Goal:** Hold until the final reminder.
      </Step>

      <Step title="Push: Day 45 — Final reminder">
        **Goal:** Low-key nudge that the offer is still available.

        "Your offer expires in `{{ days_remaining }}` days" works if your billing system supports a unique offer per user. Otherwise, a simple "We're still saving your spot" is fine.
      </Step>

      <Step title="Exit: 60 days or account_type = paid">
        **Goal:** Stop the Journey.

        Configure two exits:

        * **Conversion exit**: `account_type = "paid"` OR `subscription_renewed` event fires. The user is back; stop messaging.
        * **Timeout exit**: 60 days from entry. Set a `winback_completed = "1"` Tag in a Tag User step before exit so re-entry rules can exclude these users from accidental re-entry.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Case 2 – Advanced">
    Case 2 splits the cadence by past customer value. High-LTV churned users get a richer offer earlier; low-LTV users get the standard cadence. The structure is the same; the offer and channel mix differ.

    ##### Required data

    | Type            | Name                                     | Description                                                                                             |
    | --------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------- |
    | Tag (string)    | `account_type`                           | Set to `lapsed` on cancellation by your billing webhook. Drives entry.                                  |
    | Tag (integer)   | `total_spend_cents`                      | Lifetime value to date. Drives the high-LTV branch.                                                     |
    | Tag (timestamp) | `subscription_start_date`                | Used to compute tenure for tenure-based segmentation.                                                   |
    | Custom Event    | `subscription_cancelled`                 | Optional Journey entry event. Carry `cancel_reason` as a property if your billing platform captures it. |
    | Custom Event    | `subscription_renewed` / `trial_started` | Exit events for users who return on their own or via the Journey.                                       |

    ##### High-LTV vs standard branches

    After the Day-7 entry Wait, branch on `total_spend_cents` (or your equivalent LTV threshold):

    * **High-LTV branch** (`total_spend_cents > 5000` — adjust to your business): Day 7 personal email referencing tenure ("You were with us for `{{ tenure_months }}` months"). Day 14 push with a tier-specific concierge offer (priority support, free upgrade, account-manager outreach). Day 30 offer is more generous than the standard branch — e.g., 3 free months or a year-over-year price match.
    * **Standard branch** (`total_spend_cents <= 5000`): Identical to Case 1's cadence — Day 7 value email, Day 14 feature push, Day 30 offer, Day 45 reminder, Day 60 exit.

    ##### `cancel_reason`-aware copy

    If `subscription_cancelled` carries a `cancel_reason` property (e.g., `too_expensive`, `not_using`, `missing_feature`), branch the Day-7 email on that property:

    * `too_expensive`: Lead the Day-30 offer with the discount.
    * `not_using`: Day 7 leads with the most-valuable feature the user *did* use; Day 14 surfaces a feature drop.
    * `missing_feature`: Reference the feature directly. If it's now shipped, lead with that. If it isn't, route to a long-tail "we'll let you know when this ships" list and exit the standard win-back Journey early.

    See [Personalization with Custom Events](./personalization-custom-event) for the Liquid pattern.
  </Tab>
</Tabs>

<Tip>
  **Win-back rate is a lagging indicator.** A churned user who returns within 60 days is what most teams measure, but a user who returns 9 months later via a separate channel (paid acquisition, organic search, referral) is also a win-back success even though no Journey claims credit. Track both — the Journey-attributed win-back rate and the overall churned-cohort return rate at 90 / 180 / 365 days.
</Tip>

## FAQ

### Should I build all five Journeys at once?

No — sequence them by leverage and data readiness:

1. **Welcome Journey (Case 1)** first — highest leverage on long-term retention, requires no Custom Events.
2. **Retention Journey (Case 1)** once you have at least 30 days of session data so you can tune the inactivity threshold.
3. **Trial-to-paid conversion** as soon as `trial_end_date` is reliably set on every trial user.
4. **Win-back Journey** once your billing pipeline reliably flips `account_type` to `lapsed` on cancellation.
5. **Event-driven Journeys** (purchase, milestone, dunning) as your Custom Event tracking matures.

Each new Journey should reference the exit conditions of the others so users don't sit in two at once — see the next FAQ.

### How do I prevent a user from receiving overlapping Journeys?

Use exit conditions that map to Journey progression:

* **Welcome** exits when `core_feature_used = "1"` or `onboarding_completed`.
* **Trial-to-paid** exits when `trial_converted` or `account_type = "paid"`. Also exits on `subscription_cancelled` so cancelled trials don't keep getting reminders.
* **Retention** only enters when `Last Session > 7 days` AND `account_type` is `trial` or `paid`. Exits on app open or `subscription_cancelled`.
* **Win-back** only enters when `account_type = "lapsed"` (or on `subscription_cancelled` event). Exits on `account_type = "paid"`, `subscription_renewed`, or 60-day timeout.

Re-entry rules on Journey settings prevent the same user from re-entering an active flow. See [Re-entry rules](./journeys-settings#re-entry-rules).

### Can I build these Journeys without Custom Events or Tags?

Yes — the Case 1 versions of Welcome, Retention, and Win-back use only built-in segments (`First Session`, `Last Session`, `account_type`) and require no Custom Events. Trial-to-paid requires the `trial_end_date` Tag in both cases. Event-driven Journeys (purchase confirmation, milestones, dunning) all require Custom Events.

### Where should email warm-up fit in the rollout?

Before sending any Welcome or Retention email at scale on a new sending domain. See [Email warm-up](./email-warm-up). For double opt-in flows that confirm subscribers before adding them to your sending list, see [Set up confirmed opt-in for email](./double-opt-in-email).

### How frequently should I message users in onboarding?

A common starting point is one message per day for the first 3 days, then drop to every 2–3 days. Watch unsubscribe rate and push opt-out rate at each step — those tell you sooner than open rate whether you're being too aggressive.

### Do I need to use all three channels (push, email, SMS)?

No. Push and in-app are the foundation for mobile-first. Email layers in for consenting users when you have longer-form content (welcome, weekly digest, conversion). SMS is reserved for urgent, high-intent moments. Most apps run effectively on push + email.

## Related pages

<Columns>
  <Card title="Mobile-first strategy" icon="mobile" href="./mobile-first">
    Set up External IDs, Tags, and segments that power lifecycle Journeys.
  </Card>

  <Card title="Event-driven Journeys" icon="bolt" href="./event-driven-journeys">
    Three end-to-end patterns for translating real behavior into automation.
  </Card>

  <Card title="Welcome Journey: Mobile gaming" icon="gamepad" href="./welcome-journey-mobile-gaming">
    Worked example of a 7-day onboarding Journey with both basic and advanced data paths.
  </Card>

  <Card title="Set up confirmed opt-in for email" icon="envelope-circle-check" href="./double-opt-in-email">
    Implement double opt-in to protect deliverability before email blasts.
  </Card>

  <Card title="Email warm-up" icon="envelope" href="./email-warm-up">
    Ramp volume on a new sending domain without hurting deliverability.
  </Card>

  <Card title="Segments" icon="users" href="./segmentation">
    Group users by shared characteristics to target Journeys.
  </Card>
</Columns>


# Mobile SDK reference
Source: https://documentation.onesignal.com/docs/en/mobile-sdk-reference

Comprehensive API reference for the OneSignal Mobile SDK, including initialization, user identity, subscriptions, tags, permissions, in-app messages, live activities, and more. Supports Android, iOS, Unity, React Native, Flutter, and Cordova/Ionic platforms.

## Setup & debugging

These methods are a reference for integrating the OneSignal SDK into your app. For full platform-specific setup instructions, see [Mobile SDK setup](./mobile-sdk-setup).

### `initialize()`

Initializes the OneSignal SDK. This should be called during application startup. The `ONESIGNAL_APP_ID` can be found in [Keys & IDs](./keys-and-ids).

<Note>
  If you want to delay initialization of the OneSignal SDK, we recommend using our [Privacy methods](#privacy).
</Note>

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.initWithContext(this, ONESIGNAL_APP_ID)
  ```

  ```java Java theme={null}
  OneSignal.initWithContext(this, ONESIGNAL_APP_ID);
  ```

  ```swift Swift theme={null}
  import OneSignalFramework

  OneSignal.initialize("ONESIGNAL_APP_ID", withLaunchOptions: launchOptions)
  ```

  ```objectivec Objective-C theme={null}
  #import <OneSignalFramework/OneSignalFramework.h>

  [OneSignal initialize:@"ONESIGNAL_APP_ID" withLaunchOptions:launchOptions];
  ```

  ```csharp C# theme={null}
  OneSignal.Initialize("ONESIGNAL_APP_ID");
  ```

  ```javascript React Native theme={null}
  OneSignal.initialize("ONESIGNAL_APP_ID");
  ```

  ```dart Flutter theme={null}
  OneSignal.initialize("ONESIGNAL_APP_ID");
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.initialize("ONESIGNAL_APP_ID");

  // Cordova
  window.plugins.OneSignal.initialize("ONESIGNAL_APP_ID");
  ```
</CodeGroup>

### `setLogLevel()`

Set the logging to print additional logs to Android LogCat or Xcode logs.
Call this *before* initializing OneSignal. See [Getting a Debug Log](./capturing-a-debug-log) for more details.

Log levels (least to most verbose): `None` | `Fatal` | `Error` | `Warn` | `Info` | `Debug` | `Verbose`. Cordova/Ionic uses integers `0`–`6`.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.Debug.logLevel = LogLevel.Verbose
  ```

  ```java Java theme={null}
  OneSignal.getDebug().setLogLevel(OneSignal.LOG_LEVEL.VERBOSE);
  ```

  ```swift Swift theme={null}
  OneSignal.Debug.setLogLevel(.LL_VERBOSE)
  ```

  ```objc Objective-C theme={null}
  [OneSignal.Debug setLogLevel:ONE_S_LL_VERBOSE];
  ```

  ```csharp C# theme={null}
  OneSignal.Debug.LogLevel = LogLevel.Verbose;
  ```

  ```javascript React Native theme={null}
  OneSignal.Debug.setLogLevel(LogLevel.Verbose);
  ```

  ```dart Flutter theme={null}
  OneSignal.Debug.setLogLevel(OSLogLevel.verbose);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.Debug.setLogLevel(6);

  // Cordova
  window.plugins.OneSignal.Debug.setLogLevel(6);
  ```
</CodeGroup>

### `setAlertLevel()`

Sets the logging level to show as alert dialogs in your app. Make sure to remove this before submitting to the app store.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.Debug.alertLevel = LogLevel.Exception
  ```

  ```java Java theme={null}
  OneSignal.getDebug.setAlertLevel(LogLevel.Exception);
  ```

  ```swift Swift theme={null}
  OneSignal.Debug.setAlertLevel(.LL_NONE)
  ```

  ```objc Objective-C theme={null}
  [OneSignal.Debug setAlertLevel:ONE_S_LL_NONE];
  ```

  ```csharp C# theme={null}
  OneSignal.Debug.AlertLevel = LogLevel.None;
  ```

  ```javascript React Native theme={null}
  OneSignal.Debug.setAlertLevel(LogLevel.Verbose);
  ```

  ```dart Flutter theme={null}
  OneSignal.Debug.setAlertLevel(OSLogLevel.none);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.Debug.setAlertLevel(0);

  // Cordova
  window.plugins.OneSignal.Debug.setAlertLevel(0);
  ```
</CodeGroup>

## User identity & properties

When users open your app, OneSignal automatically creates a OneSignal ID ([User-level ID](./users) ID) and a Subscription ID ([device-level ID](./subscriptions)). You can associate multiple Subscriptions (e.g., devices, emails, phone numbers) with a single user by calling `login()` with your unique user identifier.

### `login(external_id)`

Links the current device (mobile Subscription) to a known user identified `external_id`. Call this only for **identified users** (after sign-in or session restore). For anonymous users, rely on the automatically assigned `onesignal_id` (see [User State `addObserver()`](#addeventlistener-user-state)).

**If the `external_id` already exists:** the SDK switches to the existing user, links the current mobile Subscription to it, and discards any anonymous data (tags, session data, email/SMS Subscriptions). A `409 Conflict` log is expected and can be ignored.

**If the `external_id` does not exist:** a new user is created with the current `onesignal_id`, retaining all anonymous data.

<Note>
  The SDK retries automatically on network failures. Call `login(external_id)` **every time the app starts** once the user's ID is known, and again on account switches.
</Note>

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.login("external_id")
  ```

  ```java Java theme={null}
  OneSignal.login("external_id");
  ```

  ```swift Swift theme={null}
  OneSignal.login("external_id")
  ```

  ```objc Objective-C theme={null}
  [OneSignal login:@"external_id"];
  ```

  ```csharp C# theme={null}
  OneSignal.Login("external_id");
  ```

  ```javascript React Native theme={null}
  OneSignal.login("external_id");
  ```

  ```dart Flutter theme={null}
  OneSignal.login("external_id");
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.login("external_id");

  // Cordova
  window.plugins.OneSignal.login("external_id");
  ```
</CodeGroup>

### `logout()`

Unlinks the current user from the mobile Subscription.

* Removes the `external_id` from the current mobile Subscription. Does not remove the `external_id` from other Subscriptions.
* Resets the `onesignal_id` to a new anonymous user.
* Any new data (e.g tags, Subscriptions, session data, etc.) will now be set on the new anonymous user until they are identified with the `login` method.

<Note>Use this when a user signs out of your app and you do not want to send targeted transactional messages to the device anymore.</Note>

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.logout()
  ```

  ```java Java theme={null}
  OneSignal.logout();
  ```

  ```swift Swift theme={null}
  OneSignal.logout()
  ```

  ```objc Objective-C theme={null}
  [OneSignal logout]
  ```

  ```csharp C# theme={null}
  OneSignal.Logout();
  ```

  ```javascript React Native theme={null}
  OneSignal.logout();
  ```

  ```dart Flutter theme={null}
  OneSignal.logout();
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.logout();

  // Cordova
  window.plugins.OneSignal.logout();
  ```
</CodeGroup>

### `getOnesignalId()`

Returns the current user-level `onesignal_id` from local device storage. It may return `null` before the SDK finishes initializing; use the [User State `addObserver()`](#addeventlistener-user-state) instead to reliably get the `onesignal_id` and react to changes.

<Warning> Do not persist the OneSignal ID as a permanent user identifier. It can change when users log in, log out, or switch accounts. </Warning>

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val onesignalId = OneSignal.User.onesignalId
  ```

  ```java Java theme={null}
  String onesignalId = OneSignal.getUser().getOnesignalId();
  ```

  ```swift Swift theme={null}
  let onesignalId = OneSignal.User.onesignalId
  ```

  ```objc Objective-C theme={null}
  NSString* onesignalId = OneSignal.User.onesignalId
  ```

  ```csharp C# theme={null}
  string onesignalId = OneSignal.User.OnesignalId;
  ```

  ```javascript React Native theme={null}
  const onesignalId = await OneSignal.User.getOnesignalId();
  ```

  ```dart Flutter theme={null}
  final onesignalId = await OneSignal.User.getOnesignalId();
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  const onesignalId = await OneSignal.User.getOnesignalId();

  // Cordova
  const onesignalId = await window.plugins.OneSignal.User.getOnesignalId();
  ```
</CodeGroup>

### `getExternalId()`

Returns the current user-level `external_id` from local device storage. It may return `null` if not set via the `login` method or called before user state is initialized.

<CodeGroup>
  ```kotlin Kotlin theme={null}
    val externalId = OneSignal.User.externalId
  ```

  ```java Java theme={null}
  String externalId = OneSignal.getUser().getExternalId();
  ```

  ```swift Swift theme={null}
  let externalId: String? = OneSignal.User.externalId
  ```

  ```objc Objective-C theme={null}
  NSString* externalId = OneSignal.User.externalId
  ```

  ```csharp C# theme={null}
  string externalId = OneSignal.User.ExternalId;
  ```

  ```javascript React Native theme={null}
  const externalId = await OneSignal.User.getExternalId();
  ```

  ```dart Flutter theme={null}
  final externalId = await OneSignal.User.getExternalId();
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  const externalId = await OneSignal.User.getExternalId();

  // Cordova
  const externalId = await window.plugins.OneSignal.User.getExternalId();
  ```
</CodeGroup>

### `addEventListener()` *User State*

Listen for changes in the user context (e.g., login, logout, ID assignment).

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.User.addObserver(object : IUserStateObserver {
      override fun onUserStateChange(state: UserChangedState) {
          println("User State Changed: onesignalId=${state.current.onesignalId}, externalId=${state.current.externalId}")
      }
  })
  ```

  ```java Java theme={null}
  OneSignal.getUser().addObserver(userChangedState -> {
  	Log.d("User State Changed", String.valueof(userChangedState.toJSONObject()));
  });
  ```

  ```swift Swift theme={null}
  // AppDelegate.swift
  // Add OSUserStateObserver after UIApplicationDelegate
  class AppDelegate: UIResponder, UIApplicationDelegate, OSUserStateObserver {

      func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
          // Add your AppDelegate as an observer
          OneSignal.User.addObserver(self)
      }

      // Add this new method
      func onUserStateDidChange(state: OSUserChangedState) {
          // prints out all properties
          print("OSUserChangedState: \n\(state.jsonRepresentation())")
          print(state.current.externalId)
          print(state.current.onesignalId)
      }
  }

  // Remove the observer
  OneSignal.User.removeObserver(self)
  ```

  ```objc Objective-C theme={null}
  // AppDelegate.h
  // Add OSUserStateObserver after UIApplicationDelegate
  @interface AppDelegate : UIResponder <UIApplicationDelegate, OSUserStateObserver>
  @end

  // AppDelegate.m
  @implementation AppDelegate

  - (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      // Add your AppDelegate as an observer
      [OneSignal.User addObserver:self];
  }

  // Add this new method
  - (void)onUserStateDidChangeWithState:(OSUserChangedState * _Nonnull)state {
      // prints out all properties
      NSLog(@"OSUserChangedState:\n%@", [state jsonRepresentation]);
      NSLog(@"current externalId: %@", state.current.externalId);
      NSLog(@"current onesignalId: %@", state.current.onesignalId);
  }
  @end

  // Remove the observer
  [OneSignal.User removeObserver:self];
  ```

  ```csharp C# theme={null}
  OneSignal.User.Changed += _userStateChanged;

  private void _userStateChanged(object sender, UserStateChangedEventArgs e) {
      ...
  }
  ```

  ```javascript React Native theme={null}
  const listener = (event: UserChangedState) => {
      console.log("User changed: " + (event));
  };

  OneSignal.User.addEventListener("change", listener);
  // Remove the listener
  OneSignal.User.removeEventListener("change", listener);
  ```

  ```dart Flutter theme={null}
  OneSignal.User.addObserver((state) {
  	var userState = state.jsonRepresentation();
      print('OneSignal user changed: $userState');
  });

  /// Remove a user state observer that has been previously added.
  OneSignal.User.removeObserver(observer);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  const listener = (event: UserChangedState) => {
      console.log("User changed: " + (event));
  };
  OneSignal.User.addEventListener("change", listener);
  // Remove the listener
  OneSignal.User.removeEventListener("change", listener);

  // Cordova
  window.plugins.OneSignal.User.addEventListener("change", listener);
  window.plugins.OneSignal.User.removeEventListener("change", listener);
  ```
</CodeGroup>

### `addAlias()`, `addAliases()`, `removeAlias()`, `removeAliases()`

[Aliases](./aliases) are alternative identifiers (like usernames or CRM IDs). Set `external_id` with `login()` before adding aliases. Aliases added without an `external_id` will not sync across multiple Subscriptions.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  // Add a single alias
  OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID")

  // Add multiple aliases
  var aliases = mapOf("ALIAS_LABEL_01" to "ALIAS_ID_01", "ALIAS_LABEL_02" to "ALIAS_ID_02")
  OneSignal.User.addAliases(aliases)

  // Remove a single alias
  OneSignal.User.removeAlias("ALIAS_LABEL")

  // Remove multiple aliases
  OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"])
  ```

  ```java Java theme={null}
  // Add a single alias
  OneSignal.getUser().addAlias("ALIAS_LABEL", "ALIAS_ID");

  // Add multiple aliases
  HashMap<String, String> aliases = new HashMap<String, String>();
  aliases.put("ALIAS_LABEL_01", "ALIAS_ID_01");
  aliases.put("ALIAS_LABEL_02", "ALIAS_ID_02");
  OneSignal.getUser().addAliases(aliases);

  // Remove a single alias
  OneSignal.getUser().removeAlias("ALIAS_LABEL")

  // Remove multiple aliases
  HashSet<String> labels = new HashSet<String>();
  labels.add("ALIAS_LABEL_01");
  labels.add("ALIAS_LABEL_02");
  OneSignal.getUser().removeAliases(labels);
  ```

  ```swift Swift theme={null}
  // Add a single alias
  OneSignal.User.addAlias(label: "ALIAS_LABEL", id: "ALIAS_ID")

  // Add multiple aliases
  OneSignal.User.addAliases(["ALIAS_LABEL_01": "ALIAS_ID_01", "ALIAS_LABEL_02": "ALIAS_ID_02"])

  // Remove a single alias
  OneSignal.User.removeAlias("ALIAS_LABEL")

  // Remove multiple aliases
  OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"])
  ```

  ```objc Objective-C theme={null}
  // Add a single alias
  [OneSignal.User addAliasWithLabel:@"ALIAS_LABEL" id:@"ALIAS_ID"];

  // Add multiple aliases
  [OneSignal.User addAliases:@{@"ALIAS_LABEL_01": @"ALIAS_ID_01", @"ALIAS_LABEL_02": @"ALIAS_ID_02"}]

  // Remove a single alias
  [OneSignal.User removeAlias:@"ALIAS_LABEL"]

  // Remove multiple aliases
  [OneSignal.User removeAliases:@[@"ALIAS_LABEL_01", @"ALIAS_LABEL_02"]]
  ```

  ```csharp C# theme={null}
  // Add a single alias
  OneSignal.User.AddAlias("ALIAS_LABEL", "ALIAS_ID");

  // Add multiple aliases
  OneSignal.User.AddAliases(new Dictionary<string, string> {
    { "ALIAS_LABEL_01", "ALIAS_ID_01" },
    { "ALIAS_LABEL_02", "ALIAS_ID_02" }
  });

  // Remove a single alias
  OneSignal.User.RemoveAlias("ALIAS_LABEL");

  // Remove multiple aliases
  OneSignal.User.RemoveAliases(new[] {"ALIAS_LABEL_01", "ALIAS_LABEL_02"});
  ```

  ```javascript React Native theme={null}
  // Add a single alias
  OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

  // Add multiple aliases
  OneSignal.User.addAliases({ALIAS_LABEL_01: "ALIAS_ID_01", ALIAS_LABEL_02: "ALIAS_ID_02"});

  // Remove a single alias
  OneSignal.User.removeAlias("ALIAS_LABEL");

  // Remove multiple aliases
  OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]);
  ```

  ```dart Flutter theme={null}
  // Add a single alias
  OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

  // Add multiple aliases
  var aliases = <String, String>{
    "alias_key_1": "alias_id_1",
    "alias_key_2": "alias_id_2"
  };
  OneSignal.User.addAliases(aliases);

  // Remove a single alias
  OneSignal.User.removeAlias("ALIAS_LABEL");

  // Remove multiple aliases
  var aliases = <String>["alias_key_1", "alias_key_2"];
  OneSignal.User.removeAliases(aliases);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Add a single alias - Ionic
  OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");
  // Add a single alias - Cordova
  window.plugins.OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

  // Add multiple aliases - Ionic
  OneSignal.User.addAliases({ALIAS_LABEL_01: "ALIAS_ID_01", ALIAS_LABEL_02: "ALIAS_ID_02"});
  // Add multiple aliases - Cordova
  window.plugins.OneSignal.User.addAliases({ALIAS_LABEL_01: "ALIAS_ID_01", ALIAS_LABEL_02: "ALIAS_ID_02"});

  // Remove a single alias - Ionic
  OneSignal.User.removeAlias("ALIAS_LABEL");
  // Remove a single alias - Cordova
  window.plugins.OneSignal.User.removeAlias("ALIAS_LABEL");

  // Remove multiple aliases - Ionic
  OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]);
  // Remove multiple aliases - Cordova
  window.plugins.OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]);
  ```
</CodeGroup>

### `setLanguage()`

Overrides the auto-detected language of the user. Use [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes?useskin=vector) language code.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.User.setLanguage("en")
  ```

  ```java Java theme={null}
  OneSignal.getUser().setLanguage("en");
  ```

  ```swift Swift theme={null}
  OneSignal.User.setLanguage("en")
  ```

  ```objc Objective-C theme={null}
  [OneSignal.User setLanguage:@"en"]
  ```

  ```csharp C# theme={null}
  OneSignal.User.Language = "en";
  ```

  ```javascript React Native theme={null}
  OneSignal.User.setLanguage("en");
  ```

  ```dart Flutter theme={null}
  OneSignal.User.setLanguage("en");
  ```

  ```javascript Cordova/Ionic theme={null}
  window.plugins.OneSignal.User.setLanguage("en");
  ```
</CodeGroup>

***

## Custom events

Track user actions with associated properties. See [Custom Events](./custom-events) for more details.

<Note>
  Custom events require the following minimum SDK versions: iOS `5.4.0`, Android `5.6.1`, React Native `5.3.0`, Flutter `5.4.0`, Unity `5.2.0`.
</Note>

Track and send a custom event performed by the current user.

* `name` - **Required.** The name of the event as a string.
* `properties` - **Optional.** Key-value pairs to add to the event. The properties dictionary or map must be serializable into a valid JSON Object. Supports nested values.

The SDK automatically includes app-specific data under the reserved `os_sdk` key in the properties payload (e.g., `os_sdk.device_type`).

<Accordion title="Example os_sdk payload">
  ```json theme={null}
  { 
    "os_sdk": { 
      "sdk": "050213", 
      "device_os": "18.5", 
      "type": "iOSPush", 
      "device_model": "iPhone14,4", 
      "device_type": "ios", 
      "app_version": "5.4.0" 
    }
  }
  ```
</Accordion>

### `trackEvent()`

See [Custom Events](./custom-events) for more details.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.User.trackEvent("my_event_name")

  OneSignal.User.trackEvent(
     name = "started_free_trial",
     properties = mapOf(
         "promo_code" to "NEW50",
         "membership_details" to mapOf(
             "vip" to true,
             "products_viewed_count" to 15
         )
     )
  )
  ```

  ```java Java theme={null}
  OneSignal.getUser().trackEvent("my_event_name", null);

  Map<String, Object> membershipDetails = new HashMap<>();
  membershipDetails.put("vip", true);
  membershipDetails.put("products_viewed_count", 15);

  Map<String, Object> properties = new HashMap<>();
  properties.put("promo_code", "NEW50");
  properties.put("membership_details", membershipDetails);

  OneSignal.getUser().trackEvent("started_free_trial", properties);
  ```

  ```swift Swift theme={null}
  OneSignal.User.trackEvent(name: "my_event_name", properties: nil)

  let myProperties = [
    "promo_code": "NEW50",
    "membership_details": [
      "vip": true,
      "products_viewed_count": 15
    ]
  ]
  OneSignal.User.trackEvent(name: "started_free_trial", properties: myProperties)
  ```

  ```objc Objective-C theme={null}
  [OneSignal.User trackEventWithName:@"my_event_name" properties:nil];

  NSDictionary *myProperties = @{
    @"promo_code" : @"NEW50",
    @"membership_details" : @{
      @"vip" : @true,
      @"products_viewed_count" : @15
    } 
  };
  [OneSignal.User trackEventWithName:@"started_free_trial" properties:myProperties];
  ```

  ```csharp Unity C# theme={null}
  OneSignal.User.TrackEvent("my_event_name");

  OneSignal.User.TrackEvent("started_free_trial", new Dictionary<string, object> {
      { "promo_code", "NEW50" },
      { "membership_details", new Dictionary<string, object> {
          { "vip", true },
          { "products_viewed_count", 15 }
      }}
  });
  ```

  ```javascript React Native theme={null}
  OneSignal.User.trackEvent("my_event_name")

  OneSignal.User.trackEvent("started_free_trial", {
    "promo_code": "NEW50",
    "membership_details": {
      "vip": true,
      "products_viewed_count": 15 
    }
  })
  ```

  ```dart Flutter theme={null}
  OneSignal.User.trackEvent("my_event_name")

  OneSignal.User.trackEvent("started_free_trial", {
    "promo_code": "NEW50",
    "membership_details": {
      "vip": true,
      "products_viewed_count": 15 
    }
  })
  ```

  ```javascript Cordova/Ionic theme={null}
  OneSignal.User.trackEvent("my_event_name")

  OneSignal.User.trackEvent("started_free_trial", {
    "promo_code": "NEW50",
    "membership_details": {
      "vip": true,
      "products_viewed_count": 15 
    }
  })
  ```
</CodeGroup>

## Tags

Tags are custom `key : value` pairs of string data you set on users based on events or user properties. See [Tags](./add-user-data-tags) for more details.

### `addTag()`, `addTags()`

Set a single or multiple tags on the current user.

* Values will be replaced if the key already exists.
* Exceeding your plan's tag limit will cause the operations to fail silently.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.User.addTag("KEY", "VALUE")

  OneSignal.User.addTags(mapOf("KEY_01" to "VALUE_01", "KEY_02" to "VALUE_02"))
  ```

  ```java Java theme={null}
  OneSignal.getUser().addTag("KEY", "VALUE");

  OneSignal.getUser().addTags(new HashMap<String, String>() {{
    put("KEY_01", "VALUE_01");
    put("KEY_02", "VALUE_02");
  }});
  ```

  ```swift Swift theme={null}
  OneSignal.User.addTag(key: "KEY", value: "VALUE")

  OneSignal.User.addTags(["KEY_01": "VALUE_01", "KEY_02": "VALUE_02"])
  ```

  ```objc Objective-C theme={null}
  [OneSignal.User addTag:@"KEY" value:@"VALUE"];

  [OneSignal.User addTags:@{@""KEY_01"": @""VALUE_01"", @""KEY_02"": @""VALUE_02""}];
  ```

  ```csharp C# theme={null}
  OneSignal.User.AddTag("KEY", "VALUE");

  OneSignal.User.AddTags(new Dictionary<string, string> {
    { "KEY_01", "VALUE_01" },
    { "KEY_02", "VALUE_02" }
  });
  ```

  ```javascript React Native theme={null}
  OneSignal.User.addTag('KEY', 'VALUE');

  OneSignal.User.addTags({my_tag1: 'my_value', my_tag2: 'my_value2'});
  ```

  ```dart Flutter theme={null}
  OneSignal.User.addTagWithKey("KEY", "VALUE");

  var tags = {'test': 'value', 'test2': 'value2'};
  OneSignal.User.addTags(tags);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.User.addTag("KEY", "VALUE");

  OneSignal.User.addTags({"KEY_01": "VALUE_01", "KEY_02": "VALUE_02"});

  // Cordova
  window.plugins.OneSignal.User.addTag("KEY", "VALUE");

  window.plugins.OneSignal.User.addTags({"KEY_01": "VALUE_01", "KEY_02": "VALUE_02"});
  ```
</CodeGroup>

### `removeTag()`, `removeTags()`

Delete a single or multiple tags from the current user.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.User.removeTag("KEY")

  OneSignal.User.removeTags(listOf("KEY_01", "KEY_02"))
  ```

  ```java Java theme={null}
  OneSignal.getUser().removeTag("KEY");

  OneSignal.getUser().removeTags(Arrays.asList("KEY_01", "KEY_02"));
  ```

  ```swift Swift theme={null}
  OneSignal.User.removeTag("KEY")

  OneSignal.User.removeTags(["KEY_01", "KEY_02"])
  ```

  ```objc Objective-C theme={null}
  [OneSignal.User removeTag:@"KEY"];

  [OneSignal.User removeTags:@[@""KEY_01"", @""KEY_02""]]
  ```

  ```csharp C# theme={null}
  OneSignal.User.RemoveTag("KEY");

  OneSignal.User.RemoveTags(new string[] { "KEY_01", "KEY_02" });
  ```

  ```javascript React Native theme={null}
  OneSignal.User.removeTag('my_tag1');

  OneSignal.User.removeTags(['my_tag1', 'my_tag2']);
  ```

  ```dart Flutter theme={null}
  OneSignal.User.removeTag("test");

  OneSignal.User.removeTags(["test", "test2"]);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.User.removeTag("KEY");

  OneSignal.User.removeTags(["KEY_01", "KEY_02"]);

  // Cordova
  window.plugins.OneSignal.User.removeTag("KEY");

  window.plugins.OneSignal.User.removeTags(["KEY_01", "KEY_02"]);
  ```
</CodeGroup>

### `getTags()`

Returns the local copy of the user's tags. Tags are updated from the server during `login()` or new app sessions.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val tags: Map<String, String> = OneSignal.User.getTags()
  ```

  ```java Java theme={null}
  Map<String, String> tags = OneSignal.getUser().getTags();
  ```

  ```swift Swift theme={null}
  let tags = OneSignal.User.getTags()
  ```

  ```objc Objective-C theme={null}
  NSDictionary<NSString*, NSString*> *tags = [OneSignal.User getTags]
  ```

  ```csharp C# theme={null}
  Dictionary<string, string> tags = OneSignal.User.GetTags();
  ```

  ```javascript React Native theme={null}
  const getTags = async () => {
      const tags = await OneSignal.User.getTags();
      console.log('Tags:', tags);
  };
  ```

  ```dart Flutter theme={null}
  const getTags = async () async {
      final tags = await OneSignal.User.getTags();
      print('Tags: $tags');
  };
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  const getTags = async () => {
      const tags = await OneSignal.User.getTags();
      console.log('Tags:', tags);
  };
  // Cordova
  const getTags = async () => {
      const tags = await window.plugins.OneSignal.User.getTags();
      console.log('Tags:', tags);
  };
  ```
</CodeGroup>

***

## Privacy

### `setConsentRequired()`

Enforces user consent before data collection begins. Must be called **before initializing the SDK**.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.consentRequired = true
  ```

  ```java Java theme={null}
  OneSignal.setConsentRequired(true);
  ```

  ```swift Swift theme={null}
  OneSignal.setConsentRequired(true)
  ```

  ```objc Objective-C theme={null}
  [OneSignal setConsentRequired:true];
  ```

  ```csharp C# theme={null}
  OneSignal.ConsentRequired = true;
  ```

  ```javascript React Native theme={null}
  OneSignal.setConsentRequired(true);
  ```

  ```dart Flutter theme={null}
  OneSignal.consentRequired(true);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.setConsentRequired(true);
  // Cordova
  window.plugins.OneSignal.setConsentRequired(true);
  ```
</CodeGroup>

### `setConsentGiven()`

Grants or revokes user consent for data collection. Without consent, no data is sent to OneSignal and no subscription is created.

* If [`setConsentRequired()`](#setconsentrequired) is `true`, our SDK will not be fully enabled until `setConsentGiven` is called with `true`.
* If `setConsentGiven` is set to `true` and a Subscription is created, then later it is set to `false`, that Subscription will no longer receive updates. The current data for that Subscription remains unchanged until `setConsentGiven` is set to `true` again.
* If you want to delete the User and/or Subscription data, use our [Delete user](/reference/delete-user) or [Delete subscription](/reference/delete-subscription) APIs.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.consentGiven = true
  ```

  ```java Java theme={null}
  OneSignal.setConsentGiven(true);
  ```

  ```swift Swift theme={null}
  OneSignal.setConsentGiven(true)
  ```

  ```objc Objective-C theme={null}
  [OneSignal setConsentGiven:true];
  ```

  ```csharp C# theme={null}
  OneSignal.ConsentGiven = true;
  ```

  ```javascript React Native theme={null}
  OneSignal.setConsentGiven(true);
  ```

  ```dart Flutter theme={null}
  OneSignal.consentGiven(true);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.setConsentGiven(true);
  // Cordova
  window.plugins.OneSignal.setConsentGiven(true);
  ```
</CodeGroup>

***

## Location

Tracking location points requires 3 steps:

1. Add location tracking permissions and dependencies to your app.

* **iOS**: [Choosing the Location Services Authorization to Request developer guide](https://developer.apple.com/documentation/bundleresources/choosing-the-location-services-authorization-to-request)
* **Android**: [Request location permissions developer guide](https://developer.android.com/develop/sensors-and-location/location/permissions)

You may get the following errors:

> LocationManager.startGetLocation: not possible, no location dependency found

Check your App's dependencies. A common solutions is in you `app/build.gradle` add: `implementation 'com.google.android.gms:play-services-location:21.0.1'`

2. Enable your app to share location with OneSignal using the `Location.setShared()` method.
3. Request permission from the user for location tracking with the `Location.requestPermission` method or [use in-app messages](./location-opt-in-prompt).

### `setShared()` *Location*

Enables or checks whether the SDK is sharing the Subscription's latitude and longitude with OneSignal. Set proper [location permissions](#location) first.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.Location.isShared = true

  var isShared: Boolean = OneSignal.isShared
  ```

  ```java Java theme={null}
  OneSignal.getLocation().setShared(true);

  boolean isShared = OneSignal.Location.isShared();
  ```

  ```swift Swift theme={null}
  OneSignal.Location.isShared = true

  let locationShared = OneSignal.Location.isShared
  ```

  ```objc Objective-C theme={null}
  [OneSignal.Location setShared:true];

  BOOL locationShared = [OneSignal isLocationShared];
  ```

  ```csharp C# theme={null}
  OneSignal.Location.IsShared = true;

  bool isShared = OneSignal.Location.IsShared;
  ```

  ```javascript React Native theme={null}
  OneSignal.Location.setShared(true);

  OneSignal.Location.isShared();
  ```

  ```dart Flutter theme={null}
  OneSignal.Location.setShared(true);

  OneSignal.Location.isShared();
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.Location.setShared(true);

  OneSignal.Location.isShared(isShared => {
    console.log("Location shared: ", isShared);
  });

  // Cordova
  window.plugins.OneSignal.Location.setShared(true);

  window.plugins.OneSignal.Location.isShared(isShared => {
    console.log("Location shared: ", isShared);
  });
  ```
</CodeGroup>

### `requestPermission()` *Location*

Displays the system-level location permission prompt. Alternatively, [use in-app messages](./location-opt-in-prompt). Requires proper [location permissions](#location) and `setShared(true)`.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.Location.requestPermission(true)
  ```

  ```java Java theme={null}
  import com.onesignal.Continue

  OneSignal.getLocation().requestPermission(Continue.with(result -> {
      if (result.isSuccess()) {
          Boolean granted = result.getData();
          // act on granted
      } else {
          Throwable t = result.getThrowable();
          // log, fallback, etc.
      }
  }));
  ```

  ```swift Swift theme={null}
  OneSignal.Location.requestPermission()
  ```

  ```objc Objective-C theme={null}
  [OneSignal.Location requestPermission];
  ```

  ```csharp C# theme={null}
  OneSignal.Location.RequestPermission();
  ```

  ```javascript React Native theme={null}
  OneSignal.Location.requestPermission();
  ```

  ```dart Flutter theme={null}
  OneSignal.Location.requestPermission();
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.Location.requestPermission();

  // Cordova
  window.plugins.OneSignal.Location.requestPermission();
  ```
</CodeGroup>

***

## Subscriptions

A Subscription represents a single messaging channel instance (for example, a mobile device) and has a unique Subscription ID (OneSignal's device-level ID). A user can have multiple Subscriptions across devices and platforms.

See [Subscriptions](./subscriptions) for more details.

### `User.pushSubscription.id`

Returns the current device-level `subscription_id` from local device storage. It may return `null` before the SDK finishes initializing; use the [Push Subscription `addObserver()`](#addobserver-push-subscription-changes) instead to reliably get the `subscription_id` and react to changes.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val subscriptionId = OneSignal.User.pushSubscription.id
  ```

  ```java Java theme={null}
  String subscriptionId = OneSignal.getUser().getPushSubscription().getId();
  ```

  ```swift Swift theme={null}
  let subscriptionId: String? = OneSignal.User.pushSubscription.id
  ```

  ```objc Objective-C theme={null}
  NSString* subscriptionId = OneSignal.User.pushSubscription.id
  ```

  ```csharp C# theme={null}
  string subscriptionId = OneSignal.User.PushSubscription.Id;
  ```

  ```javascript React Native theme={null}
  const subscriptionId = await OneSignal.User.pushSubscription.getIdAsync();
  ```

  ```dart Flutter theme={null}
  final subscriptionId = await OneSignal.User.pushSubscription.id;
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  const subscriptionId = await OneSignal.User.pushSubscription.getIdAsync();

  // Cordova
  const subscriptionId = await window.plugins.OneSignal.User.pushSubscription.getIdAsync();
  ```
</CodeGroup>

### `User.pushSubscription.token`

Returns the current device-level push subscription `token` from local device storage. It may return `null` before the SDK finishes initializing or the token isn't available yet; use the [Push Subscription `addObserver()`](#addobserver-push-subscription-changes) instead to reliably get the `token` and react to changes.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val pushToken = OneSignal.User.pushSubscription.token
  ```

  ```java Java theme={null}
  String pushToken = OneSignal.getUser().getPushSubscription().getToken();
  ```

  ```swift Swift theme={null}
  let token: String? = OneSignal.User.pushSubscription.token
  ```

  ```objc Objective-C theme={null}
  NSString* token = OneSignal.User.pushSubscription.token
  ```

  ```csharp C# theme={null}
  OneSignal.User.PushSubscription.Token;
  ```

  ```javascript React Native theme={null}
  await OneSignal.User.pushSubscription.getTokenAsync();
  ```

  ```dart Flutter theme={null}
  OneSignal.User.pushSubscription.token;
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  await OneSignal.User.pushSubscription.getTokenAsync();

  // Cordova
  await window.plugins.OneSignal.User.pushSubscription.getTokenAsync();
  ```
</CodeGroup>

### `addObserver()` *Push Subscription Changes*

Use this method to respond to mobile Subscription changes like:

* The device receives a new push token from Google (FCM) or Apple (APNs)
* OneSignal assigns a subscription ID
* The `optedIn` value changes (e.g. called `optIn()` or `optOut()`)
* The user toggles push permission in system settings, then opens the app

When this happens, the SDK triggers the `onPushSubscriptionChange` event. Your listener receives a state object with the `previous` and `current` values so you can detect exactly what changed.

To stop listening for updates, call the associated `removeObserver()` or `removeEventListener()` method.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  class MyObserver : IPushSubscriptionObserver {
    init {
      OneSignal.User.pushSubscription.addObserver(this)
    }

    override fun onPushSubscriptionChange(state: PushSubscriptionChangedState) {
      if (state.current.optedIn) {
        println("User is now opted-in with push token: ${state.current.token}")
      }
    }
  }

  // Remove the observer
  OneSignal.User.pushSubscription.removeObserver(this)
  ```

  ```java Java theme={null}
  public class MainActivity extends Activity implements IPushSubscriptionObserver {
    protected void onCreate(Bundle savedInstanceState) {
      OneSignal.getUser().getPushSubscription().addObserver(this);
    }

    @Override
     public void onPushSubscriptionChange(@NotNull PushSubscriptionChangedState pushSubscriptionChangedState) {
        Log.i("OneSignal", "current subscription ID: " + pushSubscriptionChangedState.getCurrent().getId() );
     }
  }

  OneSignal.getUser().getPushSubscription().removeObserver(this);
  ```

  ```swift Swift theme={null}
  class AppDelegate: UIResponder, UIApplicationDelegate, OSPushSubscriptionObserver {
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        OneSignal.User.pushSubscription.addObserver(self)
     }

     func onPushSubscriptionDidChange(state: OSPushSubscriptionChangedState) {
         // respond to state change
     }
  }

  OneSignal.User.pushSubscription.removeObserver(self)
  ```

  ```objc Objective-C theme={null}
  // AppDelegate.h
  @interface AppDelegate : UIResponder <UIApplicationDelegate, OSPushSubscriptionObserver>
  @end

  // AppDelegate.m
  @implementation AppDelegate

  - (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [OneSignal.User.pushSubscription addObserver:self];
  }

  - (void)onPushSubscriptionDidChangeWithState:(OSPushSubscriptionChangedState *)state {
     // respond to new state
  }

  @end

  [OneSignal.User.pushSubscription removeObserver:self];
  ```

  ```csharp C# theme={null}
  OneSignal.User.PushSubscription.Changed += (sender, e) =>
    {
      if (e.State.Current.Id != e.State.Previous.Id)
      {
        // OneSignal Subscription id changed.
      }
    };
  ```

  ```javascript React Native theme={null}
  OneSignal.User.pushSubscription.addEventListener('change', (subscription) => {
    console.log('OneSignal: subscription changed:', subscription);
  });

  // Removes the previously added listener
  OneSignal.User.pushSubscription.removeEventListener('change', myListener);
  ```

  ```dart Flutter theme={null}
  OneSignal.User.pushSubscription.addObserver((state) {
    if (state.current.optedIn) {
    	/// respond to new state
  	}
  });

  // Removes the previously added observer
  OneSignal.User.pushSubscription.removeObserver(myObserver);
  ```

  ```javascript Cordova/Ionic theme={null}
  const listener = (event: PushSubscriptionChangedState) => {
    console.log("Push subscription changed: " + (event));
  };

  // Add the listener - Ionic
  OneSignal.User.pushSubscription.addEventListener("change", listener);

  // Remove the listener - Ionic
  OneSignal.User.pushSubscription.removeEventListener("change", listener);

  // Add the listener - Cordova
  window.plugins.OneSignal.User.pushSubscription.addEventListener("change", listener);

  // Remove the listener - Cordova
  window.plugins.OneSignal.User.pushSubscription.removeEventListener("change", listener);
  ```
</CodeGroup>

### `optOut()`, `optIn()`, `optedIn`

Control the subscription status (`subscribed` or `unsubscribed`) of the current mobile Subscription within your app. Common use cases:

* Call `optOut()` after `logout()` to prevent push from being sent to users that log out. Call `optIn()` to resume push notifications.

* Implement a notification preference center within your app.

* `optOut()`: Sets the current push subscription status to unsubscribed (even if the user has a valid push token). This sets `notification_types` to `-2` on the server. To resubscribe the user, call `optIn()`.

* `optIn()`: Does one of three actions:
  1. If the Subscription has a valid push token, it sets the current push subscription status to `subscribed`.
  2. If the Subscription does not have a valid push token, it displays the push permission prompt.
  3. If the push permission prompt has been displayed more than the operating system's limit (once iOS, twice Android), it displays the fallback prompt.

<Frame>
  <img />
</Frame>

* `optedIn`: Returns `true` if the current push subscription status is subscribed, otherwise `false`. If the push token is valid but `optOut()` was called, this will return `false`.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.User.pushSubscription.optOut()

  OneSignal.User.pushSubscription.optIn()

  val optedIn = OneSignal.User.pushSubscription.optedIn
  ```

  ```java Java theme={null}
  OneSignal.getUser().getPushSubscription().optOut();

  OneSignal.getUser().getPushSubscription().optIn();

  Boolean optedIn = OneSignal.getUser().getPushSubscription().getOptedIn();
  ```

  ```swift Swift theme={null}
  OneSignal.User.pushSubscription.optOut()

  OneSignal.User.pushSubscription.optIn()

  let optedIn: Bool = OneSignal.User.pushSubscription.optedIn
  ```

  ```objc Objective-C theme={null}
  [OneSignal.User.pushSubscription optOut];

  [OneSignal.User.pushSubscription optIn];

  Boolean optedIn = OneSignal.User.subscriptions.push.optedIn;
  ```

  ```csharp C# theme={null}
  OneSignal.User.PushSubscription.OptOut();

  OneSignal.User.PushSubscription.OptIn();

  OneSignal.User.PushSubscription.OptedIn;
  ```

  ```javascript React Native theme={null}
  OneSignal.User.pushSubscription.optOut();

  OneSignal.User.pushSubscription.optIn();

  await OneSignal.User.pushSubscription.getOptedInAsync();
  ```

  ```dart Flutter theme={null}
  OneSignal.User.pushSubscription.optOut();

  OneSignal.User.pushSubscription.optIn();

  OneSignal.User.pushSubscription.optedIn;
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.User.pushSubscription.optOut();

  OneSignal.User.pushSubscription.optIn();

  await OneSignal.User.pushSubscription.getOptedInAsync();

  // Cordova
  window.plugins.OneSignal.User.pushSubscription.optOut();

  window.plugins.OneSignal.User.pushSubscription.optIn();

  await window.plugins.OneSignal.User.pushSubscription.getOptedInAsync();
  ```
</CodeGroup>

### `addEmail()`, `removeEmail()`

Adds or removes an email Subscription for the current user. Compatible with [Identity Verification](./identity-verification).

* `addEmail(email)` creates or reassigns the email Subscription to the current user. The same email cannot exist multiple times in one app.
* `removeEmail(email)` detaches the email from the current user and assigns it a new OneSignal ID. Other Subscriptions remain unaffected.

| Status code      | Meaning                                                             |
| ---------------- | ------------------------------------------------------------------- |
| **200 OK**       | The Subscription already belongs to the current user.               |
| **201 Created**  | A new Subscription was created and linked to the user.              |
| **202 Accepted** | The Subscription already existed and was moved to the current user. |

Call `login()` before `addEmail()` to avoid attaching it to an anonymous user. See [Email reputation best practices](./email-reputation-best-practices).

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.User.addEmail("example@email.com")

  OneSignal.User.removeEmail("example@email.com")
  ```

  ```java Java theme={null}
  OneSignal.getUser().addEmail("example@email.com")

  OneSignal.getUser().removeEmail("example@email.com")
  ```

  ```swift Swift theme={null}
  OneSignal.User.addEmail("example@email.com")

  OneSignal.User.removeEmail("example@email.com")
  ```

  ```objc Objective-C theme={null}
  [OneSignal.User addEmail:@"example@email.com"];

  [OneSignal.User removeEmail:@"example@email.com"];
  ```

  ```csharp C# theme={null}
  OneSignal.User.AddEmail("example@email.com");

  OneSignal.User.RemoveEmail("example@email.com");
  ```

  ```javascript React Native theme={null}
  OneSignal.User.addEmail("example@email.com");

  OneSignal.User.removeEmail("example@email.com");
  ```

  ```dart Flutter theme={null}
  OneSignal.User.addEmail("example@email.com");

  OneSignal.User.removeEmail("example@email.com");
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.User.addEmail("example@email.com");

  OneSignal.User.removeEmail("example@email.com");

  // Cordova
  window.plugins.OneSignal.User.addEmail("example@email.com");

  window.plugins.OneSignal.User.removeEmail("example@email.com");
  ```
</CodeGroup>

### `addSms()`, `removeSms()`

Adds or removes an SMS Subscription for the current user. Phone numbers must be in [E.164 format](https://www.twilio.com/docs/glossary/what-e164) (e.g., `+15551234567`). Compatible with [Identity Verification](./identity-verification).

* `addSms(phoneNumber)` creates or reassigns the SMS Subscription to the current user. The same number cannot exist multiple times in one app.
* `removeSms(phoneNumber)` detaches the number from the current user and assigns it a new OneSignal ID. Other Subscriptions remain unaffected.

Returns the same [status codes as `addEmail()`](#addemail-removeemail). Call `login()` before `addSms()` to avoid attaching it to an anonymous user. See [SMS Registration Requirements](./sms-registration-requirements).

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.User.addSms("+15558675309")

  OneSignal.User.removeSms("+15558675309")
  ```

  ```java Java theme={null}
  OneSignal.getUser().addSms("+15558675309")

  OneSignal.getUser().removeSms("+15558675309")
  ```

  ```swift Swift theme={null}
  OneSignal.User.addSms("+15558675309")

  OneSignal.User.removeSms("+15558675309")
  ```

  ```objc Objective-C theme={null}
  [OneSignal.User addSms:@"+15558675309"];

  [OneSignal.User removeSms:@"+15558675309"];
  ```

  ```csharp C# theme={null}
  OneSignal.User.AddSms("+15558675309");

  OneSignal.User.RemoveSms("+15558675309");
  ```

  ```javascript React Native theme={null}
  OneSignal.User.addSms("+15558675309");

  OneSignal.User.removeSms("+15558675309");
  ```

  ```dart Flutter theme={null}
  OneSignal.User.addSms("+15558675309");

  OneSignal.User.removeSms("+15558675309");
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.User.addSms("+15558675309");

  OneSignal.User.removeSms("+15558675309");

  // Cordova
  window.plugins.OneSignal.User.addSms("+15558675309");

  window.plugins.OneSignal.User.removeSms("+15558675309");
  ```
</CodeGroup>

***

## Push permissions

### `requestPermission(fallbackToSettings)` *Push*

Shows the native system prompt asking the user for push notification permission. Optionally enable a fallback prompt that links to the settings app.

* `fallbackToSettings`: If `true`, the fallback prompt will be displayed if the user denied push permissions more than the operating system's limit (once iOS, twice Android).

<Frame>
  <img />
</Frame>

<Tip>
  For production apps, consider using [In-App Messages to prompt for notification permission](./prompt-for-push-permissions) instead of calling this method directly.
</Tip>

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.Notifications.requestPermission(true)
  ```

  ```java Java theme={null}
  OneSignal.getNotifications().requestPermission(Continue.with(r -> {
      if (r.isSuccess()) {
        if (r.getData()) {
          // User accepted permission
        }
        else {
          // User rejected permission
        }
      }
      else {
        // Request failed, check r.getThrowable()
      }
  }));
  ```

  ```swift Swift theme={null}
  OneSignal.Notifications.requestPermission({ accepted in
    print("User accepted notifications: \(accepted)")
  }, fallbackToSettings: true)
  ```

  ```objc Objective-C theme={null}
  [OneSignal.Notifications requestPermission:^(BOOL accepted) {
    NSLog(@"User accepted notifications: %d", accepted);
  } fallbackToSettings:true];
  ```

  ```csharp C# theme={null}
  var result = await OneSignal.Notifications.RequestPermissionAsync(true);
  ```

  ```javascript React Native theme={null}
  OneSignal.Notifications.requestPermission(true);
  ```

  ```dart Flutter theme={null}
  OneSignal.Notifications.requestPermission(true);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.Notifications.requestPermission(true).then((accepted) => {
      console.log("User accepted notifications: " + accepted);
  });

  // Cordova
  window.plugins.OneSignal.Notifications.requestPermission(true).then((accepted) => {
      console.log("User accepted notifications: " + accepted);
  });
  ```
</CodeGroup>

### `addPermissionObserver()` *Push*

Fires when push permission changes — the user accepts/declines the prompt, or toggles notifications in system settings. The listener receives a state object with `from` and `to` values. Call `removePermissionObserver()` to stop listening.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  class MyObserver : IPermissionObserver {
    init {
      OneSignal.Notifications.addPermissionObserver(this)
    }

    override fun onNotificationPermissionChange(granted: Boolean) {
      if (granted) {
        // Notifications are now enabled
      }
    }

    fun cleanup() {
      OneSignal.Notifications.removePermissionObserver(this)
    }
  }
  ```

  ```java Java theme={null}
  public class MainActivity extends Activity implements IPermissionObserver {
    protected void onCreate(Bundle savedInstanceState) {
      OneSignal.getNotifications().addPermissionObserver(this);
    }

    @Override
    public void onNotificationPermissionChange(boolean granted) {
      if (granted) {
        // Notifications are now enabled
      }
    }

    @Override
    protected void onDestroy() {
      OneSignal.getNotifications().removePermissionObserver(this);
      super.onDestroy();
    }
  }
  ```

  ```swift Swift theme={null}
  class AppDelegate: UIResponder, UIApplicationDelegate, OSNotificationPermissionObserver {
    func application(_ application: UIApplication,
                    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
      OneSignal.Notifications.addPermissionObserver(self)
      return true
    }

    func onNotificationPermissionDidChange(_ granted: Bool) {
      print("Notification permission changed: \(granted)")
    }

    func cleanup() {
      OneSignal.Notifications.removePermissionObserver(self)
    }
  }
  ```

  ```objc Objective-C theme={null}
  // AppDelegate.h
  @interface AppDelegate : UIResponder <UIApplicationDelegate, OSNotificationPermissionObserver>
  @end

  // AppDelegate.m
  @implementation AppDelegate

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [OneSignal.Notifications addPermissionObserver:self];
    return YES;
  }

  - (void)onNotificationPermissionDidChange:(BOOL)granted {
    NSLog(@"Permission changed: %d", granted);
  }

  - (void)cleanup {
    [OneSignal.Notifications removePermissionObserver:self];
  }
  @end
  ```

  ```csharp C# theme={null}
  OneSignal.Notifications.PermissionChanged += (sender, e) =>
    {
      // Respond to permission change
    };
  ```

  ```javascript React Native theme={null}
  const onPermissionChange = (granted) => {
    console.log('Permission changed:', granted);
  };

  OneSignal.Notifications.addEventListener('permissionChange', onPermissionChange);

  // Remove later if needed
  OneSignal.Notifications.removeEventListener('permissionChange', onPermissionChange);
  ```

  ```dart Flutter theme={null}
  final observer = (bool hasPermission) {
    print("Notification permission: $hasPermission");
  };

  OneSignal.Notifications.addPermissionObserver(observer);

  // Remove later if needed
  OneSignal.Notifications.removePermissionObserver(observer);
  ```

  ```javascript Cordova/Ionic theme={null}
  const listener = (granted) => {
    console.log("Push permission changed:", granted);
  };
  // Ionic
  OneSignal.Notifications.addEventListener("permissionChange", listener);

  // Remove later if needed
  OneSignal.Notifications.removeEventListener("permissionChange", listener);

  // Cordova
  window.plugins.OneSignal.Notifications.addEventListener("permissionChange", listener);

  // Remove later if needed
  window.plugins.OneSignal.Notifications.removeEventListener("permissionChange", listener);
  ```
</CodeGroup>

### `getPermission()`, `getCanRequestPermission()`

`getPermission()` returns the current app-level push permission status. It does not reflect OneSignal-level changes from `optOut()` or the Subscriptions API. For real-time tracking, use the [Push Permission Observer](#addpermissionobserver-push) or [Push Subscription Observer](#addobserver-push-subscription-changes).

`getCanRequestPermission()` returns whether the system will show a permission prompt. If `false`, the user already denied permission. See [Prompt for push permissions](./prompt-for-push-permissions).

<CodeGroup>
  ```kotlin Kotlin theme={null}
  // getPermission
  OneSignal.Notifications.permission

  // getCanRequestPermission
  val canRequest: Boolean = OneSignal.Notifications.canRequestPermission
  ```

  ```java Java theme={null}
  OneSignal.getNotifications().getPermission();

  OneSignal.getNotifications().getCanRequestPermission();
  ```

  ```swift Swift theme={null}
  OneSignal.Notifications.permission

  OneSignal.Notifications.canRequestPermission
  ```

  ```objc Objective-C theme={null}
  [OneSignal.Notifications permission];

  [OneSignal.Notifications canRequestPermission];
  ```

  ```csharp C# theme={null}
  bool permission = OneSignal.Notifications.Permission;

  bool canRequest = OneSignal.Notifications.CanRequestPermission;
  ```

  ```javascript React Native theme={null}
  await OneSignal.Notifications.getPermissionAsync();

  await OneSignal.Notifications.canRequestPermissionAsync();
  ```

  ```dart Flutter theme={null}
  var permission = OneSignal.Notifications.permission;

  var canRequest = OneSignal.Notifications.canRequestPermission;
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  await OneSignal.Notifications.getPermissionAsync();
  await OneSignal.Notifications.canRequestPermissionAsync();

  // Cordova
  await window.plugins.OneSignal.Notifications.getPermissionAsync();
  await window.plugins.OneSignal.Notifications.canRequestPermissionAsync();
  ```
</CodeGroup>

#### `permissionNative` *iOS*

Returns an enum for the native permission of the iOS device. It will be one of:

* `0` = NotDetermined
* `1` = Denied
* `2` = Authorized
* `3` = Provisional (only available in iOS 12+)
* `4` = Ephemeral (only available in iOS 14+)

<CodeGroup>
  ```swift Swift theme={null}
  let permissionNative: OSNotificationPermission = OneSignal.Notifications.permissionNative.rawValue
  ```

  ```objectivec Objective-C theme={null}
  OSNotificationPermission permissionNative = [OneSignal.Notifications permissionNative]
  ```

  ```csharp C# theme={null}
  NotificationPermission PermissionNative
  ```

  ```javascript React Native theme={null}
  await OneSignal.Notifications.permissionNative()
  ```

  ```dart Flutter theme={null}
  var permissionNative = await OneSignal.Notifications.permissionNative()
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  await OneSignal.Notifications.permissionNative()

  // Cordova
  await window.plugins.OneSignal.Notifications.permissionNative()
  ```
</CodeGroup>

## Push notification events

### `addClickListener()` *Push*

Runs when a user clicks a push notification that opens the app. The app is already launched by the time this fires — do not relaunch or duplicate navigation. Use `removeClickListener()` or `removeEventListener()` to stop listening.

<Warning>
  In Flutter `Debug` mode, force-closing the app prevents click listeners from registering. Use a release build (`flutter run --release`) or set the Xcode scheme to `Release`.
</Warning>

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val clickListener = object : INotificationClickListener {
    override fun onClick(event: INotificationClickEvent) {
      Log.d("OneSignal", "Notification clicked: ${event.notification.title}")
    }
  }
  OneSignal.Notifications.addClickListener(clickListener)
  ```

  ```java Java theme={null}
  OneSignal.getNotifications().addClickListener(event -> {
    Log.v(Tag.LOG_TAG, "INotificationClickListener.onClick fired" +
            " with event: " + event);
  });
  ```

  ```swift Swift theme={null}
  class AppDelegate: UIResponder, UIApplicationDelegate, OSNotificationClickListener {
    func application(_ application: UIApplication,
                    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
      OneSignal.Notifications.addClickListener(self)
      return true
    }

    func onClick(event: OSNotificationClickEvent) {
      print("Notification clicked: \(event.jsonRepresentation())")
    }
  }
  ```

  ```objc Objective-C theme={null}
  // AppDelegate.h
  @interface AppDelegate : UIResponder <UIApplicationDelegate, OSNotificationClickListener>
  @end

  // AppDelegate.m
  @implementation AppDelegate

  - (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [OneSignal.Notifications addClickListener:self];
    return YES;
  }

  - (void)onClickNotification:(OSNotificationClickEvent *)event {
    NSLog(@"Notification clicked: %@", [event jsonRepresentation]);
  }
  @end
  ```

  ```csharp C# theme={null}
  OneSignal.Notifications.Clicked += (sender, e) => {
    var RawPayload = e.Notification.RawPayload;
    Console.WriteLine("Notification clicked: " + RawPayload);
  };
  ```

  ```javascript React Native theme={null}
  OneSignal.Notifications.addEventListener('click', (event) => {
    console.log('OneSignal: notification clicked:', event);
  });
  ```

  ```dart Flutter theme={null}
  OneSignal.Notifications.addClickListener((event) {
    print('Notification clicked: ${event}');
  });
  ```

  ```javascript Cordova/Ionic theme={null}
  const myClickListener = (event) => {
    console.log("Notification clicked:", JSON.stringify(event));
  };
  // Ionic
  OneSignal.Notifications.addEventListener("click", myClickListener);

  // Cordova
  window.plugins.OneSignal.Notifications.addEventListener("click", myClickListener);
  ```
</CodeGroup>

### `addForegroundLifecycleListener()` *Push*

Runs when a notification is received while the app is in the foreground. By default, OneSignal displays foreground notifications automatically — this listener lets you intercept and control that behavior.

Within this method, you can:

* Call `event.preventDefault()` to stop the notification from displaying. This is helpful to prevent the notification from disrupting the user while the app is in the foreground.
* Optionally, you have about 25 seconds to do any checks or make any changes to the notification before calling `event.notification.display()` to show it on your own terms. If you never call `display()` after `preventDefault()`, the notification is silently discarded.
  * If `preventDefault()` does not suppress the notification (or the notification appears after a \~25 second delay), check if your app sets a custom `UNUserNotificationCenterDelegate`. A custom delegate's `willPresent` completion handler can force the notification to display regardless of `preventDefault()`. Remove the custom delegate or ensure it does not pass display options (.banner, .sound, .list) to the completion handler.

<Info>This listener runs **after** [Notification Service Extensions](./service-extensions), which modify the payload before display.</Info>

Use `removeForegroundLifecycleListener()` or `removeEventListener()` to stop listening.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val lifecycleListener = object : INotificationLifecycleListener {
    override fun onWillDisplay(event: INotificationWillDisplayEvent) {
      Log.d("OneSignal", "Foreground notification: ${event.notification.title}")

      // Stop the notification from displaying automatically
      // event.preventDefault()

      // Show it manually when ready
      // event.notification.display()
    }
  }
  OneSignal.Notifications.addForegroundLifecycleListener(lifecycleListener)
  ```

  ```java Java theme={null}
  OneSignal.getNotifications().addForegroundLifecycleListener(new INotificationLifecycleListener() {
    @Override
    public void onWillDisplay(@NonNull INotificationWillDisplayEvent event) {
      Log.d("OneSignal", "Foreground notification received: " + event.getNotification().getTitle());

      // Stop the notification from displaying automatically
      // event.preventDefault();

      // Show it manually when ready
      // event.getNotification().display();
    }
  });
  ```

  ```swift Swift theme={null}
  // Add the OSNotificationLifecycleListener protocol to your app delegate
  class AppDelegate: NSObject, UIApplicationDelegate, OSNotificationLifecycleListener {
    func onWillDisplay(event: OSNotificationWillDisplayEvent) {
      print("Foreground notification: \(event.notification.title)")

      // Stop the notification from displaying automatically
      // event.preventDefault()

      // Show it manually when ready
      // event.notification.display()
    }

    func application(_ application: UIApplication,
                    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
      OneSignal.Notifications.addForegroundLifecycleListener(self)
      return true
    }
  }
  ```

  ```objc Objective-C theme={null}
  @implementation AppDelegate

  - (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [OneSignal.Notifications addForegroundLifecycleListener:self];
    return YES;
  }

  - (void)onWillDisplayNotification:(OSNotificationWillDisplayEvent *)event {
    NSLog(@"Foreground notification: %@", event.notification.title);

    // Stop the notification from displaying automatically
    // [event preventDefault];

    // Show it manually when ready
    // [event.notification display];
  }
  @end
  ```

  ```csharp C# theme={null}
  OneSignal.Notifications.ForegroundWillDisplay += (sender, e) =>
  {
    Console.WriteLine("Foreground notification: " + e.Notification.RawPayload);

    // Stop the notification from displaying automatically
    // e.PreventDefault();

    // Show it manually when ready
    // e.Notification.Display();
  };
  ```

  ```javascript React Native theme={null}
  OneSignal.Notifications.addEventListener('foregroundWillDisplay', (event) => {
    console.log("Foreground notification:", event.getNotification().title);

    // Stop the notification from displaying automatically
    // event.preventDefault();

    // Show it manually when ready
    // event.getNotification().display();
  });
  ```

  ```dart Flutter theme={null}
  OneSignal.Notifications.addForegroundWillDisplayListener((event) {
    print("Foreground notification: ${event.notification.title}");

    // Stop the notification from displaying automatically
    // event.preventDefault();

    // Show it manually when ready
    // event.notification.display();
  });
  ```

  ```javascript Cordova/Ionic theme={null}
  const myLifecyleListener = function(event) {
    console.log("Foreground notification:", event.notification.title);

    // Stop the notification from displaying automatically
    // event.preventDefault();

    // Show it manually when ready
    // event.notification.display();
  };
  // Ionic
  OneSignal.Notifications.addEventListener("foregroundWillDisplay", myLifecyleListener);

  // Cordova
  window.plugins.OneSignal.Notifications.addEventListener("foregroundWillDisplay", myLifecyleListener);
  ```
</CodeGroup>

### `clearAllNotifications()`

Removes all OneSignal notifications from the Notification Shade. Use instead of Android's `android.app.NotificationManager.cancel`. Otherwise, the notifications will be restored when your app is restarted.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.Notifications.clearAllNotifications()
  ```

  ```java Java theme={null}
  OneSignal.getNotifications.clearAllNotifications();
  ```

  ```swift Swift theme={null}
  OneSignal.Notifications.clearAll()
  ```

  ```objc Objective-C theme={null}
  [OneSignal.Notifications clearAll];
  ```

  ```csharp C# theme={null}
  OneSignal.Notifications.ClearAllNotifications();
  ```

  ```javascript React Native theme={null}
  OneSignal.Notifications.clearAll();
  ```

  ```dart Flutter theme={null}
  OneSignal.Notifications.clearAll();
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.Notifications.clearAll();

  // Cordova
  window.plugins.OneSignal.Notifications.clearAll();
  ```
</CodeGroup>

#### `removeNotification()`, `removeGroupedNotifications()` *Android*

Cancel a single notification by its Android notification ID, or a group by its group key. Use these instead of `android.app.NotificationManager.cancel` — otherwise notifications will be restored when the app restarts.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.Notifications.removeNotification(id)
  OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY")
  ```

  ```java Java theme={null}
  OneSignal.getNotifications().removeNotification(id);
  OneSignal.getNotifications().removeGroupedNotifications("GROUP_KEY");
  ```

  ```csharp C# theme={null}
  OneSignal.Notifications.RemoveNotification(id);
  OneSignal.Notifications.RemoveGroupedNotifications("GROUP_KEY");
  ```

  ```javascript React Native theme={null}
  OneSignal.Notifications.removeNotification(id);
  OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY");
  ```

  ```dart Flutter theme={null}
  OneSignal.Notifications.removeNotification(id);
  OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY");
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.Notifications.removeNotification(id);
  OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY");

  // Cordova
  window.plugins.OneSignal.Notifications.removeNotification(id);
  window.plugins.OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY");
  ```
</CodeGroup>

***

## In-App Messages

In-app messages do not require any code; however, the SDK enables you to customize when messages are presented and handle lifecycle events.

### `addTrigger()`, `addTriggers()`

Decide when to display an In-App Message based on a single or multiple triggers. See [Triggers](./iam-triggers) for more information.

Triggers are not persisted to the backend. They only exist on the local device and apply to the current user.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.InAppMessages.addTrigger("KEY", "VALUE")

  OneSignal.InAppMessages.addTriggers(mapOf("KEY_01" to "VALUE_01", "KEY_02" to "VALUE_02"))
  ```

  ```java Java theme={null}
  OneSignal.getInAppMessages().addTrigger("KEY", "VALUE");

  OneSignal.getInAppMessages().addTriggers(new HashMap<String, String>() {{
    put("KEY_01","VALUE_01");
    put("KEY_02", "VALUE_02");
  }});
  ```

  ```swift Swift theme={null}
  OneSignal.InAppMessages.addTrigger("KEY", withValue: "VALUE")

  OneSignal.InAppMessages.addTriggers(["KEY_01": "VALUE_01", "KEY_02": "VALUE_02"])
  ```

  ```objc Objective-C theme={null}
  [OneSignal.InAppMessages addTrigger:@"KEY" withValue:@"VALUE"];

  [OneSignal.InAppMessages addTriggers:@{@"KEY_01": @"VALUE_01", @"KEY_02": @"VALUE_02"}];
  ```

  ```csharp C# theme={null}
  OneSignal.InAppMessages.AddTrigger("KEY", "VALUE");

  OneSignal.InAppMessages.AddTriggers(new Dictionary<string, string> {
    { "KEY_01", "VALUE_01" },
    { "KEY_02", "VALUE_02" }
  });
  ```

  ```javascript React Native theme={null}
  OneSignal.InAppMessages.addTrigger("KEY", "VALUE");

  OneSignal.InAppMessages.addTriggers({
    "KEY_01": "VALUE_01",
    "KEY_02": "VALUE_02"
  });
  ```

  ```dart Flutter theme={null}
  OneSignal.InAppMessages.addTrigger("KEY", "VALUE");

  OneSignal.InAppMessages.addTriggers({
    "KEY_01": "VALUE_01",
    "KEY_02": "VALUE_02"
  });
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.InAppMessages.addTrigger("KEY", "VALUE");

  OneSignal.InAppMessages.addTriggers({"KEY_01":"VALUE_01", "KEY_02":"VALUE_02"});

  // Cordova
  window.plugins.OneSignal.InAppMessages.addTrigger("KEY", "VALUE");

  window.plugins.OneSignal.InAppMessages.addTriggers({"KEY_01":"VALUE_01", "KEY_02":"VALUE_02"});
  ```
</CodeGroup>

### `removeTrigger()`, `removeTriggers()`, `clearTriggers()`

Remove a single, multiple, or all triggers with the provided key from the current user.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.InAppMessages.removeTrigger("KEY")

  OneSignal.InAppMessages.removeTriggers(setOf("KEY_01", "KEY_02"))

  OneSignal.InAppMessages.clearTriggers()
  ```

  ```java Java theme={null}
  OneSignal.getInAppMessages().removeTrigger("KEY");

  OneSignal.getInAppMessages().removeTriggers(Arrays.asList("KEY_01", "KEY_02"));

  OneSignal.getInAppMessages().clearTriggers();
  ```

  ```swift Swift theme={null}
  OneSignal.InAppMessages.removeTrigger("KEY")

  OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"])

  OneSignal.InAppMessages.clearTriggers()
  ```

  ```objc Objective-C theme={null}
  [OneSignal.InAppMessages removeTrigger:@"KEY"];

  [OneSignal.InAppMessages removeTriggers:@[@"KEY_01", @"KEY_02"]];

  [OneSignal.InAppMessages clearTriggers];
  ```

  ```csharp C# theme={null}
  OneSignal.InAppMessages.RemoveTrigger("KEY");

  OneSignal.InAppMessages.RemoveTriggers(new List<string> { "KEY_01", "KEY_02" });

  OneSignal.InAppMessages.ClearTriggers();
  ```

  ```javascript React Native theme={null}
  OneSignal.InAppMessages.removeTrigger("KEY");

  OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]);

  OneSignal.InAppMessages.clearTriggers();
  ```

  ```dart Flutter theme={null}
  OneSignal.InAppMessages.removeTrigger("KEY");

  OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]);

  OneSignal.InAppMessages.clearTriggers();
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.InAppMessages.removeTrigger("KEY");

  OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]);

  OneSignal.InAppMessages.clearTriggers();

  // Cordova
  window.plugins.OneSignal.InAppMessages.removeTrigger("KEY");

  window.plugins.OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]);

  window.plugins.OneSignal.InAppMessages.clearTriggers();
  ```
</CodeGroup>

### `paused`

Prevent In-app messages from being displayed to the user. When set to `true`, no in-app messages will be presented. When set to `false`, any messages the user qualifies for will be presented to them at the appropriate time.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.InAppMessages.paused = true
  ```

  ```java Java theme={null}
  OneSignal.getInAppMessages().setPaused(true);
  ```

  ```swift Swift theme={null}
  OneSignal.InAppMessages.paused = true

  // Get `paused` state
  let paused = OneSignal.InAppMessages.paused
  ```

  ```objc Objective-C theme={null}
  [OneSignal.InAppMessages paused:true];

  // Get `paused` state
  BOOL paused = [OneSignal.InAppMessages paused];
  ```

  ```csharp C# theme={null}
  OneSignal.InAppMessages.Paused = true;
  ```

  ```javascript React Native theme={null}
  OneSignal.InAppMessages.setPaused(true);
  ```

  ```dart Flutter theme={null}
  OneSignal.InAppMessages.paused(true);
  ```

  ```javascript Cordova/Ionic theme={null}
  // Ionic
  OneSignal.InAppMessages.setPaused(true);

  // Cordova
  window.plugins.OneSignal.InAppMessages.setPaused(true);
  ```
</CodeGroup>

### `addLifecycleListener()`

Respond to or track In-App Messages being displayed and dismissed.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val lifecycleListener = object : IInAppMessageLifecycleListener {
    override fun onWillDisplay(event: IInAppMessageWillDisplayEvent) {
      print(event.message.messageId)
    }

    override fun onDidDisplay(event: IInAppMessageDidDisplayEvent) {
      print(event.message.messageId)
    }

    override fun onWillDismiss(event: IInAppMessageWillDismissEvent) {
      print(event.message.messageId)
    }

    override fun onDidDismiss(event: IInAppMessageDidDismissEvent) {
      print(event.message.messageId)
    }
  }
  OneSignal.InAppMessages.addLifecycleListener(lifecycleListener)
  OneSignal.InAppMessages.removeLifecycleListener(lifecycleListener)
  ```

  ```java Java theme={null}
  OneSignal.getInAppMessages().addLifecycleListener(new IInAppMessageLifecycleListener() {
    @Override
    public void onWillDisplay(@NonNull IInAppMessageWillDisplayEvent event) {
        Log.v(Tag.LOG_TAG, "onWillDisplayInAppMessage");
    }

    @Override
    public void onDidDisplay(@NonNull IInAppMessageDidDisplayEvent event) {
        Log.v(Tag.LOG_TAG, "onDidDisplayInAppMessage");
    }

    @Override
    public void onWillDismiss(@NonNull IInAppMessageWillDismissEvent event) {
        Log.v(Tag.LOG_TAG, "onWillDismissInAppMessage");
    }

    @Override
    public void onDidDismiss(@NonNull IInAppMessageDidDismissEvent event) {
        Log.v(Tag.LOG_TAG, "onDidDismissInAppMessage");
    }
  });
  ```

  ```swift Swift theme={null}
  // AppDelegate.swift
  // Add OSInAppMessageLifecycleListener as an implemented protocol of the class that will handle the In-App Message lifecycle events.
  class AppDelegate: UIResponder, UIApplicationDelegate, OSInAppMessageLifecycleListener {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
      // Add your implementing class as the listener
      OneSignal.InAppMessages.addLifecycleListener(self)
    }
    // Add one or more of the following optional lifecycle methods
    func onWillDisplay(event: OSInAppMessageWillDisplayEvent) {
      print("OSInAppMessageLifecycleListener: onWillDisplay Message: \(event.message.messageId)")
    }
    func onDidDisplay(event: OSInAppMessageDidDisplayEvent) {
      print("OSInAppMessageLifecycleListener: onDidDisplay Message: \(event.message.messageId)")
    }
    func onWillDismiss(event: OSInAppMessageWillDismissEvent) {
      print("OSInAppMessageLifecycleListener: onWillDismiss Message: \(event.message.messageId)")
    }
    func onDidDismiss(event: OSInAppMessageDidDisplayEvent) {
      print("OSInAppMessageLifecycleListener: onDidDismiss Message: \(event.message.messageId)")
  	}
  }
  ```

  ```objc Objective-C theme={null}
  // AppDelegate.h
  // Add OSInAppMessageLifecycleListener as an implemented protocol of the class that will handle the In-App Message lifecycle events.
  @interface AppDelegate : UIResponder <UIApplicationDelegate, OSInAppMessageLifecycleListener>
  @end

  // AppDelegate.m
  @implementation AppDelegate

  - (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      // Add your implementing class as the listener.
      [OneSignal.InAppMessages addLifecycleListener:self];
  }

  // Add one or more of the following optional lifecycle methods
  - (void)onWillDisplayInAppMessage:(OSInAppMessageWillDisplayEvent *)event {
    NSLog(@"OSInAppMessageLifecycleListener: onWillDisplay Message: %@", event.message.messageId);
  }

  - (void)onDidDisplayInAppMessage:(OSInAppMessageDidDisplayEvent *)event {
    NSLog(@"OSInAppMessageLifecycleListener: onDidDisplay Message: %@", event.message.messageId);
  }

  - (void)onWillDismissInAppMessage:(OSInAppMessageWillDismissEvent *)event {
    NSLog(@"OSInAppMessageLifecycleListener: onWillDismiss Message: %@", event.message.messageId);
  }

  - (void)onDidDismissInAppMessage:(OSInAppMessageDidDismissEvent *)event {
    NSLog(@"OSInAppMessageLifecycleListener: onDidDismiss Message: %@", event.message.messageId);
  }
  ```

  ```csharp C# theme={null}
  OneSignal.InAppMessages.WillDisplay += (sender, e) =>
    {
      // Access the in-app message with e.Message
    };

  OneSignal.InAppMessages.DidDisplay += (sender, e) =>
    {
      // Access the in-app message with e.Message
    };

  OneSignal.InAppMessages.WillDismiss += (sender, e) =>
    {
      // Access the in-app message with e.Message
    };

  OneSignal.InAppMessages.DidDismiss += (sender, e) =>
    {
      // Access the in-app message with e.Message
    };
  ```

  ```javascript React Native theme={null}
  OneSignal.InAppMessages.addEventListener('willDisplay', (event) => {
    console.log('OneSignal: will display IAM: ', event);
  });

  OneSignal.InAppMessages.addEventListener('didDisplay', (event) => {
    console.log('OneSignal: did display IAM: ', event);
  });

  OneSignal.InAppMessages.addEventListener('willDismiss', (event) => {
    console.log('OneSignal: will dismiss IAM: ', event);
  });

  OneSignal.InAppMessages.addEventListener('didDismiss', (event) => {
    console.log('OneSignal: did dismiss IAM: ', event);
  });
  ```

  ```dart Flutter theme={null}
  OneSignal.InAppMessages.addWillDisplayListener((event) {
  	print("ON WILL DISPLAY IN APP MESSAGE ${event.message.messageId}");
  });
  OneSignal.InAppMessages.addDidDisplayListener((event) {
  	print("ON DID DISPLAY IN APP MESSAGE ${event.message.messageId}");
  });
  OneSignal.InAppMessages.addWillDismissListener((event) {
  	print("ON WILL DISMISS IN APP MESSAGE ${event.message.messageId}");
  });
  OneSignal.InAppMessages.addDidDismissListener((event) {
  	print("ON DID DISMISS IN APP MESSAGE ${event.message.messageId}");
  });
  ```

  ```javascript Cordova/Ionic theme={null}
  // Define the lifecycle listener functions
  let willDisplayListener = async function(event) {
    console.log("OneSignal: will display IAM: "+ event.messageId);
  };
  let didDisplayListener = async function(event) {
    console.log("OneSignal: did display IAM: "+ event.messageId);
  };
  let willDismissListener = async function(event) {
    console.log("OneSignal: will dismiss IAM: "+ event.messageId);
  };
  let didDismissListener = async function(event) {
    console.log("OneSignal: did dismiss IAM: "+ event.messageId);
  };

  // Listeners for each event added separately
  // Ionic
  OneSignal.InAppMessages.addEventListener("willDisplay", willDisplayListener);
  OneSignal.InAppMessages.addEventListener("didDisplay", didDisplayListener);
  OneSignal.InAppMessages.addEventListener("willDismiss", willDismissListener);
  OneSignal.InAppMessages.addEventListener("didDismiss", didDismissListener);

  // Cordova
  window.plugins.OneSignal.InAppMessages.addEventListener("willDisplay", willDisplayListener);
  window.plugins.OneSignal.InAppMessages.addEventListener("didDisplay", didDisplayListener);
  window.plugins.OneSignal.InAppMessages.addEventListener("willDismiss", willDismissListener);
  window.plugins.OneSignal.InAppMessages.addEventListener("didDismiss", didDismissListener);
  ```
</CodeGroup>

### `addClickListener()` *In-App*

Respond to in-app message click events. The event contains the following [click action](./iam-click-actions) metadata:

* `actionId`: A custom identifier you set on the element.
* `urlTarget`: An enum specifying how the launch URL for the message will be presented.
* `url`: The launch URL for the action, if any.
* `closingMessage`: A boolean value indicating if the action resulted in the message being closed.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val clickListener = object : IInAppMessageClickListener {
    override fun onClick(event: IInAppMessageClickEvent) {
      print(event.result.actionId)
    }
  }
  OneSignal.InAppMessages.addClickListener(clickListener)
  ```

  ```java Java theme={null}
  OneSignal.getInAppMessages().addClickListener(new IInAppMessageClickListener() {
    @Override
    public void onClick(@Nullable IInAppMessageClickEvent event) {
      Log.v(Tag.LOG_TAG, "INotificationClickListener.inAppMessageClicked");
    }
  });
  ```

  ```swift Swift theme={null}
  class MyInAppMessageClickListener : NSObject, OSInAppMessageClickListener {
      func onClick(event: OSInAppMessageClickEvent) {
          let messageId = event.message.messageId
          print("Message ID: \(messageId)")
          let result: OSInAppMessageClickResult = event.result
          let actionId = result.actionId
          print("Action ID: ",(actionId ?? "no actionId"))
          let url = result.url
          print("URL: ", (url ?? "No URL"))
          let urlTarget: OSInAppMessageActionUrlType = result.urlTarget
          print("URL Target: \(urlTarget)")
          let closingMessage = result.closingMessage
          print("Closing Message: \(closingMessage)")
      }
  }

  // Add your object as a listener
  let myListener = MyInAppMessageClickListener()
  OneSignal.InAppMessages.addClickListener(myListener)
  ```

  ```objc Objective-C theme={null}
  // Add this method to object implementing the OSInAppMessageClickListener protocol
  - (void)onClickInAppMessage:(OSInAppMessageClickEvent * _Nonnull)event {
      NSLog(@"onClickInAppMessage event: %@", [event jsonRepresentation]);
      NSString *message = [NSString stringWithFormat:@"In App Message Click Occurred: messageId: %@ actionId: %@ url: %@ urlTarget: %@ closingMessage: %i",
                          event.message.messageId,
                          event.result.actionId,
                          event.result.url,
                          @(event.result.urlTarget),
                          event.result.closingMessage];
  }

  // Add your object as a listener
  [OneSignal.InAppMessages addClickListener:self];
  ```

  ```csharp C# theme={null}
  OneSignal.InAppMessages.Clicked += (sender, e) =>
    {
      // Access the in-app message with e.Message and the click result with e.Result
    };
  ```

  ```javascript React Native theme={null}
  OneSignal.InAppMessages.addEventListener('click', (event) => {
    console.log('OneSignal IAM clicked:', event);
  });
  ```

  ```dart Flutter theme={null}
  OneSignal.InAppMessages.addClickListener((event) {
  	print("In App Message Clicked: \n${event.result.jsonRepresentation().replaceAll("\\n", "\n")}");
  });
  ```

  ```javascript Cordova/Ionic theme={null}
  let inAppClickListener = async function(event) {
    let clickData = JSON.stringify(event);
    console.log("In-App Message Clicked: "+ clickData);
  };

  // Ionic
  OneSignal.InAppMessages.addEventListener("click", inAppClickListener);

  // Cordova
  window.plugins.OneSignal.InAppMessages.addEventListener("click", inAppClickListener);
  ```
</CodeGroup>

***

## Live Activity

Applications should allow users to opt-in to Live Activities. For example, your app gives the user the option to start the Live Activity within your US using a button or presenting an IAM. You may start and update a Live Activity via any method without an explicit prompt, unlike Notification Permission or Location Permission. Live Activities appear with the iOS Provisional Authorization UI. Live Activities must be started when your application is in the foreground. We recommend reading [Apple’s developer guidelines](https://developer.apple.com/design/human-interface-guidelines/live-activities) to learn more about Live Activities.

### `setup()`

Allows OneSignal to manage the lifecycle of a LiveActivity on behalf of the application.  This includes listening for both pushToStart token updates and pushToUpdate token updates.

<CodeGroup>
  ```swift Swift theme={null}
  //... your app's code
  OneSignal.LiveActivities.setup(MyWidgetAttributes.self);
  ```
</CodeGroup>

### `setupDefault()`

Allows cross platform SDK's to manage the lifecycle of a LiveActivity by eliminating the need for a customer app to define and manage their own ActivityAttributes. See [Cross-platform setup](./cross-platform-live-activity-setup) for further details.

<CodeGroup>
  ```csharp C# theme={null}
  using OneSignalSDK;

  //Push To Start
  OneSignal.LiveActivities.SetupDefault();

  //Launching the Live Activity from within the app (not needed for push to start)
  string activityId = "my_activity_id";

  OneSignal.LiveActivities.StartDefault(
    activityId,
    new Dictionary<string, object>() {
        { "title", "Welcome!" }
    },
    new Dictionary<string, object>() {
        { "message", new Dictionary<string, object>() {
            { "en", "Hello World!"}
        }},
    });
  ```

  ```javascript React Native theme={null}
  import { OneSignal } from 'react-native-onesignal'

  //Push To Start
  OneSignal.LiveActivities.setupDefault()

  //Launching the Live Activity from within the app (not needed for push to start)
  const activityId = "my_activity_id"
  const attributes = { title: "Sample Title" } ;
  const content = { message: { en: "message" } };
  OneSignal.LiveActivities.startDefault(activityId, attributes, content);
  ```

  ```dart Flutter theme={null}
  import 'package:onesignal_flutter/onesignal_flutter.dart';

  OneSignal.LiveActivities.setupDefault()

  //Launching the Live Activity from within the app (not needed for push to start)
  const String activityId = "my_activity_id";
  OneSignal.LiveActivities.startDefault(activityId!, {
    "title": "Welcome!"
    }, {
    "message": {"en": "Hello World!"},
  });
  ```

  ```javascript Cordova/Ionic theme={null}
  //Ionic
  import OneSignal from "onesignal-cordova-plugin";

  //Push To Start
  OneSignal.LiveActivities.setupDefault();

  //Launching the Live Activity from within the app (not needed for push to start)
  const activityId = "my_activity_id";
  const attributes = { title: "Sample Title" };
  const content = { message: { en: "message" } };
  OneSignal.LiveActivities.startDefault(activityId, attributes, content);

  //Cordova
  //Push To Start
  window.plugins.OneSignal.LiveActivities.setupDefault();

  //Launching the Live Activity from within the app (not needed for push to start)
  const activityId = "my_activity_id";
  const attributes = { title: "Sample Title" };
  const content = { message: { en: "message" } };
  window.plugins.OneSignal.LiveActivities.startDefault(
    activityId,
    attributes,
    content
  );
  ```
</CodeGroup>

### `enter()`

Entering a Live Activity associates an `activityId` with a Live Activity **Temporary Push Token** on our server. Specify this identifier when using the [Update Live Activities](/reference/update-live-activity-api) REST API to update one or multiple Live Activities simultaneously.

<CodeGroup>
  ```swift Swift theme={null}
  // ... your app's code
  let activity = try Activity<MyWidgetAttributes>.request(
    attributes: attributes,
    contentState: contentState,
    pushType: .token)
  Task {
    for await data in activity.pushTokenUpdates {
        let token = data.map {String(format: "%02x", $0)}.joined()
        // ... required code for entering a live activity
        // Activity ID cannot contain "/" characters
        OneSignal.LiveActivities.enter("ACTIVITY_ID", withToken: token)
    }
  }
  ```

  ```csharp C# theme={null}
  OneSignal.LiveActivities.EnterAsync("ACTIVITY_ID", token);
  ```

  ```csharp .Net theme={null}
  var result = OneSignalSDK.DotNet.OneSignal.Default.EnterLiveActivity("ACTIVITY_ID", token);
  if(result) {
      Console.WriteLine("Success");
  }
  ```

  ```javascript React Native theme={null}
  OneSignal.LiveActivities.enter('ACTIVITY_ID', token, (result) => {
    console.log('Results of entering live activity: ', result);
  });
  ```

  ```dart Flutter theme={null}
  OneSignal.LiveActivities.enterLiveActivity("ACTIVITY_ID", token).then((result) {
      print("Successfully enter live activity");
  }).catchError((error) {
      print("Failed to enter live activity with error: $error");
  });
  ```

  ```javascript Cordova/Ionic theme={null}
  //Ionic
  OneSignal.LiveActivities.enter("ACTIVITY_ID", token, (result) => {
    console.log("Results of entering live activity: ", result);
  });

  //Cordova
  window.plugins.OneSignal.LiveActivities.enter("ACTIVITY_ID", token, (result) => {
    console.log("Results of entering live activity: ", result);
  });
  ```
</CodeGroup>

### `exit()`

Exiting a Live activity deletes the association between an Activity Identifier with the Live Activity push token on our server.

<CodeGroup>
  ```swift Swift theme={null}
  OneSignal.LiveActivities.exit("ACTIVITY_ID")
  ```

  ```csharp C# theme={null}
  OneSignal.LiveActivities.ExitAsync("ACTIVITY_ID");
  ```

  ```csharp .Net theme={null}
  OneSignalSDK.DotNet.OneSignal.Default.ExitLiveActivity("ACTIVITY_ID");
  ```

  ```javascript React Native theme={null}
  OneSignal.LiveActivities.exit('ACTIVITY_ID', (result) => {
    console.log('Results of exiting live activity: ', result);
  });
  ```

  ```dart Flutter theme={null}
  OneSignal.LiveActivities.exit("ACTIVITY_ID").then((result) {
      print("Successfully exit live activity");
  }).catchError((error) {
      print("Failed to exit live activity: $error");
  });
  ```

  ```javascript Cordova/Ionic theme={null}
  window.plugins.OneSignal.LiveActivities.exit("ACTIVITY_ID", (result) => {
    console.log("Results of exiting live activity: ", result);
  });
  ```
</CodeGroup>

### `setPushToStartToken()`

Optional "low-level" approach to push to start live activities. Offers fine-grained control over the LiveActivity start and update tokens without altering the `ActivityAttribute` structure. [Additional details available here](https://github.com/OneSignal/OneSignal-iOS-SDK/pull/1377#:~:text=Alternative%20\(low%20level\)%20method%20to%20setup%20Live%20Activities%20with%20OneSignal)

<CodeGroup>
  ```swift Swift theme={null}
  if #available(iOS 17.2, *) {
    // Setup an async task to monitor and send pushToStartToken updates to OneSignalSDK.
    Task {
        for try await data in Activity<MyWidgetAttributes>.pushToStartTokenUpdates {
            let token = data.map {String(format: "%02x", $0)}.joined()
            OneSignal.LiveActivities.setPushToStartToken(MyWidgetAttributes.self, withToken: token)
        }
    }
    // Setup an async task to monitor for an activity to be started, for each started activity we
    // can then set up an async task to monitor and send updateToken updates to OneSignalSDK.
    Task {
        for await activity in Activity<MyWidgetAttributes>.activityUpdates {
          Task {
              for await pushToken in activity.pushTokenUpdates {
                  let token = pushToken.map {String(format: "%02x", $0)}.joined()
                  OneSignal.LiveActivities.enter("my-activity-id", withToken: token)
              }
          }
        }
    }
  }
  ```
</CodeGroup>

### `removePushToStartToken()`

Called per-activity-type whenever that activity type should no longer be registered against the current subscription

<CodeGroup>
  ```swift Swift theme={null}
  OneSignal.LiveActivities.removePushToStartToken(MyWidgetAttributes.self)
  ```
</CodeGroup>

***

## Outcomes

Track actions taken by users and attribute them to messages. See [Outcomes](./custom-outcomes) for more details.

### `addOutcome()`, `addUniqueOutcome()`, `addOutcomeWithValue()`

* `addOutcome(name)` — Add an outcome captured against the current session.
* `addUniqueOutcome(name)` — Add a unique outcome (counted once per session).
* `addOutcomeWithValue(name, value)` — Add an outcome with a numeric value.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  OneSignal.Session.addOutcome("OUTCOME_NAME")
  OneSignal.Session.addUniqueOutcome("OUTCOME_NAME")
  OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14)
  ```

  ```java Java theme={null}
  OneSignal.getSession().addOutcome("OUTCOME_NAME");
  OneSignal.getSession().addUniqueOutcome("OUTCOME_NAME");
  OneSignal.getSession().addOutcomeWithValue("OUTCOME_NAME", 3.14);
  ```

  ```swift Swift theme={null}
  OneSignal.Session.addOutcome("OUTCOME_NAME")
  OneSignal.Session.addUniqueOutcome("OUTCOME_NAME")
  OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14)
  ```

  ```objc Objective-C theme={null}
  [OneSignal.Session addOutcome:@"OUTCOME_NAME"];
  [OneSignal.Session addUniqueOutcome:@"OUTCOME_NAME"];
  [OneSignal.Session addOutcomeWithValue:@"OUTCOME_NAME" value: 3.14];
  ```

  ```csharp C# theme={null}
  OneSignal.Session.AddOutcome("OUTCOME_NAME");
  OneSignal.Session.AddUniqueOutcome("OUTCOME_NAME");
  OneSignal.Session.AddOutcomeWithValue("OUTCOME_NAME", 3.14);
  ```

  ```javascript React Native theme={null}
  OneSignal.Session.addOutcome("OUTCOME_NAME");
  OneSignal.Session.addUniqueOutcome("OUTCOME_NAME");
  OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14);
  ```

  ```dart Flutter theme={null}
  OneSignal.Session.addOutcome("OUTCOME_NAME");
  OneSignal.Session.addUniqueOutcome("OUTCOME_NAME");
  OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14);
  ```

  ```javascript Cordova/Ionic theme={null}
  //Ionic
  OneSignal.Session.addOutcome("OUTCOME_NAME");
  OneSignal.Session.addUniqueOutcome("OUTCOME_NAME");
  OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14);

  //Cordova
  window.plugins.OneSignal.Session.addOutcome("OUTCOME_NAME");
  window.plugins.OneSignal.Session.addUniqueOutcome("OUTCOME_NAME");
  window.plugins.OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14);
  ```
</CodeGroup>

***

## FAQ

### What is the difference between `onesignal_id` and the Subscription ID?

The `onesignal_id` is a user-level identifier that represents a person across all their devices and channels. The Subscription ID (`User.pushSubscription.id`) is a device-level identifier for a single push channel. One user can have multiple Subscriptions.

### Do I need to call `login()` every time the app starts?

Yes. Call `login(external_id)` on every app launch once you know the user's identifier (after sign-in or session restore). The SDK handles deduplication — if the user is already logged in with that ID, the call is effectively a no-op.

### What happens to anonymous data when I call `login()`?

If the `external_id` already exists, anonymous data (tags, session data, email/SMS Subscriptions) collected before login is discarded. If the `external_id` is new, the anonymous data is retained and associated with the newly created user.

### Why does `getOnesignalId()` return `null`?

The OneSignal ID is not available until the SDK finishes initializing. If you call `getOnesignalId()` too early (for example, immediately after `initialize()`), it may return `null`. Use [User State `addObserver()`](#addeventlistener-user-state) to reliably detect when the ID becomes available.


# Mobile SDK troubleshooting
Source: https://documentation.onesignal.com/docs/en/mobile-troubleshooting

Resolve common OneSignal Mobile SDK issues including push delivery failures, APNS errors, and in-app messaging problems across iOS, Android, and cross-platform frameworks.

<Note>
  If you are having issues with your website, see the [Web Push Troubleshooting guide](./troubleshooting-web-push).
</Note>

## Troubleshooting steps

### Review setup instructions and update the SDK

We frequently [release updates](https://github.com/OneSignal/sdks) with bug fixes, improvements, and support for the latest operating system changes. Ensure you are using the latest SDK version and have followed the setup instructions.

<Card title="Mobile SDK setup" icon="wrench" href="./mobile-sdk-setup">
  Setup instructions designed to help prevent common issues and test the integration.
</Card>

### Check common troubleshooting guides

<Columns>
  <Card title="Notifications not shown or delayed" icon="bell-slash" href="./notifications-show-successful-but-are-not-being-shown">
    Push notifications are not appearing on the device or are delayed.
  </Card>

  <Card title="Notification images not showing" icon="image" href="./notification-images-not-showing">
    Images are not appearing in the expanded notification view.
  </Card>

  <Card title="Notification CTR" icon="arrow-pointer" href="./notification-ctr">
    Low or no clicks on notifications.
  </Card>

  <Card title="Duplicated notifications" icon="copy" href="./duplicated-notifications">
    Notifications are appearing multiple times on the device.
  </Card>

  <Card title="In-app message troubleshooting" icon="message" href="./in-app-message-troubleshooting">
    In-app messages are not displaying or behaving as expected.
  </Card>
</Columns>

### Check your app for common issues

#### OneSignal methods that block push from showing

Check your app for `optOut()` like `OneSignal.User.pushSubscription.optOut()` or if you set `enabled: false` via our REST APIs. This sets the push subscription status to `unsubscribed`. See [Mobile SDK reference](./mobile-sdk-reference#optout-%2C-optin-%2C-optedin) for more details.

If you have the app open while the push is being sent, you may be preventing the push from showing via the `preventDefault()` method. This is usually set in the [Foreground Event Listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) or [Android Notification Service Extension](./service-extensions).

#### Firebase Messaging or other SDK conflicts

If your app also includes the Firebase Messaging SDK or other push notification SDKs, verify it is not intercepting messages before OneSignal can process them.

This issue commonly occurs when:

* Notifications show as **Delivered** in OneSignal but never appear on the device.
* The app includes both OneSignal and `firebase_messaging` (or a custom `FirebaseMessagingService`).
* Push works when Firebase Messaging is removed, but fails when both SDKs are present.

1. Check your `AndroidManifest.xml` for legacy Firebase receivers such as `com.google.firebase.iid.FirebaseInstanceIdReceiver` and remove/conditionally exclude them if OneSignal is responsible for push delivery.

2. Check for custom `FirebaseMessagingService` implementations (or libraries such as `firebase_messaging` in Flutter) that override `onMessageReceived`. If another service fully processes or suppresses messages, it may consume the FCM payload before OneSignal can display the notification.

3. Avoid calling Firebase token management APIs such as: `FirebaseMessaging.getToken()` or `FirebaseMessaging.deleteToken()`.

If OneSignal is responsible for push delivery, it should be the only SDK managing the push token lifecycle. Fetching or managing the FCM token directly can lead to token ownership conflicts and inconsistent delivery behavior.

If you need the device push token for other systems, read it from OneSignal (for example, `User.pushSubscription.token`) and listen for subscription/token changes using the [SDK's observer APIs](./mobile-sdk-reference#addobserver-push-subscription-changes).

### Test an example project your SDK

Check if the issue is reproducible using the example project maintained by our engineering team for each SDK.

* [iOS example project](https://github.com/OneSignal/OneSignal-iOS-SDK/tree/main/OneSignalSwiftUIExample)
* [Android example project](https://github.com/OneSignal/OneSignal-Android-SDK/tree/main/examples)
* [Cordova variants example project](https://github.com/OneSignal/OneSignal-Cordova-SDK/tree/main/examples)
* [React Native example project](https://github.com/OneSignal/react-native-onesignal/tree/main/examples)
* [Flutter example project](https://github.com/OneSignal/OneSignal-Flutter-SDK/tree/main/examples)
* [Unity example project](https://github.com/OneSignal/OneSignal-Unity-SDK/tree/main/examples)
* [.NET MAUI example project](https://github.com/OneSignal/OneSignal-DotNet-SDK/tree/main/examples)

### Check the error logs

Gather log data before diagnosing further:

* Follow the guide on [capturing a debug log](./capturing-a-debug-log).
* Look for errors, warnings, or deprecation notices that could explain the behavior.

<Card title="Capturing a debug log" icon="bug" href="./capturing-a-debug-log">
  How to enable verbose logging and capture SDK output for troubleshooting.
</Card>

### Contact support

If you are still experiencing the issue, contact `support@onesignal.com` with:

* Your OneSignal App ID
* Your External ID and/or Subscription ID of the affected device
* The notification ID or a link to the notification in the dashboard (if applicable)
* A [debug log from the device](./capturing-a-debug-log) reproducing the issue

***

## Common errors

### APNS Delegate never fired

Errors like "APNS Delegate Never Fired" and "APNS 3000" are timeout messages from Apple indicating that the device could not connect to Apple's APNS servers. This is most common when:

* Testing on APNS development environments
* Using multiple push notification dependencies or native iOS push APIs alongside OneSignal
* A temporary connectivity issue — this often self-resolves the next time the user starts a new session (app in background for 30+ seconds, then reopened)

**Steps to resolve:**

1. Remove any other push notification dependencies or native iOS push APIs and use only OneSignal. Once the error resolves, you can re-add the other code. Contact `support@onesignal.com` for best practices on coexistence.
2. Check the [debug log from the device](./capturing-a-debug-log) for more details.
3. If the error persists, [contact support](#troubleshooting-steps).

If you are using Capacitor, add this configuration to let OneSignal handle push notifications. This configuration will resolve the issue.

<CodeGroup>
  ```json json theme={null}
  {
    "ios": {
      "handleApplicationNotifications": false
    }
  }
  ```

  ```typescript capacitor.config.ts theme={null}
  const config: CapacitorConfig = {
    // ... additional configuration

    ios: {
      // ... additional configuration
      handleApplicationNotifications: false
    }
  };
  ```
</CodeGroup>

### App not opening when force-closed and clicking a notification

Make sure you are not testing on a `Debug` build. For example, on Flutter Apps, you can either:

* Use a release build via Flutter e.g. `flutter run --release` (requires a physical device)
* Update the Xcode scheme to be `Release` not `Debug`

***

## Related pages

<Columns>
  <Card title="Mobile SDK setup" icon="wrench" href="./mobile-sdk-setup">
    Setup instructions for all supported mobile and cross-platform SDKs.
  </Card>

  <Card title="Capturing a debug log" icon="bug" href="./capturing-a-debug-log">
    How to capture SDK logs for troubleshooting.
  </Card>

  <Card title="Web Push troubleshooting" icon="globe" href="./troubleshooting-web-push">
    Troubleshoot web push notification issues.
  </Card>

  <Card title="Mobile SDK reference" icon="book" href="./mobile-sdk-reference">
    Full API reference for the OneSignal Mobile SDKs.
  </Card>
</Columns>

***

## FAQ

### What happens if I change my OneSignal App ID in my app?

Changing the OneSignal App ID in your app's initialization code will create a brand new user and push subscription under the new App ID when the user updates and opens the app to the latest version.

If your iOS bundle ID and/or Android package ID are the same, then the device will continue with the same push subscription status. The user data will be brand new i.e. you will need to add back your aliases, tags, email address, phone number on the new record.

If the iOS bundle ID or Android package ID are different, then this is a brand new app and should have different push certs/keys.

### Can OneSignal send push notifications in an on-premise closed network?

This can work as long as the computers on your closed network have access to the push gateway servers that you want to support:

* [https://support.apple.com/en-us/HT203609](https://support.apple.com/en-us/HT203609)
* [https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

If the network is completely disconnected from the Internet, push notifications cannot be delivered via the standard OS/browser services, which is what we support.

***


# .NET MAUI SDK setup
Source: https://documentation.onesignal.com/docs/en/net-sdk-setup

Instructions for adding OneSignal .NET SDK to your cross-platform MAUI app for iOS, Android, and Desktop.

<SdkReleasesIframe />

## Overview

This guide explains how to integrate OneSignal push notifications into a .NET MAUI application. It covers everything from installation to configuration and service worker management.

***

## Requirements

* .NET 7.0+
* Visual Studio 2019 or newer
* Configured OneSignal app and platform

**iOS Requirements**

* macOS with Xcode 14+ (setup instructions use Xcode 16.2)
* Device with iOS 12+, iPadOS 12+, or Xcode simulator running iOS 16.2+
* CocoaPods 1.16.2+

**Android Requirements**

* Android 7.0+ device or emulator with Google Play Store (Services) installed

### Configure your OneSignal app and platform

Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).

<Note>
  If your organization already has a OneSignal account, [ask to be invited](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Step-by-step setup instructions" icon="circle-chevron-down">
  <Steps>
    <Step title="Create or select your app">
      Create a new app by clicking **New App/Website**, or add a platform to an existing app in **Settings > Push & In-App**. Select the platform(s) you want to configure and click **Next: Configure Your Platform**.

      <Frame>
        <img alt="OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection" />
      </Frame>
    </Step>

    <Step title="Configure platform credentials">
      Enter the credentials for your platform:

      * **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
      * **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
      * **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
      * **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)

      Click **Save & Continue** after entering your credentials.
    </Step>

    <Step title="Save your App ID and install the SDK">
      Your **App ID** is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.

      <Frame>
        <img alt="OneSignal dashboard showing the App ID and team invite option after setup" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

***

## SDK Setup

### 1. Add SDK

Using the .NET CLI:

```http bash theme={null}
  dotnet add package OneSignalSDK.DotNet
```

### 2. Initialize SDK

<Warning>
  Xamarin Forms is no longer supported beyond version [5.0.2](https://github.com/OneSignal/OneSignal-DotNet-SDK/releases/tag/5.0.2) of our .NET SDK. Microsoft has guides on migrating to Maui [here](https://learn.microsoft.com/en-us/dotnet/maui/migration/?view=net-maui-8.0), if needed.
</Warning>

Initialize OneSignal in `App.xaml.cs` file.

Replace `YOUR_APP_ID` with your OneSignal App ID found in your OneSignal dashboard **Settings > [Keys & IDs](./keys-and-ids)**.

<Note>
  If you don't have access to the OneSignal app, ask your [Team Members](./manage-team-members) to invite you.
</Note>

```csharp C# theme={null}
using OneSignalSDK.DotNet;
using OneSignalSDK.DotNet.Core;
using OneSignalSDK.DotNet.Core.Debug;

public App() {
  InitializeComponent();

  // Enable verbose OneSignal logging to debug issues if needed.
  OneSignal.Debug.LogLevel = LogLevel.VERBOSE;

  // OneSignal Initialization
  OneSignal.Initialize("YOUR_APP_ID");

  // RequestPermissionAsync will show the notification permission prompt.
  // We recommend removing the following code and instead using an In-App Message to prompt for notification permission (See step 5)
  OneSignal.Notifications.RequestPermissionAsync(true);

  MainPage = new AppShell();
}
```

### 3. Adding an iOS Service Extension

Microsoft has a guide on generating a Notification Service Extension [here](https://learn.microsoft.com/en-us/xamarin/ios/platform/user-notifications/enhanced-user-notifications?tabs=windows#implementing-a-service-extension), using Visual Studio and Visual Studio for Mac, but does not have any guidance on how you would create this for VSCode at this time.

If you generate a service extension following the guide above, you can follow this the code in our sample project [found on Github](https://github.com/OneSignal/OneSignal-DotNet-SDK/blob/d8c41c4ddd2f605f6bb2efbceabc7a6f6a2df1c3/OneSignalSDK.dotnet.iOS/NotificationServiceExtension.cs#L13)

```csharp C# theme={null}
using System;
using Foundation;
using OneSignalSDK.DotNet;
using OneSignalSDK.DotNet.iOS;
using UIKit;
using UserNotifications;

namespace OneSignalNotificationServiceExtension
{
    [Register("NotificationService")]
    public class NotificationService : UNNotificationServiceExtension
    {
        Action<UNNotificationContent> ContentHandler { get; set; }
        UNMutableNotificationContent BestAttemptContent { get; set; }
        UNNotificationRequest ReceivedRequest { get; set; }

        protected NotificationService(IntPtr handle) : base(handle)
        {
            // Note: this .ctor should not contain any initialization logic.
        }

        public override void DidReceiveNotificationRequest(UNNotificationRequest request, Action<UNNotificationContent> contentHandler)
        {
            ReceivedRequest = request;
            ContentHandler = contentHandler;
            BestAttemptContent = (UNMutableNotificationContent)request.Content.MutableCopy();

            NotificationServiceExtension.DidReceiveNotificationExtensionRequest(request, BestAttemptContent, contentHandler);
        }

        public override void TimeWillExpire()
        {
            // Called just before the extension will be terminated by the system.
            // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.

            NotificationServiceExtension.ServiceExtensionTimeWillExpireRequest(ReceivedRequest, BestAttemptContent);

            ContentHandler(BestAttemptContent);
        }
    }
}
```

***

## Android setup

Make sure your OneSignal app is configured for the Android platform using your [Firebase credentials](/docs/en/android-firebase-credentials).

Set up your [notification icons](/docs/en/notification-icons) to match your app’s branding. If this step is skipped, a default bell icon will display for your push notifications.

**Build for Android**

At this point, you should be able to build and run your app on a physical Android device or emulator without issues.

<Check>
  After confirming that your Android build works:

  * Continue with the [iOS setup](#ios-setup), if applicable.
  * Or jump ahead to [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## iOS setup

Make sure your OneSignal app is configured for the iOS platform using either the [p8 Token (Recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 Certificate](/docs/en/ios-p12-generate-certificates).

Follow these steps to add push notifications to your iOS app, including support for [Badges](/docs/en/badges), [Confirmed receipt](/docs/en/confirmed-delivery), and images.

### 1. Add Push Notifications capability to app target

The [Push Notifications capability](https://developer.apple.com/documentation/UserNotifications/registering-your-app-with-apns#Enable-the-push-notifications-capability) allows your app to register a push token and receive notifications.

1. Open your app’s `.xcworkspace` file in Xcode.
2. Select **your app target > Signing & Capabilities**
3. Click **+ Capability** and add **Push Notifications** capability

<Frame>
  <img />
</Frame>

### 2. Add Background Modes capability to app target

This enables your app to wake in the background when push notifications arrive.

1. Add [Background Modes](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app) capability
2. Enable **Remote notifications**

<Frame>
  <img />
</Frame>

### 3. Add app target to App Group

[App Groups](https://developer.apple.com/documentation/xcode/configuring-app-groups/#Create-App-Groups-for-all-other-platforms) allow data sharing between your app and the Notification Service Extension. Required for confirmed receipt and Badges.

<Tabs>
  <Tab title="If you do NOT have an App Group configured">
    1. Add **App Groups** capability
    2. In the App Groups capability click **+**
    3. Add a new container ID in format: `group.your_bundle_id.onesignal`

    * Keep **group.** and **.onesignal** prefix and suffix. Replace **`your_bundle_id`** with your app's bundle identifier.
    * For example, bundle identifier `com.onesignal.MyApp`, will have the container name `group.com.onesignal.MyApp.onesignal`.

    <Frame>
      <img />
    </Frame>

    <Warning> Your App Group name must exactly match your bundle ID’s spelling and capitalization across all targets. </Warning>
  </Tab>

  <Tab title="If you DO have an App Group">
    1. Open your **App Target** and **OneSignalNotificationServiceExtension Target's** `Info.plist`
    2. Add a new property to the `Info.plist` for both targets:

    * **Key:** `OneSignal_app_groups_key`
    * **Value:** Your existing App Group name (e.g., `group.your-custom-group-id`)

    ```xml XML theme={null}
    <key>OneSignal_app_groups_key</key>
    <string>group.your-custom-group-id</string>
    ```

    <Frame>
      <img />
    </Frame>

    <Warning>
      Make sure to update the `OneSignal_app_groups_key` in **both** the App Target **and** OneSignalNotificationServiceExtension Target's `Info.plist`!
    </Warning>
  </Tab>
</Tabs>

### 4. Add Notification Service Extension

The [Notification Service Extension (NSE)](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications) enables rich notifications and confirmed receipt analytics.

1. In Xcode: **File > New > Target...**
2. Select **Notification Service Extension**, then **Next**.
3. Set the product name to `OneSignalNotificationServiceExtension` and press **Finish**.
4. Press **Don't Activate** on the Activate scheme prompt.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

Set the OneSignalNotificationServiceExtension **Minimum Deployment Target** to match your main app (iOS 15+ recommended).

<Info> If you're using CocoaPods, set the deployment version in your Podfile as well. </Info>

<Frame>
  <img />
</Frame>

### 5. Add NSE target to app group

Use the same App Group ID you added in step 3.

1. Go to **OneSignalNotificationServiceExtension > Signing & Capabilities**
2. Add **App Groups**
3. Add the exact same group ID

<Warning>
  If you are using a custom App Group name and not `group.your_bundle_id.onesignal` then make sure to add your App Group ID to both the App Target and OneSignalNotificationServiceExtension Target's `Info.plist`! See [step 3](#3-add-app-target-to-app-group) for more information.
</Warning>

<Frame>
  <img />
</Frame>

### 6. Update NSE code

1. Navigate to the **OneSignalNotificationServiceExtension** folder
2. Replace the contents of the `NotificationService.swift` or `NotificationService.m` file with the following:

<Frame>
  <img />
</Frame>

<CodeGroup>
  ```swift Swift theme={null}
  import UserNotifications
  import OneSignalExtension

  class NotificationService: UNNotificationServiceExtension {
      var contentHandler: ((UNNotificationContent) -> Void)?
      var receivedRequest: UNNotificationRequest!
      var bestAttemptContent: UNMutableNotificationContent?

      // Note this extension only runs when `mutable_content` is set
      // Setting an attachment or action buttons automatically sets the property to true
      override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
          self.receivedRequest = request
          self.contentHandler = contentHandler
          self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

          if let bestAttemptContent = bestAttemptContent {
              // DEBUGGING: Uncomment the 2 lines below to check this extension is executing
  //            print("Running NotificationServiceExtension")
  //            bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

              OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
          }
      }

      override func serviceExtensionTimeWillExpire() {
          // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
          if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
              OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
              contentHandler(bestAttemptContent)
          }
      }
  }
  ```

  ```objectivec Objective-C theme={null}
  #import <OneSignalExtension/OneSignalExtension.h>
  #import "NotificationService.h"

  @interface NotificationService ()

  @property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
  @property (nonatomic, strong) UNNotificationRequest *receivedRequest;
  @property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

  @end

  @implementation NotificationService

  // Note, this extension only runs when mutable-content is set
  // Setting an attachment or action buttons automatically adds this
  - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
      self.receivedRequest = request;
      self.contentHandler = contentHandler;
      self.bestAttemptContent = [request.content mutableCopy];

      // DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is executing
  //     NSLog(@"Running NotificationServiceExtension");
  //     self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];

      [OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
                         withMutableNotificationContent:self.bestAttemptContent
                                     withContentHandler:self.contentHandler];
  }

  - (void)serviceExtensionTimeWillExpire {
      // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.

      [OneSignalExtension serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];

      self.contentHandler(self.bestAttemptContent);
  }

  @end
  ```
</CodeGroup>

You should see an error because the OneSignal package is not installed. This will be resolved in the next step.

<Frame>
  <img />
</Frame>

### 7. Add OneSignal to the NSE target

<Note>
  If your SDK uses Swift Package Manager (SPM) for iOS dependencies, you can skip this step. The OneSignal package is already resolved and available to all targets.
</Note>

Update your `ios/Podfile` to include:

<CodeGroup>
  ```ruby Podfile theme={null}
  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```

  ```ruby Example theme={null}
  target 'MyApp' do
    config = use_native_modules!

    use_react_native!(
      :path => config[:reactNativePath],
      # An absolute path to your application root.
      :app_path => "#{Pod::Config.instance.installation_root}/.."
    )

    post_install do |installer|
      # https://github.com/facebook/react-native/blob/main/packages/react-native/scripts/react_native_pods.rb#L197-L202
      react_native_post_install(
        installer,
        config[:reactNativePath],
        :mac_catalyst_enabled => false,
        # :ccache_enabled => true
      )
    end
  end

  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```
</CodeGroup>

Open your project in the terminal and run:

```shell shell  theme={null}
cd ios pod install cd .. 
```

#### Common pod install errors

You may run into the following errors, here is how you can resolve them.

<Accordion
  title="ArgumentError - \[Xcodeproj] Unable to find compatibility version string for
object version `70`."
>
  CocoaPods relies on the `xcodeproj` Ruby gem to read your Xcode project files. As of now, the latest `xcodeproj` release does not recognize object version 70, which was introduced by Xcode 16. So when CocoaPods tries to open your `.xcodeproj` file, it crashes with this error.

  1. Close Xcode.
  2. Navigate to your project's `ios/<your-app>.xcodeproj/project.pbxproj` file.
  3. Change this line: `objectVersion = 70;`
  4. Replace it with: `objectVersion = 55;`
  5. Save, close, and rerun `cd ios pod install cd ..`
</Accordion>

### Build for iOS

You should now be able to build and run your app on a real iOS device or iOS simulator (16.2+).

#### Common iOS build errors

<Accordion title="commandPhaseScript Execution exited with a non-zero code">
  1. Delete your Podfile.lock
  2. Delete your Pods folder
  3. Delete your .xcworkspace
  4. Pod install
  5. Cmd + Shift + K to Clean the build and then retry building

  If these steps do not resolve the error, build directly from the Xcode, then find the build error in the report navigator pictured below.

  <img />
</Accordion>

<Accordion title="Cycle Inside... building could produce unreliable results.">
  You may see this error when building with Xcode 15+, due to a default configuration change affecting cross platform systems.

  1. Open your `.xcworkspace` folder in Xcode and navigate to **your app target > Build Phases**.
  2. You should have a phase called **"Embed Foundation Extensions"** or **"Embed App Extensions"**.
  3. Drag and move this build phase to *above* **"Run Script"**.
  4. Build and run your app. The error should be resolved.

  <Frame>
    <img />
  </Frame>

  <Frame>
    <img />
  </Frame>
</Accordion>

<Accordion title="PBXGroup Error">
  <Info>
    RuntimeError - `PBXGroup` attempted to initialize an object with unknown ISA `PBXFileSystemSynchronizedRootGroup` from attributes: `{"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}`
  </Info>

  Fix:

  1. Find the folder listed under "path" in the error
  2. In Xcode project sidebar, right-click the folder
  3. Select **Convert to Group**

  <Frame>
    <img />
  </Frame>

  <br />

  <Frame>
    <img />
  </Frame>
</Accordion>

<Check>
  After confirming that your iOS build works, continue with [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications, subscription registration, and in-app messaging.

<Warning>
  If you are testing with an Android emulator, it should start with a cold boot.

  1. Go to **Device Manager** in Android Studio.
  2. Select your emulator device and click **Edit**.
  3. Go to **Additional Settings** or **More**.
  4. Set the **Boot option** to **Cold Boot**.
  5. Save changes and restart the emulator.
</Warning>

### Check mobile subscriptions

<Steps>
  <Step title="Launch your app on a test device.">
    The native push permission prompt should appear automatically if you added the `requestPermission` method during initialization.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    Before accepting the prompt, check the OneSignal dashboard:

    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status "Never Subscribed".

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Return to the app and tap Allow on the prompt." />

  <Step title="Refresh the OneSignal dashboard Subscription's page.">
    The subscription's status should now show **Subscribed**.

    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a [mobile subscription](/docs/en/subscriptions).
    Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a segment of test users.
    We can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

    ```curl theme={null}
    curl -X \
    POST --url 'https://api.onesignal.com/notifications' \
     --header 'content-type: application/json; charset=utf-8' \
     --header 'authorization: Key YOUR_APP_API_KEY' \
     --data \
     '{
      "app_id": "YOUR_APP_ID",
      "target_channel": "push",
      "name": "Testing basic setup",
      "headings": {
      	"en": "👋"
      },
      "contents": {
        "en": "Hello world!"
      },
      "included_segments": [
        "Test Users"
      ],
      "ios_attachments": {
        "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      },
      "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
    }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification with an image included:

    <Frame>
      <img />
    </Frame>

    <Info>Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Info>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats.

    You should see the **confirmed** stat, meaning the device received the push.
    <Check>You have successfully sent a notification via our API to a segment.</Check>

    <Warning>
      * No image received? Your [Notification Service Extension](#ios-setup) might be missing.
      * No confirmed receipt? Review the troubleshooting guide [here](/docs/en/confirmed-delivery#troubleshooting-confirmed-delivery).
      * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
    </Warning>
  </Step>
</Steps>

### Send an in-app message

[In-app messages](/docs/en/in-app-messages-setup) let you communicate with users while they are using your app.

<Steps>
  <Step title="Close or background your app on the device.">
    This is because users must meet the in-app audience criteria *before* a new session starts. In OneSignal, a new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds. For more details, see our guide on [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
  </Step>

  <Step title="Create an in-app message.">
    * In your OneSignal dashboard, navigate to **Messages > In-App > New In-App**.
    * Find and select the **Welcome** message.
    * Set your Audience as the **Test Users** segment we used previously.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Customize the message content if desired.">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Set Trigger to 'On app open'." />

  <Step title="Schedule frequency.">
    Under **Schedule > How often do you want to show this message?** select **Every time trigger conditions are satisfied**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Make message live.">
    Click **Make Message Live** so it is available to your Test Users each time they open the app.
  </Step>

  <Step title="Open the app and see the message.">
    After the in-app message is live, open your app. You should see it display:

    <Frame>
      <img />
    </Frame>

    <Warning>
      Not seeing the message?

      * Start a new session
        * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
        * For more, see [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
      * Still in the `Test Users` segment?
        * If you reinstalled or switched devices, re-add the device to [Test Users](#set-up-test-users) and confirm it's part of the Test Users segment.
      * Having issues?
        * Follow [Getting a Debug Log](/docs/en/capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
    </Warning>
  </Step>
</Steps>

<Check>
  You have successfully setup the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](/docs/en/subscriptions), setting [Test Users](/docs/en/find-set-test-subscriptions), and creating [Segments](/docs/en/segmentation).
  * Sending [Push](/docs/en/push) with images and [Confirmed receipt](/docs/en/confirmed-delivery) using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](/docs/en/in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

***

## User identification

Previously, we demonstrated how to create mobile [Subscriptions](/docs/en/subscriptions). Now we'll expand to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We'll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with our SDK's [`login` method](/docs/en/mobile-sdk-reference#login-external-id) each time they are identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with our SDK [`addTag` and `addTags` methods](/docs/en/mobile-sdk-reference#data-tags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img />
</Frame>

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

### Add email and/or SMS subscriptions

Earlier we saw how our SDK creates mobile subscriptions to send push and in-app messages. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/mobile-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/mobile-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/mobile-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/mobile-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

See our Privacy & security docs for more on:

* [Data collected by the SDK](/docs/en/data-collected-by-the-onesignal-sdk)
* [Handling personal data](/docs/en/handling-personal-data)

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](/docs/en/prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners for you to hook into. See our [SDK reference guide](/docs/en/mobile-sdk-reference) for more details.

### Push notification events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-push): Detect when a notification is tapped. Helpful for [Deep Linking](/docs/en/deep-linking).
* [`addForegroundLifecycleListener()`](/docs/en/mobile-sdk-reference#addforegroundlifecyclelistener-push): Control how notifications behave in foreground.

For full customization, see [Mobile Service Extensions](/docs/en/service-extensions).

### User state changes

* [`addObserver()` for user state](/docs/en/mobile-sdk-reference#addobserver-user-state): Detect when the External ID is set.
* [`addPermissionObserver()`](/docs/en/mobile-sdk-reference#addpermissionobserver-push): Track the user's specific interaction with the native push permission prompt.
* [`addObserver()` for push subscription](/docs/en/mobile-sdk-reference#addobserver-push-subscription-changes): Track when the push subscription status changes.

### In-app message events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Handle in-app click actions. Ideal for deep linking or tracking events.
* [`addLifecycleListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Track full lifecycle of in-app messages (shown, clicked, dismissed, etc.).

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

* [🔁 Migrating to OneSignal from another service](/docs/en/migrating-to-onesignal)
* [🌍 Location tracking](/docs/en/mobile-sdk-reference#location)
* [🔗 Deep Linking](/docs/en/deep-linking)
* [🔌 Integrations](/docs/en/integrations)
* [🧩 Mobile Service Extensions](/docs/en/service-extensions)
* [🛎️ Action buttons](/docs/en/action-buttons)
* [🌐 Multi-language messaging](/docs/en/multi-language-messaging)
* [🛡️ Identity Verification](/docs/en/identity-verification)
* [📊 Custom Outcomes](/docs/en/custom-outcomes)
* [📲 Live Activities](/docs/en/live-activities)

### Mobile SDK setup & reference

Make sure you've enabled all key features by reviewing the [Mobile push setup](/docs/en/mobile-push-setup) guide.

For full details on available methods and configuration options, visit the [Mobile SDK reference](/docs/en/mobile-sdk-reference).

<Check>Congratulations! You've successfully completed the Mobile SDK setup guide.</Check>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# News and media strategies
Source: https://documentation.onesignal.com/docs/en/news-and-media-industry

Implementation hub for news and media messaging — user IDs, category interest Tags, reading-behavior Custom Events, segments, and Journey playbooks for audience growth, paywall conversion, and re-engagement.

A news and media messaging strategy targets sites and apps where success depends on session frequency, category-specific opt-in, paywall conversion, and subscriber retention. If you publish content across multiple verticals and your growth depends on bringing readers back daily, this guide is for you.

This page is the implementation hub: which user identifier to set, what reading and category data to capture, which segments to build, and which Journeys drive opt-in, paywall conversion, and re-engagement. Each section links to the canonical docs for deeper detail.

<Columns>
  <Card title="Acquire" icon="bell" href="./welcome-journey-news-media">
    Convert anonymous traffic into opted-in readers with the Category Prompt and a category-aware Welcome Journey.
  </Card>

  <Card title="Convert" icon="circle-dollar-to-slot" href="./mobile-first-journeys#welcome-journeys">
    Turn repeat paywall hitters into subscribers with a graduated cadence of value reminders and offers.
  </Card>

  <Card title="Retain" icon="rotate-left" href="./mobile-first-journeys#retention-journeys">
    Bring back inactive readers on a 7 / 14 / 30 day cadence and re-engage lapsed subscribers separately.
  </Card>
</Columns>

## Implementation roadmap

Work through these steps in order. Each one links to its section below.

<Steps>
  <Step title="Assign External IDs">
    Set a stable, app-side identifier on every authenticated reader so push, email, and SMS tie to one profile across reinstalls and devices. [Jump to section](#identify-your-readers-with-external-ids).
  </Step>

  <Step title="Add reader properties as Tags">
    Start with `account_type`, category-interest Tags (`cat_breaking_news`, `cat_sports`, etc.), and `last_visit_date`. These power your category routing and re-engagement segments. [Jump to section](#tags).
  </Step>

  <Step title="Send reader actions as Custom Events">
    Fire `article_read`, `paywall_hit`, `newsletter_subscribed`, and `subscription_started` from your site or app. [Jump to section](#custom-events).
  </Step>

  <Step title="Build lifecycle Segments">
    Audience groups such as Active readers, Paywall hitters, Subscribers, and Inactive readers (7 / 14 / 30 days). [Jump to section](#segments).
  </Step>

  <Step title="Create lifecycle Journeys">
    Category opt-in, paywall conversion, breaking news alerts, and re-engagement. [Jump to section](#journey-examples).
  </Step>
</Steps>

<Frame>
  <iframe title="Prompting best practices for news and media sites" />
</Frame>

## Identify your readers with External IDs

External IDs preserve identity across installs and tie push, email, and SMS to one reader profile. Use the unique identifier from your CMS, account, or auth platform — for example, your site's `user_id`, an Auth0 `uid`, or your subscription-platform `customer_id`.

Set the External ID at signup, on every login, and on session resume. The OneSignal SDK does not assign it for you, and assigning it late or sporadically breaks attribution between category opt-in, paywall hits, and downstream subscription conversion.

For anonymous readers (the majority of news traffic), the OneSignal-assigned anonymous user ID still ties Tags and behavior to a Subscription. Promote anonymous profiles to authenticated profiles by setting the External ID the moment a reader logs in or subscribes — that single call merges the anonymous activity with the new identity.

<Card title="External ID setup" icon="id-card" href="./users#external-id">
  Assign a unique reader identifier so category preferences, reading history, and notifications follow the reader across devices.
</Card>

## Recommended data

Tags persist on the reader profile (current state); Custom Events record discrete moments (what just happened). Use both — Tags drive category routing and segmentation, Custom Events trigger Journey entry and Wait Until conditions.

News and media leans heavily on Tags for category opt-in (one Tag per topic) so you can target exactly the readers who care about a given story, and on Custom Events for reading behavior (`article_read`, `paywall_hit`) so retention and conversion Journeys react to what readers actually do.

### Tags

Tags persist on the reader profile and are used for segmentation and personalization. Two conventions apply depending on the Tag's role:

* **Toggle Tags** (single binary signal — newsletters, `subscription_auto_renew`): set the Tag to `1` when true and **remove it** when false. Segment with "tag exists" rather than storing `0`/`false`.
* **Checklist Tags** (state of every option matters — categories): set Tags only when the reader actively engages with category preferences — for example, when the [Category Prompt](./permission-requests) is dismissed or when the reader visits your preference center page. Don't set them up front for every reader. Choose the default value to match the model you want: `0` for explicit opt-in (reader ticks to receive each category) or `1` for opt-out (categories are enabled by default; reader unticks to remove). Use `tag exists` to find readers who have engaged with preferences at all, and `tag = 1` to target the opted-in followers of a specific category.

<Tip>
  If you only set up four kinds of Tags, start with `account_type`, your category-interest Tags, `last_visit_date`, and `first_name`. They power most starter Journeys.
</Tip>

#### Subscription and lifecycle state

| Tag                         | Values                                                    | Use                                                                                                                                                                                 |
| :-------------------------- | :-------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_type`              | `free` / `metered` / `paid` / `lapsed`                    | Paywall and lifecycle state — drives Journey entry, exit, and audience filters. Set only on identified users (External ID + completed profile); leave unset for anonymous visitors. |
| `subscription_tier`         | `digital` / `print_plus_digital` / `premium` (your tiers) | Tailor offers and disclosures by subscription tier.                                                                                                                                 |
| `subscription_start_date`   | Unix timestamp (seconds)                                  | Drive anniversary and tenure-based messaging. Use OneSignal [time operators](./time-operators) to compare against the current time.                                                 |
| `subscription_renewal_date` | Unix timestamp (seconds)                                  | Drive renewal-window messaging (e.g., "renews in 7 days") and post-expiration win-back. Pair with [time operators](./time-operators).                                               |
| `subscription_auto_renew`   | `1` (set when auto-renew is on)                           | Suppress renewal-prompt messaging for subscribers who will auto-renew. Remove the Tag when the reader turns auto-renew off — that is your highest-priority retention moment.        |

#### Category interests

One Tag per category lets you target precisely the readers who opted in to a topic. Set each `cat_*` Tag the moment the reader engages with category preferences — when the [Category Prompt](./permission-requests) is dismissed, or when they first visit your preference center page. Pick the default value to match your model: `0` for explicit opt-in (reader must tick to receive) or `1` for opt-out (all enabled by default, reader unticks to remove). Update the Tag whenever the reader changes their choice. Segment with `tag exists` to find readers who have made a choice at all, or with `tag = 1` to target the opted-in followers of a category. See [Auto-segment users by page visit](./auto-segment-users-by-page-visit) for adding category Tags automatically based on which sections a reader browses.

| Tag                                              | Values    | Use                           |
| :----------------------------------------------- | :-------- | :---------------------------- |
| `cat_breaking_news`                              | `0` / `1` | Target breaking news alerts.  |
| `cat_world` / `cat_local` / `cat_politics`       | `0` / `1` | Per-vertical opt-in segments. |
| `cat_business` / `cat_technology` / `cat_sports` | `0` / `1` | Per-vertical opt-in segments. |
| `cat_culture` / `cat_lifestyle` / `cat_opinion`  | `0` / `1` | Per-vertical opt-in segments. |

#### Newsletter subscriptions

One Tag per newsletter, separate from on-site category Tags. A reader can opt in to the *Morning Briefing* newsletter without opting in to the broader `cat_breaking_news` push category — keep the two namespaces distinct so Journeys target the right channel and product. Set the Tag from your `newsletter_subscribed` event handler and remove it on `newsletter_unsubscribed`.

| Tag                                      | Values                    | Use                                                                                      |
| :--------------------------------------- | :------------------------ | :--------------------------------------------------------------------------------------- |
| `nl_morning_briefing`                    | `1` (set when subscribed) | Target morning newsletter subscribers; gate exit from the newsletter-onboarding Journey. |
| `nl_breaking_daily` / `nl_evening_recap` | `1` (set when subscribed) | Per-newsletter opt-in segments for cross-promotion and re-engagement.                    |
| `nl_weekly_<vertical>`                   | `1` (set when subscribed) | Vertical-specific weekly newsletters (e.g., `nl_weekly_politics`, `nl_weekly_business`). |

#### Engagement and behavior

| Tag                          | Values                              | Use                                                                                                                                                                                                 |
| :--------------------------- | :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `last_visit_date`            | Unix timestamp (seconds)            | Drive recency-based re-engagement at 7 / 14 / 30 days.                                                                                                                                              |
| `total_articles_read`        | integer (as string)                 | Power active-reader segments and habit-strength signals.                                                                                                                                            |
| `favorite_section`           | string (e.g., `politics`, `sports`) | Personalize subject lines and push copy with the reader's most-read section.                                                                                                                        |
| `metered_articles_remaining` | integer (as string)                 | Articles left in the reader's metered allowance this period. Drives proactive paywall-approach messaging (e.g., "1 free article left this month") — a higher-converting moment than after the wall. |
| `paywall_hits_30d`           | integer (as string)                 | Identify readers who repeatedly hit the paywall — high-intent conversion targets.                                                                                                                   |

#### Personalization

| Tag                 | Values | Use                                                                                                                                                                                                         |
| :------------------ | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `first_name`        | string | Personalize message content (e.g., `Hi {{ first_name }}`).                                                                                                                                                  |
| `subscription_page` | string | Tag the page the reader subscribed from — see [Tag with subscription page](./auto-segment-users-by-page-visit#tag-at-subscription-one-time-web-only). Useful for routing source-specific welcome messaging. |

<Card title="Add user data tags" icon="tags" href="./add-user-data-tags">
  Add key-value pairs to reader profiles for category routing, segmentation, and personalization.
</Card>

### Custom Events

Send a Custom Event for each reader action you want to react to. Events are stored shorter-term than Tags but can carry properties (article ID, category, author, paywall threshold), making them ideal for Journey entry triggers and Liquid personalization. Use lowercase `snake_case` for event names and keep them consistent across your site and apps.

| Event                                               | Use case                                                                                                              |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `signup_completed`                                  | Welcome Journey entry.                                                                                                |
| `article_read`                                      | Engagement signal. Carries `article_id`, `category`, and `author` as properties for personalization and segmentation. |
| `paywall_hit`                                       | Paywall conversion Journey entry. Carries the article that triggered the wall as a property.                          |
| `subscription_started`                              | Exit paywall conversion Journey; thank-you and onboarding message.                                                    |
| `subscription_cancelled`                            | Win-back Journey entry.                                                                                               |
| `newsletter_subscribed` / `newsletter_unsubscribed` | Manage per-newsletter Tags and exit/reentry of newsletter-specific Journeys.                                          |
| `comment_posted` / `share_clicked`                  | Engagement signals — useful for power-reader and viral-loop Journeys.                                                 |
| `breaking_news_published`                           | Backend-fired event that triggers a category-targeted broadcast Journey.                                              |

<Card title="Custom Events" icon="bolt" href="./custom-events">
  Capture reader actions and use them to trigger Journeys or Wait Until steps.
</Card>

### Segments

Combine Tags and Custom Events into segments. Start with these eight:

| Segment                   | Definition                                                                                         |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| New visitors              | `First Session < 7 days ago`. Onboarding and category opt-in target.                               |
| Active readers            | `article_read` in the last 7 days, with N+ events. Daily or near-daily core.                       |
| Casual readers            | `Last Session < 14 days ago` AND fewer than N `article_read` events. Habit-formation target.       |
| Paywall hitters           | `paywall_hit` in the last 30 days AND `account_type = "free"`. Highest-intent conversion segment.  |
| Subscribers               | `account_type = "paid"`. Retention and engagement target.                                          |
| Lapsed subscribers        | `account_type = "lapsed"`. Win-back audience — keep separate from general re-engagement.           |
| Inactive 7 / 14 / 30 days | `Last Session > 7 / 14 / 30 days ago`. Three re-engagement tiers with progressively stronger asks. |
| Category followers        | `cat_<category> = "1"`. One segment per opted-in category for breaking news targeting.             |

<Note>
  Mature news setups run 30+ segments split by section, geography, subscription tier, device, and source channel. Start with the eight above plus a segment per top-level category, then add depth (paywall threshold, newsletter cohort, time-of-day reader) as your Journeys grow.
</Note>

<Card title="Segmentation" icon="users" href="./segmentation">
  Group readers by shared characteristics to target Journeys and category broadcasts.
</Card>

## Journey examples

With Tags, Custom Events, and segments in place, build Journeys against them. News and media Journeys mix channels by intent — push for breaking news and time-sensitive nudges, in-app for category opt-in and paywall messaging, email for newsletters and longer-form re-engagement, and SMS sparingly for critical subscriber communications. The lifecycle has five core flows:

<Columns>
  <Card title="Category opt-in onboarding" icon="newspaper" href="./welcome-journey-news-media">
    Welcome Journey that nudges readers to complete their profile and pick categories using Yes/No branches and Wait Until steps.
  </Card>

  <Card title="Breaking news broadcasts" icon="bolt" href="./event-driven-journeys">
    Backend-fired `breaking_news_published` events targeted to readers with the matching `cat_*` Tag.
  </Card>

  <Card title="Paywall conversion" icon="circle-dollar-to-slot" href="./mobile-first-journeys#welcome-journeys">
    Convert repeat `paywall_hit` readers with a graduated cadence of value reminders and offers.
  </Card>

  <Card title="Re-engagement (7 / 14 / 30 day)" icon="rotate-left" href="./mobile-first-journeys#retention-journeys">
    Bring back inactive readers with category-aware content and offers calibrated to inactivity tier.
  </Card>

  <Card title="Subscriber win-back" icon="arrow-rotate-right" href="./mobile-first-journeys#retention-journeys">
    Re-engage `lapsed` readers with renewal offers separate from general re-engagement.
  </Card>
</Columns>

<Frame>
  <iframe title="Sending news updates based on reader interests" />
</Frame>

### Common news and media patterns

* **Capture category interests at first prompt.** Use the [Category Prompt](./permission-requests) to combine push opt-in with category selection in a single moment. Every category presented gets a `cat_*` Tag at prompt time — `1` for the categories the reader ticks, `0` for the rest — exactly the data you need for targeted broadcasts. Apps that segment broadcasts by interest typically see materially higher click-through rates than apps that send to all opt-ins.
* **Auto-tag readers based on what they read.** For web, [Tag page visits](./auto-segment-users-by-page-visit) automatically applies a `cat_*` Tag the first time (or N-th time) a reader visits a section. This builds an interest profile even for readers who never explicitly opt in, and turns passive browsing into actionable segmentation.
* **Tag with subscription source.** [Tag with subscription page](./auto-segment-users-by-page-visit#tag-at-subscription-one-time-web-only) records where a reader subscribed from. Source-aware welcome messaging materially outperforms generic copy — a reader who opted in from a sports article responds to different copy than one who opted in from politics.
* **Three-tier re-engagement cadence.** Set up three inactivity segments at **7, 14, and 30 days** and run a separate Journey for each. The 7-day Journey leads with category-aware content; the 14-day Journey adds a value reminder or paywall promo; the 30-day Journey is the last call before treating the reader as churned. See [Retention Journeys](./mobile-first-journeys#retention-journeys) for the Journey shape.
* **Use the Custom Link Prompt for less intrusive opt-in.** Place a [Custom Link Prompt](./permission-requests) inline with content (e.g., "Get notified when we publish new pieces in this section") instead of a modal. This converts higher on long-form content where the reader is already invested.

<Frame>
  <iframe title="Re-engaging readers with push and in-app messages" />
</Frame>

Effective re-engagement copy includes:

<Columns>
  <Card icon="newspaper">
    **Recent breaking news** in the reader's opted-in categories
  </Card>

  <Card icon="list">
    **Top stories** from one of their tracked categories of interest
  </Card>

  <Card icon="gift">
    **Limited-time offers** for paywalled content access
  </Card>

  <Card icon="tags">
    **Discounts** on paid memberships or annual upgrades
  </Card>
</Columns>

Measure success by category opt-in rate, push CTR by category, paywall-to-subscription conversion rate, and inactive-reader return rate at 7 / 14 / 30 days — not just opens or total volume.

## FAQ

### How is this different from the Mobile-first strategy?

[Mobile-first](./mobile-first) targets subscription, freemium, and trial-driven apps where success is measured by trial-to-paid conversion. News and media overlaps on the data foundation (External IDs, Tags, Custom Events, segments) but adds category interest as a first-class concept and treats paywall conversion as the primary monetization moment. Most news traffic is also web-first and largely anonymous, which shifts the channel mix toward web push and category-aware broadcasts.

### Should I use a Tag or a Custom Event for category interest?

Use a **Tag** (`cat_breaking_news = "1"`). Category opt-in is a persistent state — the reader either wants breaking news alerts or doesn't — and Tags are designed for state-based segmentation. Custom Events represent discrete moments (the act of reading an article in that category, the act of opting in), which you may also want to send for analytics and funnel tracking.

### How many categories should I expose at first prompt?

Three to seven top-level categories work best. Fewer than three feels like too narrow a choice; more than seven overwhelms the prompt and depresses opt-in. Use the categories that match your top-level navigation. Sub-categories can be added later via in-app settings or auto-tagged from page visits.

### How do I avoid over-messaging readers who opt in to many categories?

Apply a Journey-level **frequency cap** on broadcast Journeys (e.g., at most one push per reader per 4 hours), and use a `Last Push Sent` filter to suppress sends to readers who received a recent push in the same or related category. Alternatively, set a daily cap on the segment side. Over-messaging is the fastest way to lose hard-won opt-ins.

### Do I need data integrations to use these Journeys?

No. You can build basic re-engagement and category-aware breaking news using the [Category Prompt](./permission-requests) and dashboard-only segments like "First Session" and "Last Session." Custom Events and the auto-tagging integrations give you precise reading-behavior triggers, but they are not required to ship the first version.

### What about apps that mix news with other formats (e.g., video, podcasts)?

The data foundation extends naturally. Add format Tags (`format_video = "1"`, `format_podcast = "1"`) alongside category Tags and use them as filters on top of the base segments. Each format typically gets its own Custom Events (`video_played`, `podcast_episode_completed`) that feed into the same lifecycle Journeys with format-specific copy.

## Related pages

<Columns>
  <Card title="Permission requests" icon="bell" href="./permission-requests">
    Configure the Category Prompt and Custom Link Prompt referenced throughout this guide.
  </Card>

  <Card title="Auto-segment by page visit" icon="file-lines" href="./auto-segment-users-by-page-visit">
    Tag readers with `cat_*` based on the sections they actually browse.
  </Card>

  <Card title="Mobile-first lifecycle Journeys" icon="route" href="./mobile-first-journeys">
    Welcome and retention Journey patterns adaptable to news onboarding and re-engagement.
  </Card>

  <Card title="Event-driven Journeys" icon="bolt" href="./event-driven-journeys">
    Trigger broadcasts from `breaking_news_published` and other backend-fired events.
  </Card>

  <Card title="Email confirmed opt-in" icon="envelope" href="./double-opt-in-email">
    Reduce bounces and improve deliverability with a double opt-in flow for newsletter signups.
  </Card>

  <Card title="Preference center" icon="sliders" href="./preference-center">
    Let readers manage which categories, newsletters, and channels they receive.
  </Card>
</Columns>


# OneSignal service worker
Source: https://documentation.onesignal.com/docs/en/onesignal-service-worker

Set up and configure the OneSignalSDKWorker.js file so your website can receive and display web push notifications through OneSignal.

The OneSignal service worker (`OneSignalSDKWorker.js`) is a JavaScript file hosted on your server that is required for web push notifications. It enables your site to receive and display notifications, even when the user is not on your page.

<Frame>
  <img alt="Diagram showing the OneSignal service worker receiving a push event and displaying a notification" />
</Frame>

<Note>
  If you use the WordPress or Shopify integration, the service worker is added automatically. Skip this guide and return to [WordPress setup](./wordpress) or [Shopify setup](./shopify).
</Note>

## Service worker setup

Create a dedicated `OneSignalSDKWorker.js` file for OneSignal push notifications. If your site already has a service worker and you want to use a single file, see [Combining multiple service workers](#combining-multiple-service-workers) instead.

<Steps>
  <Step title="Download or create OneSignalSDKWorker.js">
    Download the file from the OneSignal dashboard during [Web SDK setup](./web-sdk-setup) or [from GitHub](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip).

    Alternatively, create a file named `OneSignalSDKWorker.js` with the following single line of code:

    ```javascript theme={null}
    importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
    ```

    <Note>
      You can rename the file if needed (e.g., `onesignalsdkworker.js`, `ossw.js`). If you do, replace `OneSignalSDKWorker.js` in this guide with your filename.
    </Note>
  </Step>

  <Step title="Upload to your web server">
    Place `OneSignalSDKWorker.js` on your server so it is publicly accessible over HTTPS. The file must not require authentication or login to access.

    **Recommended:** Host the file in a dedicated subdirectory that never serves pages, such as `/push/onesignal/`. This avoids conflicts with other service workers on your site (e.g., a PWA or AMP service worker) and keeps the URL path stable.

    * Example: `https://yoursite.com/push/onesignal/OneSignalSDKWorker.js`

    **Alternative:** The OneSignal Web SDK defaults to looking for the file at your site root (`https://yoursite.com/OneSignalSDKWorker.js`). You can upload the file to the root directory, but it may conflict with other service workers that need root scope. If you use a PWA, place `OneSignalSDKWorker.js` in a subdirectory instead.

    <Warning>
      Choose a **permanent** URL path. Once a browser registers a service worker at a given URL, changing that URL requires a [migration](#migration-guide).
    </Warning>
  </Step>

  <Step title="Verify the file is accessible">
    Navigate to the file URL in your browser (e.g., `https://yoursite.com/push/onesignal/OneSignalSDKWorker.js`). You should see the `importScripts` line from the first step:

    <Frame>
      <img alt="Browser displaying the single importScripts line inside OneSignalSDKWorker.js" />
    </Frame>

    If you see a 404 error, a blank page, or a login prompt, the file is not correctly uploaded or is behind authentication.
  </Step>

  <Step title="Configure the SDK path (subdirectory only)">
    If you placed the file at your site root, no additional configuration is needed — skip to the next step.

    If you placed the file in a subdirectory, tell the SDK where to find it:

    #### Typical site setup

    1. In the OneSignal dashboard, go to **Settings > Push & In-App > Web Settings**.
    2. Under **Advanced Push Settings**, enable **Customize service worker paths and filenames**.

    <Frame>
      <img alt="OneSignal dashboard fields for service worker path, filename, and registration scope" />
    </Frame>

    | Field                                 | Description                                                                                                                                       | Example                 |
    | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
    | **Path to service worker files**      | Directory where `OneSignalSDKWorker.js` is hosted.                                                                                                | `/push/onesignal/`      |
    | **Service worker filename**           | Name of the `.js` file.                                                                                                                           | `OneSignalSDKWorker.js` |
    | **Service worker registration scope** | URL path the service worker controls. Must be at or below the directory where the file is hosted. Use a path that never serves user-facing pages. | `/push/onesignal/`      |

    #### Custom code setup

    Pass `serviceWorkerPath` and `serviceWorkerParam` in your [`OneSignal.init()`](./web-push-custom-code-setup) call:

    ```html theme={null}
    <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
    <script>
      window.OneSignalDeferred = window.OneSignalDeferred || [];
      window.OneSignalDeferred.push(async function(OneSignal) {
        await OneSignal.init({
          appId: "YOUR_APP_ID",
          serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
          serviceWorkerParam: { scope: "/push/onesignal/" },
        });
      });
    </script>
    ```

    | Parameter                  | Description                                                                                                                                       | Example                                  |
    | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
    | `serviceWorkerPath`        | Relative path from site root to the `.js` file (no leading slash).                                                                                | `"push/onesignal/OneSignalSDKWorker.js"` |
    | `serviceWorkerParam.scope` | URL path the service worker controls. Must be at or below the directory where the file is hosted. Use a path that never serves user-facing pages. | `"/push/onesignal/"`                     |
  </Step>

  <Step title="Review service worker requirements">
    The `OneSignalSDKWorker.js` file must meet all of the following requirements for push notifications to work.

    | Requirement              | Details                                                                                                                                                                                                                                              |
    | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Publicly accessible**  | Navigate to the file URL in a browser and confirm you see the JavaScript code.                                                                                                                                                                       |
    | **Correct content type** | The server must return `Content-Type: application/javascript; charset=utf-8`.                                                                                                                                                                        |
    | **Same origin**          | The file must be hosted on the same domain as your site. CDNs and subdomains are not allowed. See [MDN: Registering your worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#Registering_your_worker). |
    | **HTTPS**                | Service workers require a secure context. `localhost` is the only exception during development.                                                                                                                                                      |

    <Check>
      Service worker setup is complete.
    </Check>

    <Card title="Web SDK setup" icon="browsers" href="./web-sdk-setup">
      Continue with the Web SDK setup guide for next steps.
    </Card>
  </Step>
</Steps>

***

## Combining multiple service workers

Each service worker file on your site is registered at a **scope** — a URL path that determines which pages it controls. Only one service worker can be active at a given scope. If you already have a service worker (for example, a PWA or caching worker) and want OneSignal to share the same file, you can combine them.

<Warning>
  Keeping service workers in separate files with separate scopes is simpler to maintain and avoids conflicts. Only combine them if your setup requires a single service worker file.
</Warning>

To combine, add the OneSignal `importScripts` line to your **existing** service worker file:

```javascript theme={null}
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
importScripts("https://yoursite.com/your-other-service-worker.js");
```

After combining, update the OneSignal configuration to point to your existing service worker file. Follow [Step 4: Configure the SDK path](#step-4-configure-the-sdk-path-subdirectory-only) using the path and filename of your combined file.

***

## Migration guide

This section is for existing OneSignal customers who need to change the service worker file path, filename, or scope. Do not follow these steps unless you have a specific reason to change your current configuration.

<Accordion title="When and how to migrate your service worker">
  **Reasons to migrate:**

  * The root-scope OneSignal service worker conflicts with a Progressive Web App (PWA)
  * The service worker conflicts with AMP or another caching service worker
  * Security policies prohibit third-party service worker code at root scope

  **Option 1: Change scope only (recommended)**

  Changing only the scope is the safest migration. The file stays at its current URL, so existing subscribers continue to receive notifications without interruption.

  **If your file contains only OneSignal code**

  Confirm `OneSignalSDKWorker.js` contains only:

  ```javascript theme={null}
  importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
  ```

  Update the scope using the dashboard or `serviceWorkerParam` as described in [Step 4: Configure the SDK path](#step-4-configure-the-sdk-path-subdirectory-only). No other changes are needed.

  <Warning>
    If `OneSignalSDKWorker.js` is **not** hosted at your domain root today, you must continue hosting it at its current URL with the `Service-Worker-Allowed` header for at least one year. Add a comment in your backend code or internal documentation so the file is not accidentally removed.
  </Warning>

  **If your file contains OneSignal + other code**

  Your service worker may include additional `importScripts` calls (e.g., from following the [combining multiple service workers](#combining-multiple-service-workers) guide). If your current setup still works, **keep it as-is** — splitting a merged service worker requires a two-phase rollout.

  If you must separate them:

  <Steps>
    <Step title="Add a retention comment to the existing file">
      Above the OneSignal `importScripts` line in your current service worker, add:

      ```javascript theme={null}
      // KEEP until YYYY-MM-DD: Required for push delivery to subscribers who have not revisited.
      importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
      ```

      Set the date at least **one year** in the future.
    </Step>

    <Step title="Create a new dedicated OneSignal service worker">
      Create `OneSignalSDKWorker.js` in a subdirectory (e.g., `/push/onesignal/`) containing only:

      ```javascript theme={null}
      importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
      ```
    </Step>

    <Step title="Update OneSignal configuration">
      Set the new path and scope using the dashboard or `OneSignal.init()` as described in [Step 4: Configure the SDK path](#step-4-configure-the-sdk-path-subdirectory-only).
    </Step>

    <Step title="Wait for subscribers to migrate">
      New and returning visitors automatically register with the new service worker. Wait at least one year for the majority of existing subscribers to revisit your site.
    </Step>

    <Step title="Clean up">
      [Delete inactive users](./delete-users) older than your chosen retention period, then remove the OneSignal `importScripts` line from the original service worker file.
    </Step>
  </Steps>

  **Option 2: Change filename or file location**

  Changing the filename or directory is more complex because browsers fetch the service worker from the URL where it was originally registered. Subscribers who have not revisited your site still reference the old URL.

  <Warning>
    You must continue hosting the original file at its old URL for at least one year. Removing it causes 404 errors when the browser attempts to update the service worker, and affected subscribers stop receiving notifications.
  </Warning>

  **If your file contains only OneSignal code**

  <Steps>
    <Step title="Add a retention comment to the old file">
      ```javascript theme={null}
      // KEEP until YYYY-MM-DD: Required for push delivery to subscribers still on the old service worker URL.
      importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
      ```
    </Step>

    <Step title="Create the new file at the new location">
      Place `OneSignalSDKWorker.js` (or your chosen filename) in the new directory with:

      ```javascript theme={null}
      importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
      ```
    </Step>

    <Step title="Update OneSignal configuration">
      Set the new path, filename, and scope as described in [Step 4: Configure the SDK path](#step-4-configure-the-sdk-path-subdirectory-only).
    </Step>

    <Step title="Wait for subscribers to migrate">
      New and returning visitors register with the new file automatically. Wait at least one year.
    </Step>

    <Step title="Clean up">
      [Delete inactive users](./delete-users) older than your retention period, then remove the old file.
    </Step>
  </Steps>

  **If your file contains OneSignal + other code**

  Follow the steps in **Option 1: Change scope only** above. The process is the same.
</Accordion>

***

## FAQ

### Why is my service worker returning a 404?

The file is not at the URL the SDK expects. Navigate to the full file URL in your browser to confirm it is accessible. If you placed the file in a subdirectory, verify that `serviceWorkerPath` (custom code) or the dashboard path setting matches the actual file location — including the directory and filename.

### Why are notifications not displaying after I moved the service worker file?

Existing subscribers still reference the old service worker URL. The browser fetches the registered URL (cached up to 24 hours) each time a push arrives. If the old URL returns a 404, those subscribers do not receive notifications. Continue hosting the old file for at least one year while subscribers naturally migrate by revisiting your site. See the [migration guide](#migration-guide) and [Web push notifications not shown](./notifications-not-shown-web-push) guide.

### Can I host the service worker on a CDN or subdomain?

No. Browsers require service workers to be served from the same origin as the page that registers them. The file must be on your primary domain — not a CDN, subdomain, or different domain.

### Why does my PWA conflict with the OneSignal service worker?

Both are likely registered at root scope (`/`) and only one service worker can be active at a given scope. Move the OneSignal service worker to a subdirectory scope (e.g., `/push/onesignal/`) so your PWA retains control of root scope, or combine them as described in [Combining multiple service workers](#combining-multiple-service-workers).

### Can I rename the OneSignalSDKWorker.js file?

Yes. If your server requires a specific naming convention (e.g., all lowercase), rename the file to something like `onesignalsdkworker.js`. Update the filename in your OneSignal configuration — either the **Service worker filename** field in the dashboard or the `serviceWorkerPath` parameter in your `OneSignal.init()` call. See [Configure the SDK path](#step-4-configure-the-sdk-path-subdirectory-only) for details.

### What content type should my server return for the service worker file?

The server must return `Content-Type: application/javascript; charset=utf-8`. Some servers or CDN configurations return an incorrect MIME type, which causes the browser to reject the service worker registration.


# OSNotification payload
Source: https://documentation.onesignal.com/docs/en/osnotification-payload

Reference for OneSignal's OSNotification object, including all payload fields, Android and iOS-specific properties, custom data, and click actions.

The `OSNotification` class represents the push notification payload in OneSignal's SDKs. Use it to access notification title, body, custom data, and platform-specific properties when handling notifications in your app.

<Info>
  Push notification payloads are limited to `4096` bytes. To avoid truncation, keep payloads under `3500` bytes. The `additionalData` field is limited to `2048` bytes.
</Info>

***

## Accessing `OSNotification` in your app

All OneSignal SDKs provide a notification event listener that returns an `OSNotification` object:

* **Android**: Use the [notification lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push)
* **iOS**: Use the [notification lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) or a `UNNotificationServiceExtension`

### Android fields

| Property                     |           Type          | Description                                                          |
| ---------------------------- | :---------------------: | -------------------------------------------------------------------- |
| `getBody()`                  |         `String`        | Body text of the notification.                                       |
| `getTitle()`                 |         `String`        | Title of the notification.                                           |
| `getLaunchURL()`             |         `String`        | URL opened when the notification is clicked.                         |
| `getNotificationId()`        |         `String`        | OneSignal notification UUID.                                         |
| `getAdditionalData()`        |       `JSONObject`      | Custom key-value data set via dashboard or REST API. Max 2048 bytes. |
| `getTemplateId()`            |         `String`        | Template UUID, if sent using templates.                              |
| `getAndroidNotificationId()` |          `int`          | Android native notification ID.                                      |
| `getLargeIcon()`             |         `String`        | URL or resource name of large icon.                                  |
| `getSmallIcon()`             |         `String`        | Small icon resource name.                                            |
| `getSmallIconAccentColor()`  |         `String`        | Icon accent color in ARGB format.                                    |
| `getSound()`                 |         `String`        | Sound resource name played.                                          |
| `getCollapseId()`            |         `String`        | Collapse key for notification replacement.                           |
| `getPriority()`              |          `int`          | Android priority (-2 to 2).                                          |
| `getLedColor()`              |         `String`        | LED color in ARGB format.                                            |
| `getLockScreenVisibility()`  |          `int`          | Lock screen visibility: `1 = public`, `0 = private`, `-1 = secret`.  |
| `getFromProjectNumber()`     |         `String`        | Sender project number.                                               |
| `getGroupedNotifications()`  |  `List<OSNotification>` | Notifications included in a summary.                                 |
| `getGroupKey()`              |         `String`        | Group key used in summaries.                                         |
| `getGroupMessage()`          |         `String`        | Summary text.                                                        |
| `getBackgroundImageLayout()` | `BackgroundImageLayout` | Object for background image layout and text colors.                  |
| `getActionButtons()`         |   `List<ActionButton>`  | Action buttons with icon, text, and ID.                              |
| `getRawPayload()`            |         `String`        | Full raw JSON string of the payload.                                 |

### iOS fields

| Property           |      Type      | Description                                                                  |
| ------------------ | :------------: | ---------------------------------------------------------------------------- |
| `body`             |   `NSString`   | Body text of the notification.                                               |
| `title`            |   `NSString`   | Title of the notification.                                                   |
| `launchURL`        |   `NSString`   | URL opened when the notification is clicked.                                 |
| `notificationId`   |   `NSString`   | OneSignal notification UUID.                                                 |
| `additionalData`   |  `Dictionary`  | Custom key-value `data` set via dashboard or REST API. Max 2048 bytes.       |
| `templateId`       |   `NSString`   | Template UUID, if sent using templates.                                      |
| `subtitle`         |   `NSString`   | Subtitle text.                                                               |
| `category`         |   `NSString`   | iOS category identifier.                                                     |
| `threadId`         |   `NSString`   | Used to group notifications into threads (iOS 10+).                          |
| `badge`            |   `NSInteger`  | Absolute badge value.                                                        |
| `badgeIncrement`   |   `NSInteger`  | Amount to increment the badge.                                               |
| `contentAvailable` |     `BOOL`     | If `content-available=1`, triggers background fetch.                         |
| `mutableContent`   |     `BOOL`     | If `mutable-content=1`, triggers a Notification Service Extension.           |
| `actionButtons`    |    `NSArray`   | iOS action buttons.                                                          |
| `rawPayload`       | `NSDictionary` | Full raw JSON of the payload.                                                |
| `parseWithApns`    |    *Method*    | Converts raw APNS payload into an OSNotification. Use in service extensions. |

***

## `OSNotificationAction` (click events)

Describes the user's interaction with the notification.

| Property   |   Type   | Description                                           |
| ---------- | :------: | ----------------------------------------------------- |
| `actionId` | `String` | The ID of the clicked action button.                  |
| `type`     |  `enum`  | `Opened` (default tap) or `ActionTaken` (button tap). |

***

## Custom OneSignal payload structure

All OneSignal notifications include a special `"custom"` object in the payload:

```json theme={null}
{
  "custom": {
    "i": "the-notification-id"
  }
}
```

<Info>
  This key is required for OneSignal SDKs to process the notification. If missing, notifications will not trigger click events or analytics. If you send pushes from another service to devices that also use OneSignal, filter by this key to prevent duplicate processing. See [Push payload handling](./migrating-to-onesignal#push-payload-handling) for guidance.
</Info>

***

## Move additionalData to APNS root

For iOS apps, you can place `additionalData` fields in the root of the APNS payload instead of inside the `custom` dictionary. This simplifies access in custom notification handlers.

**1. Enable via the API**

Use the [Update an app API](/reference/update-an-app) and set:

```json theme={null}
{
  "additional_data_is_root_payload": true
}
```

**2. Send a push with `data`**

The `data` fields appear in the APNS root payload:

```json theme={null}
{
  "aps": {
    "alert": { "title": "Sale", "body": "20% off all items!" }
  },
  "promo_code": "SPRING20"
}
```

You can now access `promo_code` directly without checking the `custom` dictionary.

***

## Restored notifications (Android)

The Android SDK restores notifications after a device reboot or app restart.

| Property    |    Type   | Description                                                       |
| ----------- | :-------: | ----------------------------------------------------------------- |
| `restoring` | `boolean` | `true` if the notification was restored after device/app restart. |

<Tip>
  Check the `restoring` flag to skip restored notifications. To prevent old notifications from restoring entirely, set a short or `0` TTL (time-to-live) when sending.
</Tip>

***

## Push token formats

* **iOS Push (APNS)**: 64 characters, hexadecimal only (0-9, a-f). `deviceToken.map {String(format: "%02x", $0)}.joined()`
* **Android Push (FCM)**: Typically 163 characters, alphanumeric, may contain hyphens, colons, and underscores.

***

## FAQ

### What is the maximum payload size?

Push notification payloads are limited to 4096 bytes total. The `additionalData` field is limited to 2048 bytes. To avoid truncation, keep your total payload under 3500 bytes.

### How do I identify a OneSignal notification in the raw payload?

All OneSignal notifications include a `"custom"` object with an `"i"` key containing the notification ID. Check for this key to distinguish OneSignal notifications from those sent by other providers.

### Can I access additionalData in the APNS root payload?

Yes. Enable `additional_data_is_root_payload` via the [Update an app API](/reference/update-an-app) to place `additionalData` fields in the APNS root instead of inside the `custom` dictionary. See [Move additionalData to APNS root](#move-additionaldata-to-apns-root) for details.

***

<Columns>
  <Card title="Android notification categories" icon="android" href="./android-notification-categories">
    Configure notification channels for Android 8.0+ devices.
  </Card>

  <Card title="Mobile Service Extensions" icon="puzzle-piece" href="./service-extensions">
    Add rich media, badges, and confirmed receipt tracking.
  </Card>

  <Card title="Mobile SDK reference" icon="code" href="./mobile-sdk-reference">
    Full reference for OneSignal's mobile SDK methods and listeners.
  </Card>
</Columns>


# Preference center
Source: https://documentation.onesignal.com/docs/en/preference-center

Learn how to implement a custom user preference center in your app or website using OneSignal APIs to manage notification topics, frequencies, channels, and data privacy settings.

## What is a preference center?

A Preference Center is a page on your app or website that allows your users to control how and what kind of messages they receive from you. For more details and reasons why to create a Preference Center, see [A Guide to User Preference Centers](https://onesignal.com/blog/a-guide-to-user-preference-centers).

This guide explains the technical setup needed to include a user preference center in your app or website using OneSignal's APIs. In this guide we discuss how to:

* assign topics, categories, and frequency controls with [Tags](./add-user-data-tags)
* collect new communication channels (push notifications, email, SMS)
* disable communication channels if the user wants to opt-out
* handle data compliance
* delete user data

## Requirements

* OneSignal's Mobile SDKs version 5+ and/or Web SDK 16+
* Setting the [External ID or Alias](./users)
* OneSignal does not provide any APIs for creating the Preference Center layout, only the APIs to GET, PATCH, and DELETE Users and Subscriptions
  * If you have a website and need a simple preference center, try our [Category Prompt](./permission-requests)

### Additional recommended reading

* [A Guide to User Preference Centers](https://onesignal.com/blog/a-guide-to-user-preference-centers)
* [Data Collected by the OneSignal SDK](./data-collected-by-the-onesignal-sdk)
* [Handling Personal Data](./handling-personal-data)

## Setup

When the user lands on your preference center, use the [View user](/reference/view-user) API to pull the OneSignal data for the user based on either the `external_id` or a custom alias you set. This will provide you the user `properties` and `subscriptions`. Helpful data includes but not limited to:

* `properties`: the user data
  * `tags` - custom data you send to OneSignal
  * `language` - the language code for the user
* `subscriptions`: the messaging channels and subscription status
  * `id` - the Subscription ID
  * `type` - `Email`, `SMS`, \*Push (`AndroidPush`, `iOSPush`, `ChromePush`, `SafariPush`, etc)
  * `enabled` - `true` means subscribed, `false` means unsubscribed
  * `token` - the push token, email address, or phone number depending on the subscription type

<CodeGroup>
  ```json json theme={null}
  {
    "properties": {
      "tags": {
        "finance": "1",
        "tech": "1",
        "sports": "1",
        "breaking-news": "0",
        "entertainment": "0",
        "deals": "0",
        "newsletter-frequency": "weekly",
        "customer_status": "Enterprise",
        "event": "1693411710",
        "first_name": "Jon",
        "last_name": "F"
      },
      "language": "en"
    },
    "subscriptions": [
      {
        "id": "sub_id_1",
        "type": "Email",
        "token": "email@example.com",
        "enabled": true
      },
      {
        "id": "sub_id_2",
        "type": "SMS",
        "token": "1234567890",
        "enabled": true
      },
      {
        "id": "sub_id_3",
        "type": "ChromePush",
        "token": "some_token_here",
        "enabled": true
      }
    ]
  }
  ```
</CodeGroup>

Use the data provided to populate the preference center as needed.

## Assign categories and frequency controls

Refer to [Tags](./add-user-data-tags). Tags are key-value pairs used to segment and personalize. Use string-encoded integers or timestamps to enable range-based filtering.

Users can toggle interests (e.g., `sports: 1`) or set frequency tags like `newsletter-frequency: weekly`. Use this data in [Segments](./segmentation) or the [Create notification](/reference/create-message) API with filters.

To update a tag, call the [Update user](/reference/update-user) API.

## Collect new communication channels

Check `subscriptions` for type and enabled status. Show `token` only for email/SMS, not for push.

<Warning>
  If contact info exists in your system but not yet in OneSignal, use your own
  DB as a fallback to display it.
</Warning>

### Email & SMS updates

Use `addEmail`, `addSms` SDK methods or [Create subscription](/reference/create-subscription) and [Update subscription](/reference/update-subscription) APIs. Subscription `id` is required for updates.

### Push updates

If push is not enabled, prompt user.

* For mobile apps: [Prompt for Push Permissions](./prompt-for-push-permissions)
* For web: use [Native Browser Prompt](./permission-requests) or [Slide Prompt](./permission-requests)

## Disable communication channels

Use [Update subscription](/reference/update-subscription) to set `enabled` to `false`. Toggle to `true` to opt-in again.

## Handle data compliance

Prevent SDK init by default and require user consent to initialize. See [Handling Personal Data](./handling-personal-data).

## Delete user data

Use [Delete user](/reference/delete-user) API to fully remove a user from OneSignal.

***


# Fallback messages: Ensuring delivery across channels
Source: https://documentation.onesignal.com/docs/en/push-fallback-method

Implement a fallback strategy with OneSignal to ensure critical messages are delivered via email or SMS when push notifications fail. Learn how to set up cross-channel messaging using Journeys, APIs, and segmentation for reliable user engagement.

## Why use a fallback method?

A message may not always be sent or received through a given channel. Common reasons include:

* The user doesn’t have that channel available (e.g., no email address or phone number, or has not subscribed to push)
* The message failed to send due to delivery errors or invalid tokens
* Users disabling or revoking permissions
* Devices being offline or in restricted states (e.g., iOS Focus Mode)
* Uninstalled apps or expired push tokens

OneSignal supports fallback across **all channels**—Push, In-App, Email, and SMS—so you can ensure that critical communications still reach users, regardless of the original channel.

***

## Fallback strategy overview

<Steps>
  <Step title="Send primary message">
    Attempt to deliver the message through your preferred channel (e.g., Push, Email, or SMS).
  </Step>

  <Step title="Wait for delivery confirmation or interaction">
    Use delivery data or event-based logic to determine whether the message was successfully delivered, clicked or opened. In Journeys, this happens automatically using [Wait Until nodes](./journeys-actions#wait-until).
  </Step>

  <Step title="Trigger fallback channel">
    If the message did not report a [Confirmed receipt](./confirmed-delivery) or was not clicked/opened, send the same message via another available channel (e.g., Email, SMS, or Push).
  </Step>
</Steps>

***

## Requirements

* [External ID](./users#external-id)
* Users must have at least one valid [subscription](./subscriptions) for each channel (email, phone, push token)

***

## Example setups

### Option 1: OneSignal Journeys

Use [OneSignal Journeys](./journeys-overview) to visually automate fallback logic with no code.

* Drag-and-drop interface
* Supports delivery confirmation (with [Confirmed receipt](./confirmed-delivery))
* Combines Push, In-App, Email, and SMS
* Automates fallback without API integration

#### Recommended setup

Instead of yes/no branching, use a [**Wait Until**](./journeys-actions#wait-until) node:
Configure it to **wait until the message is delivered**\
*(confirmed receipt applies to push only)*, **clicked**, or **opened** *(email only)*.

* Set an **expiration period** to avoid indefinite waits
* After expiration, send the fallback message via another channel

<Frame>
  <img />
</Frame>

<Note> confirmed receipt must be enabled per platform. See [Confirmed receipt](./confirmed-delivery). </Note>

***

### Option 2: Custom fallback workflow (Advanced)

You can build a fallback system using the [OneSignal REST API](/reference/create-message) and [View Message API](/reference/view-message), but it requires careful implementation.

<Steps>
  <Step title="Send a message to one user">
    Send a notification to a single user using their `external_id` and target channel.

    ```json json theme={null}
    POST https://onesignal.com/api/v1/notifications
    {
      "include_aliases": {
        "external_id": ["user123"]
      },
      "target_channel": "push",
      "contents": { "en": "Your order has shipped!" }
    }
    ```
  </Step>

  <Step title="Check delivery status">
    Query the [View Message API](/reference/view-message) using the `notification_id` to determine if it was delivered.

    ```json json theme={null}
    GET https://onesignal.com/api/v1/notifications/{notification_id}
    ```

    If the message failed or shows `"received": 0`, prepare to resend through another channel.
  </Step>

  <Step title="Send fallback message">
    Before resending, check the user’s available channels by retrieving their record (via [View User API](/reference/view-user)).\
    Then send the message again through the next available channel (Email, SMS, or Push).
  </Step>
</Steps>

<Warning>
  This method is complex and **not recommended** for most use cases. It requires message-level tracking, user lookups, and managing fallback logic manually.
</Warning>

***

### Option 3: Event Streams

Use [Event Streams](./event-streams) to monitor message events in real time. This allows external systems to react automatically when a message fails.

Common flow:

1. Send a push or email notification
2. Capture `notification_failed` or `delivery_failed` events via Event Streams
3. Determine whether the user can receive another channel (by checking their available and opted-in subscriptions via [View User API](/reference/view-user)
4. Send a fallback message via the next available channel

> Event Streams provide real-time delivery insights but do not emit an event for “not sent,” since unsent messages have no event. Use this only for handling failures, clicks, opens and unsubscibes.

***

### Option 4: Detect and segment unsubscribed users

You can tag users who have unsubscribed from specific channels and manually retarget them via another.

<Steps>
  <Step title="Detect unsubscribed status">
    Use the SDK observer [`addPermissionObserver()`](./mobile-sdk-reference#addpermissionobserver-push) to detect push permission changes.
  </Step>

  <Step title="Tag unsubscribed users">
    When permission is revoked, tag the user (e.g., `unsubscribed_from_push: true`).
  </Step>

  <Step title="Target fallback segment">
    In the OneSignal dashboard, create a segment:

    * `unsubscribed_from_push = true`
    * AND has email or SMS subscription\
      Then target that segment with your fallback campaign.
  </Step>
</Steps>

> This is a manual option and not ideal for automation, but it works for periodic fallback campaigns.

***

## Best practices

* **Choose the fallback channel based on message priority.**
  * Use **SMS** for urgent alerts (e.g., security or downtime).
  * Use **Email or In-App** for non-urgent updates.
* **Journeys are the easiest and most reliable** method for managing fallback.
* **Add expirations** to Wait Until nodes to avoid indefinite waits.
* **confirmed receipt** is required to trigger true delivery-based fallback.
* **Avoid multi-channel duplicates** by ensuring fallback messages reference delivery status.

***

## Example use cases

### Security alert

If a security alert push fails, send an SMS alert immediately.

### Order delivery update

Send a push with tracking info. If undelivered, send the same update via Email.

### Payment failure notification

If a push fails, send an SMS urging the user to retry payment.

### Event reminder

If an email reminder isn’t delivered, send a Push notification instead.

### System downtime alert

If push fails, fallback to SMS ensures users stay informed in real time.

### Billing notice

If email delivery fails, send a push or SMS reminder.

### Flash sale notification

If push isn’t delivered, send an SMS with promo details and a link to shop.

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# ReactJS & NextJS Setup
Source: https://documentation.onesignal.com/docs/en/react-js-setup

Learn how to integrate OneSignal push notifications with your ReactJS or NextJS web application, including initialization, service worker setup, and TypeScript support.

<SdkReleasesIframe />

## Overview

This guide explains how to integrate OneSignal push notifications into a ReactJS or NextJS application. It covers everything from installation to configuration and service worker management.

***

## Requirements

* Configured OneSignal app and platform. See [Web Push Setup](./web-push-setup) to get started.

***

## Installation

Choose your preferred package manager:

<CodeGroup>
  ```bash Yarn theme={null}
  yarn add react-onesignal
  ```

  ```bash npm theme={null}
  npm install --save react-onesignal
  ```
</CodeGroup>

***

## Initialization

Import the OneSignal service and initialize it in your root component.

Replace `YOUR_APP_ID` with your OneSignal app ID found in [Keys & IDs](./keys-and-ids).

```javascript theme={null}
"use client";

import { useEffect } from 'react';
import OneSignal from 'react-onesignal';

export default function Page() {
  useEffect(() => {
    // Ensure this code runs only on the client side
    if (typeof window !== 'undefined') {
      OneSignal.init({
        appId: 'YOUR_APP_ID',
        // You can add other initialization options here
        notifyButton: {
          enable: true,
        }
      });
    }
  }, []);

  return (
    <div>
      <h1>Hello, world!</h1>
      {/* Rest of your page content */}
    </div>
  );
}
```

### Customizing init options

You can customize your initialization with additional [`init` parameters](./web-sdk-reference#init).

### Service Worker Settings

If you haven't done so already, you will need to [download the OneSignal Service Worker file](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip) to add to your site.

The `OneSignalSDKWorker.js` file must be publicly accessible. You can put it in your `public` directory, top-level root, or a subdirectory. However, if you are placing the file in a subdirectory and/or have another service worker for your site, then make sure to specify the path. See [OneSignal Service Worker](./onesignal-service-worker) for details.

| Option               | Description                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `serviceWorkerParam` | Scope controlled by the OneSignal worker. **Recommendation:** Use a custom sub-path (e.g., `"/onesignal/"`).                |
| `serviceWorkerPath`  | Path to your hosted OneSignal service worker file (e.g., `"onesignal/OneSignalSDKWorker.js"`). Must be publicly accessible. |

<Info>
  See a full working example here: [React + OneSignal Example](https://github.com/OneSignal/react-onesignal/tree/main/example)
</Info>

#### Hosting the worker

* Public root (default): `/OneSignalSDKWorker.js`
* Custom folder (recommended): e.g., `/onesignal/OneSignalSDKWorker.js` as set in the previous step.

#### Verify service worker hosting

Visit the path in your browser to confirm it's accessible.

If you used root:

```
https://your-site.com/OneSignalSDKWorker.js
```

If using the example path:

```
https://your-site.com/onesignal/OneSignalSDKWorker.js
```

It should return valid JavaScript.

### Important notes

* Avoid Duplicate Initialization in Development
  * When testing in a development environment, you might see the OneSignal SDK initialize twice, which can cause console errors.
  * This happens due to `<React.StrictMode>` causing effects to run twice in development. To resolve it, remove `<React.StrictMode>` from your root component during development.

<Warning>
  Strict mode only affects development—it does not impact production builds.
</Warning>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications and subscription registration.

### Check web push subscriptions

<Steps>
  <Step title="Launch your site on a test device.">
    * Use Chrome, Firefox, Edge, or Safari while testing.
    * **Do not use Incognito or private browsing mode.** Users cannot subscribe to push notifications in these modes.
    * The prompts should appear based on your [permission prompts](/docs/en/permission-requests) configuration.
    * Click **Allow** on the native prompt to subscribe to push notifications.

    <Frame>
      <img alt="Browser native permission prompt asking the user to allow or block notifications" />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status **Subscribed**.

    <Frame>
      <img alt="OneSignal dashboard Subscriptions page showing a web push subscription with Subscribed status" />
    </Frame>

    <Check>You have successfully created a [web push subscription](/docs/en/subscriptions).
    Web push subscriptions are created when users first subscribe to push notifications on your site.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img alt="Options menu on a subscription showing the Add to test users option" />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img alt="Segment editor with Test Users filter selected and the segment named Test Users" />
    </Frame>

    <Check>You have successfully created a segment of test users.
    You can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment created earlier.

    ```curl theme={null}
    curl -X POST --url 'https://api.onesignal.com/notifications' \
      --header 'content-type: application/json; charset=utf-8' \
      --header 'authorization: Key YOUR_APP_API_KEY' \
      --data '{
        "app_id": "YOUR_APP_ID",
        "target_channel": "push",
        "name": "Testing basic setup",
        "headings": {
          "en": "👋"
        },
        "contents": {
          "en": "Hello world!"
        },
        "included_segments": [
          "Test Users"
        ],
        "chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification.

    <Warning>Only Chrome supports images. Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Warning>

    <Frame>
      <img alt="Expanded Chrome push notification on macOS displaying a custom image" />
    </Frame>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats. You should see the **confirmed** stat, meaning the device received the push.

    <Note>Safari does not support confirmed receipt.</Note>

    <Card title="Push notification message reports" icon="chart-bar" href="/docs/en/push-notification-message-reports">
      View delivery, click, and conversion stats for your push notifications.
    </Card>
  </Step>
</Steps>

<Check>You have successfully sent a notification via the API to a segment.</Check>

If notifications are not arriving, contact `support@onesignal.com` with the following:

* The API request and response (copy-paste into a `.txt` file)
* Your Subscription ID
* Your website URL with the OneSignal code

***

## User identification

The previous section covered creating web push [Subscriptions](/docs/en/subscriptions). This section expands to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. It covers External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with the SDK's [`login` method](/docs/en/web-sdk-reference#login-external-id) each time a user is identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via the SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with the SDK's [`addTag` and `addTags` methods](/docs/en/web-sdk-reference#addtag-%2C-addtags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img alt="OneSignal user profile showing a data tag named current_level with value 6" />
</Frame>

You can create a segment of users with a level between 5 and 10, then use that segment to send targeted and personalized messages:

<Frame>
  <img alt="Segment editor filtering users where current_level is greater than 4 and less than 10" />
</Frame>

<Frame>
  <img alt="Push notification composer targeting the Level 5-10 segment with a personalized message" />
</Frame>

### Add email and/or SMS subscriptions

The OneSignal SDK creates web push subscriptions automatically when users opt in. You can also reach users through email and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/web-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/web-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address or phone number already exists in the OneSignal app, the SDK adds it to the existing user. It does not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img alt="OneSignal user profile showing push, email, and SMS subscriptions linked by External ID" />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/web-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/web-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

For more on privacy and security:

<Columns>
  <Card title="Data collected by the SDK" icon="database" href="/docs/en/data-collected-by-the-onesignal-sdk">
    Review what data the OneSignal SDK collects from users.
  </Card>

  <Card title="Handling personal data" icon="shield-halved" href="/docs/en/handling-personal-data">
    Manage and protect user data in compliance with privacy regulations.
  </Card>
</Columns>

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners you can hook into. See the [SDK reference guide](/docs/en/web-sdk-reference) for more details.

### Push notification events

* [Click event listener](/docs/en/web-sdk-reference#click): Detect when a notification is tapped.
* [Foreground lifecycle listener](/docs/en/web-sdk-reference#foregroundwilldisplay): Control how notifications behave in foreground.

### User state changes

* [User state change event listener](/docs/en/web-sdk-reference#addeventlistener-user-state): Detect when the External ID is set.
* [Permission observer](/docs/en/web-sdk-reference#permissionchange): Track the user's specific interaction with the native push permission prompt.
* [Push subscription change observer](/docs/en/web-sdk-reference#addeventlistener-push-subscription-changes): Track when the push subscription status changes.

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

<Columns>
  <Card title="Migrating to OneSignal" icon="rotate" href="/docs/en/migrating-to-onesignal">
    Move from another push provider to OneSignal.
  </Card>

  <Card title="Integrations" icon="plug" href="/docs/en/integrations">
    Connect OneSignal with third-party tools and platforms.
  </Card>

  <Card title="Action buttons" icon="bell" href="/docs/en/action-buttons">
    Add interactive buttons to push notifications.
  </Card>

  <Card title="Multi-language messaging" icon="globe" href="/docs/en/multi-language-messaging">
    Send localized messages to users in their preferred language.
  </Card>

  <Card title="Identity Verification" icon="shield-check" href="/docs/en/identity-verification">
    Secure your SDK integration with server-side identity verification.
  </Card>

  <Card title="Custom Outcomes" icon="chart-line" href="/docs/en/custom-outcomes">
    Track custom conversion events tied to your messages.
  </Card>
</Columns>

### Web SDK setup & reference

<Columns>
  <Card title="Web push setup" icon="gear" href="/docs/en/web-push-setup">
    Enable all key web push features for your integration.
  </Card>

  <Card title="Web SDK reference" icon="code" href="/docs/en/web-sdk-reference">
    Full details on available methods and configuration options.
  </Card>
</Columns>

<Check>Congratulations! You've successfully completed the Web SDK setup guide.</Check>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# Expo SDK setup
Source: https://documentation.onesignal.com/docs/en/react-native-expo-sdk-setup

Integrate the OneSignal Expo SDK into your iOS and Android apps using Expo SDK 53+ and EAS Build for push notifications and in-app messages.

<SdkReleasesIframe />

<Info>
  **Using an AI coding assistant?** Use this prompt for AI-driven installation:

  ```
  Integrate the OneSignal Expo SDK into this codebase.

  Follow the instructions at:
  https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/react-native-expo/ai-prompt.md
  ```
</Info>

<Warning>
  **Expo Go limitation:** Push notifications do not work in Expo Go. You must create a [development build](https://docs.expo.dev/develop/development-builds/introduction/) to test OneSignal features.
</Warning>

## Requirements

* A managed Expo app. For bare React Native apps, see [React Native SDK setup](./react-native-sdk-setup).
* Expo [development build](https://docs.expo.dev/develop/development-builds/introduction/)
* Expo SDK 53+ (React Native 0.79+) with [New Architecture](https://reactnative.dev/docs/new-architecture-intro) enabled
* EAS CLI ([EAS Build documentation](https://docs.expo.dev/build/introduction/))
* Configured OneSignal app and platform

**iOS Requirements**

* macOS with Xcode 14+ (setup instructions use Xcode 16.2)
* Device with iOS 12+, iPadOS 12+, or Xcode simulator running iOS 16.2+
* CocoaPods 1.16.2+

**Android Requirements**

* Android 7.0+ device or emulator with Google Play Store (Services) installed

### Configure your OneSignal app and platform

Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).

<Note>
  If your organization already has a OneSignal account, [ask to be invited](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Step-by-step setup instructions" icon="circle-chevron-down">
  <Steps>
    <Step title="Create or select your app">
      Create a new app by clicking **New App/Website**, or add a platform to an existing app in **Settings > Push & In-App**. Select the platform(s) you want to configure and click **Next: Configure Your Platform**.

      <Frame>
        <img alt="OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection" />
      </Frame>
    </Step>

    <Step title="Configure platform credentials">
      Enter the credentials for your platform:

      * **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
      * **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
      * **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
      * **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)

      Click **Save & Continue** after entering your credentials.
    </Step>

    <Step title="Save your App ID and install the SDK">
      Your **App ID** is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.

      <Frame>
        <img alt="OneSignal dashboard showing the App ID and team invite option after setup" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

***

## SDK setup

### 1. Add SDK

Install the OneSignal Expo plugin using the Expo CLI.

```shell npm theme={null}
npx expo install onesignal-expo-plugin
```

Add the `react-native-onesignal` package to your project.

<CodeGroup>
  ```shell npm theme={null}
  npm install --save react-native-onesignal
  ```

  ```shell Yarn theme={null}
  yarn add react-native-onesignal
  ```
</CodeGroup>

### 2. Configure the plugin

Open your `app.json` (or `app.config.js` / `app.config.ts`). You must include the following settings.

**Required settings**

<ParamField type="string">
  Your app's bundle identifier. Must match the p8 or p12 authentication configured in your OneSignal app.
</ParamField>

<ParamField type="object">
  Must include the `UIBackgroundModes` key set to `["remote-notification"]`.
</ParamField>

<ParamField type="object">
  iOS entitlements required for push notifications.

  * Set `aps-environment` to `"development"` for testing and `"production"` for TestFlight and App Store builds.
</ParamField>

<Warning>
  Make sure to add the plugin `[onesignal-expo-plugin]` to the front of the plugins array. It should be the first plugin in the array. Doing so will prevent the `OneSignal/OneSignal.h file not found` error.
</Warning>

<Accordion title="Additional plugin props.">
  |           Prop           |  Required  | Description                                                                                                                                                                                                                                                        |
  | :----------------------: | :--------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  |          `mode`          |      ✅     | Configures the [APNs environment](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) entitlement. Use `"development"` or `"production"` — `"development"` for testing and `"production"` for TestFlight and App Store builds. |
  |         `devTeam`        | Deprecated | **Deprecated.** Prefer [`ios.appleTeamId`](https://docs.expo.dev/versions/latest/config/app/#appleteamid) in your Expo config. The plugin falls back to `devTeam` if `appleTeamId` is not set.                                                                     |
  | `iPhoneDeploymentTarget` |      ❌     | `IPHONEOS_DEPLOYMENT_TARGET` used when adding the iOS [Notification Service Extension](./service-extensions). Should match the minimum iOS version in your Podfile (e.g., `"15.0"`).                                                                               |
  |       `smallIcons`       |      ❌     | Array of local paths to Android [small notification icons](./notification-icons#small-notification-icons) (white, transparent, 96×96px). Images are auto-scaled into the correct resource folders. Example: `["./assets/ic_stat_onesignal_default.png"]`           |
  |       `largeIcons`       |      ❌     | Array of local paths to Android [large notification icons](./notification-icons#large-notification-icons) (white, transparent, 256×256px). Example: `["./assets/ic_onesignal_large_icon_default.png"]`                                                             |
  |  `smallIconAccentColor`  |      ❌     | Hex color for the Android notification icon accent (e.g., `"#FF0000"`).                                                                                                                                                                                            |
  |     `iosNSEFilePath`     |      ❌     | Local path to a custom Notification Service Extension in Objective-C. Example: `"./assets/NotificationService.m"`                                                                                                                                                  |
  |      `appGroupName`      |      ❌     | Custom iOS [App Group](./ios-sdk-setup#step-3-create-an-app-group) name. Defaults to `"group.{ios.bundleIdentifier}.onesignal"` if omitted (e.g., `"group.com.example.myapp.onesignal2"`).                                                                         |
  |   `nseBundleIdentifier`  |      ❌     | Suffix for the NSE bundle ID. The full identifier is `{ios.bundleIdentifier}.{nseBundleIdentifier}`. Defaults to `OneSignalNotificationServiceExtension` if omitted.                                                                                               |
  |       `disableNSE`       |      ❌     | If `true`, the iOS NSE is not added. The NSE is required for badges, confirmed receipt, media attachments, and action buttons — only disable if you need basic push only.                                                                                          |
  |     `disableLocation`    |      ❌     | If `true`, the native OneSignal location module is excluded from iOS and Android builds. Use this only if your app does not call `OneSignal.Location`.                                                                                                             |
  |         `sounds`         |      ❌     | Array of local paths to custom notification sounds (`.wav` only, ≤30 seconds). Copied into the app bundle on iOS and `res/raw/` on Android. Example: `["./assets/notification_sound.wav"]`. See [Notification sounds](./notification-sounds).                      |
</Accordion>

#### Optional: Disable the location module

If your app does not use `OneSignal.Location`, set `disableLocation` to `true` in the OneSignal Expo plugin props. This option requires `react-native-onesignal` 5.5.1 or later. The plugin configures native dependency resolution so `react-native-onesignal` excludes the location module. On iOS, the plugin writes the Podfile environment setting used during CocoaPods resolution. On Android, the plugin writes `onesignal.disableLocation=true` to the generated Gradle properties.

<CodeGroup>
  ```ts app.config.ts theme={null}
  plugins: [
    withOneSignal({
      mode: 'development',
      disableLocation: true,
    }),
  ],
  ```

  ```json app.json theme={null}
  "plugins": [
    [
      "onesignal-expo-plugin",
      {
        "mode": "development",
        "disableLocation": true
      }
    ]
  ]
  ```
</CodeGroup>

<Tabs>
  <Tab title="app.config.ts">
    Starting in `onesignal-expo-plugin` 2.6.0, you can import `withOneSignal` for full TypeScript support and autocompletion on the plugin props.

    ```ts app.config.ts theme={null}
    import { ConfigContext, ExpoConfig } from '@expo/config';
    import withOneSignal from 'onesignal-expo-plugin/plugin';

    export default ({ config }: ConfigContext): ExpoConfig => ({
      ...config,
      ios: {
        bundleIdentifier: 'com.yourcompany.yourapp',
        infoPlist: {
          UIBackgroundModes: ['remote-notification'],
        },
        entitlements: {
          'aps-environment': 'development',
        },
      },
      android: {
        package: 'com.yourcompany.yourapp',
      },
      plugins: [
        withOneSignal({
          mode: 'development',
        }),
      ],
    });
    ```
  </Tab>

  <Tab title="app.json">
    ```json app.json theme={null}
      {
        "expo": {
          "ios": {
            "bundleIdentifier": "com.yourcompany.yourapp",
            "infoPlist": {
              "UIBackgroundModes": ["remote-notification"]
            },
            "entitlements": {
              "aps-environment": "development"
            }
          },
          "android": {
            "package": "com.yourcompany.yourapp"
          },
          "plugins": [
            [
              "onesignal-expo-plugin",
              {
                "mode": "development"
              }
            ]
          ]
        }
      }
    ```
  </Tab>
</Tabs>

### 3. Initialize SDK

Depending on your Expo structure (Traditional App entry or Expo Router), initialize OneSignal following these options.

<Tabs>
  <Tab title="Traditional App Entry">
    In your `App.tsx` or `App.js` file initialize OneSignal with the provided methods.

    Replace `YOUR_APP_ID` with your OneSignal App ID found in your OneSignal dashboard **Settings > [Keys & IDs](./keys-and-ids)**.

    <Note>
      If you don't have access to the OneSignal app, ask your [Team Members](./manage-team-members) to invite you.
    </Note>

    ```javascript App.tsx theme={null}
    import React, { useEffect } from 'react';
    // Include the OneSignal package
    import { OneSignal, LogLevel } from 'react-native-onesignal';

    export default function App() {
      useEffect(() => {
        // Enable verbose logging for debugging (remove in production)
        OneSignal.Debug.setLogLevel(LogLevel.Verbose);

        // Replace with your OneSignal App ID from Dashboard > Settings > Keys & IDs
        OneSignal.initialize('YOUR_APP_ID');

        // Prompt for push permission on first launch.
        // In production, consider using an in-app message instead for better opt-in rates.
        OneSignal.Notifications.requestPermission(false);

        // Define listeners once so the same reference is used to add and remove them.
        const clickListener = (event) => {
          console.log('OneSignal: notification clicked:', event);
        };

        // In v5, foreground notifications display automatically.
        // Call event.preventDefault() to suppress, then
        // event.getNotification().display() to show after async work.
        const foregroundListener = (event) => {
          console.log('OneSignal: foreground will display:', event);
        };

        OneSignal.Notifications.addEventListener('click', clickListener);
        OneSignal.Notifications.addEventListener('foregroundWillDisplay', foregroundListener);

        // Clean up listeners when the component unmounts to prevent memory leaks.
        // The same listener reference passed to addEventListener must be passed here.
        return () => {
          OneSignal.Notifications.removeEventListener('click', clickListener);
          OneSignal.Notifications.removeEventListener('foregroundWillDisplay', foregroundListener);
        };
      }, []);
    }
    ```
  </Tab>

  <Tab title="Expo Router">
    In your `app/_layout.tsx` or `app/_layout.js` file initialize OneSignal with the provided methods. The example below uses `App` as the function name — Expo Router accepts any default-exported component, so renaming it to `RootLayout` is optional but conventional.

    Replace `YOUR_APP_ID` with your OneSignal App ID found in your OneSignal dashboard **Settings > [Keys & IDs](./keys-and-ids)**.

    <Note>
      If you don't have access to the OneSignal app, ask your [Team Members](./manage-team-members) to invite you.
    </Note>

    ```javascript App.tsx theme={null}
    import React, { useEffect } from 'react';
    // Include the OneSignal package
    import { OneSignal, LogLevel } from 'react-native-onesignal';

    export default function App() {
      useEffect(() => {
        // Enable verbose logging for debugging (remove in production)
        OneSignal.Debug.setLogLevel(LogLevel.Verbose);

        // Replace with your OneSignal App ID from Dashboard > Settings > Keys & IDs
        OneSignal.initialize('YOUR_APP_ID');

        // Prompt for push permission on first launch.
        // In production, consider using an in-app message instead for better opt-in rates.
        OneSignal.Notifications.requestPermission(false);

        // Define listeners once so the same reference is used to add and remove them.
        const clickListener = (event) => {
          console.log('OneSignal: notification clicked:', event);
        };

        // In v5, foreground notifications display automatically.
        // Call event.preventDefault() to suppress, then
        // event.getNotification().display() to show after async work.
        const foregroundListener = (event) => {
          console.log('OneSignal: foreground will display:', event);
        };

        OneSignal.Notifications.addEventListener('click', clickListener);
        OneSignal.Notifications.addEventListener('foregroundWillDisplay', foregroundListener);

        // Clean up listeners when the component unmounts to prevent memory leaks.
        // The same listener reference passed to addEventListener must be passed here.
        return () => {
          OneSignal.Notifications.removeEventListener('click', clickListener);
          OneSignal.Notifications.removeEventListener('foregroundWillDisplay', foregroundListener);
        };
      }, []);
    }
    ```
  </Tab>
</Tabs>

**Reusable listeners with `useCallback`**

If your listener needs access to props or state, define it outside `useEffect` with `useCallback` so the same reference is used to add and remove the listener. Passing different function references to `addEventListener` and `removeEventListener` is a silent no-op — the listener will not be removed and can fire after the component unmounts.

```javascript theme={null}
import React, { useCallback, useEffect } from 'react';
import { OneSignal } from 'react-native-onesignal';

export default function App() {
  const clickListener = useCallback((event) => {
    console.log('OneSignal: notification clicked:', event);
    // your deps may vary
  }, []);

  useEffect(() => {
    OneSignal.Notifications.addEventListener('click', clickListener);
    return () => {
      OneSignal.Notifications.removeEventListener('click', clickListener);
    };
  }, [clickListener]);
}
```

<Check>
  Review our [OneSignal Expo Plugin GitHub repo](https://github.com/OneSignal/onesignal-expo-plugin) for additional configuration options, more complex setup instructions or open an issue. Our SDKs are open source and we welcome PRs!
</Check>

***

## Android setup

Make sure your OneSignal app is configured for the Android platform using your [Firebase credentials](/docs/en/android-firebase-credentials).

Set up your [notification icons](/docs/en/notification-icons) to match your app’s branding. If this step is skipped, a default bell icon will display for your push notifications.

**Build for Android**

At this point, you should be able to build and run your app on a physical Android device or emulator without issues.

<Check>
  After confirming that your Android build works:

  * Continue with the [iOS setup](#ios-setup), if applicable.
  * Or jump ahead to [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## iOS setup

Make sure your OneSignal app is configured for the iOS platform using either the [p8 Token (Recommended)](./ios-p8-token-based-connection-to-apns) or [p12 Certificate](./ios-p12-generate-certificates).

<Warning>
  This should use the same credentials setup in your EAS configuration.
</Warning>

### Build for iOS

You should now be able to build and run your app on a real iOS device or iOS simulator (16.2+).

#### Common iOS build errors

<Accordion title="Cycle Inside... building could produce unreliable results.">
  You may see this error when building with Xcode 15+, due to a default configuration change affecting cross platform systems.

  1. Open your `.xcworkspace` folder in Xcode and navigate to **your app target > Build Phases**.
  2. You should have a phase called **"Embed Foundation Extensions"** or **"Embed App Extensions"**.
  3. Drag and move this build phase to *above* **"Run Script"**.
  4. Build and run your app. The error should be resolved.

  <Frame>
    <img />
  </Frame>

  <Frame>
    <img />
  </Frame>
</Accordion>

<Accordion title="PBXGroup Error">
  <Info>
    RuntimeError - `PBXGroup` attempted to initialize an object with unknown ISA `PBXFileSystemSynchronizedRootGroup` from attributes: `{"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}`
  </Info>

  Fix:

  1. Find the folder listed under "path" in the error
  2. In Xcode project sidebar, right-click the folder
  3. Select **Convert to Group**

  <Frame>
    <img />
  </Frame>

  <br />

  <Frame>
    <img />
  </Frame>
</Accordion>

<Check>
  After confirming that your iOS build works, continue with [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications, subscription registration, and in-app messaging.

<Warning>
  If you are testing with an Android emulator, it should start with a cold boot.

  1. Go to **Device Manager** in Android Studio.
  2. Select your emulator device and click **Edit**.
  3. Go to **Additional Settings** or **More**.
  4. Set the **Boot option** to **Cold Boot**.
  5. Save changes and restart the emulator.
</Warning>

### Check mobile subscriptions

<Steps>
  <Step title="Launch your app on a test device.">
    The native push permission prompt should appear automatically if you added the `requestPermission` method during initialization.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    Before accepting the prompt, check the OneSignal dashboard:

    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status "Never Subscribed".

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Return to the app and tap Allow on the prompt." />

  <Step title="Refresh the OneSignal dashboard Subscription's page.">
    The subscription's status should now show **Subscribed**.

    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a [mobile subscription](/docs/en/subscriptions).
    Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a segment of test users.
    We can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

    ```curl theme={null}
    curl -X \
    POST --url 'https://api.onesignal.com/notifications' \
     --header 'content-type: application/json; charset=utf-8' \
     --header 'authorization: Key YOUR_APP_API_KEY' \
     --data \
     '{
      "app_id": "YOUR_APP_ID",
      "target_channel": "push",
      "name": "Testing basic setup",
      "headings": {
      	"en": "👋"
      },
      "contents": {
        "en": "Hello world!"
      },
      "included_segments": [
        "Test Users"
      ],
      "ios_attachments": {
        "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      },
      "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
    }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification with an image included:

    <Frame>
      <img />
    </Frame>

    <Info>Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Info>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats.

    You should see the **confirmed** stat, meaning the device received the push.
    <Check>You have successfully sent a notification via our API to a segment.</Check>

    <Warning>
      * No image received? Your [Notification Service Extension](#ios-setup) might be missing.
      * No confirmed receipt? Review the troubleshooting guide [here](/docs/en/confirmed-delivery#troubleshooting-confirmed-delivery).
      * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
    </Warning>
  </Step>
</Steps>

### Send an in-app message

[In-app messages](/docs/en/in-app-messages-setup) let you communicate with users while they are using your app.

<Steps>
  <Step title="Close or background your app on the device.">
    This is because users must meet the in-app audience criteria *before* a new session starts. In OneSignal, a new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds. For more details, see our guide on [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
  </Step>

  <Step title="Create an in-app message.">
    * In your OneSignal dashboard, navigate to **Messages > In-App > New In-App**.
    * Find and select the **Welcome** message.
    * Set your Audience as the **Test Users** segment we used previously.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Customize the message content if desired.">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Set Trigger to 'On app open'." />

  <Step title="Schedule frequency.">
    Under **Schedule > How often do you want to show this message?** select **Every time trigger conditions are satisfied**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Make message live.">
    Click **Make Message Live** so it is available to your Test Users each time they open the app.
  </Step>

  <Step title="Open the app and see the message.">
    After the in-app message is live, open your app. You should see it display:

    <Frame>
      <img />
    </Frame>

    <Warning>
      Not seeing the message?

      * Start a new session
        * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
        * For more, see [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
      * Still in the `Test Users` segment?
        * If you reinstalled or switched devices, re-add the device to [Test Users](#set-up-test-users) and confirm it's part of the Test Users segment.
      * Having issues?
        * Follow [Getting a Debug Log](/docs/en/capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
    </Warning>
  </Step>
</Steps>

<Check>
  You have successfully setup the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](/docs/en/subscriptions), setting [Test Users](/docs/en/find-set-test-subscriptions), and creating [Segments](/docs/en/segmentation).
  * Sending [Push](/docs/en/push) with images and [Confirmed receipt](/docs/en/confirmed-delivery) using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](/docs/en/in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

***

## User identification

Previously, we demonstrated how to create mobile [Subscriptions](/docs/en/subscriptions). Now we'll expand to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We'll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with our SDK's [`login` method](/docs/en/mobile-sdk-reference#login-external-id) each time they are identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with our SDK [`addTag` and `addTags` methods](/docs/en/mobile-sdk-reference#data-tags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img />
</Frame>

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

### Add email and/or SMS subscriptions

Earlier we saw how our SDK creates mobile subscriptions to send push and in-app messages. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/mobile-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/mobile-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/mobile-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/mobile-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

See our Privacy & security docs for more on:

* [Data collected by the SDK](/docs/en/data-collected-by-the-onesignal-sdk)
* [Handling personal data](/docs/en/handling-personal-data)

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](/docs/en/prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners for you to hook into. See our [SDK reference guide](/docs/en/mobile-sdk-reference) for more details.

### Push notification events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-push): Detect when a notification is tapped. Helpful for [Deep Linking](/docs/en/deep-linking).
* [`addForegroundLifecycleListener()`](/docs/en/mobile-sdk-reference#addforegroundlifecyclelistener-push): Control how notifications behave in foreground.

For full customization, see [Mobile Service Extensions](/docs/en/service-extensions).

### User state changes

* [`addObserver()` for user state](/docs/en/mobile-sdk-reference#addobserver-user-state): Detect when the External ID is set.
* [`addPermissionObserver()`](/docs/en/mobile-sdk-reference#addpermissionobserver-push): Track the user's specific interaction with the native push permission prompt.
* [`addObserver()` for push subscription](/docs/en/mobile-sdk-reference#addobserver-push-subscription-changes): Track when the push subscription status changes.

### In-app message events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Handle in-app click actions. Ideal for deep linking or tracking events.
* [`addLifecycleListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Track full lifecycle of in-app messages (shown, clicked, dismissed, etc.).

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

* [🔁 Migrating to OneSignal from another service](/docs/en/migrating-to-onesignal)
* [🌍 Location tracking](/docs/en/mobile-sdk-reference#location)
* [🔗 Deep Linking](/docs/en/deep-linking)
* [🔌 Integrations](/docs/en/integrations)
* [🧩 Mobile Service Extensions](/docs/en/service-extensions)
* [🛎️ Action buttons](/docs/en/action-buttons)
* [🌐 Multi-language messaging](/docs/en/multi-language-messaging)
* [🛡️ Identity Verification](/docs/en/identity-verification)
* [📊 Custom Outcomes](/docs/en/custom-outcomes)
* [📲 Live Activities](/docs/en/live-activities)

### Mobile SDK setup & reference

Make sure you've enabled all key features by reviewing the [Mobile push setup](/docs/en/mobile-push-setup) guide.

For full details on available methods and configuration options, visit the [Mobile SDK reference](/docs/en/mobile-sdk-reference).

<Check>Congratulations! You've successfully completed the Mobile SDK setup guide.</Check>

***

***

## Privacy and user consent

If your app requires user consent before collecting data (e.g., for GDPR compliance), you can delay OneSignal's data collection until consent is granted. Call `setConsentRequired` **before** `initialize`.

```javascript theme={null}
// Call BEFORE OneSignal.initialize()
OneSignal.setConsentRequired(true);
OneSignal.initialize('YOUR_APP_ID');

// Later, after the user grants consent (e.g., via a consent dialog)
OneSignal.setConsentGiven(true);
```

<Note>
  When consent is required but not yet given, the SDK initializes but does not send any data to OneSignal. Call `setConsentGiven(true)` once the user opts in. See [Handling Personal Data](./handling-personal-data) for more details.
</Note>

***

## Troubleshooting

| Error / Symptom                                             | Platform | Fix                                                                                                                                                          |
| ----------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OneSignal/OneSignal.h file not found`                      | iOS      | Move `onesignal-expo-plugin` to the **first** position in the `plugins` array in `app.json`                                                                  |
| `Unable to find onesignal-expo-plugin`                      | Both     | Run `npx expo install onesignal-expo-plugin` and verify it appears in `package.json`                                                                         |
| Push notifications don't work in Expo Go                    | Both     | Push requires a [development build](https://docs.expo.dev/develop/development-builds/introduction/) — Expo Go does not support native modules like OneSignal |
| No push notifications on iOS                                | iOS      | Verify APNs credentials in OneSignal and that `aps-environment` in `app.json` matches your build type (`development` or `production`)                        |
| No push notifications on Android                            | Android  | Verify FCM credentials in OneSignal and that the device has Google Play Services                                                                             |
| `Bundle identifier mismatch`                                | iOS      | Ensure `ios.bundleIdentifier` in `app.json` matches your Apple Developer account and OneSignal APNs configuration                                            |
| `eas build` fails with OneSignal errors                     | Both     | Validate `app.json` plugin configuration — check required fields and plugin ordering                                                                         |
| `Cycle Inside... building could produce unreliable results` | iOS      | See the [iOS build errors section](#common-ios-build-errors) above                                                                                           |
| `PBXGroup` / `PBXFileSystemSynchronizedRootGroup` error     | iOS      | Right-click the folder in Xcode project sidebar and select **Convert to Group** — see [iOS build errors section](#common-ios-build-errors)                   |
| Can't diagnose the issue                                    | Both     | Add `OneSignal.Debug.setLogLevel(LogLevel.Verbose)` before `initialize` and check device logs                                                                |

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# React Native SDK setup
Source: https://documentation.onesignal.com/docs/en/react-native-sdk-setup

Comprehensive guide to integrate the OneSignal React Native SDK for iOS, Android, and Amazon app platforms. Includes prerequisites, configuration steps, platform-specific setup, and troubleshooting common issues.

<SdkReleasesIframe />

<Info>
  **Using an AI coding assistant?** Use this prompt for AI-driven installation:

  ```
  Integrate the OneSignal React Native SDK into this codebase.

  Follow the instructions at:
  https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/react-native/ai-prompt.md
  ```
</Info>

## Requirements

* A bare React Native app. For managed Expo apps, use the [Expo SDK Setup](./react-native-expo-sdk-setup)
* React Native 0.79+ with [New Architecture](https://reactnative.dev/docs/new-architecture-intro) enabled
* Configured OneSignal app and platform

**iOS Requirements**

* macOS with Xcode 14+ (setup instructions use Xcode 16.2)
* Device with iOS 12+, iPadOS 12+, or Xcode simulator running iOS 16.2+
* CocoaPods 1.16.2+

**Android Requirements**

* Android 7.0+ device or emulator with Google Play Store (Services) installed

### Configure your OneSignal app and platform

Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).

<Note>
  If your organization already has a OneSignal account, [ask to be invited](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Step-by-step setup instructions" icon="circle-chevron-down">
  <Steps>
    <Step title="Create or select your app">
      Create a new app by clicking **New App/Website**, or add a platform to an existing app in **Settings > Push & In-App**. Select the platform(s) you want to configure and click **Next: Configure Your Platform**.

      <Frame>
        <img alt="OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection" />
      </Frame>
    </Step>

    <Step title="Configure platform credentials">
      Enter the credentials for your platform:

      * **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
      * **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
      * **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
      * **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)

      Click **Save & Continue** after entering your credentials.
    </Step>

    <Step title="Save your App ID and install the SDK">
      Your **App ID** is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.

      <Frame>
        <img alt="OneSignal dashboard showing the App ID and team invite option after setup" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

***

## SDK setup

### 1. Add SDK

Add the `react-native-onesignal` package to your project.

<CodeGroup>
  ```shell npm theme={null}
    npm install --save react-native-onesignal
  ```

  ```shell Yarn theme={null}
    yarn add react-native-onesignal
  ```

  ```shell Bun theme={null}
    bun add react-native-onesignal
  ```
</CodeGroup>

### Optional: Disable the location module

Starting with `react-native-onesignal` 5.5.0, you can exclude OneSignal's native location module from iOS and Android builds when your app does not use location features. By default, the package includes the native location module so `OneSignal.Location` works without extra setup.

Set `ONESIGNAL_DISABLE_LOCATION=true` before resolving or building dependencies for CocoaPods and Gradle. The value is case-insensitive. You can also set it to `1`.

<CodeGroup>
  ```shell iOS theme={null}
  cd ios
  ONESIGNAL_DISABLE_LOCATION=true pod install
  ```

  ```shell Android theme={null}
  cd android
  ONESIGNAL_DISABLE_LOCATION=true ./gradlew assembleDebug
  ```

  ```yaml GitHub Actions theme={null}
  env:
    ONESIGNAL_DISABLE_LOCATION: true
  ```
</CodeGroup>

When disabled, `OneSignal.Location.requestPermission()` and `OneSignal.Location.setShared()` no-op on native builds without the location module. `OneSignal.Location.isShared()` resolves `false`.

If you change this value in an existing project, reinstall CocoaPods dependencies in a shell where the variable is exported:

```shell theme={null}
cd ios
pod deintegrate
rm -rf Pods Podfile.lock
ONESIGNAL_DISABLE_LOCATION=true pod install
```

Gradle re-reads the variable on each configuration, so a clean build with the variable set is enough on Android.

<Warning>
  When using Xcode or Android Studio, launch the IDE from a terminal where `ONESIGNAL_DISABLE_LOCATION` is exported. IDEs launched from the Dock or Finder do not inherit variables set only in your shell profile. On CI, key CocoaPods and Gradle caches on the value of `ONESIGNAL_DISABLE_LOCATION`.
</Warning>

### 2. Initialize SDK

In your `App.tsx`, `App.js`, or `index.js` file initialize OneSignal with the provided methods.

Replace `YOUR_APP_ID` with your OneSignal App ID found in your OneSignal dashboard **Settings > [Keys & IDs](./keys-and-ids)**.

<Note>
  If you don't have access to the OneSignal app, ask your [Team Members](./manage-team-members) to invite you.
</Note>

```javascript App.tsx theme={null}
import React, { useEffect } from 'react';
// Include the OneSignal package
import { OneSignal, LogLevel } from 'react-native-onesignal';

export default function App() {
  useEffect(() => {
    // Enable verbose logging for debugging (remove in production)
    OneSignal.Debug.setLogLevel(LogLevel.Verbose);

    // Replace with your OneSignal App ID from Dashboard > Settings > Keys & IDs
    OneSignal.initialize('YOUR_APP_ID');

    // Prompt for push permission on first launch.
    // In production, consider using an in-app message instead for better opt-in rates.
    OneSignal.Notifications.requestPermission(false);

    // Define listeners once so the same reference is used to add and remove them.
    const clickListener = (event) => {
      console.log('OneSignal: notification clicked:', event);
    };

    // In v5, foreground notifications display automatically.
    // Call event.preventDefault() to suppress, then
    // event.getNotification().display() to show after async work.
    const foregroundListener = (event) => {
      console.log('OneSignal: foreground will display:', event);
    };

    OneSignal.Notifications.addEventListener('click', clickListener);
    OneSignal.Notifications.addEventListener('foregroundWillDisplay', foregroundListener);

    // Clean up listeners when the component unmounts to prevent memory leaks.
    // The same listener reference passed to addEventListener must be passed here.
    return () => {
      OneSignal.Notifications.removeEventListener('click', clickListener);
      OneSignal.Notifications.removeEventListener('foregroundWillDisplay', foregroundListener);
    };
  }, []);
}
```

**Reusable listeners with `useCallback`**

If your listener needs access to props or state, define it outside `useEffect` with `useCallback` so the same reference is used to add and remove the listener. Passing different function references to `addEventListener` and `removeEventListener` is a silent no-op — the listener will not be removed and can fire after the component unmounts.

```javascript theme={null}
import React, { useCallback, useEffect } from 'react';
import { OneSignal } from 'react-native-onesignal';

export default function App() {
  const clickListener = useCallback((event) => {
    console.log('OneSignal: notification clicked:', event);
    // your deps may vary
  }, []);

  useEffect(() => {
    OneSignal.Notifications.addEventListener('click', clickListener);
    return () => {
      OneSignal.Notifications.removeEventListener('click', clickListener);
    };
  }, [clickListener]);
}
```

***

## Android setup

Make sure your OneSignal app is configured for the Android platform using your [Firebase credentials](/docs/en/android-firebase-credentials).

Set up your [notification icons](/docs/en/notification-icons) to match your app’s branding. If this step is skipped, a default bell icon will display for your push notifications.

**Build for Android**

At this point, you should be able to build and run your app on a physical Android device or emulator without issues.

<Check>
  After confirming that your Android build works:

  * Continue with the [iOS setup](#ios-setup), if applicable.
  * Or jump ahead to [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## iOS setup

Make sure your OneSignal app is configured for the iOS platform using either the [p8 Token (Recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 Certificate](/docs/en/ios-p12-generate-certificates).

Follow these steps to add push notifications to your iOS app, including support for [Badges](/docs/en/badges), [Confirmed receipt](/docs/en/confirmed-delivery), and images.

### 1. Add Push Notifications capability to app target

The [Push Notifications capability](https://developer.apple.com/documentation/UserNotifications/registering-your-app-with-apns#Enable-the-push-notifications-capability) allows your app to register a push token and receive notifications.

1. Open your app’s `.xcworkspace` file in Xcode.
2. Select **your app target > Signing & Capabilities**
3. Click **+ Capability** and add **Push Notifications** capability

<Frame>
  <img />
</Frame>

### 2. Add Background Modes capability to app target

This enables your app to wake in the background when push notifications arrive.

1. Add [Background Modes](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app) capability
2. Enable **Remote notifications**

<Frame>
  <img />
</Frame>

### 3. Add app target to App Group

[App Groups](https://developer.apple.com/documentation/xcode/configuring-app-groups/#Create-App-Groups-for-all-other-platforms) allow data sharing between your app and the Notification Service Extension. Required for confirmed receipt and Badges.

<Tabs>
  <Tab title="If you do NOT have an App Group configured">
    1. Add **App Groups** capability
    2. In the App Groups capability click **+**
    3. Add a new container ID in format: `group.your_bundle_id.onesignal`

    * Keep **group.** and **.onesignal** prefix and suffix. Replace **`your_bundle_id`** with your app's bundle identifier.
    * For example, bundle identifier `com.onesignal.MyApp`, will have the container name `group.com.onesignal.MyApp.onesignal`.

    <Frame>
      <img />
    </Frame>

    <Warning> Your App Group name must exactly match your bundle ID’s spelling and capitalization across all targets. </Warning>
  </Tab>

  <Tab title="If you DO have an App Group">
    1. Open your **App Target** and **OneSignalNotificationServiceExtension Target's** `Info.plist`
    2. Add a new property to the `Info.plist` for both targets:

    * **Key:** `OneSignal_app_groups_key`
    * **Value:** Your existing App Group name (e.g., `group.your-custom-group-id`)

    ```xml XML theme={null}
    <key>OneSignal_app_groups_key</key>
    <string>group.your-custom-group-id</string>
    ```

    <Frame>
      <img />
    </Frame>

    <Warning>
      Make sure to update the `OneSignal_app_groups_key` in **both** the App Target **and** OneSignalNotificationServiceExtension Target's `Info.plist`!
    </Warning>
  </Tab>
</Tabs>

### 4. Add Notification Service Extension

The [Notification Service Extension (NSE)](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications) enables rich notifications and confirmed receipt analytics.

1. In Xcode: **File > New > Target...**
2. Select **Notification Service Extension**, then **Next**.
3. Set the product name to `OneSignalNotificationServiceExtension` and press **Finish**.
4. Press **Don't Activate** on the Activate scheme prompt.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

Set the OneSignalNotificationServiceExtension **Minimum Deployment Target** to match your main app (iOS 15+ recommended).

<Info> If you're using CocoaPods, set the deployment version in your Podfile as well. </Info>

<Frame>
  <img />
</Frame>

### 5. Add NSE target to app group

Use the same App Group ID you added in step 3.

1. Go to **OneSignalNotificationServiceExtension > Signing & Capabilities**
2. Add **App Groups**
3. Add the exact same group ID

<Warning>
  If you are using a custom App Group name and not `group.your_bundle_id.onesignal` then make sure to add your App Group ID to both the App Target and OneSignalNotificationServiceExtension Target's `Info.plist`! See [step 3](#3-add-app-target-to-app-group) for more information.
</Warning>

<Frame>
  <img />
</Frame>

### 6. Update NSE code

1. Navigate to the **OneSignalNotificationServiceExtension** folder
2. Replace the contents of the `NotificationService.swift` or `NotificationService.m` file with the following:

<Frame>
  <img />
</Frame>

<CodeGroup>
  ```swift Swift theme={null}
  import UserNotifications
  import OneSignalExtension

  class NotificationService: UNNotificationServiceExtension {
      var contentHandler: ((UNNotificationContent) -> Void)?
      var receivedRequest: UNNotificationRequest!
      var bestAttemptContent: UNMutableNotificationContent?

      // Note this extension only runs when `mutable_content` is set
      // Setting an attachment or action buttons automatically sets the property to true
      override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
          self.receivedRequest = request
          self.contentHandler = contentHandler
          self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

          if let bestAttemptContent = bestAttemptContent {
              // DEBUGGING: Uncomment the 2 lines below to check this extension is executing
  //            print("Running NotificationServiceExtension")
  //            bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

              OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
          }
      }

      override func serviceExtensionTimeWillExpire() {
          // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
          if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
              OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
              contentHandler(bestAttemptContent)
          }
      }
  }
  ```

  ```objectivec Objective-C theme={null}
  #import <OneSignalExtension/OneSignalExtension.h>
  #import "NotificationService.h"

  @interface NotificationService ()

  @property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
  @property (nonatomic, strong) UNNotificationRequest *receivedRequest;
  @property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

  @end

  @implementation NotificationService

  // Note, this extension only runs when mutable-content is set
  // Setting an attachment or action buttons automatically adds this
  - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
      self.receivedRequest = request;
      self.contentHandler = contentHandler;
      self.bestAttemptContent = [request.content mutableCopy];

      // DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is executing
  //     NSLog(@"Running NotificationServiceExtension");
  //     self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];

      [OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
                         withMutableNotificationContent:self.bestAttemptContent
                                     withContentHandler:self.contentHandler];
  }

  - (void)serviceExtensionTimeWillExpire {
      // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.

      [OneSignalExtension serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];

      self.contentHandler(self.bestAttemptContent);
  }

  @end
  ```
</CodeGroup>

You should see an error because the OneSignal package is not installed. This will be resolved in the next step.

<Frame>
  <img />
</Frame>

### 7. Add OneSignal to the NSE target

<Note>
  If your SDK uses Swift Package Manager (SPM) for iOS dependencies, you can skip this step. The OneSignal package is already resolved and available to all targets.
</Note>

Update your `ios/Podfile` to include:

<CodeGroup>
  ```ruby Podfile theme={null}
  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```

  ```ruby Example theme={null}
  target 'MyApp' do
    config = use_native_modules!

    use_react_native!(
      :path => config[:reactNativePath],
      # An absolute path to your application root.
      :app_path => "#{Pod::Config.instance.installation_root}/.."
    )

    post_install do |installer|
      # https://github.com/facebook/react-native/blob/main/packages/react-native/scripts/react_native_pods.rb#L197-L202
      react_native_post_install(
        installer,
        config[:reactNativePath],
        :mac_catalyst_enabled => false,
        # :ccache_enabled => true
      )
    end
  end

  target 'OneSignalNotificationServiceExtension' do
    pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
  end
  ```
</CodeGroup>

Open your project in the terminal and run:

```shell shell  theme={null}
cd ios pod install cd .. 
```

#### Common pod install errors

You may run into the following errors, here is how you can resolve them.

<Accordion
  title="ArgumentError - \[Xcodeproj] Unable to find compatibility version string for
object version `70`."
>
  CocoaPods relies on the `xcodeproj` Ruby gem to read your Xcode project files. As of now, the latest `xcodeproj` release does not recognize object version 70, which was introduced by Xcode 16. So when CocoaPods tries to open your `.xcodeproj` file, it crashes with this error.

  1. Close Xcode.
  2. Navigate to your project's `ios/<your-app>.xcodeproj/project.pbxproj` file.
  3. Change this line: `objectVersion = 70;`
  4. Replace it with: `objectVersion = 55;`
  5. Save, close, and rerun `cd ios pod install cd ..`
</Accordion>

### Build for iOS

You should now be able to build and run your app on a real iOS device or iOS simulator (16.2+).

#### Common iOS build errors

<Accordion title="commandPhaseScript Execution exited with a non-zero code">
  1. Delete your Podfile.lock
  2. Delete your Pods folder
  3. Delete your .xcworkspace
  4. Pod install
  5. Cmd + Shift + K to Clean the build and then retry building

  If these steps do not resolve the error, build directly from the Xcode, then find the build error in the report navigator pictured below.

  <img />
</Accordion>

<Accordion title="Cycle Inside... building could produce unreliable results.">
  You may see this error when building with Xcode 15+, due to a default configuration change affecting cross platform systems.

  1. Open your `.xcworkspace` folder in Xcode and navigate to **your app target > Build Phases**.
  2. You should have a phase called **"Embed Foundation Extensions"** or **"Embed App Extensions"**.
  3. Drag and move this build phase to *above* **"Run Script"**.
  4. Build and run your app. The error should be resolved.

  <Frame>
    <img />
  </Frame>

  <Frame>
    <img />
  </Frame>
</Accordion>

<Accordion title="PBXGroup Error">
  <Info>
    RuntimeError - `PBXGroup` attempted to initialize an object with unknown ISA `PBXFileSystemSynchronizedRootGroup` from attributes: `{"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}`
  </Info>

  Fix:

  1. Find the folder listed under "path" in the error
  2. In Xcode project sidebar, right-click the folder
  3. Select **Convert to Group**

  <Frame>
    <img />
  </Frame>

  <br />

  <Frame>
    <img />
  </Frame>
</Accordion>

<Check>
  After confirming that your iOS build works, continue with [Testing the OneSignal SDK integration](#testing-the-onesignal-sdk-integration).
</Check>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications, subscription registration, and in-app messaging.

<Warning>
  If you are testing with an Android emulator, it should start with a cold boot.

  1. Go to **Device Manager** in Android Studio.
  2. Select your emulator device and click **Edit**.
  3. Go to **Additional Settings** or **More**.
  4. Set the **Boot option** to **Cold Boot**.
  5. Save changes and restart the emulator.
</Warning>

### Check mobile subscriptions

<Steps>
  <Step title="Launch your app on a test device.">
    The native push permission prompt should appear automatically if you added the `requestPermission` method during initialization.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    Before accepting the prompt, check the OneSignal dashboard:

    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status "Never Subscribed".

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Return to the app and tap Allow on the prompt." />

  <Step title="Refresh the OneSignal dashboard Subscription's page.">
    The subscription's status should now show **Subscribed**.

    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a [mobile subscription](/docs/en/subscriptions).
    Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a segment of test users.
    We can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

    ```curl theme={null}
    curl -X \
    POST --url 'https://api.onesignal.com/notifications' \
     --header 'content-type: application/json; charset=utf-8' \
     --header 'authorization: Key YOUR_APP_API_KEY' \
     --data \
     '{
      "app_id": "YOUR_APP_ID",
      "target_channel": "push",
      "name": "Testing basic setup",
      "headings": {
      	"en": "👋"
      },
      "contents": {
        "en": "Hello world!"
      },
      "included_segments": [
        "Test Users"
      ],
      "ios_attachments": {
        "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      },
      "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
    }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification with an image included:

    <Frame>
      <img />
    </Frame>

    <Info>Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Info>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats.

    You should see the **confirmed** stat, meaning the device received the push.
    <Check>You have successfully sent a notification via our API to a segment.</Check>

    <Warning>
      * No image received? Your [Notification Service Extension](#ios-setup) might be missing.
      * No confirmed receipt? Review the troubleshooting guide [here](/docs/en/confirmed-delivery#troubleshooting-confirmed-delivery).
      * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
    </Warning>
  </Step>
</Steps>

### Send an in-app message

[In-app messages](/docs/en/in-app-messages-setup) let you communicate with users while they are using your app.

<Steps>
  <Step title="Close or background your app on the device.">
    This is because users must meet the in-app audience criteria *before* a new session starts. In OneSignal, a new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds. For more details, see our guide on [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
  </Step>

  <Step title="Create an in-app message.">
    * In your OneSignal dashboard, navigate to **Messages > In-App > New In-App**.
    * Find and select the **Welcome** message.
    * Set your Audience as the **Test Users** segment we used previously.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Customize the message content if desired.">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Set Trigger to 'On app open'." />

  <Step title="Schedule frequency.">
    Under **Schedule > How often do you want to show this message?** select **Every time trigger conditions are satisfied**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Make message live.">
    Click **Make Message Live** so it is available to your Test Users each time they open the app.
  </Step>

  <Step title="Open the app and see the message.">
    After the in-app message is live, open your app. You should see it display:

    <Frame>
      <img />
    </Frame>

    <Warning>
      Not seeing the message?

      * Start a new session
        * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
        * For more, see [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
      * Still in the `Test Users` segment?
        * If you reinstalled or switched devices, re-add the device to [Test Users](#set-up-test-users) and confirm it's part of the Test Users segment.
      * Having issues?
        * Follow [Getting a Debug Log](/docs/en/capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
    </Warning>
  </Step>
</Steps>

<Check>
  You have successfully setup the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](/docs/en/subscriptions), setting [Test Users](/docs/en/find-set-test-subscriptions), and creating [Segments](/docs/en/segmentation).
  * Sending [Push](/docs/en/push) with images and [Confirmed receipt](/docs/en/confirmed-delivery) using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](/docs/en/in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

***

## User identification

Previously, we demonstrated how to create mobile [Subscriptions](/docs/en/subscriptions). Now we'll expand to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We'll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with our SDK's [`login` method](/docs/en/mobile-sdk-reference#login-external-id) each time they are identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with our SDK [`addTag` and `addTags` methods](/docs/en/mobile-sdk-reference#data-tags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img />
</Frame>

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

### Add email and/or SMS subscriptions

Earlier we saw how our SDK creates mobile subscriptions to send push and in-app messages. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/mobile-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/mobile-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/mobile-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/mobile-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

See our Privacy & security docs for more on:

* [Data collected by the SDK](/docs/en/data-collected-by-the-onesignal-sdk)
* [Handling personal data](/docs/en/handling-personal-data)

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](/docs/en/prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners for you to hook into. See our [SDK reference guide](/docs/en/mobile-sdk-reference) for more details.

### Push notification events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-push): Detect when a notification is tapped. Helpful for [Deep Linking](/docs/en/deep-linking).
* [`addForegroundLifecycleListener()`](/docs/en/mobile-sdk-reference#addforegroundlifecyclelistener-push): Control how notifications behave in foreground.

For full customization, see [Mobile Service Extensions](/docs/en/service-extensions).

### User state changes

* [`addObserver()` for user state](/docs/en/mobile-sdk-reference#addobserver-user-state): Detect when the External ID is set.
* [`addPermissionObserver()`](/docs/en/mobile-sdk-reference#addpermissionobserver-push): Track the user's specific interaction with the native push permission prompt.
* [`addObserver()` for push subscription](/docs/en/mobile-sdk-reference#addobserver-push-subscription-changes): Track when the push subscription status changes.

### In-app message events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Handle in-app click actions. Ideal for deep linking or tracking events.
* [`addLifecycleListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Track full lifecycle of in-app messages (shown, clicked, dismissed, etc.).

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

* [🔁 Migrating to OneSignal from another service](/docs/en/migrating-to-onesignal)
* [🌍 Location tracking](/docs/en/mobile-sdk-reference#location)
* [🔗 Deep Linking](/docs/en/deep-linking)
* [🔌 Integrations](/docs/en/integrations)
* [🧩 Mobile Service Extensions](/docs/en/service-extensions)
* [🛎️ Action buttons](/docs/en/action-buttons)
* [🌐 Multi-language messaging](/docs/en/multi-language-messaging)
* [🛡️ Identity Verification](/docs/en/identity-verification)
* [📊 Custom Outcomes](/docs/en/custom-outcomes)
* [📲 Live Activities](/docs/en/live-activities)

### Mobile SDK setup & reference

Make sure you've enabled all key features by reviewing the [Mobile push setup](/docs/en/mobile-push-setup) guide.

For full details on available methods and configuration options, visit the [Mobile SDK reference](/docs/en/mobile-sdk-reference).

<Check>Congratulations! You've successfully completed the Mobile SDK setup guide.</Check>

***

***

## Privacy and user consent

If your app requires user consent before collecting data (e.g., for GDPR compliance), you can delay OneSignal's data collection until consent is granted. Call `setConsentRequired` **before** `initialize`.

```javascript theme={null}
// Call BEFORE OneSignal.initialize()
OneSignal.setConsentRequired(true);
OneSignal.initialize('YOUR_APP_ID');

// Later, after the user grants consent (e.g., via a consent dialog)
OneSignal.setConsentGiven(true);
```

<Note>
  When consent is required but not yet given, the SDK initializes but does not send any data to OneSignal. Call `setConsentGiven(true)` once the user opts in. See [Handling Personal Data](./handling-personal-data) for more details.
</Note>

***

## Troubleshooting

| Error / Symptom                                          | Platform | Fix                                                                                                                                                               |
| -------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Unable to find react-native-onesignal`                  | Both     | Run `npm install react-native-onesignal` and rebuild                                                                                                              |
| `NativeEventEmitter() requires a non-null argument`      | Both     | Move `OneSignal.initialize()` inside `useEffect`                                                                                                                  |
| No push notifications on iOS                             | iOS      | Verify APNs credentials in OneSignal and that the Notification Service Extension is configured                                                                    |
| No push notifications on Android                         | Android  | Verify FCM credentials in OneSignal and that the device has Google Play Services                                                                                  |
| `Unable to resolve module`                               | Both     | Clear Metro cache: `npx react-native start --reset-cache`                                                                                                         |
| `[OneSignal] App Group not found`                        | iOS      | Add the same App Group to both the main app target and the NSE target                                                                                             |
| `CocoaPods could not find compatible versions`           | iOS      | Delete `ios/Podfile.lock` and run `pod install` again                                                                                                             |
| Build fails on Android                                   | Android  | Clean the build: `cd android && ./gradlew clean && cd ..`                                                                                                         |
| `this.RNOneSignal.onPermissionChanged is not a function` | Android  | Enable [New Architecture](https://reactnative.dev/docs/new-architecture-intro) in your project. The OneSignal SDK requires New Architecture (React Native 0.79+). |
| Can't diagnose the issue                                 | Both     | Add `OneSignal.Debug.setLogLevel(LogLevel.Verbose)` before `initialize` and check device logs                                                                     |

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# Mobile service extensions
Source: https://documentation.onesignal.com/docs/en/service-extensions

Intercept and customize push notifications before display on iOS and Android. Enable rich media, confirmed receipt, custom styling, and background data handling.

Notification service extensions let you intercept and modify push notifications before they are displayed to the user. Use them to add rich media, customize appearance, handle background data, and enable confirmed receipt analytics.

<Note>
  For a full reference of the notification payload structure, see [OSNotification payload](./osnotification-payload).
</Note>

## Android notification service extension

The Android notification service extension allows you to process notifications before they are shown to the user. Common use cases include:

* Receiving data in the background with or without displaying a notification
* Overriding notification settings based on client-side app logic, such as custom accent color, vibration pattern, or other [`NotificationCompat`](https://developer.android.com/reference/androidx/core/app/NotificationCompat) options

### Step 1: Create a class for the service extension

Create a class that implements `INotificationServiceExtension` and its `onNotificationReceived` method.

The `onNotificationReceived` method receives an `event` parameter of type [`INotificationReceivedEvent`](https://github.com/OneSignal/OneSignal-Android-SDK/blob/25924dc3739fbe3ae64a73efc7b504449a18cdea/OneSignalSDK/onesignal/core/src/main/java/com/onesignal/notifications/INotificationReceivedEvent.kt#L46).

<CodeGroup>
  ```java Java theme={null}
  package your.package.name

  import androidx.annotation.Keep;
  import com.onesignal.notifications.IActionButton;
  import com.onesignal.notifications.IDisplayableMutableNotification;
  import com.onesignal.notifications.INotificationReceivedEvent;
  import com.onesignal.notifications.INotificationServiceExtension;

  @Keep
  public class NotificationServiceExtension implements INotificationServiceExtension {

       @Override
       public void onNotificationReceived(INotificationReceivedEvent event) {
          IDisplayableMutableNotification notification = event.getNotification();

          if (notification.getActionButtons() != null) {
             for (IActionButton button : notification.getActionButtons()) {
                // Modify action buttons here
             }
          }
       }
  }
  ```

  ```kotlin Kotlin theme={null}
  package your.package.name

  import androidx.annotation.Keep
  import com.onesignal.notifications.INotificationReceivedEvent
  import com.onesignal.notifications.INotificationServiceExtension

  @Keep
  class NotificationServiceExtension : INotificationServiceExtension {
      override fun onNotificationReceived(event: INotificationReceivedEvent) {
          val notification = event.notification
          val context = event.context

          notification.actionButtons?.forEach { button ->
              // Modify action buttons here
          }
      }
  }
  ```
</CodeGroup>

<Note>
  The `@Keep` annotation is required in both Java and Kotlin to prevent code shrinking tools (R8 or ProGuard) from renaming or removing your class when minification is enabled.
</Note>

### Step 2: Customize the notification

Add your customization logic inside the `onNotificationReceived` method before registering the extension. The following tabs show common patterns.

<Tabs>
  <Tab title="Prevent display">
    Use `event.preventDefault()` to suppress automatic display, then call `display()` after performing async work.

    <CodeGroup>
      ```java Java theme={null}
      event.preventDefault();

      new Thread(() -> {
          try {
              Thread.sleep(1000);
          } catch (InterruptedException ignored) {}

          event.getNotification().display();
      }).start();
      ```

      ```kotlin Kotlin theme={null}
      event.preventDefault()

      Thread {
          try {
              Thread.sleep(1000)
          } catch (ignored: InterruptedException) {}

          event.notification.display()
      }.start()
      ```
    </CodeGroup>

    <Warning>
      If you call `event.preventDefault()` but never call `display()`, the notification is silently dropped. See [Duplicated notifications](./duplicated-notifications#android-notification-service-extension) for details on avoiding duplicate displays.
    </Warning>
  </Tab>

  <Tab title="Add a custom field">
    <CodeGroup>
      ```java Java theme={null}
      String promoCode = notification.getAdditionalData() != null
          ? notification.getAdditionalData().optString("promo_code", null)
          : null;

      if (promoCode != null) {
          String updatedBody = notification.getBody() + " Use code: " + promoCode;
          notification.setExtender(builder -> {
              builder.setContentText(updatedBody);
          });
      }
      ```

      ```kotlin Kotlin theme={null}
      val promoCode = notification.additionalData?.optString("promo_code", null)

      promoCode?.let {
          val updatedBody = "${notification.body}\nUse code: $promoCode"
          notification.setExtender { builder ->
              builder.setContentText(updatedBody)
          }
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Change color and icon">
    <CodeGroup>
      ```java Java theme={null}
      int iconResId = R.drawable.icon_default;
      String type = notification.getAdditionalData() != null
          ? notification.getAdditionalData().optString("type", "")
          : "";

      switch (type) {
          case "sale":
              iconResId = R.drawable.icon_sale;
              break;
          case "reminder":
              iconResId = R.drawable.icon_reminder;
              break;
      }

      int finalIconResId = iconResId;
      notification.setExtender(builder -> {
          builder.setColor(0xFF0000FF).setSmallIcon(finalIconResId);
      });
      ```

      ```kotlin Kotlin theme={null}
      val type = notification.additionalData?.optString("type", "") ?: ""

      val iconResId = when (type) {
          "sale" -> R.drawable.icon_sale
          "reminder" -> R.drawable.icon_reminder
          else -> R.drawable.icon_default
      }

      notification.setExtender { builder ->
          builder.setColor(0xFF0000FF).setSmallIcon(iconResId)
      }
      ```
    </CodeGroup>

    <Note>
      Icons referenced here must exist in the `res/drawable` directory.
    </Note>
  </Tab>
</Tabs>

### Step 3: Add the service extension to your AndroidManifest.xml

Add the class name and value as `meta-data` within the `<application>` tag of your `AndroidManifest.xml` file. Ignore any "unused" warnings.

```xml XML theme={null}
<application>
  <meta-data
    android:name="com.onesignal.NotificationServiceExtension"
    android:value="com.onesignal.example.NotificationServiceExtension" />
</application>
```

Replace `com.onesignal.example.NotificationServiceExtension` with your class's fully qualified name.

***

## iOS notification service extension

The [`UNNotificationServiceExtension`](https://developer.apple.com/reference/usernotifications/unnotificationserviceextension) allows you to modify push notification content before it is displayed. It is required for:

* [Images & rich media](./rich-media)
* [Confirmed receipt](./confirmed-delivery)
* [Badges](./badges)
* [Action buttons](./action-buttons)
* [Influenced opens with Firebase Analytics](./google-analytics-for-firebase)

If you followed the [Mobile SDK setup](./mobile-sdk-setup), the notification service extension is already configured. This section explains how to access the OneSignal notification payload data and troubleshoot issues.

### Getting the iOS push payload

Inside your `didReceive(_:withContentHandler:)` override, you call `OneSignalExtension.didReceiveNotificationExtensionRequest` to let OneSignal process the notification and invoke the content handler. Read or modify `bestAttemptContent` before calling this method.

In this example, a notification is sent with the following data:

```json JSON theme={null}
{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "headings": {"en": "The message title"},
  "contents": {"en": "The message contents"},
  "data":{
    "additional_data_key_1":"value_1",
    "additional_data_key_2":"value_2"
    },
  "include_subscription_ids": ["SUBSCRIPTION_ID_1"]
}
```

Access this additional `data` within the OneSignalNotificationServiceExtension via the `a` key inside the `custom` dictionary of `userInfo`:

<CodeGroup>
  ```swift Swift theme={null}
  if let bestAttemptContent = bestAttemptContent {

      if let customData = bestAttemptContent.userInfo["custom"] as? [String: Any],
         let additionalData = customData["a"] as? [String: Any] {

          if let jsonData = try? JSONSerialization.data(withJSONObject: additionalData, options: .prettyPrinted),
             let jsonString = String(data: jsonData, encoding: .utf8) {
              print("The additionalData dictionary in JSON format:\n\(jsonString)")
          } else {
              print("Failed to convert additionalData to JSON format.")
          }
      }

      if let messageData = bestAttemptContent.userInfo["aps"] as? [String: Any],
         let apsData = messageData["alert"] as? [String: Any],
         let body = apsData["body"] as? String,
         let title = apsData["title"] as? String {
          print("The message contents is: \(body), message headings is: \(title)")
      } else {
          print("Unable to retrieve apsData")
      }

      OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest,
                                                                with: bestAttemptContent,
                                                                withContentHandler: self.contentHandler)
  }
  ```

  ```objc Objective-C theme={null}
  if (bestAttemptContent) {
      NSDictionary *customData = bestAttemptContent.userInfo[@"custom"];
      if ([customData isKindOfClass:[NSDictionary class]]) {
          NSDictionary *additionalData = customData[@"a"];
          if ([additionalData isKindOfClass:[NSDictionary class]]) {
              NSError *error;
              NSData *jsonData = [NSJSONSerialization dataWithJSONObject:additionalData options:NSJSONWritingPrettyPrinted error:&error];
              if (jsonData) {
                  NSString *jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
                  NSLog(@"The additionalData dictionary in JSON format:\n%@", jsonString);
              } else {
                  NSLog(@"Failed to convert additionalData to JSON format: %@", error.localizedDescription);
              }
          }
      }

      NSDictionary *messageData = bestAttemptContent.userInfo[@"aps"];
      if ([messageData isKindOfClass:[NSDictionary class]]) {
          NSDictionary *apsData = messageData[@"alert"];
          if ([apsData isKindOfClass:[NSDictionary class]]) {
              NSString *body = apsData[@"body"];
              NSString *title = apsData[@"title"];
              if ([body isKindOfClass:[NSString class]] && [title isKindOfClass:[NSString class]]) {
                  NSLog(@"The message content is: %@, message heading is: %@", body, title);
              }
          } else {
              NSLog(@"Unable to retrieve apsData");
          }
      }

      [OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
                                               withNotification:bestAttemptContent
                                                withContentHandler:self.contentHandler];
  }
  ```
</CodeGroup>

**Example console output:**

```
The additionalData dictionary in JSON format:
{
  "additional_data_key_1" : "value_1",
  "additional_data_key_2" : "value_2"
}
The message contents is: The message contents, message headings is: The message title
```

### Troubleshooting the iOS notification service extension

Use this section to debug issues with images, action buttons, or confirmed deliveries not showing on iOS.

#### Check your Xcode settings

In **General > Targets**, verify that your **main app target** and **OneSignalNotificationServiceExtension** target have the same:

* **Supported Destinations**
* **Minimum Deployment** (iOS 14.5 or higher)

<Warning>
  If you are using CocoaPods, make sure these match with your main target in the Podfile to avoid build errors.
</Warning>

<Frame>
  <img alt="Xcode General tab showing Supported Destinations and Minimum Deployment for the main app target" />
</Frame>

<Frame>
  <img alt="Xcode General tab showing Supported Destinations and Minimum Deployment for the notification service extension target" />
</Frame>

In the **OneSignalNotificationServiceExtension > Info** tab, expand the `NSExtension` key and verify it contains:

```xml XML theme={null}
<dict>
  <key>NSExtensionPointIdentifier</key>
  <string>com.apple.usernotifications.service</string>
  <key>NSExtensionPrincipalClass</key>
  <string>$(PRODUCT_MODULE_NAME).NotificationService</string>
</dict>
```

<Frame>
  <img alt="Xcode Info tab showing the NSExtension dictionary with NSExtensionPointIdentifier and NSExtensionPrincipalClass keys" />
</Frame>

<Warning>
  If using Objective-C, replace `$(PRODUCT_MODULE_NAME).NotificationService` with `NotificationService`.
</Warning>

#### Turn off "Copy only when installing"

Select your **main app target > Build Phases > Embed App Extensions**. Ensure "Copy only when installing" is **not** checked:

<Frame>
  <img alt="Xcode Build Phases tab showing Embed App Extensions with Copy only when installing unchecked" />
</Frame>

### Debugging the iOS notification service extension

Follow these steps to verify the notification service extension is set up correctly.

#### 1. Update the OneSignalNotificationServiceExtension code

Open `NotificationService.m` or `NotificationService.swift` and replace the file contents with the code below. This adds logging to help verify the extension is running.

Replace `YOUR_BUNDLE_ID` with your actual Bundle ID.

<CodeGroup>
  ```swift Swift theme={null}
  import UserNotifications
  import OneSignalExtension
  import os.log

  class NotificationService: UNNotificationServiceExtension {

      var contentHandler: ((UNNotificationContent) -> Void)?
      var receivedRequest: UNNotificationRequest!
      var bestAttemptContent: UNMutableNotificationContent?

      override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
          self.receivedRequest = request
          self.contentHandler = contentHandler
          self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

          let userInfo = request.content.userInfo
          let custom = userInfo["custom"]
          print("Running NotificationServiceExtension: userInfo = \(userInfo.description)")
          print("Running NotificationServiceExtension: custom = \(custom.debugDescription)")
          os_log("%{public}@", log: OSLog(subsystem: "YOUR_BUNDLE_ID", category: "OneSignalNotificationServiceExtension"), type: OSLogType.debug, userInfo.debugDescription)

          if let bestAttemptContent = bestAttemptContent {
              // Prepend "[Modified]" to confirm the extension is running
              print("Running NotificationServiceExtension")
              bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

              OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
          }
      }

      override func serviceExtensionTimeWillExpire() {
          if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
              OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
              contentHandler(bestAttemptContent)
          }
      }
  }
  ```

  ```objc Objective-C theme={null}
  #import <OneSignalExtension/OneSignalExtension.h>

  #import "NotificationService.h"

  @interface NotificationService ()

  @property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
  @property (nonatomic, strong) UNNotificationRequest *receivedRequest;
  @property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

  @end

  @implementation NotificationService

  - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
      self.receivedRequest = request;
      self.contentHandler = contentHandler;
      self.bestAttemptContent = [request.content mutableCopy];

      NSUserDefaults *userDefault = [[NSUserDefaults alloc] initWithSuiteName:@"group.YOUR_BUNDLE_ID.onesignal"];
      NSLog(@"NSE player_id: %@", [userDefault stringForKey:@"GT_PLAYER_ID"]);
      NSLog(@"NSE app_id: %@", [userDefault stringForKey:@"GT_APP_ID"]);

      // Prepend "[Modified]" to confirm the extension is running
      NSLog(@"Running NotificationServiceExtension");
      self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];

      [OneSignal.Debug setLogLevel:ONE_S_LL_VERBOSE];

      [OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
                                                withNotification:self.bestAttemptContent
                                              withContentHandler:self.contentHandler];
  }

  - (void)serviceExtensionTimeWillExpire {
      [OneSignalExtension serviceExtensionTimeWillExpireRequest:self.receivedRequest
                                               withNotification:self.bestAttemptContent];

      self.contentHandler(self.bestAttemptContent);
  }

  @end
  ```
</CodeGroup>

<Note>
  Debug log types need to be enabled in Console via **Action > Include Debug Messages**.
</Note>

#### 2. Change your active scheme

Set your Active Scheme to `OneSignalNotificationServiceExtension`.

<Frame>
  <img alt="Xcode toolbar showing the active scheme dropdown set to OneSignalNotificationServiceExtension" />
</Frame>

#### 3. Build and run the project

Build and run the project in Xcode on a real device.

#### 4. Open the console

In Xcode, select **Window > Devices and Simulators**.

<Frame>
  <img alt="Xcode menu showing the Window dropdown with Devices and Simulators selected" />
</Frame>

You should see your device connected. Select **Open Console**.

<Frame>
  <img alt="Xcode Devices window showing the Open Console button for a connected device" />
</Frame>

#### 5. Check the console

In the Console:

1. Select **Action > Include Debug Messages**
2. Search for `OneSignalNotificationServiceExtension` as the CATEGORY
3. Select **Start**

<Frame>
  <img alt="macOS Console app showing the category filter and Start button for debugging the notification service extension" />
</Frame>

Send a notification to the device with a message body (use the `contents` property if sending from the [Create notification](/reference/push-notification) API). Example payload:

```curl cURL theme={null}
curl --request POST \
 --url 'https://api.onesignal.com/notifications' \
 --header 'Authorization: Key YOUR_API_KEY' \
 --header 'accept: application/json' \
 --header 'content-type: application/json' \
 --data '
{
"app_id": "YOUR_APP_ID",
"target_channel": "push",
"headings": {"en": "The message title"},
"contents": {"en": "The message contents"},
"data":{"additional_data_key_1":"value_1","additional_data_key_2":"value_2"},
"include_subscription_ids": [
"SUBSCRIPTION_ID_1"
]
}'
```

You should see a message logged whether the app is running or not.

<Frame>
  <img alt="macOS Console app showing debug log output from the OneSignalNotificationServiceExtension" />
</Frame>

If you do not see a message, remove OneSignal from your app and follow the [Mobile SDK setup](./mobile-sdk-setup) again to verify the integration.

## FAQ

### Why isn't my notification service extension running on iOS?

The extension only runs when `mutable-content` is set in the push payload. OneSignal sets this automatically when you include an attachment or action buttons. Verify your Xcode settings match the requirements in the [troubleshooting section](#troubleshooting-the-ios-notification-service-extension).

### Can I prevent a notification from displaying on Android?

Yes. Call `event.preventDefault()` in your `onNotificationReceived` method to suppress automatic display. You can then call `event.getNotification().display()` to show it later, or never call `display()` to silently drop the notification without displaying it. See [Duplicated notifications](./duplicated-notifications#android-notification-service-extension) for details on avoiding duplicates when using this pattern.

### Do I need the @Keep annotation on Android?

Yes. The `@Keep` annotation prevents ProGuard or R8 from renaming or removing your class that implements `INotificationServiceExtension` during minification. Without it, OneSignal cannot find the class at runtime.

## Related pages

<Columns>
  <Card title="Mobile SDK setup" icon="mobile" href="./mobile-sdk-setup">
    Install and configure the OneSignal SDK for iOS and Android.
  </Card>

  <Card title="Images & rich media" icon="image" href="./rich-media">
    Attach images, GIFs, and video to push notifications.
  </Card>

  <Card title="Confirmed receipt" icon="check" href="./confirmed-delivery">
    Track confirmed notification delivery to devices.
  </Card>

  <Card title="Duplicated notifications" icon="clone" href="./duplicated-notifications">
    Troubleshoot duplicate push notifications on all platforms.
  </Card>
</Columns>


# Social activity
Source: https://documentation.onesignal.com/docs/en/social-activity

Send push, email, and SMS notifications for social actions including likes, follows, direct messages, and competitive gaming events. Uses custom_data for personalized, backend-triggered alerts.

Notify users when something happens that involves them: a like, a reply, a follow, an incoming message, or a competitive event in a game. These notifications drive re-engagement even when users aren't currently active in your app.

<Note>
  OneSignal is not designed for real-time communication. Push notifications are best used as a fallback when users are not actively in the app. For real-time in-app messaging, use your app's existing messaging layer and trigger OneSignal notifications only when the recipient is offline or inactive.
</Note>

<Columns>
  <Card title="Social activity" icon="heart" href="#social-activity-notifications">
    Notify users when someone likes, comments, mentions, tags, or follows them.
  </Card>

  <Card title="Direct messages" icon="message" href="#direct-user-to-user-messages">
    Alert users to new incoming messages with debouncing and conversation deep links.
  </Card>

  <Card title="Gaming alerts" icon="gamepad" href="./social-activity#gaming%3A-competitive-and-social-alerts">
    Send time-sensitive competitive events like base attacks, challenges, and guild activity.
  </Card>
</Columns>

## Prerequisites

Before you begin, make sure you have:

* The OneSignal SDK installed on your app. See [Mobile SDK setup](./mobile-sdk-setup) or [Web SDK setup](./web-push-setup).
* An `external_id` set for every user so you can target them by your own identifier. See [Users & Aliases](./users).
* A backend that can detect social actions and call the OneSignal API. See [REST API overview](/reference/rest-api-overview).
* [Templates](./templates) created in the dashboard if you plan to use `custom_data` for personalization. A `template_id` is required to use `custom_data`.

<Warning>
  **Keep `custom_data` payloads under 2KB.** The `custom_data` field has a hard size limit. Sending large payloads — full conversation lists, leaderboard arrays, base64 images, or HTML — risks truncation or rejection. For rich content, pass an identifier (e.g., `digest_id` or `summary_url`) and have the recipient's device fetch the full payload from your backend on tap. See [Personalize messages with API custom\_data](./personalization-api-custom-data) for the size limit details and array-iteration patterns.
</Warning>

## Social activity notifications

Send a push notification when a user is involved in a social action. Use `custom_data` to inject the sender's name, avatar, and relevant context into the message at send time. No data is stored in OneSignal.

### Common social actions

| Action  | Example notification                   |
| ------- | -------------------------------------- |
| Like    | "Anna liked your photo."               |
| Comment | "Leo replied: 'Looks awesome!'"        |
| Mention | "Sara mentioned you in a comment."     |
| Tag     | "James tagged you in a post."          |
| Follow  | "Maya started following you."          |
| Invite  | "Ben invited you to the event."        |
| Share   | "Alex shared 'Hawaii Album' with you." |

### Setup

<Steps>
  <Step title="Detect the action on your backend">
    When a social action occurs, your backend identifies the sender and recipient, plus any relevant context like post ID or content:

    ```json JSON theme={null}
    {
      "action": "like",
      "sender_id": "user_b",
      "sender_name": "Anna",
      "sender_avatar": "https://cdn.yourapp.com/avatars/anna.jpg",
      "recipient_id": "user_a",
      "post_id": "xyz789",
      "post_title": "My Hawaii trip"
    }
    ```
  </Step>

  <Step title="Create a push template">
    In the dashboard, go to **Messages > Templates > New Push Template**. Use Liquid syntax to reference `custom_data` fields:

    **Heading:**

    ```liquid Liquid theme={null}
    {{ message.custom_data.sender_name | default: "Someone" }}
    ```

    **Message:**

    ```liquid Liquid theme={null}
    {{ message.custom_data.sender_name | default: "Someone" }} liked your post "{{ message.custom_data.post_title | default: "your post" }}".
    ```

    **Image (optional, displays the sender's avatar):**

    ```liquid Liquid theme={null}
    {{ message.custom_data.sender_avatar }}
    ```

    Save the template and note its `template_id`.
  </Step>

  <Step title="Call the Create Message API">
    From your backend, send the notification to the recipient:

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user_a"]
      },
      "custom_data": {
        "sender_name": "Anna",
        "sender_avatar": "https://cdn.yourapp.com/avatars/anna.jpg",
        "post_title": "My Hawaii trip",
        "post_id": "xyz789"
      },
      "url": "yourapp://posts/xyz789"
    }
    ```

    OneSignal renders the template at send time using the `custom_data` values. The sender's name and avatar appear in the notification without being stored in OneSignal.
  </Step>

  <Step title="Optional: add email and SMS fallbacks">
    To reach users who have push disabled or whose notification went undelivered, see [Email and SMS fallbacks](#email-and-sms-fallbacks) below.
  </Step>
</Steps>

<Tip>
  Use `| default:` filters in every Liquid placeholder so the message still reads naturally if a field is missing. For example: `{{ message.custom_data.sender_name | default: "Someone" }}`. See [Using Liquid syntax](./using-liquid-syntax) for more filters.
</Tip>

<Tip>
  **Avatar and image URL requirements.** The `sender_avatar` URL (and any other notification image) must be:

  * **HTTPS** — iOS rejects HTTP URLs.
  * **Publicly accessible** — APNs and FCM cannot send authenticated requests.
  * **Under \~1 MB** — iOS limit is 10 MB but practical delivery windows favor smaller assets.
  * **Served with the correct `Content-Type` header** — `image/jpeg`, `image/png`, etc.

  Hosting from a CDN with cached headers is the safest setup.
</Tip>

### Throttle high-volume actions

A viral post can generate thousands of `like` events per second. Don't send a push for each one — that floods the recipient and gets your app muted or uninstalled. The pattern:

1. Accumulate counts on your backend (e.g., a Redis counter keyed by recipient + post).
2. After a quiet window (10 minutes is a reasonable default), send a single digest push: "12 people liked your post."
3. If more likes arrive after the digest, start a fresh window — don't immediately push again.

The same logic applies to comments, follows, and reactions. See [Throttling](./throttling) for OneSignal-side rate limits if your backend can't debounce.

## Direct (user-to-user) messages

Notify a user when they receive a new direct message, and deep link them directly into the conversation.

<Note>
  Only send a push when the recipient is not actively in the chat. Notifying someone who is already reading the conversation creates a poor experience. Use your app's own logic to check whether the recipient is currently active before triggering a notification. OneSignal does not track whether a user is currently using your app.
</Note>

### Setup

<Steps>
  <Step title="Detect when a message is sent and check activity">
    When User A sends a message to User B, check whether User B is currently active in that conversation. If User B is offline or not in the conversation, proceed to send a push.
  </Step>

  <Step title="Avoid sending one push per message">
    If User A sends several messages in a row, wait a short period after the last message before triggering a notification. Here is how to do this in your backend:

    1. When the first message arrives, start a timer (for example, 60 seconds).
    2. If another message arrives before the timer runs out, reset it.
    3. When the timer runs out with no new messages, send a single push summarizing the unread count.

    OneSignal does not consolidate multiple API calls automatically, so if you call the API five times, five notifications are sent.
  </Step>

  <Step title="Send the push notification">
    Send a push to User B with a deep link to the conversation:

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "headings": { "en": "New message" },
      "contents": { "en": "Anna: 'Hey, you around?'" },
      "include_aliases": {
        "external_id": ["user_b_id"]
      },
      "url": "yourapp://chat/chat_1234",
      "data": {
        "click_action": "open_chat",
        "conversation_id": "chat_1234",
        "sender_id": "user_a_id"
      }
    }
    ```

    Your app reads `data.conversation_id` on notification open and navigates to the correct screen. See [Deep linking](./deep-linking) for platform-specific setup.
  </Step>

  <Step title="Optional: add email and SMS fallbacks">
    To reach users who have push disabled or whose notification went undelivered, see [Email and SMS fallbacks](#email-and-sms-fallbacks) below.
  </Step>
</Steps>

<Tip>
  **Group notifications by conversation natively.** Backend debouncing reduces *how many* notifications fire, but iOS and Android can also visually collapse multiple notifications into a single thread. Set a thread or collapse identifier (e.g., the `conversation_id`) so the OS groups messages from the same chat. See [Notification grouping](./push#notification-grouping).
</Tip>

<Tip>
  **Update the badge count on each new message.** Most chat apps want the iOS/Android badge to reflect total unread messages across all conversations. Pass the unread count via the API on each push so the badge stays accurate even when a user clears one notification but has others outstanding. See [Badges](./push#badges).
</Tip>

<Warning>
  **Lock Screen privacy.** iOS shows notification content on the Lock Screen by default — including the message preview ("Anna: 'Hey, you around?'"). For messaging apps with sensitive content (health, finance, dating, professional), consider sending a generic preview ("New message from Anna") and let users opt into full previews via your in-app settings.
</Warning>

## Gaming: competitive and social alerts

Competitive games benefit from time-sensitive alerts that create urgency. Use `custom_data` to make these notifications feel specific and personal. A notification that names the attacker or shows exact resource counts is far more compelling than a generic alert.

### Common competitive events

| Event          | Example notification                                                       |
| -------------- | -------------------------------------------------------------------------- |
| Base attack    | "Your village is under attack! Orca is raiding your base."                 |
| Challenge      | "DragonSlayer99 challenged you to a ranked duel. You have 24h to respond." |
| Leaderboard    | "You've been knocked out of the top 10. Orca just passed you at #8."       |
| Guild event    | "Guild war starts in 30 minutes. BladeClan is counting on you!"            |
| Clan invite    | "DragonSlayer99 invited you to join BladeClan."                            |
| Resource ready | "Your troops are trained and ready to deploy."                             |

### Setup

<Steps>
  <Step title="Detect the game event on your backend">
    When a competitive event occurs, your game backend identifies the affected player and captures relevant context:

    ```json JSON theme={null}
    {
      "event": "base_attack",
      "attacker_id": "user_orca",
      "attacker_name": "Orca",
      "recipient_id": "user_dragon",
      "resources_at_risk": {
        "gold": 12400,
        "elixir": 8200
      }
    }
    ```
  </Step>

  <Step title="Create a push template">
    In the dashboard, create a Push Template with Liquid references:

    **Heading:**

    ```liquid Liquid theme={null}
    ⚔️ Your village is under attack!
    ```

    **Message:**

    ```liquid Liquid theme={null}
    {{ message.custom_data.attacker_name | default: "An enemy" }} is raiding your base. You're at risk of losing {{ message.custom_data.gold | default: "0" }} gold and {{ message.custom_data.elixir | default: "0" }} elixir.
    ```

    Save the template and note its `template_id`.
  </Step>

  <Step title="Send the notification">
    Call the Create Message API from your game backend:

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user_dragon"]
      },
      "custom_data": {
        "attacker_name": "Orca",
        "gold": "12400",
        "elixir": "8200"
      },
      "url": "yourgame://base/defend",
      "data": {
        "event": "base_attack",
        "attacker_id": "user_orca"
      }
    }
    ```

    The `url` deep links the player directly to the defend screen. The `data` object passes context to your app's notification handler so it can load the correct battle state.
  </Step>

  <Step title="Optional: add email and SMS fallbacks">
    To reach players who have push disabled or whose notification went undelivered, see [Email and SMS fallbacks](#email-and-sms-fallbacks) below.
  </Step>
</Steps>

<Tip>
  **Respect quiet hours for non-urgent alerts.** Base-attack pushes at 3 AM local time are a known opt-out driver. Split your gaming alerts into two tiers:

  * **Time-critical** (guild war starting in 30 minutes, base under attack right now) — send immediately regardless of local time.
  * **Non-time-critical** (troops are ready, daily reward available, weekly recap) — use [Intelligent Delivery or Custom time per timezone](./push#delivery-schedule-and-optimization) so they land in waking hours in the player's local timezone.

  Most gaming-alert opt-outs come from the second category sending at the wrong time, not from the first category being too frequent.
</Tip>

<Tip>
  **Consider Live Activities for in-progress events.** For ongoing matches, raids, or live events on iOS 16.1+, a [Live Activity](./live-activities) on the Lock Screen and Dynamic Island is often a better experience than repeated push notifications updating the same context. Use Live Activities for the live state ("23 minutes remaining, you're #4") and reserve push for milestone or completion moments.
</Tip>

### More gaming alert examples

<Tabs>
  <Tab title="Leaderboard overtake">
    **Template message:**

    ```liquid Liquid theme={null}
    {{ message.custom_data.overtaker_name | default: "Another player" }} just passed you. You dropped from #{{ message.custom_data.previous_rank }} to #{{ message.custom_data.current_rank }} on the leaderboard.
    ```

    **API request:**

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user_dragon"]
      },
      "custom_data": {
        "overtaker_name": "Orca",
        "previous_rank": "8",
        "current_rank": "9"
      },
      "url": "yourgame://leaderboard"
    }
    ```
  </Tab>

  <Tab title="Guild event">
    Send to all guild members simultaneously by passing multiple `external_id` values. Each receives the same message.

    **Template message:**

    ```liquid Liquid theme={null}
    Guild war alert! {{ message.custom_data.guild_name | default: "Your guild" }} clashes in {{ message.custom_data.minutes_until | default: "30" }} minutes. Get in position.
    ```

    **API request:**

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user_dragon", "user_orca", "user_shadow"]
      },
      "custom_data": {
        "guild_name": "BladeClan",
        "minutes_until": "30"
      },
      "url": "yourgame://guild/war"
    }
    ```
  </Tab>

  <Tab title="Challenge invite">
    **Template message:**

    ```liquid Liquid theme={null}
    {{ message.custom_data.challenger_name | default: "A player" }} challenged you to a {{ message.custom_data.game_mode | default: "duel" }}. You have {{ message.custom_data.hours_to_respond | default: "24" }} hours to accept.
    ```

    **API request:**

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user_dragon"]
      },
      "custom_data": {
        "challenger_name": "DragonSlayer99",
        "game_mode": "ranked duel",
        "hours_to_respond": "24"
      },
      "url": "yourgame://challenges/incoming",
      "data": {
        "challenge_id": "chal_9876",
        "challenger_id": "user_dragonslayer99"
      }
    }
    ```
  </Tab>
</Tabs>

## Email and SMS fallbacks

Add an email or SMS fallback to any notification type to reach users who have push disabled or whose notification was not delivered. Use the [View Message API](/reference/view-message) to check for a [confirmed receipt](./confirmed-delivery) or click. If none is recorded within your delay window, send a follow-up using the same `custom_data` approach with an Email or SMS template.

<Tabs>
  <Tab title="Email">
    **Social activity**

    Best for high-value actions like mentions and direct replies.

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_EMAIL_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user_a"]
      },
      "custom_data": {
        "sender_name": "Anna",
        "sender_avatar": "https://cdn.yourapp.com/avatars/anna.jpg",
        "action": "liked your post",
        "post_title": "My Hawaii trip",
        "post_url": "https://yourapp.com/posts/xyz789"
      }
    }
    ```

    **Email template example (subject):**

    ```liquid Liquid theme={null}
    {{ message.custom_data.sender_name | default: "Someone" }} {{ message.custom_data.action | default: "interacted with your post" }}
    ```

    **Direct messages**

    Best as a daily digest of unread conversations rather than per-message alerts.

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_EMAIL_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user_b_id"]
      },
      "custom_data": {
        "unread_count": "3",
        "conversations": [
          { "sender_name": "Anna", "preview": "Hey, you around?", "url": "https://yourapp.com/chat/chat_1234" },
          { "sender_name": "Leo", "preview": "Did you see this?", "url": "https://yourapp.com/chat/chat_5678" }
        ]
      }
    }
    ```

    **Email template example (subject):**

    ```liquid Liquid theme={null}
    You have {{ message.custom_data.unread_count | default: "new" }} unread message{% if message.custom_data.unread_count != "1" %}s{% endif %}
    ```

    **Email template example (body, iterating over the conversations array):**

    ```liquid Liquid theme={null}
    <h2>You have {{ message.custom_data.unread_count }} unread messages</h2>
    <ul>
      {% for conversation in message.custom_data.conversations %}
        <li>
          <strong>{{ conversation.sender_name }}:</strong>
          "{{ conversation.preview }}"
          <a href="{{ conversation.url }}">Open</a>
        </li>
      {% endfor %}
    </ul>
    ```

    See [Personalize messages with API custom\_data](./personalization-api-custom-data) for the full array-iteration reference, including nested objects and conditional rendering.

    **Gaming**

    Best for non-urgent recaps like weekly leaderboard summaries, guild war results, or milestone unlocks.

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_EMAIL_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user_dragon"]
      },
      "custom_data": {
        "player_name": "DragonSlayer99",
        "rank": "7",
        "rank_change": "+3",
        "top_players": [
          { "name": "Orca", "score": "48200" },
          { "name": "Shadow", "score": "45100" },
          { "name": "DragonSlayer99", "score": "43800" }
        ],
        "summary_url": "https://yourgame.com/rankings/weekly"
      }
    }
    ```

    **Email template example (subject):**

    ```liquid Liquid theme={null}
    Your weekly rankings: #{{ message.custom_data.rank }} ({{ message.custom_data.rank_change }} this week)
    ```
  </Tab>

  <Tab title="SMS">
    **Social activity**

    Best for high-importance actions like mentions and direct replies, not routine likes or follows.

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_SMS_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user_a"]
      },
      "custom_data": {
        "sender_name": "Anna",
        "post_title": "My Hawaii trip",
        "post_url": "https://yourapp.com/posts/xyz789"
      }
    }
    ```

    **SMS template example:**

    ```liquid Liquid theme={null}
    {{ message.custom_data.sender_name | default: "Someone" }} mentioned you in "{{ message.custom_data.post_title | default: "a post" }}". Tap to reply: {{ message.custom_data.post_url }}
    ```

    **Direct messages**

    Best for individual missed messages rather than bulk message sequences.

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_SMS_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user_b_id"]
      },
      "custom_data": {
        "sender_name": "Anna",
        "message_preview": "Hey, you around?",
        "conversation_url": "https://yourapp.com/chat/chat_1234"
      }
    }
    ```

    **SMS template example:**

    ```liquid Liquid theme={null}
    New message from {{ message.custom_data.sender_name | default: "a user" }}: "{{ message.custom_data.message_preview }}". Reply in the app: {{ message.custom_data.conversation_url }}
    ```

    **Gaming**

    Best for time-critical events like base attacks where the player needs to act immediately.

    ```json JSON theme={null}
    {
      "app_id": "YOUR_APP_ID",
      "template_id": "YOUR_SMS_TEMPLATE_ID",
      "include_aliases": {
        "external_id": ["user_dragon"]
      },
      "custom_data": {
        "attacker_name": "Orca",
        "gold": "12400",
        "game_url": "https://yourgame.com/base/defend"
      }
    }
    ```

    **SMS template example:**

    ```liquid Liquid theme={null}
    ⚔️ ATTACK! {{ message.custom_data.attacker_name | default: "An enemy" }} is raiding your base. {{ message.custom_data.gold | default: "0" }} gold at risk. Defend now: {{ message.custom_data.game_url }}
    ```
  </Tab>
</Tabs>

<Tip>
  Give users control over their fallback preferences. An opt-in like "Notify me by SMS if I miss a message" helps prevent unwanted messages for users who intentionally have push disabled.
</Tip>

## FAQ

### Can OneSignal send notifications in real time, like a chat app?

No. Push notifications are delivered through Apple (APNs) and Google (FCM) infrastructure, which introduces variable delivery times and no delivery guarantees. Use your app's existing messaging layer for real-time in-app communication and use OneSignal as a fallback when the recipient is not actively in the app.

### How do I avoid notifying a user who is already in the app?

OneSignal does not track whether a user is currently active in your app. Your own backend logic must determine whether to trigger the notification. Only call the OneSignal API when you've confirmed the recipient is offline or not in the relevant screen.

### How do I prevent multiple notifications from rapid message sequences?

Add a short delay in your backend before sending a notification. When the first message arrives, start a timer. If another message comes in before it runs out, reset it. When the timer runs out, send a single push with the unread count. OneSignal does not consolidate multiple API calls automatically, so if you call the API five times, five notifications are sent.

### Is `custom_data` saved to the user's profile after the message sends?

No. `custom_data` is ephemeral and exists only during the API request, used to render the template at send time. It is not stored in OneSignal and cannot be reused in future messages or Journeys. For persistent user data, use [Tags](./message-personalization).

### Can I target multiple recipients in one API call?

Yes. Pass multiple `external_id` values in the `include_aliases` array. If each recipient needs different personalized content (for example, different attacker names), use the bulk personalization pattern in `custom_data`. See [Personalize messages with API custom\_data](./personalization-api-custom-data) for the full approach. The exact per-call recipient cap and rate limits are documented on the [Create Message API reference](/reference/create-message) — for very large audiences, segment-based targeting is more efficient than passing thousands of `external_id` values per call.

### Do I need to localize messages for international users?

Yes for any audience that spans languages. The `headings` and `contents` fields accept multiple language codes (e.g., `{ "en": "...", "es": "...", "fr": "..." }`) and OneSignal selects the right variant based on each subscription's language. The same pattern applies to template fields. See [Multi-language messaging](./multi-language-messaging) for the full reference, including fallback language behavior.

## Related pages

<Columns>
  <Card title="Personalize messages with API custom_data" icon="sparkles" href="./personalization-api-custom-data">
    Inject dynamic, message-specific data into templates using custom\_data and Liquid syntax.
  </Card>

  <Card title="Message personalization" icon="user" href="./message-personalization">
    Overview of all personalization options in OneSignal, including Tags, user attributes, and segmentation.
  </Card>

  <Card title="Deep linking" icon="link" href="./deep-linking">
    Route users to a specific screen in your app when they tap a notification.
  </Card>

  <Card title="Create an Activity Feed" icon="list" href="./create-an-activity-feed">
    Display a history of social alerts inside your app using OneSignal's notification inbox.
  </Card>

  <Card title="Templates" icon="file" href="./templates">
    Create and manage reusable message templates for push, email, and SMS.
  </Card>

  <Card title="Create Message API" icon="code" href="/reference/create-message">
    Complete API reference for sending messages with custom\_data, targeting, and all available fields.
  </Card>
</Columns>


# Transactional messages
Source: https://documentation.onesignal.com/docs/en/transactional-messages

Learn how to send transactional messages like OTPs, billing updates, and reminders using OneSignal’s API with personalized data via push, email, or SMS.

Sending timely and personalized messages to individuals or small groups is critical to delivering a strong customer experience and maintaining engagement. Transactional messages—such as One-Time Passcodes (OTPs), billing updates, or activity confirmations—allow you to share meaningful, real-time updates from your server.

This guide explains how to send transactional messages (push, email, or SMS) with OneSignal's API using custom data and user identifiers.

***

## Common use cases

Use transactional messages to:

* Send login and verification codes (OTP)
* Confirm orders, receipts, or subscription changes
* Deliver billing status or renewal alerts
* Remind users about appointments or deadlines
* Acknowledge key actions (e.g. signups or purchases)

***

## Requirements

Before sending transactional messages, we suggest reviewing the following guides:

* Understand OneSignal [Users](./users), [Subscriptions](./subscriptions), and [Aliases](./aliases).
* Setup your [Database, DMP, or CRM to communicate with OneSignal](./database-dmp-crm-integration) or use one of our [Integrations](./integrations).
* Create [Templates](./templates) to personalize your messages.
* Use [Liquid Syntax](./using-liquid-syntax) to personalize your messages.

***

## Identifying users

To target individual users, you must identify them within OneSignal. The recommended approach is to set an **External ID**, which should map to the user identifier used in your database or CRM.

OneSignal also supports up to **10 aliases per user**, enabling you to associate multiple identifiers (e.g., `other_user_id`, `facebook_id`, etc.) across your systems. For email and SMS, you can also send messages directly using the email address or phone number respectively.

***

## Targeting users

Use the [Create Message API](/reference/create-message) to send transactional messages across push, email, and SMS channels by targeting users via aliases, email addresses, phone numbers, or subscription IDs.

### Send to aliases (recommended)

Use `include_aliases` to target the recommended `external_id` or other aliases like so:

<CodeGroup>
  ```json external_id theme={null}
  {
    "app_id": "YOUR_APP_ID",
    "include_aliases": {"external_id": ["userA", "userB"]},
    "contents": {"en": "English Message"},
    "target_channel": "push"
  }
  ```

  ```json custom_alias theme={null}
  {
    "app_id": "YOUR_APP_ID",
    "include_aliases": { "alias_label": ["alias_id_1", "alias_id_2"] },
    "contents": { "en": "English Message" },
    "target_channel": "email"
  }
  ```
</CodeGroup>

### Send to subscriptions

If you want to send to specific Subscriptions, you can use the `include_subscription_ids` property. This option is not recommended because Users can have multiple Subscriptions.

```json theme={null}
{
  "app_id": "YOUR_APP_ID",
  "include_subscription_ids": ["1dd608f2-c6a1-11e3-851d-000c2940e62c"],
  "contents": { "en": "English Message" }
}
```

### Send to email addresses

If you have the user's email address, you can send emails to them using the `include_email_tokens` property.

Any emails included that do not exist within your OneSignal app will automatically create a new email subscription.

```json theme={null}
{
  "app_id": "YOUR_APP_ID",
  "include_email_tokens": ["user1@email.com", "user2@email.com"],
  "email_subject": "Welcome to Cat Facts!",
  "email_body": "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts</h1><h4>Learn more about everyone's favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can't wait to surprise you with funny details about your favorite animal.</p><h5>Today's Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href='https://catfac.ts/welcome'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href='[unsubscribe_url]'>Unsubscribe</a></small></p></body></html>"
}
```

### Send to phone numbers

If you have the user's phone number, you can send them SMS and MMS using the `include_phone_numbers` property.

Any phone numbers included that do not exist within your OneSignal app will automatically create a new SMS subscription.

```json theme={null}
{
  "app_id": "YOUR_APP_ID",
  "include_phone_numbers": ["+15555555555"],
  "contents": { "en": "English Message" }
}
```

***

## Adding custom data

For personalized content, pass user-specific `custom_data` to the message using Templates and Liquid syntax.

Steps to add custom data:

1. Create a [Template](./templates) via the dashboard or [Create template API](/reference/create-template).
2. Add [Liquid Variables](./using-liquid-syntax) (e.g., `{{ message.custom_data.order_id }}`) to your template.
3. Reference the `template_id` and `custom_data` within your Create Message API call.

```json theme={null}
{
  "app_id": "YOUR_APP_ID",
  "include_aliases": { "external_id": ["userA"] },
  "template_id": "8458af75-4da2-4ecf-afb5-f242a8926cc3",
  "custom_data": { "order_id": 123, "currency": "USD", "amount": 25 }
}
```

### Example: One-Time Passcode (OTP)

1. Identify the user using an alias, email, or phone number.
2. Create a Template that includes a verification code:

```
Your verification code is {{ message.custom_data.verification_code }}
```

3. Generate the `verification_code` on your server when the user requests access.
4. Input the `verification_code` value into the API request.

```json theme={null}
{
  "app_id": "YOUR_APP_ID",
  "include_aliases": { "external_id": ["userA"] },
  "template_id": "8458af75-4da2-4ecf-afb5-f242a8926cc3",
  "custom_data": { "verification_code": "123456" }
}
```

**Alternative:** If you don't want to use templates and `custom_data` you can input the variable value directly into the message with string concatenation. For example:

```json theme={null}
{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"external_id": ["userA"]},
  "contents": {"en": "Your verification code is " + verification_code}
}
```

***

## Troubleshooting

* For `include_aliases`, the alias must be registered on the user beforehand.
* For email/SMS, ensure correct formatting.

***

## Additional Resources

* [Create message guide](/reference/create-message)
* [Users](./users) and [Aliases](./aliases)
* [Templates](./templates) and [Liquid Syntax](./using-liquid-syntax)
* [Rate Limits](/reference/rate-limits)

***


# Web SDK troubleshooting
Source: https://documentation.onesignal.com/docs/en/troubleshooting-web-push

Troubleshoot OneSignal Web Push issues including service worker errors, origin mismatches, MIME types, and notifications not showing.

## Overview

This guide walks you through troubleshooting your OneSignal Web SDK setup. Before continuing, review the [Web SDK setup](./web-sdk-setup) to ensure you've completed all steps.

The most common reasons web push appears to not be working are related to your browser and device's notification settings:

### Browser compatibility

Users may see [web permission prompts](/docs/en/permission-requests) but cannot subscribe to push notifications in incognito, private, or guest browser modes.

<Accordion title="Browser compatibility by operating system">
  | Browser                                                                          | Windows | macOS | Android | iOS |
  | -------------------------------------------------------------------------------- | ------- | ----- | ------- | --- |
  | [Chrome](https://en.wikipedia.org/wiki/Google_Chrome)                            | ✅       | ✅     | ✅       | ✅ ¹ |
  | [Firefox](https://en.wikipedia.org/wiki/Firefox)                                 | ✅       | ✅     | ✅       | ✅ ¹ |
  | [Safari 10+](https://en.wikipedia.org/wiki/Safari_\(web_browser\))               | ❌       | ✅     | ❌       | ✅ ¹ |
  | [Microsoft Edge](https://en.wikipedia.org/wiki/Microsoft_Edge)                   | ✅       | ✅     | ✅       | ✅ ¹ |
  | [Opera](https://en.wikipedia.org/wiki/Opera_\(web_browser\)) ²                   | ✅       | ✅     | ✅       | ✅ ¹ |
  | [Samsung Internet](https://en.wikipedia.org/wiki/Samsung_Internet_for_Android) ² | ❌       | ❌     | ✅       | ✅ ¹ |
  | [Yandex](https://en.wikipedia.org/wiki/Yandex_Browser) ²                         | ✅       | ✅     | ✅       | ✅ ¹ |
  | [UC Browser](https://en.wikipedia.org/wiki/UC_Browser) ²                         | ✅       | ❌     | ✅       | ✅ ¹ |
  | [Internet Explorer](https://en.wikipedia.org/wiki/Internet_Explorer)             | ❌       | ❌     | ❌       | ❌   |
  | [DuckDuckGo](https://en.wikipedia.org/wiki/DuckDuckGo)                           | ❌       | ❌     | ❌       | ❌   |

  <Info>
    ¹ iOS requires web app installation (see [iOS web push setup](/docs/en/web-push-for-ios))

    ² Chromium-based browsers appear as "Chrome" in OneSignal analytics
  </Info>
</Accordion>

### Device notification settings

Device Notification Settings are the **most common cause** of web push not appearing on a device. Check the following settings including Focus modes (Do Not Disturb, Low Battery, etc.) before looking elsewhere.

<Warning>
  Select the correct operating system from the tabs below. You should see Windows, macOS, Android, and iOS.
</Warning>

<Tabs>
  <Tab title="Windows">
    <Accordion title="Windows 10 Notification Settings">
      1. Select **Start > Settings > Notifications & Actions > Get notifications from apps and other senders**

      2. **Make sure your site and browser are also enabled.**

      <Frame>
        <img />
      </Frame>
    </Accordion>

    **Windows 11 Notification Settings:**

    1. Select **Start > Settings > System > Notifications**

    <Frame>
      <img />
    </Frame>

    2. Turn On **Notifications**

    3. Turn Off **Do not disturb** (while testing, push will show when this is disabled)

    4. Scroll down to **Notifications from apps and other senders**

    <Frame>
      <img alt="Windows 11 Settings showing the Notifications from apps and other senders list" />
    </Frame>

    5. Make sure your browsers are turned **On**.

    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="macOS">
    1. Navigate to **System Settings > Notifications**
    2. Make sure **Notifications** is enabled in Notification Center.

    <Info>
      You may need to select **Allow notifications when mirroring or sharing the display**.
    </Info>

    <Frame>
      <img />
    </Frame>

    3. Scroll down to **Application Notifications** list and make sure your browser is turned on.

    <Warning>
      Some browsers like Chrome and Edge show 2 different application entries.

      1. Standard web push notifications
      2. Internal alerts e.g Google calendar

      Make sure both are enabled.
    </Warning>

    <Frame>
      <img />
    </Frame>

    4. Select the Application and toggle on the settings. Select how you want notifications to be displayed.

    <Frame>
      <img />
    </Frame>

    <Warning>
      Some older versions of Safari may show the website in your Application Notifications list. Make sure to check the website is turned on in this case.
    </Warning>

    5. Navigate to **System Settings > Focus** and make sure no Focus modes are active while testing.

    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="Android">
    1. Navigate to **Settings > Notifications > your browser of choice**.
    2. Make sure **"Show notifications"** and your website are checked.

    <Frame>
      <img />
    </Frame>

    <Note>
      Android uses per-app notification channels. If your browser's notification channel is set to silent or turned off, push notifications won't appear even if the top-level toggle is on. In Settings, tap the browser entry and check that each notification channel is enabled and set to a visible alert style.
    </Note>
  </Tab>

  <Tab title="iOS">
    <Warning>
      iOS requires you to add your site to the Home Screen before subscribers can receive push notifications on iPhones and iPads. Complete the [iOS web push setup](/docs/en/web-push-for-ios) before troubleshooting.
    </Warning>

    1. Click the browser's **Share** button and select **Add to Home Screen**.
    2. Open your site from the Home Screen and allow notifications when the permission prompt appears.
    3. Go to device's **Settings > Notifications > your site** and make sure **Allow Notifications** is toggled on.
  </Tab>
</Tabs>

### Prompt display issues

The following are common reasons why the web push notification prompt may not display as expected.

<Steps>
  <Step title="Confirm a prompt is configured">
    Review your [Web permission prompt](/docs/en/permission-requests) setup to ensure you have configured a prompt and understand the different browser behaviors.

    For instance, some browsers like Safari require a user gesture (clicking a button) before the native prompt can appear. Details for each browser can be found in our [Web permission prompt > Native permission prompt](/docs/en/permission-requests#native-permission-prompt) section.
  </Step>

  <Step title="Check browser compatability, incognito, private browser, or guest browser modes.">
    Browsers do not allow users to subscribe to notifications in these modes. This is why the Slide Prompt may show but the native Permission Prompt will not display.

    Make sure you are [using a browser and device that supports web push](/docs/en/troubleshooting-web-push#browser-compatibility).
  </Step>

  <Step title="Check your browser's Notification Settings">
    Navigate to your browser's settings and check the "Notifications" permission setting. Chrome example: `chrome://settings/content/notifications`

    <Frame>
      <img />
    </Frame>

    In this example:

    * The user has selected "Don't allow sites to send notifications" which will prevent the native permission prompt from showing. This must show "Sites can ask to send notifications" to allow the native permission prompt to show.
    * The user has added `https://yoursite.com` to the "Not allowed to send notifications" list, which will prevent the native permission prompt from showing. This must be removed from the list to allow the native permission prompt to show.

    **Browser specific documentation:**

    * [Chrome](https://support.google.com/chrome/answer/3220216) - This page explains how to manage notifications in Chrome by going to Settings > Privacy and security > Site Settings > Notifications, where you can control default behavior and manage permissions for individual websites.
    * [Firefox](https://support.mozilla.org/en-US/kb/push-notifications-firefox) - This guide covers Firefox's Web Push notifications, explaining how to manage notification permissions through Settings > Privacy & Security > Notifications, and how to control permissions for specific sites through the address bar's site information icon.
    * [Safari](https://support.apple.com/guide/safari/customize-website-notifications-sfri40734/mac) - This Apple guide explains how to customize Safari notifications on Mac through Safari > Preferences > Websites > Notifications, where you can manage which sites can send notifications and control notification behavior through System Preferences.
    * [Edge](https://support.microsoft.com/en-us/microsoft-edge/manage-website-notifications-in-microsoft-edge-0c555609-5bf2-479d-a59d-fb30a0b80b2b) - This article details how to manage Edge notifications by navigating to Settings > Privacy, search, and services > Site permissions > Notifications, or by clicking the site information icon in the address bar.
  </Step>

  <Step title="iOS/iPadOS requirements are not met.">
    For iOS, there are some additional requirements to prompt users for their subscription. More information can be seen in the [Mobile Web Push for iOS/iPadOS](/docs/en/web-push-for-ios) guide.
  </Step>
</Steps>

***

## Troubleshooting steps

After checking the above, follow these steps to troubleshoot your OneSignal Web SDK setup.

<Steps>
  <Step title="Open the browser developer tools console">
    The browser's developer tools let you interact with the OneSignal Web SDK and enable logging to check for errors.

    <Tabs>
      <Tab title="Desktop">
        * **Chrome**: Right click on the page, click *Inspect*, and click the *Console* tab of the popup window that opens up.
        * **Firefox**: Right click on the page, click *Inspect element*, and click the *Console* tab of the popup window that opens up.
        * **Safari**: Go to **Safari → Preferences → Advanced** and make sure *Show Develop menu in menu bar* is checked. Then, on your webpage, right click, click *Inspect element*, and click the *Console* tab of the popup window that opens up.

        <Frame>
          <img alt="Browser developer tools console open on a webpage" />
        </Frame>
      </Tab>

      <Tab title="Android">
        * **Chrome on Android**: [Enable USB Debugging](https://developer.chrome.com/docs/devtools/remote-debugging/), connect your device into your computer and access the Dev Tools with `chrome://inspect#devices` in your Desktop Chrome browser.
        * **Firefox on Android**: [Enable USB Debugging](https://developer.mozilla.org/en-US/docs/Tools/about:debugging), connect your device into your computer and access the Dev Tools with `about:debugging` in your Desktop Firefox browser.
      </Tab>

      <Tab title="iOS">
        1. [Enable the web inspector on iOS](https://developer.apple.com/library/archive/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/GettingStarted/GettingStarted.html).
        2. Open the Safari browser on your mac and select **Develop > your device > your site**.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Enable web SDK logging">
    Run the following command in the developer tools Console:

    ```javascript theme={null}
    OneSignal.Debug.setLogLevel('trace');
    ```

    * You should see `undefined` as the result.
    * Close the tab and open a new one to the same page. Refreshing alone won't trigger all SDK initialization events.
    * You will start to see OneSignal SDK logs in the Console.

    <Frame>
      <img alt="Browser console showing OneSignal SDK trace-level log output" />
    </Frame>
  </Step>
</Steps>

### Configuration errors

You may encounter the following errors after OneSignal initializes:

<Danger>
  Error: SDK already initialized
</Danger>

<Frame>
  <img alt="Console error showing SDK already initialized message" />
</Frame>

**What this means:** The OneSignal Web SDK `init` code is being called more than once, often caused by combining WordPress plugin or Shopify integration setup with manual code or accidentally adding the OneSignal `init` code multiple times.

**How to fix:** Remove any duplicate `init` calls. If using the WordPress plugin or Shopify integration, remove any manual OneSignal code from your files.

<Danger>
  Error: Can only be used on: (URL Set in OneSignal Dashboard)
</Danger>

<Frame>
  <img alt="Console error showing site origin mismatch between dashboard URL and current page" />
</Frame>

**What this means:** The domain you are currently visiting doesn't match the site URL configured in your OneSignal dashboard.

**How to fix:** Copy the site URL in your browser and paste it into your OneSignal dashboard **Settings > Push & In-app > Web > Site URL** configuration. Make sure it is the site origin using the following format:

* **Protocol:** Must be `https://` (for local testing, see [Localhost configuration](./web-sdk-setup#local-testing))
* **Domain:** `example.com` vs `www.example.com`
* **Subdomain:** `app.example.com` vs `example.com`

All three components must match between your actual site URL and your dashboard configuration.

<Danger>
  Error: OneSignalSDK: The "My site is not fully HTTPS" option is no longer supported starting with version 16 (User Model) of the OneSignal SDK.
</Danger>

<Frame>
  <img alt="Console error showing HTTP site not supported in SDK v16" />
</Frame>

**What this means:** Your OneSignal dashboard is configured to use an HTTP site and you likely updated to use HTTPS.

Users who subscribed while using HTTP or the "My site is not fully HTTPS" option are actually subscribed to a subdomain in the format `https://your-label.os.tc`, not your actual site origin. Web push is not supported on HTTP sites or websites that cannot host service workers.

**How to fix:** Both options require your users to resubscribe because they are subscribed to the `os.tc` subdomain, not your site.

1. **Create a new OneSignal App** and set the new App ID in your init code. This lets you continue sending push from the old app to notify users.

   Send notifications letting users know the site has been updated and they should resubscribe. Offering a discount or incentive helps. Set the "Launch URL" to a landing page with a resubscription prompt (Bell, Custom Link, or Category Slide). See [Permission prompts](./permission-requests) for details.

2. **Keep the same App ID** by using the [Update an App](/reference/update-an-app) API to update `chrome_web_origin` and `safari_site_origin` to your HTTPS origin.

   Because users subscribed to the `os.tc` subdomain, their browser does not have push permissions for your actual domain. They will be prompted again, and if they resubscribe, they will have two web push Subscriptions on the same browser — causing duplicate notifications.

   To prevent duplicates, [delete all current web push subscribers](./delete-users) before updating. Send a few notifications first letting users know they should resubscribe. See [Permission prompts](./permission-requests) for prompt options.

### Service worker installation errors

If you are presented with the [Native permission prompt](./permission-requests) and click "Allow", you may encounter the following service worker installation errors:

<Danger>
  Y: Registration of a Service Worker failed.
</Danger>

<Danger>
  \[Service Worker Installation] Installing service worker failed TypeError: Failed to register a ServiceWorker for scope ('`https://your-site.com/`') with script ('`https://your-site.com/...`'): A bad HTTP response code (404) was received when fetching the script.
</Danger>

<Danger>
  \[Service Worker Installation] Installing service worker failed TypeError: Failed to register a ServiceWorker for scope ('`https://www.yoursite.com/`') with script ('`https://www.yoursite.com/...`'): A bad HTTP response code (403) was received when fetching the script.
</Danger>

<Frame>
  <img alt="Console error showing service worker registration failure with 404 or 403 response" />
</Frame>

<Danger>
  The script has an unsupported MIME type ('current MIME type').
  \[Service Worker Installation] Installing service worker failed SecurityError: Failed to register a ServiceWorker for scope ('[https://your-site.com/](https://your-site.com/)') with script ('[https://your-site.com/](https://your-site.com/)...'): The script has an unsupported MIME type ('current MIME type').
</Danger>

<Frame>
  <img alt="Console error showing unsupported MIME type for service worker script" />
</Frame>

<Danger>
  \[Service Worker Installation] Installing service worker failed SecurityError: Failed to register a ServiceWorker for scope ('[https://your-site.com/](https://your-site.com/)') with script ('[https://your-site.com/](https://your-site.com/)...'): The script resource is behind a redirect, which is disallowed.
</Danger>

<Frame>
  <img alt="Console error showing service worker script blocked by a redirect" />
</Frame>

**What this means:** Your service worker file is configured incorrectly.

**How to fix:**

<Steps>
  <Step title="Find your service worker path">
    The SDK looks for the `OneSignalSDKWorker.js` service worker file in the root directory of your site unless you specify a custom filename or location as described in the [Service Worker setup guide](./onesignal-service-worker).

    Make sure you have configured the correct filename, location, and scope for the SDK to find the service worker file.
  </Step>

  <Step title="Visit the service worker file directly in your browser">
    Based on your configuration, open the file directly in your browser.

    * If you did not configure a custom location, then you should see the JavaScript code for the service worker file in your site's root: `https://yoursite.com/OneSignalSDKWorker.js`
    * If using WordPress, you should see it here: `https://yoursite.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js`
    * If using a custom location, you should see it here: `https://yoursite.com/your-custom-location/OneSignalSDKWorker.js`

    <Warning>
      File names are case-sensitive. Make sure you use `OneSignalSDKWorker.js` or the filename you configured.

      Some servers will automatically lowercase the filename. Take this into consideration if you cannot find the file.
    </Warning>
  </Step>

  <Step title="Verify the file loads">
    * You should see the following JavaScript code:
      ```javascript JavaScript theme={null}
      importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
      ```
    * This file must be served with a `content-type` of `application/javascript`.
    * There can be no redirects to this file. Files must be hosted on the same domain as your site (no CDN or proxy domains).
  </Step>
</Steps>

<Note>
  See the [Service Worker setup guide](./onesignal-service-worker) for more detailed setup instructions.
</Note>

### Notifications not shown

This section assumes:

1. You have reviewed the [Notifications not shown: Web Push](./notifications-not-shown-web-push) guide for common reasons why notifications may not be showing up on your device.
2. You were shown the [Native permission prompt](./permission-requests) and clicked "Allow". See [Prompt display issues](#prompt-display-issues) above if you did not subscribe via the Native permission prompt.

If the above are true, follow these steps to check your Subscription ID and send yourself a push notification:

<Steps>
  <Step title="Get your Subscription ID">
    Run the following code in the browser developer tools console:

    ```javascript JavaScript theme={null}
    function getUserInfo() {
      console.log('getUserInfo()');
      Promise.all([
        OneSignal.Notifications.isPushSupported(),
        OneSignal.Notifications.permission,
        OneSignal.User.PushSubscription.optedIn,
        OneSignal.User.PushSubscription.id
      ]).then(([
        isPushSupported,
        isSubscribed,
        isOptedIn,
        subscriptionId
      ]) => {
        console.log('The current URL of this page: ', location.href);
        console.log('Push is supported on this browser: ', isPushSupported);
        console.log('You are subscribed to notifications in the browser: ', isSubscribed);
        console.log('You are opted-in with OneSignal: ' , isOptedIn);
        console.log('Your OneSignal Subscription ID: ', subscriptionId);
      }).catch(e => {
        console.error('Error getting user info:', e);
      });
    }
    getUserInfo();
    ```

    This will tell you:

    * The URL of the page you are on if there is any confusion.
    * If the current browser supports push notifications.
      * `true` means the browser supports push notifications.
      * `false` means the browser does not support push notifications.
    * If you are subscribed to notifications in the browser.
      * `true` means you allowed push permissions for this URL.
      * `false` means you did not allow or denied push permissions for this URL.
    * If you are opted-in with OneSignal.
      * `true` means your Subscription is subscribed to push notifications in OneSignal.
      * `false` means your Subscription is not subscribed to push notifications in OneSignal. Check if the [`optOut()` method](./web-sdk-reference) is being called on your site.
    * Your OneSignal Subscription ID.

      * Save this for the next step. This is the ID you will use to send yourself a push notification.

      <Frame>
        <img alt="Console output showing push support status, subscription state, and Subscription ID" />
      </Frame>

      <Warning>
        Save this console data to a text file and share with OneSignal Support if you need further assistance.
      </Warning>
  </Step>

  <Step title="Send yourself a notification">
    If you are subscribed to notifications, opted-in with OneSignal, and have a Subscription ID, you can send yourself a notification.

    Follow the steps in [Test Users](./test-users) to set yourself as a tester and send yourself a notification.
  </Step>

  <Step title="Test with Chrome">
    If you are not getting notifications in Chrome, use these Chrome-specific diagnostic tools to identify the issue.

    1. In a new tab, open `chrome://gcm-internals`.
    2. Click the "Start Recording" button on the top left. Making sure you see "Connection State: CONNECTED".
    3. Leave this open and send yourself another push notification to your Chrome web push Subscription.
    4. You should see something in the "Receive Message Log" if you got it.

    <Frame>
      <img alt="Chrome GCM internals page showing Receive Message Log with a received data message" />
    </Frame>

    * If you don't see a "Data msg received", then your Chrome browser is not receiving the notification at all. Contact OneSignal Support with the GCM internals logs.
    * If you see "Data msg received" but you still didn't receive a notification, continue to the next step.

    5. Open a new tab to `chrome://serviceworker-internals`
    6. Search for `Scope: https://your-site.com` (replace `your-site.com` with your actual site domain).
    7. Click **Inspect**, or **Start -> Inspect**. A Chrome Developer Tools popup will appear.

    <Frame>
      <img alt="Chrome service worker internals page showing the Inspect button for a registered service worker" />
    </Frame>

    8. On the Chrome Developer Tools popup to our service worker, click the **Console** tab, and run `OneSignalWorker.log.trace();`. It should return `undefined`. Any messages from our service worker should now appear in this popup.
  </Step>
</Steps>

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***

## FAQ

### Why do I see "SDK already initialized"?

The OneSignal Web SDK `init` code is being called more than once on the page. This commonly happens when combining the WordPress plugin with manual code, or when the init tag is included in multiple page templates. Remove duplicate `init` calls to resolve it.

### Can I use web push on HTTP sites?

No. Web push requires HTTPS because service workers — which handle push delivery — only work on secure origins. If you previously used the "My site is not fully HTTPS" option, you must migrate to HTTPS. See [Configuration errors](#configuration-errors) for migration steps.

### How do I test web push on localhost?

You can test on `localhost` during development. See [Localhost configuration](./web-sdk-setup#local-testing) for setup instructions. Note that `localhost` testing only works in Chromium-based browsers.

***

## Related pages

<Columns>
  <Card title="Web SDK setup" icon="globe" href="./web-sdk-setup">
    Complete the initial OneSignal Web SDK installation and configuration.
  </Card>

  <Card title="Service worker setup" icon="gear" href="./onesignal-service-worker">
    Configure the OneSignal service worker file for your site.
  </Card>

  <Card title="Permission prompts" icon="bell" href="./permission-requests">
    Configure how and when to prompt visitors for web push permission.
  </Card>

  <Card title="Notifications not shown" icon="eye-slash" href="./notifications-not-shown-web-push">
    Common reasons why web push notifications may not appear on your device.
  </Card>
</Columns>


# Tutorials & use cases
Source: https://documentation.onesignal.com/docs/en/tutorials

Explore step-by-step tutorials and best-practice examples to help you implement OneSignal features and boost engagement, retention, and revenue.

Now that OneSignal is set up in your app, pick a use case to build. Each tutorial below is a working example you can adapt, grounded in the core concepts shared across every section.

<Note>
  New to OneSignal? Complete the [Quickstart guide](./quickstart-guide) first to install the SDK and send your first message, then come back here to pick your use cases.
</Note>

## Core concepts

Every tutorial on this page builds on these foundations. Skim them once and you'll recognize the same patterns everywhere else.

<Columns>
  <Card title="Users and External IDs" icon="user" href="./users">
    Learn how OneSignal identifies users and links them across devices using External IDs.
  </Card>

  <Card title="Segments" icon="users" href="./segmentation">
    Build audience segments using tag filters and other conditions.
  </Card>

  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Add custom properties to users for personalization and segmentation.
  </Card>

  <Card title="Custom events" icon="calendar-check" href="./custom-events">
    Capture user actions and trigger automated Journeys or Wait Until steps.
  </Card>

  <Card title="Journeys" icon="route" href="./journeys-overview">
    Build automated messaging workflows triggered by user behavior and data.
  </Card>

  <Card title="Personalization" icon="user-check" href="./message-personalization">
    Use user data and preferences to personalize every message.
  </Card>
</Columns>

## Industry strategies

Jump to the playbook for your industry, or browse use cases by lifecycle stage below. Many strategies apply across industries.

<Columns>
  <Card title="Mobile" icon="mobile" href="./mobile-first">
    Basic onboarding, retention, trial-to-paid conversion, and win-back strategies for mobile apps.
  </Card>

  <Card title="Gaming" icon="gamepad" href="./gaming-industry">
    Establish streaks and regular use early. Reward highly-engaged players and re-engage lapsed players.
  </Card>

  <Card title="Ecommerce" icon="shopping-cart" href="./ecommerce-strategies">
    Abandoned cart recovery and loyalty programs.
  </Card>

  <Card title="News and media" icon="newspaper" href="./news-and-media-industry">
    Get readers to complete their profile and pick categories to send them messages they care about.
  </Card>

  <Card title="Financial and fintech" icon="credit-card" href="./financial-fintech-industry">
    Push for that critical early-win like making a deposit or transaction and 2FA confirmation.
  </Card>
</Columns>

## Onboard new users

Set your messaging foundation, collect more opt-ins, and capture meaningful user data in the first session.

<Columns>
  <Card title="Basic welcome journeys" icon="seedling" href="./mobile-first-journeys#welcome-journeys">
    Set up a Welcome Journey for your app.
  </Card>

  <Card title="Gaming: Welcome Journey" icon="medal" href="./welcome-journey-mobile-gaming">
    Drive new players to their first meaningful in-game action with an automated onboarding flow.
  </Card>

  <Card title="Push permission prompts" icon="bell" href="./prompt-for-push-permissions">
    Ask for permission the right way so more users opt in to push.
  </Card>

  <Card title="Category onboarding" icon="list-check" href="./welcome-journey-news-media">
    Have readers pick topics so every message is one they want.
  </Card>
</Columns>

## Engage and convert

Trigger the right message at the right moment to move users toward an action.

<Columns>
  <Card title="Event-driven Journeys" icon="bolt" href="./event-driven-journeys">
    Trigger Journeys with user actions and events.
  </Card>

  <Card title="Abandoned cart" icon="cart-plus" href="./abandoned-cart">
    Recover lost revenue with event-triggered abandoned cart reminders.
  </Card>

  <Card title="Loyalty Journey" icon="trophy" href="./loyalty-journey">
    Notify customers of points balances and unlocked rewards to drive repeat purchases.
  </Card>

  <Card title="Flash sales and Black Friday" icon="bullhorn" href="./flash-sale">
    Drive urgency with time-limited sale campaigns.
  </Card>

  <Card title="Back-in-stock alerts" icon="boxes-stacked" href="./back-in-stock-alerts">
    Notify users when products are back in stock.
  </Card>
</Columns>

## Retain and re-engage

Keep users coming back, recover lapsed users, and earn long-term loyalty.

<Columns>
  <Card title="Daily streaks" icon="fire" href="./daily-streak">
    Reward consistency with daily streak reminders that keep users coming back.
  </Card>

  <Card title="Increase App Store reviews" icon="stars" href="./example-app-store-review">
    Prompt satisfied users for App Store reviews while reducing friction.
  </Card>

  <Card title="Target outdated app versions" icon="circle-up" href="./app-version-update">
    Prompt users on outdated versions to update via in-app messages.
  </Card>

  <Card title="Push fallback to email or SMS" icon="arrows-rotate" href="./push-fallback-method">
    Ensure critical messages are delivered even when push is disabled.
  </Card>
</Columns>

## Operational

Always-on infrastructure that runs alongside your campaigns.

<Columns>
  <Card title="Transactional messages" icon="paper-plane" href="./transactional-messages">
    Send important real-time updates such as receipts, confirmations, or alerts.
  </Card>

  <Card title="Booking confirmations" icon="ticket" href="./booking-confirmations">
    Send booking confirmations and recovery emails triggered by real-time booking status.
  </Card>

  <Card title="Magic link and OTP verification" icon="key" href="./example-verification-magic-link-otp">
    Send one-time passwords, magic links, and verification emails for sign-in and authentication.
  </Card>

  <Card title="Email confirmed opt-in" icon="envelope" href="./double-opt-in-email">
    Reduce bounces and improve deliverability with a double opt-in flow.
  </Card>

  <Card title="Preference center" icon="gear" href="./preference-center">
    Let users manage their messaging preferences and communication channels.
  </Card>
</Columns>

***


# Unity SDK setup
Source: https://documentation.onesignal.com/docs/en/unity-sdk-setup

Learn how to set up OneSignal's Unity SDK to easily add push notifications to your Unity apps for iOS, Android, Amazon, and Huawei. This guide covers Unity installation, platform configuration, and initialization.

<SdkReleasesIframe />

## Overview

## Setting up push notifications for your Unity app using OneSignal

Integrating push notifications into your Unity app is a powerful way to boost user engagement and retention. OneSignal's Unity SDK supports iOS (APNS), Android (FCM), Amazon (ADM), and Huawei devices, enabling real-time messaging with minimal effort.

Whether you're building mobile games or interactive apps, this guide helps you integrate OneSignal quickly and reliably.

***

## Requirements

* Unity 2022.3 or newer
* Configured OneSignal app and platform

**iOS Requirements**

* macOS with Xcode 14+ (setup instructions use Xcode 16.2)
* Device with iOS 12+, iPadOS 12+, or Xcode simulator running iOS 16.2+

**Android Requirements**

* Android 7.0+ device or emulator with Google Play Store (Services) installed

### Configure your OneSignal app and platform

Configure your OneSignal app with the platforms you support — Apple (APNs), Google (FCM), Huawei (HMS), and/or Amazon (ADM).

<Note>
  If your organization already has a OneSignal account, [ask to be invited](/docs/en/manage-team-members) to the Organization. Otherwise, [sign up for a free account](https://onesignal.com) to get started.
</Note>

<Accordion title="Step-by-step setup instructions" icon="circle-chevron-down">
  <Steps>
    <Step title="Create or select your app">
      Create a new app by clicking **New App/Website**, or add a platform to an existing app in **Settings > Push & In-App**. Select the platform(s) you want to configure and click **Next: Configure Your Platform**.

      <Frame>
        <img alt="OneSignal dashboard showing the new app setup flow with Organization name, app name, and channel selection" />
      </Frame>
    </Step>

    <Step title="Configure platform credentials">
      Enter the credentials for your platform:

      * **Android**: [Set up Firebase credentials](/docs/en/android-firebase-credentials)
      * **iOS**: [p8 token (recommended)](/docs/en/ios-p8-token-based-connection-to-apns) or [p12 certificate](/docs/en/ios-p12-generate-certificates)
      * **Amazon**: [Generate API key](/docs/en/generate-an-amazon-api-key)
      * **Huawei**: [Authorize OneSignal](/docs/en/authorize-onesignal-to-send-huawei-push)

      Click **Save & Continue** after entering your credentials.
    </Step>

    <Step title="Save your App ID and install the SDK">
      Your **App ID** is displayed on the final screen. Copy and save it — you need it when initializing the SDK. Select your SDK platform, then follow the setup guide.

      <Frame>
        <img alt="OneSignal dashboard showing the App ID and team invite option after setup" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

***

## Setup

### 1. Add the OneSignal Unity SDK

Two installation methods are available:

<Tabs>
  <Tab title="Unity Asset Store">
    1. [Add the SDK to your account](https://assetstore.unity.com/packages/add-ons/services/billing/onesignal-sdk-193316) via **Add to My Assets**.
    2. Click **Open in Unity** to launch Unity Editor and Package Manager.
    3. Download and **Import** the SDK.

    <Frame>
      <img />
    </Frame>

    4. Accept the prompt to import all files.
    5. Go to **Window > OneSignal SDK Setup** and follow the checklist, especially **Import OneSignal packages**.
    6. After import, Unity will update the registry. Complete the remaining setup steps shown in the setup window.

    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="Unity Package Manager">
    1. Navigate to **Edit > Project Settings > Package Manager**.

    <Frame>
      <img />
    </Frame>

    2. Add a scoped registry:

    ```
    Name        npmjs
    URL         https://registry.npmjs.org
    Scope(s)    com.onesignal
    ```

    3. Open **Window > Package Manager** and switch to **My Registries**.
    4. Install the desired OneSignal SDK packages.
    5. Open **Window > OneSignal SDK Setup** and complete the final steps.

    <Frame>
      <img />
    </Frame>
  </Tab>
</Tabs>

### 2. Platform setup

Add all the platforms your app supports.

#### iOS setup

Our SDK auto-configures the required Xcode settings. Choose your provisioning approach:

<Tabs>
  <Tab title="Automatically Sign (Recommended)">
    1. Go to **File > Build Settings** > **Player Settings**.
    2. Under **Other Settings**, check **Automatically Sign**.

    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="Manual Provisioning">
    Make sure your Apple Developer account has:

    * An App Group: `group.{your_bundle_id}.onesignal`
    * Enabled **Push Notifications** and **App Groups**
    * Refreshed provisioning profiles for your bundle ID
  </Tab>
</Tabs>

#### Android setup

1. Go to **Edit > Project Settings > Player** > **Android**.
2. Under **Publishing Settings**, enable:

* **Custom Main Gradle Template**
* **Custom Gradle Properties Template**

3. Run **Assets > External Dependency Manager > Android Resolver > Force Resolve**.

Additional considerations:

* **Target API Level must be 33+** (v5.0.6+).
* If **Minify is enabled**, run **Copy Android plugin to Assets** from **OneSignal SDK Setup** to use `OneSignalConfig.androidlib`.
* Replace the default icons within `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res` with your own (lowercase file names only, underscores allowed). See [Customize Notification Icons](./notification-icons) for more.

#### Amazon setup

<Note>
  Only required for Amazon apps available via the Amazon App Store.
</Note>

<Accordion title="Amazon FireOS (ADM) setup" icon="circle-chevron-down">
  1. Edit or create `Plugins/Android/AndroidManifest.xml`.
  2. Add namespace:

  ```xml theme={null}
   xmlns:amazon="http://schemas.amazon.com/apk/res/android"
  ```

  3. Add permissions:

  ```xml theme={null}
  <uses-permission android:name="com.amazon.device.messaging.permission.RECEIVE" />
  <permission android:name="COM.YOUR.PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE" android:protectionLevel="signature" />
  <uses-permission android:name="COM.YOUR.PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE" />
  ```

  4. Add the following to the `<application>` tag:

  ```xml theme={null}
  <amazon:enable-feature android:name="com.amazon.device.messaging" android:required="false"/>
  <service android:name="com.onesignal.notifications.services.ADMMessageHandler" android:exported="false" />
  <service android:name="com.onesignal.notifications.services.ADMMessageHandlerJob"
           android:permission="android.permission.BIND_JOB_SERVICE"
           android:exported="false" />
  <receiver android:name="com.onesignal.notifications.receivers.ADMMessageReceiver"
            android:permission="com.amazon.device.messaging.permission.SEND" >
    <intent-filter>
      <action android:name="com.amazon.device.messaging.intent.REGISTRATION" />
      <action android:name="com.amazon.device.messaging.intent.RECEIVE" />
      <category android:name="COM.YOUR.PACKAGE_NAME" />
    </intent-filter>
  </receiver>
  ```

  5. Replace all `COM.YOUR.PACKAGE_NAME` instances with your actual package name.

  6. Place your `api_key.txt` under `Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/assets`

  * See [Generate an Amazon API Key Guide](./generate-an-amazon-api-key) for help creating this file.
</Accordion>

#### Huawei setup

<Note>
  Only required for Huawei apps available via the Huawei App Gallery.

  See [Huawei Unity SDK setup](./huawei-unity-sdk-setup) for more.
</Note>

### 3. Initialize the SDK

Add this code inside the `Start()` method of a `MonoBehaviour` early in your application's lifecycle.

Replace `YOUR_APP_ID` with your OneSignal App ID found in your OneSignal dashboard **Settings > [Keys & IDs](./keys-and-ids)**.

<Note>
  If you don't have access to the OneSignal app, ask your [Team Members](./manage-team-members) to invite you.
</Note>

```csharp C# theme={null}
using OneSignalSDK;

void Start () {
  // Enable verbose logging for debugging (remove in production)
  OneSignal.Debug.LogLevel = LogLevel.Verbose;
  // Initialize with your OneSignal App ID
  OneSignal.Initialize("YOUR_APP_ID");
  // Use this method to prompt for push notifications.
  // We recommend removing this method after testing and instead use In-App Messages to prompt for notification permission.
  await OneSignal.Notifications.RequestPermissionAsync(true);
}
```

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications, subscription registration, and in-app messaging.

<Warning>
  If you are testing with an Android emulator, it should start with a cold boot.

  1. Go to **Device Manager** in Android Studio.
  2. Select your emulator device and click **Edit**.
  3. Go to **Additional Settings** or **More**.
  4. Set the **Boot option** to **Cold Boot**.
  5. Save changes and restart the emulator.
</Warning>

### Check mobile subscriptions

<Steps>
  <Step title="Launch your app on a test device.">
    The native push permission prompt should appear automatically if you added the `requestPermission` method during initialization.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    Before accepting the prompt, check the OneSignal dashboard:

    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status "Never Subscribed".

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Return to the app and tap Allow on the prompt." />

  <Step title="Refresh the OneSignal dashboard Subscription's page.">
    The subscription's status should now show **Subscribed**.

    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a [mobile subscription](/docs/en/subscriptions).
    Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img />
    </Frame>

    <Check>You have successfully created a segment of test users.
    We can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment we created earlier.

    ```curl theme={null}
    curl -X \
    POST --url 'https://api.onesignal.com/notifications' \
     --header 'content-type: application/json; charset=utf-8' \
     --header 'authorization: Key YOUR_APP_API_KEY' \
     --data \
     '{
      "app_id": "YOUR_APP_ID",
      "target_channel": "push",
      "name": "Testing basic setup",
      "headings": {
      	"en": "👋"
      },
      "contents": {
        "en": "Hello world!"
      },
      "included_segments": [
        "Test Users"
      ],
      "ios_attachments": {
        "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      },
      "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
    }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification with an image included:

    <Frame>
      <img />
    </Frame>

    <Info>Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Info>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats.

    You should see the **confirmed** stat, meaning the device received the push.
    <Check>You have successfully sent a notification via our API to a segment.</Check>

    <Warning>
      * No image received? Your [Notification Service Extension](#ios-setup) might be missing.
      * No confirmed receipt? Review the troubleshooting guide [here](/docs/en/confirmed-delivery#troubleshooting-confirmed-delivery).
      * Having issues? Copy-paste the api request and a log from start to finish of app launch into a `.txt` file. Then share both with `support@onesignal.com`.
    </Warning>
  </Step>
</Steps>

### Send an in-app message

[In-app messages](/docs/en/in-app-messages-setup) let you communicate with users while they are using your app.

<Steps>
  <Step title="Close or background your app on the device.">
    This is because users must meet the in-app audience criteria *before* a new session starts. In OneSignal, a new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds. For more details, see our guide on [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
  </Step>

  <Step title="Create an in-app message.">
    * In your OneSignal dashboard, navigate to **Messages > In-App > New In-App**.
    * Find and select the **Welcome** message.
    * Set your Audience as the **Test Users** segment we used previously.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Customize the message content if desired.">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Set Trigger to 'On app open'." />

  <Step title="Schedule frequency.">
    Under **Schedule > How often do you want to show this message?** select **Every time trigger conditions are satisfied**.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Make message live.">
    Click **Make Message Live** so it is available to your Test Users each time they open the app.
  </Step>

  <Step title="Open the app and see the message.">
    After the in-app message is live, open your app. You should see it display:

    <Frame>
      <img />
    </Frame>

    <Warning>
      Not seeing the message?

      * Start a new session
        * You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
        * For more, see [how in-app messages are displayed](/docs/en/in-app-messages-setup#how-are-iams-displayed%3F).
      * Still in the `Test Users` segment?
        * If you reinstalled or switched devices, re-add the device to [Test Users](#set-up-test-users) and confirm it's part of the Test Users segment.
      * Having issues?
        * Follow [Getting a Debug Log](/docs/en/capturing-a-debug-log) while reproducing the steps above. This will generate additional logging that you can share with `support@onesignal.com` and we will help investigate what's going on.
    </Warning>
  </Step>
</Steps>

<Check>
  You have successfully setup the OneSignal SDK and learned important concepts like:

  * Gathering [Subscriptions](/docs/en/subscriptions), setting [Test Users](/docs/en/find-set-test-subscriptions), and creating [Segments](/docs/en/segmentation).
  * Sending [Push](/docs/en/push) with images and [Confirmed receipt](/docs/en/confirmed-delivery) using Segments and our [Create message](/reference/create-message) API.
  * Sending [In-app messages](/docs/en/in-app-messages-setup).

  Continue with this guide to identify users in your app and setup additional features.
</Check>

***

## User identification

Previously, we demonstrated how to create mobile [Subscriptions](/docs/en/subscriptions). Now we'll expand to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We'll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with our SDK's [`login` method](/docs/en/mobile-sdk-reference#login-external-id) each time they are identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with our SDK [`addTag` and `addTags` methods](/docs/en/mobile-sdk-reference#data-tags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img />
</Frame>

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

<br />

<Frame>
  <img />
</Frame>

### Add email and/or SMS subscriptions

Earlier we saw how our SDK creates mobile subscriptions to send push and in-app messages. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/mobile-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/mobile-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/mobile-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/mobile-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

See our Privacy & security docs for more on:

* [Data collected by the SDK](/docs/en/data-collected-by-the-onesignal-sdk)
* [Handling personal data](/docs/en/handling-personal-data)

***

## Prompt for push permissions

Instead of calling `requestPermission()` immediately on app open, take a more strategic approach. Use an in-app message to explain the value of push notifications before requesting permission.

For best practices and implementation details, see our [Prompt for push permissions](/docs/en/prompt-for-push-permissions) guide.

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners for you to hook into. See our [SDK reference guide](/docs/en/mobile-sdk-reference) for more details.

### Push notification events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-push): Detect when a notification is tapped. Helpful for [Deep Linking](/docs/en/deep-linking).
* [`addForegroundLifecycleListener()`](/docs/en/mobile-sdk-reference#addforegroundlifecyclelistener-push): Control how notifications behave in foreground.

For full customization, see [Mobile Service Extensions](/docs/en/service-extensions).

### User state changes

* [`addObserver()` for user state](/docs/en/mobile-sdk-reference#addobserver-user-state): Detect when the External ID is set.
* [`addPermissionObserver()`](/docs/en/mobile-sdk-reference#addpermissionobserver-push): Track the user's specific interaction with the native push permission prompt.
* [`addObserver()` for push subscription](/docs/en/mobile-sdk-reference#addobserver-push-subscription-changes): Track when the push subscription status changes.

### In-app message events

* [`addClickListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Handle in-app click actions. Ideal for deep linking or tracking events.
* [`addLifecycleListener()`](/docs/en/mobile-sdk-reference#addclicklistener-in-app): Track full lifecycle of in-app messages (shown, clicked, dismissed, etc.).

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

* [🔁 Migrating to OneSignal from another service](/docs/en/migrating-to-onesignal)
* [🌍 Location tracking](/docs/en/mobile-sdk-reference#location)
* [🔗 Deep Linking](/docs/en/deep-linking)
* [🔌 Integrations](/docs/en/integrations)
* [🧩 Mobile Service Extensions](/docs/en/service-extensions)
* [🛎️ Action buttons](/docs/en/action-buttons)
* [🌐 Multi-language messaging](/docs/en/multi-language-messaging)
* [🛡️ Identity Verification](/docs/en/identity-verification)
* [📊 Custom Outcomes](/docs/en/custom-outcomes)
* [📲 Live Activities](/docs/en/live-activities)

### Mobile SDK setup & reference

Make sure you've enabled all key features by reviewing the [Mobile push setup](/docs/en/mobile-push-setup) guide.

For full details on available methods and configuration options, visit the [Mobile SDK reference](/docs/en/mobile-sdk-reference).

<Check>Congratulations! You've successfully completed the Mobile SDK setup guide.</Check>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Vue JS Web SDK setup
Source: https://documentation.onesignal.com/docs/en/vue-js-setup

Integrate OneSignal Web Push Notifications into your Vue.js application using either the onesignal-vue or @onesignal/onesignal-vue3 plugin. Learn how to install, configure, and customize service workers for seamless push delivery.

<SdkReleasesIframe />

## Overview

This guide explains how to integrate OneSignal push notifications into a Vue.js application. It covers both Vue 2 and Vue 3 using the official OneSignal Vue plugins, along with key setup considerations including service worker configuration and TypeScript support.

***

## Requirements

* Configured OneSignal app and platform. See [Web Push Setup](./web-push-setup) to get started.

### Vue Compatibility

Make sure you install a plugin version compatible with your Vue environment.

| Vue | OneSignal Plugin                                              |
| --- | ------------------------------------------------------------- |
| 2   | [onesignal-vue](https://github.com/OneSignal/onesignal-vue)   |
| 3   | [onesignal-vue3](https://github.com/OneSignal/onesignal-vue3) |

***

## Installation

Install via your preferred package manager:

<CodeGroup>
  ```bash yarn theme={null}
  yarn add onesignal-vue
  # or yarn add @onesignal/onesignal-vue3
  ```

  ```bash npm theme={null}
  npm install --save onesignal-vue
  # or npm install --save @onesignal/onesignal-vue3
  ```
</CodeGroup>

***

## Initialization

Import the OneSignal service and initialize it in your root component. The `init` function returns a promise that resolves when OneSignal is loaded.

Replace `YOUR_APP_ID` with your OneSignal app ID found in [Keys & IDs](./keys-and-ids).

<CodeGroup>
  ```javascript Vue2 theme={null}
  import Vue from 'vue'
  import OneSignalVue from 'onesignal-vue'

  Vue.use(OneSignalVue);

  new Vue({
    render: h => h(App),
    beforeMount() {
      this.$OneSignal.init({ appId: 'YOUR_APP_ID' });
    }
  }).$mount('#app')
  //Example 1
  await this.$OneSignal.init({ appId: 'YOUR_APP_ID' });
  // do other stuff

  //Example 2
  this.$OneSignal.init({ appId: 'YOUR_APP_ID' }).then(() => {
    // do other stuff
  });
  ```

  ```javascript Vue3 theme={null}
  /*
  In Vue 3, you can pass in the OneSignal initialization options directly as an argument to the `use` function. You can still initialize separately if you prefer editor benefits like code completion.
  */
  import { createApp } from 'vue'
  import OneSignalVuePlugin from '@onesignal/onesignal-vue3'

  createApp(App).use(OneSignalVuePlugin, {
    appId: 'YOUR_APP_ID',
  }).mount('#app');

  // OR

  import { createApp } from 'vue'
  import OneSignalVuePlugin from '@onesignal/onesignal-vue3'

  createApp(App).use(OneSignalVuePlugin).mount('#app');

  // component
  this.$OneSignal.init({
    appId: "YOUR_APP_ID"
  });
  ```
</CodeGroup>

The OneSignal plugin automatically exposes a `$OneSignal` global property accessible inside the application.

### Composition API

You can also leverage Vue's [Composition API](https://vuejs.org/guide/extras/composition-api-faq.html) via the `useOneSignal()` hook that can be called from within [`setup`](https://vuejs.org/api/composition-api-setup.html#basic-usage).

### Customizing init options

You can customize your initialization with additional [`init` parameters](./web-sdk-reference#init).

### Service Worker Settings

If you haven't done so already, you will need to [download the OneSignal Service Worker file](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip) to add to your site.

The `OneSignalSDKWorker.js` file must be publicly accessible. You can put it in your `public` directory, top-level root, or a subdirectory. However, if you are placing the file in a subdirectory and/or have another service worker for your site, then make sure to specify the path. See [OneSignal Service Worker](./onesignal-service-worker) for details.

| Option               | Description                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `serviceWorkerParam` | Scope controlled by the OneSignal worker. **Recommendation:** Use a custom sub-path (e.g., `"/onesignal/"`).                |
| `serviceWorkerPath`  | Path to your hosted OneSignal service worker file (e.g., `"onesignal/OneSignalSDKWorker.js"`). Must be publicly accessible. |

**Example:**

```javascript theme={null}
this.$OneSignal.init({
  appId: 'YOUR-ONESIGNAL-APP-ID',
  serviceWorkerParam: {
    scope: '/onesignal/'
  },
  serviceWorkerPath: 'onesignal/OneSignalSDKWorker.js'
});
```

#### Hosting the worker

* Public root (default): `/OneSignalSDKWorker.js`
* Custom folder (recommended): e.g., `/onesignal/OneSignalSDKWorker.js` as set in the previous step.

#### Verify service worker hosting

Visit the path in your browser to confirm it's accessible.

If you used root:

```
https://your-site.com/OneSignalSDKWorker.js
```

If using the example path:

```
https://your-site.com/onesignal/OneSignalSDKWorker.js
```

It should return valid JavaScript.

### Important notes

* Avoid Duplicate Initialization in Development
  * When testing in a development environment, you might see the OneSignal SDK initialize twice, which can cause console errors.
  * This happens due to `<React.StrictMode>` causing effects to run twice in development. To resolve it, remove `<React.StrictMode>` from your root component during development.

<Warning>
  Strict mode only affects development—it does not impact production builds.
</Warning>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications and subscription registration.

### Check web push subscriptions

<Steps>
  <Step title="Launch your site on a test device.">
    * Use Chrome, Firefox, Edge, or Safari while testing.
    * **Do not use Incognito or private browsing mode.** Users cannot subscribe to push notifications in these modes.
    * The prompts should appear based on your [permission prompts](/docs/en/permission-requests) configuration.
    * Click **Allow** on the native prompt to subscribe to push notifications.

    <Frame>
      <img alt="Browser native permission prompt asking the user to allow or block notifications" />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status **Subscribed**.

    <Frame>
      <img alt="OneSignal dashboard Subscriptions page showing a web push subscription with Subscribed status" />
    </Frame>

    <Check>You have successfully created a [web push subscription](/docs/en/subscriptions).
    Web push subscriptions are created when users first subscribe to push notifications on your site.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img alt="Options menu on a subscription showing the Add to test users option" />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img alt="Segment editor with Test Users filter selected and the segment named Test Users" />
    </Frame>

    <Check>You have successfully created a segment of test users.
    You can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment created earlier.

    ```curl theme={null}
    curl -X POST --url 'https://api.onesignal.com/notifications' \
      --header 'content-type: application/json; charset=utf-8' \
      --header 'authorization: Key YOUR_APP_API_KEY' \
      --data '{
        "app_id": "YOUR_APP_ID",
        "target_channel": "push",
        "name": "Testing basic setup",
        "headings": {
          "en": "👋"
        },
        "contents": {
          "en": "Hello world!"
        },
        "included_segments": [
          "Test Users"
        ],
        "chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification.

    <Warning>Only Chrome supports images. Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Warning>

    <Frame>
      <img alt="Expanded Chrome push notification on macOS displaying a custom image" />
    </Frame>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats. You should see the **confirmed** stat, meaning the device received the push.

    <Note>Safari does not support confirmed receipt.</Note>

    <Card title="Push notification message reports" icon="chart-bar" href="/docs/en/push-notification-message-reports">
      View delivery, click, and conversion stats for your push notifications.
    </Card>
  </Step>
</Steps>

<Check>You have successfully sent a notification via the API to a segment.</Check>

If notifications are not arriving, contact `support@onesignal.com` with the following:

* The API request and response (copy-paste into a `.txt` file)
* Your Subscription ID
* Your website URL with the OneSignal code

***

## User identification

The previous section covered creating web push [Subscriptions](/docs/en/subscriptions). This section expands to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. It covers External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with the SDK's [`login` method](/docs/en/web-sdk-reference#login-external-id) each time a user is identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via the SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with the SDK's [`addTag` and `addTags` methods](/docs/en/web-sdk-reference#addtag-%2C-addtags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img alt="OneSignal user profile showing a data tag named current_level with value 6" />
</Frame>

You can create a segment of users with a level between 5 and 10, then use that segment to send targeted and personalized messages:

<Frame>
  <img alt="Segment editor filtering users where current_level is greater than 4 and less than 10" />
</Frame>

<Frame>
  <img alt="Push notification composer targeting the Level 5-10 segment with a personalized message" />
</Frame>

### Add email and/or SMS subscriptions

The OneSignal SDK creates web push subscriptions automatically when users opt in. You can also reach users through email and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/web-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/web-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address or phone number already exists in the OneSignal app, the SDK adds it to the existing user. It does not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img alt="OneSignal user profile showing push, email, and SMS subscriptions linked by External ID" />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/web-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/web-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

For more on privacy and security:

<Columns>
  <Card title="Data collected by the SDK" icon="database" href="/docs/en/data-collected-by-the-onesignal-sdk">
    Review what data the OneSignal SDK collects from users.
  </Card>

  <Card title="Handling personal data" icon="shield-halved" href="/docs/en/handling-personal-data">
    Manage and protect user data in compliance with privacy regulations.
  </Card>
</Columns>

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners you can hook into. See the [SDK reference guide](/docs/en/web-sdk-reference) for more details.

### Push notification events

* [Click event listener](/docs/en/web-sdk-reference#click): Detect when a notification is tapped.
* [Foreground lifecycle listener](/docs/en/web-sdk-reference#foregroundwilldisplay): Control how notifications behave in foreground.

### User state changes

* [User state change event listener](/docs/en/web-sdk-reference#addeventlistener-user-state): Detect when the External ID is set.
* [Permission observer](/docs/en/web-sdk-reference#permissionchange): Track the user's specific interaction with the native push permission prompt.
* [Push subscription change observer](/docs/en/web-sdk-reference#addeventlistener-push-subscription-changes): Track when the push subscription status changes.

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

<Columns>
  <Card title="Migrating to OneSignal" icon="rotate" href="/docs/en/migrating-to-onesignal">
    Move from another push provider to OneSignal.
  </Card>

  <Card title="Integrations" icon="plug" href="/docs/en/integrations">
    Connect OneSignal with third-party tools and platforms.
  </Card>

  <Card title="Action buttons" icon="bell" href="/docs/en/action-buttons">
    Add interactive buttons to push notifications.
  </Card>

  <Card title="Multi-language messaging" icon="globe" href="/docs/en/multi-language-messaging">
    Send localized messages to users in their preferred language.
  </Card>

  <Card title="Identity Verification" icon="shield-check" href="/docs/en/identity-verification">
    Secure your SDK integration with server-side identity verification.
  </Card>

  <Card title="Custom Outcomes" icon="chart-line" href="/docs/en/custom-outcomes">
    Track custom conversion events tied to your messages.
  </Card>
</Columns>

### Web SDK setup & reference

<Columns>
  <Card title="Web push setup" icon="gear" href="/docs/en/web-push-setup">
    Enable all key web push features for your integration.
  </Card>

  <Card title="Web SDK reference" icon="code" href="/docs/en/web-sdk-reference">
    Full details on available methods and configuration options.
  </Card>
</Columns>

<Check>Congratulations! You've successfully completed the Web SDK setup guide.</Check>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>


# watchOS & Wear OS Support
Source: https://documentation.onesignal.com/docs/en/watchos-and-wear-os-support

Complete guide to implementing OneSignal push notifications for standalone Apple watchOS and Android Wear OS applications, including setup instructions and API integration.

## Apple watchOS Setup

OneSignal supports push notifications for Apple Watch apps in two ways: synced notifications from paired iOS apps and standalone watchOS app implementations.

### Synced Notifications

When an iOS mobile app is synced to a watchOS app, notifications sent to the iPhone will automatically appear on the paired Apple Watch.

### Standalone watchOS Implementation

For standalone watchOS apps, you can implement push notifications independently. While OneSignal doesn't provide a dedicated SDK for standalone watchOS apps, you can integrate using the following approach:

<Steps>
  <Step title="Register for Remote Notifications">
    Implement the Apple WatchKit `WKExtension` with the `registerForRemoteNotifications` [method](https://developer.apple.com/documentation/watchkit/wkextension/3141920-registerforremotenotifications?language=objc). This generates the APNs push token specifically for the watch device.
  </Step>

  <Step title="Handle Token Registration">
    Set up the `WKExtensionDelegate` to capture the APNs push token using the `didRegisterForRemoteNotificationsWithDeviceToken` [method](https://developer.apple.com/documentation/watchkit/wkextensiondelegate/3141924-didregisterforremotenotification?language=objc).
  </Step>

  <Step title="Register Device with OneSignal">
    Create the subscription in OneSignal using the [Add a device](/reference/add-a-device) API with these required properties:

    **Required Parameters:**

    * `identifier`: The APNs push token generated by the watch
    * `device_type`: Set to `0` for iOS devices
    * `external_user_id`: Unique identifier for the user who owns this subscription

    **Optional Parameters:**

    * `test_type`: Required only when testing on development or ad-hoc builds
    * Additional properties as needed for your implementation
  </Step>

  <Step title="Send Notifications">
    Once the device is registered, you can send push notifications directly to the watch through OneSignal's dashboard or API.
  </Step>
</Steps>

***

## Android Wear OS Setup

The OneSignal Android Native SDK is fully compatible with Android Wear OS applications, providing seamless integration without additional configuration.

### Custom Notifications

You can enhance the watch experience by building:

* Custom notification layouts optimized for wearable displays
* Wearable-specific actions and interactions
* Watch-only notification behaviors

Follow the official Android Developer [Notifications on Wear OS](https://developer.android.com/training/wearables/notifications) documentation for detailed implementation guidance on creating rich, interactive notifications tailored for wearable devices.

### Implementation Notes

* Use the same OneSignal Android SDK as mobile apps
* No additional setup required for basic functionality
* Custom layouts and actions require standard Android Wear OS development practices

***


# Web SDK - Custom Code Setup
Source: https://documentation.onesignal.com/docs/en/web-push-custom-code-setup

Complete guide for setting up OneSignal Web Push notifications using custom code integration. Configure JavaScript SDK, service workers, and Safari certificates for Chrome, Firefox, Safari, and other web browsers.

<SdkReleasesIframe />

<Warning>
  Only use this Custom Code setup if you need advanced configuration or programmatic control. For most users, we recommend the:

  * [Typical web push setup](./web-push-setup)
  * [WordPress setup](./wordpress)
  * [Shopify setup](./shopify)
</Warning>

If you're using a JavaScript framework, follow these specialized guides:

* [Angular setup](./angular-setup)
* [React JS setup](./react-js-setup)
* [Vue JS setup](./vue-js-setup)

## Requirements

* HTTPS website: Web push does not work on HTTP or in incognito/private modes.
* Server access: You’ll need to upload a service worker file to your site.
* Single origin: Web push follows the [Same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy). If you have multiple origins (domains/subdomains), you will need multiple OneSignal apps (one per origin). To comply with this browser limitation, you can either:
  * Redirect traffic to a single origin for subscriptions.
  * Create multiple OneSignal apps—one per origin.

***

## Configure your OneSignal app and platform

In the OneSignal dashboard:

* Go to **Settings > Push & In-App > Web**.
* Select the **Custom Code** integration type.

### Site setup

Add the site details:

* **Site Name**: The name of your site and default notification title.
* **Site URL**: The exact [origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) of your site, e.g., `https://yourdomain.com`. Avoid using `www.` if your site isn’t configured that way. See [Requirements](#requirements) if you have multiple origins.
* **Auto Resubscribe**: Enable this to automatically resubscribe users who clear their browser data when they return to your site (no new permission prompt required).
* **Default Icon URL**: Upload a square `256x256px` PNG or JPG image that appears in notifications and prompts. If not set, a bell icon is used as the default.

<Frame>
  <img alt="OneSignal web push configuration showing site name, URL, and icon settings" />
</Frame>

#### Local testing

To test on localhost, use a separate OneSignal app from your production app and add `allowLocalhostAsSecureOrigin: true` to your `init` options.

If you're testing localhost on HTTPS with a self-signed certificate, you may need to tell Chrome to ignore invalid certificates with `--allow-insecure-localhost`. Firefox and Safari provide built-in mechanisms to add exceptions for security certificates.

```html theme={null}
  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
    window.OneSignalDeferred = window.OneSignalDeferred || [];
    OneSignalDeferred.push(function(OneSignal) {
      OneSignal.init({
        appId: "YOUR_OS_APP_ID",
        allowLocalhostAsSecureOrigin: true,
      });
    });
  </script>
```

### Safari web push certificate (optional)

OneSignal provides Safari certificates automatically at no cost. Only enable this if you have existing Safari Web Push certificates you need to use.

<Frame>
  <img alt="Safari certificate upload option" />
</Frame>

If enabled, upload your `Safari Web .p12 Push Certificate` and enter the password.

Click **Save** to continue.

### Upload service worker files

On the next page of web push configuration, you will be provided the `OneSignalSDKWorker.js` service worker file.

The web SDK looks for this file in the root of your site by default, e.g., `https://yourdomain.com/OneSignalSDKWorker.js`. You can change the file location, name, and scope in code.

<Card title="OneSignal service worker" icon="gear" href="./onesignal-service-worker">
  Advanced service worker configuration, custom integration, and migration from other providers.
</Card>

### Add code to site

Add this code to your website's `<head>` section. Replace:

* `YOUR_ONESIGNAL_APP_ID` with your actual App ID from the OneSignal dashboard
* `YOUR_SAFARI_WEB_ID` with your actual Safari Web ID from the OneSignal dashboard

```html HTML theme={null}
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_ONESIGNAL_APP_ID",
      safari_web_id: "YOUR_SAFARI_WEB_ID",
      // Optional: Only needed if using custom Safari certificates
      // Find in Settings > Push & In-App > Web > Safari Certificate
      notifyButton: {
        enable: true,
      },
    });
  });
</script>
```

### iOS web push support

Apple started supporting web push notifications on iPhones and iPads running iOS 16.4+. Unlike Android devices where web push just "works" as long as visited on a supported browser, Apple added a few more requirements such as a `manifest.json` file and a user action to add your site to their home screen.

<Card title="iOS web push setup" icon="apple" href="./web-push-for-ios">
  Add the required `manifest.json` file and guide users to add your site to their home screen.
</Card>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications and subscription registration.

### Check web push subscriptions

<Steps>
  <Step title="Launch your site on a test device.">
    * Use Chrome, Firefox, Edge, or Safari while testing.
    * **Do not use Incognito or private browsing mode.** Users cannot subscribe to push notifications in these modes.
    * The prompts should appear based on your [permission prompts](/docs/en/permission-requests) configuration.
    * Click **Allow** on the native prompt to subscribe to push notifications.

    <Frame>
      <img alt="Browser native permission prompt asking the user to allow or block notifications" />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status **Subscribed**.

    <Frame>
      <img alt="OneSignal dashboard Subscriptions page showing a web push subscription with Subscribed status" />
    </Frame>

    <Check>You have successfully created a [web push subscription](/docs/en/subscriptions).
    Web push subscriptions are created when users first subscribe to push notifications on your site.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img alt="Options menu on a subscription showing the Add to test users option" />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img alt="Segment editor with Test Users filter selected and the segment named Test Users" />
    </Frame>

    <Check>You have successfully created a segment of test users.
    You can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment created earlier.

    ```curl theme={null}
    curl -X POST --url 'https://api.onesignal.com/notifications' \
      --header 'content-type: application/json; charset=utf-8' \
      --header 'authorization: Key YOUR_APP_API_KEY' \
      --data '{
        "app_id": "YOUR_APP_ID",
        "target_channel": "push",
        "name": "Testing basic setup",
        "headings": {
          "en": "👋"
        },
        "contents": {
          "en": "Hello world!"
        },
        "included_segments": [
          "Test Users"
        ],
        "chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification.

    <Warning>Only Chrome supports images. Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Warning>

    <Frame>
      <img alt="Expanded Chrome push notification on macOS displaying a custom image" />
    </Frame>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats. You should see the **confirmed** stat, meaning the device received the push.

    <Note>Safari does not support confirmed receipt.</Note>

    <Card title="Push notification message reports" icon="chart-bar" href="/docs/en/push-notification-message-reports">
      View delivery, click, and conversion stats for your push notifications.
    </Card>
  </Step>
</Steps>

<Check>You have successfully sent a notification via the API to a segment.</Check>

If notifications are not arriving, contact `support@onesignal.com` with the following:

* The API request and response (copy-paste into a `.txt` file)
* Your Subscription ID
* Your website URL with the OneSignal code

***

## User identification

The previous section covered creating web push [Subscriptions](/docs/en/subscriptions). This section expands to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. It covers External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with the SDK's [`login` method](/docs/en/web-sdk-reference#login-external-id) each time a user is identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via the SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with the SDK's [`addTag` and `addTags` methods](/docs/en/web-sdk-reference#addtag-%2C-addtags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img alt="OneSignal user profile showing a data tag named current_level with value 6" />
</Frame>

You can create a segment of users with a level between 5 and 10, then use that segment to send targeted and personalized messages:

<Frame>
  <img alt="Segment editor filtering users where current_level is greater than 4 and less than 10" />
</Frame>

<Frame>
  <img alt="Push notification composer targeting the Level 5-10 segment with a personalized message" />
</Frame>

### Add email and/or SMS subscriptions

The OneSignal SDK creates web push subscriptions automatically when users opt in. You can also reach users through email and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/web-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/web-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address or phone number already exists in the OneSignal app, the SDK adds it to the existing user. It does not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img alt="OneSignal user profile showing push, email, and SMS subscriptions linked by External ID" />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/web-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/web-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

For more on privacy and security:

<Columns>
  <Card title="Data collected by the SDK" icon="database" href="/docs/en/data-collected-by-the-onesignal-sdk">
    Review what data the OneSignal SDK collects from users.
  </Card>

  <Card title="Handling personal data" icon="shield-halved" href="/docs/en/handling-personal-data">
    Manage and protect user data in compliance with privacy regulations.
  </Card>
</Columns>

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners you can hook into. See the [SDK reference guide](/docs/en/web-sdk-reference) for more details.

### Push notification events

* [Click event listener](/docs/en/web-sdk-reference#click): Detect when a notification is tapped.
* [Foreground lifecycle listener](/docs/en/web-sdk-reference#foregroundwilldisplay): Control how notifications behave in foreground.

### User state changes

* [User state change event listener](/docs/en/web-sdk-reference#addeventlistener-user-state): Detect when the External ID is set.
* [Permission observer](/docs/en/web-sdk-reference#permissionchange): Track the user's specific interaction with the native push permission prompt.
* [Push subscription change observer](/docs/en/web-sdk-reference#addeventlistener-push-subscription-changes): Track when the push subscription status changes.

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

<Columns>
  <Card title="Migrating to OneSignal" icon="rotate" href="/docs/en/migrating-to-onesignal">
    Move from another push provider to OneSignal.
  </Card>

  <Card title="Integrations" icon="plug" href="/docs/en/integrations">
    Connect OneSignal with third-party tools and platforms.
  </Card>

  <Card title="Action buttons" icon="bell" href="/docs/en/action-buttons">
    Add interactive buttons to push notifications.
  </Card>

  <Card title="Multi-language messaging" icon="globe" href="/docs/en/multi-language-messaging">
    Send localized messages to users in their preferred language.
  </Card>

  <Card title="Identity Verification" icon="shield-check" href="/docs/en/identity-verification">
    Secure your SDK integration with server-side identity verification.
  </Card>

  <Card title="Custom Outcomes" icon="chart-line" href="/docs/en/custom-outcomes">
    Track custom conversion events tied to your messages.
  </Card>
</Columns>

### Web SDK setup & reference

<Columns>
  <Card title="Web push setup" icon="gear" href="/docs/en/web-push-setup">
    Enable all key web push features for your integration.
  </Card>

  <Card title="Web SDK reference" icon="code" href="/docs/en/web-sdk-reference">
    Full details on available methods and configuration options.
  </Card>
</Columns>

<Check>Congratulations! You've successfully completed the Web SDK setup guide.</Check>

***

***

## FAQ

### Do I need HTTPS for web push notifications?

Yes. All modern browsers require HTTPS for push notification support. If your site uses HTTP, you must migrate to HTTPS before setting up web push.

### Can I use this setup with a single-page application (SPA)?

Yes. The Custom Code setup is the recommended approach for SPAs built with frameworks like React, Angular, or Vue. See the framework-specific guides at the [top of this page](#) for [Angular](./angular-setup), [React](./react-js-setup), and [Vue](./vue-js-setup).

### What happens if a user clears their browser data?

The user's push subscription is removed. If **Auto Resubscribe** is enabled, they are automatically resubscribed the next time they visit your site.

***

## Related pages

<Columns>
  <Card title="Permission Requests" icon="bell" href="./permission-requests">
    Configure when and how users are prompted to subscribe.
  </Card>

  <Card title="Web SDK Reference" icon="code" href="./web-sdk-reference">
    Full API reference for the OneSignal Web SDK.
  </Card>
</Columns>


# iOS web push setup
Source: https://documentation.onesignal.com/docs/en/web-push-for-ios

Complete guide to enabling web push notifications on iOS and iPadOS devices, including manifest file setup, user onboarding strategies, and implementation best practices for Safari, Chrome, and Edge browsers.

<SdkReleasesIframe />

Apple started suporting push notifications on iOS and iPadOS 16.4+ for web apps added to a user's home screen. This functionality works across Safari, Chrome, and Edge browsers, opening new engagement opportunities for web-first companies. This comprehensive guide covers everything you need to implement iOS web push notifications successfully.

<Frame>
  <img />
</Frame>

***

## Important updates for 2025

**Cross-Browser Support**: Web push notifications now work across all major browsers on iOS/iPadOS 16.4+ including Safari, Chrome, and Edge.

**iOS 17+ Improvements**: Enhanced implementation with relevant APIs enabled by default, making web push more accessible to users.

**Reliability Considerations**: Some developers report occasional reliability issues where iOS web push notifications may work initially but then stop unexpectedly. Monitor your notification delivery rates and have fallback engagement strategies in place.

***

## Requirements

* **iOS/iPadOS Version**: 16.4 or higher
* **HTTPS Origin**: Secure connection with responsive design
* **Web Application Manifest**: Valid `manifest.json` file with correct settings
* **Home Screen Installation**: Web app must be added to user's home screen from any supported browser
* **User-Initiated Action**: User must interact with your site before permission prompts can appear
* **OneSignal Service Worker**: Required for notification delivery

### Progressive web app (PWA) check

If your website is already a [Progressive Web App (PWA)](https://onesignal.com/blog/what-is-a-pwa/), no additional site updates are needed. Use [Lighthouse in Chrome DevTools](https://developer.chrome.com/docs/lighthouse/overview/#devtools) to audit whether your site qualifies as a PWA.

***

## Setup

### 1. Create your web application manifest

A Web Application Manifest (`manifest.json`) is a JSON file that defines how your web application appears and behaves when installed on a user's device. For iOS web push, this file is **mandatory**.

#### Required manifest fields

Your `manifest.json` must include these essential fields:

* **`$schema`** (recommended): JSON schema URL for validation and IDE support
* **`name`** (required): Full application name displayed to users
* **`display`** (required): Must be set to `"standalone"` or `"fullscreen"` for iOS compatibility
* **`start_url`** (required): Entry point URL when the application launches
* **`icons`** (required): Array of icon objects with multiple sizes
* **`id`** (recommended): Unique identifier allowing multiple app instances

#### Example manifest file

```json theme={null}
{
  "$schema": "https://json.schemastore.org/web-manifest-combined.json",
  "name": "OneSignal Manifest Example",
  "short_name": "OS Manifest",
  "display": "standalone",
  "start_url": "/",
  "theme_color": "#E54B4D",
  "background_color": "#ffffff",
  "icons": [
    { "src": "/icon-192x192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-256x256.png", "sizes": "256x256", "type": "image/png" },
    { "src": "/icon-384x384.png", "sizes": "384x384", "type": "image/png" },
    { "src": "/icon-512x512.png", "sizes": "512x512", "type": "image/png" }
  ],
  "id": "?homescreen=1"
}
```

#### Implementation steps

1. **File Placement**: Place `manifest.json` in your website's root directory
2. **HTML Integration**: Add this link tag to the `<head>` section of all pages:

```html theme={null}
<link rel="manifest" href="/manifest.json"/>
```

3. **Icon Preparation**: Create high-quality PNG icons in multiple sizes (192x192, 256x256, 384x384, 512x512 pixels recommended)

<Note>
  Use tools like [SimiCart Manifest Generator](https://www.simicart.com/manifest-generator.html/) to quickly create manifest files, or validate existing ones with [Manifest Tester](https://manifesttester.com/).
</Note>

### 2. Add the OneSignal service worker

If you've already completed our [Web SDK setup](./web-sdk-setup) and can receive web push notifications on other browsers, this step is complete. See [OneSignal Service Worker](./onesignal-service-worker) documentation for detailed setup instructions.

### 3. Configure permission prompts

Existing [Web permission prompts](./permission-requests) from your [Web SDK setup](./web-sdk-setup) will work on iOS devices **only after users add your site to their home screen and open it from there**. This is Apple's design requirement.

### 4. Guide users to "Add to Home Screen"

Unlike desktop or Android devices where permission prompts appear based on your settings, iOS requires a specific user journey that you must facilitate.

#### The required user journey

Users must complete these steps to receive notifications:

1. Visit your website on Safari, Chrome, or Edge on iOS/iPadOS 16.4+
2. Click the browser's **Share** button
3. Select **Add to Home Screen** option
4. Save the app to their device
5. Open the app from the home screen (not the browser)
6. Interact with your subscribe button to trigger the native permission prompt

<Frame>
  <img />
</Frame>

#### User onboarding strategies

Since this process isn't intuitive, implement clear guidance through:

* **Website banners**: Display banners specifically on mobile Apple devices explaining the value of notifications and providing step-by-step instructions.

* **Visual guides**: Use screenshots and arrows to show users exactly where to tap.

* **Timing**: Present the guidance after users have demonstrated engagement with your content.

#### Implementation examples

Here are effective approaches from real applications:

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

#### Open source solutions

Consider implementing this popular open-source banner solution:

**GitHub Project**: [add-to-home-screen by rajatsehgal](https://github.com/rajatsehgal/add-to-home-screen)

<Frame>
  <img />
</Frame>

Additional banner examples and best practices available at [web.dev](https://web.dev/promote-install/).

### 5. Testing and validation

#### Manifest file testing

1. **Accessibility Check**: Navigate to `https://yoursite.com/manifest.json` to ensure public accessibility
2. **Browser DevTools**:
   * Open Chrome DevTools (F12)
   * Go to Application tab → Manifest
   * Review any errors or warnings
3. **Online Validators**:
   * [Manifest Tester](https://manifesttester.com/)
   * [Redirection.io Validator](https://redirection.io/tools/web-app-manifest/validator)
   * [ValidBot Manifest Wizard](https://www.validbot.com/tools/app-manifest-wizard.php)

#### End-to-end push notification testing

1. Visit your website on iOS 16.4+ device using Safari, Chrome, or Edge
2. Click the browser's **Share** button
3. Select **Add to home screen**
4. Save the app to your device
5. Open the app from the home screen (crucial step)
6. Trigger your subscribe button - the native permission prompt should appear
7. Grant permission and test notification delivery

#### Important testing notes

**Re-testing requirements**: To test again on the same device:

* Remove the app from home screen
* Clear browser cache (Settings > Safari/Chrome/Edge > Clear cache)
* Repeat the process

**Permission denied recovery**: If permission is denied, the home screen app must be removed and re-added for the permission prompt to appear again.

**Common issues to check**:

* Ensure `display` field is `"standalone"` or `"fullscreen"`
* Verify all icon paths are accessible
* Confirm manifest serves with correct MIME type (`application/manifest+json`)
* Test for CORS errors

***

## Troubleshooting

**Manifest not loading**: Check file path, HTTPS requirement, and MIME type configuration on your server.

**Icons not displaying**: Verify icon file accessibility and correct size specifications in manifest.

**Permission prompt not appearing**: Ensure user accessed site via home screen app and clicked an interactive element first.

**Notifications not delivering**: Verify OneSignal service worker is properly installed and check browser console for errors.

***

## Next steps

<Check>
  You're now ready to send notifications! Continue to [Push](./push) documentation or use our [Create message](/reference/create-message) API to start engaging your iOS users with web push notifications.
</Check>

For ongoing success, monitor your iOS web push performance metrics and consider implementing progressive enhancement strategies that gracefully handle the additional steps required for iOS users while providing seamless experiences on other platforms.

***


# Web SDK reference
Source: https://documentation.onesignal.com/docs/en/web-sdk-reference

Complete API reference for OneSignal Web SDK v16 with initialization, user management, push notifications, slidedown prompts, and debugging methods. Learn how to implement web push notifications, manage user subscriptions, and integrate email/SMS features.

## Setup & debugging

You may need to wrap OneSignal calls in `OneSignalDeferred.push(async function (OneSignal) { ... })` (use `function (OneSignal) { ... }` when you do not need `await`). The **`OneSignal`** argument is the SDK instance used throughout this reference (for example `await OneSignal.init({ ... })`).

You can push several callbacks, or put multiple statements inside one callback.

The OneSignal SDK is loaded with the `defer` attribute on your page. For example:

`<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>`

That way the SDK runs after the document is parsed and does not block rendering. Scripts that run earlier still need a place to queue work until the SDK is ready. Start with:

`window.OneSignalDeferred = window.OneSignalDeferred || [];`

That line defines `OneSignalDeferred` if it is missing. If an earlier snippet on the page already set it, the same reference is kept; otherwise it begins as an empty array `[]` you push callbacks onto.

Arrays expose a [`.push()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) method, so you enqueue functions with `OneSignalDeferred.push(...)`. When the SDK loads, it drains the queue and redefines `.push()` so later pushes run immediately (see the [Web SDK source](https://github.com/OneSignal/OneSignal-Website-SDK)).

<Note>
  Most snippets below use `OneSignal` alone. Treat that as the instance from your deferred callback after `await OneSignal.init({ ... })`, unless a section states otherwise (for example [`setConsentRequired()`](#setconsentrequired) before `init`).
</Note>

### `init()`

Initializes the OneSignal SDK. This should be called in the `<head>` tag once on each page of your site. The `ONESIGNAL_APP_ID` can be found in [Keys & IDs](./keys-and-ids).

<Note>
  If you want to delay initialization of the OneSignal SDK, we recommend using our [Privacy methods](#privacy).
</Note>

<CodeGroup>
  ```javascript JavaScript theme={null}
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "ONESIGNAL_APP_ID",
    });
  });
  ```
</CodeGroup>

<Warning>
  Init options only work with [Custom Code Setup](./web-push-custom-code-setup). Otherwise, these are configured in the OneSignal dashboard.
</Warning>

|             Parameter            |   Type  | Description                                                                                                                                                   |
| :------------------------------: | :-----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|              `appId`             |  String | **Required:** Your OneSignal App ID found in [Keys & IDs](./keys-and-ids).                                                                                    |
|   `requiresUserPrivacyConsent`   | Boolean | Delays SDK initialization until the user provides privacy consent. Must call [`setConsentGiven()`](#setconsentgiven) to complete setup.                       |
|          `safari_web_id`         |  String | The Safari Web ID for your uploaded Safari `.p12` certificate. [Web Quickstart](./web-push-setup).                                                            |
|          `promptOptions`         |  Object | Customize the permission prompts. [Details below](#promptoptions-parameters).                                                                                 |
|          `notifyButton`          |  Object | Enable and configure the Subscription Bell. [Details below](#notifybutton-parameters).                                                                        |
|       `welcomeNotification`      |  Object | Customize or disable the welcome notification. [Details below](#welcomenotification-parameters).                                                              |
|       `persistNotification`      | Boolean | Chrome (desktop only) - `true`: notification persists until clicked, `false`: disappears after a short time. Firefox/Safari ignore this setting.              |
|            `webhooks`            |  Object | Configure event callbacks. [See Webhooks](./webhooks).                                                                                                        |
|         `autoResubscribe`        | Boolean | **Recommended:** Auto-resubscribes users who clear browser cache or migrate to OneSignal. Overrides dashboard setting if used in code.                        |
|  `notificationClickHandlerMatch` |  String | `"exact"` (default): focuses tab with an exact URL match. `"origin"`: focuses any tab with the same domain.                                                   |
| `notificationClickHandlerAction` |  String | `"navigate"` (default): navigates to `launchURL`. `"focus"`: focuses existing tab (only used with `"origin"` match).                                          |
|       `serviceWorkerParam`       |  Object | Set the `scope` of the service worker. Must be different from other service worker's scope if applicable. Example:<br />`{ scope: "/myPath/myCustomScope/" }` |
|        `serviceWorkerPath`       |  String | Set the location of the OneSignal service worker file. Example:<br />`"myPath/OneSignalSDKWorker.js"`                                                         |

***

#### `promptOptions` parameters

Use `promptOptions` to localize or customize the user permission prompts. All fields are optional.

Structure: `promptOptions.slidedown.prompts` is an **array**; each element is one prompt configuration. The **`type`**, **`autoPrompt`**, **`delay`**, **`text`**, and **`categories`** fields belong on **each object inside `prompts`**, not as top-level keys next to `appId` on `init`.

|   Parameter  |       Type       | Description                                                                                                                                                                                                                                                                                                                                     |
| :----------: | :--------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  `slidedown` |      Object      | Wrapper for slidedown configuration. Contains `prompts`.                                                                                                                                                                                                                                                                                        |
|   `prompts`  | Array of Objects | Array of prompt configs. Example:<br />`promptOptions: { slidedown: { prompts: [{...}, {...}] } }`                                                                                                                                                                                                                                              |
|    `type`    |      String      | **Per `prompts[]` entry.** Prompt types:<br /><ul><li>`push` – Slide Prompt (no categories)</li><li>`category` – Slide Prompt with up to 10 categories</li><li>`email` – Collect email only</li><li>`sms` – Collect phone number only</li><li>`smsAndEmail` – Collect both</li></ul>See [Web Permission Prompts](./permission-requests).        |
| `autoPrompt` |      Boolean     | **Per `prompts[]` entry.** <ul><li>`true`: show based on `delay`.</li><li>`false`: prompt only shown manually via Slidedown API.</li></ul>                                                                                                                                                                                                      |
|    `delay`   |      Object      | **Per `prompts[]` entry.** When auto-prompt runs:<br />`{ pageViews: 3, timeDelay: 20 }` = after 3rd pageview and 20s wait.                                                                                                                                                                                                                     |
|    `text`    |      Object      | **Per `prompts[]` entry.** Custom text options:<br /><ul><li>`actionMessage` (max 90 chars)</li><li>`acceptButton` (max 15)</li><li>`cancelButton` (max 15)</li><li>`emailLabel`, `smsLabel`, `confirmMessage`</li><li>`updateMessage`, `positiveUpdateButton`, `negativeUpdateButton` (used for updating categories or contact info)</li></ul> |
| `categories` | Array of Objects | **Per `prompts[]` entry**, for `type: category`. Each object includes:<br />`tag`: internal key<br />`label`: user-visible name<br />Example: `[ {tag: "local_news", label: "Local News"} ]`. See [Tags](./add-user-data-tags).                                                                                                                 |

***

#### `notifyButton` parameters

Configure the Subscription Bell (notify button) shown on the page.

|      Parameter     |   Type   | Description                                                                                                   |
| :----------------: | :------: | ------------------------------------------------------------------------------------------------------------- |
|      `enable`      |  Boolean | Enables the Subscription Bell. Disabled by default.                                                           |
| `displayPredicate` | Function | Custom function (or Promise) that returns `true` or `false` to show/hide the Bell. Evaluated once when shown. |
|       `size`       |  String  | `'small'`, `'medium'`, or `'large'`. Shrinks to `'small'` after subscription.                                 |
|     `position`     |  String  | `'bottom-left'` or `'bottom-right'`.                                                                          |
|      `offset`      |  Object  | CSS pixel offsets: `{ bottom: '50px', left: '10px' }`                                                         |
|     `prenotify`    |  Boolean | If `true`, shows a "1 unread" icon and custom hover text.                                                     |
|    `showCredit`    |  Boolean | Set to `false` to hide "Powered by OneSignal" in the popup.                                                   |
|       `text`       |  Object  | Custom text for the bell UI.                                                                                  |

***

#### `welcomeNotification` parameters

Customize the welcome notification sent after first-time subscription.

| Parameter |   Type  | Description                                                                                |
| :-------: | :-----: | ------------------------------------------------------------------------------------------ |
| `disable` | Boolean | Disable welcome notification.                                                              |
| `message` |  String | **Required:** Notification message. Defaults to `'Thanks for subscribing!'` if blank.      |
|  `title`  |  String | Notification title. Defaults to site title. Use `' '` (space) to remove (not recommended). |
|   `url`   |   URL   | Optional URL to open when the user clicks the notification. Typically not needed.          |

***

**Example**:

<CodeGroup>
  ```javascript Example init for Custom Code Setup theme={null}
  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_APP_ID",
      safari_web_id: "YOUR_SAFARI_WEB_ID",
      notifyButton: {
        enable: true,
      },
      promptOptions: {
        slidedown: {
          prompts: [{
              type: "smsAndEmail",
              autoPrompt: false,
              text: {
                emailLabel: "Insert Email Address",
                smsLabel: "Insert Phone Number",
                acceptButton: "Submit",
                cancelButton: "No Thanks",
                actionMessage: "Receive the latest news, updates and offers as they happen.",
                updateMessage: "Update your push notification subscription preferences.",
                confirmMessage: "Thank You!",
                positiveUpdateButton: "Save Preferences",
                negativeUpdateButton: "Cancel",
              },
              delay: {
                pageViews: 1,
                timeDelay: 20
              },
            },
            {
              type: "category",
              autoPrompt: true,
              text: {
                actionMessage: "We'd like to show you notifications for the latest news and updates.",
                acceptButton: "Allow",
                cancelButton: "Cancel",

                /* CATEGORY SLIDEDOWN SPECIFIC TEXT */
                negativeUpdateButton: "Cancel",
                positiveUpdateButton: "Save Preferences",
                updateMessage: "Update your push notification subscription preferences.",
              },
              delay: {
                pageViews: 3,
                timeDelay: 20
              },
              categories: [{
                  tag: "politics",
                  label: "Politics"
                },
                {
                  tag: "local_news",
                  label: "Local News"
                },
                {
                  tag: "world_news",
                  label: "World News",
                },
                {
                  tag: "culture",
                  label: "Culture"
                },
              ]
            }
          ]
        }
      }
    });
  });
  </script>
  ```
</CodeGroup>

### `setLogLevel()`

Set the logging to print additional logs to the console. See [Debugging with Browser DevTools](./troubleshooting-web-push#debugging-using-browser-developer-tools) for more details. Run from a deferred callback after `init` (same **`OneSignal`** instance as elsewhere).

```javascript JavaScript theme={null}
  OneSignal.Debug.setLogLevel("trace");
```

**Log levels**:

* `'trace'`
* `'debug'`
* `'info'`
* `'warn'`
* `'error'`

***

## User identity & properties

When users subscribe to push notifications on your website, OneSignal automatically creates a OneSignal ID (user-level ID) and a Subscription ID (device-level ID). You can associate multiple Subscriptions (e.g., devices, emails, phone numbers) with a single user by calling `login()` with your unique user identifier.

<Note>
  See [Users](./users) and [Subscriptions](./subscriptions) for more details.
</Note>

### `login(external_id)`

Sets the current user context to the provided `external_id`. This links the current device (web push Subscription) to a known user and unifies all future data under a single `onesignal_id`. Use this method only for **identified users** (for example, after login or account restore). For anonymous users, do not call `login`. Instead, track them using their automatically assigned `onesignal_id` (see [OneSignal.User.onesignalId](#onesignal-user-onesignalid)).

**What happens when you call `login(external_id)`**

The SDK behaves differently depending on whether the `external_id` already exists within the OneSignal app.

**If the `external_id` already exists:**

* The SDK switches to that existing user.
  * You may see a `409 Conflict` in the browser network log or console. It means the External ID already exists in the app; it is expected in this path and is not usually a promise rejection you must handle.
* The current `onesignal_id` is discarded and the existing `onesignal_id` for that user is loaded.
* The current device (web push Subscription) is linked to the existing user.
* Anonymous data collected before login is not merged and is discarded. This includes tags, session data, email/SMS Subscriptions, and other local user properties.

**If the `external_id` does not exist:**

* A new user is created using the current `onesignal_id`.
* All data collected while the user was anonymous is retained.
* The device (web push Subscription) becomes linked to this new user.

**Retry behavior:**

* The SDK automatically retries the login request on network failures or server errors.
* You do not need to implement your own retry logic.

**Best practices:**

* Call `login(external_id)` **every page load** once you know the user's ID (for example, after sign-in or session restore).
* Call it again whenever the signed-in user changes (account switch).
* Do not call `login` before you have a stable, known user identifier.

```javascript JavaScript theme={null}
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.login("external_id");
});
```

### `logout()`

Unlinks the current user from the web push Subscription.

* Removes the `external_id` from the current web push Subscription. Does not remove the `external_id` from other Subscriptions.
* Resets the `onesignal_id` to a new anonymous user.
* Any new data (e.g tags, Subscriptions, session data, etc.) will now be set on the new anonymous user until they are identified with the `login` method.

<Note>Use this when a user signs out of your site and you do not want to send targeted transactional messages to the browser anymore.</Note>

```javascript JavaScript theme={null}
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.logout();
});
```

### `OneSignal.User.onesignalId`

Retrieves the current user's `onesignal_id` stored locally on the browser. This value represents the active user context (OneSignal's User ID) and can change over time — for example, when you call `login(external_id)` or when the SDK initializes. If called too early, this method may return `null`.

This value is not the Subscription ID which is used to identify the browser aka web push Subscription (see [User.PushSubscription.id](#user-pushsubscription-id)).

**When `onesignal_id` is available:**

* After the OneSignal SDK finishes initializing
* After a user is identified with `login(external_id)`
* After switching users or restoring a session

If you need to reliably react to changes or get this ID, use [User State `addEventListener('change', …)`](#addeventlistener-user-state) instead of polling.

**Common use cases:**
In most cases, you will want to use your own External ID set via the `login` method. However, there are some cases where you may want to use the `onesignal_id` directly.

* Tracking anonymous users before an External ID is set
* Storing the OneSignal ID in your backend for support or debugging
* Correlating OneSignal users with internal logs
* Displaying the ID for troubleshooting or QA

<Warning> Do not persist the OneSignal ID as a permanent user identifier. It can change when users log in, log out, or switch accounts. </Warning>

```javascript JavaScript theme={null}
const onesignalId = OneSignal.User.onesignalId;
```

### `OneSignal.User.externalId`

Retrieve the current user's External ID saved locally on the browser. May be `null` if not set via the `login` method or called before user state is initialized. Instead, use [User State `addEventListener('change', …)`](#addeventlistener-user-state) to listen for user state changes.

```javascript JavaScript theme={null}
  const externalId = OneSignal.User.externalId;
```

### `addEventListener()` *User State*

Listen for changes in the user context (e.g., login, logout, ID assignment).

```javascript JavaScript theme={null}
  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.addEventListener('change', function (event) {
      console.log('change', { event });
    });
  });
```

### `addAlias()`, `addAliases()`, `removeAlias()`, `removeAliases()`

Aliases are alternative identifiers (like usernames or CRM IDs).

* Set `external_id` with `login()` before adding aliases. Aliases added to subscriptions without `external_id` will not sync across multiple subscriptions.
* See [Aliases](./aliases) for details.

```javascript JavaScript theme={null}
  // Add a single alias
  OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

  // Add multiple aliases
  OneSignal.User.addAliases({
    ALIAS_LABEL_01: "ALIAS_ID_01",
    ALIAS_LABEL_02: "ALIAS_ID_02",
    ALIAS_LABEL_03: "ALIAS_ID_03",
  });

  // Remove a single alias
  OneSignal.User.removeAlias("ALIAS_LABEL");

  // Remove multiple aliases
  OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02", "ALIAS_LABEL_03"]);
```

### `getLanguage()`, `setLanguage()`

Get and/or override the auto-detected language of the user. See [Multi-language messaging](./multi-language-messaging) for a list of available language codes.

```javascript JavaScript theme={null}
  // Get the language of the currently logged-in user
  OneSignal.User.getLanguage();

  // Set the language of the currently logged-in user
  OneSignal.User.setLanguage("en");
```

***

## Custom events

[Trigger Journeys](./journeys-settings#custom-events) and [Wait Until step activation](./journeys-actions#wait-until) via a [custom event](./custom-events).

<Note>
  Custom events require Web SDK `160500`+.

  A user should be logged in for custom events to be tracked.

  Call custom event APIs on the **`OneSignal`** instance passed into `OneSignalDeferred.push` (see **Setup & debugging** at the top of this page), not on `window.OneSignal` — the page SDK is initialized through the deferred queue, and that callback is the supported way to access `OneSignal.User`.
</Note>

Track and send a custom event performed by the current user.

* `name` - **Required.** The name of the event as a string.
* `properties` - **Optional.** Key-value pairs to add to the event. The properties dictionary or map must be serializable into a valid JSON Object. Supports nested values.

The SDK automatically includes app-specific data into the properties payload under the reserved key `os_sdk` that will be available to consume. For example, to target events by subscription type, you would access `os_sdk.type`.

```json json theme={null}
{ 
  "os_sdk": {
    "device_os": "138",
    "type": "ChromePush",
    "device_model": "MacIntel",
    "sdk": "160500"
  }
}
```

### `trackEvent()`

Call after [`init()`](#init) completes. This example uses one deferred callback so `init` always runs before `trackEvent`:

```javascript JavaScript theme={null}
OneSignalDeferred.push(async function (OneSignal) {
  await OneSignal.init({ appId: "ONESIGNAL_APP_ID" });

  const properties = {
    promo_code: "NEW50",
    membership_details: {
      vip: true,
      products_viewed_count: 15,
    },
  };
  OneSignal.User.trackEvent("started_free_trial", properties);

  // Event name only (no properties)
  OneSignal.User.trackEvent("my_event_name");
});
```

<Note>
  In production, add `trackEvent` to the deferred callback where you already `await OneSignal.init(...)`. Do not register a second `init` unless you intend to.
</Note>

***

## Tags

Tags are custom `key : value` pairs of string data you set on users based on events or user properties. See [Tags](./add-user-data-tags) for more details.

### `addTag()`, `addTags()`

Set a single or multiple tags on the current user.

* Values will be replaced if the key already exists.
* Exceeding your plan's tag limit will cause the operations to fail silently.

```javascript JavaScript theme={null}
  // Add a single tag
  OneSignal.User.addTag('tag_key', 'tag_value');

  // Add multiple tags
  OneSignal.User.addTags({
   KEY_01: "VALUE_01",
   KEY_02: "VALUE_02",
   KEY_03: "VALUE_03"
  });
```

### `removeTag()`, `removeTags()`

Delete a single or multiple tags from the current user.

```javascript JavaScript theme={null}
  // Delete a single tag
  OneSignal.User.removeTag("KEY");

  OneSignal.User.removeTags(['KEY_01', 'KEY_02', 'KEY_03']);
```

### `getTags()`

Returns the local copy of the user's tags. Tags are updated from the server during `login()` or new app sessions.

```javascript JavaScript theme={null}
  const tags = OneSignal.User.getTags()
```

***

## Privacy

### `setConsentRequired()`

Enforces user consent before data collection begins. Must be called **before** [`init()`](#init) runs (for example at the start of the first `OneSignalDeferred` callback, before `await OneSignal.init(...)`).

This method is the same as adding `requiresUserPrivacyConsent: true` to the `init` options.

```javascript JavaScript theme={null}
  OneSignal.setConsentRequired(true);
```

### `setConsentGiven()`

Grants or revokes user consent for data collection. Without consent, no data is sent to OneSignal and no subscription is created.

* If [`setConsentRequired()`](#setconsentrequired) or `requiresUserPrivacyConsent` is set to `true`, our SDK will not be fully enabled until `setConsentGiven` is called with `true`.
* If `setConsentGiven` is set to `true` and a Subscription is created, then later it is set to `false`, that Subscription will no longer receive updates. The current data for that Subscription remains unchanged until `setConsentGiven` is set to `true` again.
* If you want to delete the User and/or Subscription data, use our [Delete user](/reference/delete-user) or [Delete subscription](/reference/delete-subscription) APIs.

```javascript JavaScript theme={null}
  OneSignal.setConsentGiven(true);
```

***

## Subscriptions

A Subscription represents a single messaging channel instance (for example, a browser) and has a unique Subscription ID (OneSignal's device-level ID). A user can have multiple Subscriptions across devices and platforms.

See [Subscriptions](./subscriptions) for more details.

### `User.PushSubscription.id`

Retrieves the web push Subscription ID for the current browser, stored locally by the SDK.

This ID uniquely identifies this specific browser’s push channel, not the user. It is commonly used when associating devices or browsers with your backend or debugging delivery issues.

If called before the Subscription is created or restored, this value may be `null`.

<Note> To reliably detect when the web push Subscription ID becomes available or changes, use the [push Subscription listener](#addeventlistener-push-subscription-changes). </Note>

```javascript JavaScript theme={null}
  const subscription_id = OneSignal.User.PushSubscription.id;
```

### `User.PushSubscription.token`

Returns the current push subscription token. May return `null` if called too early. It's recommended to get this data within the [subscription observer](#addeventlistener-push-subscription-changes) to react to changes.

```javascript JavaScript theme={null}
  OneSignal.User.PushSubscription.token;
```

### `addEventListener()` *Push Subscription Changes*

Use this method to respond to push subscription changes like:

* The device receives a new push token from Google (FCM) or Apple (APNs)
* OneSignal assigns a subscription ID
* The `optedIn` value changes (e.g. called `optIn()` or `optOut()`)
* The user toggles push permission in browser or OS settings, then returns to your site

When this happens, the SDK runs your **`change`** listener with a state object that includes `previous` and `current` so you can detect what changed.

<Note>
  When [`autoResubscribe`](#init) is `true`, returning visitors may fire the `change` event with `optedIn: true` on both `previous` and `current` because the browser permission did not change — only the push token was re-registered (for example, after clearing site data or migrating). For analytics or server-side tracking that should reflect **new** or **re-subscriptions**, `event.current.token && !event.previous.token` is usually more reliable than comparing `optedIn` alone.
</Note>

To stop listening for updates, call `removeEventListener()` with the same handler reference you passed to `addEventListener()`.

```javascript JavaScript theme={null}
  function pushSubscriptionChangeListener(event) {
    console.log("event.previous.id", event.previous.id);
    console.log("event.current.id", event.current.id);
    console.log("event.previous.token", event.previous.token);
    console.log("event.current.token", event.current.token);
    console.log("event.previous.optedIn", event.previous.optedIn);
    console.log("event.current.optedIn", event.current.optedIn);
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });
```

**External analytics (for example Google Analytics via `dataLayer`):** fire a custom event when a push token appears and there was no token before, so re-registration with unchanged `optedIn` still counts correctly. The subscription ID may arrive in the same callback or a later `change` event depending on timing:

```javascript JavaScript theme={null}
  function pushSubscriptionChangeListener(event) {
    if (!event.current.token || event.previous.token) {
      return;
    }
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: "onesignal_push_subscribed",
      onesignal_subscription_id: event.current.id,
    });
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });
```

<Warning>
  In incognito or private browsing, the Slidedown can still appear when [`autoPrompt`](#promptoptions-parameters) is `true`, but push subscriptions typically do not persist after the session ends. [`isPushSupported()`](#ispushsupported) does not detect private browsing; it only indicates whether web push is available in principle. Before programmatically triggering the prompt (for example [`promptPush()`](#promptpush)), still call `isPushSupported()` so you avoid prompting on browsers that cannot use web push.
</Warning>

### `optOut()`, `optIn()`, `optedIn`

Control the subscription status (`subscribed` or `unsubscribed`) of the current push Subscription. Use these methods to control the push subscription status on your site. Common use cases: 1) Prevent push from being sent to users that log out. 2) Implement a notification preference center within your site.

* `optOut()`: Sets the current push subscription status to unsubscribed (even if the user has a valid push token).
* `optIn()`: Does one of the following:
  1. If the Subscription has a valid push token, it sets the current push subscription status to `subscribed`.
  2. If the Subscription does not have a valid push token, it attempts to display the push permission prompt.
* `optedIn`: Returns `true` if the current push subscription status is subscribed, otherwise `false`. If the push token is valid but `optOut()` was called, this will return `false`.

```javascript JavaScript theme={null}
  OneSignal.User.PushSubscription.optOut();

  OneSignal.User.PushSubscription.optIn();

  var optedIn = OneSignal.User.PushSubscription.optedIn;
```

### `addEmail()`, `removeEmail()`

Adds or removes an email Subscription (email address) for the current user.

These methods are compatible with [Identity Verification](./identity-verification).

**When you call `addEmail(email)`:**

* The email address becomes an email Subscription for the current user.
* The email may be created or reassigned.
* The same email address cannot exist multiple times in the same OneSignal app. If you see duplicate email addresses, check your REST API requests and contact support if needed.

The SDK returns the following HTTP status codes:

| Status code      | Meaning                                                                              |
| ---------------- | ------------------------------------------------------------------------------------ |
| **200 OK**       | The email Subscription already belongs to the current user. No changes were made.    |
| **201 Created**  | A new email Subscription was created and linked to the user.                         |
| **202 Accepted** | The email Subscription already existed in the app and was moved to the current user. |

**When you call `removeEmail(email)`:**

* The email Subscription is removed from the current user.
* The current External ID is removed from the email Subscription.
* A new OneSignal ID is assigned to the email Subscription.
* Other Subscriptions (push, SMS, other emails) remain unaffected.

**Best practices:**

* Call `login()` first, then call `addEmail()`. Otherwise, the email may be attached to an anonymous user.
* Use a stable, verified email address.
* Follow [Email reputation best practices](./email-reputation-best-practices).

```javascript JavaScript theme={null}
  OneSignal.User.addEmail("example@email.com");

  OneSignal.User.removeEmail("example@email.com");
```

### `addSms()`, `removeSms()`

Adds or removes an SMS Subscription (phone number) for the current user. Phone numbers must be provided in [E.164 format](https://www.twilio.com/docs/glossary/what-e164) (for example, `+15551234567`).

These methods are compatible with [Identity Verification](./identity-verification).

**When you call `addSms(phoneNumber)`:**

* The phone number becomes an SMS Subscription for the current user.
* The number may be created or reassigned.
* The same phone number cannot exist multiple times in the same OneSignal app. If you see duplicate phone numbers, check your REST API requests and contact support if needed.

The SDK returns the following HTTP status codes:

| Status code      | Meaning                                                                            |
| ---------------- | ---------------------------------------------------------------------------------- |
| **200 OK**       | The SMS Subscription already belongs to the current user. No changes were made.    |
| **201 Created**  | A new SMS Subscription was created and linked to the user.                         |
| **202 Accepted** | The SMS Subscription already existed in the app and was moved to the current user. |

**When you call `removeSms(phoneNumber)`:**

* The SMS Subscription is removed from the current user.
* The current External ID is removed from the SMS Subscription.
* A new OneSignal ID is assigned to the SMS Subscription.
* Other Subscriptions (push, email, other SMS) remain unaffected.

**Best practices:**

* Call `login()` first, then call `addSms()`. Otherwise, the SMS Subscription may be attached to an anonymous user.
* Always validate and normalize phone numbers to [E.164 format](https://www.twilio.com/docs/glossary/what-e164) before sending.
* Follow [SMS Registration Requirements](./sms-registration-requirements).

```javascript JavaScript theme={null}
  OneSignal.User.addSms("+15558675309");

  OneSignal.User.removeSms("+15558675309");
```

***

## Slidedown prompts

Display the various slidedown prompts on your sites. See [Web permission prompts](./permission-requests) for more details.

* If dismissed, future calls will be ignored for at least three days. Further declines will lengthen the time required to elapse before prompting the user again.
* To override back-off behavior, pass `{force: true}` to the method. However, to provide a good user experience, bind the action to a UI-initiated event like a button click.

<Warning>
  This does not replace the Native Browser Prompt required for subscription. You must obtain permissions using the native browser prompt.
</Warning>

### `promptPush()`

Displays the regular slidedown prompt for push notifications.

* If using categories, call [`promptPushCategories()`](#promptpushcategories) instead.
* Subject to backoff logic set by OneSignal. See [Web permission prompts](./permission-requests#auto-prompt-%26-display-settings) for more details.

```javascript JavaScript theme={null}
  OneSignal.Slidedown.promptPush();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPush({force: true});
```

### `promptPushCategories()`

Displays the category slidedown prompt, allowing users to update their tags. Also triggers the native notification permission prompt if the user has not already granted permission.

* If not using categories, call [`promptPush()`](#promptpush) instead.
* Subject to backoff logic set by OneSignal. See [Web permission prompts](./permission-requests#auto-prompt-%26-display-settings) for more details.

```javascript JavaScript theme={null}
  OneSignal.Slidedown.promptPushCategories();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPushCategories({force: true});
```

### `promptSms()`

Displays the SMS subscription prompt.

* Subject to backoff logic set by OneSignal. See [Web permission prompts](./permission-requests#auto-prompt-%26-display-settings) for more details.

```javascript JavaScript theme={null}
  OneSignal.Slidedown.promptSms();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSms({force: true});
```

### `promptEmail()`

Displays the email subscription prompt.

* Subject to backoff logic set by OneSignal. See [Web permission prompts](./permission-requests#auto-prompt-%26-display-settings) for more details.

```javascript JavaScript theme={null}
  OneSignal.Slidedown.promptEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptEmail({force: true});
```

### `promptSmsAndEmail()`

Displays the SMS and email subscription prompts simultaneously.

* Subject to backoff logic set by OneSignal. See [Web permission prompts](./permission-requests#auto-prompt-%26-display-settings) for more details.

```javascript JavaScript theme={null}
  OneSignal.Slidedown.promptSmsAndEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSmsAndEmail({force: true});
```

### `addEventListener()` *Slidedown*

Add a callback to detect the Slidedown prompt shown event.

```javascript JavaScript theme={null}
  OneSignalDeferred.push(function(OneSignal) {

    OneSignal.Slidedown.addEventListener('slidedownShown', function (event) {
      console.log('slidedownShown', { event });
    });

  });
```

***

## Push notifications

### `requestPermission()`

Requests push notifications permission via the native browser prompt. Subject to backoff logic set by the browser. See [Web permission prompts](./permission-requests#native-permission-prompt) for more details.

```javascript JavaScript theme={null}
  OneSignal.Notifications.requestPermission();
```

### `isPushSupported()`

Returns `true` if the current browser supports web push.

```javascript JavaScript theme={null}
  const isSupported = OneSignal.Notifications.isPushSupported();
```

### `OneSignal.Notifications.permission`

Returns a boolean indicating the site's current permission to display notifications.

* `true`: The user has granted permission to display notifications.
* `false`: The user has either denied or not yet granted permission to display notifications.

This value reflects **browser notification permission** only. It does not reflect OneSignal `optOut`, subscription ID, or push token. For those, use [`User.PushSubscription`](#user-pushsubscription-id) (and related methods below).

To listen for permission changes, use the [`permissionChange`](#permissionchange) event.

```javascript JavaScript theme={null}
  let permission = OneSignal.Notifications.permission;
```

### `addEventListener()` *Notifications*

You can hook into the notification life-cycle with `addEventListener`. Replace the first argument with an event name such as `permissionChange`, `click`, or `dismiss` (see subsections below). You can register multiple handlers per event.

To stop listening, call `removeEventListener` with the **same** event name and handler reference.

```javascript JavaScript theme={null}
  function onClick(event) {
    console.log("click", event);
  }

  OneSignal.Notifications.addEventListener("click", onClick);
  OneSignal.Notifications.removeEventListener("click", onClick);
```

#### `permissionChange`

This event occurs when the user clicks Allow or Block or dismisses the browser's native permission request.

```javascript JavaScript theme={null}
  function permissionChangeListener(permission) {
    if (permission) {
      console.log(`permission accepted!`);
    }
  }

  OneSignal.Notifications.addEventListener("permissionChange", permissionChangeListener);
```

#### `permissionPromptDisplay`

This event occurs when the browser's native permission request has just been shown.

```javascript JavaScript theme={null}
  function promptListener(event) {
    console.log("permission prompt displayed", event);
  }

  OneSignal.Notifications.addEventListener("permissionPromptDisplay", promptListener);
```

#### `click`

This event will fire when the notification's body/title or action buttons are clicked.

```javascript JavaScript theme={null}
  function clickEventListener(event) {
    console.log(`click event: ${event}`);
  }

  OneSignal.Notifications.addEventListener("click", clickEventListener);
```

#### `foregroundWillDisplay`

This event occurs before a notification is displayed. This event is fired on your page. If multiple browser tabs are open on your site, this event will be fired on *all* pages on which OneSignal is active.

```javascript JavaScript theme={null}
  function foregroundWillDisplayListener(event) {
    console.log("notification will display", event);
  }

  OneSignal.Notifications.addEventListener("foregroundWillDisplay", foregroundWillDisplayListener);
```

#### `dismiss`

This event occurs when:

* A user purposely dismisses the notification without clicking the notification body or action buttons
* On Chrome on Android, a user dismisses all web push notifications (this event will be fired for each web push notification we show)
* A notification expires on its own and disappears

<Info>
  This event *does not occur* if a user clicks on the notification body or one of the action buttons. That is considered a notification `click` event.
</Info>

```javascript JavaScript theme={null}
  function notificationDismissedListener(event) {
    console.log(`dismiss event: ${event}`);
  }

  OneSignal.Notifications.addEventListener("dismiss", notificationDismissedListener);
```

### `setDefaultUrl()`

Sets the default URL for notifications.

If you haven't set a default URL, your notification will open to the root of your site by default.

```javascript JavaScript theme={null}
  OneSignal.Notifications.setDefaultUrl("https://onesignal.com");
```

Provide a valid URL to open when the user clicks a notification that does not specify its own URL. If the notification payload includes a URL, it overrides this default.

Safari Web Push does not use `setDefaultUrl()` the same way; launch and icon behavior follow your Safari / Apple configuration (for example the Site URL in your OneSignal Safari settings). See [Web push setup](./web-push-setup) for Safari-specific steps.

### `setDefaultTitle()`

Sets the default title to display on notifications.

```javascript JavaScript theme={null}
  OneSignal.Notifications.setDefaultTitle("Powered by OneSignal!");
```

If a notification is created with a title, the specified title always overrides this default title.

A notification's title defaults to the title of the page the user last visited. If your page titles vary between pages, this inconsistency can be undesirable. Call this to standardize page titles across notifications, as long as a notification title isn't specified.

***

## Outcomes

Outcome methods are on **`OneSignal.Session`**. Use the same deferred **`OneSignal`** instance as elsewhere after `init`.

### `sendOutcome()`

Triggers an outcome which can be viewed in the OneSignal dashboard. Accepts an outcome name (`string`, required) and a value (`number`, optional). Each time `sendOutcome` method is invoked with the same outcome name passed, the outcome count will increase, and the outcome value will be increased by the amount passed in (if included). See [Custom Outcomes](./custom-outcomes) for more details.

```javascript JavaScript theme={null}
  OneSignal.Session.sendOutcome('outcome name', 19.84);
```

### `sendUniqueOutcome()`

Triggers an outcome which can be viewed in the OneSignal dashboard. Accepts only the outcome name (`string`, required). `sendUniqueOutcome` will increase the count for that outcome only once per user. See [Custom Outcomes](./custom-outcomes) for more details.

```javascript JavaScript theme={null}
  OneSignal.Session.sendUniqueOutcome('outcome name');
```

***


# Web SDK setup
Source: https://documentation.onesignal.com/docs/en/web-sdk-setup

Add OneSignal web push notifications to your website with the JavaScript SDK, service worker setup, and dashboard configuration.

<SdkReleasesIframe />

## Overview

This guide walks you through adding OneSignal web push notifications to your site — from dashboard configuration to SDK installation. OneSignal supports Chrome, Firefox, Edge, Safari, and [other major browsers](./web-push-setup-faq).

<Note>
  If you use the WordPress or Shopify integration, skip this guide and return to [WordPress setup](./wordpress) or [Shopify setup](./shopify).
</Note>

***

## Requirements

* HTTPS website: Web push does not work on HTTP or in incognito/private modes.
* Server access: You’ll need to upload a service worker file to your site.
* Single origin: Web push follows the [Same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy). If you have multiple origins (domains/subdomains), you will need multiple OneSignal apps (one per origin). To comply with this browser limitation, you can either:
  * Redirect traffic to a single origin for subscriptions.
  * Create multiple OneSignal apps—one per origin.

<Note>
  If your team already created an account with OneSignal, [ask to be invited as an admin role](./manage-team-members) so you can set up the app. Otherwise, sign up for a free account at [onesignal.com](https://onesignal.com) to get started.
</Note>

***

## Configure your OneSignal app and platform

In the OneSignal dashboard:

* Go to **Settings > Push & In-App > Web**.

<Frame>
  <img alt="OneSignal dashboard Settings page showing Web platform activation" />
</Frame>

Select integration type:

<Columns>
  <Card title="Typical Site (recommended)">
    Manage prompts and settings directly through the OneSignal dashboard without additional coding.
  </Card>

  <Card title="WordPress" href="./wordpress">
    Required if using WordPress with our official plugin.
  </Card>

  <Card title="Custom Code" href="./web-push-custom-code-setup">
    For developers who need full control over prompts and SDK configuration.
  </Card>
</Columns>

### Site setup

Add the site details:

* **Site Name**: The name of your site and default notification title.
* **Site URL**: The URL of your site. See [Site URL](#site-url) for more details.
* **Auto Resubscribe**: Enable this to automatically resubscribe users who clear their browser data when they return to your site (no new permission prompt required).
* **Default Icon URL**: Upload a square 256x256px PNG or JPG image that appears in notifications and prompts. If not set, a bell icon is used as the default.

<Frame>
  <img alt="OneSignal web push configuration showing site name, URL, and icon settings" />
</Frame>

#### Site URL

Enter the exact [origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) of your site, e.g., `https://yourdomain.com`. Avoid using `www.` if your site isn’t configured that way.

If you have multiple origins:

* Redirect to a single origin.
* Or set up one OneSignal app per origin.

#### Local testing

The web SDK can be tested on localhost environments. If you are testing on localhost, use a separate OneSignal app from your production app.

<Accordion title="Localhost configuration" icon="circle-chevron-down">
  Set the **SITE URL** to exactly match your localhost environment URL. The URL must match one of these common localhost formats:

  * `http://localhost`
  * `https://localhost:3000`
  * `http://127.0.0.1`
  * `https://127.0.0.1:5000`

  <Note>
    If your localhost is using HTTP, select **Treat HTTP localhost as HTTPS for testing**.

    Google Chrome treats `http://localhost` and `http://127.0.0.1` as secure origins, allowing HTTPS integrations even on HTTP. This is why you cannot test other non-standard origins on HTTPS localhost.
  </Note>

  <Frame>
    <img alt="OneSignal localhost configuration with Treat HTTP localhost as HTTPS option" />
  </Frame>

  #### Add `allowLocalhostAsSecureOrigin` to your OneSignal `init` options

  When initializing OneSignal on your localhost site, add `allowLocalhostAsSecureOrigin: true,` to your OneSignal `init` options.

  Additionally, if you're testing localhost on HTTPS with a self-signed certificate, you may have to ask Chrome to ignore invalid certificates for testing with: `--allow-insecure-localhost`. Firefox and Safari provide built-in mechanisms to add exceptions for security certificates.

  ```html HTML theme={null}
    <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
    <script>
      window.OneSignalDeferred = window.OneSignalDeferred || [];
      OneSignalDeferred.push(function(OneSignal) {
        OneSignal.init({
          appId: "YOUR_OS_APP_ID",
          allowLocalhostAsSecureOrigin: true,
        });
      });
    </script>
  ```
</Accordion>

### Permissions prompt

Typical site setup allows you or your team members to add, remove, and update permission prompts through the OneSignal dashboard anytime.

<Card title="Web permission prompts" icon="bell" href="./permission-requests">
  Configure when and how the browser permission dialog appears to your users.
</Card>

### Welcome notification (optional)

You can also set a welcome notification to be sent to users when they subscribe to push notifications.

To set this go to **Settings → Push & In-app → Web**:

<Frame>
  <img alt="Welcome notification configuration" />
</Frame>

For custom code setups, please see our [SDK reference guide](./web-sdk-reference#welcomenotification-parameters).

### Advanced settings

The following features are configurable in the OneSignal dashboard.

#### Webhooks

The web SDK can `POST` certain web push events to a URL of your choosing.

Web Push Webhooks are a separate implementation from [Event Webhooks](./event-streams) and cannot be used interchangeably.

<Card title="Web push webhooks" icon="webhook" href="./webhooks">
  Send web push events to your server via POST requests.
</Card>

#### Service workers

On the next page of web push configuration, you will be provided the `OneSignalSDKWorker.js` service worker file.

The web SDK looks for this file in the root of your site by default. You can change the file location, name, and scope in the settings below.

* **Path to service worker files** is the path to the directory where you will host the service worker file.
* **Main and Updater service worker filenames** defaults to `OneSignalSDKWorker.js`. You can rename this file, but it must use a `.js` extension.
* **Service worker registration scope** controls which pages the service worker can operate on. For push notifications this has no effect. Set it to the same path as your service worker file location.

<Frame>
  <img alt="Service worker path, filename, and scope configuration fields" />
</Frame>

With this example, you should see the file's code publicly accessible at `https://yourdomain.com/push/onesignal/OneSignalSDKWorker.js`

<Card title="OneSignal service worker" icon="gear" href="./onesignal-service-worker">
  Advanced service worker configuration, custom integration, and migration from other providers.
</Card>

#### Click behavior

Control how users navigate to the [URL](./links) you set when they click the notification.

If the user does not have your site open in any tab, the browser opens a new tab and navigates to the notification URL. If the user already has your site open, the behavior depends on the setting you choose:

| Setting                      | Matches on                             | Action                                                |
| ---------------------------- | -------------------------------------- | ----------------------------------------------------- |
| **Exact Navigate** (default) | Exact URL (e.g. `example.com/product`) | Navigates to the notification URL in the matching tab |
| **Origin Navigate**          | Origin (e.g. `example.com`)            | Navigates to the notification URL in the matching tab |
| **Exact Focus**              | Exact URL                              | Focuses the matching tab without refreshing           |
| **Origin Focus**             | Origin                                 | Focuses the matching tab without refreshing           |

#### Persistence

By default, web push notifications appear on the device for roughly 5 seconds before moving to the Notification Center, where they remain for about 1 week before the operating system removes them.

Some devices and versions of Chrome and Edge allow you to persist notifications on screen until the user interacts with them. **This can annoy users and is not recommended.** Enabling persistence may also reduce character count and affect how images and buttons display.

Changes to persistence settings only take effect for subscribers who visit your site after the update. If you do not see the change, wait for subscribers to revisit your site or ask them to clear their browser data.

#### Safari certificate (Optional)

OneSignal automatically provides the necessary certificates to work with Safari browsers at no additional cost. If you already have your own Safari Web Push Certificates, toggle on this option to upload your `Safari Web .p12 Push Certificate` and password.

<Frame>
  <img alt="Safari Web Push certificate upload toggle and fields" />
</Frame>

***

## Upload service worker file

Add the `OneSignalSDKWorker.js` service worker file to your site.

Download it from the OneSignal dashboard or [from GitHub](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip).

<Frame>
  <img alt="OneSignal service worker file download and setup step" />
</Frame>

Either put this file in your site's root directory or in a subdirectory. If you put it in a subdirectory, you will need to set the **Path to service worker files** in the [Advanced settings > Service workers](#service-workers) section.

Once the file is on your server, check the following to make sure it works:

<Steps>
  <Step title="Verify the location">
    Make sure the file is located in the same **Path to service worker files** as set in [Advanced settings > Service workers](#service-workers). If you did not update these settings, then you should have put the file in your root. For example:

    * `https://yourdomain.com/OneSignalSDKWorker.js`
    * `https://yourdomain.com/some-subdirectory/OneSignalSDKWorker.js`
  </Step>

  <Step title="It must be publicly accessible on your origin">
    The `OneSignalSDKWorker.js` file must be publicly accessible and available on your origin. It cannot be hosted via a CDN or placed on a different origin with redirect.

    When you visit the URL to the file, you should see the code.
  </Step>

  <Step title="It must be served with a content-type: application/javascript">
    This is a JavaScript file and must be served as such. It cannot have a content-type of text/html.
  </Step>
</Steps>

<Card title="OneSignal service worker" icon="gear" href="./onesignal-service-worker">
  Advanced configuration and migration from other web push providers.
</Card>

## Add code to your site

The JavaScript SDK code below works on any site. If your site is built with [Angular](./angular-setup), [React JS](./react-js-setup), or [Vue JS](./vue-js-setup) then follow these links.

To initialize OneSignal on your site with our JavaScript SDK, copy/paste the provided code into your website's `<head>` tags. The OneSignal dashboard provides this same snippet pre-filled with your [app ID](./keys-and-ids).

```html HTML theme={null}
  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
    window.OneSignalDeferred = window.OneSignalDeferred || [];
    OneSignalDeferred.push(async function(OneSignal) {
      await OneSignal.init({
        appId: "YOUR_ONESIGNAL_APP_ID",
      });
    });
  </script>
```

### iOS web push support

Apple started supporting web push notifications on iPhones and iPads running iOS 16.4+. Unlike Android devices where web push just "works" as long as visited on a supported browser, Apple added a few more requirements such as a `manifest.json` file and a user action to add your site to their home screen.

<Card title="iOS web push setup" icon="apple" href="./web-push-for-ios">
  Add the required `manifest.json` file and guide users to add your site to their home screen.
</Card>

***

## Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications and subscription registration.

### Check web push subscriptions

<Steps>
  <Step title="Launch your site on a test device.">
    * Use Chrome, Firefox, Edge, or Safari while testing.
    * **Do not use Incognito or private browsing mode.** Users cannot subscribe to push notifications in these modes.
    * The prompts should appear based on your [permission prompts](/docs/en/permission-requests) configuration.
    * Click **Allow** on the native prompt to subscribe to push notifications.

    <Frame>
      <img alt="Browser native permission prompt asking the user to allow or block notifications" />
    </Frame>
  </Step>

  <Step title="Check your OneSignal dashboard">
    * Go to **Audience > Subscriptions**.
    * You should see a new entry with the status **Subscribed**.

    <Frame>
      <img alt="OneSignal dashboard Subscriptions page showing a web push subscription with Subscribed status" />
    </Frame>

    <Check>You have successfully created a [web push subscription](/docs/en/subscriptions).
    Web push subscriptions are created when users first subscribe to push notifications on your site.</Check>
  </Step>
</Steps>

### Set up test users

test users are helpful for testing a push notification before sending a message.

<Steps>
  <Step title="Add to Test Users.">
    In the dashboard, next to the subscription, click the **Options (three dots)** button and select **Add to Test Users**.

    <Frame>
      <img alt="Options menu on a subscription showing the Add to test users option" />
    </Frame>
  </Step>

  <Step title="Name your subscription.">
    Name the subscription so you can easily identify your device later in the **test users tab**.
  </Step>

  <Step title="Create a test users segment.">
    Go to **Audience > Segments > New Segment**.
  </Step>

  <Step title="Name the segment.">
    Name the segment `Test Users` (the name is important because it will be used later).
  </Step>

  <Step title="Add the Test Users filter and click Create Segment.">
    <Frame>
      <img alt="Segment editor with Test Users filter selected and the segment named Test Users" />
    </Frame>

    <Check>You have successfully created a segment of test users.
    You can now test sending messages to this individual device and groups of test users.</Check>
  </Step>
</Steps>

### Send test push via API

<Steps>
  <Step title="Get your App API Key and App ID.">
    In your OneSignal dashboard, go to **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
  </Step>

  <Step title="Update the provided code.">
    Replace `YOUR_APP_API_KEY` and `YOUR_APP_ID` in the code below with your actual keys. This code uses the `Test Users` segment created earlier.

    ```curl theme={null}
    curl -X POST --url 'https://api.onesignal.com/notifications' \
      --header 'content-type: application/json; charset=utf-8' \
      --header 'authorization: Key YOUR_APP_API_KEY' \
      --data '{
        "app_id": "YOUR_APP_ID",
        "target_channel": "push",
        "name": "Testing basic setup",
        "headings": {
          "en": "👋"
        },
        "contents": {
          "en": "Hello world!"
        },
        "included_segments": [
          "Test Users"
        ],
        "chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
      }'
    ```
  </Step>

  <Step title="Run the code.">
    Run the code in your terminal.
  </Step>

  <Step title="Check images and confirmed receipt.">
    If all setup steps were completed successfully, the test users should receive a notification.

    <Warning>Only Chrome supports images. Images will appear small in the collapsed notification view. Expand the notification to see the full image.</Warning>

    <Frame>
      <img alt="Expanded Chrome push notification on macOS displaying a custom image" />
    </Frame>
  </Step>

  <Step title="Check for confirmed receipt.">
    In your dashboard, go to **Delivery > Sent Messages**, then click the message to view stats. You should see the **confirmed** stat, meaning the device received the push.

    <Note>Safari does not support confirmed receipt.</Note>

    <Card title="Push notification message reports" icon="chart-bar" href="/docs/en/push-notification-message-reports">
      View delivery, click, and conversion stats for your push notifications.
    </Card>
  </Step>
</Steps>

<Check>You have successfully sent a notification via the API to a segment.</Check>

If notifications are not arriving, contact `support@onesignal.com` with the following:

* The API request and response (copy-paste into a `.txt` file)
* Your Subscription ID
* Your website URL with the OneSignal code

***

## User identification

The previous section covered creating web push [Subscriptions](/docs/en/subscriptions). This section expands to identifying [Users](/docs/en/users) across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. It covers External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

### Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend's user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for [Integrations](/docs/en/integrations)).

Set the External ID with the SDK's [`login` method](/docs/en/web-sdk-reference#login-external-id) each time a user is identified by your app.

<Note>
  OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

  As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

  Setting the External ID via the SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
</Note>

### Add Tags

[Tags](/docs/en/add-user-data-tags) are key-value pairs of string data you can use to store user properties (like `username`, `role`, or preferences) and events (like `purchase_date`, `game_level`, or user interactions). Tags power advanced [Message Personalization](/docs/en/message-personalization) and [Segmentation](/docs/en/segmentation) allowing for more advanced use cases.

Set tags with the SDK's [`addTag` and `addTags` methods](/docs/en/web-sdk-reference#addtag-%2C-addtags) as events occur in your app.

In this example, the user reached level 6 identifiable by the tag called `current_level` set to a value of `6`.

<Frame>
  <img alt="OneSignal user profile showing a data tag named current_level with value 6" />
</Frame>

You can create a segment of users with a level between 5 and 10, then use that segment to send targeted and personalized messages:

<Frame>
  <img alt="Segment editor filtering users where current_level is greater than 4 and less than 10" />
</Frame>

<Frame>
  <img alt="Push notification composer targeting the Level 5-10 segment with a personalized message" />
</Frame>

### Add email and/or SMS subscriptions

The OneSignal SDK creates web push subscriptions automatically when users opt in. You can also reach users through email and SMS channels by creating the corresponding subscriptions.

* Use the [`addEmail` method](/docs/en/web-sdk-reference#addemail-%2C-removeemail) to create email subscriptions.
* Use the [`addSms` method](/docs/en/web-sdk-reference#addsms-%2C-removesms) to create SMS subscriptions.

If the email address or phone number already exists in the OneSignal app, the SDK adds it to the existing user. It does not create duplicates.

You can view unified users via **Audience > Users** in the dashboard or with the [View user API](/reference/view-user).

<Frame>
  <img alt="OneSignal user profile showing push, email, and SMS subscriptions linked by External ID" />
</Frame>

<Note>
  Best practices for multi-channel communication

  * Obtain explicit consent before adding email or SMS subscriptions.
  * Explain the benefits of each communication channel to users.
  * Provide channel preferences so users can select which channels they prefer.
</Note>

***

### Privacy & user consent

To control when OneSignal collects user data, use the SDK's consent gating methods:

* [`setConsentRequired(true)`](/docs/en/web-sdk-reference#setconsentrequired): Prevents data collection until consent is given.
* [`setConsentGiven(true)`](/docs/en/web-sdk-reference#setconsentgiven): Enables data collection once consent is granted.

For more on privacy and security:

<Columns>
  <Card title="Data collected by the SDK" icon="database" href="/docs/en/data-collected-by-the-onesignal-sdk">
    Review what data the OneSignal SDK collects from users.
  </Card>

  <Card title="Handling personal data" icon="shield-halved" href="/docs/en/handling-personal-data">
    Manage and protect user data in compliance with privacy regulations.
  </Card>
</Columns>

***

## Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes.

The SDK provides several event listeners you can hook into. See the [SDK reference guide](/docs/en/web-sdk-reference) for more details.

### Push notification events

* [Click event listener](/docs/en/web-sdk-reference#click): Detect when a notification is tapped.
* [Foreground lifecycle listener](/docs/en/web-sdk-reference#foregroundwilldisplay): Control how notifications behave in foreground.

### User state changes

* [User state change event listener](/docs/en/web-sdk-reference#addeventlistener-user-state): Detect when the External ID is set.
* [Permission observer](/docs/en/web-sdk-reference#permissionchange): Track the user's specific interaction with the native push permission prompt.
* [Push subscription change observer](/docs/en/web-sdk-reference#addeventlistener-push-subscription-changes): Track when the push subscription status changes.

***

## Advanced setup & capabilities

Explore more capabilities to enhance your integration:

<Columns>
  <Card title="Migrating to OneSignal" icon="rotate" href="/docs/en/migrating-to-onesignal">
    Move from another push provider to OneSignal.
  </Card>

  <Card title="Integrations" icon="plug" href="/docs/en/integrations">
    Connect OneSignal with third-party tools and platforms.
  </Card>

  <Card title="Action buttons" icon="bell" href="/docs/en/action-buttons">
    Add interactive buttons to push notifications.
  </Card>

  <Card title="Multi-language messaging" icon="globe" href="/docs/en/multi-language-messaging">
    Send localized messages to users in their preferred language.
  </Card>

  <Card title="Identity Verification" icon="shield-check" href="/docs/en/identity-verification">
    Secure your SDK integration with server-side identity verification.
  </Card>

  <Card title="Custom Outcomes" icon="chart-line" href="/docs/en/custom-outcomes">
    Track custom conversion events tied to your messages.
  </Card>
</Columns>

### Web SDK setup & reference

<Columns>
  <Card title="Web push setup" icon="gear" href="/docs/en/web-push-setup">
    Enable all key web push features for your integration.
  </Card>

  <Card title="Web SDK reference" icon="code" href="/docs/en/web-sdk-reference">
    Full details on available methods and configuration options.
  </Card>
</Columns>

<Check>Congratulations! You've successfully completed the Web SDK setup guide.</Check>

***

***

## FAQ

### Does web push work on HTTP sites?

No. Web push requires HTTPS. Browsers enforce this as a security requirement. The only exception is `localhost` and `127.0.0.1`, which browsers treat as secure origins for development purposes.

### Why do I need a service worker file?

The service worker runs in the background and handles incoming push notifications even when the user does not have your site open. Without it, the browser cannot display notifications. The `OneSignalSDKWorker.js` file must be publicly accessible on your origin.

### Can I use web push on iOS (iPhone/iPad)?

Yes, starting with iOS 16.4+. However, Apple requires a `manifest.json` file and the user must add your site to their home screen first. See [iOS web push setup](./web-push-for-ios) for the full requirements.

### Why are my notifications not showing?

Common causes include an incorrectly placed service worker file, a mismatched Site URL in the dashboard, or the user having notifications blocked in their browser settings. See [Notifications not shown or delayed](./notifications-show-successful-but-are-not-being-shown) for a full troubleshooting checklist.

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***


# Web push webhooks
Source: https://documentation.onesignal.com/docs/en/webhooks

Set up HTTP webhooks to receive real-time notifications when users display, click, or dismiss web push notifications. Complete guide with examples for Chrome, Firefox, and Safari browser support.

## Overview

Web Push Webhooks allow you to receive real-time HTTP POST notifications whenever users interact with your push notifications. When a notification is displayed, clicked, or dismissed, OneSignal automatically sends the notification data and any custom parameters to your specified webhook URL.

<Warning>
  For Journey webhooks, see our [Journey webhooks](./journeys-webhook) page.
</Warning>

**Key Benefits:**

* Track notification engagement in real-time
* Trigger automated workflows based on user interactions
* Sync notification data with your analytics platform
* Implement custom business logic for notification events

## Browser Support

| Browser | Platform Support        | Webhook Events Available             |
| ------- | ----------------------- | ------------------------------------ |
| Chrome  | macOS, Windows, Android | All events (display, click, dismiss) |
| Firefox | macOS, Windows, Android | Display and click events             |
| Safari  | Not supported           | None                                 |

## Available Webhook Events

### notification.willDisplay

Triggered immediately after a notification appears on the user's screen.

**Use cases:** Track delivery rates, log impression data, trigger follow-up campaigns

### notification.clicked

Triggered when a user clicks on the notification body or any action button.

**Use cases:** Track engagement rates, trigger conversion events, redirect users to specific content

### notification.dismissed

Triggered when a user actively dismisses a notification or when it expires automatically.

**Browser support:** Chrome only
**Use cases:** Track dismissal rates, optimize notification timing, A/B test notification content

**Important:** Clicking the notification body or action buttons does NOT trigger the dismissed webhook.

## Setup Methods

<Tabs>
  <Tab title="Dashboard Configuration (Recommended for Most Users)">
    <Steps>
      <Step>
        Navigate to **Settings > Web** in your OneSignal dashboard
      </Step>

      <Step>
        Enable the "Enable webhooks" toggle
      </Step>

      <Step>
        Enter your webhook URLs for each event you want to track
      </Step>
    </Steps>

    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="Custom Code Integration">
    Add webhook configuration to your existing `OneSignal.init()` method:

    ```javascript theme={null}
    // Add to your existing OneSignal initialization - do NOT call init twice
    OneSignal.init({
      // Your other existing settings here
      webhooks: {
        cors: false, // Recommended: leave as false unless you need custom headers
        'notification.willDisplay': 'https://yoursite.com/webhook/display',
        'notification.clicked': 'https://yoursite.com/webhook/click',
        'notification.dismissed': 'https://yoursite.com/webhook/dismiss' // Chrome only
      }
    });
    ```
  </Tab>
</Tabs>

<Info>Make sure your webhook URLs are HTTPS (required by Chrome's security policies).</Info>

## CORS Configuration

The `cors` setting determines what headers and data your webhook endpoint receives:

* **`cors: false` (Recommended):** Simpler setup, no CORS configuration needed on your server
* **`cors: true`:** Provides additional headers but requires CORS support on your server

**When to use `cors: true`:**

* You need the `Content-Type: application/json` header
* You want the `X-OneSignal-Event` header for easier event identification
* Your server already supports CORS for non-simple requests

## Webhook Request Format

### Standard Request (cors: false)

Your webhook endpoint receives a POST request with this payload structure:

```json theme={null}
{
  "event": "notification.clicked",
  "notificationId": "ed46884e-0e3f-4373-9e11-e28f27746d3d",
  "heading": "Your notification title",
  "content": "Your notification message",
  "additionalData": {
    "userId": "12345",
    "campaignId": "summer-sale",
    "customField": "customValue"
  },
  "actionId": "buy-now-button",
  "url": "https://yoursite.com/product/123"
}
```

### Enhanced Request (cors: true)

Same payload as above, plus these additional headers:

```http theme={null}
Content-Type: application/json
X-OneSignal-Event: notification.clicked
```

## Payload Field Reference

| Field            | Type   | Description                                                            | Always Present    |
| ---------------- | ------ | ---------------------------------------------------------------------- | ----------------- |
| `event`          | string | Event type that triggered the webhook                                  | ✅                 |
| `notificationId` | string | Unique OneSignal notification identifier                               | ✅                 |
| `heading`        | string | Notification title                                                     | Only if provided  |
| `content`        | string | Notification message body                                              | Only if provided  |
| `additionalData` | object | Custom data sent with notification                                     | Only if provided  |
| `actionId`       | string | ID of clicked action button (empty string = notification body clicked) | Click events only |
| `url`            | string | Launch URL for the notification                                        | Only if provided  |
| `subscriptionId` | string | OneSignal user/subscription ID                                         | CORS enabled only |

## Implementation Best Practices

### Webhook Endpoint Requirements

**Security:**

* Use HTTPS URLs only (HTTP URLs will be blocked by Chrome)
* Implement proper authentication/validation for your webhook endpoints
* Consider rate limiting to handle high-volume notifications

**Response Requirements:**

* Return HTTP 200 status for successful processing
* Respond within 10 seconds to avoid timeouts
* Handle duplicate webhook calls gracefully (implement idempotency)

### Error Handling

```javascript theme={null}
// Example webhook endpoint (Node.js/Express)
app.post('/webhook/notification', (req, res) => {
  try {
    const { event, notificationId, additionalData } = req.body;

    // Validate required fields
    if (!event || !notificationId) {
      return res.status(400).json({ error: 'Missing required fields' });
    }

    // Process the webhook data
    processNotificationEvent(req.body);

    // Always respond with 200 OK
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});
```

## Common Issues and Solutions

### Webhooks Not Firing

**Possible causes:**

* Webhook code not present on all pages with OneSignal initialization
* User hasn't visited a page with webhook code after it was added
* HTTPS requirement not met
* Server returning non-200 status codes

**Solution:** Ensure webhook configuration is included in your OneSignal init code on all pages where notifications are active.

### Missing Data in Webhooks

**Cause:** Webhooks only track events for users who visit pages with the webhook configuration active.

**Solution:** Deploy webhook code to all pages with OneSignal, not just specific landing pages.

### Duplicate Webhook Calls

**Cause:** Network issues or browser behavior may cause duplicate requests.

**Solution:** Implement idempotency using the `notificationId` field to deduplicate events.

## Webhook Limitations

* **One webhook URL per event:** You cannot set multiple webhook URLs for the same event type
* **HTTPS only:** HTTP URLs will not work due to browser security restrictions
* **Chrome-only dismissal tracking:** The `notification.dismissed` event only works in Chrome
* **Page dependency:** Users must visit pages with webhook code active for tracking to work

## Testing Your Webhooks

1. **Send a test notification** through your OneSignal dashboard
2. **Monitor your webhook endpoint** for incoming requests
3. **Verify payload structure** matches your expectations
4. **Test different scenarios:**
   * Notification display
   * Clicking notification body
   * Clicking action buttons (if configured)
   * Dismissing notifications (Chrome only)

## Next Steps

After setting up webhooks, consider:

* **Analytics Integration:** Forward webhook data to your analytics platform
* **User Segmentation:** Use webhook events to create user segments based on engagement
* **Automated Workflows:** Trigger email campaigns or app notifications based on push notification interactions
* **A/B Testing:** Use webhook data to measure the effectiveness of different notification strategies


# Welcome Journey: Mobile gaming
Source: https://documentation.onesignal.com/docs/en/welcome-journey-mobile-gaming

Build an automated onboarding flow that drives new players to their first meaningful in-game action — from minimal data setup to fully event-driven personalization.

This playbook implements the [Gaming strategies](./gaming-industry) hub as a 7-day onboarding Journey. Both cases share the same goal: get players to their first meaningful in-game action fast, build a play habit, and reduce early churn. The difference is how much player data you have available.

* **Case 1 – Basic:** You only have data collected automatically by the OneSignal SDK, such as `First Session` and `Last Session`. Messages are time-based, with no event tracking required.
* **Case 2 – Advanced:** You have Custom Events and Tags from gameplay. Messages are behavior-driven and personalized per player.

You can start with the Basic path and layer in Advanced data integrations as your implementation matures.

***

## At a glance

Setup is the same for both cases. The only difference is the daily decision step.

1. Define the [entry, exit, and recent-activity segments](#segments).
2. Build the [push, email, and in-app message templates](#templates).
3. Configure [Journey entry, exit, and re-entry rules](#journey-settings).
4. Wire up [Day 1](#day-1) — the same in both cases: email → IAM → Time Window → push.
5. Repeat the daily pattern for Days 2 through 7, then add the [Day 7 closing email](#day-7).
   * **Case 1:** [Wait + Time Window + Yes/No + Push](#day-2).
   * **Case 2:** [Wait Until + Time Window + Push (expiration branch)](#days-26).

***

## Onboarding goals

| Goal                              | Description                                                                                        |
| --------------------------------- | -------------------------------------------------------------------------------------------------- |
| Reach the first meaningful action | Tutorial completion, first win, first level completed, or any first meaningful in-game achievement |
| Drive account completion          | Profile setup, avatar creation, linking accounts                                                   |
| Build a play habit                | Establish regular sessions within the first 7 days                                                 |
| Encourage social connections      | Friends, guilds, clans, co-op play                                                                 |
| Reduce early churn (Day 1, 3, 7)  | Re-engage players who haven't returned within their first week                                     |

## Prerequisites

Work through the [Gaming strategies implementation roadmap](./gaming-industry#implementation-roadmap) before building this Journey. The strategy page defines the data foundation; this page implements one specific Journey on top of it.

**Required:**

* Familiarity with [Journeys](./journeys-overview) concepts (entry/exit rules, message and action steps, etc.).
* An active OneSignal app with the [mobile SDK](./mobile-sdk-setup) installed.
* Push permissions enabled by the player. This Journey relies on push notifications to re-engage players, so prompt for permission early — for example, after a tutorial or during an onboarding sequence.
* **Case 2 only:** a `daily_session` Custom Event — see [Custom Events](./gaming-industry#custom-events) on the strategy hub and [Required data](#required-data) below.

**Recommended:**

* A standalone push permission IAM. See [Prompt for push permission with in-app messages](./prompt-for-push-permissions) for how to configure an IAM with a **Push Permission Prompt** click action.
* **Case 2 only:** a `player_name` Tag for per-player personalization in the shared templates — see [Tags](./gaming-industry#tags) on the strategy hub.

### Segments

**Entry segment:**

* Name: "New Players First Day Inactivity"
* Filters: **First session** less than `1` day ago **AND** **Last session** greater than `4` hours ago.

A player matches this segment the moment they cross the 4-hour inactivity threshold within their first day of opening the app — exactly when the Day 1 re-engagement push should fire.

<Info>
  **Why 4 hours of inactivity?**

  Four hours is long enough to avoid feeling needy — many players close the app between sessions and come back later the same day — but short enough that the game is still fresh in their mind. It's a strong default, not a magic number: casual puzzle games may prefer a shorter window (2 hours), while RPGs or strategy games may warrant longer (6–8 hours). To test alternatives, clone the Journey with a different segment threshold and compare Day 2 return rates.
</Info>

**Exit segment:**

* Name: "Players who have not returned in 1 week"
* Filters: **Last session** greater than `1` week ago.

A player matches this segment the moment they have not returned to the game in over a week. At that point, they exit the welcome Journey and will be tagged for a separate winback Journey.

**Recent activity check:**

* Name: "Players active in the last 12 hours"
* Filters: **Last session** less than `12` hours ago.

Case 1's Yes/No branch on each daily step uses this segment to skip the push if the player has already played and likely claimed today's reward. Twelve hours is a deliberate compromise. Pushes fire between 6 PM and 10 PM, so the segment is evaluated somewhere in that window — a longer lookback (e.g., 18+ hours) would count *yesterday's* evening session as "recent activity" and skip the push for a player who hasn't actually returned today.

### Templates

These templates are starting points — clone, edit, and re-use them in your own Journey. They use [Liquid syntax](./using-liquid-syntax) for personalization.

<Tabs>
  <Tab title="Push Notification templates">
    | Day | Name           | Title                             | Message                                                                                                     |
    | :-: | -------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
    |  1  | Day 1 — Reward | 🎁 Your Day 1 loot drop is ready  | Jump in and claim it, `{{ player_name \| default: 'hero' }}`. Your adventure starts now!                    |
    |  2  | Day 2 — Reward | ⚡ Day 2 rewards unlocked          | Keep the momentum, `{{ player_name \| default: 'hero' }}` — grab your loot before it vanishes!              |
    |  3  | Day 3 — Reward | ⚔️ Day 3 loot is incoming         | Sharpen your blades, `{{ player_name \| default: 'hero' }}` — your reward is waiting in-game!               |
    |  4  | Day 4 — Reward | 📜 New quests just dropped        | Your Day 4 reward includes rare crafting materials. Tap now to collect!                                     |
    |  5  | Day 5 — Reward | 💎 A rare treasure chest awaits   | Day 5 loot is inside, `{{ player_name \| default: 'hero' }}`. Open it before the timer runs out!            |
    |  6  | Day 6 — Reward | 🔥 One more day to Veteran status | You're almost there, `{{ player_name \| default: 'hero' }}`. Log in today to lock in tomorrow's reward!     |
    |  7  | Day 7 — Reward | 🏆 You've hit Veteran status      | Claim your 7-day reward, `{{ player_name \| default: 'hero' }}` — you've made it through the toughest week. |

    <Columns>
      <Card title="Templates" icon="clone" href="./templates">
        Create and manage reusable message templates.
      </Card>

      <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
        Overview of all personalization options available in OneSignal.
      </Card>

      <Card title="Deep linking" icon="arrow-up-right-from-square" href="./deep-linking">
        Route users to the correct page.
      </Card>
    </Columns>
  </Tab>

  <Tab title="Email templates">
    Emails carry the long-form moments of the Journey. Two emails fire — one on Day 1 and one on Day 7 — and each plays a distinct role. See [Email messaging](./email-messaging) for setup.

    **Day 1 — Welcome and push opt-in**

    *Purpose:* Thank the player for downloading, reinforce what the game offers, and open paths to push opt-in and community.

    *Suggested subject:* Welcome aboard, `{{ player_name | default: 'hero' }}`

    *Content outline:*

    * A short welcome and thank-you for downloading.
    * 2–3 things the player can do next — claim their starter pack, customize their character, pick a class, or join a guild.
    * A **turn-on-notifications** CTA that deep-links to an in-app **preference center** or notification settings screen. This lets the player enable push and manage email preferences in one place without a fresh OS prompt.
    * Links to the game's social and community channels (Discord, X, Reddit, YouTube) so they can follow along outside the app.

    **Day 7 — Leaderboard and community recap**

    The milestone email at the end of the Journey. Where the Day 1 email welcomes the player into the game, this email welcomes them into the community.

    *Purpose:* Shift the player's mindset from "a game I'm trying" to "a community I'm part of" — the transition that drives retention past Day 7.

    *Suggested subject:* Where do you rank, `{{ player_name | default: 'hero' }}`?

    *Content outline:*

    * A first-week recap — high-level milestones or stats, personalized via Tags or Liquid if you've captured them.
    * A **weekly leaderboard** snapshot (top 10 or the player's current rank) to seed competitive motivation.
    * A guild-join CTA for players not yet in a guild.
    * Social share buttons — one-tap share of a highlight or milestone to the player's social accounts.
    * A teaser for what's next: the Day 14 reward, upcoming events, or a seasonal content drop.

    <Columns>
      <Card title="Templates" icon="clone" href="./templates">
        Create and manage reusable message templates.
      </Card>

      <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
        Overview of all personalization options available in OneSignal.
      </Card>

      <Card title="Deep linking" icon="arrow-up-right-from-square" href="./deep-linking">
        Route users to the correct page.
      </Card>
    </Columns>
  </Tab>

  <Tab title="In-App Message templates">
    In-app messages fire when the player returns to the app. All are optional but high-leverage — setup completion, new-player conversion, and social bonds.

    **Day 1 — Onboarding carousel**

    Use a carousel to create a multi-card onboarding flow that funnels new players into two critical setup steps:

    1. Profile completion
    2. Push opt-in

    Players who finish both are dramatically more likely to stick: profile investment creates sunk-cost attachment, and without push opt-in, the rest of this Journey can't reach the player.

    <Info>
      Using in-app messages with a Push Permission Prompt will not show if the player has already granted push permission.
    </Info>

    **Day 3 — New-player loot box**

    Promote a one-time new-user bundle to convert first-week curiosity into commitment. Day 3 is the tipping point between "trying the game" and "playing the game" — a generous exclusive offer lands when players are most receptive:

    1. A bundle with premium currency, rare gear, and a booster pack
    2. A 24-hour countdown to create urgency
    3. A deep link to the store's new-user offer for a one-tap claim

    Gate redemption on the backend (one claim per player) so the IAM can safely retarget players who saw it but didn't convert. Target the IAM at *Tag `claimed_new_user_offer` is `false`* so redeemers don't see the offer again.

    **Day 6 — Social connections**

    Encourage social connections by prompting players to join a clan, invite friends, or unlock co-op play. Make sure to reward players who complete these actions!

    <Columns>
      <Card title="Design your in-app message" icon="pen-ruler" href="./design-your-in-app-message">
        Full reference for the in-app message editor, blocks, and Carousel.
      </Card>

      <Card title="Message personalization" icon="wand-magic-sparkles" href="./message-personalization">
        Overview of all personalization options available in OneSignal.
      </Card>

      <Card title="Deep linking" icon="arrow-up-right-from-square" href="./deep-linking">
        Route users to the correct page.
      </Card>
    </Columns>
  </Tab>
</Tabs>

## Journey configuration

Both cases share the same segments, message templates, and Journey settings. Define them once and reference them from either case.

### Journey settings

**Entry rules:**

* Audience Segment: "New Players First Day Inactivity"
* Future additions only: **Checked** — this must stay checked so existing users aren't bulk-enrolled the moment the Journey is saved.

**Exit rules:**

* Meet a certain condition: check **Exit when a user enters a segment**.
  * Segment: "Players who have not returned in 1 week"
* Tag users when they exit early: `completed_welcome_journey:false`
  * Identifies players who stopped returning before completing the Journey. Use it as the entry filter for a downstream winback Journey so stalled players get a dedicated "we miss you" flow rather than more onboarding messages.

**Re-entry rules:** No — the player can receive this Journey only once.

***

## Case 1: Basic onboarding journey

This Journey uses time-based delays and session filters — a "set it and forget it" onboarding flow that covers the critical first-week re-engagement window with minimal data requirements.

### Daily timing: Wait + Time Window

This Journey uses two Journey actions together to deliver a daily re-engagement push during the player's most likely play window:

1. **[Wait](./journeys-actions#wait):** A fixed delay between messages.
2. **[Time Window](./journeys-actions#time-window):** A delivery window every day between 6 PM and 10 PM in the player's local timezone. Every push is held until the window opens.

**Why a 6 PM – 10 PM window?**

Mobile gaming engagement peaks in the evening across genres. Morning pushes compete with email and social notifications during the "inbox sweep" most people do on their commute, and they get swiped away. A 6 PM – 10 PM window targets peak intent. Adjust this based on your audience — kids' games may skew earlier, competitive games may skew later — but evening is the right default for most games.

**Why not just use a 24-hour Wait?**

A plain 24-hour Wait would send pushes at essentially random times around the clock — whenever the player's Day 1 push happened to fire. Some players would get 3 AM pushes, others would get lunchtime pushes. Pairing a short Wait with a Time Window lets the Time Window control the actual delivery time, so every push lands between 6 PM and 10 PM regardless of when the Wait expires.

Set the Wait to the **Time Window duration + a 2-hour buffer**. For a 4-hour window (6 PM – 10 PM), the Wait is **6 hours**. The buffer guarantees the Wait always expires *after* the window closes, so the next push is held for the following day's window rather than sending again the same day:

| Day 1 push fires at | + 6h Wait expires at | Inside 6 PM – 10 PM?           | Next push |
| ------------------- | -------------------- | ------------------------------ | --------- |
| 6 PM (earliest)     | 12 AM                | No → holds until 6 PM next day | Day 2 ✓   |
| 8 PM                | 2 AM                 | No → holds until 6 PM next day | Day 2 ✓   |
| 10 PM (latest)      | 4 AM                 | No → holds until 6 PM next day | Day 2 ✓   |

Without the buffer — say, a 4-hour Wait that exactly matches the window — a 6 PM push would expire at 10 PM the same day, still inside the window, and send the Day 2 push the same night.

<Tip>
  The Time Window uses a randomization algorithm to distribute users through the allowed hours. If a lot of users are waiting to enter the window at the same time, they won't all receive a push at 6 PM sharp — OneSignal will spread them out to avoid a thundering herd of message sends.
</Tip>

### Basic Journey steps

#### Day 1

<Steps>
  <Step title="Email: Day 1 — Welcome and push opt-in">
    **Goal:** Open the Journey with an appreciative, welcoming, community-focused email that also drives push opt-in.

    Because this is the first *message* step, the email lands 4 hours after the player's first session ends (per the entry segment) rather than immediately on install — less needy, less transactional. The email's push opt-in CTA also catches players who declined the install-time permission prompt, deep-linking them to the in-app preference center.
  </Step>

  <Step title="In-App Message: Day 1 — Onboarding carousel">
    **Goal:** Get players to complete their profile and turn on push notifications.

    <Warning>
      Using in-app messages with a Push Permission Prompt will not show if the player has already granted push permission.

      Make sure this in-app message doesn't overlap with other [push permission prompt strategies](./prompt-for-push-permissions) as discussed in [Prerequisites](#prerequisites).

      It is better to remove the push permission prompt from this in-app message than to have both trigger at the same time.
    </Warning>
  </Step>

  <Step title="Time Window: 6 PM – 10 PM">
    **Goal:** Prevent the Day 1 push from firing outside the evening play window.

    The entry segment triggers whenever the 4-hour inactivity threshold is crossed — including overnight or early morning. Without this step, a player who stopped playing at 2 AM would otherwise receive the Day 1 push at 6 AM. This Time Window holds the push until 6 PM in the player's timezone.
  </Step>

  <Step title="Push Notification: Day 1 — Reward">
    **Goal:** Drive a second session on Day 1 while the player is still engaged.
  </Step>
</Steps>

#### Day 2

<Steps>
  <Step title="Wait: 6 hours">
    **Goal:** Push the next Time Window evaluation past 10 PM so the window snaps to the next day rather than re-firing the same evening. See [Daily timing](#daily-timing-wait--time-window) for the math.
  </Step>

  <Step title="Time Window: 6 PM – 10 PM">
    **Goal:** Hold the next push until the evening play window.
  </Step>

  <Step title="Yes/No branch: Players active in the last 12 hours">
    **Goal:** Skip the push if the player has already returned to claim their reward.

    **Setup:** Segment membership: "Players active in the last 12 hours"

    This creates 2 branches:

    * **Yes:** Player has been active within the last 12 hours → skip the push and continue to the next day's Wait step.
    * **No:** Player hasn't returned → send the Day 2 — Reward push.
  </Step>

  <Step title="Push Notification: Day 2 — Reward">
    **Goal:** Bring the player back to claim the next reward.

    Add this to the **No** branch of the previous step.
  </Step>
</Steps>

Once you set this up, you should have a Journey that looks like this:

<Frame>
  <img alt="Day 1 and Day 2 of the Case 1 Journey: email, in-app message, Time Window, push, then a 6-hour Wait, Time Window, Yes/No branch, and Day 2 push on the No branch." />
</Frame>

#### Days 3–6

Each of these days repeats the Day 2 pattern:

* **Wait 6 hours**
* **Time Window 6 PM – 10 PM**
* **Yes/No branch:** Players active in the last 12 hours
* **Push notification** on the **No** branch.

Insert the **Day 3** and **Day 6** IAM steps *before* the corresponding day's 6-hour Wait (the first step of that day's pattern) so the IAM is queued and ready to display the next time the player opens the app.

<Frame>
  <img alt="Days 3 through 6 pattern: an in-app message step queued before the daily Wait, Time Window, Yes/No branch, and reward push on the No branch." />
</Frame>

#### Day 7

Day 7 follows the same four-step pattern as Days 3–6 and adds a closing email after the branches converge:

<Steps>
  <Step title="Wait + Time Window + Yes/No + Push">
    Same shape as Days 2–6: a 6-hour Wait, a 6 PM – 10 PM Time Window, the Yes/No branch on *Players active in the last 12 hours*, and the **Day 7 — Reward** push on the **No** branch.
  </Step>

  <Step title="Email: Day 7 — Leaderboard and community recap">
    Add this email step *after* the Yes/No branch's two paths converge — not on either branch. Placing it after convergence means active and inactive players both receive the milestone email, regardless of whether they took the Day 7 push.
  </Step>
</Steps>

<Frame>
  <img alt="Day 7 closing: the standard four-step pattern ending in the Day 7 reward push, followed by the Day 7 leaderboard email after the Yes/No branch's two paths converge." />
</Frame>

### Best practices for Case 1

* **Run the push permission prompt outside the Journey.** Configure it as a standalone [push permission prompt IAM](./prompt-for-push-permissions) so first-session players see it before they ever enter the Journey.
* **Route long-silent players to winback via the exit rule.** The 1-week exit rule sets `completed_welcome_journey:false` so stalled players land in a dedicated winback Journey rather than cycling through more reward reminders. A shorter threshold (for example 48 hours) would exit players *before* Day 3 and Day 7 — the exact messages designed for silent players — and defeat the Journey's purpose.
* **Skip the push if the player was recently active.** The Yes/No branch on the *Players active in the last 12 hours* segment prevents sending a "claim your reward" push to a player who has already come back and likely claimed it. Without this gate, you risk layering a redundant reminder on top of an in-app notification they've already seen.
* **Bookend the Journey with email.** The Day 1 welcome email opens with a community-focused touchpoint that also catches players who declined the install-time push prompt; the Day 7 leaderboard email closes by transitioning the player from onboarding into the community. Both reach players regardless of push opt-in state.
* **Frame messages as reward reminders, not streak claims.** Case 1 has no way to verify whether the player actually returned, so claiming a "3-day streak" to someone who hasn't opened the app since Day 1 feels dishonest. Stick to "your Day N reward is ready" — it's honest and just as motivating. For real streak tracking, see Case 2.
* **Deep-link every push to the reward claim screen.** Tapping a push should land the player on the exact reward screen, not the app home. Deep linking removes friction and materially improves tap-through to claim rates. See [Deep linking](./deep-linking).

***

## Case 2: Advanced onboarding journey

Case 2 is structurally identical to Case 1 — same entry segment, exit rule, templates, Day 1 setup, and Day 3/6 IAMs. The only change is from Day 2 onward: replace Case 1's **Wait** and **Yes/No branch** with a single [Wait Until](./journeys-actions#wait-until) node that listens for a `daily_session` Custom Event. The Time Window stays.

This swaps a time-based heuristic ("did the player return in the last 12 hours?") for a behavioral fact ("did the player actually return?"). Players who return on their own take the event branch and continue silently — no push lands on top of an active session.

### Required data

| Type         | Name            | Description                                                                                                                                                                                                 |
| ------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Custom Event | `daily_session` | Fire on app open, deduped to **once per calendar day** in the player's timezone. The dedupe is critical — without it, same-day return events would advance the Journey through subsequent days too quickly. |
| Tag (string) | `player_name`   | *Recommended.* Player's display name. The shared templates already use `{{ player_name \| default: 'hero' }}`, so this Tag activates per-player personalization. Without it, every player sees `hero`.      |

See [Custom Events](./gaming-industry#custom-events) and [Tags](./gaming-industry#tags) on the [Gaming strategies](./gaming-industry) hub for the full data foundation, or [Custom Events](./custom-events) and [Tags](./add-user-data-tags) for the canonical reference docs.

### Advanced Journey steps

#### Day 1

Identical to Case 1. See [Case 1's Day 1](#day-1) for the full step list.

#### Days 2–6

Days 2 through 6 share a single pattern. Each day uses a Wait Until node in place of Case 1's Wait + Yes/No combo. The Time Window and the day's push move onto the expiration branch; the event branch stays silent.

<Steps>
  <Step title="Wait Until: daily_session">
    **Condition:** the `daily_session` Custom Event fires.
    **Expiration:** **22 hours**.

    * **Event branch** — player returned on their own. Continue silently; no push.
    * **Expiration branch** — player didn't return in 22 hours. Continue to the next two steps.

    <Tip>
      **Optional: Scope each Wait Until to a specific day with an event property.** Fire `daily_session` with a property like `day` that increments per session day (`1`, `2`, `3`, ...). Each day's Wait Until then matches on the property's value — Day 2's Wait Until catches `daily_session` where `day = 2`, Day 3's catches `daily_session` where `day = 3`, and so on.

      This guarantees a late-arriving or replayed event from an earlier day can't satisfy a later day's Wait Until, and gives you cleaner per-day funnel analytics. See [Event Matching](./journeys-actions#event-matching) for the property-matching configuration.
    </Tip>
  </Step>

  <Step title="Time Window: 6 PM – 10 PM (expiration branch only)">
    On the expiration branch, hold the player until the next 6 PM – 10 PM window in their timezone. This is the same Time Window pattern Case 1 uses, kept here so the push always lands in the evening regardless of when the Wait Until expired.
  </Step>

  <Step title="Push: day's reward template (expiration branch only)">
    Send the day's reward push (`push_day_2` through `push_day_6`).

    After this step, both branches converge and continue to the next day's Wait Until.
  </Step>
</Steps>

**Why 22 hours.** The expiration window has two jobs: give the returning player enough time to fire `daily_session`, and keep each day's push aligned with its intended calendar day. A much longer expiration (say, 30 hours) would push "Day 2's reward" into Day 3 territory; much shorter (say, 12 hours) would expire while many players are still asleep and miss return signals. 22 hours is tuned for Day 1 → Day 2: a Day 1 push at 8 PM expires at \~6 PM Day 2, right at the start of the next window.

For Day 3 onward, the timing self-stabilizes. Whether a day ends on the event branch (silent) or expiration branch (push at 6–10 PM), the next Wait Until starts in the evening, and 22 hours from there lands the next expiration in the late-afternoon-to-evening band — well-positioned for the next Time Window.

<Info>
  **Late-night edge case.** If `daily_session` fires very late (e.g., 11 PM Day 1), the next Wait Until starts at 11 PM and could expire as late as 9 PM Day 2, after the window has already opened. The player still gets the push that evening, but closer to the 10 PM cutoff. If most of your players are night owls, shorten the expiration to 18–20 hours.
</Info>

**Quick timing scenario (Day 2).**

* Day 1 push fires at 8 PM. Wait Until starts.
* *Player returns:* opens the app at 9 AM Day 2 → `daily_session` fires → event branch → silent. Day 3's Wait Until starts immediately.
* *Player doesn't return:* Wait Until expires at 6 PM Day 2 → Time Window holds until 6 PM (no-op, already inside) → push fires at 6 PM Day 2 → Day 3's Wait Until starts.

**IAM placement.** Insert the **Day 3** and **Day 6** IAM steps *before* their corresponding day's Wait Until node, so the IAM is queued and ready to display the next time the player opens the app.

#### Day 7

Day 7 follows the same Wait Until pattern as Days 2–6 and adds a closing email after the branches converge:

<Steps>
  <Step title="Wait Until + Time Window + Push (expiration branch)">
    Same shape as [Days 2–6](#days-26): a Wait Until on `daily_session` with a 22-hour expiration, then the Time Window and `push_day_7` on the expiration branch. The event branch stays silent.
  </Step>

  <Step title="Email: Day 7 — Leaderboard and community recap">
    Add this email step *after* both branches converge — not on either branch. Active and inactive players both receive the milestone email, regardless of whether the push fired.
  </Step>
</Steps>

### Best practices for Case 2

* **All Case 1 best practices still apply.** Push prompt outside the Journey, reward-focused copy, deep linking, bookend email on Day 1/7. Case 2 adds behavioral precision on top — it doesn't replace the fundamentals.
* **Dedupe `daily_session` on the client.** Fire it exactly once per calendar day in the player's timezone so the Wait Until evaluates predictably.
* **Keep the event branch silent.** Don't add a push or email on the event branch. The player is already in the app; the IAM steps that follow handle any in-app nudging.
* **Use `reward_claimed` for a stronger signal.** If your game has an explicit "Claim" action for daily rewards, fire a `reward_claimed` Custom Event and swap it in for `daily_session`. The event branch then triggers only when the player actually completed the intended action. See [`reward_claimed` in the Gaming strategies hub](./gaming-industry#custom-events).
* **Scope each Wait Until with an event property.** Fire `daily_session` (or `reward_claimed`) with a `day` property that increments per session day, then have each day's Wait Until match the corresponding value. Prevents late or replayed events from earlier days from satisfying a later day's Wait Until and produces cleaner per-day analytics. See [Event Matching](./journeys-actions#event-matching).
* **Sync to your backend (optional).** Add a [Webhook](./journeys-webhook) step on the event branch to notify your backend that the player returned, decoupling reward granting from the Journey's messaging role.

<Columns>
  <Card title="Custom Events" icon="bolt" href="./custom-events">
    Behavioral foundation of Case 2 — track daily sessions, reward claims, and other key moments.
  </Card>

  <Card title="Wait Until action" icon="hourglass" href="./journeys-actions#wait-until">
    Reference for event/expiration branches and condition setup.
  </Card>
</Columns>

***

## Compare Case 1 and Case 2

Both cases share the same entry segment, 1-week exit rule, templates, IAMs, and Day 1 + Day 7 email — all defined once in [Journey segments](#segments), [Journey templates](#templates), and [Journey settings](#journey-settings). Case 2 only changes the daily decision step.

|                                 | Case 1: Basic                                                                                                                                                                           | Case 2: Advanced                                                                                                                        |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Data required**               | Auto-tracked session data only                                                                                                                                                          | `daily_session` Custom Event (+ `player_name` Tag for personalization)                                                                  |
| **Setup effort**                | Low — no SDK instrumentation                                                                                                                                                            | Medium — one Custom Event + one Tag                                                                                                     |
| **Daily decision**              | [Wait](./journeys-actions#wait) + [Time Window](./journeys-actions#time-window) + [Yes/No branch](./journeys-actions#yesno-branch) on the *Players active in the last 12 hours* segment | [Wait Until](./journeys-actions#wait-until) on `daily_session` + [Time Window](./journeys-actions#time-window) on the expiration branch |
| **Push trigger**                | Sends unless the player was active in the last 12 hours (heuristic)                                                                                                                     | Sends only if the player didn't fire `daily_session` in the expiration window (behavioral)                                              |
| **Returning-player experience** | May receive a redundant push if the activity heuristic misses                                                                                                                           | Silent event branch — never piled on top of an in-app session                                                                           |
| **Personalization**             | Templates use `{{ player_name \| default: 'hero' }}` and fall back to `hero`                                                                                                            | Same templates personalize per player once `player_name` is set                                                                         |
| **Optional extensions**         | Add SMS or email steps for non-push-opt-in players                                                                                                                                      | `reward_claimed` swap for a stronger behavioral signal, backend [Webhook](./journeys-webhook) sync on the event branch                  |
| **Best for**                    | New apps, small teams, MVPs — ship in a week                                                                                                                                            | Teams with Custom Event instrumentation already in place                                                                                |

***

## Where to go from here

Start with Case 1 if you're setting up lifecycle messaging for the first time — it covers the onboarding window with minimal data requirements. As you add Custom Event and Tag instrumentation, upgrade to Case 2 by swapping each day's `Wait + Time Window + Yes/No` combo for a `Wait Until daily_session` node. Adding the `daily_session` event alone is enough to flip the Journey from time-based to behavior-based; setting `player_name` activates the personalization the templates already accommodate.

The first 7 days determine whether a player becomes a long-term user or a churn statistic. Invest in getting this right.

After this Journey is live, return to the [Gaming strategies](./gaming-industry) hub for the next layer of lifecycle messaging — re-engagement at Day 1/3/7/14, milestone celebrations on `level_completed` and `streak_reached`, and VIP / spend-based flows for high-value players.

## Related pages

<Columns>
  <Card title="Gaming strategies" icon="gamepad" href="./gaming-industry">
    Strategy hub: player IDs, Tags, Custom Events, segments, and Journey patterns for gaming apps.
  </Card>

  <Card title="Mobile-first lifecycle Journeys" icon="route" href="./mobile-first-journeys">
    Welcome, event-driven, and retention Journey patterns shared across mobile-first apps.
  </Card>

  <Card title="Event-driven Journeys" icon="bolt" href="./event-driven-journeys">
    Trigger Journeys from gameplay events with Wait Until and Event Matching.
  </Card>

  <Card title="Custom Events" icon="bolt" href="./custom-events">
    Reference for the `daily_session` and `reward_claimed` events used in Case 2.
  </Card>

  <Card title="Prompt for push permission" icon="bell" href="./prompt-for-push-permissions">
    Configure the standalone Push Permission Prompt IAM referenced in Prerequisites.
  </Card>

  <Card title="Email warm-up" icon="envelope" href="./email-warm-up">
    Required if you're sending the Day 1 and Day 7 emails at scale on a new domain.
  </Card>
</Columns>


# Category onboarding for news and media
Source: https://documentation.onesignal.com/docs/en/welcome-journey-news-media

Welcome Journey for news and media apps that nudges readers to complete their profile and pick category preferences using Yes/No branches, Wait Until steps, follow-up pushes, and tailored emails.

This playbook implements the [News and media strategies](./news-and-media-industry) hub's category opt-in onboarding flow as a multi-day Welcome Journey. The Journey progressively nudges readers to complete their profile, pick category preferences, and (optionally) confirm their email — without competing with editorial broadcasts that publish breaking news from the dashboard or API.

This Journey is **gap-driven**: each step checks whether the reader has already taken the action it would otherwise prompt, and stays silent if they have. A reader who arrives fully set up gets only the welcome and final emails. A reader who never returns gets the IAMs and follow-up pushes reinforcing what's still missing.

***

## At a glance

1. Send a [welcome email](#step-1-welcome-email) introducing the company, getting started in the app, and the community.
2. [Wait Until](#step-2-wait-until-profile-set) the reader has a profile — `account_type` exists, set only on identified users with an External ID and a completed profile. On expiration, show a Profile setup IAM.
3. [Wait Until](#step-3-wait-until-categories-set) the reader has engaged with category preferences (any `cat_*` Tag exists). On expiration, show a Category IAM.
4. If either gap remains, [send a follow-up push](#step-4-follow-up-push-if-data-is-missing) reinforcing what's missing.
5. If the profile is still missing after another day, [send a profile reminder push](#step-5-profile-reminder-push).
6. [Send a final email](#step-6-final-email) branched on `account_type` (upgrade pitch, community welcome, etc.).

***

## Onboarding goals

| Goal                        | Description                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Complete reader profile     | Log in, create an account, and collect email or SMS Subscriptions.                                                 |
| Set up category preferences | Visit the profile or preference center so `cat_*` Tags get set, enabling targeted broadcasts by topic.             |
| (Optional) Confirm email    | If running [double opt-in](./double-opt-in-email) in parallel, gate every email step on `confirmed_opt_in = true`. |

## Prerequisites

Work through the [News and media strategies implementation roadmap](./news-and-media-industry#implementation-roadmap) before building this Journey. The strategy hub defines the data foundation; this page implements one specific Journey on top of it.

**Required:**

* Familiarity with [Journeys](./journeys-overview) concepts — entry/exit rules, [Wait Until](./journeys-actions#wait-until), and [Yes/No branch](./journeys-actions#yesno-branch).
* An active OneSignal app with at least the data foundation from [News and media strategies](./news-and-media-industry) — `account_type` and the `cat_*` category Tags.
* A [Category Prompt](./permission-requests) or your own category-selection UI on the site to capture the `cat_*` Tags.
* A [preference center](./preference-center) page on your site for IAMs and emails to deep-link to. See [Deep linking](./deep-linking) for the configuration.

**Recommended:**

* The [confirmed opt-in Journey](./double-opt-in-email). When run in parallel, this Welcome Journey can gate every email step on `confirmed_opt_in = true` so unconfirmed addresses don't receive marketing email.
* An [HTML in-app message template](./in-app-html-templates#checklist-survey) for the Category IAM. The HTML format lets readers change category preferences inline without leaving the app.

## Journey configuration

### Required data

| Type | Name                                                                | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tag  | `account_type`                                                      | Values: `free` / `metered` / `paid` / `lapsed`. Set this Tag **only** on identified users — readers who have an External ID and a completed profile (logged in or registered). Do not set it on anonymous visitors. Existence gates the Profile setup IAM and the profile-reminder push; the Tag's value drives the final-email branch.                                                                                                            |
| Tag  | `cat_*` (one per category, e.g., `cat_breaking_news`, `cat_sports`) | Set these Tags **only** when the reader visits your profile or preference center page — not before. The default value at that point is your call: use `0` for an explicit opt-in model (reader must tick to receive) or `1` for an opt-out model (all categories enabled by default). The "Has selected categories" segment then matches whenever any `cat_*` Tag exists, regardless of value, since existence proves the reader visited the page. |
| Tag  | `confirmed_opt_in`                                                  | *Optional.* `true` if the reader has confirmed their email via the [double opt-in Journey](./double-opt-in-email). Used as a Yes/No gate before each email step.                                                                                                                                                                                                                                                                                   |

### Journey segments

Define these once and reuse them across the Journey steps.

**Has profile:**

* Name: "Has profile"
* Filter: `account_type` **exists**

A reader matches whenever `account_type` is set to any value (`free`, `metered`, `paid`, or `lapsed`). This Tag should only be set on identified users with an External ID, this segment effectively means "has logged in or registered" — anonymous visitors should never match.

**Has selected categories:**

* Name: "Has selected categories"
* Filters: `cat_breaking_news` **exists**

A reader matches as soon as any `cat_*` Tag is present on their record — i.e., they've visited the profile or preference center page where category preferences are captured. Whether the Tag's value is `0` or `1` doesn't matter for this gate; the reader has already made their choice. Update this segment whenever you add a new category to your data model.

**Fully onboarded:**

* Name: "Fully onboarded"
* Filters: `account_type` **exists** **AND** `cat_breaking_news` **exists**

Used by Step 4's Yes/No branch — readers in this segment skip the follow-up push.

### Journey templates

These templates are starting points — clone, edit, and re-use them in your own Journey. They use [Liquid syntax](./using-liquid-syntax) for personalization against `first_name`, `account_type`, `favorite_section`, and `metered_articles_remaining`.

#### Email templates

Two emails carry the long-form moments of the Journey — a welcome at entry and a final cross-sell at the end. Both skip automatically when the reader has no email Subscription, so the IAMs, pushes, and gap checks still drive the rest of the flow.

**Email 1 — Welcome (immediate)**

*Purpose:* Introduce the publication, getting started in the app, and the community, plus what to expect from the Journey.

*Suggested subject:* Welcome to OneSignal News, `{{ first_name | default: 'reader' }}`

*Content outline:*

* A short welcome and thank-you for opting in.
* A **getting started** mini-section — 2–3 things the reader can do next: pick categories, follow newsletters, install the app, log in or create an account.
* A **manage your topics** CTA that deep-links to your preference center.
* Links to your social and community channels (Discord, X, YouTube) so they can follow along outside the app.

**Email 2 — Final**

*Purpose:* Cross-sell other channels and surfaces, branched by `account_type`. The closing email of the Journey.

Branch the content with Liquid (or send conditional templates from a Yes/No branch in the Journey itself):

| `account_type` | Email 2 angle                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Not set        | Account creation pitch with social proof.                                                                                                               |
| `free`         | Upgrade pitch — feature comparison, free trial offer.                                                                                                   |
| `metered`      | Urgency-led upsell — "You're `{{ metered_articles_remaining }}` articles away from your limit."                                                         |
| `paid`         | Community welcome, app download (if web reader), advanced preference features.                                                                          |
| `lapsed`       | Win-back offer with renewal-specific incentive. Consider routing to a [dedicated win-back Journey](./news-and-media-industry#journey-examples) instead. |

#### Push templates

Two pushes drive the gap-reminder steps. Pushes skip automatically for readers without a push Subscription, so email-only and SMS-only readers still progress through the rest of the flow.

**Push 1 — Reinforce (gap-driven)**

*Purpose:* Catch readers who haven't completed their profile or picked categories. A single template that addresses both gaps generically.

*Suggested title:* Finish setting up your OneSignal News experience

*Suggested body:* You're a few taps away from a personalized news feed. Pick your topics or finish your profile.

*Launch URL:* Deep-link to your preference center.

**Push 2 — Profile reminder**

*Purpose:* Nudge readers who still haven't created a profile a day after Push 1. Sent only when `account_type` is still missing.

*Suggested title:* Save your spot, `{{ first_name | default: 'reader' }}`

*Suggested body:* Create an account to sync your reading list, get personalized news, and pick up where you left off on any device.

*Launch URL:* Deep-link to your auth flow (log in or create an account).

#### In-app message templates

Two IAMs nudge readers who arrive at a Wait Until expiration branch. IAMs are queued by the Journey step and display the next time the reader opens the app or site.

**Profile setup IAM**

*Purpose:* Convert anonymous readers into authenticated profiles.

A standard IAM with a "Log in or create an account" CTA that deep-links to the customer's auth flow. Keep copy short — one benefit ("personalized news, saved articles, sync across devices") plus the CTA.

**Category IAM**

*Purpose:* Capture category preferences from readers who haven't selected any.

Two implementation options:

* **HTML IAM with inline form.** Use the [In-App HTML Templates checklist/survey example](./in-app-html-templates#checklist-survey) as a starting point. Render checkboxes for each category; on submit, set the matching `cat_*` Tag to `1`. Highest conversion because the reader doesn't leave the app.
* **Simple IAM with deep-link.** A single CTA that deep-links to a [preference center](./preference-center) page that re-triggers the Category Prompt or shows your custom category UI. Easier to build but adds friction.

The Category Prompt itself can't be triggered from a Journey IAM directly — Journeys can't run client-side prompts. Either render the form inline (HTML IAM), or deep-link to a page that triggers the prompt client-side.

### Journey settings

**Entry rules:**

* Audience: **All users**.
* Future additions only: **Checked** — must stay checked so existing users aren't bulk-enrolled when the Journey is set live.

**Exit rules:**

* Default — when the reader moves through the entire Journey.

**Re-entry rules:** No — the reader can receive this Journey only once.

***

## Journey steps

The Journey has 6 sequential steps. Each email step (Steps 1 and 6) is preceded by a Yes/No on `confirmed_opt_in = true` if you're running [double opt-in](./double-opt-in-email) in parallel. The push steps (Steps 4 and 5) don't need that gate — pushes don't require email confirmation.

### Step 1. Welcome email

<Steps>
  <Step title="Yes/No: confirmed_opt_in = true (optional)">
    Skip this branch if you're not running [double opt-in](./double-opt-in-email).

    **Setup:** Yes/No branch on segment membership for "Confirmed opt-in" (filter: `confirmed_opt_in = true`).

    * **Yes →** continue to the email step.
    * **No →** skip the email and rejoin the main flow at Step 2. The parallel double-opt-in Journey continues moving the reader toward confirmation; this Journey just refuses to send marketing email until they're confirmed.
  </Step>

  <Step title="Email: Email 1 — Welcome">
    Send the welcome email. Skipped automatically by OneSignal if the reader has no email Subscription.
  </Step>
</Steps>

### Step 2. Wait Until profile set

<Steps>
  <Step title="Wait Until: in segment &#x22;Has profile&#x22;">
    **Condition:** the reader is in the **Has profile** segment (`account_type` exists).

    **Expiration:** **24 hours**.

    * **Event branch (segment matched):** silent. Continue to Step 3.
    * **Expiration branch (24h, no profile):** continue to the next step.

    A reader who already has a profile when they reach this step matches the condition immediately and skips straight to Step 3 — no IAM is queued.
  </Step>

  <Step title="In-App Message: Profile setup IAM (expiration branch only)">
    Display the Profile setup IAM. The IAM is queued by the Journey step and renders the next time the reader opens the app or site, deep-linking to the auth flow.

    After this step, the expiration branch rejoins the main flow at Step 3.
  </Step>
</Steps>

### Step 3. Wait Until categories set

<Steps>
  <Step title="Wait Until: in segment &#x22;Has selected categories&#x22;">
    **Condition:** the reader is in the **Has selected categories** segment (any `cat_*` Tag exists).

    **Expiration:** **24 hours**.

    * **Event branch (segment matched):** silent. Continue to Step 4.
    * **Expiration branch (24h, no categories):** continue to the next step.
  </Step>

  <Step title="In-App Message: Category IAM (expiration branch only)">
    Display the Category IAM (HTML form or preference-center deep-link). After this step, the expiration branch rejoins the main flow at Step 4.
  </Step>
</Steps>

### Step 4. Follow-up push (if data is missing)

<Steps>
  <Step title="Yes/No: in segment &#x22;Fully onboarded&#x22;">
    **Setup:** Yes/No branch on the **Fully onboarded** segment (has profile AND has selected categories).

    * **Yes (fully onboarded):** skip the push and continue to Step 5.
    * **No (still missing profile or categories):** continue to the push step.
  </Step>

  <Step title="Push: Push 1 — Reinforce">
    Send the gap-reminder push deep-linked to your preference center. Skipped automatically if the reader has no push Subscription.

    No `confirmed_opt_in` gate is needed — that gate is for marketing email only.
  </Step>
</Steps>

### Step 5. Profile reminder push

<Steps>
  <Step title="Wait: 1 day">
    A simple [Wait](./journeys-actions#wait) step that gives the reader a day to act on Push 1 before the next nudge.
  </Step>

  <Step title="Yes/No: in segment &#x22;Has profile&#x22;">
    **Setup:** Yes/No branch on the **Has profile** segment (`account_type` exists).

    * **Yes (has profile):** skip the push and continue to Step 6.
    * **No (profile still missing):** continue to the push step.
  </Step>

  <Step title="Push: Push 2 — Profile reminder">
    Send the profile-reminder push deep-linked to your auth flow. Skipped automatically if the reader has no push Subscription.

    This step intentionally only checks for profile, not categories — readers without a profile are the highest-value gap to close, and a third push would risk fatigue.
  </Step>
</Steps>

### Step 6. Final email

<Steps>
  <Step title="Yes/No: confirmed_opt_in = true (optional)">
    Same gate as Step 1. Skip if not running double opt-in.
  </Step>

  <Step title="Email: Email 2 — Final">
    Send the final email. Branch content on `account_type` (Liquid `{% case account_type %}` blocks or per-segment templates). See [Email 2 — Final](#email-templates) above for the per-status copy angle.
  </Step>
</Steps>

***

## Best practices

* **Don't compete with editorial sends.** Breaking news goes out as one-time dashboard or API campaigns to category segments (`cat_breaking_news = 1`), not as Journey messages. The Welcome Journey only sends meta messages — welcome, profile/category nudges, and the final upgrade pitch. If you ever feel tempted to add an editorial-style push to this Journey, route it through the [Breaking news broadcasts](./news-and-media-industry#journey-examples) flow instead.
* **Set `cat_*` Tags only when the reader visits your profile or preference center page.** The presence of any `cat_*` Tag is what the segment uses to decide "this reader has seen and made a choice" — Tags shouldn't exist before then. The default value (`0` for opt-in, `1` for opt-out) is up to you and depends on whether you want readers to tick boxes to receive each category or untick to remove them.
* **Update the "Has selected categories" segment whenever you add a new category.** Each `cat_*` Tag has to be OR'd into the segment manually. Document the segment alongside your category list so it doesn't drift.
* **Gate every email step on `confirmed_opt_in = true` if you run double opt-in.** A reader who hasn't confirmed should never get marketing email. The IAMs and gap checks still run for them — only the emails skip.
* **Keep IAMs short.** The Profile and Category IAMs each serve one job. Don't bundle multiple CTAs into either; readers about to convert on a single ask are derailed by a second one.
* **Set a global frequency cap.** Editorial sends will reach readers in the same few days as this Journey. A cap on the segment side (e.g., max one push per reader per 4 hours) prevents the editor's send and any incidental Journey nudges from piling up.
* **Lapsed subscribers can stay in the entry rule** ("All users, future additions only"), but the Email 2 `lapsed` branch is a stopgap. For most teams, a [dedicated win-back Journey](./news-and-media-industry#journey-examples) handles lapsed subscribers better than a final touch tucked inside the welcome flow.

***

## FAQ

### Why doesn't this Journey send breaking news pushes?

Breaking news is editorially driven and time-sensitive — sent as one-time dashboard or API campaigns to category segments (`cat_breaking_news = 1`), not as Journey messages. Mixing editorial content into this Journey would either delay breaking news (waiting on the Journey schedule) or compete with the editor's manual send. Keep the two responsibilities separate.

### What happens to readers without an email Subscription?

The two email steps (welcome and final) skip automatically — OneSignal won't send an email to a reader who has no email channel. The pushes, IAMs, and Wait Until steps still run, so push-only and SMS-only readers still get the gap-driven nudges.

### What if the reader has email but no push?

Welcome and final emails still send. The two follow-up pushes skip automatically because the reader has no push Subscription, and the IAMs never display because the reader has no app or site session for them to render in. The Journey effectively becomes an email-only flow for this reader.

### What is the Wait Until step actually checking?

Wait Until listens for the reader to enter the configured segment. The instant they do, the event branch fires and the Journey continues. If 24 hours pass without the segment matching, the expiration branch fires instead. A reader who already qualifies when they reach the step progresses immediately — no IAM is queued.

### How do I add a new category?

Three steps:

1. Add a new `cat_<category>` Tag to your data model. The Tag is set on a reader's record the next time they visit your profile or preference center page — match the default value (`0` for opt-in, `1` for opt-out) to your other categories so existing readers get a consistent experience.
2. Add the category to your [Category Prompt](./permission-requests) or custom category UI.
3. Update the **Has selected categories** and **Fully onboarded** segments to OR in the new Tag (`cat_<category>` exists). Every step using those segments picks up the change automatically.

### Should I run this alongside the double-opt-in Journey?

Yes if you collect email and want CAN-SPAM / GDPR-aligned consent. Add the [confirmed opt-in Journey](./double-opt-in-email) in parallel, gated on the same audience. This Welcome Journey then checks `confirmed_opt_in = true` before each email step so unconfirmed addresses never receive marketing email.

### Why is the entry rule "All users" instead of a more specific segment?

This Journey is gap-driven, not entry-segmented. Every reader is checked at each step against whether they've completed the corresponding action; readers who arrived already set up just pass through silently. **Future additions only** still prevents bulk-enrolling existing users when the Journey is set live.

### How long does the Journey last?

Roughly 3 days from entry. Step 1 fires immediately, Steps 2 and 3 each have a 24-hour Wait Until window, Step 4 (follow-up push) follows immediately, Step 5 waits 1 day for the profile-reminder push, and Step 6 (final email) sends right after.

## Related pages

<Columns>
  <Card title="News and media strategies" icon="newspaper" href="./news-and-media-industry">
    Strategy hub: External IDs, category Tags, Custom Events, segments, and Journey patterns for news and media.
  </Card>

  <Card title="Confirmed opt-in for email" icon="envelope-circle-check" href="./double-opt-in-email">
    Run the double opt-in Journey in parallel and gate this Journey's email steps on `confirmed_opt_in = true`.
  </Card>

  <Card title="Permission requests" icon="bell" href="./permission-requests">
    Configure the Category Prompt that captures `cat_*` Tags before this Journey starts.
  </Card>

  <Card title="In-App HTML templates" icon="code" href="./in-app-html-templates#checklist-survey">
    Build the inline category-selection form used by the Category IAM.
  </Card>

  <Card title="Preference center" icon="sliders" href="./preference-center">
    The destination for emails and IAMs that need richer settings (frequency, quiet hours, newsletters).
  </Card>

  <Card title="Deep linking" icon="arrow-up-right-from-square" href="./deep-linking">
    Deep-link from emails and IAMs to specific pages on your site or app.
  </Card>
</Columns>


# Windows app setup
Source: https://documentation.onesignal.com/docs/en/windows-app-setup

Complete guide for integrating OneSignal push notifications into your Universal Windows Platform (UWP) app using Windows Push Notification Service (WNS) and OneSignal's REST API

# Windows App Setup

## Requirements

Before setting up OneSignal for your Windows app, ensure you have:

* **Universal Windows Platform (UWP) App** - OneSignal currently supports UWP apps only
* **Microsoft Store App Registration** - Required for obtaining Package SID and Secret Key
* **OneSignal Account** - Free account with configured app and platform settings

<Info>OneSignal does not currently support Windows App SDK (WinUI 3). If your app uses Windows App SDK instead of UWP, please contact `support@onesignal.com` for guidance on [migration options](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/notifications).</Info>

## Configure Your OneSignal App and Platform

### Step 1: Set Up Your OneSignal Account

If your team already has a OneSignal account, [request admin access](./manage-team-members) to configure platform settings. Otherwise, [create a free account](https://onesignal.com) to get started.

### Step 2: Create or Configure Your OneSignal App

OneSignal allows you to configure multiple platforms (iOS, Android, Huawei, Amazon, Windows) within a single app for cross-platform messaging.

#### Create New App

1. Click **New App/Website** from your dashboard
2. Choose a recognizable app name and organization name
3. Select **Windows (UWP)** as your platform
4. Click **Next: Configure Your Platform**

<Frame>
  <img />
</Frame>

#### Add Platform to Existing App

1. Select your existing app
2. Navigate to **Settings > Push & In-App**
3. Click **Add Platform** and select **Windows (UWP)**

<Frame>
  <img />
</Frame>

### Step 3: Configure Additional Platforms (Optional)

If you're building a cross-platform app, configure additional platforms now:

* **Android**: [Set up Firebase Credentials](./android-firebase-credentials)
* **iOS**: [p8 Token (Recommended)](./ios-p8-token-based-connection-to-apns) or [p12 Certificate](./ios-p12-generate-certificates)
* **Amazon**: [Generate API Key](./generate-an-amazon-api-key)
* **Huawei**: [Authorize OneSignal](./authorize-onesignal-to-send-huawei-push)

Click **Save & Continue** after entering credentials for each platform.

### Step 4: Select Target SDK

Choose **Windows UWP** as your target SDK and click **Save & Continue**.

<Frame>
  <img />
</Frame>

### Step 5: Save Your App ID

**Critical:** Copy and securely store your OneSignal App ID - you'll need this for API calls and user registration.

<Frame>
  <img />
</Frame>

Optionally, invite team members by clicking **Invite**, then click **Done** to continue.

## Windows Platform Configuration

### Get Microsoft Store Credentials

Since OneSignal uses Windows Push Notification Service (WNS), you'll need credentials from the Microsoft Store:

1. **Publish to Microsoft Store** - Your app must be registered in the Microsoft Store (even if not publicly available)
2. **Obtain Package SID and Secret Key** - Follow [Microsoft's detailed guide](https://learn.microsoft.com/en-us/azure/notification-hubs/notification-hubs-windows-store-dotnet-get-started-wns-push-notification#create-an-app-in-windows-store) to retrieve these credentials
3. **Configure OneSignal Platform**:
   * Navigate to **Settings > Windows (UWP)** in your OneSignal dashboard
   * Paste your Package SID and Secret Key
   * Click **Save** to activate the platform

<Frame>
  <img />
</Frame>

> **Gotcha:** Package SID and Secret Key are only available after your app is registered with the Microsoft Store. You cannot test push notifications locally without these credentials.

## SDK Integration

### Understanding the Architecture

OneSignal doesn't provide a dedicated UWP SDK. Instead, you'll integrate using:

1. **Windows Push Notification Service (WNS)** - Microsoft's native push service
2. **OneSignal REST API** - For user management and message sending
3. **Notification Channel URI** - Acts as the device token for push notifications

For comprehensive understanding of WNS, review [Microsoft's WNS documentation](https://docs.microsoft.com/en-us/windows/uwp/design/shell/tiles-and-notifications/windows-push-notification-services--wns--overview).

### Register Users for Push Notifications

#### Step 1: Request Notification Channel

Follow Microsoft's guide to [create a notification channel](https://learn.microsoft.com/en-us/windows/apps/design/shell/tiles-and-notifications/request-create-save-notification-channel). The channel URI returned by WNS serves as your device token.

```csharp theme={null}
// Example: Getting notification channel URI
var channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
string channelUri = channel.Uri; // This is your token for OneSignal
```

#### Step 2: Create OneSignal User Record

Call OneSignal's [Create user](/reference/create-user) API to register the device:

**Required Parameters:**

* `subscription.type`: `"WindowsPush"`
* `subscription.token`: The channel URI from Step 1

**Recommended Parameters:**

* `identity.external_id`: Unique identifier for the user (e.g., user ID from your system)
* `properties`: Any custom user properties for targeting

```json theme={null}
{
  "identity": {
    "external_id": "your-user-id-123"
  },
  "subscriptions": [
    {
      "type": "WindowsPush",
      "token": "https://cloud.notify.windows.com/?token=..."
    }
  ],
  "properties": {
    "tags": {
      "user_type": "premium",
      "app_version": "1.2.0"
    }
  }
}
```

> **Gotcha:** Channel URIs can expire and change. Implement logic to refresh the channel URI periodically and update the OneSignal user record when it changes.

### Handle Channel URI Changes

WNS channel URIs can expire. Implement the `PushNotificationReceived` event to detect when you need to refresh:

```csharp theme={null}
channel.PushNotificationReceived += OnPushNotificationReceived;

// Check if channel URI has changed
if (channel.Uri != storedChannelUri) {
    // Update OneSignal user record with new URI
    await UpdateOneSignalUser(channel.Uri);
}
```

## Sending Push Notifications

### Using OneSignal Dashboard

1. Navigate to **Messages > Push** in your OneSignal dashboard
2. Create a new push notification
3. Select your Windows platform
4. Configure your message content and targeting
5. Send immediately or schedule for later

### Using OneSignal API

Send notifications programmatically using the [Create notification](/reference/create-message) API:

```json theme={null}
{
  "app_id": "your-onesignal-app-id",
  "contents": {"en": "Your notification message"},
  "headings": {"en": "Notification Title"},
  "include_external_user_ids": ["your-user-id-123"],
  "channel_for_external_user_ids": "push"
}
```

For detailed messaging options and advanced targeting, see [Sending Push Messages](./push).

## Next Steps and Best Practices

### Testing Your Integration

1. **Test Notification Channel Creation** - Ensure your app successfully creates and maintains a WNS channel
2. **Verify User Registration** - Confirm users are properly registered in your OneSignal dashboard
3. **Send Test Notifications** - Use the OneSignal dashboard to send test messages
4. **Handle Notification Events** - Implement proper handling for notification received, opened, and dismissed events

### Common Issues and Solutions

**Channel URI Not Working**

* Verify your Package SID and Secret Key are correctly configured
* Ensure your app is properly registered with the Microsoft Store
* Check that the channel URI hasn't expired

**Users Not Receiving Notifications**

* Confirm the OneSignal user record was created successfully
* Verify the Windows platform is properly configured in OneSignal
* Check that notifications aren't being blocked by Windows notification settings

**API Integration Issues**

* Validate your OneSignal App ID is correct
* Ensure you're using the correct API endpoints and authentication
* Review API response codes and error messages for troubleshooting

### Production Considerations

* Implement proper error handling for all OneSignal API calls
* Set up monitoring for channel URI refresh failures
* Consider implementing offline queueing for API calls during network issues
* Plan for scaling user registration during peak app usage periods

For additional support and advanced implementation guidance, contact OneSignal support or explore our comprehensive [API documentation](/reference/rest-api-overview).


# Cancel message
Source: https://documentation.onesignal.com/reference/cancel-message

DELETE /notifications/{message_id}?app_id={app_id}
Stop a scheduled or currently outgoing message.

## Overview

The Cancel message API can be used to stop scheduled messages from being sent. It does not delete or remove the message from the app. If a message is in the process of sending, then canceling it may not fully prevent all targeted users from receiving it.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users, scheduling the message in the future with `send_after`. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and use this API to cancel sending the message to the user if not needed anymore.

If you need a way to remove a notification already sent to a user, see [Remove notifications & TTL](/docs/en/push).

***


# Create custom events
Source: https://documentation.onesignal.com/reference/create-custom-events

POST /apps/{app_id}/custom_events
The Custom Events API allows you to record user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones.

## Overview

The Custom Events API allows you to track user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones. See [Custom events](/docs/en/custom-events) for more information.

### Use Cases

Custom events can be used to:

* Enter users into [Journeys](/docs/en/journeys-settings)
* Trigger Journey [Wait Until](/docs/en/journeys-actions) nodes

### Error handling

If individual events can't be processed, an `errors` key will be returned in the response (with HTTP status 202) containing information about each failing event. The most common event-specific error is a failure to find a user associated with the External ID or OneSignal ID in the event.

If you'd like to retry sending events in the case of a failure, you only need to re-send the events for which errors were returned -- events that don't have an error associated with them are still processed. However, if a 5xx HTTP response is returned, you must retry the entire batch of events.

In either case, if you are implementing retry, make sure to also pass an [`idempotency_key`](/reference/idempotent-notification-requests).

### Duplicate events

If you implement retry behavior for your custom event delivery, please provide the [`idempotency_key`](/reference/idempotent-notification-requests) field. Each unique event should get its own unique UUID, and when retrying delivery for events, the same UUID must be provided. Duplicate events with the same `idempotency_key` will be ignored on a best-effort basis within a 4-hour period. This allows you to avoid erroneously triggering Journeys multiple times or incurring charges for storing unnecessary duplicate events.

***


# Sending messages with the OneSignal API
Source: https://documentation.onesignal.com/reference/create-message

Send push notifications, emails, SMS, and Live Activities with the OneSignal API. Covers audience targeting, message composition, scheduling, and response handling.

## Overview

This guide walks you through sending messages with the OneSignal API — from choosing a target audience to composing content, scheduling delivery, and validating responses. Each section covers channel-specific options and performance guidance.

### Prerequisites

1. Complete [Channel Setup](/docs/en/channel-setup) for the channels you plan to use: push, email, SMS, Live Activities.
2. Start accumulating [Subscriptions](/docs/en/subscriptions) for your users.
3. Have your REST API Key and App ID ready. See [Keys and IDs](/docs/en/keys-and-ids).

***

## Choose your target audience

You can target users with **one of the following methods per request**:

* **Aliases**: Specific users via unique IDs, emails, or phone numbers.
* **Segments**: Groups based on predefined behaviors or attributes.
* **Filters**: Custom rules using tags, location, activity, and more.

<Warning>
  Only one targeting method is allowed per message. For example, you cannot mix aliases and filters.
</Warning>

You can also target specific platforms (for example, `isAndroid`, `isIos`, `isAnyWeb`) when sending push notifications. By default, all push platforms are enabled.

### Aliases, emails, phone numbers

Target specific users or lists of users (up to 20,000 entries per request). This method is best for [Transactional Messages](/docs/en/transactional-messages).

<Accordion title="Aliases, emails, and phone numbers targeting parameters">
  <ParamField type="object">
    Target up to 20,000 users by their `external_id`, `onesignal_id`, or a custom alias. Combine with `target_channel` to select the delivery channel.

    ```json theme={null}
    {
      "include_aliases": {
        "external_id": [
          "user1",
          "user2",
          "user3"
        ]
      },
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="string">
    The targeted delivery channel. Required when using `include_aliases` or `included_segments` and sending SMS/RCS. Accepts `"push"`, `"email"`, or `"sms"`. The `"sms"` value covers both SMS and RCS — RCS messages are delivered through the SMS channel.

    ```json theme={null}
    {
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="array">
    Target users' specific [Subscriptions](/docs/en/subscriptions) by ID. Max 20,000 `subscription_id` per request.

    ```json theme={null}
    {
      "include_subscription_ids": [
        "1dd608f2-c6a1-11e3-851d-000c2940e62c"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send to specific email addresses (max 20,000 per request). Can only be used when sending [email](/reference/email). If the email address does not exist within the OneSignal App, a new email subscription is created.

    ```json theme={null}
    {
      "email_to": [
        "user1@example.com",
        "user2@example.com"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send SMS/MMS/RCS to phone numbers in [E.164 format](/docs/en/sms-setup#what-is-e164-format) (max 20,000 per request). Can only be used when sending [SMS/MMS/RCS](/reference/sms). If the phone number does not exist within the OneSignal App, a new SMS subscription is created.

    ```json theme={null}
    {
      "include_phone_numbers": [
        "+19999999999"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Segments

Target users in existing [segments](/docs/en/segmentation). Users in multiple segments only receive the message once.

<Accordion title="Segments targeting parameters">
  <ParamField type="array">
    Target predefined [segments](/docs/en/segmentation). Users who are in multiple segments only receive the message once. Combine with `excluded_segments` to exclude users from specific segments. When sending SMS/RCS, set `target_channel` to `"sms"` (or use the legacy `isSms=true` field).

    ```json theme={null}
    {
      "included_segments": [
        "Active Users",
        "Inactive Users"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Exclude users in these [segments](/docs/en/segmentation) even if they're in `included_segments`.

    ```json theme={null}
    {
      "included_segments": [
        "Subscribed Users"
      ],
      "excluded_segments": [
        "Inactive Users"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Filters

Build real-time audiences with `AND`/`OR` logic without creating segments first.

You can include up to **200 total entries per request**. This includes filter rows (for example, each `field`) and logical operators like `{"operator": "OR"}`.

<Accordion title="Filters targeting parameter details">
  <Info>
    **Performance guidance:**

    * **Fast:** Tag filters using `"="` or `"exists"`, and filters on `last_session`, `session_count`, or `country`.
    * **Slower:** Negation filters (`"!="`, `"not_exists"`) — especially with users who have many tags. Contact support to request indexing optimizations.
    * **Slow by default:** Numeric comparisons (`">"`, `"<"`) on tags or custom properties. Indexing may be available on request.
    * **Mixed performance:** Combining tag filters with other fields may increase computation time.
  </Info>

  <ParamField type="string">
    * Implicit `AND` logic between filters. Use `"operator": "OR"` to start a new branch.
    * `OR` filters are mutually exclusive. Recipients only need to satisfy one condition.
    * Allowed values: `"AND"`, `"OR"`.

    <CodeGroup>
      ```json AND example theme={null}
      // Users must satisfy both filters to be included.
      // Notice the AND operator is not required

      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      // The same example using the AND operator. This is not required.
      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "AND"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      ```

      ```json OR example theme={null}
      // Users can satisfy either filter to be included.

      "filters": [
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "tag", "key": "level", "relation": "=", "value": "20"}
      ]
      ```

      ```json Combinations theme={null}
      // In this example, users must either have:
      // The specified session_count AND tag requirement
      // Or it will be all records where last_session is satisfied
      {
        "name": "2 filters or 1",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"}
        ]
      }

      // Similar to the first example, this shows how to require a specific field
      // across other filters

      {
        "name": "3 filters, 1 required across all",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
        ]
      }

      // Example of 3 user groups with 2 requirements
      // (group_1 OR group_2 OR group_3) AND (requirement_1 OR requirement_2)

      {
        "name": "3 groups with 2 requirements",
        "filters": [
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"}
        ]
      }
      ```
    </CodeGroup>
  </ParamField>

  <ParamField type="object">
    ### `tag`

    Target based on custom user [Tags](/docs/en/add-user-data-tags).

    <Warning>
      Do not use tags for targeting individual users like a "user id".
      Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
    </Warning>

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
      * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
    * `key` = Tag key to compare.
    * `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

    ```json theme={null}
    "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "OR"},
      {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
    ]
    ```

    ### `country`

    Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "country", "relation": "=", "value": "US"},
        {"operator": "OR"},
        {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
      ]
      ```

    ### `last_session`

    Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "last_session", "relation": ">","hours_ago": "10"}
      ]
      ```

    ### `first_session`

    Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "first_session", "relation": "<","hours_ago": "24"}
      ]
      ```

    ### `session_count`

    Total number of sessions by the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="` or `"!="`
    * `value` = number of sessions. Example: `"1"`

      ```json theme={null}
      "filters": [
        {"field": "session_count", "relation": ">","value": "5"}
      ]
      ```

    ### `session_time`

    Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

    * `relation` = `">"` or `"<"`
    * `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

      ```json theme={null}
      "filters": [
        {"field": "session_time", "relation": ">","value": "86400"}
      ]
      ```

    ### `language`

    [User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = 2 character language code. Example: `"en"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "language", "relation": "=","value": "en"},
        {"operator": "OR"},
        {"field": "language", "relation": "in_array","value": "es,fr,de"}
      ]
      ```

    ### `app_version`

    App version set on the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = app version. Example: `"1.0.0"`
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "app_version", "relation": "=","value": "1.0.1"},
        {"operator": "OR"},
        {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
      ]
      ```

    ### `location`

    Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

    * `radius` = in meters
    * `lat` = latitude
    * `long` = longitude

      ```json theme={null}
      "filters": [
        {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
      ]
      ```
  </ParamField>
</Accordion>

***

## Craft your message

Each channel has its own set of fields. At a minimum, you need the following to send a displayable message:

* **Push and SMS** use `contents`
* **Email** uses `email_subject` and `email_body`
* Or reuse `template_id` if you created [templates](/docs/en/templates).

<CodeGroup>
  ```json Push and SMS theme={null}
  // Message request body
  {
    "contents": {
      "en": "Hello, world",
      "es": "Hola Mundo",
      "fr": "Bonjour le monde",
      "zh-Hans": "你好世界"
    }
  }
  ```

  ```json Email theme={null}
  // Message request body
  {
    "email_subject": "Hello, world",
    "email_body": "<html><body><h1>Hello, world</h1></body></html>"
  }
  ```
</CodeGroup>

For advanced customization—like adding images, buttons, sounds, or tracking—see the channel-specific options below.

### Push notification options

Below are the most common parameters for push notifications. For the full list of options, see the [Push notification reference](/reference/push-notification).

<Accordion title="Push notification options">
  #### Content and text

  * [`contents`](/reference/push-notification#body-contents) – Main message body.
  * [`headings`](/reference/push-notification#body-headings) – Title of the notification.
  * [`subtitle`](/reference/push-notification#body-subtitle) – Secondary line of text.
  * [`template_id`](/reference/push-notification#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Appearance

  * [`ios_attachments`](/reference/push-notification#body-ios-attachments) – Images/video/media.
  * [`big_picture`](/reference/push-notification#body-big-picture) – Large image (Android).
  * [`chrome_web_image`](/reference/push-notification#body-chrome-web-image) – Large image (Chrome).
  * [`small_icon`](/reference/push-notification#body-small-icon)
  * [`large_icon`](/reference/push-notification#body-large-icon)
  * [`buttons`](/reference/push-notification#body-buttons) – Action buttons.

  #### Delivery and priority

  * [`android_channel_id`](/reference/push-notification#body-android-channel-id)
  * [`priority`](/reference/push-notification#body-priority) – Delivery urgency.
  * [`ios_interruption_level`](/reference/push-notification#body-ios-interruption-level)
  * [`collapse_id`](/reference/push-notification#body-collapse-id) – Replaces older messages.

  #### Data and extras

  * [`data`](/reference/push-notification#body-data) – Custom key-value pairs sent to your app.
  * [`url`](/reference/push-notification#body-url) – Opens when notification is tapped.
</Accordion>

### Email options

<Accordion title="Email options">
  #### Content

  * [`email_subject`](/reference/email#body-email-subject)
  * [`email_body`](/reference/email#body-email-body)
  * [`email_preheader`](/reference/email#body-email-preheader)

  #### Appearance

  * [`template_id`](/reference/email#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Sender info

  * [`email_from_name`](/reference/email#body-email-from-name)
  * [`email_reply_to`](/reference/email#body-email-reply-to)
</Accordion>

### SMS/MMS options

<Accordion title="SMS/MMS options">
  #### Content

  * [`contents`](/reference/sms#body-contents)
  * [`template_id`](/reference/sms#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Media (MMS only)

  * [`sms_media_urls`](/reference/sms#body-sms-media-urls)

  #### Sender info

  * [`sms_from`](/reference/sms#body-sms-from)
</Accordion>

***

## Schedule and per-user delivery

By default, messages are sent immediately. You can schedule delivery in advance and optimize timing per user based on their local timezone or recent activity.

<Accordion title="Schedule delivery and per-user optimization parameters">
  <ParamField type="string">
    Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript's Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring).

    ```json theme={null}
    {
      "send_after": "2025-09-24T14:00:00-07:00"
    }
    ```
  </ParamField>

  <ParamField type="string">
    Controls how push and email messages are delivered on a per-user basis. Not available for SMS.

    * `"timezone"`: Sends at the same local time across time zones.
    * `"last-active"`: Delivers based on each user's most recent session.

    Not compatible with [push throttling](/docs/en/throttling). When `delayed_option` is set, you must also set `throttle_rate_per_minute` to `0`.

    ```json theme={null}
    {
      "delayed_option": "last-active",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>

  <ParamField type="string">
    Use with `delayed_option: "timezone"` to set a consistent daily delivery time. Accepted formats:

    * `"9:00AM"` (12-hour)
    * `"21:45"` (24-hour)
    * `"09:45:30"` (HH:mm:ss)

    Example — Send every day at 9 AM in each user's local time:

    ```json theme={null}
    {
      "delayed_option": "timezone",
      "delivery_time_of_day": "9:00AM",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>
</Accordion>

***

## Submit the request

This final example sends a localized push notification to all subscribed users:

```curl theme={null}
curl -X "POST" "https://api.onesignal.com/notifications" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Key YOUR_API_KEY' \
     -d $'{
      "target_channel": "push",
      "included_segments": [
        "Subscribed Users"
      ],
      "app_id": "YOUR_APP_ID",
      "contents": {
        "en": "Hello, world",
        "es": "Hola mundo",
        "fr": "Bonjour le monde",
        "zh-Hans": "你好世界"
      }
    }'
```

Once the request is sent, OneSignal forwards it to the appropriate downstream provider, which then delivers it to the recipient:

* **Push:** FCM, APNs, or HMS
* **Email:** your email service provider
* **SMS:** Twilio

### Handle the response

You receive a `200` response code if the request is valid and accepted.

* If an `id` is returned, the message was created successfully. Save this `id` for future tracking and reference of message stats via the [View message API](/reference/view-message).
* If no `id` is returned, the message was not created, likely because there are no valid [subscriptions](/docs/en/subscriptions) in the target audience.

**Response details by channel:**

* [Push](/reference/push-notification#response-id)
* [Email](/reference/email#response-id)
* [SMS](/reference/sms#response-id)

<Note>
  See our [REST API Overview](/reference/rest-api-overview#reliability-and-delivery) page for details on retries and [rate limits](/reference/rate-limits).
</Note>

***

## FAQ

### Can I combine `include_aliases`, `included_segments`, and `filters` in one request?

No. Each request must use exactly one targeting method. Mixing them returns a validation error. Choose aliases for transactional sends to specific users, segments for predefined audiences, or filters for ad-hoc audiences built with `AND`/`OR` logic.

### Does `target_channel: "sms"` cover RCS?

Yes. The `target_channel` enum accepts `"push"`, `"email"`, and `"sms"`. RCS messages are delivered through the SMS channel — there is no separate `"rcs"` value. OneSignal decides whether to send via RCS or SMS based on the recipient's device and your sender configuration.

### My request returned `200` but no `id`. What happened?

The request was valid but no message was created, typically because the target audience contains no valid subscriptions for the selected channel. Common causes include a segment that resolves to zero users, all targeted aliases being unsubscribed, or phone numbers that don't match an existing SMS subscription.

### Can I use `//` comments in the JSON request body?

No. The `//` comments in the examples on this page are illustrative only. Strict JSON does not support comments — strip them before sending to the API.

### How is the `Sent` count in reports related to the API response?

The dashboard `Sent` metric is a composite. To derive it from the [View message API](/reference/view-message), sum `successful + failed + errored`. See the [Metrics glossary](/docs/en/analytics-metrics-glossary) for the full mapping between dashboard, API, CSV, and Event Streams names.

***

## Next steps

Refer to the channel-specific APIs to customize delivery further:

* [Push notification](/reference/push-notification)
* [Email](/reference/email)
* [SMS](/reference/sms)
* [Live Activities](/reference/start-live-activity)
* [Server-Side SDKs](/docs/en/server-sdk-reference)


# Create user
Source: https://documentation.onesignal.com/reference/create-user

POST /apps/{app_id}/users
Create a new user or modify the subscriptions associated with an existing User.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint enables you to create and manage users outside of frontendSDK-based sessions. It's primarily used to:

* Import users from other systems.
* Programmatically define users by assigning identifiers (aliases), properties (e.g., tags), and messaging subscriptions (e.g., email, mobile, SMS).

If you're using the frontend SDKs, user creation is typically handled automatically via methods like `login`, `addEmail`, and `addSms`. See [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) for conceptual guidance.

***

## How to use this API

To successfully create a user via the API:

* You must provide at least one unique identifier via the `identity` and Subscription via the `subscriptions` fields.
* You can optionally include user profile data (`properties`) and one or more messaging `subscriptions`.

## Key Concepts

### Aliases

Aliases uniquely identify a user and should include an `external_id` (the recommended identifier). They allow you to reference users across platforms or external systems. Up to 10 custom aliases are supported. Each alias key and value has a maximum length of 128 characters.

### Properties

User properties store information such as tags, location, activity, and device data. These attributes help you personalize campaigns and optimize engagement strategies.

### Subscriptions

A user can have up to **20 subscriptions** (across email, SMS, push, etc.). Subscriptions connect users to channels for message delivery and are transferable across users. See [Subscriptions](/docs/en/subscriptions) for more.

***


# Delete user
Source: https://documentation.onesignal.com/reference/delete-user

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}
Delete a user including all associated properties, subscriptions, and identity.

## Overview

Use this API to permanently delete a user from your OneSignal project, including all associated subscriptions, properties, and aliases. The operation is asynchronous—user data will be deleted shortly after the request is accepted.

***

## How to use this API

To delete a user, you must be able to identify them using one of the following alias types:

* `external_id` (recommended and most common)
* `onesignal_id`
* A custom Alias that you have set

Pass the appropriate `alias_label` and corresponding `alias_id` in the request path.

<Warning>
  This operation deletes all data associated with the user, including:

  * All identity aliases
  * All channel subscriptions (push, email, SMS, etc.)
  * All custom user properties
</Warning>

## Because this is an irreversible operation, be sure that you really intend to delete the user and all their data.


# Email
Source: https://documentation.onesignal.com/reference/email

POST /notifications?c=email
Send a message using the email channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for email. See [Push notification](/reference/push-notification) or [SMS](/reference/sms) to send to those channels.

Ensure your [Email setup](/docs/en/email-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# View user identity
Source: https://documentation.onesignal.com/reference/fetch-aliases

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Retrieve all aliases associated with a user using a known alias, such as an `external_id`, `onesignal_id`, or a custom alias. This API helps you map back to a user’s full identity from any one piece of identifying information.

## Overview

Use this API when you want to retrieve the complete identity object for a user, which includes all aliases tied to that user. It is ideal for cases where you know one alias and want to discover others—especially helpful for user mapping, debugging, or linking systems.

This endpoint is similar to the [View user](/reference/view-user) API but only returns the `identity` object—not subscriptions or properties.

<Tip>
  If you only know a subscription\_id, use View user identity (by subscription) instead.
</Tip>

For more context on user identity and aliasing:

* [Users](/docs/en/users)
* [Aliases](/docs/en/aliases)

***

## How to use this API

To identify the user, use:

* `alias_label` – the type of alias you’re using to find the user (e.g. `external_id`, `onesignal_id`, or a custom alias)
* `alias_id` – the actual value of that alias

Common usage patterns:

Using `external_id` (recommended):

* `alias_label`: `external_id`
* `alias_id`: your user ID (e.g., user-123)

Using `onesignal_id`:

* `alias_label`: `onesignal_id`
* `alias_id`: the OneSignal-assigned unique ID

Using a custom alias:

* Define your own alias label (e.g. `shopify_customer_id`) and its value

<Note>
  We strongly recommend setting and using the `external_id` as your primary user identifier for portability and simplicity across your systems.
</Note>

***


# Idempotent API requests
Source: https://documentation.onesignal.com/reference/idempotent-notification-requests

Prevent duplicate messages or custom events when retrying API requests.

## Overview

When you create messages or custom events via our REST API, network failures or timeouts can cause uncertainty about whether a request succeeded. **Idempotent requests** solve this problem by ensuring the same request is only processed once—even if it is sent multiple times.

This page explains how idempotency works in OneSignal, when to use it, and common pitfalls to avoid.

### When you should use idempotency

You should use idempotent requests any time you plan to retry API calls, especially when:

* You receive a timeout, 500-level error, or no response.
* Your infrastructure automatically retries failed requests.
* Delivering a duplicate message or custom event would be harmful.
* Missing a message or custom event would be harmful.

### The problem idempotency solves

Consider this common failure scenario:

1. You send a `notifications#create` or `custom_events#create` request.
2. OneSignal begins processing and sending the message or event.
3. A network error occurs before your client receives a response.

At this point, your system cannot know whether the request succeeded.

* If you retry and the request already succeeded, users may receive duplicates.
* If you do not retry and the request failed, users may miss important messages or events.

**Idempotency provides a safe retry mechanism.**

***

## How idempotency works

OneSignal supports idempotent operations for:

* [`notifications#create`](/reference/create-message)
* [`custom_events#create`](/reference/create-custom-events)

You provide a unique `idempotency_key` with each request.

### Request flow with idempotency

1. You send a request with an `idempotency_key`.
2. OneSignal processes the request and begins sending the message or creating the custom event.
3. A network error or timeout occurs.
4. You retry the request using the same `idempotency_key`.
5. OneSignal detects the duplicate and returns the result of the original request.
6. Only one notification or custom event is processed.

You can repeat this retry any number of times. As long as the `idempotency_key` remains the same, the operation will only be processed once.

***

## Idempotency key reference

<ParamField type="RFC 9562 UUID">
  A unique identifier used to prevent duplicate messages or custom events from repeat API calls. Keys must be unique [RFC 9562 UUID format](https://en.wikipedia.org/wiki/Universally_unique_identifier). Valid for 30 days.
</ParamField>

<Note>
  This `idempotency_key` property used to be called `external_id` but caused confusion with our [Users `external_id`](/docs/en/users) alias, so we have added this new property name to reduce confusion. Both will work in this case.
</Note>

***

## Important constraints and gotchas

<Warning> If you reuse the same `idempotency_key` for different messages or events, only the first request will be processed. </Warning>

Keep the following in mind:

* **Keys must be unique per logical operation**
  Generate a new UUID for every notification or custom event you intend to send.

* **Keys are retained for 30 days**
  After 30 days, OneSignal may delete the record. Reusing the same key after that window may result in a new message being sent.

* **Use a strong source of randomness**
  Predictable or reused UUIDs can cause unexpected deduplication.

* **Idempotency does not guarantee delivery**
  It only guarantees at-most-once processing. You should still monitor API responses and logs.

### Legacy behavior

The `idempotency_key` property was previously named `external_id`. This caused confusion with the Users `external_id` alias, so `idempotency_key` is now the recommended field name. Both names are currently supported.

### Best practices

* Always include `idempotency_key` when implementing retries.
* Store the `idempotency_key` alongside your request metadata for debugging.
* Retry only after honoring any `Retry-After` header returned by the API.
* Combine idempotency with proper timeout handling (for example, a 60-second HTTP timeout).

***


# Message history
Source: https://documentation.onesignal.com/reference/message-history

POST /notifications/{message_id}/history
View which subscriptions received a particular message

## Overview

This API enables you to retrieve all [Subscriptions](/docs/en/subscriptions) that received a specific push notification or email. You can access the notification's history for up to seven days after it was sent. Please note that notifications sent to fewer than 1,000 recipients will not record a "received" event, but they will still record "sent" events.

***

## How to Use this API

1. Submit a request to generate a report.

2. Decide delivery method

   * After receiving a successful response, **poll the destination URL** until the file becomes available. Exports typically complete within 1-3 minutes; we recommend a 10-second polling interval.
   * Alternatively, you can opt to receive an email to the address specified in the optional `email` parameter when the report is ready.

### Requirements

* A [OneSignal Professional or Enterprise Plan](https://onesignal.com/pricing).
* Enabled the "Send History via OneSignal API" option in Settings -> Integrations; notifications sent before this setting is enabled can't be retrieved.
* Requests must be made within seven days of sending the notification.

### Polling

Use the `csv_file_url` property in the response to test if the report is complete. If you receive a '403' error response, retry fetching the file after a short period; it only means we're still generating the report.

### Sample Report

The generated report is a simple CSV file that can be imported into any system for further processing.

```csv report.csv theme={null}
player_id,onesignal_id,external_id,target_channel,timestamp
"2c4fac95-7dfb-4113-9347-aba3a92ff557","ccddf35a-1233-4423-8a57-ac8c4b38eb81","a07aec27-2586-4b92-a24f-62660a1517fa","push","1628189160"
"68f5cf73-b20a-4de9-b6ee-79a863b8e7d8","d2f9f2f8-94af-4942-8183-115cef1213d5","4b66359f-3d94-4a73-806d-8ef5f0430b3d","push","1628187816"

```

### Limitations

* Querying for `opens` events are not supported.
* The `timestamp` column is included only for `clicked` events.

***


# Push notification
Source: https://documentation.onesignal.com/reference/push-notification

POST /notifications?c=push
Send a message using the push notification channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for push. See [Email](/reference/email) or [SMS](/reference/sms) to send to those channels.

Ensure your application is properly configured by following the [Mobile SDK Setup](/docs/en/mobile-sdk-setup) and/or [Web SDK Setup](/docs/en/web-sdk-setup) guides. You should see subscribed push [Subscriptions](/docs/en/subscriptions) in your OneSignal dashboard to send them messages.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Rate limits and error handling
Source: https://documentation.onesignal.com/reference/rate-limits

Understand OneSignal API and application rate limits, common errors, retry behavior, and how to safely recover from failures without sending duplicate messages or disabling your app.

OneSignal uses rate limits and error responses as safety mechanisms to protect your app from accidental overloads, duplicate sends, and retry storms.

There are three categories to understand:

* **API rate limits** return HTTP `429` errors when request volume is too high.
* **Network timeouts or temporary server failures** return `5xx` errors or no response at all.
* **Application message limits** may temporarily disable your app if too many messages are sent in a short period.

<Info>
  Most apps never hit these limits during normal usage. When they do occur, they are usually caused by retries, loops, or unexpected audience expansion.
</Info>

<Check>
  **Quick implementation checklist**

  * Expect `429`, `5xx`, and timeouts. They are normal at scale.
  * Never retry message sends without an `idempotency_key`.
  * For non-urgent retries, wait **100 seconds** before retrying.
  * API rate limits (`429`) never disable your app.
  * Only message volume limits can disable your app.
  * `POST /notifications` (create) and `DELETE /notifications` (cancel) count toward the same rate limit.
  * The [Create custom events](/reference/create-custom-events) endpoint has its own rate limit, separate from the notification endpoints.
</Check>

***

## API rate limits

API rate limits apply **per app and per endpoint**. They are evaluated when a request is received, not when a response is returned.

These limits are designed to throttle traffic, not block your app.

| Endpoint                                                                                  | Rate limit                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create message](/reference/create-message) / [Cancel message](/reference/cancel-message) | **Free plans:** 150 requests/sec/app<br />**Paid plans:** 6,000 requests/sec/app<br /><br />The `POST /notifications` and `DELETE /notifications` endpoints share the same limit. Requests count toward it regardless of method. For example, 3,000 creates + 3,000 cancels = 6,000 requests/sec on a paid plan.<br /><br />Each request can target many users or segments. |
| [Create custom events](/reference/create-custom-events)                                   | Rate-limited independently from Create Message.<br />**Request size limits:** 2,024 bytes per event · 1 MB per request body                                                                                                                                                                                                                                                 |
| Create, update, or delete users or subscriptions                                          | 1,000 requests/sec/app<br />1 request/sec per user or subscription<br />Up to 100 property updates per request                                                                                                                                                                                                                                                              |
| View endpoints (messages, templates, users)                                               | 1 request/sec/app<br />Up to 10 look-back requests/sec                                                                                                                                                                                                                                                                                                                      |
| Message History and CSV exports                                                           | Keep parallel exports under 100 GB per file                                                                                                                                                                                                                                                                                                                                 |

<Note>
  High-volume messaging should use fewer message creation requests with larger audiences instead of increasing request frequency.
</Note>

**Handling API rate limit errors (`429`):**

When you exceed an API rate limit, OneSignal returns an HTTP `429` response:

```json theme={null}
{
  "errors": ["API rate limit exceeded."]
}
```

The response includes a `Retry-After` header indicating how many seconds to wait before retrying.

**What to do when you receive a `429` error:**

1. Stop sending requests immediately.
2. Wait for the full duration specified in the `Retry-After` header.
3. Retry using exponential backoff.
4. Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for retries that send messages.

<Warning>
  Retrying before the `Retry-After` delay or retrying in tight loops can extend throttling and increase failure rates.
</Warning>

***

## Error handling and retry strategies

Retries are safe only when implemented correctly. Some failed requests may still be processing on our servers.

* Retriable errors generally include network timeouts, no responses, 429, and 5xx errors.
* Non-retryable errors include 400, 401, or 403 errors which indicate invalid input, authentication problems, or missing permissions. These are not temporary failures.

**Simple retry strategy:**

* Wait **100 seconds** before retrying.
  * This aligns with the maximum API response timeout.
  * If no response or network error occurs, the request may still be processing during this window.
* Retry **up to 3 total attempts** (original + 2 retries).
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

**Time-sensitive (advanced) retry strategy:**

* Retry using exponential backoff with jitter (for example: 2s, 4s, 8s… up to 60s).
* Cap retries to **10 total attempts** and stop after **10–15 minutes**.
* For `429` responses, treat `Retry-After` as a minimum delay: wait `max(Retry-After, backoff)`.
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

<Warning>
  Retrying message or custom event API requests without idempotency can result in duplicate messages or custom events.
</Warning>

<Accordion title="Example retry logic">
  ```text theme={null}
  attempt = 1
  max_attempts = 3

  send request with idempotency_key

  if response is success:
    stop

  if response is 429:
    wait Retry-After seconds
  elif response is 5xx or timeout:
    wait 100 seconds

  if attempt < max_attempts:
    retry with same idempotency_key
  else:
    fail safely
  ```
</Accordion>

### Retry decision guide

| Error type              | Retry? | When                 | Idempotency required |
| ----------------------- | ------ | -------------------- | -------------------- |
| `429 Too Many Requests` | Yes    | After `Retry-After`  | Yes                  |
| `5xx Server Error`      | Yes    | Backoff or 100s      | Yes                  |
| Timeout / no response   | Yes    | Immediate or delayed | Yes                  |
| `400 Bad Request`       | No     | Fix request          | No                   |
| `401 / 403`             | No     | Fix auth/permissions | No                   |

<Warning>
  Common implementation mistakes:

  * Retrying with a new idempotency key on each attempt.
  * Retrying indefinitely without a retry cap.
  * Retrying `400` or `401` errors without fixing the request.
  * Sending one request per user instead of batching audiences.
</Warning>

***

## Application message limits (app disablement)

Application message limits protect your users from receiving too many notifications in a short period of time.

**How the limit works:**

In any rolling 15-minute window, you may send up to **10 × your total number of subscribed [Subscriptions](/docs/en/subscriptions)**.

This limit is based on the total number of messages delivered, not the number of API requests.

* Sending 1 notification to 1,000 Subscriptions = 1,000 messages
* Sending 10 notifications to 1,000 Subscriptions each = 10,000 messages

The 15-minute window is rolling, not fixed.

* Messages are counted for 15 minutes after they are sent
* As time passes, older messages automatically stop counting
* You only exceed the limit if more than 10× your subscribed Subscriptions receive messages within the same 15-minute span

Example limits:

* App with 1,000 subscribed Subscriptions → up to 10,000 messages in any 15 minutes
* App with 10,000 subscribed Subscriptions → up to 100,000 messages in any 15 minutes

**Example scenarios:** App with 1,000 subscribed Subscriptions (limit: 10,000 messages per 15 minutes)

| Scenario                                                                              | Messages counted in any 15-minute period |    App disabled?    |
| ------------------------------------------------------------------------------------- | ---------------------------------------: | :-----------------: |
| At **12:00**, send 1 notification to 1,000 users                                      |                                    1,000 |          No         |
| At **12:00**, send 10 notifications to 1,000 users                                    |                                   10,000 |   Yes (hits limit)  |
| Between **12:00–12:14**, send 10,000 notifications to 1 user                          |                                   10,000 |   Yes (hits limit)  |
| Send **9,000 messages at 12:00**, then **9,000 more at 12:16**                        |                                    9,000 |          No         |
| Send **9,000 messages spread between 12:00–12:14**, then send **9,000 more at 12:15** |                                 \~18,000 | Yes (exceeds limit) |

<Note> This limit is evaluated continuously over a rolling 15-minute window, not in fixed time blocks. If any 15-minute span exceeds your limit, the app is disabled. </Note>

**What happens if the limit is exceeded:**

If your app sends more messages than allowed within a 15-minute window:

* Your app is temporarily disabled
* All app administrators receive an email notification
* A re-enable banner appears in the OneSignal Dashboard

<Warning> Only application message limits can disable your app. API rate limits (`429` errors) never disable apps. </Warning>

**What to do if your app is disabled:**

If your app is disabled, follow these steps in order:

1. Pause message sending from your backend, jobs, or automations.
2. Identify the cause, such as infinite loops, retry storms, or unexpected segment growth.
3. Log in to the OneSignal Dashboard.
4. Click **Re-enable** in the red banner at the top of the app.
5. If you need help re-enabling your app, contact `support@onesignal.com`.

***

## FAQ

### Do API rate limits disable my app?

No. API rate limits (`429` errors) only throttle your requests temporarily. Only [application message limits](#application-message-limits-app-disablement) — which track the total volume of messages delivered — can disable your app.

### What is an idempotency key and when do I need one?

An idempotency key is a unique identifier you include with a request so that retrying the same request does not create a duplicate message or event. You need one whenever you retry a `POST /notifications` or custom event request. Reuse the same key for every retry attempt. See [Idempotent API requests](/reference/idempotent-notification-requests).

### Can I increase my API rate limit?

Paid plans have higher rate limits (6,000 requests/sec vs. 150 for free plans). If you need limits beyond the paid tier, contact `support@onesignal.com` with your use case and expected volume.

### Why was my app disabled even though I didn't hit the API rate limit?

API rate limits and application message limits are separate. Your app can be disabled if the total number of messages delivered in any 15-minute window exceeds 10× your subscription count — even if every individual API request succeeded. Common causes include retry storms, runaway automations, or targeting a larger audience than intended.

***

## Related pages

<Columns>
  <Card title="Idempotent API requests" icon="rotate" href="/reference/idempotent-notification-requests">
    Prevent duplicate messages by reusing idempotency keys on retries.
  </Card>

  <Card title="Create message API" icon="paper-plane" href="/reference/create-message">
    API reference for sending push, email, SMS, and in-app messages.
  </Card>

  <Card title="Create custom event API" icon="bolt" href="/reference/create-custom-events">
    API reference for sending custom events that trigger Journeys.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="/docs/en/subscriptions">
    Understand how subscriptions are counted toward message limits.
  </Card>
</Columns>


# REST API overview
Source: https://documentation.onesignal.com/reference/rest-api-overview

Programmatic access to OneSignal messaging, user management, segments, and data exports over HTTPS with rate limiting and retry support.

The OneSignal REST API follows the [REST architecture](https://en.wikipedia.org/wiki/Representational_state_transfer) and provides programmatic access to core messaging and user features. Use the API to send push notifications, emails, and SMS, manage Users, Subscriptions, Segments, export data, and configure apps.

## Which API to use

| Goal                          | API                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| Send a push, email, or SMS    | [Create Message](/reference/create-message)                                                              |
| Add or update user data       | [Create User](/reference/create-user) / [Update User](/reference/update-user)                            |
| Target a group of users       | [Create Segments](/reference/create-segments) or use [Filters](/reference/create-message#filters) inline |
| Export analytics or user data | [CSV Export](/reference/csv-export) / [CSV of Events](/reference/export-csv-of-events)                   |
| Manage app configuration      | [Create App](/reference/create-an-app) / [Update App](/reference/update-an-app)                          |

***

## Requirements

**General**

* **HTTPS required**: All API requests must use HTTPS with **TLS 1.2 or higher** on port `443`.
* **Network access**: Firewalls or proxies must allow **outbound traffic** to `https://api.onesignal.com` on port `443`.
* **DNS TTL**: Clients must respect OneSignal’s DNS **TTL of 300 seconds** to avoid stale IP resolution.

**Incoming Traffic to OneSignal (API & SDK Requests)**

All incoming API traffic—whether from your backend, the OneSignal SDKs, or the dashboard—passes through **Cloudflare**, which serves as the global edge network.

* You may see Cloudflare IP addresses in logs.
* Cloudflare IPs may change over time.
* If you maintain a strict firewall, use Cloudflare’s official [IP ranges](https://www.cloudflare.com/ips/)

<Warning>
  Avoid allowlisting specific Cloudflare IPs, as they may change without notice.
</Warning>

**Outgoing Traffic from OneSignal (Webhooks & Event Streams)**

For features where OneSignal sends HTTP requests to your servers (such as webhooks or event streams), traffic originates from OneSignal infrastructure running on Google Cloud Platform (GCP) in the `europe-west4` region (Groningen, Netherlands).

* Allow inbound traffic from `https://api.onesignal.com`, **or**
* Use GCP’s maintained IP range list and filter by `europe-west4` region: [GCP IP ranges](https://www.gstatic.com/ipranges/cloud.json)

<Note>
  OneSignal supports [IP allowlisting](/docs/en/keys-and-ids) with REST API keys.
</Note>

***

### Platform-specific network requirements

#### FCM (Google Android and Chrome push)

* Required ports: `5228`, `443`, `5229`, and `5230`
* No IP allowlisting needed
* More info: [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

#### APNs (Apple iOS, iPadOS, Safari push)

* Required ports: `5223`, `443`, and `2197`
* Recommended servers:
  * Sandbox: `api.sandbox.push.apple.com:443`
  * Production: `api.push.apple.com:443`
  * IP range: `17.0.0.0/8`
* More info:
  * [Apple Support](https://support.apple.com/en-us/102266)
  * [APNs Developer Docs](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns?language=objc)

***

## Core API capabilities

### Send messages

See the [Create Message guide](/reference/create-message) to get started. Programmatically send:

<Columns>
  <Card title="Push Notifications" icon="bell" href="/reference/push-notification">
    Send push notifications to apps and websites.
  </Card>

  <Card title="Email" icon="envelope" href="/reference/email">
    Send transactional and promotional emails.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/reference/sms">
    Send SMS or MMS messages globally.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="/reference/start-live-activity">
    Send Live Activity updates to iOS devices.
  </Card>
</Columns>

<Note>
  For platform-specific features like personalization, throttling, and frequency capping, see the [Push](/docs/en/push), [Email](/docs/en/email-messaging), [SMS](/docs/en/sms-messaging), and [Live Activities](/docs/en/live-activities) overview guides.
</Note>

***

### Manage templates

[Templates](/docs/en/templates) are reusable push, email, and SMS messages that simplify development and improve consistency.

<Columns>
  <Card title="Create template" icon="plus" href="/reference/create-template">
    Save a reusable message layout for push, email, or SMS.
  </Card>

  <Card title="Update template" icon="pen-to-square" href="/reference/update-template">
    Modify an existing template's content or settings.
  </Card>

  <Card title="View templates" icon="eye" href="/reference/view-templates">
    List all templates in your app with their metadata.
  </Card>

  <Card title="Delete template" icon="trash" href="/reference/delete-template">
    Permanently remove a template from your app.
  </Card>
</Columns>

***

### Track custom events

[Custom events](/docs/en/custom-events) record user actions like purchases, content views, or milestones. Use them to enter users into [Journeys](/docs/en/journeys-settings) or trigger [Wait Until](/docs/en/journeys-actions) nodes.

<Card title="Create custom events" icon="bolt" href="/reference/create-custom-events">
  Record user events to trigger Journeys and track behavior.
</Card>

***

### Manage Users and Subscriptions

See the [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) guides for more details.

<Columns>
  <Card title="Create user" icon="user-plus" href="/reference/create-user">
    Create a user with optional aliases and subscriptions.
  </Card>

  <Card title="View user" icon="eye" href="/reference/view-user">
    View user details.
  </Card>

  <Card title="Update user" icon="user-pen" href="/reference/update-user">
    Modify a User's properties, tags, or aliases.
  </Card>

  <Card title="Delete user" icon="user-minus" href="/reference/delete-user">
    Permanently remove a User and all associated data.
  </Card>
</Columns>

***

### Manage Segments

[Segments](/docs/en/segmentation) group Users by filters for targeted messaging.

<Columns>
  <Card title="Create Segments" icon="plus" href="/reference/create-segments">
    Define a new Segment with filters to group Users.
  </Card>

  <Card title="Update Segment" icon="pen-to-square" href="/reference/update-segment">
    Modify a Segment's name or replace its filters.
  </Card>

  <Card title="Delete Segments" icon="trash" href="/reference/delete-segments">
    Permanently remove a Segment from your app.
  </Card>
</Columns>

<Note>
  You can also target users dynamically using [filters](/reference/create-message#filters) without creating persistent segments.
</Note>

***

### Export data

For analytics breakdowns, see [Analytics overview](/docs/en/analytics-overview).

<Columns>
  <Card title="Export CSV of subscriptions" icon="file-export" href="/reference/csv-export">
    Export all user and subscription data.
  </Card>

  <Card title="Export CSV of events" icon="file-export" href="/reference/export-csv-of-events">
    Export events like sent, received, and clicked.
  </Card>

  <Card title="View messages" icon="eye" href="/reference/view-messages">
    View message details and analytics.
  </Card>

  <Card title="View message" icon="magnifying-glass" href="/reference/view-message">
    View individual message details.
  </Card>
</Columns>

***

### Manage Apps & API Keys

OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See [Apps, orgs, & accounts](/docs/en/apps-organizations).

<Columns>
  <Card title="Create an app" icon="plus" href="/reference/create-an-app">
    Register a new app with platform credentials.
  </Card>

  <Card title="Update an app" icon="pen-to-square" href="/reference/update-an-app">
    Modify app settings or platform credentials.
  </Card>

  <Card title="View single app" icon="eye" href="/reference/view-an-app">
    Retrieve configuration and details for one app.
  </Card>

  <Card title="View multiple apps" icon="list" href="/reference/view-apps">
    List all apps in your account.
  </Card>
</Columns>

#### API key management

See [Keys & IDs](/docs/en/keys-and-ids) for more details.

<Columns>
  <Card title="Create API key" icon="key" href="/reference/create-api-key">
    Generate a new API key with specific permissions.
  </Card>

  <Card title="View API keys" icon="eye" href="/reference/view-api-keys">
    List all API keys and their permissions for your app.
  </Card>

  <Card title="Delete API key" icon="trash" href="/reference/delete-api-key">
    Revoke an API key permanently.
  </Card>

  <Card title="Update API key" icon="pen-to-square" href="/reference/update-api-key">
    Modify an API key's permissions or IP allowlist.
  </Card>
</Columns>

***

## Error handling and retries

The OneSignal API may return temporary errors such as `429` (rate limited), `5xx` (server errors), or timeouts. When this happens, the request may still be processing. If you retry failed requests, always use an `idempotency_key` and follow the recommended retry delays to avoid duplicate messages.

<Card title="Rate limits and error handling" icon="triangle-exclamation" href="/reference/rate-limits">
  Retry strategies, error definitions, and recovery steps.
</Card>

***

## FAQ

### What is the timeout for API responses?

* Default: **100 seconds**
* If you're unsure whether a request completed, use an [`idempotency_key`](/reference/idempotent-notification-requests) to safely retry.
* See [Rate limits and error handling](/reference/rate-limits) for more details.

### Do I need to download or renew certificates to call the OneSignal API?

No. The OneSignal API uses HTTPS with a publicly trusted TLS certificate managed by Cloudflare. These edge certificates renew automatically and are trusted by all major browsers, operating systems, and runtimes.

If your network pins a specific leaf certificate, it will expire and rotate every few months — this is normal Cloudflare behavior. Trust the root and intermediate CAs in the chain instead of the leaf certificate to avoid disruption.

<Accordion title="Certificate pinning details and workarounds">
  * **Best practice**: Trust the root and intermediate CAs in the chain instead of the rotating leaf certificate.
  * **If you must pin a certificate**: Pin the public key (SPKI) of the CA or use a backup key set, not the exact leaf certificate.
  * **Fetching the current certificate**: If your process requires the active leaf certificate, retrieve it directly:

  ```bash theme={null}
  SERVERNAME=api.onesignal.com
  echo -n | openssl s_client -connect $SERVERNAME:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/${SERVERNAME}_current.pem
  ```

  To retrieve the full chain, add the `-showcerts` flag to `openssl s_client`.

  See [Cloudflare SSL/TLS documentation](https://developers.cloudflare.com/ssl/get-started/) and [Cloudflare Edge Certificates documentation](https://developers.cloudflare.com/ssl/edge-certificates/) for more details.
</Accordion>

### Why am I getting a 403 Forbidden error?

A `403` response means the API key is valid but does not have permission for the requested operation. Check the following:

* **Wrong key type**: App API keys work for app-level endpoints (sending messages, managing Users). Organization API keys are required for org-level endpoints (creating apps, managing API keys). See [Keys & IDs](/docs/en/keys-and-ids) for details.
* **IP allowlisting**: If IP allowlisting is enabled on your API key, requests from IPs not on the list are denied. Verify your server's IP is included.
* **Revoked or rotated key**: If the key was recently rotated, the old key is no longer valid. Update your integration with the new key.

### Why am I getting "UnknownHostException - Unable to resolve host api.onesignal.com"?

This error means your environment cannot resolve the DNS for `api.onesignal.com`. Common causes:

* **Firewall or proxy blocking DNS**: Ensure your network allows outbound DNS queries and traffic to `api.onesignal.com` on port `443`.
* **No internet connectivity**: Verify the device or server has an active network connection.
* **DNS server misconfiguration**: Try a public DNS resolver like `8.8.8.8` (Google) or `1.1.1.1` (Cloudflare) to rule out local DNS issues.
* **Stale DNS cache**: Flush your local DNS cache and ensure your client respects the TTL of 300 seconds.


# SMS
Source: https://documentation.onesignal.com/reference/sms

POST /notifications?c=sms
Send a message using the SMS channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for SMS and MMS. See [Push notification](/reference/push-notification) or [Email](/reference/email) to send to those channels.

Ensure your [SMS setup](/docs/en/sms-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***

## Trackable links

Add trackable links to your SMS `contents` using [liquid syntax](/docs/en/using-liquid-syntax) in the format `{{'your_url' | track_link}}`.

Example:

```json JSON theme={null}
{
  "contents": {
    "en": "Hi, here's my link: {{'https://example.com' | track_link}} "
  }
}
```

In this example, the liquid syntax block will be replaced with a trackable short link and display in the message as: `1sgnl.co/XXXX`.

<Note>
  See [SMS trackable links](/docs/en/links#sms) for more details.
</Note>

***


# Start Live Activity
Source: https://documentation.onesignal.com/reference/start-live-activity

POST /apps/{app_id}/activities/activity/{activity_type}
Remotely start a Live Activity on iOS devices via OneSignal's REST API. Define the activity type, target users, and send dynamic, updatable content directly to a Live Activity interface.

## Overview

Remotely start an iOS Live Activity using OneSignal’s REST API. Live Activities provide real-time updates directly on the lock screen and Dynamic Island (on supported devices), enhancing user engagement with ongoing events like sports games, deliveries, or countdowns.

***

## How to use this API

1. Define a Live Activity in your app. See [Live Activities developer setup](/docs/en/live-activities-developer-setup) to get started.
2. Use the `activity_type` parameter to specify the type of the Live Activity UI to use.
3. Select your target audience to receive the Live Activity. Target all or individual users.
4. Generate a unique `activity_id` to track and manage your Live Activity.
5. Use the `event_attributes` parameter to initialize the Live Activity with static data.
6. Use the `event_updates` parameter to update the Live Activity with dynamic content.

### Select your target audience

Before sending a message, you need to determine who should receive it. OneSignal offers three targeting options:

1. **Aliases & Subscription IDs**: Send messages to specific users using unique identifiers such as External ID (recommended), OneSignal ID, custom alias, or subscription ID.
2. **Segments**: Target predefined user groups based on attributes and behavior.
3. **Filters**: Create custom targeting rules using user properties, such as tags, location, or activity.

<Note>
  You can only use one targeting method per message. For example, you cannot combine alias-based targeting with filters in the same request.

  See [Select your target audience](/reference/create-message#select-your-target-audience) for more information.
</Note>

### Set a unique `activity_id`

* Set a unique `activity_id` to track and manage the Live Activity. This value is crucial for maintaining a consistent reference to the Live Activity across different devices and sessions. Consider using a UUID, CUID, or NanoID for this parameter.
* Ensure that the `activity_id` is unique and consistently used for each Live Activity to avoid conflicts and ensure accurate tracking.

  ```json Example theme={null}
  {
    "activity_id": "217aae2b-42ee-4097-bc3f-b7a6e9d15b9b",
    ...
  }
  ```

<Info>
  See [Live Activities developer setup](/docs/en/live-activities-developer-setup) guide for more information.
</Info>

### Set `event_attributes` to initialize the Live Activity

Set default/static data to display in the Live Activity upon start.

```json Example theme={null}
{
  "event_attributes": {
  	"awayTeam": "Away Team Name",
    "homeTeam": "Home Team Name"
  }
}
```

### Set `event_updates` for dynamic content

The content used to update a running Live Activity. The object must conform to the `ContentState` interface defined within your app's Live Activity. See [Live Activities developer setup](/docs/en/live-activities-developer-setup).

Ensure that the `event_updates` object matches the [`ContentState`](https://developer.apple.com/documentation/activitykit/activityattributes/contentstate#) interface exactly as defined in your Live Activity implementation. Inconsistencies can cause Live Activities to fail to display.

```json Example theme={null}
{
  "event_updates": {
    "quarter": 1,
    "homeScore": 70,
    "awayScore": 78,
    "inTimeout": false
  }
}
```

***


# Update Live Activity
Source: https://documentation.onesignal.com/reference/update-live-activity-api

POST /apps/{app_id}/live_activities/{activity_id}/notifications
Update or terminate running iOS Live Activities using OneSignal’s Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

## Overview

Update or terminate running iOS Live Activities using our REST API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

Before using this API, ensure your app is properly configured by following the [Live Activities developer setup](/docs/en/live-activities-developer-setup).

## How to Use this API

1. Select the Live Activity to update by specifying its `activity_id` in the URL. This is set when using the:

* [Start Live Activity API](/reference/start-live-activity)
* [Triggering it in-app](/docs/en/live-activities-developer-setup).
* [`LiveActivities.enter` SDK method](/docs/en/mobile-sdk-reference#enter)

2. Update the state of the Live Activity by setting the `event_updates` parameter to a JSON object that matches the structure of the `ActivityAttributes.ContentState` struct defined in your Live Activity widget extension.

3. When ready to terminate the Live Activity:

* Set the `event` parameter to `end`
* Include a `dismissal_date` if you want the Live Activity to be dismissed in less than 4 hours.
* Set the `dismissal_date` to a time in the past to dismiss the Live Activity immediately. User must have clicked "Allow" for the Live Activity to be removed programmatically.

<Warning>
  Once a Live Activity `activity_id` is ended, you cannot update it. This includes changing the `dismissal_date` or `event` parameter.

  If the Live Activity is not being dismissed immediately, it is either because:

  * The `activity_id` has already been ended.
  * The user has not clicked "Allow" for the Live Activity to be removed programmatically.
</Warning>

***


# Update user
Source: https://documentation.onesignal.com/reference/update-user

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}
Modify a user's properties.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint updates user-level properties for an existing user in your OneSignal app.

* To change a user's `identity` like `external_id` or custom [Aliases](/docs/en/aliases), use the [Create alias](/reference/create-alias) and [Delete alias](/reference/delete-alias) APIs.
* To manage a user's `subscriptions`, use the [Create Subscription by alias](/reference/create-subscription) or [Create user](/reference/create-user) APIs.

***

## How to use this API

You must supply an alias in the request path:

* `alias_label`: The type of identifier (e.g., `external_id`, `onesignal_id`, or a custom alias label).
* `alias_id`: The corresponding value for that label.

See [Users](/docs/en/users) and [Aliases](/docs/en/aliases) for more info.

***


# View message
Source: https://documentation.onesignal.com/reference/view-message

GET /notifications/{message_id}?app_id={app_id}
View the details of a single message and the Outcomes associated with it.

## Overview

The View message API allows you to fetch data from a single push, email, or SMS message at a time. If you want to get multiple messages at a time, use the [View messages](/reference/view-messages) API. In most cases, you will likely want to use [Event Streams](/docs/en/event-streams) instead.

Currently this API does not provide Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are only **accessible 30 days after creation**; however, messages sent using the OneSignal dashboard are accessible for the app's lifetime.

See our [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and (after giving your users some time to interact with the message) pull the data if desired.

For example, if you send a message targeting the `include_aliases` parameter, the response will include the aliases you set. If you send with the `included_segments` parameter, then the response will only provide the segments you set. When targeting segments or filters, you can use the [Export audience activity CSV](/reference/export-csv-of-events) API to get the user event data.

To view outcome data for the message, you must include the `outcome_name` parameter with the name of the outcome you want to fetch, along with the accompanying aggregation type (.count or .sum), for example: `os__click.count`. For more information on outcome definitions, see [View Outcomes](/reference/view-outcomes).

***


# View messages
Source: https://documentation.onesignal.com/reference/view-messages

GET /notifications?app_id={app_id}&limit={limit}&offset={offset}&kind={kind}&template_id={template_id}&time_offset={time_offset}
View the details for a collection of messages.

## Overview

The View messages API fetches data for up to 50 push, email, or SMS messages at a time. To fetch a single message, use the [View message](/reference/view-message) API. In most cases, use [Event Streams](/docs/en/event-streams) instead.

This API does not return Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are **retained for 30 days** after creation; messages sent through the OneSignal dashboard are retained for the app's lifetime.

See [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

Use time-offset pagination for sequential pulls of all messages, and standard pagination for ad-hoc queries. For ETL or bulk export pipelines, use [Event Streams](/docs/en/event-streams) instead.

Filter results to a specific message kind or template using the `kind` and `template_id` query parameters. Both filters work with either pagination style.

### Optimized pagination with time offset

To efficiently retrieve all available messages for an app, use `time_offset`-based pagination. When `time_offset` is specified, the sort order changes from descending to ascending — the oldest messages appear first based on the [`send_after` date](/reference/create-message#send-after).

#### Accepted `time_offset` values

* ISO 8601 formatted timestamp — for example, `2025-01-01T00:00:00.000Z` (January 1, 2025, at 00:00 UTC).
* Opaque cursor token (Base64-encoded) — provided in the API response as `next_time_offset`.

<Steps>
  <Step title="Initial fetch">
    To fetch messages from a specific date onward, set `time_offset` to an ISO 8601 formatted timestamp. For example, to retrieve messages sent since January 1, 2025: `time_offset=2025-01-01T00:00:00.000Z`.

    <Note>
      * `time_offset` cannot be used with the standard `offset` parameter.
      * `time_offset` excludes messages that match the exact timestamp to avoid duplicates.
      * The response includes `next_time_offset`, a cursor token for the next page. No decoding required. For example: `"next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="`
    </Note>
  </Step>

  <Step title="Fetch additional pages">
    Use `next_time_offset` from the previous response as the `time_offset` value in the next request. For example: `time_offset=MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw==`.
  </Step>

  <Step title="Continue until completion">
    Repeat the request until an empty `notifications` array is returned, indicating all messages have been fetched.
  </Step>

  <Step title="Handling new messages">
    Because results are sorted ascending, new messages are added to the end. To resume fetching from where you left off, reuse the last `next_time_offset` that returned an empty response.
  </Step>
</Steps>

### Standard pagination

Use the `limit` and `offset` parameters to page through notifications for an app. The maximum result size is 50, and the default `limit` is `50`. Use `limit` to specify the result size and `offset` to increment by the limit value with each request.

For example, the first request uses `offset=0`, the second `offset=50`, the third `offset=100`, and so on.

Standard pagination is convenient for ad-hoc queries but degrades as the `offset` value grows. For sequential pulls of all messages, use time-offset pagination.

***


# View user
Source: https://documentation.onesignal.com/reference/view-user

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}
Retrieve a user including aliases, properties, and subscriptions.

## Overview

* Use this API to retrieve a user's full profile, including identity aliases, user properties, and messaging subscription details across channels.
* This is helpful for verifying user data, debugging subscription issues, or syncing OneSignal user data with your internal systems.

For detailed concepts and guides, see [Users](/docs/en/users), [Subscriptions](/docs/en/subscriptions), and [Aliases](/docs/en/aliases) documentation.

## How to use this API

To look up a user, you must provide both an `alias_label` and an `alias_id`. In most cases, your `external_id` will serve as the `alias_label`, and its value will be passed as the `alias_id`. While you may use a custom alias, we strongly recommend setting and using the `external_id` as your primary user identifier for consistency across platforms.

To retrieve a user using their OneSignal ID, set the `alias_label` to `onesignal_id`. **Note**: When querying with any alias other than `onesignal_id`, authentication is required.

***


# Server SDK reference
Source: https://documentation.onesignal.com/docs/en/server-sdk-reference

Install, configure, and use OneSignal server SDKs to send push notifications, emails, and SMS from your backend in Node.js, Python, Java, Go, PHP, Ruby, C#, and Rust.

All OneSignal server SDKs are generated from the same OpenAPI specification, so they share a consistent interface regardless of language. Each SDK wraps the [OneSignal REST API](/reference/create-message) and provides typed models for requests and responses.

## Available SDKs

| Language  | Package                                                                                            | Repository                                                  |
| --------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Node.js   | [@onesignal/node-onesignal](https://www.npmjs.com/package/@onesignal/node-onesignal)               | [GitHub](https://github.com/OneSignal/node-onesignal)       |
| Python    | [onesignal-python-api](https://pypi.org/project/onesignal-python-api/)                             | [GitHub](https://github.com/OneSignal/onesignal-python-api) |
| Java      | [onesignal-java-client](https://central.sonatype.com/artifact/com.onesignal/onesignal-java-client) | [GitHub](https://github.com/OneSignal/onesignal-java-api)   |
| Go        | [onesignal-go-api](https://pkg.go.dev/github.com/OneSignal/onesignal-go-api)                       | [GitHub](https://github.com/OneSignal/onesignal-go-api)     |
| PHP       | [onesignal/onesignal-php-api](https://packagist.org/packages/onesignal/onesignal-php-api)          | [GitHub](https://github.com/OneSignal/onesignal-php-api)    |
| Ruby      | [onesignal](https://rubygems.org/gems/onesignal)                                                   | [GitHub](https://github.com/OneSignal/onesignal-ruby-api)   |
| C# (.NET) | [OneSignalApi](https://www.nuget.org/packages/OneSignalApi)                                        | [GitHub](https://github.com/OneSignal/onesignal-dotnet-api) |
| Rust      | [onesignal-rust-api](https://crates.io/crates/onesignal-rust-api)                                  | [GitHub](https://github.com/OneSignal/onesignal-rust-api)   |

***

## Installation

<Note>
  Version numbers below are examples. Check the package registry for each SDK to install the latest version.
</Note>

<Tabs>
  <Tab title="Node.js">
    ```bash theme={null}
    npm install @onesignal/node-onesignal
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install onesignal-python-api
    ```
  </Tab>

  <Tab title="Java">
    **Maven**

    ```xml theme={null}
    <dependency>
      <groupId>com.onesignal</groupId>
      <artifactId>onesignal-java-client</artifactId>
      <version>5.3.0</version>
    </dependency>
    ```

    **Gradle**

    ```groovy theme={null}
    implementation "com.onesignal:onesignal-java-client:5.3.0"
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/OneSignal/onesignal-go-api/v5
    ```
  </Tab>

  <Tab title="PHP">
    Add to `composer.json`:

    ```json theme={null}
    {
      "require": {
        "onesignal/onesignal-php-api": "^5.3"
      }
    }
    ```

    Then run `composer update`.
  </Tab>

  <Tab title="Ruby">
    Add to your `Gemfile`:

    ```ruby theme={null}
    gem 'onesignal', '~> 5.3'
    ```

    Then run `bundle install`.
  </Tab>

  <Tab title="C# (.NET)">
    ```bash theme={null}
    dotnet add package OneSignalApi
    ```
  </Tab>

  <Tab title="Rust">
    Add to `Cargo.toml` under `[dependencies]`:

    ```toml theme={null}
    onesignal-rust-api = "5.3.0"
    ```
  </Tab>
</Tabs>

***

## Configuration

Every SDK requires authentication via API keys. Two key types are available:

* **REST API Key** — required for most endpoints (sending notifications, managing users, etc.). Found in your app's **Settings > Keys & IDs**.
* **Organization API Key** — only required for organization-level endpoints like creating or listing apps. Found in **Organization Settings**.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const OneSignal = require('@onesignal/node-onesignal');

    const configuration = OneSignal.createConfiguration({
      restApiKey: 'YOUR_REST_API_KEY',
      organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',
    });

    const client = new OneSignal.DefaultApi(configuration);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import onesignal
    from onesignal.api import default_api

    configuration = onesignal.Configuration(
        rest_api_key='YOUR_REST_API_KEY',
        organization_api_key='YOUR_ORGANIZATION_API_KEY',
    )

    with onesignal.ApiClient(configuration) as api_client:
        client = default_api.DefaultApi(api_client)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.onesignal.client.ApiClient;
    import com.onesignal.client.Configuration;
    import com.onesignal.client.auth.HttpBearerAuth;
    import com.onesignal.client.api.DefaultApi;

    ApiClient defaultClient = Configuration.getDefaultApiClient();

    HttpBearerAuth restApiAuth = (HttpBearerAuth) defaultClient
        .getAuthentication("rest_api_key");
    restApiAuth.setBearerToken("YOUR_REST_API_KEY");

    HttpBearerAuth orgApiAuth = (HttpBearerAuth) defaultClient
        .getAuthentication("organization_api_key");
    orgApiAuth.setBearerToken("YOUR_ORGANIZATION_API_KEY");

    DefaultApi client = new DefaultApi(defaultClient);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import onesignal "github.com/OneSignal/onesignal-go-api"

    restAuth := context.WithValue(
        context.Background(),
        onesignal.RestApiKey,
        "YOUR_REST_API_KEY",
    )

    orgAuth := context.WithValue(
        restAuth,
        onesignal.OrganizationApiKey,
        "YOUR_ORGANIZATION_API_KEY",
    )

    apiClient := onesignal.NewAPIClient(onesignal.NewConfiguration())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use onesignal\client\api\DefaultApi;
    use onesignal\client\Configuration;
    use GuzzleHttp;

    $config = Configuration::getDefaultConfiguration()
        ->setRestApiKeyToken('YOUR_REST_API_KEY')
        ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');

    $client = new DefaultApi(
        new GuzzleHttp\Client(),
        $config
    );
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'onesignal'

    OneSignal.configure do |config|
      config.rest_api_key = 'YOUR_REST_API_KEY'
      config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'
    end

    client = OneSignal::DefaultApi.new
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    using OneSignalApi.Api;
    using OneSignalApi.Client;

    var config = new Configuration();
    config.BasePath = "https://api.onesignal.com";
    config.AccessToken = "YOUR_REST_API_KEY";

    var client = new DefaultApi(config);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use onesignal::apis::configuration::Configuration;

    fn create_configuration() -> Configuration {
        let mut config = Configuration::new();
        config.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
        config.organization_api_key_token = Some("YOUR_ORGANIZATION_API_KEY".to_string());
        config
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Store your API keys in environment variables or a secrets manager. Never commit them to source control.
</Warning>

***

## Send a push notification

Send push notifications to web and mobile [Subscriptions](./subscriptions) by targeting a segment. These examples show the happy path — add error handling (try/catch, error callbacks) for production use.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.contents = { en: 'Hello from OneSignal!' };
    notification.headings = { en: 'Push Notification' };
    notification.included_segments = ['Subscribed Users'];

    const response = await client.createNotification(notification);
    console.log('Notification ID:', response.id);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        contents=onesignal.StringMap(en='Hello from OneSignal!'),
        headings=onesignal.StringMap(en='Push Notification'),
        included_segments=['Subscribed Users'],
    )

    response = client.create_notification(notification)
    print('Notification ID:', response.id)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.onesignal.client.model.Notification;
    import com.onesignal.client.model.StringMap;

    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");

    StringMap contents = new StringMap();
    contents.en("Hello from OneSignal!");
    notification.setContents(contents);

    StringMap headings = new StringMap();
    headings.en("Push Notification");
    notification.setHeadings(headings);

    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));

    var response = client.createNotification(notification);
    System.out.println("Notification ID: " + response.getId());
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Hello from OneSignal!")})
    notification.SetHeadings(onesignal.StringMap{En: onesignal.PtrString("Push Notification")})
    notification.SetIncludedSegments([]string{"Subscribed Users"})

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()

    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Notification ID:", response.GetId())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use onesignal\client\model\Notification;
    use onesignal\client\model\StringMap;

    $content = new StringMap();
    $content->setEn('Hello from OneSignal!');

    $headings = new StringMap();
    $headings->setEn('Push Notification');

    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setContents($content);
    $notification->setHeadings($headings);
    $notification->setIncludedSegments(['Subscribed Users']);

    $response = $client->createNotification($notification);
    echo 'Notification ID: ' . $response->getId();
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      contents: { en: 'Hello from OneSignal!' },
      headings: { en: 'Push Notification' },
      included_segments: ['Subscribed Users']
    })

    response = client.create_notification(notification)
    puts "Notification ID: #{response.id}"
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    using OneSignalApi.Model;

    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        Contents = new StringMap(en: "Hello from OneSignal!"),
        Headings = new StringMap(en: "Push Notification"),
        IncludedSegments = new List<string> { "Subscribed Users" }
    };

    var response = client.CreateNotification(notification);
    Console.WriteLine("Notification ID: " + response.Id);
    ```

    Note: .NET SDK does not normalize newline characters automatically. If your content contains `\r\n` normalize it before passing to `Contents`:

    ```csharp theme={null}
    var normalizedContent = yourContent
       .Replace("\\r\\n", "\n")
       .Replace("\\n", "\n")
       .Replace("\r\n", "\n")
       .Replace("\r", "\n");
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use onesignal::apis::default_api;
    use onesignal::models::{Notification, StringMap};

    let mut contents = StringMap::new();
    contents.en = Some("Hello from OneSignal!".to_string());

    let mut headings = StringMap::new();
    headings.en = Some("Push Notification".to_string());

    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.contents = Some(Box::new(contents));
    notification.headings = Some(Box::new(headings));
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);

    let config = create_configuration();
    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Send an email

Send emails to [Subscriptions](./subscriptions) with the `email` channel.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.email_subject = 'Important Update';
    notification.email_body = '<h1>Hello!</h1><p>This is an HTML email.</p>';
    notification.included_segments = ['Subscribed Users'];
    notification.channel_for_external_user_ids = 'email';

    const response = await client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        email_subject='Important Update',
        email_body='<h1>Hello!</h1><p>This is an HTML email.</p>',
        included_segments=['Subscribed Users'],
        channel_for_external_user_ids='email',
    )

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");
    notification.setEmailSubject("Important Update");
    notification.setEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>");
    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
    notification.setChannelForExternalUserIds("email");

    var response = client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetEmailSubject("Important Update")
    notification.SetEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>")
    notification.SetIncludedSegments([]string{"Subscribed Users"})
    notification.SetChannelForExternalUserIds("email")

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setEmailSubject('Important Update');
    $notification->setEmailBody('<h1>Hello!</h1><p>This is an HTML email.</p>');
    $notification->setIncludedSegments(['Subscribed Users']);
    $notification->setChannelForExternalUserIds('email');

    $response = $client->createNotification($notification);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      email_subject: 'Important Update',
      email_body: '<h1>Hello!</h1><p>This is an HTML email.</p>',
      included_segments: ['Subscribed Users'],
      channel_for_external_user_ids: 'email'
    })

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        EmailSubject = "Important Update",
        EmailBody = "<h1>Hello!</h1><p>This is an HTML email.</p>",
        IncludedSegments = new List<string> { "Subscribed Users" },
        ChannelForExternalUserIds = "email"
    };

    var response = client.CreateNotification(notification);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.email_subject = Some("Important Update".to_string());
    notification.email_body = Some("<h1>Hello!</h1><p>This is an HTML email.</p>".to_string());
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
    notification.channel_for_external_user_ids = Some("email".to_string());

    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Send an SMS

Send SMS text messages to [Subscriptions](./subscriptions) with the `sms` channel.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.contents = { en: 'Your SMS message content here' };
    notification.included_segments = ['Subscribed Users'];
    notification.channel_for_external_user_ids = 'sms';
    notification.sms_from = '+15551234567';

    const response = await client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        contents=onesignal.StringMap(en='Your SMS message content here'),
        included_segments=['Subscribed Users'],
        channel_for_external_user_ids='sms',
        sms_from='+15551234567',
    )

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    StringMap contents = new StringMap();
    contents.en("Your SMS message content here");

    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");
    notification.setContents(contents);
    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
    notification.setChannelForExternalUserIds("sms");
    notification.setSmsFrom("+15551234567");

    var response = client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Your SMS message content here")})
    notification.SetIncludedSegments([]string{"Subscribed Users"})
    notification.SetChannelForExternalUserIds("sms")
    notification.SetSmsFrom("+15551234567")

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $content = new StringMap();
    $content->setEn('Your SMS message content here');

    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setContents($content);
    $notification->setIncludedSegments(['Subscribed Users']);
    $notification->setChannelForExternalUserIds('sms');
    $notification->setSmsFrom('+15551234567');

    $response = $client->createNotification($notification);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      contents: { en: 'Your SMS message content here' },
      included_segments: ['Subscribed Users'],
      channel_for_external_user_ids: 'sms',
      sms_from: '+15551234567'
    })

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        Contents = new StringMap(en: "Your SMS message content here"),
        IncludedSegments = new List<string> { "Subscribed Users" },
        ChannelForExternalUserIds = "sms",
        SmsFrom = "+15551234567"
    };

    var response = client.CreateNotification(notification);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let mut contents = StringMap::new();
    contents.en = Some("Your SMS message content here".to_string());

    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.contents = Some(Box::new(contents));
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
    notification.channel_for_external_user_ids = Some("sms".to_string());
    notification.sms_from = Some("+15551234567".to_string());

    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Full API reference

Each server SDK supports the same set of API endpoints. Refer to your SDK's API documentation for the complete method list, including users, subscriptions, segments, templates, and more.

| SDK       | API reference                                                                                     |
| --------- | ------------------------------------------------------------------------------------------------- |
| Node.js   | [DefaultApi.md](https://github.com/OneSignal/node-onesignal/blob/main/DefaultApi.md)              |
| Python    | [DefaultApi.md](https://github.com/OneSignal/onesignal-python-api/blob/main/docs/DefaultApi.md)   |
| Java      | [DefaultApi.md](https://github.com/OneSignal/onesignal-java-api/blob/main/docs/DefaultApi.md)     |
| Go        | [DefaultApi.md](https://github.com/OneSignal/onesignal-go-api/blob/main/docs/DefaultApi.md)       |
| PHP       | [DefaultApi.md](https://github.com/OneSignal/onesignal-php-api/blob/main/docs/Api/DefaultApi.md)  |
| Ruby      | [DefaultApi.md](https://github.com/OneSignal/onesignal-ruby-api/blob/main/docs/DefaultApi.md)     |
| C# (.NET) | [DefaultApi.md](https://github.com/OneSignal/onesignal-dotnet-api/blob/main/docs/DefaultApi.md)   |
| Rust      | [default\_api docs](https://github.com/OneSignal/onesignal-rust-api/blob/main/docs/DefaultApi.md) |

For the underlying REST API, see the [complete API reference](/reference/create-message).

***

## FAQ

### Which server SDK should I choose?

Use the SDK that matches your backend language. All server SDKs are generated from the same OpenAPI specification and support the same endpoints, so functionality is identical across languages.

### What is the difference between the REST API Key and Organization API Key?

The **REST API Key** is scoped to a single app and is required for most operations like sending notifications and managing users. The **Organization API Key** is scoped to your organization and is only needed for creating or listing apps. Most integrations only need the REST API Key.

### Can I use the REST API directly instead of an SDK?

Yes. The server SDKs are convenience wrappers around the [OneSignal REST API](/reference/create-message). You can call the API directly using any HTTP client with the `key` authentication scheme (`Authorization: key YOUR_REST_API_KEY`).

### Are these SDKs auto-generated?

Yes. All server SDKs are generated from the OneSignal OpenAPI specification using [OpenAPI Generator](https://openapi-generator.tech). This ensures consistent API coverage across all languages.

***

## Related pages

<Columns>
  <Card title="REST API overview" icon="code" href="/reference/rest-api-overview">
    Endpoints, authentication, rate limits, and request/response formats.
  </Card>

  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    Find your App ID, REST API key, and Organization API key.
  </Card>

  <Card title="Transactional messages" icon="paper-plane" href="./transactional-messages">
    Send OTPs, receipts, and time-sensitive alerts via API with personalized data.
  </Card>

  <Card title="Identity verification" icon="shield-halved" href="./identity-verification">
    Secure your integration with server-generated JWTs to prevent User impersonation.
  </Card>
</Columns>


# Add a player
Source: https://documentation.onesignal.com/reference/add-a-device

POST `https://onesignal.com/api/v1/players`

Register a new Subscription (aka player) to one of your OneSignal apps.

<Warning>
  This is a Legacy API. Use [Create User](/reference/create-user) or [Create Subscription](/reference/create-subscription) instead.
</Warning>

***

## Headers

| Header          | Value                     | Required | Description                      |
| --------------- | ------------------------- | -------- | -------------------------------- |
| `Content-Type`  | `application/json`        | Yes      | The content type of the request. |
| `Authorization` | `Basic YOUR_REST_API_KEY` | Yes      | Your OneSignal REST API key.     |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                                |
| -------------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                                     |
| `device_type`        | integer | Yes      | Device platform: 0 = iOS, 1 = Android, 2 = Amazon, 3 = Windows Phone, etc. |
| `identifier`         | string  | No       | Push token, email address, or phone number.                                |
| `language`           | string  | No       | Language code (e.g. "en").                                                 |
| `timezone`           | integer | No       | Time zone offset in seconds.                                               |
| `game_version`       | string  | No       | Version of your app.                                                       |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                                         |
| `device_os`          | string  | No       | Operating system version (e.g., "13.3").                                   |
| `ad_id`              | string  | No       | Advertising ID.                                                            |
| `sdk`                | string  | No       | OneSignal SDK version (e.g., "050201" for 5.2.1).                          |
| `session_count`      | integer | No       | Number of times the user has used the app.                                 |
| `tags`               | object  | No       | Custom tags as key-value pairs.                                            |
| `external_user_id`   | string  | No       | Your system's user ID for this device.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc.                 |

***

## Example Request

```json theme={null}
POST /api/v1/players HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "device_type": 1,
  "identifier": "abcdef123456",
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_model": "Pixel 4",
  "device_os": "12",
  "ad_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sdk": "050401",
  "session_count": 5,
  "tags": {
    "user_type": "free",
    "level": "10"
  },
  "external_user_id": "user123",
  "notification_types": 1
}
```

***

## Response

```json theme={null}
{
  "id": "Subscription_id_string"
}
```

## Errors

* 400 Bad Request – Invalid parameters or missing required fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Not allowed for your account type or plan.


# Copy template to another app
Source: https://documentation.onesignal.com/reference/copy-template-to-another-app

POST /templates/{template_id}/copy_to_app?app_id={app_id}
Create a duplicate of a template in another app. The new template will be completely separate from the original (including having a new template_id) but will be created with all the same content.

## Overview

This API allows you to copy a template from one app (`app_id`) to another (`target_app_id`). The duplicated template will have the same content as the original, but a new unique `template_id`.

<Note>
  If you are trying to copy an email template, we also have an [Email Template Forwarding](/docs/en/email-template-forwarding) feature that does not require an API call.

  Both options support HTML and Drag & Drop email templates.
</Note>

***

## Requirements

* **Organization Membership:** Both the `app_id` and `target_app_id` must belong to the same [Organization](/docs/en/apps-organizations).
* **Authorization Required:** You must use your [Organization API key](/docs/en/keys-and-ids#organization-api-key), not an app-level REST API key.
* **Permissions Note:** Your user must have admin-level access to both the source and target apps. If not, the request will fail with a "permission denied" error.

***

## Parameters

* `template_id` (path param): UUID of the template to be copied.
* `app_id` (query param): ID of the app where the original template exists.
* `target_app_id` (body param): ID of the app where the template will be duplicated.

***

## How to Use

### 1. Locate the Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

### 2. Get App IDs

Refer to [Keys & IDs](/docs/en/keys-and-ids) to find your `app_id` and `target_app_id`.

***

## Response

The response will include:

* The new `template_id` for the copied template
* Confirmation of successful creation
* Any warnings if applicable (e.g., limited fields copied)

***


# Create or update alias
Source: https://documentation.onesignal.com/reference/create-alias

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Create or update one or more user aliases when you already know an existing alias. This API performs an upsert on the user’s identity object—either adding new aliases or updating existing ones.

## Overview

Use this API to manage user aliases by providing one known alias (such as `external_id`, `onesignal_id`, or a custom alias) and specifying additional aliases to add or update.

This endpoint focuses solely on the `identity` object. If you need to fully create a user with subscriptions and properties, use the [Create user](/reference/create-user) API instead.

<Note>
  * If an alias with the same `alias_label` already exists for the user, it will be updated. If it doesn’t exist, a new alias will be created.
  * Want to use a subscription instead of an alias to identify the user? Use [Create alias (by subscription)](/reference/create-alias-by-subscription).
</Note>

See also:

* [Users](/docs/en/users) – for details on OneSignal ID and External ID
* [Aliases](/docs/en/aliases) – for setting and managing custom aliases
* [Delete alias](/reference/delete-alias) – for removing aliases

***

## How to use this API

To identify the user:

* Use `alias_label` for the type of alias you know (e.g., `external_id`, `onesignal_id`, or a custom alias)
* Use `alias_id` for the value of that alias

<Note>
  We strongly recommend setting the `external_id` as your primary user identifier. This can be done through our frontend SDK's login method when a user signs in to your app or website. It helps OneSignal associate the user's push, email, and SMS subscriptions to a unified user identity.
</Note>

Changes to the identity object take effect immediately upon request.

Alias keys (`alias_label`) and values (`alias_id`) are each limited to **128 characters**. A user can have up to **10 custom aliases** total.

***


# Create alias (by subscription)
Source: https://documentation.onesignal.com/reference/create-alias-by-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Create or update an alias for a user using a known subscription ID.

Create or update an alias for a user using a known subscription ID.

# Overview

Use this API to add or update aliases associated with a user when you only know at least one subscription ID. This API is handy for scenarios where the user's identity is unknown, but a subscription is available.

To remove an alias, see [Delete alias](/reference/delete-alias) API.

***

# How to use this API

You must know the `subscription_id` of the subscription that belongs to the user in which you want to update. Subscription IDs are UUIDs generated by OneSignal and cannot change. See [Subscriptions](/docs/en/subscriptions) for details.

This endpoint performs an upsert—if the user already has an alias with the specified alias label, it gets updated; otherwise, a new alias will be created.

The request body must include an identity object containing one or more aliases to be created or updated.

The OneSignal ID is read-only and used only for fetching. See [Users](/docs/en/users) for details.

Aliases are updated immediately upon request.

***


# Create an app
Source: https://documentation.onesignal.com/reference/create-an-app

POST /apps
Programmatically create a new OneSignal app via the REST API. This guide explains required fields, supported platform configurations (Web, Android, iOS), and how to properly authenticate using your Organization API key.

## Overview

Use this API to programmatically create a new OneSignal app. This is useful for automating app setup, particularly when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need to Base64 encode your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns):

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates):

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Create API key
Source: https://documentation.onesignal.com/reference/create-api-key

POST /apps/{app_id}/auth/tokens
Use the OneSignal API to create a new Rich Authentication Token (App API Key) for a specific app. This guide explains how to authenticate with the Organization API key and configure optional IP allowlists using CIDR notation.

## Overview

Use this API to create a new **App API Key** (also called a **Rich Authentication Token**) for a specific OneSignal app. These keys are used to authenticate API requests at the app level and offer enhanced security features, including optional IP allowlisting.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

### IP allowlisting

By default, the API key will not be restricted to any specific IP addresses. To enable IP allowlisting, you need to set the `ip_allowlist_mode` parameter to `explicit` and provide a list of allowed IP addresses in the `ip_allowlist` parameter.

If you want to set the explicit range of IPs that can use this API key, add them by setting `ip_allowlist_mode` to `explicit` and in `ip_allowlist` add the IPs in CIDRs notation as an array of string values.

***


# Create segment
Source: https://documentation.onesignal.com/reference/create-segments

POST /apps/{app_id}/segments
Programmatically create segments in your OneSignal app using flexible filters and targeting rules.

## Overview

Use this API to create new [Segments](/docs/en/segmentation) programmatically. These segments are then accessible in the OneSignal Dashboard and usable in messages, Journeys, and in-app messaging campaigns.

<Note>
  To modify an existing segment, use the [Update segment](/reference/update-segment) API.
</Note>

***

## How to use this API

This endpoint allows your backend to define audience segments by passing in a combination of filters and logical operators like `"AND"` and `"OR"`, mirroring the segmentation capabilities of the OneSignal Dashboard.

### Name the segment

The name of the segment as it shows in the OneSignal dashboard and accessible via the `included_segments` and `excluded_segments` targeting parameters.

### Describe the segment

Optionally include a `description` (max 255 characters) to record the segment's purpose. The description is returned by the [View segments](/reference/view-segments) and [View segment](/reference/view-segment) APIs.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "10"}
  ]
}
```

### Define the `filters`

Available filters:

* [operator](#operator)
* [tag](#tag)
* [last\_session](#last_session)
* [first\_session](#first_session)
* [session\_count](#session_count)
* [session\_time](#session_time-1)
* [language](#language)
* [app\_version](#app_version)
* [location](#location)
* [country](#country)

### `operator`

**Description**

Allows you to combine or separate properties. Filters combined with an `"AND"` have higher priority than `"OR"` filters.

* `"AND"` = the 2+ connected filters must be satisfied for the recipient to be included. Filter entries use this by default and its not required to be included.
* `"OR"` = the 2 filters separated by the `"OR"` operator are mutually exclusive. The recipients only need to satisfy the conditions on either side of the `"OR"` operator.

<CodeGroup>
  ```json AND example theme={null}
  // Users must satisfy both filters to be included.
  // Notice the AND operator is not required

  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  // The same example using the AND operator. This is not required.
  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "AND"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  ```

  ```json OR example theme={null}
  // Users can satisfy either filter to be included.

  "filters": [
    {"field": "tag", "key": "level", "relation": "=", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "level", "relation": "=", "value": "20"}
  ]
  ```

  ```json Combinations theme={null}
  // In this example, users must either have:
  // The specified session_count AND tag requirement
  // Or it will be all records where last_session is satisfied
  {
    "name": "2 filters or 1",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"}
    ]
  }

  // Similar to the first example, this shows how to require a specific field
  // across other filters

  {
    "name": "3 filters, 1 required across all",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
    ]
  }
  ```
</CodeGroup>

### `tag`

**Description**

Target based on custom user [Tags](/docs/en/add-user-data-tags).

<Warning>
  Do not use tags for targeting individual users like a "user id".
  Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
</Warning>

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
  * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
* `key` = Tag key to compare.
* `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

```json theme={null}
"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "OR"},
  {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
]
```

### `last_session`

**Description**

Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "last_session", "relation": ">","hours_ago": "10"}
  ]
  ```

### `first_session`

**Description**

Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "first_session", "relation": "<","hours_ago": "24"}
  ]
  ```

### `session_count`

**Description**

Total number of sessions by the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="` or `"!="`
* `value` = number of sessions. Example: `"1"`

  ```json theme={null}
  "filters": [
    {"field": "session_count", "relation": ">","value": "5"}
  ]
  ```

### `session_time`

**Description**

Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

* `relation` = `">"` or `"<"`
* `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

  ```json theme={null}
  "filters": [
    {"field": "session_time", "relation": ">","value": "86400"}
  ]
  ```

### `language`

**Description**

[User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = 2 character language code. Example: `"en"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "language", "relation": "=","value": "en"},
    {"operator": "OR"},
    {"field": "language", "relation": "in_array","value": "es,fr,de"}
  ]
  ```

### `app_version`

**Description**

App version set on the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = app version. Example: `"1.0.0"`
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "app_version", "relation": "=","value": "1.0.1"},
    {"operator": "OR"},
    {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
  ]
  ```

### `location`

**Description**

Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

* `radius` = in meters
* `lat` = latitude
* `long` = longitude

  ```json theme={null}
  "filters": [
    {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
  ]
  ```

### `country`

**Description**

Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "=", "value": "US"},
    {"operator": "OR"},
    {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
  ]
  ```

***


# Create Subscription by alias
Source: https://documentation.onesignal.com/reference/create-subscription

POST /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions
Use this API to attach a new subscription—such as email, SMS, or push notification—to an existing OneSignal user identified by an alias.

## Overview

This API allows you to add a **new Subscription** to an existing [User](/docs/en/users) via an alias identifier. A *Subscription* reflects a user's intent to receive messages through a specific communication channel, such as email, SMS, or push notifications. See [Subscriptions](/docs/en/subscriptions) for additional context.

If you're looking to **create a new user and add Subscriptions simultaneously**, use the [Create User](/reference/create-user) API instead.

***

## How to use this API

To attach a Subscription, the user must already exist and be referenced using an alias. The `alias_label` and `alias_id` path parameters define how the user is identified:

* Common alias: `external_id`
* Other options: `onesignal_id`, or custom aliases

For details, refer to [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

## Required Fields

Each Subscription must include at least:

* `type`: the channel (e.g., `Email`, `SMS`, `iOSPush`)
* `token`: the unique identifier for the channel (e.g., email address, phone number, push token)

If the specified `type` and `token` already exist in the app, the Subscription will be transferred to the user identified in the path parameters.

***


# Create template
Source: https://documentation.onesignal.com/reference/create-template

POST /templates
Create reusable message templates for push, email, and SMS channels. Templates can be accessed through both the dashboard and API using a `template_id`.

## Overview

Use this endpoint to create a new message template in your OneSignal app. Once created, the template becomes available for use when sending messages via both the Dashboard and the REST API by referencing the `template_id`.

Templates streamline and standardize message content across push, email, and SMS channels.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Before using this endpoint, ensure that the target channel (push, email, or SMS) is properly configured in your OneSignal app. See [Channel Setup](/docs/en/channel-setup) for guidance.

### Push Templates

**Requirements:**

* Set the `contents` property with the English (`en`) language key.
* All [Push Channel Properties](/reference/push-notification) are valid for use in push templates.
* By default, all push platforms are enabled. You can target specific platforms by explicitly setting them (e.g., `isAndroid: true` disables others).

### Email Templates

**Requirements:**

* Set `isEmail: true`.
* Include both `email_subject` and `email_body`.
* All [Email Channel Properties](/reference/email) are valid for use in email templates.

### SMS Templates

**Requirements:**

* Set `isSMS: true`.
* Provide SMS-specific parameters like `contents`.
* All [SMS Channel Properties](/reference/sms) are valid for use in SMS templates.

***


# Export subscriptions CSV
Source: https://documentation.onesignal.com/reference/csv-export

POST /players/csv_export
Generate a GZip-compressed CSV export of your current subscription data using this API endpoint.

## Overview

Use this endpoint to request a GZip-compressed CSV export of all your [Subscriptions data](/docs/en/subscriptions) from OneSignal. The export includes both default and optional user data fields, and supports filters to refine the dataset. The file is downloadable via a URL returned in the API response.

***

## How to use this API

By default, this will export all Subscriptions within the app.

**Optional filters:**

You can narrow the export using:

* `segment_name`: Only export Subscriptions from a specific segment. Segment membership rules determine which subscription statuses are included. Use with `include_unsubscribed` to include unsubscribed subscriptions.
* `last_active_since`: Export Subscriptions where their `last_session` was after a specific Unix timestamp. Example: Use `1704067200` for Subscriptions active since January 1st, 2024.
* `include_unsubscribed`: When exporting a segment, set to `true` to include unsubscribed subscriptions alongside subscribed ones. By default, segment-filtered exports only return subscribed subscriptions. This parameter has no effect when `segment_name` is not provided.

**Example successful response:**

```json 200 OK theme={null}
{
  "csv_file_url": "https://onesignal.com/csv_exports/b2f7f966.../users_1849..._2024-11-10.csv.gz"
}
```

**Export time considerations:**

* Generation speed: \~2,000 records per second.
* File readiness: The `csv_file_url` may return a 404 until generation completes.
* Download retry: Poll the file URL at intervals until the file is ready.
* File expiration: The file remains available for 3 days after generation.
* Concurrency: Only one export per OneSignal account can run at a time.

**File not ready (404 response)**

```xml 404 CSV GET  theme={null}
This XML file does not appear to have any style information
associated with it. The document tree is shown below.
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

<Info>
  You can safely poll the `csv_file_url` until the file becomes available. Implement retry logic based on expected data volume and generation speed.

  Only one export is allowed at a time per account. Wait until the `.csv.gz` file is downloaded before triggering another export.
</Info>

***

## CSV data contents

The export includes two types of fields:

* **Default fields**: Always included unless excluded by schema changes.
* **Extra fields**: Must be explicitly requested using the `extra_fields` parameter.

### Default fields

* `id`: The Subscription ID.

* `identifier`: The push token, email address, or phone number depending on the Subscription type.

* `session_count`: The number of times the user has opened the app.

* `language`: The user's language in ISO 639-1 format.

* `timezone`: Deprecated — use `timezone_id` instead.

* `game_version`: The version of your app that the user is currently using.

* `device_os`: The device's operating system version.

* `device_type`: Integer representing channel/device type.
  * `0`: iOSPush
  * `1`: AndroidPush
  * `2`: FireOSPush
  * `5`: ChromePush
  * `7,17`: SafariPush
  * `11`: Email
  * `14`: SMS

* `device_model`: The device's hardware string.

* `ad_id`: Deprecated.

* `tags`: Custom key/value data.

* `last_active`: The last time the user was active.

* `playtime`: The total amount of time in seconds the user had the mobile app open.

* `created_at`: The first time the user was seen.

* `invalid_identifier`: Boolean flag for unsubscribed state.
  * `t`: Unsubscribed
  * `f`: Subscribed

### Extra fields (`extra_fields`)

Pass `extra_fields` in your request to include any of the following:

* `external_user_id`: Maps to the `external_id` of the user.

* `onesignal_id`: OneSignal's user ID.

* `location`: Adds the `lat` and `long` coordinates if set.

* `country`: The user's country in ISO 3166-1 Alpha 2 format.

* `ip`: The IP address if detected. Can be IPv4 or IPv6 format.

* `web_auth`: Only available to OneSignal SDKs. The `web_auth` key for web push.

* `web_p256`: Only available to OneSignal SDKs. The `web_p256` for web push.

* `unsubscribed_at`: The date and time the user last unsubscribed. They may resubscribe at any time. Check the `invalid_identifier` field to determine if they are currently subscribed.

* `notification_types`: Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/en/subscriptions#notification-types).

* `timezone_id`: The user's timezone in IANA format.

***


# Remove alias
Source: https://documentation.onesignal.com/reference/delete-alias

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}
Remove a specific alias from a user.

## Overview

Use this API to remove a specific alias from a user’s identity object without deleting the user. This operation only affects user identity labels—subscriptions and the core user record remain intact. To delete a user entirely, including all associated aliases and subscriptions, see the [Delete user](/reference/delete-user) API.

***

## How to use this API

To remove an alias from a user:

1. Identify the user via a known alias by specifying:

   * `alias_label` – the type of alias (e.g., email, external\_id)
   * `alias_id` – the unique identifier for that alias

2. Specify the alias to remove using:

   * `alias_label_to_delete` – the label of the alias to be deleted

   The `alias_label_to_delete` can be the same as the `alias_label` used to identify the user.

3. This action is performed synchronously—the alias is deleted immediately after the request is processed.

<Warning>
  The `onesignal_id` alias cannot be deleted. Only secondary aliases (like email, external\_id, etc.) are removable.
</Warning>

For a full explanation of identity management, see [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

***

## FAQ

### Can I delete the same alias that I used to look up the user?

Yes. This is a common scenario—especially if an alias was set incorrectly and needs to be removed. Just be sure to include that alias both as the identifier and as alias\_label\_to\_delete.

If you want to delete the entire user and all associated data, use the [Delete user](/reference/delete-user) API.

### What happens if I delete all aliases associated with the user?

A user will always retain at least one alias, the onesignal\_id. Even if you remove all other aliases, the user and their subscriptions remain linked to the onesignal\_id.

***


# Delete API key
Source: https://documentation.onesignal.com/reference/delete-api-key

DELETE /apps/{app_id}/auth/tokens/{token_id}
Delete a specific Rich Authentication Token (App API Key) for a OneSignal app. Requires your Organization API Key and the token's unique ID, not the token value itself.

## Overview

Use this API to delete a specific App API Key (Rich Authentication Token) for a single OneSignal.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Delete segment
Source: https://documentation.onesignal.com/reference/delete-segments

DELETE /apps/{app_id}/segments/{segment_id}
Delete segments from OneSignal. Does not delete users or subscriptions.

## Overview

The Delete segment method is used when you want to programmatically delete a segment from within the OneSignal Dashboard UI.

<Warning>
  Once a segment is deleted, it cannot be recovered. You will need to create a new segment with the same filters.
</Warning>

***

## How to use this API

You can pass in the `segment_id` dictating which segment from our dashboard will be deleted.

The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard as shown below:

<Frame>
  <img />
</Frame>

***


# Delete Subscription
Source: https://documentation.onesignal.com/reference/delete-subscription

DELETE /apps/{app_id}/subscriptions/{subscription_id}
Delete a specific subscription by its subscription_id. This stops messages from being sent to that subscription but does not prevent future subscriptions with the same token.

## Overview

Use this API to delete an existing Subscription and its associated properties. Deletion is **asynchronous**, and while the Subscription is being removed, messages will no longer be sent to it.

<Warning>
  This operation only deletes a **single Subscription**. To remove a **user and all their Subscriptions**, use the [Delete User](/reference/delete-user) API instead.
</Warning>

### What Happens When You Delete

* Messages will stop being sent to the deleted subscription.
* **Deleting a Subscription does not block new Subscriptions** with the same `token`.
  * If the app is reopened or a token is re-submitted (e.g., same email or phone), a **new Subscription** may be automatically created.
  * This ensures users can re-subscribe if needed without requiring manual intervention.

***

## How to Use This API

**Required:** `subscription_id`

You must provide the `subscription_id` of the subscription to be deleted. This ID is a UUID generated by OneSignal and is immutable.

To find the `subscription_id`:

1. Use the [View User](/reference/view-user) API.
2. Look at the `subscriptions` array in the response.
3. Identify the correct subscription by its `type`, `token`, or other metadata.
4. Use the corresponding `id` field as the `subscription_id`.

***


# Delete template
Source: https://documentation.onesignal.com/reference/delete-template

DELETE /templates/{template_id}?app_id={app_id}
Permanently delete a specific message template from your OneSignal app using its template ID. Templates used in Journeys must be removed from those Journeys before deletion.

## Overview

This endpoint allows you to delete a single template associated with your OneSignal app. Deletion is **immediate and irreversible**.

<Warning>
  If the template is currently used in a Journey, it cannot be deleted until that Journey has been deleted.
</Warning>

***

## How to use this API

Required Parameters

* `template_id` (path param): The OneSignal-generated UUID of the template to delete.
* `app_id` (query param): Your OneSignal App ID.

### Where to Find `template_id`

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# Delete player record
Source: https://documentation.onesignal.com/reference/delete-user-record

delete https://onesignal.com/api/v1/players/{player_id}?app_id={app_id}

Delete a player (aka Subscription).

<Warning>
  This is a Legacy API. Use [Delete User](/reference/delete-user) or [Delete Subscription](/reference/delete-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `app_id`    | string | Yes      | Your OneSignal App ID.         |
| `player_id` | string | Yes      | The Subscription ID to delete. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Example Request

```http theme={null}
DELETE /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json
```

***

## Example Response

```json theme={null}
{
  "success": true
}
```

The Subscription will be deleted from the OneSignal database.

***


# Edit player
Source: https://documentation.onesignal.com/reference/edit-device

put https://onesignal.com/api/v1/players/{player_id}

Update a player's (Subscription's) information using the Subscription ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `player_id` | string | Yes      | The OneSignal Subscription ID. |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request.    |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                |
| -------------------- | ------- | -------- | ---------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                     |
| `identifier`         | string  | No       | Push token, email, or phone number.                        |
| `language`           | string  | No       | Language code (e.g., "en").                                |
| `timezone`           | integer | No       | Time zone offset in seconds.                               |
| `game_version`       | string  | No       | App version.                                               |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                         |
| `device_os`          | string  | No       | OS version (e.g., "14.5").                                 |
| `ad_id`              | string  | No       | Advertising ID.                                            |
| `sdk`                | string  | No       | OneSignal SDK version.                                     |
| `tags`               | object  | No       | Custom key-value pairs.                                    |
| `external_user_id`   | string  | No       | Your internal user ID.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc. |
| `email_auth_hash`    | string  | No       | Required to update email identifiers securely.             |
| `sms_auth_hash`      | string  | No       | Required to update SMS identifiers securely.               |

> Only include fields you want to change. Fields left out will not be modified.

***

## Example Request

```json theme={null}
PUT /api/v1/players/player_id_string HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "external_user_id": "user123",
  "tags": {
    "level": "20",
    "subscription": "active"
  },
  "language": "fr",
  "timezone": 3600,
  "device_os": "16.0"
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Missing or invalid fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied.
* 404 Not Found – Device with player\_id not found.

***


# Edit tags with external user id
Source: https://documentation.onesignal.com/reference/edit-tags-with-external-user-id

put https://onesignal.com/api/v1/apps/{app_id}/users/{external_user_id}

Update a player's (Subscription's) information using the External ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter          | Type   | Required | Description             |
| ------------------ | ------ | -------- | ----------------------- |
| `app_id`           | string | Yes      | Your OneSignal App ID.  |
| `external_user_id` | string | Yes      | The user's External ID. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Request Body Parameters

| Field  | Type   | Required | Description                       |
| ------ | ------ | -------- | --------------------------------- |
| `tags` | object | Yes      | Key-value pairs to set or update. |

* To **delete a tag**, set its value to an empty string (`""`).
* Existing tags with the same keys will be **overwritten**.

***

## Example Request

```http theme={null}
PATCH /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json

{
  "tags": {
    "plan": "premium",
    "logged_in": "true",
    "referral": ""
  }
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Invalid request or payload.
* 401 Unauthorized – Invalid or missing keys.
* 403 Forbidden – Access denied due to insufficient permissions.
* 404 Not Found – No players found for given `external_user_id`.

***


# Export audience activity CSV
Source: https://documentation.onesignal.com/reference/export-csv-of-events

POST /notifications/{message_id}/export_events
Export a compressed CSV report of audience-level delivery and engagement data for a specific message. This includes sent, delivered, clicked, failed, and unsubscribed events across Push, Email, and SMS channels.

## Overview

Get a CSV of per-recipient audience activity events (sends, clicks, failures, etc.) for a push, email, or SMS message. This endpoint mirrors the **Export** button in the dashboard's Audience Activity section on each message report:

* [Push message reports](/docs/en/push-notification-message-reports)
* [Email message reports](/docs/en/email-message-reports)
* [SMS message reports](/docs/en/sms-message-reports)

The CSV schema varies by channel. See each channel's message reports page for column definitions.

***

## How to use this API

Get the message `id` from the [Sending messages API](/reference/create-message) or the [View messages API](/reference/view-messages).

A successful request returns `200 OK` with a `csv_file_url`:

```json 200 OK theme={null}
{
    "csv_file_url": "https://onesignal-data.onesignal.com/csv_exports/YOUR_APP_ID/events_audience-activity-YOUR_MESSAGE_ID-push-YYYY-MM-DDTHH-MM-SSTZ.csv.gz"
}
```

The generated file name follows the pattern `events_audience-activity-{message_id}-{channel}-{timestamp}.csv.gz`.

The file is generated at \~2,000 records per second. For large audiences, generation can take several minutes, and the URL may return `404` until the file is ready:

```xml 404 Not Found theme={null}
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

Poll the `csv_file_url` with GET and implement retries with exponential backoff. When the file is ready, the GET request downloads the `.csv.gz` file.

<Info>
  * The CSV download URL is valid for **3 days** after creation.
  * File names include a random UUID to prevent guessing.
</Info>

<Warning>
  Only **one concurrent export** is allowed per OneSignal account. Download the `.csv.gz` file before starting another export, or the new request fails.
</Warning>

***


# View user identity (by subscription)
Source: https://documentation.onesignal.com/reference/fetch-identity-by-subscription

GET /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Retrieve all aliases linked to a user using a known `subscription_id`. This is useful when the user’s identity is unknown but you have access to one of their push, email, or SMS subscriptions.

## Overview

Use this API when you want to find the full identity (all aliases) of a user, starting from a known `subscription_id`. This is helpful for debugging, reverse lookups, or support use cases where only a subscription record is available.

<Note>
  Unlike the [View user identity](/reference/fetch-aliases) API which starts with an alias (e.g., `external_id`), this endpoint works when only a subscription ID is known.
</Note>

See [Subscriptions](/docs/en/subscriptions) for background on how subscriptions relate to users.

***

## How to use this API

To use this endpoint, you must provide:

* `subscription_id` – A UUID generated by OneSignal when a device or channel (e.g., push, email, SMS) is registered.

<Warning>
  `subscription_id` values are immutable and cannot be changed. Make sure you are using the correct value, as they are unique to each app and platform.
</Warning>

Once a valid `subscription_id` is provided, the API will return the user’s identity object, which includes all associated aliases like `external_id`, `onesignal_id`, and any custom aliases.

***


# List audit logs
Source: https://documentation.onesignal.com/reference/list-audit-logs

GET /organizations/{organization_id}/audit_logs
Retrieve a paginated, time-scoped list of audit log events for an organization. Requires an Enterprise plan. Supports filtering by app, action, actor, target, and IP address.

## Overview

The List audit logs API returns a record of actions taken within your organization — who did what, when, and from where. Use it to support compliance workflows, security investigations, and activity monitoring.

<Note>
  This endpoint requires an Enterprise plan with the audit logs entitlement enabled. Contact your account manager to enable access. See [Audit logs](/docs/en/audit-logs) for a feature overview.
</Note>

***

## How to use this API

Authenticate with your [Organization API Key](/docs/en/keys-and-ids#organization-api-key). App-level API keys are not accepted.

### Time range

Every initial request requires a `start_time`. Results are returned in ascending chronological order.

* The maximum lookback window is **90 days**.
* `start_time` must be an ISO 8601 timestamp within the last 90 days.
* `end_time` is optional and defaults to the current time.
* Historical data is only available from **2026-02-18T00:00:00Z** onward.

### Cursor-based pagination

When a response contains more results than the requested `limit`, the response includes `has_more: true` and a `next_cursor` value. Pass `next_cursor` as the `cursor` parameter in the next request. When using a cursor, `start_time` and `end_time` are not required.

<Warning>
  When `app_ids` is set, org-level events (those not associated with any specific app) are always included in results alongside the filtered app events.
</Warning>


# Rotate API key
Source: https://documentation.onesignal.com/reference/rotate-api-key

POST /apps/{app_id}/auth/tokens/{token_id}/rotate
Rotate an existing App API Key (Rich Authentication Token) for a OneSignal app. Useful when a token is compromised or needs replacement without creating a new key from scratch.

## Overview

Use this API to rotate a **Rich Authentication Token** (App API Key) for a specific OneSignal app. Rotating a key revokes the current token and generates a new one under the same configuration—ideal when a token is lost or compromised but you don’t want to recreate and reconfigure it from scratch.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can rotate an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Transfer Subscription
Source: https://documentation.onesignal.com/reference/transfer-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/owner
Transfer a Subscription to a different user within the same OneSignal app. Useful for associating existing Subscriptions like push, email, or SMS with a new or updated user identity.

## Overview

Use this API to transfer a Subscription from one user to another within the same OneSignal app.

It is highly recommended to use our web and mobile SDKs to set and update the External ID with the `login` method instead of this API. Your app or website may continue to be setting the wrong External ID. Make sure to only use this API if you are setting the same External ID within your app or website.

This is typically used when:

* You want to reassign an existing push, email, or SMS Subscription to a new or updated user.
* You have changed how you're identifying users (e.g., migrating from anonymous to known users).

<Note>
  - Subscriptions **cannot be transferred across different OneSignal apps**.
  - For email and SMS Subscriptions, you can instead create new ones using [Create User](/reference/create-user).
  - For push Subscriptions, platform limitations may apply—see [Subscriptions](/docs/en/subscriptions#importing-push-subscriptions) for details.
</Note>

***

## How to Use This API

### Required Path Parameter: `subscription_id`

You must know the `subscription_id` of the subscription to be transferred. This is a unique UUID assigned by OneSignal.

### Required Body Parameter: `identity` (object)

This specifies the user the subscription should be moved to. Only **one alias** should be used per request. You can identify the target user using one of:

* `external_id` (recommended)
* `onesignal_id`
* A [custom alias](/docs/en/aliases)

***


# Unsubscribe email with token
Source: https://documentation.onesignal.com/reference/unsubscribe-with-token

POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
Unsubscribe an email address from future messages by calling this API from your custom unsubscribe page. Automatically disables the associated email subscription using a token-based approach.

## Overview

Use this API to unsubscribe an email address directly from your custom unsubscribe landing page. It is ideal when building branded opt-out experiences and enables you to track which email caused the unsubscribe.

When invoked, this endpoint:

* Sets the email Subscription's `enabled` property to `false`
* Prevents further messages from being sent to the email address unless explicitly overridden (see [Overriding unsubscribes](/reference/email#body-include-unsubscribed))
* Email Subscriptions can be re-subscribed using the [Update Subscription](/reference/update-subscription) API

<Tip>
  For instructions on setting up a custom unsubscribe page, see [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page).
</Tip>

***

## How to Use This API

### Step 1: Set Up Your Custom Unsubscribe Page

Follow the guide to [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page). You'll add a custom unsubscribe URL to your email templates using Liquid syntax.

Example URL in your email template:

```liquid theme={null}
https://yourdomain.com/unsubscribe?app_id={{ app_id }}&notification_id={{ notification_id }}&token={{ token }}
```

### Step 2: Extract the Parameters

When a user clicks the unsubscribe link, your custom unsubscribe page should extract the following from the URL:

* `app_id`: OneSignal app ID
* `notification_id`: The ID of the specific email message sent
* `token`: The email token, a secure reference to the subscription

### Step 3: Call the API

When the user confirms they want to unsubscribe (e.g., clicks a button on your unsubscribe page), make a POST request to this endpoint:

```
POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
```

Example Request (JavaScript):

```js theme={null}
fetch("https://api.onesignal.com/apps/your-app-id/notifications/your-notification-id/unsubscribe?token=abc123xyz", {
  method: "POST"
});
```

<Info>
  No request body or authentication is required. The token acts as a secure identifier.
</Info>

<Note>
  * This API only works for email subscriptions.
  * It should only be used from a server or frontend context that you control (e.g., your custom unsubscribe page).
  * Once unsubscribed, the email address will not receive future emails from your app unless resubscribed.
</Note>

***


# Update an app
Source: https://documentation.onesignal.com/reference/update-an-app

PUT /apps/{app_id}
Use to update the name or push platform configuration of an existing app. This guide explains required parameters and platform-specific update rules

## Overview

Use this API to programmatically update an existing OneSignal app. This is useful when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

***

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Warning>
  If you change your FCM Service Account JSON file to a different Firebase project, your Android Subscriptions tied to the current project will become invalid. They will not be able to receive push notifications until they open your app again with this new FCM Service Account JSON file.
</Warning>

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need help Base64 encoding your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns). **You will likely never need to update these parameters if set correctly during app creation**:

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates). **These must be updated every year which is why we recommend using p8 authentication**:

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Update API key
Source: https://documentation.onesignal.com/reference/update-api-key

PATCH /apps/{app_id}/auth/tokens/{token_id}
Update a Rich Authentication Token (App API Key) for a OneSignal app. Modify the token's name or IP allowlist settings using your Organization API Key.

## Overview

Use this API to update the properties of a specific **Rich Authentication Token** (App API Key) for a OneSignal app. You can change the name, IP allowlist mode, or the list of allowed IPs. This is helpful for adjusting access rules without needing to recreate the key.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Update segment
Source: https://documentation.onesignal.com/reference/update-segment

PATCH /apps/{app_id}/segments/{segment_id}
Update an existing segment's name and/or filters. The name parameter is always required. When filters are provided, all existing filters are replaced with the new ones.

## Overview

Update an existing segment's name and/or filters. This API allows you to modify [Segments](/docs/en/segmentation) programmatically without having to delete and recreate them.

<Note>
  The `name` parameter is always required, even if you're not changing it. When filters are provided, all existing filters are **replaced** with the new ones. Omit the `filters` parameter to keep existing filters intact. The `filters` array cannot be empty—if provided, it must contain at least one filter.
</Note>

***

## How to use this API

### Update segment name only

To update just the segment name without changing filters:

```json theme={null}
{
  "name": "New Segment Name"
}
```

### Update segment description

Update the optional `description` (max 255 characters). Pass an empty string to clear the existing description; omit the field to leave it unchanged.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION"
}
```

### Update segment filters

To update the segment filters (this replaces all existing filters), provide the `name` (required) and `filters`:

```json theme={null}
{
  "name": "Updated Segment",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "5"},
    {"operator": "AND"},
    {"field": "tag", "key": "subscription", "relation": "=", "value": "premium"}
  ]
}
```

### Filter syntax

The filter syntax is identical to the [Create segment](/reference/create-segments) API. Available filters include:

* `tag` - Filter by Tags
* `last_session` - Filter by last active time
* `first_session` - Filter by first session time
* `session_count` - Filter by number of sessions
* `session_time` - Filter by total usage duration
* `language` - Filter by user language
* `app_version` - Filter by app version
* `location` - Filter by GPS coordinates
* `country` - Filter by country

Use `AND` and `OR` operators to combine filters:

```json theme={null}
{
  "name": "Engaged Premium Users",
  "filters": [
    {"field": "tag", "key": "plan", "relation": "=", "value": "premium"},
    {"operator": "AND"},
    {"field": "session_count", "relation": ">", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "vip", "relation": "=", "value": "true"}
  ]
}
```

***

## Response

### Success response

```json theme={null}
{
  "success": true,
  "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19"
}
```

### Error responses

| Status Code | Description                                                                              |
| ----------- | ---------------------------------------------------------------------------------------- |
| 400         | Bad request - Invalid filters, duplicate segment name, or segment used by active Journey |
| 403         | Forbidden - API not available for your plan                                              |
| 404         | Not found - Segment does not exist                                                       |
| 429         | Rate limit exceeded                                                                      |

***


# Update Subscription by ID
Source: https://documentation.onesignal.com/reference/update-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}
Update properties on an existing OneSignal subscription using its subscription_id. Commonly used to enable or disable a subscription when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties by `subscription_id`.

This endpoint is primarily used by the OneSignal SDK to manage subscription state.

Most external use cases are better served by the [Update Subscription by token](/reference/update-subscription-by-token) API, which can use the Email Address or Phone Number as the `token` or the [Update User](/reference/update-user) API, which allows for updating user-level data.

<Note>
  For **email opt-outs**, it's recommended to use the [Unsubscribe Email (with token)](/reference/unsubscribe-with-token) API instead. This avoids the need to store or manage the `subscription_id`.
</Note>

***

## How to use this API

**Required:** `subscription_id`

To update a subscription, you **must know the `subscription_id`**. This is a UUID generated by OneSignal and is immutable.

* You can retrieve a subscription ID by querying the [User object](/docs/en/users).
* See the [Subscriptions](/docs/en/subscriptions) guide for an explanation of how subscription IDs are generated and used.

<Note>
  You **cannot** update the `type` of a Subscription. If the `type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the Subscription with the correct type.
</Note>

***


# Update Subscription by token
Source: https://documentation.onesignal.com/reference/update-subscription-by-token

PATCH /apps/{app_id}/subscriptions_by_token/{token_type}/{token}
Update properties on an existing Subscription using its token. Commonly used to enable or disable subscription status when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties.

This API can be useful if:

* You only know the `token` and `token_type` and want to update metadata or status flags directly.
* You are managing Subscription status outside of the OneSignal SDK. Like with a [custom preference page or unsubscribe page](/docs/en/create-custom-unsubscribe-page).

***

## How to use this API

To update a Subscription, you must know the `token_type` and the `token`.

The `token_type` is the [Subscription's type](/docs/en/server-sdk-reference#subscription-types) (e.g., `Email`, `SMS`, `iOSPush`, `AndroidPush`, etc.).

The `token` is the push token, email address, or phone number associated with the Subscription.

Ensure the `token` is valid and correctly formatted for the chosen `token_type`.

* **Email format:** Should be a valid email address that you confirmed can receive emails.
* **SMS format:** Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164).
* **iOSPush APNS token format:** 64 characters, hexadecimal characters only (0-9,a-f).
* **AndroidPush FCM token format:** Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.

<Warning>
  You **cannot** update the `token_type` and `token` of a Subscription with this API. If the `token_type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the subscription with the correct type.

  If multiple Subscriptions are found for the `token` and `token_type`, an `Http 400` error is returned with a list of subscription IDs that match the criteria.
</Warning>

***


# Update template
Source: https://documentation.onesignal.com/reference/update-template

PATCH /templates/{template_id}?app_id={app_id}
Update existing OneSignal message templates for push, email, or SMS. Changes apply immediately across dashboard and API usage via the `template_id` reference.

## Overview

This endpoint allows you to update an existing push, email, or SMS template in your OneSignal app. Once updated, the changes are applied immediately and reflected across both the Dashboard and API when using the associated `template_id`.

Templates are updated using the same structure as when [creating templates](/reference/create-template).

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

To update a template, you must supply:

* Your **OneSignal App ID** found in [Keys & IDs](/docs/en/keys-and-ids).
* The **Template ID**

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***

## Channel-Specific Requirements

### Push Templates

* The `contents` property must use the `en` (English) key along with other languages you want to support.
* All [Push Notification Properties](/reference/push-notification) are valid.
* All platforms are enabled by default. To limit, explicitly enable desired ones (e.g., `isAndroid: true` disables iOS and Web).

### Email Templates

* Set `isEmail: true`
* Include `email_subject` and `email_body`
* All [Email Channel Properties](/reference/email) are supported.

### SMS Templates

* Set `isSMS: true`
* All [SMS Channel Properties](/reference/sms) are supported.

***


# View an app
Source: https://documentation.onesignal.com/reference/view-an-app

GET /apps/{app_id}
View the details of a single OneSignal app

## Overview

Use this API to retrieve metadata and platform configuration for a single OneSignal app associated with your account. This includes app names, App ID, Subscription counts, timestamps, and push platform credentials (Android/FCM, iOS/APNS, Web Push, Safari), making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

***

## How to use this API

To retrieve your app, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View API keys
Source: https://documentation.onesignal.com/reference/view-api-keys

GET /apps/{app_id}/auth/tokens
View the details of all of your current app API keys (Rich Authentication Token) for a single OneSignal app.

## Overview

This API is helpful for auditing and managing the API keys (Rich Authentication Tokens) associated with an app. It returns metadata for each token, including:

* Token name and ID
* IP allow list mode and associated CIDR ranges (if any)
* Creation and last updated timestamps

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

***


# View apps
Source: https://documentation.onesignal.com/reference/view-apps

GET /apps
Retrieve a list of all OneSignal apps associated with your account, including key app details like name, App ID, subscription counts, and timestamps. Useful for managing multiple apps through the OneSignal API.

## Overview

Use this API to retrieve metadata for all OneSignal apps associated with your account. This includes app names, App IDs, subscription counts, and timestamps, making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

<Warning>
  This API is limited to return a maximum of 1000 Apps. If you need access to more, then you should store the `app_id` and `name` for each of your apps on your own server to look up with the [View an app](/reference/view-an-app) API to get data for each app separately. Also, if you need to delete apps, then you can provide the `app_id` and `name` to OneSignal Support and ask for these to be deleted.
</Warning>

***

## How to use this API

To retrieve your apps, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View player
Source: https://documentation.onesignal.com/reference/view-device

GET https://onesignal.com/api/v1/players/{player_id}

Retrieve a single player record (Subscription) data registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `player_id` | string | Yes      | The OneSignal ID of the device. |

***

## Query Parameters

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `app_id`  | string | Yes      | Your OneSignal App ID. |

***

## Headers

| Header          | Value                            | Required | Description                        |
| --------------- | -------------------------------- | -------- | ---------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal LegacyREST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players/player_id_string?app_id=your_app_id HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json{ theme={null}
  "id": "player_id_string",
  "identifier": "push_token_or_email",
  "session_count": 5,
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_os": "14.4",
  "device_type": 1,
  "tags": {
    "level": "10",
    "user_type": "free"
  },
  "last_active": 1625253300,
  "created_at": 1625249800,
  "invalid_identifier": false,
  "external_user_id": "user123"
}
```

### Response Fields

| Field                | Type      | Description                                             |
| -------------------- | --------- | ------------------------------------------------------- |
| `id`                 | string    | OneSignal player ID.                                    |
| `identifier`         | string    | Push token, email, or phone number.                     |
| `session_count`      | integer   | Number of sessions associated with this device.         |
| `language`           | string    | Language set on the device (e.g., "en").                |
| `timezone`           | integer   | Time zone offset in seconds.                            |
| `game_version`       | string    | Version of your app the device is running.              |
| `device_os`          | string    | Operating system version.                               |
| `device_type`        | integer   | Numeric code for platform (0 = iOS, 1 = Android, etc.). |
| `tags`               | object    | Custom tags set on the device.                          |
| `last_active`        | timestamp | Last time the user was active (Unix timestamp).         |
| `created_at`         | timestamp | When the device record was created.                     |
| `invalid_identifier` | boolean   | Whether the push token or identifier is invalid.        |
| `external_user_id`   | string    | Your internal user ID mapped to this device.            |

***

## Errors

* 400 Bad Request – Missing or invalid parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied for this app or resource.
* 404 Not Found – The specified player\_id does not exist.

***


# View players
Source: https://documentation.onesignal.com/reference/view-devices

GET `https://onesignal.com/api/v1/players?app_id={app_id}&limit={limit}&offset={offset}`

Retrieve up to 80,000 player records (Subscriptions) registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Query Parameters

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `app_id`  | string | Yes      | Your OneSignal App ID.                                 |
| `limit`   | int    | No       | Number of entries to return (max 300, default is 300). |
| `offset`  | int    | No       | Result offset for pagination.                          |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players?app_id=your_app_id&limit=100&offset=0 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json theme={null}
{
  "total_count": 6,
  "offset": 0,
  "limit": 300,
  "players": [
    {
      "id": "player_id_1",
      "identifier": "push_token_or_email",
      "session_count": 3,
      "language": "en",
      "timezone": -28800,
      "game_version": "1.0",
      "device_os": "15.0",
      "device_type": 1,
      "tags": {
        "level": "15",
        "user_type": "free"
      },
      "last_active": 1625253300,
      "created_at": 1625249800,
      "invalid_identifier": false,
      "external_user_id": "user123"
    }
  ]
}
```

### Response Fields

| Field                        | Type    | Description                                  |
| ---------------------------- | ------- | -------------------------------------------- |
| `total_count`                | integer | Total number of devices for the app.         |
| `offset`                     | integer | Current pagination offset.                   |
| `limit`                      | integer | Number of devices returned in this response. |
| `players`                    | array   | List of device objects.                      |
| `players[].id`               | string  | Unique OneSignal player ID.                  |
| `players[].identifier`       | string  | Push token, email, or phone number.          |
| `players[].tags`             | object  | Custom tags set on the device.               |
| `players[].external_user_id` | string  | Your internal user ID.                       |

***

## Errors

* 400 Bad Request – Invalid query parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access not allowed for this app or key.

***


# View outcomes
Source: https://documentation.onesignal.com/reference/view-outcomes

GET /apps/{app_id}/outcomes?outcome_names={outcome_names}&outcome_time_range={outcome_time_range}&outcome_platforms={outcome_platforms}&outcome_attribution={outcome_attribution}
View and export push notification outcome metrics such as clicks, conversions, and custom events.

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

## Overview

Use this API to retrieve Outcome metrics associated with your OneSignal app, including push notification interactions and custom-defined events. Outcomes include data points like:

* **Clicks**: Number of users who clicked on a push.
* **Confirmed Deliveries**: Number of confirmed message deliveries.
* **Session Durations**: Number of sessions initiated.
* **Custom Events**: Actions like purchases, form submissions, or any event your app tracks via custom Outcome names.

For details on configuring custom Outcomes, refer to the [Outcomes documentation](/docs/en/custom-outcomes).

<Info>
  Outcomes are stored for approximately 30 days. To retain this data, you should regularly export it before it expires.
</Info>

***

## How to use this API

This API allows you to filter and aggregate Outcome data using several query parameters.

### `outcome_names`

Specify one or more Outcome names with an aggregation type suffix (`.count` or `.sum`).

**Default Outcome names:**

* `os__click.count` – Push notification clicks.
* `os__confirmed_delivery.count` – Confirmed deliveries.
* `os__session_duration.count` – Total sessions.

**Custom Outcome names:**

* You can track any custom event name (e.g. `Purchase`, `Signup`).
* If the custom name contains a comma, include only one name per request to avoid parsing issues.
* Example: `outcome_names=os__click.count,Purchase.count`

### `outcome_time_range`

The time range values can be one of the following:

* `1h` = (default) the last 1 hour data.
* `1d` = the last 1 day data.
* `1mo` = the last 1 month data.

### `outcome_platforms`

Maps to the subscription type property. Default is data from all platforms enabled for your OneSignal App.

| `device_type` | `type`      |
| ------------- | ----------- |
| 0             | iOSPush     |
| 1             | AndroidPush |
| 2             | FireOSPush  |
| 5             | ChromePush  |
| 8             | FirefoxPush |
| 11            | Email       |
| 14            | SMS         |
| 17            | SafariPush  |

Example: `outcome_platform=0` for iOS `outcome_platform=17,8` for Safari and Firefox.

### `outcome_attribution`

The way in which the Outcome occurred:

* `direct` = the Outcome occurred when the user interacted with the message. Some Outcomes only have `direct` attribution like `os__click` and `os__confirmed_delivery` because they only occur as the direct result of the message.
* `influenced` = the Outcome occurred within the Time Window of the message being sent, but the user never interacted with the message. See [Outcomes](/docs/en/custom-outcomes) for details.
* `unattributed` = the Outcome occurred without a direct or influenced attribute.
* `total` = (default) the sum of direct+influenced+unattributed.

***


# View segment
Source: https://documentation.onesignal.com/reference/view-segment

GET /apps/{app_id}/segments/{segment_id}
Retrieve details for a single segment by its ID, including subscriber count and optionally segment metadata and filters.

## Overview

Retrieve details for a single segment by its ID. By default, this endpoint returns only the subscriber count. Use the optional `include-segment-detail` parameter to also retrieve segment metadata and filters.

<Note>
  The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard.
</Note>

<Warning>
  **User-based segments not supported**: Segments containing message event or custom event filters (user-based segments) are not yet supported via this API. Attempting to fetch these segments will return a 400 error. These segments can only be managed through the dashboard UI.
</Warning>

***

## How to use this API

### Basic usage

By default, this endpoint returns only the subscriber count for the segment:

```json theme={null}
{
  "subscriber_count": 12345
}
```

### Include segment details

To retrieve full segment details including metadata and filters, set `include-segment-detail=true`:

```
GET /apps/{app_id}/segments/{segment_id}?include-segment-detail=true
```

This returns the subscriber count along with a `payload` object containing segment details:

<CodeGroup>
  ```json Simple filter theme={null}
  {
    "subscriber_count": 12345,
    "payload": {
      "id": "4414c404-56a3-11ed-9b6a-0242ac120002",
      "name": "Subscribed Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {
          "field": "session_count",
          "relation": ">",
          "value": "5"
        }
      ]
    }
  }
  ```

  ```json With AND/OR operators theme={null}
  {
    "subscriber_count": 5678,
    "payload": {
      "id": "5525d515-67b4-22fe-0c7b-1353bd231113",
      "name": "Engaged Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {"field": "session_count", "relation": ">", "value": "2"},
        {"operator": "AND"},
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "last_session", "relation": "<", "hours_ago": "24"}
      ]
    }
  }
  ```
</CodeGroup>

### Filters format

The `filters` array uses the **same format** as the [Create segment](/reference/create-segments) API. This means you can:

* Read filters from this endpoint
* Modify them as needed
* Use them directly with the [Update segment](/reference/update-segment) or [Create segment](/reference/create-segments) APIs

The array contains filter objects and operator objects:

**Filter object** - defines a condition:

| Field                   | Type    | Description                                                                                                                                         |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field`                 | string  | The filter type: `tag`, `last_session`, `first_session`, `session_count`, `session_time`, `language`, `app_version`, `location`, `country`, `email` |
| `relation`              | string  | The comparison operator: `>`, `<`, `=`, `!=`, `exists`, `not_exists`, `in_array`, `not_in_array`, `time_elapsed_gt`, `time_elapsed_lt`              |
| `value`                 | string  | The filter value (for most filter types)                                                                                                            |
| `key`                   | string  | The filter key (required for `tag` filters)                                                                                                         |
| `hours_ago`             | string  | Hours ago value (for `last_session`/`first_session` filters)                                                                                        |
| `radius`, `lat`, `long` | string  | Location parameters (for `location` filters)                                                                                                        |
| `unsupported_in_api`    | boolean | If `true`, this filter cannot be used with Create/Update segment APIs (see note below)                                                              |

**Operator object** - combines filters:

| Field      | Type   | Description                                                                        |
| ---------- | ------ | ---------------------------------------------------------------------------------- |
| `operator` | string | Either `AND` or `OR`. Filters connected with `AND` have higher priority than `OR`. |

<Warning>
  Some segments created via the dashboard UI may contain filter types not supported by the public API (e.g., `message_event`, `custom_event`). These filters will include `unsupported_in_api: true`. You cannot use these filters when creating or updating segments via the API.
</Warning>

### Payload fields

| Field         | Type           | Description                                                                         |
| ------------- | -------------- | ----------------------------------------------------------------------------------- |
| `id`          | string         | The unique identifier for the segment (UUID v4).                                    |
| `name`        | string         | The segment name (max 128 characters).                                              |
| `description` | string \| null | Human-readable description for the segment (max 255 characters). `null` when unset. |
| `created_at`  | integer        | Unix timestamp when the segment was created.                                        |
| `source`      | string         | The source of the segment: `default`, `custom`, or `quickstart`.                    |
| `filters`     | array          | Array of filter and operator objects that define the segment criteria.              |

***


# View segments
Source: https://documentation.onesignal.com/reference/view-segments

GET /apps/{app_id}/segments
Retrieve a list of segments associated with a specific OneSignal app. Useful for programmatically accessing segment metadata such as name, creation date, and status.

## Overview

Retrieve a list of segments associated with a specific OneSignal app. This is helpful when you want to access segment metadata programmatically instead of using the OneSignal Dashboard UI.

<Warning>
  This endpoint only retrieves existing segment metadata. It does not provide the segment filters or user data.
</Warning>

***


# View template
Source: https://documentation.onesignal.com/reference/view-template

GET /templates/{template_id}?app_id={app_id}
Retrieve the details of a specific message template in your OneSignal app using its template ID. This API returns the template content, target channel, and timestamps for creation and last update.

## Overview

This endpoint returns metadata and content for a single template, including:

* Template body/content
* Target delivery channel (e.g., push, email, SMS)
* Creation and last updated timestamps

This is useful for inspecting existing templates before using or updating them.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Required parameters:

* `app_id` (query param): Your OneSignal App ID.
* `template_id` (path param): The unique ID of the template.

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# View templates
Source: https://documentation.onesignal.com/reference/view-templates

GET /templates?app_id={app_id}&limit={limit}&offset={offset}
Retrieve a paginated list of message templates from your OneSignal app. This endpoint returns summary information for each template, including ID, name, creation, and update timestamps.

## Overview

Use this endpoint to retrieve a list of message templates associated with a specific OneSignal app. The response provides summary information only:

* `template_id`
* `name`
* `created_at`
* `updated_at`

<Note>
  This endpoint does **not** return full template content such as message bodies, channel properties, or delivery configuration. For detailed template data, use the [View Template](/reference/view-template) endpoint.
</Note>

***

## How to Use This API

### Required Parameters

* **`app_id`** (query param): The OneSignal App ID whose templates you want to retrieve.

### Optional Parameters

* **`limit`** (query param): Number of templates to return (default: `50`, maximum: `50`).
* **`offset`** (query param): Number of templates to skip. Use for pagination.

### Pagination Example

If your app has 125 templates and you're using the default limit of 50:

1. First request (first 50 templates):\
   `GET /templates?app_id={app_id}&offset=0`

2. Second request (next 50 templates):\
   `GET /templates?app_id={app_id}&offset=50`

3. Third request (final 25 templates):\
   `GET /templates?app_id={app_id}&offset=100`

Repeat the request while adjusting the `offset` until you've retrieved all templates.

***


# Changelog
Source: https://documentation.onesignal.com/release-notes/changelog

Learn about the latest updates to OneSignal.

Follow along with updates across OneSignal. We're launching new features and improving our product all the time!

<Update label="June 18 2026">
  **AI-assisted SDK installation updated and expanded**

  * AI install prompts have been rewritten and expanded to cover Android, iOS, React Native, Flutter, and Web SDKs.
  * Paste a single ready-made prompt into your AI coding assistant (Cursor, Claude, Copilot, or similar) and the assistant installs the SDK, drops in initialization code, and configures push and in-app messaging automatically.
  * No deep development experience required — marketers and non-technical users can complete SDK setup in minutes.
  * Prompt instructions were revised to fix errors identified during internal testing, so generated integrations are more accurate.
  * Available to all new sign-ups with no enablement required; requires an AI coding tool and access to the app codebase.
</Update>

<Update label="June 15 2026">
  **Extended `in_array` and `not_in_array` relations to the Device Type filter**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `device_type` filter field. Use them to match against a comma-separated list of device types in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "device_type", "relation": "in_array", "value": "iOS,Android"},
    {"operator": "AND"},
    {"field": "device_type", "relation": "not_in_array", "value": "Email"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="June 15 2026">
  **RCS editor experience improvements**

  We've improved how you build and send RCS, giving you a more intuitive editor, clearer approval visibility, and a more graceful SMS fallback experience:

  * **See carrier approval status in settings.** Each sender resource's carrier approval status is now visible at **Settings > SMS > Senders**, so you can track where each carrier stands in the approval process without leaving the dashboard.
  * **Select a sender per RCS template.** In Templates you now choose a specific sender instead of relying on a single global default, improving how RCS sends within Journeys and giving you automations for multiple SMS use cases.
  * **A more intuitive editor.** The composer automatically shows the right editor for the selected sender — the RCS editor for senders with an RCS resource, and the SMS editor for SMS-only senders.
  * **Text only RCS.** A new Text only content type sends plain branded RCS text.

  When a sender gains an approved RCS sending resource, OneSignal automatically prefers RCS for existing automations on that sender, mapping your existing SMS content to RCS so there's no manual rework.

  Available for all customers contracted for RCS. See [RCS messaging](/docs/en/rcs-messaging) for details.
</Update>

<Update label="June 8 2026">
  **Segment editor improvements: multi-value filters, copy filters, and filter JSON**

  Building segments in the dashboard is now faster and more flexible:

  * **Match multiple values in one filter.** The Language, Country, App Version, and User Tag filters now support the "is any of" and "is not any of" relations, so you can match a list of values in a single filter instead of chaining several filters with OR.
  * **Copy filters and filter groups.** Duplicate an individual filter or an entire filter group from the editor to reuse its configuration without rebuilding it by hand.
  * **View and copy filter JSON.** Open the filter JSON panel to see the REST API representation of your segment's filters, then copy it to use directly in the [Create segment](/reference/create-segments) API.
</Update>

<Update label="June 4 2026">
  **Retired Alexa and Windows Phone 8.0 as Device Type filter options**

  The `Alexa` and `Windows Phone 8.0` values are no longer available for the Device Type filter when you create or edit a segment, in both the dashboard and the Create segment API. Selecting either value in the dashboard is no longer possible, and the API rejects them with a validation error.

  Existing segments that already use these values continue to evaluate and deliver as before. To save changes to such a segment, replace the retired Device Type filter first.
</Update>

<Update label="June 2 2026">
  **Extended `in_array` and `not_in_array` relations to tag and app version filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `tag` and `app_version` filter fields, in addition to the `country` and `language` fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"},
    {"operator": "AND"},
    {"field": "app_version", "relation": "not_in_array", "value": "1.0.0,1.0.1"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="May 11 2026">
  **Email BCC is now generally available**

  You can now add BCC (blind carbon copy) recipients to email sends, including templates used in journeys and messages sent via the API. Use BCC to archive customer-facing email to a shared inbox or compliance system, forward sends to third-party services, or keep internal stakeholders copied on transactional sends.

  * Available on all plan types.
  * Maximum of 5 BCC addresses per send.
  * Each BCC recipient counts toward the total email volume for that send (for example, 1,000 primary recipients with 1 BCC address = 2,000 sends).
  * BCC metrics are excluded from analytics.

  See [BCC emails](/docs/en/email-bcc) for setup and usage details.
</Update>

<Update label="May 12 2026">
  **Added `in_array` and `not_in_array` relations for country and language filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `country` and `language` filter fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "in_array", "value": "US,GB,CA"},
    {"operator": "AND"},
    {"field": "language", "relation": "not_in_array", "value": "es,fr"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="April 21 2026">
  **Manage custom aliases from the User Profile**

  You can now view, add, edit, and delete a user's custom aliases directly from the **Aliases** section on the User Profile **Overview** tab, without using the API.

  * Add an alias by entering a label (alias key) and value (alias ID), copy any alias value to the clipboard, edit a value, or remove an alias.
  * Each user supports up to 10 aliases, and alias labels and values can each contain up to 128 characters.
  * `external_id` and `onesignal_id` are reserved and can't be used as custom alias labels.
  * A user must have an External ID set before you can add custom aliases. External ID is still managed separately in the Profile section.

  See [Aliases](/docs/en/aliases) for more details.
</Update>

<Update label="April 17 2026">
  **Role-based access control (RBAC) is now generally available**

  Granular role-based access control has been rolled out to all customers, giving teams more flexibility to support least-privilege access patterns and manage permissions as they scale.

  * **New `team_member` org-level default role.** A baseline role for new users added to an organization.
  * **New `composer` app-level role.** Lets users create and edit messages, templates, segments, and journeys without sending, activating, or deleting content.
  * **Updates to `editor` and `viewer` roles.** Refined permissions for clearer separation of duties.
  * Available roles vary by plan type.

  See [Manage team members](/docs/en/manage-team-members) for the full breakdown of roles, permissions, and plan availability.
</Update>

<Update label="April 16 2026">
  **Light/dark mode toggle for HTML in-app message previews**

  You can now switch between light and dark mode directly in the dashboard when previewing HTML in-app messages, so what you see matches what your users will actually see.

  * A light/dark mode toggle is now available in the in-app message preview for HTML messages.
  * The preview no longer reflects your OS theme. It reflects the mode you select in the dashboard.
  * Previously, the preview always rendered using whatever theme your own computer was set to, with no indication that was the cause, so there was no reliable way to check dark mode designs from the dashboard.

  HTML in-app messages do not automatically get a dark mode. The message still has to be coded for it using `@media (prefers-color-scheme: dark)` styles. If your message doesn't include those styles, toggling to dark mode in the preview won't change how it looks.

  The toggle is available for HTML in-app messages only. Block-type in-app messages are not included in this release. Generally available for all customers using HTML in-app messages.

  See [Design your in-app message with HTML](/docs/en/design-your-in-app-message-with-html) for how to add dark mode support.
</Update>

<Update label="April 15 2026">
  **Standardized delivery metrics across all channels**

  Delivery metric terminology is now consistent across every messaging channel in OneSignal. All channels now share a unified delivery hierarchy: Audience → Sent → Delivered, with the same definitions everywhere. Labels have been aligned across delivery reports, journey reports, engagement trends, and CSV exports. The [Metrics Glossary](/docs/en/analytics-metrics-glossary) has been fully rewritten as the canonical reference for every metric definition.
</Update>

<Update label="April 10 2026">
  **Audience counts now show subscribed and unsubscribed breakdowns**

  The segment editor now shows both subscribed and unsubscribed counts for every subscription-based segment, with a per-channel breakdown across push, email, and SMS. Previously, only the opted-in (subscribed) count was visible.

  Additional improvements:

  * Counts always return within approximately 15 seconds. Exact counts are shown when possible; estimates are used when an exact count can't be calculated in time.
  * Estimates are clearly labeled: above 10,000 with a +/- margin of error (e.g. 140,000 +/- 5,000), and below 10,000 as a less-than value (e.g. \<4,800).
  * Estimates will never show 0 for a segment. Previously for segments with very small but non-zero membership, estimates could incorrectly show as 0.

  This release covers subscription-based segments. User-based segment improvements are coming later in Q2 2026.
</Update>

<Update label="April 7 2026">
  **Updated User Profile page**

  The User Profile page has been redesigned with a tabbed layout and several new management actions directly on the page:

  * Add and remove Subscriptions from a User
  * Search across a User's data tags
  * Perform more direct edits and admin actions without leaving the profile

  The previous profile view is still accessible from the **Actions** menu if you need it.
</Update>

<Update label="March 25 2026">
  **test users now apply at the User level**
  Marking a Subscription as a test user now automatically marks all Subscriptions for that User as test users, effectively creating a Test User.

  * Any new Subscriptions added to a Test User will automatically be marked as test users.
  * Test User is now a User-level property rather than a Subscription-level one.

  **OneSignal Server SDKs just got their first v5 stable release!**

  After a period of testing and iteration, v5 is now the default version users will get when installing any of our server SDKs. Here are the current versions included in this release:

  | Language | Version |
  | -------- | ------- |
  | Node.js  | 5.4.0   |
  | Go       | 5.3.0   |
  | Java     | 5.3.0   |
  | .NET     | 5.4.0   |
  | Rust     | 5.3.0   |
  | Ruby     | 5.3.0   |
  | Python   | 5.3.0   |
  | PHP      | 5.3.0   |

  This release pairs well with our recently refreshed Server SDK Reference, giving developers a solid starting point for integrating with the OneSignal API.
</Update>

<Update label="March 20 2026">
  **Audit Log Export is now in GA**

  * Customers can now export audit logs. Customers can export 2 days for free tier and up to 90 days with security and legal entitlement (either as individual SKU or enterprise plan).
  * Provides customers additional metadata details and allows them to filter through data locally for their own audits and consumption with their own tools.

  **Failed Reasons in Audience Activity for everyone!**

  * Free plan users can now see exactly why individual audience members failed to receive a notification — directly in the Audience Activity view.
  * When a notification fails, especially common when troubleshooting set up, free users had no way to know whether the problem was a bad token, an unsubscribed user, or a device issue — leaving them guessing and unable to fix anything. Now they get the same failure visibility paid users have, so they can debug and get set up properly.
  * Same data retention as audience activity (30 days)
</Update>

<Update label="March 17 2026">
  **Data Model Updates and Field Deprecations**

  To improve platform performance, strengthen data integrity, and reduce the risk of configuration errors, we are introducing several updates to the OneSignal data model.

  These changes will take effect **April 15, 2026.**

  **Field Limits**

  We are introducing limits on two user fields to improve consistency and prevent unexpected behavior.

  Existing records exceeding these limits will not be modified to avoid disrupting current data and operations.

  **External ID**

  * `external_id` values can contain up to 128 characters.

  **Aliases**

  * Each user can have up to 10 aliases.
  * Each alias key and value can contain up to 128 characters.

  **Field Deprecations**

  We are deprecating several legacy Subscription fields that are no longer actively used:

  * `amount_spent`
  * `rooted`
  * `bought_sku`
  * `app_interests`
  * `purchased_items`

  After April 15, 2026, these fields will no longer be available in:

  * Segment Builder
  * API requests
  * Event streams
  * Webhooks

  **Impact for Customers Using These Fields**

  If your implementation currently references any of these fields:

  **Segments:** Segments using these fields will be paused and labeled for your review.

  **Journeys:** Journeys depending on those segments will be archived.

  **Event Streams and Webhooks:** These fields will return empty values.

  **What You Need to Do**

  Most customers do not need to take any action.

  If your implementation relies on any of the deprecated fields, we recommend reviewing your segments and integrations before **April 15, 2026.**
</Update>

<Update label="March 6 2026">
  Email Address Validation is now available!

  * When email addresses are added to OneSignal, they're now validated at three entry points:
    * API: syntax check
    * CSV import: full validation including typo detection, MX record lookup, disposable email flagging, and role-based address detection\*
    * Bulk validation: same full checks, runs against addresses already in your audience
  * Free plans have syntax and typo checks.
  * Paid plans will have syntax, typo, MX, disposable email, and role based email address checks.

  See [Email Address Validation](/docs/en/email-address-validation) for more details.
</Update>

<Update label="March 4 2026">
  **Dashboard layout redesign has shipped!**

  * Panel-based layout. The old floating card approach has been replaced with flat panels. The side nav sits in a clean gray panel, and the main content in a white panel. This simplifies the look and feel and gives us a more modern aesthetic.
  * New global top bar. Breadcrumbs, the new Create menu, Help/Support links, and Upgrade button all live in a new sticky top bar that follows you on scroll.

  **Richer date context across the dashboard**

  Dates show up everywhere in OneSignal — denoting message creation, notification send times, user sessions, etc. — but it wasn't always clear which timezone you were looking at, or how recent something actually was. This came up in a discussion last week among the dashboard engineers.

  Now, hovering over a date in the following areas of the Dashboard shows a tooltip with three pieces of context at once: the time in your local timezone, the time in UTC, and a relative timestamp (like "2 days ago").

  Where you'll see it:

  * Message lists and indexes
  * Message reports
  * Message review modals before sending
  * User and subscription profiles

  This is enabled for all apps — no action needed. Just hover a date and it's there!

  **In-App Message library with new quickstarts!**

  We've shipped a library of professionally designed, ready-to-use in-app message templates — available now to all plans in the dashboard.

  What's in it: 7 categories of quick starts covering the most common IAM use cases: push soft prompts, promotions, onboarding flows, feature announcements, location prompts, spin-to-win, and notification preference centers.

  How to access: Dashboard → Messages → In-App → New In-App → OneSignal Quick Starts. No feature flag or backend enablement required — available immediately. (See demo for the full experience in product)

  Go from zero to a production-ready in-app message in minutes, without writing HTML from scratch!
</Update>

<Update label="March 3 2026">
  **Enhanced Snowflake Integration Now Available!**

  Key improvements include:

  * 15-minute sync intervals (down from 24 hours)
  * Selective event syncing so customers only export what they need
  * Self-service setup directly in the OneSignal dashboard
  * New events like in-app impressions, email bounced/received, and separated Live Activity events.
  * We've also added richer properties including Template ID, last active timestamp, and subscription status.

  Customers get near real-time data in their Snowflake instance with full control over what gets synced meaning faster insights. Selective syncing alone can dramatically reduce event volume (and spend) by letting them export only the events that they need.

  This moves from the legacy flat annual fee to our Event Streams pricing model. Customers pre-purchase an event volume tier, and that tier covers all destinations (Snowflake, BigQuery, Databricks, etc.).

  Live now for all customers. All new customers will automatically have access to this new integration. Existing legacy Snowflake customers have until August 1st to migrate to the new integration before deprecation. Both integrations can run in parallel during the transition so they can ensure parity/consistency, and we will be doing outreach to those affected shortly.

  See [Snowflake](/docs/en/snowflake) for more details.
</Update>

<Update label="February 26 2026">
  **Audit Logs API is now available**

  Enterprise customers (with Legal & Security package) can now programmatically access the same audit log data surfaced in the OneSignal dashboard — pipe it directly into their SIEM, compliance tooling, or internal security workflows.

  * Returns a time-scoped record of actions taken in their org — who did what, when, and from where
  * Filter by app, action type, actor, target, or IP address
  * Supports cursor-based pagination for large result sets

  See [Audit Logs API](/reference/list-audit-logs) for more details.
</Update>

<Update label="February 9 2026">
  Huawei Badge Parameter Support

  We now support app icon badges on Huawei (HMS) devices via both the API and dashboard.

  * What's new: Three new parameters on `Notification#Create`
    * `huawei_badge_class` — the app's launcher activity class name (required for badge)
    * `huawei_badge_set_num` — set the badge to an exact number (0–99)
    * `huawei_badge_add_num` — increment the badge by a specific amount (1–99)

  On the dashboard, you'll see a new Badge option under Send to Huawei Android with "Don't set" / "Set to" / "Increase by" options.

  * Good to know:
    * Setting `huawei_badge_set_num` to 0 clears the badge
    * If neither set nor add is specified, the badge increments by 1 by default
    * Huawei does not auto-clear badges when the app opens
</Update>

<Update label="January 29 2026">
  API Documentation Improvements

  * New API endpoint: [View Segment](/reference/view-segment) - Retrieve details of a specific segment by ID, including optional segment filter details.
  * New API endpoint: [Update Segment](/reference/update-segment) - Update an existing segment's name and/or filters programmatically.
  * Fixed JSON example formatting across multiple API reference pages for improved readability:
    * Segments API: view-segments, create-segments, delete-segments
    * Users API: create-user, view-user, update-user, delete-user
    * Subscriptions API: create-subscription, delete-subscription, transfer-subscription, unsubscribe-with-token, create-alias-by-subscription
</Update>

<Update label="January 26 2026">
  **Audit Logs are now available!**

  * Customers now have the ability to determine exactly what's happening across their OneSignal account. Audit Logs gives them a complete timeline of every action taken in their organization—who did what, when, and from where.
  * Track 50+ action types including:
    * Authentication events (login, logout, API key operations)
    * Message activity (notifications sent, canceled, A/B tests, Journeys)
    * Team changes (member added, role changed, removed)
    * Configuration updates (webhooks, segments, templates, integrations)
    * Billing & subscription events
  * Powerful filtering:
    * Search by team member email
    * Filter by action type, app, IP address, or item type
    * Custom date ranges with presets
    * Shareable filtered URLs—customers can collaborate with their team instantly
  * Deep visibility:
    * Expandable rows reveal 30+ fields: IP address, browser, location, correlation ID, API version, and more
    * Available at both App and Organization levels
    * Quick-access links from Journeys, Segments, Templates, Notifications, and more
  * Retention:
    * Legal & Security package: 90-day lookback
    * All other plans: 2-day lookback
  * Perfect for security audits, debugging, and understanding team activity at a glance.
</Update>

<Update label="January 9 2026">
  * Standardized time series for charts are now available for:
    * Event Streams and webhooks
    * Email delivery reports
    * SMS/RCS delivery reports
</Update>

<Update label="December 22 2025">
  * confirmed receipt Now Available On Engagement Trends
    * Customers with access to confirmed receipt can now see confirmed receipt on the Engagement Trends Time Series Chart.
    * This missing data was a common point of confusion for customers. They could see confirmed receipt & click through rate, but had no access to the total confirmed deliveries metric.
    * This additional data point gives customers confidence in the rates we're showing and helps with confusion on the difference between "delivered" and "Confirmed receipt" for push notifications.
</Update>

<Update label="December 12 2025">
  * New integration - Self-serve Snowflake data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake without going through customer support
    * The legacy Snowflake documentation remains available for existing implementations
</Update>

<Update label="December 8 2025">
  Live Activities in Event Streams & Integrations

  Live Activities Analytics provides two key capabilities to optimize customers' live activity strategy:

  1. Better Troubleshooting with confirmed receipt
     Gain visibility into whether devices actually received live activity updates. confirmed receipt tracking identifies delivery issues quickly to understand the true reach of live activities.
     Available in:

  * Individual message reports with per-device confirmation
  * Data exports to BI tools (through event streams and integrations)

  2. Deeper Engagement Insights with data exports to integrations & event streams
     Answer critical questions about how users interact with your live activities:

  * How many users engaged with my live activity over its duration?
  * When did users drop off?
  * What was the peak engagement time?
  * When did users click? (coming soon)

  Export live activity data to BI tools to analyze engagement patterns, optimize timing, and improve future campaigns.
</Update>

<Update label="December 5 2025">
  We've launched a new [Metrics Glossary](/docs/en/analytics-metrics-glossary) in our documentation. This resource provides a single source of truth for delivery metric definitions, helping both our team and customers understand our metrics consistently across dashboards, APIs, and exports.
  While we continue working toward unified terminology across all touch points, this glossary establishes clear mappings and definitions as they exist today, making it easier for customers to navigate our current analytics landscape.

  Custom Events in User Activity Timeline
  Custom events are now visible per User on their profile page in a dedicated tab. You can:

  * Filter by event type and event source
  * Filter by date, to any time window in the past. Only limiting factor is customer's own events retention window setting!
  * Expand each event to see the full payload
  * Click through to the events index to see that event type's config and full cross-user activity log

  This is important because:

  * It helps paint the complete picture of user activity. At a basic level, customers ask the question, "what's going on with this user?" and this helps answer it.
  * Especially useful for zoomed-in troubleshooting, auditing, what-happened analysis.
  * Please note: this will only be visible to customers in Custom Events early access, but will be available to all as they gain access to Custom Events
</Update>

<Update label="November 26 2025">
  UX Improvements Now Live

  1. Row-Level Linking
     You can now click anywhere on a table row to navigate to its destination, instead of having to click a specific cell. This makes navigation faster and more intuitive.
  2. Row Highlighting on Hover
     All tables now highlight the entire row on hover, helping users track data more easily and reducing visual strain when scanning wide tables.
  3. Improved Responsiveness
     The actions column has been narrowed to preserve horizontal space and is now right-aligned at the end of every table.
     It also features sticky, floating behavior — especially useful on smaller screens where horizontal scrolling is required.
     Some tables better truncate long text (e.g., lengthy message names) more effectively to maintain a clean layout.
  4. Refined Sorting UX
     Updated sort icons make the sort direction easier to interpret. Clicking anywhere on a column header now toggles sorting, improving ease of use.
  5. Unified Column Visibility Menu (Applies to Journeys, Users, Subscriptions)
     Tables with customizable columns now use a consistent, cleaner UI. Column changes update live as you toggle them.
  6. Updated Search Bar UI
     The search bar now aligns with design standards, featuring a left-aligned search icon, and a button that shows after typing for easy input clearing.
  7. Improved Pagination Formatting
     Pagination controls now use comma formatting for large numbers, improving scannability and readability.

  Core Component Update
  Many of the enhancements above come from migrating these tables to our core design system’s DataTable component. Sorting and filtering improvements for tables are consistently among the most requested features we receive. While these updates don’t introduce new sorting or filtering behavior yet, this component upgrade provides a more consistent experience for the functionality we have today, and does lay the foundation for Product teams to build more advanced table capabilities once those initiatives are prioritized.

  Coming Soon

  * Most tables across the Dashboard already include these improvements. A few remaining areas still require component updates before they can adopt the full set of new enhancements:
    * In-app index
    * Templates index
    * Audience activity table
    * A/B tests stats table
</Update>

<Update label="November 12 2025">
  UX Enhancement: Duplicate Templates Directly from the Editor
  In usability tests and dogfooding sessions, we noticed users often duplicate Journey nodes and then edit their templates. Previously, you had to exit the template editor and duplicate the template from the index view, an extra step that interrupted the workflow.
  Now, you can duplicate templates directly from the actions dropdown in the template editor. This small but meaningful improvement streamlines your editing experience and makes iteration faster. While our long-term goal is to enable template/content editing directly within Journeys, this enhancement is a great step in that direction.

  New Platform Filters for Engagement Trends & Subscription Trends
  You can now filter push engagement trend data by platform (iOS, Google Android, Huawei, etc.) to get a more granular view of performance across specific devices.
  In the spirit of our Analytics Consistency project, we've also brought this same filtering experience to Subscription Trends.

  Analytics Consistency: Standardized Time Series Chart Filters
  We're standardizing filter options across our time series charts, giving customers a consistent experience and clear access based on their plan.
  Key Changes:

  * All charts will share the same set of granularity and look back filters
  * Consistent casing and terminology used on all filters
  * Consistent upgrade experience for customers on plans with limited access
    As an example, Subscription Trends now supports a 2 year look back after the change.

  Charts where we've already rolled out these changes:

  * Engagement Trends
  * Subscription Trends
  * Global Outcomes
  * Push Delivery
  * All Template Reports
  * Coming Soon:
  * Email Delivery
  * SMS Delivery
  * Journeys Reports

  Look back access based on plan type:

  * Free: 30 days
  * Growth: 90 days
  * Professional: 1 year
  * Enterprise: 2 years
  * Custom: Up to 90 days (based on plan types above)
</Update>

<Update label="October 6 2025">
  Nice UXE on Journey Settings. We’ve updated the Journeys Settings Side panel to be more user friendly by adding a side navigation to keep each section in focus. This is in tandem with the eventuality of having more settings available to the user as we look towards Journey Goals, and more.  We will accompany this release with an intercom slide letting the user know we have updated the settings area as to give them a heads up due to the abrupt pattern change.

  Every Setting, In Focus: Journey Settings are now grouped and spotlighted, helping you zero in on each choice without distraction.
</Update>

<Update label="October 2 2025">
  Custom Events are now available to all customers on paid plans! You can now send custom events via our API or SDK, and use them to trigger actions in Journeys with your own event data.
</Update>

<Update label="September 21 2025">
  Customers can now pause a segment that's counting towards their segments entitlement even though it's only being used in an archived journey or paused IAM. We also made it even easier to pause segments, if the user wants to pause a segment, we'll help the user pause or archive the active IAMs or journeys stopping the user from pausing a segment.
</Update>

<Update label="September 9 2025">
  Deactivate email senders

  Deactivate email domains that are no longer in use or were set up incorrectly. This includes fallback handling for your email templates and scheduled sends to make sure you don't break them by removing a domain, just in case it was being used more widely than you anticipated.
</Update>

<Update label="August 29 2025">
  Personalize emails with real-time Data Feeds

  You can now use Data Feeds to pull live content from your APIs directly into emails at send time. No more static CSVs or preloaded tags — every message can include the latest account details, product recommendations, or order updates.

  Available in the email template composer for emails sent via Journeys, Data Feeds includes preview tools and error handling to keep sends smooth.

  👉 See how to set up [Data Feeds](/docs/en/data-feeds)
</Update>

<Update label="August 04 2025">
  You can now hold users in a Journey step until specific conditions are met before they move forward with the *Wait Until* action. This new feature allows you to:

  * Hold users at a step until they enter a segment or trigger a message event (such as a specific message being delivered, opened, or clicked).
  * Add multiple conditions and branch users based on whichever condition they meet first.
  * Set an expiration path that moves users forward or removes them from the Journey if none of the conditions are met within your chosen timeframe. This gives you greater flexibility and control over how users progress through your Journeys. Learn more: [Journeys Actions](/docs/en/journeys-actions)

  AI Composer Push Notifications
  You can now generate or improve push notification message copy using the AI message composer. This update helps you craft high-performing content without leaving OneSignal. When creating a new push notification, select AI-generated push button to get started. To improve existing copy, select “Refine” in the Title, Subject, or Message fields.

  New [Integrations](/docs/en/integrations) index page contains the following enhancements:

  * Filtering by type of integration
  * Filtering by Inbound/Outbound directions of data flow
  * Includes our new inbound DWH/Data ingestion options for custom events
</Update>

<Update label="July 07 2025">
  * Quickly identify and manage segments tied to campaigns
    * We’ve made it easier to clean up outdated segments.
    * Previously, you couldn’t delete a segment if it was tied to an In-App Message (IAM) or Journey, even if that campaign was paused or archived. Now, when you try to delete a segment, you’ll see a modal listing all IAMs and Journeys that are preventing deletion.
    * This helps you quickly locate and update the associated campaigns, so you can keep your workspace clean and organized without having to hunt through every Journey or IAM.
</Update>

<Update label="June 30 2025">
  * Segment users based on real message engagement
    * You can now create user segments based on how they interacted with previous messages across push, email, SMS and in-app.
    * This update adds a new Message Event filter that allows you to segment users based on events like email opens, push clicks, SMS failures, and more - without relying on tags or external tools.
    * Available on all paid plans.
    * See [Segmentation](/docs/en/segmentation#message-event-filters) for more details.
</Update>

<Update label="June 27 2025">
  * New documentation with Mintlify!
    * We've updated our docs!
    * New AI features and easier readability.
    * Updated API reference and openapi spec.
    * New Tutorials page with common use cases and step-by-step details to get you setup quickly!
</Update>

<Update label="June 18 2025">
  * Track In-App engagement trends alongside push, email, and SMS
    * Customers can now see In-App Message impressions, clicks, and click-through rates directly in the Engagement Trends chart. This update gives marketers a unified view of how users are interacting with all message types over time—including In-App—making it easier to spot trends, report on performance, and optimize messaging across channels.
    * With this update, In-App engagement data is now included alongside push, email, and SMS across all views in the Engagement Trends chart. Stats are grouped by day and support up to two years of data (depending on plan). This data is exportable via CSV just like other channels, and can be filtered to look at specific date ranges or message types.
    * This feature is available to all customers.
</Update>

<Update label="June 12 2025">
  * Unlock deeper email engagement insights with multi-link tracking
    * Customers can now track engagement on every individual link within their emails. This update gives customers a much clearer view into what content or messaging is working so they can improve email performance over time.
    * Previously, when customers included multiple links within an email, they could only view total click counts across all links. Now, they can see which specific links get the most engagement and how links perform inside journeys. This helps them refine content and messaging strategies.
    * Multi-link tracking is automatically applied to most emails created in the Drag & Drop or HTML editor. Link-level performance metrics will also be available for emails sent using a template and emails in a Journey.
    * This feature is available to all customers with access to email.
</Update>

<Update label="May 23 2025">
  * View and optimize message performance with Template Analytics
    * OneSignal customers can quickly assess how individual templates are performing across all messages, without needing to download and stitch together separate reports.
    * When users click into a template, they now land on a detailed analytics view showing Delivered, Unique Opens, Unique Clicks, and Unsubscribes. They can track performance over time, filter by platform, explore delivery breakdowns like Failed or Capped, and review a list of messages that used the template.
    * Template analytics is especially useful for:
      * Marketers who test and iterate on message content
      * Developers who need visibility into transactional message delivery
      * High-volume senders seeking scalable insights
    * Transactional visibility is a key differentiator that sets us apart from Firebase and other open source solutions. Customers can now answer questions like “How many Account Confirmation emails did I send last week?” or “What was the click-through rate on my Password Reset messages?”
    * Important note: For templates created before April 17, 2025, enhanced metrics are only available for messages sent after that date. Customers can use the “Show historical data” toggle at the top of the page to see earlier performance data.
    * The feature is live and available by default. Reporting history varies by plan:
      * Free: 30 days
      * Growth: 90 days
      * Professional: 1 year
      * Enterprise: 2 years
</Update>

<Update label="May 16 2025">
  * Add users manually from the dashboard
    * You can now create new users directly from the *Users* tab in your OneSignal dashboard using a simple form. This update makes it easy to manually add a user with an email address, phone number, or both without needing an SDK, API call or CSV upload.
    * This is especially helpful for quickly testing campaigns or adding users who aren’t yet in your system.
</Update>

<Update label="May 14 2025">
  * Track SMS link performance directly in OneSignal
    * Customers can now track SMS link performance directly in OneSignal without needing third-party tools like Bit.ly or custom UTM parameters. This feature gives our customers a more streamlined, built-in way to measure engagement and optimize messages faster, removing friction and helping drive better results from their SMS efforts.
    * When composing an SMS message, customers simply click “Insert Trackable Link” and enter the full URL they want to send users to. OneSignal automatically shortens the link using the 1sgnl.co domain so it fits within SMS character limits and can be tracked.
    * All SMS users will have access to trackable links as part of their existing plan.
</Update>

<Update label="May 07 2025">
  * Simplify message organization with easier label management
    * Now you can add labels to your messages to help you organize and manage them.
    * See [Labels](/docs/en/labels) for more details.
</Update>

<Update label="May 01 2025">
  * Template analytics
    * You can now view and optimize template performance from a centralized reporting view. Click into any message template to view detailed performance data across every message a template is used in.
</Update>

<Update label="Apr 25 2025">
  * Improved CSV Importer
    * **Real-time validation:** Get instant feedback on formatting errors before upload.
    * **Smart column mapping:** Easily align your CSV headers with OneSignal fields.
    * **Email suppression support:** Add or manage your suppression list directly in the file.
    * **Upload history:** View the status of your past imports for up to 30 days.
    * **Helpful templates:** Start quickly with a pre-built CSV example.
</Update>

<Update label="Apr 21 2025">
  * Fine-tune your Live Activities with new API parameters
    * You can now add more control, reliability, and speed to your Live Activities with three new parameters in the OneSignal API: - ios\_relevance\_score: Helps determine which Live Activity displays most prominently on iOS. - include\_aliases: Allows you to target individual users directly rather than relying on segment-based delivery. - idempotency\_key: Prevents the creation of duplicate Live Activities when retrying start requests if not using the OneSignal SDK.
</Update>

<Update label="April 14 2025">
  * New integration - Databricks data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Databricks. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Databricks, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="April 08 2025">
  * View opt-out status by sender and support transactional messaging even with marketing opt-outs
    * You can now see SMS opt-out status by sender, giving you better visibility and control when managing marketing and transactional messages.
    * With this update, you can:
      * View subscription status by individual sender for any phone number
      * Continue sending transactional messages (like OTPs or alerts) even if a user has opted out of marketing
      * Maintain deliverability and avoid carrier filtering by respecting opt-out preferences
    * This is especially useful if you manage separate senders for promotional and transactional use cases.
    * To access this feature, go to **Consent Management > Advanced Opt-out Settings** and turn off the setting that globally unsubscribes a user when they reply with an opt-out keyword.
    * *Note: This option is only available to customers using advanced opt-out settings for SMS.*
</Update>

<Update label="March 19 2025">
  * Easily find and select the right templates with visual previews
    * Quickly identify and select your email and in-app message templates with the new updated card view.
    * Instead of relying on template names alone, you can now see clear visual previews, making it easier to choose the right template at a glance.
</Update>

<Update label="March 12 2025">
  * Create users in OneSignal via HubSpot workflows
    * Keep your users in sync across HubSpot and OneSignal! With this new workflow action, you can now create users in OneSignal whenever a HubSpot workflow trigger fires. This enables you to queue up personalization details (such as Tags) and plan engagement strategies before a user even interacts with your mobile platform. Additionally, you can trigger an SMS or email via HubSpot while simultaneously creating a user in OneSignal—ensuring seamless and immediate engagement.
    * [HubSpot Documentation](/docs/en/hubspot)
  * Push preview accuracy improvements
    * As operating systems update, they often introduce new changes in their push designs.
    * We've updated our previews so they match latest and greatest push notification designs across iOS (18), Android (15), Windows (11), macOS (Sequoia). This ensures you see what your users will see when testing in OneSignal.
  * PII Masking of Emails and Phone Numbers
    * Protect user privacy and reduce compliance risks by masking personally identifiable information (PII) such as emails and phone numbers. With PII masking, your team can work securely while still analyzing campaign performance and sharing insights across teams.
    * OneSignal automatically masks phone numbers and emails in the dashboard and any data exported directly from the platform. However, PII masking does not currently apply to data accessed via API requests, external IDs, or Tags.
</Update>

<Update label="March 07 2025">
  * Verify & Lookup Phone Numbers
    * Sends the user a one-time verification code to ensure the customer owns the phone #
    * Confirms the phone number entered by a user at onboarding is valid
</Update>

<Update label="February 28 2025">
  * Added New Integration - [BigQuery Data Export](/docs/en/bigquery)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to BigQuery. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in BigQuery, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
  * Channel subscriber counts have moved
    * The counts of subscribed counts for each channel have moved from the dashboard to the Subscriptions page in OneSignal. Now you will see the number of *Subscribed* subscriptions for each channel at the top of the Subscriptions page under Audience to get an overview of audience reach per channel in the context of your subscriptions.
    * If you still wish to view this information on the Dashboard, you can filter your Subscriptions trends chart by channel.
</Update>

<Update label="February 14 2025">
  * Improvements to Keywords
    * We've made a couple of improvements to our SMS keywords.
      * Segment by subscription status when sending a keyword to encourage converting your customers who are not yet subscribed into opting in to your SMS marketing messages
      * Setup an auto-responder for unrecognized keywords
</Update>

<Update label="February 12 2025">
  * New Engagement Analytics on the OneSignal Dashboard

    * Are you curious to learn more about how your end users engage with the messages you send from OneSignal? Head to your Dashboard to see the new Engagement Trends report.
    * With this report you will gain insight into how users engage with your messages across Push, Email, and SMS. Track click-through-rate, unsubscribes, and monitor trends over time to refine your messaging strategy and optimize communication frequency. This comprehensive report consolidates data from all message types (Dashboard, API, Journeys) for a clearer view of performance. Now available in your OneSignal dashboard!

    <Frame>
      <img alt="New Engagement Analytics on the OneSignal Dashboard" />
    </Frame>
</Update>

<Update label="January 29 2025">
  * Sort segments by Last edited, Created at and more
    * Finding and managing your segments just got easier!
    * You can now sort segments by Last edited, Created at and more.
      * This update is especially valuable for customers who:
        * Maintain numerous segments
        * Frequently update their segment configurations
        * Need to identify and clean up outdated segments
        * Want to quickly find recently modified segments
</Update>

<Update label="January 27 2025">
  * Email Senders (Multi-Domain Sending)
    * Create distinct senders for different types of communications:
      * Keep your marketing campaigns separate from crucial transactional emails
      * Maintain different brand voices for various product lines
      * Optimize sender reputation for each type of communication
      * [Email Senders](/docs/en/senders)
  * Improved In-app Message Analytics for Event Streams
    * We've added a new In-app Message Analytics for Event Streams.
</Update>

<Update label="January 21 2025">
  * Email Intelligent Delivery
    * We've added intelligent delivery to email.
    * Transform your email engagement with OneSignal's latest breakthrough: Intelligent Delivery. This powerful new feature automatically determines the optimal time to reach each individual user, maximizing your email campaign's impact.
    * Our algorithm continuously learns from:
      * User open patterns
      * Click-through behavior
      * Real human interactions (excluding bot activity)
</Update>

<Update label="January 16 2025">
  * Retirement of Automated Message for Free apps
    * Automated Messages are no longer supported and the feature has been retired in the free plan. Paid apps will continue to have access to this feature until further notice.
    * Active automated messages will remain live and continue functioning as expected. However, you can no longer create new automated messages, or reactivate paused automated messages. To build new automated sequences and enhance your campaigns, we recommend using [Journeys](/docs/en/journeys-overview).
</Update>

<Update label="January 15 2025">
  * Customize how your users re-enter split branches
    * Now you can customize how your users re-enter split branches. This feature is available for all Journeys.
    * [Journey Entry Triggers](/docs/en/journeys-actions)
  * Improving New Message Experience
    * We improved the new message experience by adding a library of templates (get inspiration for your next push, in-app, email, or SMS), or quickly start from a template you've made, or a previous message.
</Update>

<Update label="January 03 2025">
  * message.url - New Push Event Stream Property
    * `message.url` is now a supported property for push events. It enables the retrieval of the launch URL directly from your event stream payload.
</Update>

<Update label="December 24 2024">
  * Journeys Multi-split Branching
    * Now you can set up more personalized paths in your Journey. Create up to 20 branches to test channels, content, timing, ordering, and more. Assign different weights to each branch, or easily distribute audiences evenly across all branches. See how different paths perform against each other or against a control group.
</Update>

<Update label="December 20 2024">
  * WordPress Plugin v3
    * We've upgraded our Wordpress Web Push plugin to v3+. What's changed:
      * Upgrades the OneSignal Web SDK from version 15 to 16.
      * Setup more new prompts within the OneSignal dashboard, including the following. No custom code is required anymore to configure these.
        * Category Prompt
        * Email/Phone Slide Prompt
        * Custom Link Prompt.
      * When publishing a new post, check the "Send notification when post is published" box to send a push notification.
      * Choose which audience segment should receive notifications for each post.
      * Web Topics are included by default.
      * Send to mobile app subscribers, with an option to direct them to a different URL (Deep Link).
</Update>

<Update label="December 11 2024">
  * Improved Logs in Event Streams
    * We've improved the Event Streams feature to make troubleshooting simpler and faster. Now, you’ll find dedicated tabs for successful and failed events, making it easier to spot issues at a glance. Clear empty states show when there’s no data in either tab, and updated messaging ensures you know the logs display a sample of your data.
  * SMS Keywords
    * We've added keywords for SMS. Keyword engagement enables quick, two-way communication, enhancing personalization, accessibility, and user satisfaction. It drives conversions and higher engagement with your subscribers. Add a data tag to the keyword, and segment based on their preferences to send more targeted SMS.
  * Quickstart Segments

    * We are thrilled to launch three new segment templates designed to help you hit the ground running with proven strategies:
      * First-Time audience
      * Regional audience
      * Custom Audience based on tags
    * Our analysis of 6.3 billion message deliveries uncovered powerful insights. These templates are built to help you:
      * Create high-performing segments from day one.
      * Use proven filter combinations that drive higher engagement.

    <Frame>
      <img alt="Quickstart Segments" />
    </Frame>
</Update>

<Update label="December 02 2024">
  * Email Quickstart Templates
    * We've added a library of quickstart templates for email. Explore our library of professionally crafted email templates, designed to inspire your creativity and elevate your email campaigns. Use them as a starting point to create impactful messages that drive conversions and engage your audience effectively.
</Update>

<Update label="November 27 2024">
  * Scheduling Journeys
    * Now you can schedule Journeys to send at a specific time. This feature is available for all Journeys.
  * Settings Overview Page
    * Now you can access and manage all your settings in a centralized setting overview page. Platform-specific settings have been reorganized under their relevant channels for better clarity.
</Update>

<Update label="November 20 2024">
  * Bulk Archive and Delete Journeys

    * Now you can bulk archive or delete Journeys from the Journeys index. Select up to 20 Journeys, and then choose an action you'd like to take to clean up Journeys you're no longer using.

    <Frame>
      <img alt="Bulk Archive and Delete Journeys" />
    </Frame>
</Update>

<Update label="November 06 2024">
  * Improved Export for Global Outcomes
    * We've improved the export for Global Outcomes to include more data and make it easier to use in your reporting.
  * Preview allows you to preview the content of a message and can be very helpful when you have a message with personalization (i.e. Tags, dynamic content, custom data). With preview, you can preview content from a specific test user's perspective, or with example custom data.
  * Settings for Email & Side Navigation Updates
    * In the side navigation, you can now easily see your Push, SMS, and Email settings. What was once "Messaging" is now "Push" settings, and SMS and Email Settings will take you directly to your channel's settings.
    * For email, we've created a dedicated place to manage your email provider and senders. If you are a OneSignal mail user, you'll also be able to see your reputation and suppression lists here.
  * SMS Usage
    * We've added SMS Usage in the Usage page. We've also added a breakdown so you can see the message type, and a breakout by inbound and outbound. You may see an unknown country if a segment failed to send.
</Update>

<Update label="October 02 2024">
  * Add Notes on your Journeys
    * Now you can add notes to the steps of your Journeys to keep reminders and more effectively collaborate and share information with your team. This feature is available for all Journeys.
</Update>

<Update label="September 27 2024">
  * New Quickstart Journeys
    * We've added a new Quickstart Journeys to help you get started with Journeys. This feature is available for all Journeys.
  * SMS Text-to-Subscribe
    * It's now easier to set up double opt-in and text-to-subscribe phone number collection experiences for your customers!
</Update>

<Update label="September 12 2024">
  * Confirmed Click-Through-Rate (CCTR) metric

    * We have added a new metric to measure the CTR using confirmed receipt. Confirmed Click-Through-Rate (CCTR) is measured by (total clicks/confirmed delivered) \* 100%

    <Frame>
      <img alt="Confirmed Click-Through-Rate (CCTR) metric" />
    </Frame>
</Update>

<Update label="September 06 2024">
  * Export your Subscription Trends
    * Now you can export the data from your Subscription Trends report as a CSV. If you apply filters to the report, OneSignal will export based on the filters you've applied so that you can fine-tune the data that you use to evaluate your messaging audience.
</Update>

<Update label="August 05 2024">
  * Email Saved Rows
    * Saved Rows are reusable content blocks that help streamline email creation and management. Many companies, especially those that have a lot of templates, prefer to use saved rows in their emails for consistency and to save time. Saved Rows are easily attached to new emails so you don't have to create the same information from scratch each time. And when things change, you just have to update the saved row, and your updates will automatically sync across all campaigns that have that saved row attached.
    * Common use cases include:
      * headers (logo, slogan)
      * footers (company details, social media links, mailing addresses)
      * disclaimers
      * other elements that are used across multiple campaigns
    * You can now save Email Drag-and-Drop rows to use across many Campaigns or Templates. These re-suable **Saved Rows** make it easy to sync updates across many emails at once. Click on the **Rows** tab of a Drag-and-Drop email, to view your **Saved Rows**. To save your first row, click the save icon in the edit, in the top right corner of the row.
    * We recommend you set up all of your templates to use saved rows for your header and footer so that you need to update the branding or content; you only have to make those edits once.
</Update>

<Update label="July 30 2024">
  * Journeys now target anonymous users
    * Now, Journeys do not require External IDs to be set on subscriptions. Instead, Journeys will target your entire user base within OneSignal, including anonymous users. We recommend still configuring External IDs to identify individual users who have subscribed to multiple channels.
</Update>

<Update label="July 25 2024">
  * Have more visibility into SMS unsubscribes, resubscribes, and help keywords
    * We now make it easier to manage your Consent Keywords within Onesignal. Reach out to support if you'd like to update the default consent keywords and replies.
</Update>

<Update label="July 19 2024">
  * Email Reply-to field now supports custom properties
    * Now you can use [Message Personalization](/docs/en/message-personalization) within the `reply-to`field on an email. This allows you to direct message replies to the right inbox and can be helpful if you are sending from different brands or across different countries.
</Update>

<Update label="July 16 2024">
  * Push Failures and Unsubscribes in Audience Activity
    * Obtain a list of subscriptions that have faced errors - failures or unsubscribes, for a specific push notification in the push report page.
</Update>

<Update label="July 03 2024">
  * Integrations: OneSignal Message Events can be sent to Twilio Segment
    * Customers can now select and send message events from OneSignal to sync back to their Twilio Segment account, making the Segment integration bidirectional.
  * Use Audience Activity for Live Activities to get a list of recipients
    * Get a list of subscriptions that successfully or failed to receive a Live Activity on a Live Activity report page, which is accessible through the Delivery - Sent Index. This list can be exported as well.
</Update>

<Update label="June 06 2024">
  * In-app message audience activity
    * In the report page of an in-app message, you can now see which mobile subscriptions viewed (impression) or clicked on an in-app message. Audience activity is available for 30 days from the time the message is displayed
</Update>

<Update label="May 15 2024">
  * FCM Expired Tokens > Increased Android Unsubscribes
    * On May 15, 2024, Google's FCM service will start to expire stale push tokens for devices that have been inactive for more than 270 days. You may see a spike in Android unsubscribes when sending notifications due to this change. Don't panic! These are devices that have not been online in over 270 days and are part of Google's [Best practices for FCM registration token management](https://firebase.google.com/docs/cloud-messaging/manage-tokens). If the device does come back online and opens your app, OneSignal will automatically resubscribe them to push if they were previously subscribed already.
    * See [FCM Expired Token FAQ](/docs/en/fcm-expired-token-faq) for more details.
</Update>

<Update label="April 29 2024">
  * Configure more granular Frequency Capping rates for Push
    * Push notifications can now be capped at a rate of x notifications per any time frame (less than 1 week). Navigate to Settings > Messaging > Push Frequency Capping > Custom (in the time dropdown) to view these settings.
    * Read [Frequency Capping Documentation](/docs/en/frequency-capping) for more details.
</Update>

<Update label="April 11 2024">
  * Added Android Live Notifications
    * Android's Live Notifications deliver live, dynamic content in notifications to enhance user engagement and app interactivity. This is a feature similar to iOS's Live Activities feature (introduced with iOS 16), but uses its own set of tools and APIs that enable similar functionalities.
    * See [Android Live Notifications](/docs/en/android-live-notifications) for more details.
  * Major improvements to Android SDK
  * Push to start Live Activities
    * Live Activities can now be launched on a user's screen when the mobile app is in the background (app is not open). Live Activities can both be started and updated by a remote push notification.
    * [How to start a Live Activity with a remote push notification](/docs/en/live-activities)
</Update>

<Update label="April 01 2024">
  * Added Audience Activity reports for Journeys
    * We have added Audience Activity reports for Journeys so you can get a closer look at which subscriptions were sent messages during a Journey. To view this report, click into a message report on your Journey. [Learn more here](/docs/en/journeys-analytics#audience-activity).
</Update>

<Update label="March 18 2024">
  * Added a new Setup guide for Analytics
    * We have added a new Analytics Setup guide to our product documentation detailing how to track Confirmed Deliveries and set up Custom Outcomes with support from your development team.
</Update>

<Update label="March 12 2024">
  * Mobile SDK Updates
    * We recommend updating to the latest SDK versions listed below to benefit from critical bug fixes, stability improvements, and new features. These updates include key enhancements across all platforms, including iOS 5.1.3 and Android 5.1.6, which improve concurrency safety, crash resilience, and background thread handling. The updates also include important API adjustments like more accurate property handling in the `PushSubscriptionState`.
</Update>

<Update label="February 16 2024">
  * Journeys is now available on the Growth plan
    * Journeys is now available on the Growth plan. This means you can now create and manage Journeys with up to 100,000 users.
    * See [Journeys](/docs/en/journeys-overview) for more details.
</Update>

<Update label="February 12 2024">
  * Added Auto Warm Up
    * We have added a new feature that allows you to automatically warm up your app when a user opens it. This feature is available for all OneSignal customers.
    * See [Email Warm Up](/docs/en/email-warm-up) for more details.
</Update>

<Update label="February 02 2024">
  * Journeys has easier targeting based on user activity
    * We've added support for Segments with time-based rules (e.g., first session, last session, etc.) and also simplified targeting inactive users. Now you can target your inactive users by including a segment based on last session behavior.
  * Email: Schedule Sends Across Different Timezones
    * Email campaigns can now be scheduled to send across different timezones. This feature is available for all OneSignal customers.
</Update>

<Update label="January 30 2024">
  * Email now supports One Click Unsubscribe
    * Inbox Service Providers (ISP) like Gmail, Outlook, iOS Mail, and Yahoo! Mail, AOL, and Verison Mail require senders to provide a One Click Unsubscribe option. The unsubscribe button is rendered at the discretion of the ISP based on sending criteria, which may include a daily sending volume greater than 5,000 emails.
</Update>

<Update label="December 18 2023">
  * Filter your messages with labels
    * Now you can filter your messages with [labels](/docs/en/labels). This feature is available for all OneSignal customers.
  * CSV Importer can now update properties
    * CSV Importer for email now enables updates to user properties `language`, `country`, and `timezone_id`.
  * Send more personalized messages and multi-language emails
    * [Dynamic Content Documentation](/docs/en/dynamic-content)
</Update>

<Update label="December 14 2023">
  * All OneSignal apps now belong to an Organization
    * We have added a new feature that allows you to manage your OneSignal apps within an Organization. This feature is available for all OneSignal customers.
    * See [Apps, Orgs, and Accounts](/docs/en/apps-organizations)
  * Journeys now has better analytics
    * We've added a new Journeys Report. See [Journeys Analytics](/docs/en/journeys-analytics) for more details.
</Update>

<Update label="November 22 2023">
  * Removed Journey Notifications from Delivery Reports and the View Notifications endpoint
</Update>

<Update label="October 04 2023">
  * Added new integration - [Snowflake](/docs/en/snowflake)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Snowflake, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="September 27 2023">
  * You can now save and continue
    * Changed the default option for saving a message to save work without exiting the message.
</Update>

<Update label="September 13 2023">
  * Added the ability to adjust the default padding for IAM blocks
    * Learn more about [IAM blocks](/docs/en/design-your-in-app-message)
  * Added the ability to edit entry triggers and re-entry rules for live Journeys
    * Learn more about [Journey entry triggers](/docs/en/journeys-overview)
</Update>

<Update label="September 05 2023">
  * Added ability to create multi-language push messages by pasting your CSV
    * Learn more about [Multi-language messages](/docs/en/multi-language-messaging)
  * Added new "Editor" role permissions
    * Learn more about [Managing team members](/docs/en/manage-team-members)
  * Added enhanced Journey message stats and reports.
    * Learn more about [Journey message stats and reports](/docs/en/journeys-analytics)
</Update>

<Update label="September 01 2023">
  * Added a new feature to forward email templates to an app
    * Learn more at [Email Template Forwarding](/docs/en/email-template-forwarding)
  * Added FCM v1 API support for Android Push Notifications
    * Learn more about [Android Firebase credentials](/docs/en/android-firebase-credentials)
</Update>

<Update label="August 15 2022">
  * Android 13 changes
    * Android 13 introduces a runtime notification permission, meaning users must opt in to receive push notifications. Apps targeting Android 13 must explicitly prompt for permission at a time of their choosing, or the system will display the permission prompt automatically on first launch—often resulting in lower opt-in rates.
    * See [Android 13 Push Notification Developer Update Guide](/release-notes/android-13-push-notification-developer-update-guide) or our [Prompt for Push Permissions](/docs/en/prompt-for-push-permissions) guide for details.
</Update>


# SDK Releases
Source: https://documentation.onesignal.com/release-notes/sdk-releases

View the latest OneSignal SDK releases and updates.

## Mobile

<SdkReleasesIframe />

## Web

<SdkReleasesIframe />

## Server

<SdkReleasesIframe />

## Plugins

<SdkReleasesIframe />


# Web SDK reference
Source: https://documentation.onesignal.com/docs/en/web-sdk-reference

Complete API reference for OneSignal Web SDK v16 with initialization, user management, push notifications, slidedown prompts, and debugging methods. Learn how to implement web push notifications, manage user subscriptions, and integrate email/SMS features.

## Setup & debugging

You may need to wrap OneSignal calls in `OneSignalDeferred.push(async function (OneSignal) { ... })` (use `function (OneSignal) { ... }` when you do not need `await`). The **`OneSignal`** argument is the SDK instance used throughout this reference (for example `await OneSignal.init({ ... })`).

You can push several callbacks, or put multiple statements inside one callback.

The OneSignal SDK is loaded with the `defer` attribute on your page. For example:

`<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>`

That way the SDK runs after the document is parsed and does not block rendering. Scripts that run earlier still need a place to queue work until the SDK is ready. Start with:

`window.OneSignalDeferred = window.OneSignalDeferred || [];`

That line defines `OneSignalDeferred` if it is missing. If an earlier snippet on the page already set it, the same reference is kept; otherwise it begins as an empty array `[]` you push callbacks onto.

Arrays expose a [`.push()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) method, so you enqueue functions with `OneSignalDeferred.push(...)`. When the SDK loads, it drains the queue and redefines `.push()` so later pushes run immediately (see the [Web SDK source](https://github.com/OneSignal/OneSignal-Website-SDK)).

<Note>
  Most snippets below use `OneSignal` alone. Treat that as the instance from your deferred callback after `await OneSignal.init({ ... })`, unless a section states otherwise (for example [`setConsentRequired()`](#setconsentrequired) before `init`).
</Note>

### `init()`

Initializes the OneSignal SDK. This should be called in the `<head>` tag once on each page of your site. The `ONESIGNAL_APP_ID` can be found in [Keys & IDs](./keys-and-ids).

<Note>
  If you want to delay initialization of the OneSignal SDK, we recommend using our [Privacy methods](#privacy).
</Note>

<CodeGroup>
  ```javascript JavaScript theme={null}
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "ONESIGNAL_APP_ID",
    });
  });
  ```
</CodeGroup>

<Warning>
  Init options only work with [Custom Code Setup](./web-push-custom-code-setup). Otherwise, these are configured in the OneSignal dashboard.
</Warning>

|             Parameter            |   Type  | Description                                                                                                                                                   |
| :------------------------------: | :-----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|              `appId`             |  String | **Required:** Your OneSignal App ID found in [Keys & IDs](./keys-and-ids).                                                                                    |
|   `requiresUserPrivacyConsent`   | Boolean | Delays SDK initialization until the user provides privacy consent. Must call [`setConsentGiven()`](#setconsentgiven) to complete setup.                       |
|          `safari_web_id`         |  String | The Safari Web ID for your uploaded Safari `.p12` certificate. [Web Quickstart](./web-push-setup).                                                            |
|          `promptOptions`         |  Object | Customize the permission prompts. [Details below](#promptoptions-parameters).                                                                                 |
|          `notifyButton`          |  Object | Enable and configure the Subscription Bell. [Details below](#notifybutton-parameters).                                                                        |
|       `welcomeNotification`      |  Object | Customize or disable the welcome notification. [Details below](#welcomenotification-parameters).                                                              |
|       `persistNotification`      | Boolean | Chrome (desktop only) - `true`: notification persists until clicked, `false`: disappears after a short time. Firefox/Safari ignore this setting.              |
|            `webhooks`            |  Object | Configure event callbacks. [See Webhooks](./webhooks).                                                                                                        |
|         `autoResubscribe`        | Boolean | **Recommended:** Auto-resubscribes users who clear browser cache or migrate to OneSignal. Overrides dashboard setting if used in code.                        |
|  `notificationClickHandlerMatch` |  String | `"exact"` (default): focuses tab with an exact URL match. `"origin"`: focuses any tab with the same domain.                                                   |
| `notificationClickHandlerAction` |  String | `"navigate"` (default): navigates to `launchURL`. `"focus"`: focuses existing tab (only used with `"origin"` match).                                          |
|       `serviceWorkerParam`       |  Object | Set the `scope` of the service worker. Must be different from other service worker's scope if applicable. Example:<br />`{ scope: "/myPath/myCustomScope/" }` |
|        `serviceWorkerPath`       |  String | Set the location of the OneSignal service worker file. Example:<br />`"myPath/OneSignalSDKWorker.js"`                                                         |

***

#### `promptOptions` parameters

Use `promptOptions` to localize or customize the user permission prompts. All fields are optional.

Structure: `promptOptions.slidedown.prompts` is an **array**; each element is one prompt configuration. The **`type`**, **`autoPrompt`**, **`delay`**, **`text`**, and **`categories`** fields belong on **each object inside `prompts`**, not as top-level keys next to `appId` on `init`.

|   Parameter  |       Type       | Description                                                                                                                                                                                                                                                                                                                                     |
| :----------: | :--------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  `slidedown` |      Object      | Wrapper for slidedown configuration. Contains `prompts`.                                                                                                                                                                                                                                                                                        |
|   `prompts`  | Array of Objects | Array of prompt configs. Example:<br />`promptOptions: { slidedown: { prompts: [{...}, {...}] } }`                                                                                                                                                                                                                                              |
|    `type`    |      String      | **Per `prompts[]` entry.** Prompt types:<br /><ul><li>`push` – Slide Prompt (no categories)</li><li>`category` – Slide Prompt with up to 10 categories</li><li>`email` – Collect email only</li><li>`sms` – Collect phone number only</li><li>`smsAndEmail` – Collect both</li></ul>See [Web Permission Prompts](./permission-requests).        |
| `autoPrompt` |      Boolean     | **Per `prompts[]` entry.** <ul><li>`true`: show based on `delay`.</li><li>`false`: prompt only shown manually via Slidedown API.</li></ul>                                                                                                                                                                                                      |
|    `delay`   |      Object      | **Per `prompts[]` entry.** When auto-prompt runs:<br />`{ pageViews: 3, timeDelay: 20 }` = after 3rd pageview and 20s wait.                                                                                                                                                                                                                     |
|    `text`    |      Object      | **Per `prompts[]` entry.** Custom text options:<br /><ul><li>`actionMessage` (max 90 chars)</li><li>`acceptButton` (max 15)</li><li>`cancelButton` (max 15)</li><li>`emailLabel`, `smsLabel`, `confirmMessage`</li><li>`updateMessage`, `positiveUpdateButton`, `negativeUpdateButton` (used for updating categories or contact info)</li></ul> |
| `categories` | Array of Objects | **Per `prompts[]` entry**, for `type: category`. Each object includes:<br />`tag`: internal key<br />`label`: user-visible name<br />Example: `[ {tag: "local_news", label: "Local News"} ]`. See [Tags](./add-user-data-tags).                                                                                                                 |

***

#### `notifyButton` parameters

Configure the Subscription Bell (notify button) shown on the page.

|      Parameter     |   Type   | Description                                                                                                   |
| :----------------: | :------: | ------------------------------------------------------------------------------------------------------------- |
|      `enable`      |  Boolean | Enables the Subscription Bell. Disabled by default.                                                           |
| `displayPredicate` | Function | Custom function (or Promise) that returns `true` or `false` to show/hide the Bell. Evaluated once when shown. |
|       `size`       |  String  | `'small'`, `'medium'`, or `'large'`. Shrinks to `'small'` after subscription.                                 |
|     `position`     |  String  | `'bottom-left'` or `'bottom-right'`.                                                                          |
|      `offset`      |  Object  | CSS pixel offsets: `{ bottom: '50px', left: '10px' }`                                                         |
|     `prenotify`    |  Boolean | If `true`, shows a "1 unread" icon and custom hover text.                                                     |
|    `showCredit`    |  Boolean | Set to `false` to hide "Powered by OneSignal" in the popup.                                                   |
|       `text`       |  Object  | Custom text for the bell UI.                                                                                  |

***

#### `welcomeNotification` parameters

Customize the welcome notification sent after first-time subscription.

| Parameter |   Type  | Description                                                                                |
| :-------: | :-----: | ------------------------------------------------------------------------------------------ |
| `disable` | Boolean | Disable welcome notification.                                                              |
| `message` |  String | **Required:** Notification message. Defaults to `'Thanks for subscribing!'` if blank.      |
|  `title`  |  String | Notification title. Defaults to site title. Use `' '` (space) to remove (not recommended). |
|   `url`   |   URL   | Optional URL to open when the user clicks the notification. Typically not needed.          |

***

**Example**:

<CodeGroup>
  ```javascript Example init for Custom Code Setup theme={null}
  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_APP_ID",
      safari_web_id: "YOUR_SAFARI_WEB_ID",
      notifyButton: {
        enable: true,
      },
      promptOptions: {
        slidedown: {
          prompts: [{
              type: "smsAndEmail",
              autoPrompt: false,
              text: {
                emailLabel: "Insert Email Address",
                smsLabel: "Insert Phone Number",
                acceptButton: "Submit",
                cancelButton: "No Thanks",
                actionMessage: "Receive the latest news, updates and offers as they happen.",
                updateMessage: "Update your push notification subscription preferences.",
                confirmMessage: "Thank You!",
                positiveUpdateButton: "Save Preferences",
                negativeUpdateButton: "Cancel",
              },
              delay: {
                pageViews: 1,
                timeDelay: 20
              },
            },
            {
              type: "category",
              autoPrompt: true,
              text: {
                actionMessage: "We'd like to show you notifications for the latest news and updates.",
                acceptButton: "Allow",
                cancelButton: "Cancel",

                /* CATEGORY SLIDEDOWN SPECIFIC TEXT */
                negativeUpdateButton: "Cancel",
                positiveUpdateButton: "Save Preferences",
                updateMessage: "Update your push notification subscription preferences.",
              },
              delay: {
                pageViews: 3,
                timeDelay: 20
              },
              categories: [{
                  tag: "politics",
                  label: "Politics"
                },
                {
                  tag: "local_news",
                  label: "Local News"
                },
                {
                  tag: "world_news",
                  label: "World News",
                },
                {
                  tag: "culture",
                  label: "Culture"
                },
              ]
            }
          ]
        }
      }
    });
  });
  </script>
  ```
</CodeGroup>

### `setLogLevel()`

Set the logging to print additional logs to the console. See [Debugging with Browser DevTools](./troubleshooting-web-push#debugging-using-browser-developer-tools) for more details. Run from a deferred callback after `init` (same **`OneSignal`** instance as elsewhere).

```javascript JavaScript theme={null}
  OneSignal.Debug.setLogLevel("trace");
```

**Log levels**:

* `'trace'`
* `'debug'`
* `'info'`
* `'warn'`
* `'error'`

***

## User identity & properties

When users subscribe to push notifications on your website, OneSignal automatically creates a OneSignal ID (user-level ID) and a Subscription ID (device-level ID). You can associate multiple Subscriptions (e.g., devices, emails, phone numbers) with a single user by calling `login()` with your unique user identifier.

<Note>
  See [Users](./users) and [Subscriptions](./subscriptions) for more details.
</Note>

### `login(external_id)`

Sets the current user context to the provided `external_id`. This links the current device (web push Subscription) to a known user and unifies all future data under a single `onesignal_id`. Use this method only for **identified users** (for example, after login or account restore). For anonymous users, do not call `login`. Instead, track them using their automatically assigned `onesignal_id` (see [OneSignal.User.onesignalId](#onesignal-user-onesignalid)).

**What happens when you call `login(external_id)`**

The SDK behaves differently depending on whether the `external_id` already exists within the OneSignal app.

**If the `external_id` already exists:**

* The SDK switches to that existing user.
  * You may see a `409 Conflict` in the browser network log or console. It means the External ID already exists in the app; it is expected in this path and is not usually a promise rejection you must handle.
* The current `onesignal_id` is discarded and the existing `onesignal_id` for that user is loaded.
* The current device (web push Subscription) is linked to the existing user.
* Anonymous data collected before login is not merged and is discarded. This includes tags, session data, email/SMS Subscriptions, and other local user properties.

**If the `external_id` does not exist:**

* A new user is created using the current `onesignal_id`.
* All data collected while the user was anonymous is retained.
* The device (web push Subscription) becomes linked to this new user.

**Retry behavior:**

* The SDK automatically retries the login request on network failures or server errors.
* You do not need to implement your own retry logic.

**Best practices:**

* Call `login(external_id)` **every page load** once you know the user's ID (for example, after sign-in or session restore).
* Call it again whenever the signed-in user changes (account switch).
* Do not call `login` before you have a stable, known user identifier.

```javascript JavaScript theme={null}
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.login("external_id");
});
```

### `logout()`

Unlinks the current user from the web push Subscription.

* Removes the `external_id` from the current web push Subscription. Does not remove the `external_id` from other Subscriptions.
* Resets the `onesignal_id` to a new anonymous user.
* Any new data (e.g tags, Subscriptions, session data, etc.) will now be set on the new anonymous user until they are identified with the `login` method.

<Note>Use this when a user signs out of your site and you do not want to send targeted transactional messages to the browser anymore.</Note>

```javascript JavaScript theme={null}
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.logout();
});
```

### `OneSignal.User.onesignalId`

Retrieves the current user's `onesignal_id` stored locally on the browser. This value represents the active user context (OneSignal's User ID) and can change over time — for example, when you call `login(external_id)` or when the SDK initializes. If called too early, this method may return `null`.

This value is not the Subscription ID which is used to identify the browser aka web push Subscription (see [User.PushSubscription.id](#user-pushsubscription-id)).

**When `onesignal_id` is available:**

* After the OneSignal SDK finishes initializing
* After a user is identified with `login(external_id)`
* After switching users or restoring a session

If you need to reliably react to changes or get this ID, use [User State `addEventListener('change', …)`](#addeventlistener-user-state) instead of polling.

**Common use cases:**
In most cases, you will want to use your own External ID set via the `login` method. However, there are some cases where you may want to use the `onesignal_id` directly.

* Tracking anonymous users before an External ID is set
* Storing the OneSignal ID in your backend for support or debugging
* Correlating OneSignal users with internal logs
* Displaying the ID for troubleshooting or QA

<Warning> Do not persist the OneSignal ID as a permanent user identifier. It can change when users log in, log out, or switch accounts. </Warning>

```javascript JavaScript theme={null}
const onesignalId = OneSignal.User.onesignalId;
```

### `OneSignal.User.externalId`

Retrieve the current user's External ID saved locally on the browser. May be `null` if not set via the `login` method or called before user state is initialized. Instead, use [User State `addEventListener('change', …)`](#addeventlistener-user-state) to listen for user state changes.

```javascript JavaScript theme={null}
  const externalId = OneSignal.User.externalId;
```

### `addEventListener()` *User State*

Listen for changes in the user context (e.g., login, logout, ID assignment).

```javascript JavaScript theme={null}
  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.addEventListener('change', function (event) {
      console.log('change', { event });
    });
  });
```

### `addAlias()`, `addAliases()`, `removeAlias()`, `removeAliases()`

Aliases are alternative identifiers (like usernames or CRM IDs).

* Set `external_id` with `login()` before adding aliases. Aliases added to subscriptions without `external_id` will not sync across multiple subscriptions.
* See [Aliases](./aliases) for details.

```javascript JavaScript theme={null}
  // Add a single alias
  OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

  // Add multiple aliases
  OneSignal.User.addAliases({
    ALIAS_LABEL_01: "ALIAS_ID_01",
    ALIAS_LABEL_02: "ALIAS_ID_02",
    ALIAS_LABEL_03: "ALIAS_ID_03",
  });

  // Remove a single alias
  OneSignal.User.removeAlias("ALIAS_LABEL");

  // Remove multiple aliases
  OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02", "ALIAS_LABEL_03"]);
```

### `getLanguage()`, `setLanguage()`

Get and/or override the auto-detected language of the user. See [Multi-language messaging](./multi-language-messaging) for a list of available language codes.

```javascript JavaScript theme={null}
  // Get the language of the currently logged-in user
  OneSignal.User.getLanguage();

  // Set the language of the currently logged-in user
  OneSignal.User.setLanguage("en");
```

***

## Custom events

[Trigger Journeys](./journeys-settings#custom-events) and [Wait Until step activation](./journeys-actions#wait-until) via a [custom event](./custom-events).

<Note>
  Custom events require Web SDK `160500`+.

  A user should be logged in for custom events to be tracked.

  Call custom event APIs on the **`OneSignal`** instance passed into `OneSignalDeferred.push` (see **Setup & debugging** at the top of this page), not on `window.OneSignal` — the page SDK is initialized through the deferred queue, and that callback is the supported way to access `OneSignal.User`.
</Note>

Track and send a custom event performed by the current user.

* `name` - **Required.** The name of the event as a string.
* `properties` - **Optional.** Key-value pairs to add to the event. The properties dictionary or map must be serializable into a valid JSON Object. Supports nested values.

The SDK automatically includes app-specific data into the properties payload under the reserved key `os_sdk` that will be available to consume. For example, to target events by subscription type, you would access `os_sdk.type`.

```json json theme={null}
{ 
  "os_sdk": {
    "device_os": "138",
    "type": "ChromePush",
    "device_model": "MacIntel",
    "sdk": "160500"
  }
}
```

### `trackEvent()`

Call after [`init()`](#init) completes. This example uses one deferred callback so `init` always runs before `trackEvent`:

```javascript JavaScript theme={null}
OneSignalDeferred.push(async function (OneSignal) {
  await OneSignal.init({ appId: "ONESIGNAL_APP_ID" });

  const properties = {
    promo_code: "NEW50",
    membership_details: {
      vip: true,
      products_viewed_count: 15,
    },
  };
  OneSignal.User.trackEvent("started_free_trial", properties);

  // Event name only (no properties)
  OneSignal.User.trackEvent("my_event_name");
});
```

<Note>
  In production, add `trackEvent` to the deferred callback where you already `await OneSignal.init(...)`. Do not register a second `init` unless you intend to.
</Note>

***

## Tags

Tags are custom `key : value` pairs of string data you set on users based on events or user properties. See [Tags](./add-user-data-tags) for more details.

### `addTag()`, `addTags()`

Set a single or multiple tags on the current user.

* Values will be replaced if the key already exists.
* Exceeding your plan's tag limit will cause the operations to fail silently.

```javascript JavaScript theme={null}
  // Add a single tag
  OneSignal.User.addTag('tag_key', 'tag_value');

  // Add multiple tags
  OneSignal.User.addTags({
   KEY_01: "VALUE_01",
   KEY_02: "VALUE_02",
   KEY_03: "VALUE_03"
  });
```

### `removeTag()`, `removeTags()`

Delete a single or multiple tags from the current user.

```javascript JavaScript theme={null}
  // Delete a single tag
  OneSignal.User.removeTag("KEY");

  OneSignal.User.removeTags(['KEY_01', 'KEY_02', 'KEY_03']);
```

### `getTags()`

Returns the local copy of the user's tags. Tags are updated from the server during `login()` or new app sessions.

```javascript JavaScript theme={null}
  const tags = OneSignal.User.getTags()
```

***

## Privacy

### `setConsentRequired()`

Enforces user consent before data collection begins. Must be called **before** [`init()`](#init) runs (for example at the start of the first `OneSignalDeferred` callback, before `await OneSignal.init(...)`).

This method is the same as adding `requiresUserPrivacyConsent: true` to the `init` options.

```javascript JavaScript theme={null}
  OneSignal.setConsentRequired(true);
```

### `setConsentGiven()`

Grants or revokes user consent for data collection. Without consent, no data is sent to OneSignal and no subscription is created.

* If [`setConsentRequired()`](#setconsentrequired) or `requiresUserPrivacyConsent` is set to `true`, our SDK will not be fully enabled until `setConsentGiven` is called with `true`.
* If `setConsentGiven` is set to `true` and a Subscription is created, then later it is set to `false`, that Subscription will no longer receive updates. The current data for that Subscription remains unchanged until `setConsentGiven` is set to `true` again.
* If you want to delete the User and/or Subscription data, use our [Delete user](/reference/delete-user) or [Delete subscription](/reference/delete-subscription) APIs.

```javascript JavaScript theme={null}
  OneSignal.setConsentGiven(true);
```

***

## Subscriptions

A Subscription represents a single messaging channel instance (for example, a browser) and has a unique Subscription ID (OneSignal's device-level ID). A user can have multiple Subscriptions across devices and platforms.

See [Subscriptions](./subscriptions) for more details.

### `User.PushSubscription.id`

Retrieves the web push Subscription ID for the current browser, stored locally by the SDK.

This ID uniquely identifies this specific browser’s push channel, not the user. It is commonly used when associating devices or browsers with your backend or debugging delivery issues.

If called before the Subscription is created or restored, this value may be `null`.

<Note> To reliably detect when the web push Subscription ID becomes available or changes, use the [push Subscription listener](#addeventlistener-push-subscription-changes). </Note>

```javascript JavaScript theme={null}
  const subscription_id = OneSignal.User.PushSubscription.id;
```

### `User.PushSubscription.token`

Returns the current push subscription token. May return `null` if called too early. It's recommended to get this data within the [subscription observer](#addeventlistener-push-subscription-changes) to react to changes.

```javascript JavaScript theme={null}
  OneSignal.User.PushSubscription.token;
```

### `addEventListener()` *Push Subscription Changes*

Use this method to respond to push subscription changes like:

* The device receives a new push token from Google (FCM) or Apple (APNs)
* OneSignal assigns a subscription ID
* The `optedIn` value changes (e.g. called `optIn()` or `optOut()`)
* The user toggles push permission in browser or OS settings, then returns to your site

When this happens, the SDK runs your **`change`** listener with a state object that includes `previous` and `current` so you can detect what changed.

<Note>
  When [`autoResubscribe`](#init) is `true`, returning visitors may fire the `change` event with `optedIn: true` on both `previous` and `current` because the browser permission did not change — only the push token was re-registered (for example, after clearing site data or migrating). For analytics or server-side tracking that should reflect **new** or **re-subscriptions**, `event.current.token && !event.previous.token` is usually more reliable than comparing `optedIn` alone.
</Note>

To stop listening for updates, call `removeEventListener()` with the same handler reference you passed to `addEventListener()`.

```javascript JavaScript theme={null}
  function pushSubscriptionChangeListener(event) {
    console.log("event.previous.id", event.previous.id);
    console.log("event.current.id", event.current.id);
    console.log("event.previous.token", event.previous.token);
    console.log("event.current.token", event.current.token);
    console.log("event.previous.optedIn", event.previous.optedIn);
    console.log("event.current.optedIn", event.current.optedIn);
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });
```

**External analytics (for example Google Analytics via `dataLayer`):** fire a custom event when a push token appears and there was no token before, so re-registration with unchanged `optedIn` still counts correctly. The subscription ID may arrive in the same callback or a later `change` event depending on timing:

```javascript JavaScript theme={null}
  function pushSubscriptionChangeListener(event) {
    if (!event.current.token || event.previous.token) {
      return;
    }
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: "onesignal_push_subscribed",
      onesignal_subscription_id: event.current.id,
    });
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });
```

<Warning>
  In incognito or private browsing, the Slidedown can still appear when [`autoPrompt`](#promptoptions-parameters) is `true`, but push subscriptions typically do not persist after the session ends. [`isPushSupported()`](#ispushsupported) does not detect private browsing; it only indicates whether web push is available in principle. Before programmatically triggering the prompt (for example [`promptPush()`](#promptpush)), still call `isPushSupported()` so you avoid prompting on browsers that cannot use web push.
</Warning>

### `optOut()`, `optIn()`, `optedIn`

Control the subscription status (`subscribed` or `unsubscribed`) of the current push Subscription. Use these methods to control the push subscription status on your site. Common use cases: 1) Prevent push from being sent to users that log out. 2) Implement a notification preference center within your site.

* `optOut()`: Sets the current push subscription status to unsubscribed (even if the user has a valid push token).
* `optIn()`: Does one of the following:
  1. If the Subscription has a valid push token, it sets the current push subscription status to `subscribed`.
  2. If the Subscription does not have a valid push token, it attempts to display the push permission prompt.
* `optedIn`: Returns `true` if the current push subscription status is subscribed, otherwise `false`. If the push token is valid but `optOut()` was called, this will return `false`.

```javascript JavaScript theme={null}
  OneSignal.User.PushSubscription.optOut();

  OneSignal.User.PushSubscription.optIn();

  var optedIn = OneSignal.User.PushSubscription.optedIn;
```

### `addEmail()`, `removeEmail()`

Adds or removes an email Subscription (email address) for the current user.

These methods are compatible with [Identity Verification](./identity-verification).

**When you call `addEmail(email)`:**

* The email address becomes an email Subscription for the current user.
* The email may be created or reassigned.
* The same email address cannot exist multiple times in the same OneSignal app. If you see duplicate email addresses, check your REST API requests and contact support if needed.

The SDK returns the following HTTP status codes:

| Status code      | Meaning                                                                              |
| ---------------- | ------------------------------------------------------------------------------------ |
| **200 OK**       | The email Subscription already belongs to the current user. No changes were made.    |
| **201 Created**  | A new email Subscription was created and linked to the user.                         |
| **202 Accepted** | The email Subscription already existed in the app and was moved to the current user. |

**When you call `removeEmail(email)`:**

* The email Subscription is removed from the current user.
* The current External ID is removed from the email Subscription.
* A new OneSignal ID is assigned to the email Subscription.
* Other Subscriptions (push, SMS, other emails) remain unaffected.

**Best practices:**

* Call `login()` first, then call `addEmail()`. Otherwise, the email may be attached to an anonymous user.
* Use a stable, verified email address.
* Follow [Email reputation best practices](./email-reputation-best-practices).

```javascript JavaScript theme={null}
  OneSignal.User.addEmail("example@email.com");

  OneSignal.User.removeEmail("example@email.com");
```

### `addSms()`, `removeSms()`

Adds or removes an SMS Subscription (phone number) for the current user. Phone numbers must be provided in [E.164 format](https://www.twilio.com/docs/glossary/what-e164) (for example, `+15551234567`).

These methods are compatible with [Identity Verification](./identity-verification).

**When you call `addSms(phoneNumber)`:**

* The phone number becomes an SMS Subscription for the current user.
* The number may be created or reassigned.
* The same phone number cannot exist multiple times in the same OneSignal app. If you see duplicate phone numbers, check your REST API requests and contact support if needed.

The SDK returns the following HTTP status codes:

| Status code      | Meaning                                                                            |
| ---------------- | ---------------------------------------------------------------------------------- |
| **200 OK**       | The SMS Subscription already belongs to the current user. No changes were made.    |
| **201 Created**  | A new SMS Subscription was created and linked to the user.                         |
| **202 Accepted** | The SMS Subscription already existed in the app and was moved to the current user. |

**When you call `removeSms(phoneNumber)`:**

* The SMS Subscription is removed from the current user.
* The current External ID is removed from the SMS Subscription.
* A new OneSignal ID is assigned to the SMS Subscription.
* Other Subscriptions (push, email, other SMS) remain unaffected.

**Best practices:**

* Call `login()` first, then call `addSms()`. Otherwise, the SMS Subscription may be attached to an anonymous user.
* Always validate and normalize phone numbers to [E.164 format](https://www.twilio.com/docs/glossary/what-e164) before sending.
* Follow [SMS Registration Requirements](./sms-registration-requirements).

```javascript JavaScript theme={null}
  OneSignal.User.addSms("+15558675309");

  OneSignal.User.removeSms("+15558675309");
```

***

## Slidedown prompts

Display the various slidedown prompts on your sites. See [Web permission prompts](./permission-requests) for more details.

* If dismissed, future calls will be ignored for at least three days. Further declines will lengthen the time required to elapse before prompting the user again.
* To override back-off behavior, pass `{force: true}` to the method. However, to provide a good user experience, bind the action to a UI-initiated event like a button click.

<Warning>
  This does not replace the Native Browser Prompt required for subscription. You must obtain permissions using the native browser prompt.
</Warning>

### `promptPush()`

Displays the regular slidedown prompt for push notifications.

* If using categories, call [`promptPushCategories()`](#promptpushcategories) instead.
* Subject to backoff logic set by OneSignal. See [Web permission prompts](./permission-requests#auto-prompt-%26-display-settings) for more details.

```javascript JavaScript theme={null}
  OneSignal.Slidedown.promptPush();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPush({force: true});
```

### `promptPushCategories()`

Displays the category slidedown prompt, allowing users to update their tags. Also triggers the native notification permission prompt if the user has not already granted permission.

* If not using categories, call [`promptPush()`](#promptpush) instead.
* Subject to backoff logic set by OneSignal. See [Web permission prompts](./permission-requests#auto-prompt-%26-display-settings) for more details.

```javascript JavaScript theme={null}
  OneSignal.Slidedown.promptPushCategories();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPushCategories({force: true});
```

### `promptSms()`

Displays the SMS subscription prompt.

* Subject to backoff logic set by OneSignal. See [Web permission prompts](./permission-requests#auto-prompt-%26-display-settings) for more details.

```javascript JavaScript theme={null}
  OneSignal.Slidedown.promptSms();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSms({force: true});
```

### `promptEmail()`

Displays the email subscription prompt.

* Subject to backoff logic set by OneSignal. See [Web permission prompts](./permission-requests#auto-prompt-%26-display-settings) for more details.

```javascript JavaScript theme={null}
  OneSignal.Slidedown.promptEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptEmail({force: true});
```

### `promptSmsAndEmail()`

Displays the SMS and email subscription prompts simultaneously.

* Subject to backoff logic set by OneSignal. See [Web permission prompts](./permission-requests#auto-prompt-%26-display-settings) for more details.

```javascript JavaScript theme={null}
  OneSignal.Slidedown.promptSmsAndEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSmsAndEmail({force: true});
```

### `addEventListener()` *Slidedown*

Add a callback to detect the Slidedown prompt shown event.

```javascript JavaScript theme={null}
  OneSignalDeferred.push(function(OneSignal) {

    OneSignal.Slidedown.addEventListener('slidedownShown', function (event) {
      console.log('slidedownShown', { event });
    });

  });
```

***

## Push notifications

### `requestPermission()`

Requests push notifications permission via the native browser prompt. Subject to backoff logic set by the browser. See [Web permission prompts](./permission-requests#native-permission-prompt) for more details.

```javascript JavaScript theme={null}
  OneSignal.Notifications.requestPermission();
```

### `isPushSupported()`

Returns `true` if the current browser supports web push.

```javascript JavaScript theme={null}
  const isSupported = OneSignal.Notifications.isPushSupported();
```

### `OneSignal.Notifications.permission`

Returns a boolean indicating the site's current permission to display notifications.

* `true`: The user has granted permission to display notifications.
* `false`: The user has either denied or not yet granted permission to display notifications.

This value reflects **browser notification permission** only. It does not reflect OneSignal `optOut`, subscription ID, or push token. For those, use [`User.PushSubscription`](#user-pushsubscription-id) (and related methods below).

To listen for permission changes, use the [`permissionChange`](#permissionchange) event.

```javascript JavaScript theme={null}
  let permission = OneSignal.Notifications.permission;
```

### `addEventListener()` *Notifications*

You can hook into the notification life-cycle with `addEventListener`. Replace the first argument with an event name such as `permissionChange`, `click`, or `dismiss` (see subsections below). You can register multiple handlers per event.

To stop listening, call `removeEventListener` with the **same** event name and handler reference.

```javascript JavaScript theme={null}
  function onClick(event) {
    console.log("click", event);
  }

  OneSignal.Notifications.addEventListener("click", onClick);
  OneSignal.Notifications.removeEventListener("click", onClick);
```

#### `permissionChange`

This event occurs when the user clicks Allow or Block or dismisses the browser's native permission request.

```javascript JavaScript theme={null}
  function permissionChangeListener(permission) {
    if (permission) {
      console.log(`permission accepted!`);
    }
  }

  OneSignal.Notifications.addEventListener("permissionChange", permissionChangeListener);
```

#### `permissionPromptDisplay`

This event occurs when the browser's native permission request has just been shown.

```javascript JavaScript theme={null}
  function promptListener(event) {
    console.log("permission prompt displayed", event);
  }

  OneSignal.Notifications.addEventListener("permissionPromptDisplay", promptListener);
```

#### `click`

This event will fire when the notification's body/title or action buttons are clicked.

```javascript JavaScript theme={null}
  function clickEventListener(event) {
    console.log(`click event: ${event}`);
  }

  OneSignal.Notifications.addEventListener("click", clickEventListener);
```

#### `foregroundWillDisplay`

This event occurs before a notification is displayed. This event is fired on your page. If multiple browser tabs are open on your site, this event will be fired on *all* pages on which OneSignal is active.

```javascript JavaScript theme={null}
  function foregroundWillDisplayListener(event) {
    console.log("notification will display", event);
  }

  OneSignal.Notifications.addEventListener("foregroundWillDisplay", foregroundWillDisplayListener);
```

#### `dismiss`

This event occurs when:

* A user purposely dismisses the notification without clicking the notification body or action buttons
* On Chrome on Android, a user dismisses all web push notifications (this event will be fired for each web push notification we show)
* A notification expires on its own and disappears

<Info>
  This event *does not occur* if a user clicks on the notification body or one of the action buttons. That is considered a notification `click` event.
</Info>

```javascript JavaScript theme={null}
  function notificationDismissedListener(event) {
    console.log(`dismiss event: ${event}`);
  }

  OneSignal.Notifications.addEventListener("dismiss", notificationDismissedListener);
```

### `setDefaultUrl()`

Sets the default URL for notifications.

If you haven't set a default URL, your notification will open to the root of your site by default.

```javascript JavaScript theme={null}
  OneSignal.Notifications.setDefaultUrl("https://onesignal.com");
```

Provide a valid URL to open when the user clicks a notification that does not specify its own URL. If the notification payload includes a URL, it overrides this default.

Safari Web Push does not use `setDefaultUrl()` the same way; launch and icon behavior follow your Safari / Apple configuration (for example the Site URL in your OneSignal Safari settings). See [Web push setup](./web-push-setup) for Safari-specific steps.

### `setDefaultTitle()`

Sets the default title to display on notifications.

```javascript JavaScript theme={null}
  OneSignal.Notifications.setDefaultTitle("Powered by OneSignal!");
```

If a notification is created with a title, the specified title always overrides this default title.

A notification's title defaults to the title of the page the user last visited. If your page titles vary between pages, this inconsistency can be undesirable. Call this to standardize page titles across notifications, as long as a notification title isn't specified.

***

## Outcomes

Outcome methods are on **`OneSignal.Session`**. Use the same deferred **`OneSignal`** instance as elsewhere after `init`.

### `sendOutcome()`

Triggers an outcome which can be viewed in the OneSignal dashboard. Accepts an outcome name (`string`, required) and a value (`number`, optional). Each time `sendOutcome` method is invoked with the same outcome name passed, the outcome count will increase, and the outcome value will be increased by the amount passed in (if included). See [Custom Outcomes](./custom-outcomes) for more details.

```javascript JavaScript theme={null}
  OneSignal.Session.sendOutcome('outcome name', 19.84);
```

### `sendUniqueOutcome()`

Triggers an outcome which can be viewed in the OneSignal dashboard. Accepts only the outcome name (`string`, required). `sendUniqueOutcome` will increase the count for that outcome only once per user. See [Custom Outcomes](./custom-outcomes) for more details.

```javascript JavaScript theme={null}
  OneSignal.Session.sendUniqueOutcome('outcome name');
```

***


# Sending messages with the OneSignal API
Source: https://documentation.onesignal.com/reference/create-message

Send push notifications, emails, SMS, and Live Activities with the OneSignal API. Covers audience targeting, message composition, scheduling, and response handling.

## Overview

This guide walks you through sending messages with the OneSignal API — from choosing a target audience to composing content, scheduling delivery, and validating responses. Each section covers channel-specific options and performance guidance.

### Prerequisites

1. Complete [Channel Setup](/docs/en/channel-setup) for the channels you plan to use: push, email, SMS, Live Activities.
2. Start accumulating [Subscriptions](/docs/en/subscriptions) for your users.
3. Have your REST API Key and App ID ready. See [Keys and IDs](/docs/en/keys-and-ids).

***

## Choose your target audience

You can target users with **one of the following methods per request**:

* **Aliases**: Specific users via unique IDs, emails, or phone numbers.
* **Segments**: Groups based on predefined behaviors or attributes.
* **Filters**: Custom rules using tags, location, activity, and more.

<Warning>
  Only one targeting method is allowed per message. For example, you cannot mix aliases and filters.
</Warning>

You can also target specific platforms (for example, `isAndroid`, `isIos`, `isAnyWeb`) when sending push notifications. By default, all push platforms are enabled.

### Aliases, emails, phone numbers

Target specific users or lists of users (up to 20,000 entries per request). This method is best for [Transactional Messages](/docs/en/transactional-messages).

<Accordion title="Aliases, emails, and phone numbers targeting parameters">
  <ParamField type="object">
    Target up to 20,000 users by their `external_id`, `onesignal_id`, or a custom alias. Combine with `target_channel` to select the delivery channel.

    ```json theme={null}
    {
      "include_aliases": {
        "external_id": [
          "user1",
          "user2",
          "user3"
        ]
      },
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="string">
    The targeted delivery channel. Required when using `include_aliases` or `included_segments` and sending SMS/RCS. Accepts `"push"`, `"email"`, or `"sms"`. The `"sms"` value covers both SMS and RCS — RCS messages are delivered through the SMS channel.

    ```json theme={null}
    {
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="array">
    Target users' specific [Subscriptions](/docs/en/subscriptions) by ID. Max 20,000 `subscription_id` per request.

    ```json theme={null}
    {
      "include_subscription_ids": [
        "1dd608f2-c6a1-11e3-851d-000c2940e62c"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send to specific email addresses (max 20,000 per request). Can only be used when sending [email](/reference/email). If the email address does not exist within the OneSignal App, a new email subscription is created.

    ```json theme={null}
    {
      "email_to": [
        "user1@example.com",
        "user2@example.com"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send SMS/MMS/RCS to phone numbers in [E.164 format](/docs/en/sms-setup#what-is-e164-format) (max 20,000 per request). Can only be used when sending [SMS/MMS/RCS](/reference/sms). If the phone number does not exist within the OneSignal App, a new SMS subscription is created.

    ```json theme={null}
    {
      "include_phone_numbers": [
        "+19999999999"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Segments

Target users in existing [segments](/docs/en/segmentation). Users in multiple segments only receive the message once.

<Accordion title="Segments targeting parameters">
  <ParamField type="array">
    Target predefined [segments](/docs/en/segmentation). Users who are in multiple segments only receive the message once. Combine with `excluded_segments` to exclude users from specific segments. When sending SMS/RCS, set `target_channel` to `"sms"` (or use the legacy `isSms=true` field).

    ```json theme={null}
    {
      "included_segments": [
        "Active Users",
        "Inactive Users"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Exclude users in these [segments](/docs/en/segmentation) even if they're in `included_segments`.

    ```json theme={null}
    {
      "included_segments": [
        "Subscribed Users"
      ],
      "excluded_segments": [
        "Inactive Users"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Filters

Build real-time audiences with `AND`/`OR` logic without creating segments first.

You can include up to **200 total entries per request**. This includes filter rows (for example, each `field`) and logical operators like `{"operator": "OR"}`.

<Accordion title="Filters targeting parameter details">
  <Info>
    **Performance guidance:**

    * **Fast:** Tag filters using `"="` or `"exists"`, and filters on `last_session`, `session_count`, or `country`.
    * **Slower:** Negation filters (`"!="`, `"not_exists"`) — especially with users who have many tags. Contact support to request indexing optimizations.
    * **Slow by default:** Numeric comparisons (`">"`, `"<"`) on tags or custom properties. Indexing may be available on request.
    * **Mixed performance:** Combining tag filters with other fields may increase computation time.
  </Info>

  <ParamField type="string">
    * Implicit `AND` logic between filters. Use `"operator": "OR"` to start a new branch.
    * `OR` filters are mutually exclusive. Recipients only need to satisfy one condition.
    * Allowed values: `"AND"`, `"OR"`.

    <CodeGroup>
      ```json AND example theme={null}
      // Users must satisfy both filters to be included.
      // Notice the AND operator is not required

      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      // The same example using the AND operator. This is not required.
      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "AND"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      ```

      ```json OR example theme={null}
      // Users can satisfy either filter to be included.

      "filters": [
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "tag", "key": "level", "relation": "=", "value": "20"}
      ]
      ```

      ```json Combinations theme={null}
      // In this example, users must either have:
      // The specified session_count AND tag requirement
      // Or it will be all records where last_session is satisfied
      {
        "name": "2 filters or 1",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"}
        ]
      }

      // Similar to the first example, this shows how to require a specific field
      // across other filters

      {
        "name": "3 filters, 1 required across all",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
        ]
      }

      // Example of 3 user groups with 2 requirements
      // (group_1 OR group_2 OR group_3) AND (requirement_1 OR requirement_2)

      {
        "name": "3 groups with 2 requirements",
        "filters": [
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"}
        ]
      }
      ```
    </CodeGroup>
  </ParamField>

  <ParamField type="object">
    ### `tag`

    Target based on custom user [Tags](/docs/en/add-user-data-tags).

    <Warning>
      Do not use tags for targeting individual users like a "user id".
      Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
    </Warning>

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
      * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
    * `key` = Tag key to compare.
    * `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

    ```json theme={null}
    "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "OR"},
      {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
    ]
    ```

    ### `country`

    Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "country", "relation": "=", "value": "US"},
        {"operator": "OR"},
        {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
      ]
      ```

    ### `last_session`

    Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "last_session", "relation": ">","hours_ago": "10"}
      ]
      ```

    ### `first_session`

    Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "first_session", "relation": "<","hours_ago": "24"}
      ]
      ```

    ### `session_count`

    Total number of sessions by the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="` or `"!="`
    * `value` = number of sessions. Example: `"1"`

      ```json theme={null}
      "filters": [
        {"field": "session_count", "relation": ">","value": "5"}
      ]
      ```

    ### `session_time`

    Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

    * `relation` = `">"` or `"<"`
    * `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

      ```json theme={null}
      "filters": [
        {"field": "session_time", "relation": ">","value": "86400"}
      ]
      ```

    ### `language`

    [User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = 2 character language code. Example: `"en"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "language", "relation": "=","value": "en"},
        {"operator": "OR"},
        {"field": "language", "relation": "in_array","value": "es,fr,de"}
      ]
      ```

    ### `app_version`

    App version set on the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = app version. Example: `"1.0.0"`
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "app_version", "relation": "=","value": "1.0.1"},
        {"operator": "OR"},
        {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
      ]
      ```

    ### `location`

    Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

    * `radius` = in meters
    * `lat` = latitude
    * `long` = longitude

      ```json theme={null}
      "filters": [
        {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
      ]
      ```
  </ParamField>
</Accordion>

***

## Craft your message

Each channel has its own set of fields. At a minimum, you need the following to send a displayable message:

* **Push and SMS** use `contents`
* **Email** uses `email_subject` and `email_body`
* Or reuse `template_id` if you created [templates](/docs/en/templates).

<CodeGroup>
  ```json Push and SMS theme={null}
  // Message request body
  {
    "contents": {
      "en": "Hello, world",
      "es": "Hola Mundo",
      "fr": "Bonjour le monde",
      "zh-Hans": "你好世界"
    }
  }
  ```

  ```json Email theme={null}
  // Message request body
  {
    "email_subject": "Hello, world",
    "email_body": "<html><body><h1>Hello, world</h1></body></html>"
  }
  ```
</CodeGroup>

For advanced customization—like adding images, buttons, sounds, or tracking—see the channel-specific options below.

### Push notification options

Below are the most common parameters for push notifications. For the full list of options, see the [Push notification reference](/reference/push-notification).

<Accordion title="Push notification options">
  #### Content and text

  * [`contents`](/reference/push-notification#body-contents) – Main message body.
  * [`headings`](/reference/push-notification#body-headings) – Title of the notification.
  * [`subtitle`](/reference/push-notification#body-subtitle) – Secondary line of text.
  * [`template_id`](/reference/push-notification#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Appearance

  * [`ios_attachments`](/reference/push-notification#body-ios-attachments) – Images/video/media.
  * [`big_picture`](/reference/push-notification#body-big-picture) – Large image (Android).
  * [`chrome_web_image`](/reference/push-notification#body-chrome-web-image) – Large image (Chrome).
  * [`small_icon`](/reference/push-notification#body-small-icon)
  * [`large_icon`](/reference/push-notification#body-large-icon)
  * [`buttons`](/reference/push-notification#body-buttons) – Action buttons.

  #### Delivery and priority

  * [`android_channel_id`](/reference/push-notification#body-android-channel-id)
  * [`priority`](/reference/push-notification#body-priority) – Delivery urgency.
  * [`ios_interruption_level`](/reference/push-notification#body-ios-interruption-level)
  * [`collapse_id`](/reference/push-notification#body-collapse-id) – Replaces older messages.

  #### Data and extras

  * [`data`](/reference/push-notification#body-data) – Custom key-value pairs sent to your app.
  * [`url`](/reference/push-notification#body-url) – Opens when notification is tapped.
</Accordion>

### Email options

<Accordion title="Email options">
  #### Content

  * [`email_subject`](/reference/email#body-email-subject)
  * [`email_body`](/reference/email#body-email-body)
  * [`email_preheader`](/reference/email#body-email-preheader)

  #### Appearance

  * [`template_id`](/reference/email#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Sender info

  * [`email_from_name`](/reference/email#body-email-from-name)
  * [`email_reply_to`](/reference/email#body-email-reply-to)
</Accordion>

### SMS/MMS options

<Accordion title="SMS/MMS options">
  #### Content

  * [`contents`](/reference/sms#body-contents)
  * [`template_id`](/reference/sms#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Media (MMS only)

  * [`sms_media_urls`](/reference/sms#body-sms-media-urls)

  #### Sender info

  * [`sms_from`](/reference/sms#body-sms-from)
</Accordion>

***

## Schedule and per-user delivery

By default, messages are sent immediately. You can schedule delivery in advance and optimize timing per user based on their local timezone or recent activity.

<Accordion title="Schedule delivery and per-user optimization parameters">
  <ParamField type="string">
    Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript's Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring).

    ```json theme={null}
    {
      "send_after": "2025-09-24T14:00:00-07:00"
    }
    ```
  </ParamField>

  <ParamField type="string">
    Controls how push and email messages are delivered on a per-user basis. Not available for SMS.

    * `"timezone"`: Sends at the same local time across time zones.
    * `"last-active"`: Delivers based on each user's most recent session.

    Not compatible with [push throttling](/docs/en/throttling). When `delayed_option` is set, you must also set `throttle_rate_per_minute` to `0`.

    ```json theme={null}
    {
      "delayed_option": "last-active",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>

  <ParamField type="string">
    Use with `delayed_option: "timezone"` to set a consistent daily delivery time. Accepted formats:

    * `"9:00AM"` (12-hour)
    * `"21:45"` (24-hour)
    * `"09:45:30"` (HH:mm:ss)

    Example — Send every day at 9 AM in each user's local time:

    ```json theme={null}
    {
      "delayed_option": "timezone",
      "delivery_time_of_day": "9:00AM",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>
</Accordion>

***

## Submit the request

This final example sends a localized push notification to all subscribed users:

```curl theme={null}
curl -X "POST" "https://api.onesignal.com/notifications" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Key YOUR_API_KEY' \
     -d $'{
      "target_channel": "push",
      "included_segments": [
        "Subscribed Users"
      ],
      "app_id": "YOUR_APP_ID",
      "contents": {
        "en": "Hello, world",
        "es": "Hola mundo",
        "fr": "Bonjour le monde",
        "zh-Hans": "你好世界"
      }
    }'
```

Once the request is sent, OneSignal forwards it to the appropriate downstream provider, which then delivers it to the recipient:

* **Push:** FCM, APNs, or HMS
* **Email:** your email service provider
* **SMS:** Twilio

### Handle the response

You receive a `200` response code if the request is valid and accepted.

* If an `id` is returned, the message was created successfully. Save this `id` for future tracking and reference of message stats via the [View message API](/reference/view-message).
* If no `id` is returned, the message was not created, likely because there are no valid [subscriptions](/docs/en/subscriptions) in the target audience.

**Response details by channel:**

* [Push](/reference/push-notification#response-id)
* [Email](/reference/email#response-id)
* [SMS](/reference/sms#response-id)

<Note>
  See our [REST API Overview](/reference/rest-api-overview#reliability-and-delivery) page for details on retries and [rate limits](/reference/rate-limits).
</Note>

***

## FAQ

### Can I combine `include_aliases`, `included_segments`, and `filters` in one request?

No. Each request must use exactly one targeting method. Mixing them returns a validation error. Choose aliases for transactional sends to specific users, segments for predefined audiences, or filters for ad-hoc audiences built with `AND`/`OR` logic.

### Does `target_channel: "sms"` cover RCS?

Yes. The `target_channel` enum accepts `"push"`, `"email"`, and `"sms"`. RCS messages are delivered through the SMS channel — there is no separate `"rcs"` value. OneSignal decides whether to send via RCS or SMS based on the recipient's device and your sender configuration.

### My request returned `200` but no `id`. What happened?

The request was valid but no message was created, typically because the target audience contains no valid subscriptions for the selected channel. Common causes include a segment that resolves to zero users, all targeted aliases being unsubscribed, or phone numbers that don't match an existing SMS subscription.

### Can I use `//` comments in the JSON request body?

No. The `//` comments in the examples on this page are illustrative only. Strict JSON does not support comments — strip them before sending to the API.

### How is the `Sent` count in reports related to the API response?

The dashboard `Sent` metric is a composite. To derive it from the [View message API](/reference/view-message), sum `successful + failed + errored`. See the [Metrics glossary](/docs/en/analytics-metrics-glossary) for the full mapping between dashboard, API, CSV, and Event Streams names.

***

## Next steps

Refer to the channel-specific APIs to customize delivery further:

* [Push notification](/reference/push-notification)
* [Email](/reference/email)
* [SMS](/reference/sms)
* [Live Activities](/reference/start-live-activity)
* [Server-Side SDKs](/docs/en/server-sdk-reference)


# Idempotent API requests
Source: https://documentation.onesignal.com/reference/idempotent-notification-requests

Prevent duplicate messages or custom events when retrying API requests.

## Overview

When you create messages or custom events via our REST API, network failures or timeouts can cause uncertainty about whether a request succeeded. **Idempotent requests** solve this problem by ensuring the same request is only processed once—even if it is sent multiple times.

This page explains how idempotency works in OneSignal, when to use it, and common pitfalls to avoid.

### When you should use idempotency

You should use idempotent requests any time you plan to retry API calls, especially when:

* You receive a timeout, 500-level error, or no response.
* Your infrastructure automatically retries failed requests.
* Delivering a duplicate message or custom event would be harmful.
* Missing a message or custom event would be harmful.

### The problem idempotency solves

Consider this common failure scenario:

1. You send a `notifications#create` or `custom_events#create` request.
2. OneSignal begins processing and sending the message or event.
3. A network error occurs before your client receives a response.

At this point, your system cannot know whether the request succeeded.

* If you retry and the request already succeeded, users may receive duplicates.
* If you do not retry and the request failed, users may miss important messages or events.

**Idempotency provides a safe retry mechanism.**

***

## How idempotency works

OneSignal supports idempotent operations for:

* [`notifications#create`](/reference/create-message)
* [`custom_events#create`](/reference/create-custom-events)

You provide a unique `idempotency_key` with each request.

### Request flow with idempotency

1. You send a request with an `idempotency_key`.
2. OneSignal processes the request and begins sending the message or creating the custom event.
3. A network error or timeout occurs.
4. You retry the request using the same `idempotency_key`.
5. OneSignal detects the duplicate and returns the result of the original request.
6. Only one notification or custom event is processed.

You can repeat this retry any number of times. As long as the `idempotency_key` remains the same, the operation will only be processed once.

***

## Idempotency key reference

<ParamField type="RFC 9562 UUID">
  A unique identifier used to prevent duplicate messages or custom events from repeat API calls. Keys must be unique [RFC 9562 UUID format](https://en.wikipedia.org/wiki/Universally_unique_identifier). Valid for 30 days.
</ParamField>

<Note>
  This `idempotency_key` property used to be called `external_id` but caused confusion with our [Users `external_id`](/docs/en/users) alias, so we have added this new property name to reduce confusion. Both will work in this case.
</Note>

***

## Important constraints and gotchas

<Warning> If you reuse the same `idempotency_key` for different messages or events, only the first request will be processed. </Warning>

Keep the following in mind:

* **Keys must be unique per logical operation**
  Generate a new UUID for every notification or custom event you intend to send.

* **Keys are retained for 30 days**
  After 30 days, OneSignal may delete the record. Reusing the same key after that window may result in a new message being sent.

* **Use a strong source of randomness**
  Predictable or reused UUIDs can cause unexpected deduplication.

* **Idempotency does not guarantee delivery**
  It only guarantees at-most-once processing. You should still monitor API responses and logs.

### Legacy behavior

The `idempotency_key` property was previously named `external_id`. This caused confusion with the Users `external_id` alias, so `idempotency_key` is now the recommended field name. Both names are currently supported.

### Best practices

* Always include `idempotency_key` when implementing retries.
* Store the `idempotency_key` alongside your request metadata for debugging.
* Retry only after honoring any `Retry-After` header returned by the API.
* Combine idempotency with proper timeout handling (for example, a 60-second HTTP timeout).

***


# Rate limits and error handling
Source: https://documentation.onesignal.com/reference/rate-limits

Understand OneSignal API and application rate limits, common errors, retry behavior, and how to safely recover from failures without sending duplicate messages or disabling your app.

OneSignal uses rate limits and error responses as safety mechanisms to protect your app from accidental overloads, duplicate sends, and retry storms.

There are three categories to understand:

* **API rate limits** return HTTP `429` errors when request volume is too high.
* **Network timeouts or temporary server failures** return `5xx` errors or no response at all.
* **Application message limits** may temporarily disable your app if too many messages are sent in a short period.

<Info>
  Most apps never hit these limits during normal usage. When they do occur, they are usually caused by retries, loops, or unexpected audience expansion.
</Info>

<Check>
  **Quick implementation checklist**

  * Expect `429`, `5xx`, and timeouts. They are normal at scale.
  * Never retry message sends without an `idempotency_key`.
  * For non-urgent retries, wait **100 seconds** before retrying.
  * API rate limits (`429`) never disable your app.
  * Only message volume limits can disable your app.
  * `POST /notifications` (create) and `DELETE /notifications` (cancel) count toward the same rate limit.
  * The [Create custom events](/reference/create-custom-events) endpoint has its own rate limit, separate from the notification endpoints.
</Check>

***

## API rate limits

API rate limits apply **per app and per endpoint**. They are evaluated when a request is received, not when a response is returned.

These limits are designed to throttle traffic, not block your app.

| Endpoint                                                                                  | Rate limit                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create message](/reference/create-message) / [Cancel message](/reference/cancel-message) | **Free plans:** 150 requests/sec/app<br />**Paid plans:** 6,000 requests/sec/app<br /><br />The `POST /notifications` and `DELETE /notifications` endpoints share the same limit. Requests count toward it regardless of method. For example, 3,000 creates + 3,000 cancels = 6,000 requests/sec on a paid plan.<br /><br />Each request can target many users or segments. |
| [Create custom events](/reference/create-custom-events)                                   | Rate-limited independently from Create Message.<br />**Request size limits:** 2,024 bytes per event · 1 MB per request body                                                                                                                                                                                                                                                 |
| Create, update, or delete users or subscriptions                                          | 1,000 requests/sec/app<br />1 request/sec per user or subscription<br />Up to 100 property updates per request                                                                                                                                                                                                                                                              |
| View endpoints (messages, templates, users)                                               | 1 request/sec/app<br />Up to 10 look-back requests/sec                                                                                                                                                                                                                                                                                                                      |
| Message History and CSV exports                                                           | Keep parallel exports under 100 GB per file                                                                                                                                                                                                                                                                                                                                 |

<Note>
  High-volume messaging should use fewer message creation requests with larger audiences instead of increasing request frequency.
</Note>

**Handling API rate limit errors (`429`):**

When you exceed an API rate limit, OneSignal returns an HTTP `429` response:

```json theme={null}
{
  "errors": ["API rate limit exceeded."]
}
```

The response includes a `Retry-After` header indicating how many seconds to wait before retrying.

**What to do when you receive a `429` error:**

1. Stop sending requests immediately.
2. Wait for the full duration specified in the `Retry-After` header.
3. Retry using exponential backoff.
4. Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for retries that send messages.

<Warning>
  Retrying before the `Retry-After` delay or retrying in tight loops can extend throttling and increase failure rates.
</Warning>

***

## Error handling and retry strategies

Retries are safe only when implemented correctly. Some failed requests may still be processing on our servers.

* Retriable errors generally include network timeouts, no responses, 429, and 5xx errors.
* Non-retryable errors include 400, 401, or 403 errors which indicate invalid input, authentication problems, or missing permissions. These are not temporary failures.

**Simple retry strategy:**

* Wait **100 seconds** before retrying.
  * This aligns with the maximum API response timeout.
  * If no response or network error occurs, the request may still be processing during this window.
* Retry **up to 3 total attempts** (original + 2 retries).
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

**Time-sensitive (advanced) retry strategy:**

* Retry using exponential backoff with jitter (for example: 2s, 4s, 8s… up to 60s).
* Cap retries to **10 total attempts** and stop after **10–15 minutes**.
* For `429` responses, treat `Retry-After` as a minimum delay: wait `max(Retry-After, backoff)`.
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

<Warning>
  Retrying message or custom event API requests without idempotency can result in duplicate messages or custom events.
</Warning>

<Accordion title="Example retry logic">
  ```text theme={null}
  attempt = 1
  max_attempts = 3

  send request with idempotency_key

  if response is success:
    stop

  if response is 429:
    wait Retry-After seconds
  elif response is 5xx or timeout:
    wait 100 seconds

  if attempt < max_attempts:
    retry with same idempotency_key
  else:
    fail safely
  ```
</Accordion>

### Retry decision guide

| Error type              | Retry? | When                 | Idempotency required |
| ----------------------- | ------ | -------------------- | -------------------- |
| `429 Too Many Requests` | Yes    | After `Retry-After`  | Yes                  |
| `5xx Server Error`      | Yes    | Backoff or 100s      | Yes                  |
| Timeout / no response   | Yes    | Immediate or delayed | Yes                  |
| `400 Bad Request`       | No     | Fix request          | No                   |
| `401 / 403`             | No     | Fix auth/permissions | No                   |

<Warning>
  Common implementation mistakes:

  * Retrying with a new idempotency key on each attempt.
  * Retrying indefinitely without a retry cap.
  * Retrying `400` or `401` errors without fixing the request.
  * Sending one request per user instead of batching audiences.
</Warning>

***

## Application message limits (app disablement)

Application message limits protect your users from receiving too many notifications in a short period of time.

**How the limit works:**

In any rolling 15-minute window, you may send up to **10 × your total number of subscribed [Subscriptions](/docs/en/subscriptions)**.

This limit is based on the total number of messages delivered, not the number of API requests.

* Sending 1 notification to 1,000 Subscriptions = 1,000 messages
* Sending 10 notifications to 1,000 Subscriptions each = 10,000 messages

The 15-minute window is rolling, not fixed.

* Messages are counted for 15 minutes after they are sent
* As time passes, older messages automatically stop counting
* You only exceed the limit if more than 10× your subscribed Subscriptions receive messages within the same 15-minute span

Example limits:

* App with 1,000 subscribed Subscriptions → up to 10,000 messages in any 15 minutes
* App with 10,000 subscribed Subscriptions → up to 100,000 messages in any 15 minutes

**Example scenarios:** App with 1,000 subscribed Subscriptions (limit: 10,000 messages per 15 minutes)

| Scenario                                                                              | Messages counted in any 15-minute period |    App disabled?    |
| ------------------------------------------------------------------------------------- | ---------------------------------------: | :-----------------: |
| At **12:00**, send 1 notification to 1,000 users                                      |                                    1,000 |          No         |
| At **12:00**, send 10 notifications to 1,000 users                                    |                                   10,000 |   Yes (hits limit)  |
| Between **12:00–12:14**, send 10,000 notifications to 1 user                          |                                   10,000 |   Yes (hits limit)  |
| Send **9,000 messages at 12:00**, then **9,000 more at 12:16**                        |                                    9,000 |          No         |
| Send **9,000 messages spread between 12:00–12:14**, then send **9,000 more at 12:15** |                                 \~18,000 | Yes (exceeds limit) |

<Note> This limit is evaluated continuously over a rolling 15-minute window, not in fixed time blocks. If any 15-minute span exceeds your limit, the app is disabled. </Note>

**What happens if the limit is exceeded:**

If your app sends more messages than allowed within a 15-minute window:

* Your app is temporarily disabled
* All app administrators receive an email notification
* A re-enable banner appears in the OneSignal Dashboard

<Warning> Only application message limits can disable your app. API rate limits (`429` errors) never disable apps. </Warning>

**What to do if your app is disabled:**

If your app is disabled, follow these steps in order:

1. Pause message sending from your backend, jobs, or automations.
2. Identify the cause, such as infinite loops, retry storms, or unexpected segment growth.
3. Log in to the OneSignal Dashboard.
4. Click **Re-enable** in the red banner at the top of the app.
5. If you need help re-enabling your app, contact `support@onesignal.com`.

***

## FAQ

### Do API rate limits disable my app?

No. API rate limits (`429` errors) only throttle your requests temporarily. Only [application message limits](#application-message-limits-app-disablement) — which track the total volume of messages delivered — can disable your app.

### What is an idempotency key and when do I need one?

An idempotency key is a unique identifier you include with a request so that retrying the same request does not create a duplicate message or event. You need one whenever you retry a `POST /notifications` or custom event request. Reuse the same key for every retry attempt. See [Idempotent API requests](/reference/idempotent-notification-requests).

### Can I increase my API rate limit?

Paid plans have higher rate limits (6,000 requests/sec vs. 150 for free plans). If you need limits beyond the paid tier, contact `support@onesignal.com` with your use case and expected volume.

### Why was my app disabled even though I didn't hit the API rate limit?

API rate limits and application message limits are separate. Your app can be disabled if the total number of messages delivered in any 15-minute window exceeds 10× your subscription count — even if every individual API request succeeded. Common causes include retry storms, runaway automations, or targeting a larger audience than intended.

***

## Related pages

<Columns>
  <Card title="Idempotent API requests" icon="rotate" href="/reference/idempotent-notification-requests">
    Prevent duplicate messages by reusing idempotency keys on retries.
  </Card>

  <Card title="Create message API" icon="paper-plane" href="/reference/create-message">
    API reference for sending push, email, SMS, and in-app messages.
  </Card>

  <Card title="Create custom event API" icon="bolt" href="/reference/create-custom-events">
    API reference for sending custom events that trigger Journeys.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="/docs/en/subscriptions">
    Understand how subscriptions are counted toward message limits.
  </Card>
</Columns>


# REST API overview
Source: https://documentation.onesignal.com/reference/rest-api-overview

Programmatic access to OneSignal messaging, user management, segments, and data exports over HTTPS with rate limiting and retry support.

The OneSignal REST API follows the [REST architecture](https://en.wikipedia.org/wiki/Representational_state_transfer) and provides programmatic access to core messaging and user features. Use the API to send push notifications, emails, and SMS, manage Users, Subscriptions, Segments, export data, and configure apps.

## Which API to use

| Goal                          | API                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| Send a push, email, or SMS    | [Create Message](/reference/create-message)                                                              |
| Add or update user data       | [Create User](/reference/create-user) / [Update User](/reference/update-user)                            |
| Target a group of users       | [Create Segments](/reference/create-segments) or use [Filters](/reference/create-message#filters) inline |
| Export analytics or user data | [CSV Export](/reference/csv-export) / [CSV of Events](/reference/export-csv-of-events)                   |
| Manage app configuration      | [Create App](/reference/create-an-app) / [Update App](/reference/update-an-app)                          |

***

## Requirements

**General**

* **HTTPS required**: All API requests must use HTTPS with **TLS 1.2 or higher** on port `443`.
* **Network access**: Firewalls or proxies must allow **outbound traffic** to `https://api.onesignal.com` on port `443`.
* **DNS TTL**: Clients must respect OneSignal’s DNS **TTL of 300 seconds** to avoid stale IP resolution.

**Incoming Traffic to OneSignal (API & SDK Requests)**

All incoming API traffic—whether from your backend, the OneSignal SDKs, or the dashboard—passes through **Cloudflare**, which serves as the global edge network.

* You may see Cloudflare IP addresses in logs.
* Cloudflare IPs may change over time.
* If you maintain a strict firewall, use Cloudflare’s official [IP ranges](https://www.cloudflare.com/ips/)

<Warning>
  Avoid allowlisting specific Cloudflare IPs, as they may change without notice.
</Warning>

**Outgoing Traffic from OneSignal (Webhooks & Event Streams)**

For features where OneSignal sends HTTP requests to your servers (such as webhooks or event streams), traffic originates from OneSignal infrastructure running on Google Cloud Platform (GCP) in the `europe-west4` region (Groningen, Netherlands).

* Allow inbound traffic from `https://api.onesignal.com`, **or**
* Use GCP’s maintained IP range list and filter by `europe-west4` region: [GCP IP ranges](https://www.gstatic.com/ipranges/cloud.json)

<Note>
  OneSignal supports [IP allowlisting](/docs/en/keys-and-ids) with REST API keys.
</Note>

***

### Platform-specific network requirements

#### FCM (Google Android and Chrome push)

* Required ports: `5228`, `443`, `5229`, and `5230`
* No IP allowlisting needed
* More info: [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

#### APNs (Apple iOS, iPadOS, Safari push)

* Required ports: `5223`, `443`, and `2197`
* Recommended servers:
  * Sandbox: `api.sandbox.push.apple.com:443`
  * Production: `api.push.apple.com:443`
  * IP range: `17.0.0.0/8`
* More info:
  * [Apple Support](https://support.apple.com/en-us/102266)
  * [APNs Developer Docs](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns?language=objc)

***

## Core API capabilities

### Send messages

See the [Create Message guide](/reference/create-message) to get started. Programmatically send:

<Columns>
  <Card title="Push Notifications" icon="bell" href="/reference/push-notification">
    Send push notifications to apps and websites.
  </Card>

  <Card title="Email" icon="envelope" href="/reference/email">
    Send transactional and promotional emails.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/reference/sms">
    Send SMS or MMS messages globally.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="/reference/start-live-activity">
    Send Live Activity updates to iOS devices.
  </Card>
</Columns>

<Note>
  For platform-specific features like personalization, throttling, and frequency capping, see the [Push](/docs/en/push), [Email](/docs/en/email-messaging), [SMS](/docs/en/sms-messaging), and [Live Activities](/docs/en/live-activities) overview guides.
</Note>

***

### Manage templates

[Templates](/docs/en/templates) are reusable push, email, and SMS messages that simplify development and improve consistency.

<Columns>
  <Card title="Create template" icon="plus" href="/reference/create-template">
    Save a reusable message layout for push, email, or SMS.
  </Card>

  <Card title="Update template" icon="pen-to-square" href="/reference/update-template">
    Modify an existing template's content or settings.
  </Card>

  <Card title="View templates" icon="eye" href="/reference/view-templates">
    List all templates in your app with their metadata.
  </Card>

  <Card title="Delete template" icon="trash" href="/reference/delete-template">
    Permanently remove a template from your app.
  </Card>
</Columns>

***

### Track custom events

[Custom events](/docs/en/custom-events) record user actions like purchases, content views, or milestones. Use them to enter users into [Journeys](/docs/en/journeys-settings) or trigger [Wait Until](/docs/en/journeys-actions) nodes.

<Card title="Create custom events" icon="bolt" href="/reference/create-custom-events">
  Record user events to trigger Journeys and track behavior.
</Card>

***

### Manage Users and Subscriptions

See the [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) guides for more details.

<Columns>
  <Card title="Create user" icon="user-plus" href="/reference/create-user">
    Create a user with optional aliases and subscriptions.
  </Card>

  <Card title="View user" icon="eye" href="/reference/view-user">
    View user details.
  </Card>

  <Card title="Update user" icon="user-pen" href="/reference/update-user">
    Modify a User's properties, tags, or aliases.
  </Card>

  <Card title="Delete user" icon="user-minus" href="/reference/delete-user">
    Permanently remove a User and all associated data.
  </Card>
</Columns>

***

### Manage Segments

[Segments](/docs/en/segmentation) group Users by filters for targeted messaging.

<Columns>
  <Card title="Create Segments" icon="plus" href="/reference/create-segments">
    Define a new Segment with filters to group Users.
  </Card>

  <Card title="Update Segment" icon="pen-to-square" href="/reference/update-segment">
    Modify a Segment's name or replace its filters.
  </Card>

  <Card title="Delete Segments" icon="trash" href="/reference/delete-segments">
    Permanently remove a Segment from your app.
  </Card>
</Columns>

<Note>
  You can also target users dynamically using [filters](/reference/create-message#filters) without creating persistent segments.
</Note>

***

### Export data

For analytics breakdowns, see [Analytics overview](/docs/en/analytics-overview).

<Columns>
  <Card title="Export CSV of subscriptions" icon="file-export" href="/reference/csv-export">
    Export all user and subscription data.
  </Card>

  <Card title="Export CSV of events" icon="file-export" href="/reference/export-csv-of-events">
    Export events like sent, received, and clicked.
  </Card>

  <Card title="View messages" icon="eye" href="/reference/view-messages">
    View message details and analytics.
  </Card>

  <Card title="View message" icon="magnifying-glass" href="/reference/view-message">
    View individual message details.
  </Card>
</Columns>

***

### Manage Apps & API Keys

OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See [Apps, orgs, & accounts](/docs/en/apps-organizations).

<Columns>
  <Card title="Create an app" icon="plus" href="/reference/create-an-app">
    Register a new app with platform credentials.
  </Card>

  <Card title="Update an app" icon="pen-to-square" href="/reference/update-an-app">
    Modify app settings or platform credentials.
  </Card>

  <Card title="View single app" icon="eye" href="/reference/view-an-app">
    Retrieve configuration and details for one app.
  </Card>

  <Card title="View multiple apps" icon="list" href="/reference/view-apps">
    List all apps in your account.
  </Card>
</Columns>

#### API key management

See [Keys & IDs](/docs/en/keys-and-ids) for more details.

<Columns>
  <Card title="Create API key" icon="key" href="/reference/create-api-key">
    Generate a new API key with specific permissions.
  </Card>

  <Card title="View API keys" icon="eye" href="/reference/view-api-keys">
    List all API keys and their permissions for your app.
  </Card>

  <Card title="Delete API key" icon="trash" href="/reference/delete-api-key">
    Revoke an API key permanently.
  </Card>

  <Card title="Update API key" icon="pen-to-square" href="/reference/update-api-key">
    Modify an API key's permissions or IP allowlist.
  </Card>
</Columns>

***

## Error handling and retries

The OneSignal API may return temporary errors such as `429` (rate limited), `5xx` (server errors), or timeouts. When this happens, the request may still be processing. If you retry failed requests, always use an `idempotency_key` and follow the recommended retry delays to avoid duplicate messages.

<Card title="Rate limits and error handling" icon="triangle-exclamation" href="/reference/rate-limits">
  Retry strategies, error definitions, and recovery steps.
</Card>

***

## FAQ

### What is the timeout for API responses?

* Default: **100 seconds**
* If you're unsure whether a request completed, use an [`idempotency_key`](/reference/idempotent-notification-requests) to safely retry.
* See [Rate limits and error handling](/reference/rate-limits) for more details.

### Do I need to download or renew certificates to call the OneSignal API?

No. The OneSignal API uses HTTPS with a publicly trusted TLS certificate managed by Cloudflare. These edge certificates renew automatically and are trusted by all major browsers, operating systems, and runtimes.

If your network pins a specific leaf certificate, it will expire and rotate every few months — this is normal Cloudflare behavior. Trust the root and intermediate CAs in the chain instead of the leaf certificate to avoid disruption.

<Accordion title="Certificate pinning details and workarounds">
  * **Best practice**: Trust the root and intermediate CAs in the chain instead of the rotating leaf certificate.
  * **If you must pin a certificate**: Pin the public key (SPKI) of the CA or use a backup key set, not the exact leaf certificate.
  * **Fetching the current certificate**: If your process requires the active leaf certificate, retrieve it directly:

  ```bash theme={null}
  SERVERNAME=api.onesignal.com
  echo -n | openssl s_client -connect $SERVERNAME:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/${SERVERNAME}_current.pem
  ```

  To retrieve the full chain, add the `-showcerts` flag to `openssl s_client`.

  See [Cloudflare SSL/TLS documentation](https://developers.cloudflare.com/ssl/get-started/) and [Cloudflare Edge Certificates documentation](https://developers.cloudflare.com/ssl/edge-certificates/) for more details.
</Accordion>

### Why am I getting a 403 Forbidden error?

A `403` response means the API key is valid but does not have permission for the requested operation. Check the following:

* **Wrong key type**: App API keys work for app-level endpoints (sending messages, managing Users). Organization API keys are required for org-level endpoints (creating apps, managing API keys). See [Keys & IDs](/docs/en/keys-and-ids) for details.
* **IP allowlisting**: If IP allowlisting is enabled on your API key, requests from IPs not on the list are denied. Verify your server's IP is included.
* **Revoked or rotated key**: If the key was recently rotated, the old key is no longer valid. Update your integration with the new key.

### Why am I getting "UnknownHostException - Unable to resolve host api.onesignal.com"?

This error means your environment cannot resolve the DNS for `api.onesignal.com`. Common causes:

* **Firewall or proxy blocking DNS**: Ensure your network allows outbound DNS queries and traffic to `api.onesignal.com` on port `443`.
* **No internet connectivity**: Verify the device or server has an active network connection.
* **DNS server misconfiguration**: Try a public DNS resolver like `8.8.8.8` (Google) or `1.1.1.1` (Cloudflare) to rule out local DNS issues.
* **Stale DNS cache**: Flush your local DNS cache and ensure your client respects the TTL of 300 seconds.


# Add a player
Source: https://documentation.onesignal.com/reference/add-a-device

POST `https://onesignal.com/api/v1/players`

Register a new Subscription (aka player) to one of your OneSignal apps.

<Warning>
  This is a Legacy API. Use [Create User](/reference/create-user) or [Create Subscription](/reference/create-subscription) instead.
</Warning>

***

## Headers

| Header          | Value                     | Required | Description                      |
| --------------- | ------------------------- | -------- | -------------------------------- |
| `Content-Type`  | `application/json`        | Yes      | The content type of the request. |
| `Authorization` | `Basic YOUR_REST_API_KEY` | Yes      | Your OneSignal REST API key.     |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                                |
| -------------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                                     |
| `device_type`        | integer | Yes      | Device platform: 0 = iOS, 1 = Android, 2 = Amazon, 3 = Windows Phone, etc. |
| `identifier`         | string  | No       | Push token, email address, or phone number.                                |
| `language`           | string  | No       | Language code (e.g. "en").                                                 |
| `timezone`           | integer | No       | Time zone offset in seconds.                                               |
| `game_version`       | string  | No       | Version of your app.                                                       |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                                         |
| `device_os`          | string  | No       | Operating system version (e.g., "13.3").                                   |
| `ad_id`              | string  | No       | Advertising ID.                                                            |
| `sdk`                | string  | No       | OneSignal SDK version (e.g., "050201" for 5.2.1).                          |
| `session_count`      | integer | No       | Number of times the user has used the app.                                 |
| `tags`               | object  | No       | Custom tags as key-value pairs.                                            |
| `external_user_id`   | string  | No       | Your system's user ID for this device.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc.                 |

***

## Example Request

```json theme={null}
POST /api/v1/players HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "device_type": 1,
  "identifier": "abcdef123456",
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_model": "Pixel 4",
  "device_os": "12",
  "ad_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sdk": "050401",
  "session_count": 5,
  "tags": {
    "user_type": "free",
    "level": "10"
  },
  "external_user_id": "user123",
  "notification_types": 1
}
```

***

## Response

```json theme={null}
{
  "id": "Subscription_id_string"
}
```

## Errors

* 400 Bad Request – Invalid parameters or missing required fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Not allowed for your account type or plan.


# Cancel message
Source: https://documentation.onesignal.com/reference/cancel-message

DELETE /notifications/{message_id}?app_id={app_id}
Stop a scheduled or currently outgoing message.

## Overview

The Cancel message API can be used to stop scheduled messages from being sent. It does not delete or remove the message from the app. If a message is in the process of sending, then canceling it may not fully prevent all targeted users from receiving it.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users, scheduling the message in the future with `send_after`. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and use this API to cancel sending the message to the user if not needed anymore.

If you need a way to remove a notification already sent to a user, see [Remove notifications & TTL](/docs/en/push).

***


# Copy template to another app
Source: https://documentation.onesignal.com/reference/copy-template-to-another-app

POST /templates/{template_id}/copy_to_app?app_id={app_id}
Create a duplicate of a template in another app. The new template will be completely separate from the original (including having a new template_id) but will be created with all the same content.

## Overview

This API allows you to copy a template from one app (`app_id`) to another (`target_app_id`). The duplicated template will have the same content as the original, but a new unique `template_id`.

<Note>
  If you are trying to copy an email template, we also have an [Email Template Forwarding](/docs/en/email-template-forwarding) feature that does not require an API call.

  Both options support HTML and Drag & Drop email templates.
</Note>

***

## Requirements

* **Organization Membership:** Both the `app_id` and `target_app_id` must belong to the same [Organization](/docs/en/apps-organizations).
* **Authorization Required:** You must use your [Organization API key](/docs/en/keys-and-ids#organization-api-key), not an app-level REST API key.
* **Permissions Note:** Your user must have admin-level access to both the source and target apps. If not, the request will fail with a "permission denied" error.

***

## Parameters

* `template_id` (path param): UUID of the template to be copied.
* `app_id` (query param): ID of the app where the original template exists.
* `target_app_id` (body param): ID of the app where the template will be duplicated.

***

## How to Use

### 1. Locate the Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

### 2. Get App IDs

Refer to [Keys & IDs](/docs/en/keys-and-ids) to find your `app_id` and `target_app_id`.

***

## Response

The response will include:

* The new `template_id` for the copied template
* Confirmation of successful creation
* Any warnings if applicable (e.g., limited fields copied)

***


# Create or update alias
Source: https://documentation.onesignal.com/reference/create-alias

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Create or update one or more user aliases when you already know an existing alias. This API performs an upsert on the user’s identity object—either adding new aliases or updating existing ones.

## Overview

Use this API to manage user aliases by providing one known alias (such as `external_id`, `onesignal_id`, or a custom alias) and specifying additional aliases to add or update.

This endpoint focuses solely on the `identity` object. If you need to fully create a user with subscriptions and properties, use the [Create user](/reference/create-user) API instead.

<Note>
  * If an alias with the same `alias_label` already exists for the user, it will be updated. If it doesn’t exist, a new alias will be created.
  * Want to use a subscription instead of an alias to identify the user? Use [Create alias (by subscription)](/reference/create-alias-by-subscription).
</Note>

See also:

* [Users](/docs/en/users) – for details on OneSignal ID and External ID
* [Aliases](/docs/en/aliases) – for setting and managing custom aliases
* [Delete alias](/reference/delete-alias) – for removing aliases

***

## How to use this API

To identify the user:

* Use `alias_label` for the type of alias you know (e.g., `external_id`, `onesignal_id`, or a custom alias)
* Use `alias_id` for the value of that alias

<Note>
  We strongly recommend setting the `external_id` as your primary user identifier. This can be done through our frontend SDK's login method when a user signs in to your app or website. It helps OneSignal associate the user's push, email, and SMS subscriptions to a unified user identity.
</Note>

Changes to the identity object take effect immediately upon request.

Alias keys (`alias_label`) and values (`alias_id`) are each limited to **128 characters**. A user can have up to **10 custom aliases** total.

***


# Create alias (by subscription)
Source: https://documentation.onesignal.com/reference/create-alias-by-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Create or update an alias for a user using a known subscription ID.

Create or update an alias for a user using a known subscription ID.

# Overview

Use this API to add or update aliases associated with a user when you only know at least one subscription ID. This API is handy for scenarios where the user's identity is unknown, but a subscription is available.

To remove an alias, see [Delete alias](/reference/delete-alias) API.

***

# How to use this API

You must know the `subscription_id` of the subscription that belongs to the user in which you want to update. Subscription IDs are UUIDs generated by OneSignal and cannot change. See [Subscriptions](/docs/en/subscriptions) for details.

This endpoint performs an upsert—if the user already has an alias with the specified alias label, it gets updated; otherwise, a new alias will be created.

The request body must include an identity object containing one or more aliases to be created or updated.

The OneSignal ID is read-only and used only for fetching. See [Users](/docs/en/users) for details.

Aliases are updated immediately upon request.

***


# Create an app
Source: https://documentation.onesignal.com/reference/create-an-app

POST /apps
Programmatically create a new OneSignal app via the REST API. This guide explains required fields, supported platform configurations (Web, Android, iOS), and how to properly authenticate using your Organization API key.

## Overview

Use this API to programmatically create a new OneSignal app. This is useful for automating app setup, particularly when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need to Base64 encode your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns):

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates):

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Create API key
Source: https://documentation.onesignal.com/reference/create-api-key

POST /apps/{app_id}/auth/tokens
Use the OneSignal API to create a new Rich Authentication Token (App API Key) for a specific app. This guide explains how to authenticate with the Organization API key and configure optional IP allowlists using CIDR notation.

## Overview

Use this API to create a new **App API Key** (also called a **Rich Authentication Token**) for a specific OneSignal app. These keys are used to authenticate API requests at the app level and offer enhanced security features, including optional IP allowlisting.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

### IP allowlisting

By default, the API key will not be restricted to any specific IP addresses. To enable IP allowlisting, you need to set the `ip_allowlist_mode` parameter to `explicit` and provide a list of allowed IP addresses in the `ip_allowlist` parameter.

If you want to set the explicit range of IPs that can use this API key, add them by setting `ip_allowlist_mode` to `explicit` and in `ip_allowlist` add the IPs in CIDRs notation as an array of string values.

***


# Create custom events
Source: https://documentation.onesignal.com/reference/create-custom-events

POST /apps/{app_id}/custom_events
The Custom Events API allows you to record user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones.

## Overview

The Custom Events API allows you to track user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones. See [Custom events](/docs/en/custom-events) for more information.

### Use Cases

Custom events can be used to:

* Enter users into [Journeys](/docs/en/journeys-settings)
* Trigger Journey [Wait Until](/docs/en/journeys-actions) nodes

### Error handling

If individual events can't be processed, an `errors` key will be returned in the response (with HTTP status 202) containing information about each failing event. The most common event-specific error is a failure to find a user associated with the External ID or OneSignal ID in the event.

If you'd like to retry sending events in the case of a failure, you only need to re-send the events for which errors were returned -- events that don't have an error associated with them are still processed. However, if a 5xx HTTP response is returned, you must retry the entire batch of events.

In either case, if you are implementing retry, make sure to also pass an [`idempotency_key`](/reference/idempotent-notification-requests).

### Duplicate events

If you implement retry behavior for your custom event delivery, please provide the [`idempotency_key`](/reference/idempotent-notification-requests) field. Each unique event should get its own unique UUID, and when retrying delivery for events, the same UUID must be provided. Duplicate events with the same `idempotency_key` will be ignored on a best-effort basis within a 4-hour period. This allows you to avoid erroneously triggering Journeys multiple times or incurring charges for storing unnecessary duplicate events.

***


# Create segment
Source: https://documentation.onesignal.com/reference/create-segments

POST /apps/{app_id}/segments
Programmatically create segments in your OneSignal app using flexible filters and targeting rules.

## Overview

Use this API to create new [Segments](/docs/en/segmentation) programmatically. These segments are then accessible in the OneSignal Dashboard and usable in messages, Journeys, and in-app messaging campaigns.

<Note>
  To modify an existing segment, use the [Update segment](/reference/update-segment) API.
</Note>

***

## How to use this API

This endpoint allows your backend to define audience segments by passing in a combination of filters and logical operators like `"AND"` and `"OR"`, mirroring the segmentation capabilities of the OneSignal Dashboard.

### Name the segment

The name of the segment as it shows in the OneSignal dashboard and accessible via the `included_segments` and `excluded_segments` targeting parameters.

### Describe the segment

Optionally include a `description` (max 255 characters) to record the segment's purpose. The description is returned by the [View segments](/reference/view-segments) and [View segment](/reference/view-segment) APIs.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "10"}
  ]
}
```

### Define the `filters`

Available filters:

* [operator](#operator)
* [tag](#tag)
* [last\_session](#last_session)
* [first\_session](#first_session)
* [session\_count](#session_count)
* [session\_time](#session_time-1)
* [language](#language)
* [app\_version](#app_version)
* [location](#location)
* [country](#country)

### `operator`

**Description**

Allows you to combine or separate properties. Filters combined with an `"AND"` have higher priority than `"OR"` filters.

* `"AND"` = the 2+ connected filters must be satisfied for the recipient to be included. Filter entries use this by default and its not required to be included.
* `"OR"` = the 2 filters separated by the `"OR"` operator are mutually exclusive. The recipients only need to satisfy the conditions on either side of the `"OR"` operator.

<CodeGroup>
  ```json AND example theme={null}
  // Users must satisfy both filters to be included.
  // Notice the AND operator is not required

  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  // The same example using the AND operator. This is not required.
  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "AND"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  ```

  ```json OR example theme={null}
  // Users can satisfy either filter to be included.

  "filters": [
    {"field": "tag", "key": "level", "relation": "=", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "level", "relation": "=", "value": "20"}
  ]
  ```

  ```json Combinations theme={null}
  // In this example, users must either have:
  // The specified session_count AND tag requirement
  // Or it will be all records where last_session is satisfied
  {
    "name": "2 filters or 1",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"}
    ]
  }

  // Similar to the first example, this shows how to require a specific field
  // across other filters

  {
    "name": "3 filters, 1 required across all",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
    ]
  }
  ```
</CodeGroup>

### `tag`

**Description**

Target based on custom user [Tags](/docs/en/add-user-data-tags).

<Warning>
  Do not use tags for targeting individual users like a "user id".
  Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
</Warning>

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
  * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
* `key` = Tag key to compare.
* `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

```json theme={null}
"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "OR"},
  {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
]
```

### `last_session`

**Description**

Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "last_session", "relation": ">","hours_ago": "10"}
  ]
  ```

### `first_session`

**Description**

Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "first_session", "relation": "<","hours_ago": "24"}
  ]
  ```

### `session_count`

**Description**

Total number of sessions by the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="` or `"!="`
* `value` = number of sessions. Example: `"1"`

  ```json theme={null}
  "filters": [
    {"field": "session_count", "relation": ">","value": "5"}
  ]
  ```

### `session_time`

**Description**

Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

* `relation` = `">"` or `"<"`
* `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

  ```json theme={null}
  "filters": [
    {"field": "session_time", "relation": ">","value": "86400"}
  ]
  ```

### `language`

**Description**

[User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = 2 character language code. Example: `"en"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "language", "relation": "=","value": "en"},
    {"operator": "OR"},
    {"field": "language", "relation": "in_array","value": "es,fr,de"}
  ]
  ```

### `app_version`

**Description**

App version set on the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = app version. Example: `"1.0.0"`
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "app_version", "relation": "=","value": "1.0.1"},
    {"operator": "OR"},
    {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
  ]
  ```

### `location`

**Description**

Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

* `radius` = in meters
* `lat` = latitude
* `long` = longitude

  ```json theme={null}
  "filters": [
    {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
  ]
  ```

### `country`

**Description**

Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "=", "value": "US"},
    {"operator": "OR"},
    {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
  ]
  ```

***


# Create Subscription by alias
Source: https://documentation.onesignal.com/reference/create-subscription

POST /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions
Use this API to attach a new subscription—such as email, SMS, or push notification—to an existing OneSignal user identified by an alias.

## Overview

This API allows you to add a **new Subscription** to an existing [User](/docs/en/users) via an alias identifier. A *Subscription* reflects a user's intent to receive messages through a specific communication channel, such as email, SMS, or push notifications. See [Subscriptions](/docs/en/subscriptions) for additional context.

If you're looking to **create a new user and add Subscriptions simultaneously**, use the [Create User](/reference/create-user) API instead.

***

## How to use this API

To attach a Subscription, the user must already exist and be referenced using an alias. The `alias_label` and `alias_id` path parameters define how the user is identified:

* Common alias: `external_id`
* Other options: `onesignal_id`, or custom aliases

For details, refer to [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

## Required Fields

Each Subscription must include at least:

* `type`: the channel (e.g., `Email`, `SMS`, `iOSPush`)
* `token`: the unique identifier for the channel (e.g., email address, phone number, push token)

If the specified `type` and `token` already exist in the app, the Subscription will be transferred to the user identified in the path parameters.

***


# Create template
Source: https://documentation.onesignal.com/reference/create-template

POST /templates
Create reusable message templates for push, email, and SMS channels. Templates can be accessed through both the dashboard and API using a `template_id`.

## Overview

Use this endpoint to create a new message template in your OneSignal app. Once created, the template becomes available for use when sending messages via both the Dashboard and the REST API by referencing the `template_id`.

Templates streamline and standardize message content across push, email, and SMS channels.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Before using this endpoint, ensure that the target channel (push, email, or SMS) is properly configured in your OneSignal app. See [Channel Setup](/docs/en/channel-setup) for guidance.

### Push Templates

**Requirements:**

* Set the `contents` property with the English (`en`) language key.
* All [Push Channel Properties](/reference/push-notification) are valid for use in push templates.
* By default, all push platforms are enabled. You can target specific platforms by explicitly setting them (e.g., `isAndroid: true` disables others).

### Email Templates

**Requirements:**

* Set `isEmail: true`.
* Include both `email_subject` and `email_body`.
* All [Email Channel Properties](/reference/email) are valid for use in email templates.

### SMS Templates

**Requirements:**

* Set `isSMS: true`.
* Provide SMS-specific parameters like `contents`.
* All [SMS Channel Properties](/reference/sms) are valid for use in SMS templates.

***


# Create user
Source: https://documentation.onesignal.com/reference/create-user

POST /apps/{app_id}/users
Create a new user or modify the subscriptions associated with an existing User.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint enables you to create and manage users outside of frontendSDK-based sessions. It's primarily used to:

* Import users from other systems.
* Programmatically define users by assigning identifiers (aliases), properties (e.g., tags), and messaging subscriptions (e.g., email, mobile, SMS).

If you're using the frontend SDKs, user creation is typically handled automatically via methods like `login`, `addEmail`, and `addSms`. See [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) for conceptual guidance.

***

## How to use this API

To successfully create a user via the API:

* You must provide at least one unique identifier via the `identity` and Subscription via the `subscriptions` fields.
* You can optionally include user profile data (`properties`) and one or more messaging `subscriptions`.

## Key Concepts

### Aliases

Aliases uniquely identify a user and should include an `external_id` (the recommended identifier). They allow you to reference users across platforms or external systems. Up to 10 custom aliases are supported. Each alias key and value has a maximum length of 128 characters.

### Properties

User properties store information such as tags, location, activity, and device data. These attributes help you personalize campaigns and optimize engagement strategies.

### Subscriptions

A user can have up to **20 subscriptions** (across email, SMS, push, etc.). Subscriptions connect users to channels for message delivery and are transferable across users. See [Subscriptions](/docs/en/subscriptions) for more.

***


# Export subscriptions CSV
Source: https://documentation.onesignal.com/reference/csv-export

POST /players/csv_export
Generate a GZip-compressed CSV export of your current subscription data using this API endpoint.

## Overview

Use this endpoint to request a GZip-compressed CSV export of all your [Subscriptions data](/docs/en/subscriptions) from OneSignal. The export includes both default and optional user data fields, and supports filters to refine the dataset. The file is downloadable via a URL returned in the API response.

***

## How to use this API

By default, this will export all Subscriptions within the app.

**Optional filters:**

You can narrow the export using:

* `segment_name`: Only export Subscriptions from a specific segment. Segment membership rules determine which subscription statuses are included. Use with `include_unsubscribed` to include unsubscribed subscriptions.
* `last_active_since`: Export Subscriptions where their `last_session` was after a specific Unix timestamp. Example: Use `1704067200` for Subscriptions active since January 1st, 2024.
* `include_unsubscribed`: When exporting a segment, set to `true` to include unsubscribed subscriptions alongside subscribed ones. By default, segment-filtered exports only return subscribed subscriptions. This parameter has no effect when `segment_name` is not provided.

**Example successful response:**

```json 200 OK theme={null}
{
  "csv_file_url": "https://onesignal.com/csv_exports/b2f7f966.../users_1849..._2024-11-10.csv.gz"
}
```

**Export time considerations:**

* Generation speed: \~2,000 records per second.
* File readiness: The `csv_file_url` may return a 404 until generation completes.
* Download retry: Poll the file URL at intervals until the file is ready.
* File expiration: The file remains available for 3 days after generation.
* Concurrency: Only one export per OneSignal account can run at a time.

**File not ready (404 response)**

```xml 404 CSV GET  theme={null}
This XML file does not appear to have any style information
associated with it. The document tree is shown below.
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

<Info>
  You can safely poll the `csv_file_url` until the file becomes available. Implement retry logic based on expected data volume and generation speed.

  Only one export is allowed at a time per account. Wait until the `.csv.gz` file is downloaded before triggering another export.
</Info>

***

## CSV data contents

The export includes two types of fields:

* **Default fields**: Always included unless excluded by schema changes.
* **Extra fields**: Must be explicitly requested using the `extra_fields` parameter.

### Default fields

* `id`: The Subscription ID.

* `identifier`: The push token, email address, or phone number depending on the Subscription type.

* `session_count`: The number of times the user has opened the app.

* `language`: The user's language in ISO 639-1 format.

* `timezone`: Deprecated — use `timezone_id` instead.

* `game_version`: The version of your app that the user is currently using.

* `device_os`: The device's operating system version.

* `device_type`: Integer representing channel/device type.
  * `0`: iOSPush
  * `1`: AndroidPush
  * `2`: FireOSPush
  * `5`: ChromePush
  * `7,17`: SafariPush
  * `11`: Email
  * `14`: SMS

* `device_model`: The device's hardware string.

* `ad_id`: Deprecated.

* `tags`: Custom key/value data.

* `last_active`: The last time the user was active.

* `playtime`: The total amount of time in seconds the user had the mobile app open.

* `created_at`: The first time the user was seen.

* `invalid_identifier`: Boolean flag for unsubscribed state.
  * `t`: Unsubscribed
  * `f`: Subscribed

### Extra fields (`extra_fields`)

Pass `extra_fields` in your request to include any of the following:

* `external_user_id`: Maps to the `external_id` of the user.

* `onesignal_id`: OneSignal's user ID.

* `location`: Adds the `lat` and `long` coordinates if set.

* `country`: The user's country in ISO 3166-1 Alpha 2 format.

* `ip`: The IP address if detected. Can be IPv4 or IPv6 format.

* `web_auth`: Only available to OneSignal SDKs. The `web_auth` key for web push.

* `web_p256`: Only available to OneSignal SDKs. The `web_p256` for web push.

* `unsubscribed_at`: The date and time the user last unsubscribed. They may resubscribe at any time. Check the `invalid_identifier` field to determine if they are currently subscribed.

* `notification_types`: Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/en/subscriptions#notification-types).

* `timezone_id`: The user's timezone in IANA format.

***


# Remove alias
Source: https://documentation.onesignal.com/reference/delete-alias

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}
Remove a specific alias from a user.

## Overview

Use this API to remove a specific alias from a user’s identity object without deleting the user. This operation only affects user identity labels—subscriptions and the core user record remain intact. To delete a user entirely, including all associated aliases and subscriptions, see the [Delete user](/reference/delete-user) API.

***

## How to use this API

To remove an alias from a user:

1. Identify the user via a known alias by specifying:

   * `alias_label` – the type of alias (e.g., email, external\_id)
   * `alias_id` – the unique identifier for that alias

2. Specify the alias to remove using:

   * `alias_label_to_delete` – the label of the alias to be deleted

   The `alias_label_to_delete` can be the same as the `alias_label` used to identify the user.

3. This action is performed synchronously—the alias is deleted immediately after the request is processed.

<Warning>
  The `onesignal_id` alias cannot be deleted. Only secondary aliases (like email, external\_id, etc.) are removable.
</Warning>

For a full explanation of identity management, see [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

***

## FAQ

### Can I delete the same alias that I used to look up the user?

Yes. This is a common scenario—especially if an alias was set incorrectly and needs to be removed. Just be sure to include that alias both as the identifier and as alias\_label\_to\_delete.

If you want to delete the entire user and all associated data, use the [Delete user](/reference/delete-user) API.

### What happens if I delete all aliases associated with the user?

A user will always retain at least one alias, the onesignal\_id. Even if you remove all other aliases, the user and their subscriptions remain linked to the onesignal\_id.

***


# Delete API key
Source: https://documentation.onesignal.com/reference/delete-api-key

DELETE /apps/{app_id}/auth/tokens/{token_id}
Delete a specific Rich Authentication Token (App API Key) for a OneSignal app. Requires your Organization API Key and the token's unique ID, not the token value itself.

## Overview

Use this API to delete a specific App API Key (Rich Authentication Token) for a single OneSignal.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Delete segment
Source: https://documentation.onesignal.com/reference/delete-segments

DELETE /apps/{app_id}/segments/{segment_id}
Delete segments from OneSignal. Does not delete users or subscriptions.

## Overview

The Delete segment method is used when you want to programmatically delete a segment from within the OneSignal Dashboard UI.

<Warning>
  Once a segment is deleted, it cannot be recovered. You will need to create a new segment with the same filters.
</Warning>

***

## How to use this API

You can pass in the `segment_id` dictating which segment from our dashboard will be deleted.

The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard as shown below:

<Frame>
  <img />
</Frame>

***


# Delete Subscription
Source: https://documentation.onesignal.com/reference/delete-subscription

DELETE /apps/{app_id}/subscriptions/{subscription_id}
Delete a specific subscription by its subscription_id. This stops messages from being sent to that subscription but does not prevent future subscriptions with the same token.

## Overview

Use this API to delete an existing Subscription and its associated properties. Deletion is **asynchronous**, and while the Subscription is being removed, messages will no longer be sent to it.

<Warning>
  This operation only deletes a **single Subscription**. To remove a **user and all their Subscriptions**, use the [Delete User](/reference/delete-user) API instead.
</Warning>

### What Happens When You Delete

* Messages will stop being sent to the deleted subscription.
* **Deleting a Subscription does not block new Subscriptions** with the same `token`.
  * If the app is reopened or a token is re-submitted (e.g., same email or phone), a **new Subscription** may be automatically created.
  * This ensures users can re-subscribe if needed without requiring manual intervention.

***

## How to Use This API

**Required:** `subscription_id`

You must provide the `subscription_id` of the subscription to be deleted. This ID is a UUID generated by OneSignal and is immutable.

To find the `subscription_id`:

1. Use the [View User](/reference/view-user) API.
2. Look at the `subscriptions` array in the response.
3. Identify the correct subscription by its `type`, `token`, or other metadata.
4. Use the corresponding `id` field as the `subscription_id`.

***


# Delete template
Source: https://documentation.onesignal.com/reference/delete-template

DELETE /templates/{template_id}?app_id={app_id}
Permanently delete a specific message template from your OneSignal app using its template ID. Templates used in Journeys must be removed from those Journeys before deletion.

## Overview

This endpoint allows you to delete a single template associated with your OneSignal app. Deletion is **immediate and irreversible**.

<Warning>
  If the template is currently used in a Journey, it cannot be deleted until that Journey has been deleted.
</Warning>

***

## How to use this API

Required Parameters

* `template_id` (path param): The OneSignal-generated UUID of the template to delete.
* `app_id` (query param): Your OneSignal App ID.

### Where to Find `template_id`

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# Delete user
Source: https://documentation.onesignal.com/reference/delete-user

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}
Delete a user including all associated properties, subscriptions, and identity.

## Overview

Use this API to permanently delete a user from your OneSignal project, including all associated subscriptions, properties, and aliases. The operation is asynchronous—user data will be deleted shortly after the request is accepted.

***

## How to use this API

To delete a user, you must be able to identify them using one of the following alias types:

* `external_id` (recommended and most common)
* `onesignal_id`
* A custom Alias that you have set

Pass the appropriate `alias_label` and corresponding `alias_id` in the request path.

<Warning>
  This operation deletes all data associated with the user, including:

  * All identity aliases
  * All channel subscriptions (push, email, SMS, etc.)
  * All custom user properties
</Warning>

## Because this is an irreversible operation, be sure that you really intend to delete the user and all their data.


# Delete player record
Source: https://documentation.onesignal.com/reference/delete-user-record

delete https://onesignal.com/api/v1/players/{player_id}?app_id={app_id}

Delete a player (aka Subscription).

<Warning>
  This is a Legacy API. Use [Delete User](/reference/delete-user) or [Delete Subscription](/reference/delete-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `app_id`    | string | Yes      | Your OneSignal App ID.         |
| `player_id` | string | Yes      | The Subscription ID to delete. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Example Request

```http theme={null}
DELETE /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json
```

***

## Example Response

```json theme={null}
{
  "success": true
}
```

The Subscription will be deleted from the OneSignal database.

***


# Edit player
Source: https://documentation.onesignal.com/reference/edit-device

put https://onesignal.com/api/v1/players/{player_id}

Update a player's (Subscription's) information using the Subscription ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `player_id` | string | Yes      | The OneSignal Subscription ID. |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request.    |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                |
| -------------------- | ------- | -------- | ---------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                     |
| `identifier`         | string  | No       | Push token, email, or phone number.                        |
| `language`           | string  | No       | Language code (e.g., "en").                                |
| `timezone`           | integer | No       | Time zone offset in seconds.                               |
| `game_version`       | string  | No       | App version.                                               |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                         |
| `device_os`          | string  | No       | OS version (e.g., "14.5").                                 |
| `ad_id`              | string  | No       | Advertising ID.                                            |
| `sdk`                | string  | No       | OneSignal SDK version.                                     |
| `tags`               | object  | No       | Custom key-value pairs.                                    |
| `external_user_id`   | string  | No       | Your internal user ID.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc. |
| `email_auth_hash`    | string  | No       | Required to update email identifiers securely.             |
| `sms_auth_hash`      | string  | No       | Required to update SMS identifiers securely.               |

> Only include fields you want to change. Fields left out will not be modified.

***

## Example Request

```json theme={null}
PUT /api/v1/players/player_id_string HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "external_user_id": "user123",
  "tags": {
    "level": "20",
    "subscription": "active"
  },
  "language": "fr",
  "timezone": 3600,
  "device_os": "16.0"
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Missing or invalid fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied.
* 404 Not Found – Device with player\_id not found.

***


# Edit tags with external user id
Source: https://documentation.onesignal.com/reference/edit-tags-with-external-user-id

put https://onesignal.com/api/v1/apps/{app_id}/users/{external_user_id}

Update a player's (Subscription's) information using the External ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter          | Type   | Required | Description             |
| ------------------ | ------ | -------- | ----------------------- |
| `app_id`           | string | Yes      | Your OneSignal App ID.  |
| `external_user_id` | string | Yes      | The user's External ID. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Request Body Parameters

| Field  | Type   | Required | Description                       |
| ------ | ------ | -------- | --------------------------------- |
| `tags` | object | Yes      | Key-value pairs to set or update. |

* To **delete a tag**, set its value to an empty string (`""`).
* Existing tags with the same keys will be **overwritten**.

***

## Example Request

```http theme={null}
PATCH /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json

{
  "tags": {
    "plan": "premium",
    "logged_in": "true",
    "referral": ""
  }
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Invalid request or payload.
* 401 Unauthorized – Invalid or missing keys.
* 403 Forbidden – Access denied due to insufficient permissions.
* 404 Not Found – No players found for given `external_user_id`.

***


# Email
Source: https://documentation.onesignal.com/reference/email

POST /notifications?c=email
Send a message using the email channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for email. See [Push notification](/reference/push-notification) or [SMS](/reference/sms) to send to those channels.

Ensure your [Email setup](/docs/en/email-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Export audience activity CSV
Source: https://documentation.onesignal.com/reference/export-csv-of-events

POST /notifications/{message_id}/export_events
Export a compressed CSV report of audience-level delivery and engagement data for a specific message. This includes sent, delivered, clicked, failed, and unsubscribed events across Push, Email, and SMS channels.

## Overview

Get a CSV of per-recipient audience activity events (sends, clicks, failures, etc.) for a push, email, or SMS message. This endpoint mirrors the **Export** button in the dashboard's Audience Activity section on each message report:

* [Push message reports](/docs/en/push-notification-message-reports)
* [Email message reports](/docs/en/email-message-reports)
* [SMS message reports](/docs/en/sms-message-reports)

The CSV schema varies by channel. See each channel's message reports page for column definitions.

***

## How to use this API

Get the message `id` from the [Sending messages API](/reference/create-message) or the [View messages API](/reference/view-messages).

A successful request returns `200 OK` with a `csv_file_url`:

```json 200 OK theme={null}
{
    "csv_file_url": "https://onesignal-data.onesignal.com/csv_exports/YOUR_APP_ID/events_audience-activity-YOUR_MESSAGE_ID-push-YYYY-MM-DDTHH-MM-SSTZ.csv.gz"
}
```

The generated file name follows the pattern `events_audience-activity-{message_id}-{channel}-{timestamp}.csv.gz`.

The file is generated at \~2,000 records per second. For large audiences, generation can take several minutes, and the URL may return `404` until the file is ready:

```xml 404 Not Found theme={null}
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

Poll the `csv_file_url` with GET and implement retries with exponential backoff. When the file is ready, the GET request downloads the `.csv.gz` file.

<Info>
  * The CSV download URL is valid for **3 days** after creation.
  * File names include a random UUID to prevent guessing.
</Info>

<Warning>
  Only **one concurrent export** is allowed per OneSignal account. Download the `.csv.gz` file before starting another export, or the new request fails.
</Warning>

***


# View user identity
Source: https://documentation.onesignal.com/reference/fetch-aliases

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Retrieve all aliases associated with a user using a known alias, such as an `external_id`, `onesignal_id`, or a custom alias. This API helps you map back to a user’s full identity from any one piece of identifying information.

## Overview

Use this API when you want to retrieve the complete identity object for a user, which includes all aliases tied to that user. It is ideal for cases where you know one alias and want to discover others—especially helpful for user mapping, debugging, or linking systems.

This endpoint is similar to the [View user](/reference/view-user) API but only returns the `identity` object—not subscriptions or properties.

<Tip>
  If you only know a subscription\_id, use View user identity (by subscription) instead.
</Tip>

For more context on user identity and aliasing:

* [Users](/docs/en/users)
* [Aliases](/docs/en/aliases)

***

## How to use this API

To identify the user, use:

* `alias_label` – the type of alias you’re using to find the user (e.g. `external_id`, `onesignal_id`, or a custom alias)
* `alias_id` – the actual value of that alias

Common usage patterns:

Using `external_id` (recommended):

* `alias_label`: `external_id`
* `alias_id`: your user ID (e.g., user-123)

Using `onesignal_id`:

* `alias_label`: `onesignal_id`
* `alias_id`: the OneSignal-assigned unique ID

Using a custom alias:

* Define your own alias label (e.g. `shopify_customer_id`) and its value

<Note>
  We strongly recommend setting and using the `external_id` as your primary user identifier for portability and simplicity across your systems.
</Note>

***


# View user identity (by subscription)
Source: https://documentation.onesignal.com/reference/fetch-identity-by-subscription

GET /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Retrieve all aliases linked to a user using a known `subscription_id`. This is useful when the user’s identity is unknown but you have access to one of their push, email, or SMS subscriptions.

## Overview

Use this API when you want to find the full identity (all aliases) of a user, starting from a known `subscription_id`. This is helpful for debugging, reverse lookups, or support use cases where only a subscription record is available.

<Note>
  Unlike the [View user identity](/reference/fetch-aliases) API which starts with an alias (e.g., `external_id`), this endpoint works when only a subscription ID is known.
</Note>

See [Subscriptions](/docs/en/subscriptions) for background on how subscriptions relate to users.

***

## How to use this API

To use this endpoint, you must provide:

* `subscription_id` – A UUID generated by OneSignal when a device or channel (e.g., push, email, SMS) is registered.

<Warning>
  `subscription_id` values are immutable and cannot be changed. Make sure you are using the correct value, as they are unique to each app and platform.
</Warning>

Once a valid `subscription_id` is provided, the API will return the user’s identity object, which includes all associated aliases like `external_id`, `onesignal_id`, and any custom aliases.

***


# Message history
Source: https://documentation.onesignal.com/reference/message-history

POST /notifications/{message_id}/history
View which subscriptions received a particular message

## Overview

This API enables you to retrieve all [Subscriptions](/docs/en/subscriptions) that received a specific push notification or email. You can access the notification's history for up to seven days after it was sent. Please note that notifications sent to fewer than 1,000 recipients will not record a "received" event, but they will still record "sent" events.

***

## How to Use this API

1. Submit a request to generate a report.

2. Decide delivery method

   * After receiving a successful response, **poll the destination URL** until the file becomes available. Exports typically complete within 1-3 minutes; we recommend a 10-second polling interval.
   * Alternatively, you can opt to receive an email to the address specified in the optional `email` parameter when the report is ready.

### Requirements

* A [OneSignal Professional or Enterprise Plan](https://onesignal.com/pricing).
* Enabled the "Send History via OneSignal API" option in Settings -> Integrations; notifications sent before this setting is enabled can't be retrieved.
* Requests must be made within seven days of sending the notification.

### Polling

Use the `csv_file_url` property in the response to test if the report is complete. If you receive a '403' error response, retry fetching the file after a short period; it only means we're still generating the report.

### Sample Report

The generated report is a simple CSV file that can be imported into any system for further processing.

```csv report.csv theme={null}
player_id,onesignal_id,external_id,target_channel,timestamp
"2c4fac95-7dfb-4113-9347-aba3a92ff557","ccddf35a-1233-4423-8a57-ac8c4b38eb81","a07aec27-2586-4b92-a24f-62660a1517fa","push","1628189160"
"68f5cf73-b20a-4de9-b6ee-79a863b8e7d8","d2f9f2f8-94af-4942-8183-115cef1213d5","4b66359f-3d94-4a73-806d-8ef5f0430b3d","push","1628187816"

```

### Limitations

* Querying for `opens` events are not supported.
* The `timestamp` column is included only for `clicked` events.

***


# Push notification
Source: https://documentation.onesignal.com/reference/push-notification

POST /notifications?c=push
Send a message using the push notification channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for push. See [Email](/reference/email) or [SMS](/reference/sms) to send to those channels.

Ensure your application is properly configured by following the [Mobile SDK Setup](/docs/en/mobile-sdk-setup) and/or [Web SDK Setup](/docs/en/web-sdk-setup) guides. You should see subscribed push [Subscriptions](/docs/en/subscriptions) in your OneSignal dashboard to send them messages.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Rotate API key
Source: https://documentation.onesignal.com/reference/rotate-api-key

POST /apps/{app_id}/auth/tokens/{token_id}/rotate
Rotate an existing App API Key (Rich Authentication Token) for a OneSignal app. Useful when a token is compromised or needs replacement without creating a new key from scratch.

## Overview

Use this API to rotate a **Rich Authentication Token** (App API Key) for a specific OneSignal app. Rotating a key revokes the current token and generates a new one under the same configuration—ideal when a token is lost or compromised but you don’t want to recreate and reconfigure it from scratch.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can rotate an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# SMS
Source: https://documentation.onesignal.com/reference/sms

POST /notifications?c=sms
Send a message using the SMS channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for SMS and MMS. See [Push notification](/reference/push-notification) or [Email](/reference/email) to send to those channels.

Ensure your [SMS setup](/docs/en/sms-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***

## Trackable links

Add trackable links to your SMS `contents` using [liquid syntax](/docs/en/using-liquid-syntax) in the format `{{'your_url' | track_link}}`.

Example:

```json JSON theme={null}
{
  "contents": {
    "en": "Hi, here's my link: {{'https://example.com' | track_link}} "
  }
}
```

In this example, the liquid syntax block will be replaced with a trackable short link and display in the message as: `1sgnl.co/XXXX`.

<Note>
  See [SMS trackable links](/docs/en/links#sms) for more details.
</Note>

***


# Start Live Activity
Source: https://documentation.onesignal.com/reference/start-live-activity

POST /apps/{app_id}/activities/activity/{activity_type}
Remotely start a Live Activity on iOS devices via OneSignal's REST API. Define the activity type, target users, and send dynamic, updatable content directly to a Live Activity interface.

## Overview

Remotely start an iOS Live Activity using OneSignal’s REST API. Live Activities provide real-time updates directly on the lock screen and Dynamic Island (on supported devices), enhancing user engagement with ongoing events like sports games, deliveries, or countdowns.

***

## How to use this API

1. Define a Live Activity in your app. See [Live Activities developer setup](/docs/en/live-activities-developer-setup) to get started.
2. Use the `activity_type` parameter to specify the type of the Live Activity UI to use.
3. Select your target audience to receive the Live Activity. Target all or individual users.
4. Generate a unique `activity_id` to track and manage your Live Activity.
5. Use the `event_attributes` parameter to initialize the Live Activity with static data.
6. Use the `event_updates` parameter to update the Live Activity with dynamic content.

### Select your target audience

Before sending a message, you need to determine who should receive it. OneSignal offers three targeting options:

1. **Aliases & Subscription IDs**: Send messages to specific users using unique identifiers such as External ID (recommended), OneSignal ID, custom alias, or subscription ID.
2. **Segments**: Target predefined user groups based on attributes and behavior.
3. **Filters**: Create custom targeting rules using user properties, such as tags, location, or activity.

<Note>
  You can only use one targeting method per message. For example, you cannot combine alias-based targeting with filters in the same request.

  See [Select your target audience](/reference/create-message#select-your-target-audience) for more information.
</Note>

### Set a unique `activity_id`

* Set a unique `activity_id` to track and manage the Live Activity. This value is crucial for maintaining a consistent reference to the Live Activity across different devices and sessions. Consider using a UUID, CUID, or NanoID for this parameter.
* Ensure that the `activity_id` is unique and consistently used for each Live Activity to avoid conflicts and ensure accurate tracking.

  ```json Example theme={null}
  {
    "activity_id": "217aae2b-42ee-4097-bc3f-b7a6e9d15b9b",
    ...
  }
  ```

<Info>
  See [Live Activities developer setup](/docs/en/live-activities-developer-setup) guide for more information.
</Info>

### Set `event_attributes` to initialize the Live Activity

Set default/static data to display in the Live Activity upon start.

```json Example theme={null}
{
  "event_attributes": {
  	"awayTeam": "Away Team Name",
    "homeTeam": "Home Team Name"
  }
}
```

### Set `event_updates` for dynamic content

The content used to update a running Live Activity. The object must conform to the `ContentState` interface defined within your app's Live Activity. See [Live Activities developer setup](/docs/en/live-activities-developer-setup).

Ensure that the `event_updates` object matches the [`ContentState`](https://developer.apple.com/documentation/activitykit/activityattributes/contentstate#) interface exactly as defined in your Live Activity implementation. Inconsistencies can cause Live Activities to fail to display.

```json Example theme={null}
{
  "event_updates": {
    "quarter": 1,
    "homeScore": 70,
    "awayScore": 78,
    "inTimeout": false
  }
}
```

***


# Transfer Subscription
Source: https://documentation.onesignal.com/reference/transfer-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/owner
Transfer a Subscription to a different user within the same OneSignal app. Useful for associating existing Subscriptions like push, email, or SMS with a new or updated user identity.

## Overview

Use this API to transfer a Subscription from one user to another within the same OneSignal app.

It is highly recommended to use our web and mobile SDKs to set and update the External ID with the `login` method instead of this API. Your app or website may continue to be setting the wrong External ID. Make sure to only use this API if you are setting the same External ID within your app or website.

This is typically used when:

* You want to reassign an existing push, email, or SMS Subscription to a new or updated user.
* You have changed how you're identifying users (e.g., migrating from anonymous to known users).

<Note>
  - Subscriptions **cannot be transferred across different OneSignal apps**.
  - For email and SMS Subscriptions, you can instead create new ones using [Create User](/reference/create-user).
  - For push Subscriptions, platform limitations may apply—see [Subscriptions](/docs/en/subscriptions#importing-push-subscriptions) for details.
</Note>

***

## How to Use This API

### Required Path Parameter: `subscription_id`

You must know the `subscription_id` of the subscription to be transferred. This is a unique UUID assigned by OneSignal.

### Required Body Parameter: `identity` (object)

This specifies the user the subscription should be moved to. Only **one alias** should be used per request. You can identify the target user using one of:

* `external_id` (recommended)
* `onesignal_id`
* A [custom alias](/docs/en/aliases)

***


# Unsubscribe email with token
Source: https://documentation.onesignal.com/reference/unsubscribe-with-token

POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
Unsubscribe an email address from future messages by calling this API from your custom unsubscribe page. Automatically disables the associated email subscription using a token-based approach.

## Overview

Use this API to unsubscribe an email address directly from your custom unsubscribe landing page. It is ideal when building branded opt-out experiences and enables you to track which email caused the unsubscribe.

When invoked, this endpoint:

* Sets the email Subscription's `enabled` property to `false`
* Prevents further messages from being sent to the email address unless explicitly overridden (see [Overriding unsubscribes](/reference/email#body-include-unsubscribed))
* Email Subscriptions can be re-subscribed using the [Update Subscription](/reference/update-subscription) API

<Tip>
  For instructions on setting up a custom unsubscribe page, see [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page).
</Tip>

***

## How to Use This API

### Step 1: Set Up Your Custom Unsubscribe Page

Follow the guide to [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page). You'll add a custom unsubscribe URL to your email templates using Liquid syntax.

Example URL in your email template:

```liquid theme={null}
https://yourdomain.com/unsubscribe?app_id={{ app_id }}&notification_id={{ notification_id }}&token={{ token }}
```

### Step 2: Extract the Parameters

When a user clicks the unsubscribe link, your custom unsubscribe page should extract the following from the URL:

* `app_id`: OneSignal app ID
* `notification_id`: The ID of the specific email message sent
* `token`: The email token, a secure reference to the subscription

### Step 3: Call the API

When the user confirms they want to unsubscribe (e.g., clicks a button on your unsubscribe page), make a POST request to this endpoint:

```
POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
```

Example Request (JavaScript):

```js theme={null}
fetch("https://api.onesignal.com/apps/your-app-id/notifications/your-notification-id/unsubscribe?token=abc123xyz", {
  method: "POST"
});
```

<Info>
  No request body or authentication is required. The token acts as a secure identifier.
</Info>

<Note>
  * This API only works for email subscriptions.
  * It should only be used from a server or frontend context that you control (e.g., your custom unsubscribe page).
  * Once unsubscribed, the email address will not receive future emails from your app unless resubscribed.
</Note>

***


# Update an app
Source: https://documentation.onesignal.com/reference/update-an-app

PUT /apps/{app_id}
Use to update the name or push platform configuration of an existing app. This guide explains required parameters and platform-specific update rules

## Overview

Use this API to programmatically update an existing OneSignal app. This is useful when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

***

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Warning>
  If you change your FCM Service Account JSON file to a different Firebase project, your Android Subscriptions tied to the current project will become invalid. They will not be able to receive push notifications until they open your app again with this new FCM Service Account JSON file.
</Warning>

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need help Base64 encoding your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns). **You will likely never need to update these parameters if set correctly during app creation**:

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates). **These must be updated every year which is why we recommend using p8 authentication**:

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Update API key
Source: https://documentation.onesignal.com/reference/update-api-key

PATCH /apps/{app_id}/auth/tokens/{token_id}
Update a Rich Authentication Token (App API Key) for a OneSignal app. Modify the token's name or IP allowlist settings using your Organization API Key.

## Overview

Use this API to update the properties of a specific **Rich Authentication Token** (App API Key) for a OneSignal app. You can change the name, IP allowlist mode, or the list of allowed IPs. This is helpful for adjusting access rules without needing to recreate the key.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Update Live Activity
Source: https://documentation.onesignal.com/reference/update-live-activity-api

POST /apps/{app_id}/live_activities/{activity_id}/notifications
Update or terminate running iOS Live Activities using OneSignal’s Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

## Overview

Update or terminate running iOS Live Activities using our REST API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

Before using this API, ensure your app is properly configured by following the [Live Activities developer setup](/docs/en/live-activities-developer-setup).

## How to Use this API

1. Select the Live Activity to update by specifying its `activity_id` in the URL. This is set when using the:

* [Start Live Activity API](/reference/start-live-activity)
* [Triggering it in-app](/docs/en/live-activities-developer-setup).
* [`LiveActivities.enter` SDK method](/docs/en/mobile-sdk-reference#enter)

2. Update the state of the Live Activity by setting the `event_updates` parameter to a JSON object that matches the structure of the `ActivityAttributes.ContentState` struct defined in your Live Activity widget extension.

3. When ready to terminate the Live Activity:

* Set the `event` parameter to `end`
* Include a `dismissal_date` if you want the Live Activity to be dismissed in less than 4 hours.
* Set the `dismissal_date` to a time in the past to dismiss the Live Activity immediately. User must have clicked "Allow" for the Live Activity to be removed programmatically.

<Warning>
  Once a Live Activity `activity_id` is ended, you cannot update it. This includes changing the `dismissal_date` or `event` parameter.

  If the Live Activity is not being dismissed immediately, it is either because:

  * The `activity_id` has already been ended.
  * The user has not clicked "Allow" for the Live Activity to be removed programmatically.
</Warning>

***


# Update segment
Source: https://documentation.onesignal.com/reference/update-segment

PATCH /apps/{app_id}/segments/{segment_id}
Update an existing segment's name and/or filters. The name parameter is always required. When filters are provided, all existing filters are replaced with the new ones.

## Overview

Update an existing segment's name and/or filters. This API allows you to modify [Segments](/docs/en/segmentation) programmatically without having to delete and recreate them.

<Note>
  The `name` parameter is always required, even if you're not changing it. When filters are provided, all existing filters are **replaced** with the new ones. Omit the `filters` parameter to keep existing filters intact. The `filters` array cannot be empty—if provided, it must contain at least one filter.
</Note>

***

## How to use this API

### Update segment name only

To update just the segment name without changing filters:

```json theme={null}
{
  "name": "New Segment Name"
}
```

### Update segment description

Update the optional `description` (max 255 characters). Pass an empty string to clear the existing description; omit the field to leave it unchanged.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION"
}
```

### Update segment filters

To update the segment filters (this replaces all existing filters), provide the `name` (required) and `filters`:

```json theme={null}
{
  "name": "Updated Segment",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "5"},
    {"operator": "AND"},
    {"field": "tag", "key": "subscription", "relation": "=", "value": "premium"}
  ]
}
```

### Filter syntax

The filter syntax is identical to the [Create segment](/reference/create-segments) API. Available filters include:

* `tag` - Filter by Tags
* `last_session` - Filter by last active time
* `first_session` - Filter by first session time
* `session_count` - Filter by number of sessions
* `session_time` - Filter by total usage duration
* `language` - Filter by user language
* `app_version` - Filter by app version
* `location` - Filter by GPS coordinates
* `country` - Filter by country

Use `AND` and `OR` operators to combine filters:

```json theme={null}
{
  "name": "Engaged Premium Users",
  "filters": [
    {"field": "tag", "key": "plan", "relation": "=", "value": "premium"},
    {"operator": "AND"},
    {"field": "session_count", "relation": ">", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "vip", "relation": "=", "value": "true"}
  ]
}
```

***

## Response

### Success response

```json theme={null}
{
  "success": true,
  "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19"
}
```

### Error responses

| Status Code | Description                                                                              |
| ----------- | ---------------------------------------------------------------------------------------- |
| 400         | Bad request - Invalid filters, duplicate segment name, or segment used by active Journey |
| 403         | Forbidden - API not available for your plan                                              |
| 404         | Not found - Segment does not exist                                                       |
| 429         | Rate limit exceeded                                                                      |

***


# Update Subscription by ID
Source: https://documentation.onesignal.com/reference/update-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}
Update properties on an existing OneSignal subscription using its subscription_id. Commonly used to enable or disable a subscription when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties by `subscription_id`.

This endpoint is primarily used by the OneSignal SDK to manage subscription state.

Most external use cases are better served by the [Update Subscription by token](/reference/update-subscription-by-token) API, which can use the Email Address or Phone Number as the `token` or the [Update User](/reference/update-user) API, which allows for updating user-level data.

<Note>
  For **email opt-outs**, it's recommended to use the [Unsubscribe Email (with token)](/reference/unsubscribe-with-token) API instead. This avoids the need to store or manage the `subscription_id`.
</Note>

***

## How to use this API

**Required:** `subscription_id`

To update a subscription, you **must know the `subscription_id`**. This is a UUID generated by OneSignal and is immutable.

* You can retrieve a subscription ID by querying the [User object](/docs/en/users).
* See the [Subscriptions](/docs/en/subscriptions) guide for an explanation of how subscription IDs are generated and used.

<Note>
  You **cannot** update the `type` of a Subscription. If the `type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the Subscription with the correct type.
</Note>

***


# Update Subscription by token
Source: https://documentation.onesignal.com/reference/update-subscription-by-token

PATCH /apps/{app_id}/subscriptions_by_token/{token_type}/{token}
Update properties on an existing Subscription using its token. Commonly used to enable or disable subscription status when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties.

This API can be useful if:

* You only know the `token` and `token_type` and want to update metadata or status flags directly.
* You are managing Subscription status outside of the OneSignal SDK. Like with a [custom preference page or unsubscribe page](/docs/en/create-custom-unsubscribe-page).

***

## How to use this API

To update a Subscription, you must know the `token_type` and the `token`.

The `token_type` is the [Subscription's type](/docs/en/server-sdk-reference#subscription-types) (e.g., `Email`, `SMS`, `iOSPush`, `AndroidPush`, etc.).

The `token` is the push token, email address, or phone number associated with the Subscription.

Ensure the `token` is valid and correctly formatted for the chosen `token_type`.

* **Email format:** Should be a valid email address that you confirmed can receive emails.
* **SMS format:** Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164).
* **iOSPush APNS token format:** 64 characters, hexadecimal characters only (0-9,a-f).
* **AndroidPush FCM token format:** Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.

<Warning>
  You **cannot** update the `token_type` and `token` of a Subscription with this API. If the `token_type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the subscription with the correct type.

  If multiple Subscriptions are found for the `token` and `token_type`, an `Http 400` error is returned with a list of subscription IDs that match the criteria.
</Warning>

***


# Update template
Source: https://documentation.onesignal.com/reference/update-template

PATCH /templates/{template_id}?app_id={app_id}
Update existing OneSignal message templates for push, email, or SMS. Changes apply immediately across dashboard and API usage via the `template_id` reference.

## Overview

This endpoint allows you to update an existing push, email, or SMS template in your OneSignal app. Once updated, the changes are applied immediately and reflected across both the Dashboard and API when using the associated `template_id`.

Templates are updated using the same structure as when [creating templates](/reference/create-template).

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

To update a template, you must supply:

* Your **OneSignal App ID** found in [Keys & IDs](/docs/en/keys-and-ids).
* The **Template ID**

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***

## Channel-Specific Requirements

### Push Templates

* The `contents` property must use the `en` (English) key along with other languages you want to support.
* All [Push Notification Properties](/reference/push-notification) are valid.
* All platforms are enabled by default. To limit, explicitly enable desired ones (e.g., `isAndroid: true` disables iOS and Web).

### Email Templates

* Set `isEmail: true`
* Include `email_subject` and `email_body`
* All [Email Channel Properties](/reference/email) are supported.

### SMS Templates

* Set `isSMS: true`
* All [SMS Channel Properties](/reference/sms) are supported.

***


# Update user
Source: https://documentation.onesignal.com/reference/update-user

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}
Modify a user's properties.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint updates user-level properties for an existing user in your OneSignal app.

* To change a user's `identity` like `external_id` or custom [Aliases](/docs/en/aliases), use the [Create alias](/reference/create-alias) and [Delete alias](/reference/delete-alias) APIs.
* To manage a user's `subscriptions`, use the [Create Subscription by alias](/reference/create-subscription) or [Create user](/reference/create-user) APIs.

***

## How to use this API

You must supply an alias in the request path:

* `alias_label`: The type of identifier (e.g., `external_id`, `onesignal_id`, or a custom alias label).
* `alias_id`: The corresponding value for that label.

See [Users](/docs/en/users) and [Aliases](/docs/en/aliases) for more info.

***


# View an app
Source: https://documentation.onesignal.com/reference/view-an-app

GET /apps/{app_id}
View the details of a single OneSignal app

## Overview

Use this API to retrieve metadata and platform configuration for a single OneSignal app associated with your account. This includes app names, App ID, Subscription counts, timestamps, and push platform credentials (Android/FCM, iOS/APNS, Web Push, Safari), making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

***

## How to use this API

To retrieve your app, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View API keys
Source: https://documentation.onesignal.com/reference/view-api-keys

GET /apps/{app_id}/auth/tokens
View the details of all of your current app API keys (Rich Authentication Token) for a single OneSignal app.

## Overview

This API is helpful for auditing and managing the API keys (Rich Authentication Tokens) associated with an app. It returns metadata for each token, including:

* Token name and ID
* IP allow list mode and associated CIDR ranges (if any)
* Creation and last updated timestamps

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

***


# View apps
Source: https://documentation.onesignal.com/reference/view-apps

GET /apps
Retrieve a list of all OneSignal apps associated with your account, including key app details like name, App ID, subscription counts, and timestamps. Useful for managing multiple apps through the OneSignal API.

## Overview

Use this API to retrieve metadata for all OneSignal apps associated with your account. This includes app names, App IDs, subscription counts, and timestamps, making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

<Warning>
  This API is limited to return a maximum of 1000 Apps. If you need access to more, then you should store the `app_id` and `name` for each of your apps on your own server to look up with the [View an app](/reference/view-an-app) API to get data for each app separately. Also, if you need to delete apps, then you can provide the `app_id` and `name` to OneSignal Support and ask for these to be deleted.
</Warning>

***

## How to use this API

To retrieve your apps, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View player
Source: https://documentation.onesignal.com/reference/view-device

GET https://onesignal.com/api/v1/players/{player_id}

Retrieve a single player record (Subscription) data registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `player_id` | string | Yes      | The OneSignal ID of the device. |

***

## Query Parameters

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `app_id`  | string | Yes      | Your OneSignal App ID. |

***

## Headers

| Header          | Value                            | Required | Description                        |
| --------------- | -------------------------------- | -------- | ---------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal LegacyREST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players/player_id_string?app_id=your_app_id HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json{ theme={null}
  "id": "player_id_string",
  "identifier": "push_token_or_email",
  "session_count": 5,
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_os": "14.4",
  "device_type": 1,
  "tags": {
    "level": "10",
    "user_type": "free"
  },
  "last_active": 1625253300,
  "created_at": 1625249800,
  "invalid_identifier": false,
  "external_user_id": "user123"
}
```

### Response Fields

| Field                | Type      | Description                                             |
| -------------------- | --------- | ------------------------------------------------------- |
| `id`                 | string    | OneSignal player ID.                                    |
| `identifier`         | string    | Push token, email, or phone number.                     |
| `session_count`      | integer   | Number of sessions associated with this device.         |
| `language`           | string    | Language set on the device (e.g., "en").                |
| `timezone`           | integer   | Time zone offset in seconds.                            |
| `game_version`       | string    | Version of your app the device is running.              |
| `device_os`          | string    | Operating system version.                               |
| `device_type`        | integer   | Numeric code for platform (0 = iOS, 1 = Android, etc.). |
| `tags`               | object    | Custom tags set on the device.                          |
| `last_active`        | timestamp | Last time the user was active (Unix timestamp).         |
| `created_at`         | timestamp | When the device record was created.                     |
| `invalid_identifier` | boolean   | Whether the push token or identifier is invalid.        |
| `external_user_id`   | string    | Your internal user ID mapped to this device.            |

***

## Errors

* 400 Bad Request – Missing or invalid parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied for this app or resource.
* 404 Not Found – The specified player\_id does not exist.

***


# View players
Source: https://documentation.onesignal.com/reference/view-devices

GET `https://onesignal.com/api/v1/players?app_id={app_id}&limit={limit}&offset={offset}`

Retrieve up to 80,000 player records (Subscriptions) registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Query Parameters

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `app_id`  | string | Yes      | Your OneSignal App ID.                                 |
| `limit`   | int    | No       | Number of entries to return (max 300, default is 300). |
| `offset`  | int    | No       | Result offset for pagination.                          |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players?app_id=your_app_id&limit=100&offset=0 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json theme={null}
{
  "total_count": 6,
  "offset": 0,
  "limit": 300,
  "players": [
    {
      "id": "player_id_1",
      "identifier": "push_token_or_email",
      "session_count": 3,
      "language": "en",
      "timezone": -28800,
      "game_version": "1.0",
      "device_os": "15.0",
      "device_type": 1,
      "tags": {
        "level": "15",
        "user_type": "free"
      },
      "last_active": 1625253300,
      "created_at": 1625249800,
      "invalid_identifier": false,
      "external_user_id": "user123"
    }
  ]
}
```

### Response Fields

| Field                        | Type    | Description                                  |
| ---------------------------- | ------- | -------------------------------------------- |
| `total_count`                | integer | Total number of devices for the app.         |
| `offset`                     | integer | Current pagination offset.                   |
| `limit`                      | integer | Number of devices returned in this response. |
| `players`                    | array   | List of device objects.                      |
| `players[].id`               | string  | Unique OneSignal player ID.                  |
| `players[].identifier`       | string  | Push token, email, or phone number.          |
| `players[].tags`             | object  | Custom tags set on the device.               |
| `players[].external_user_id` | string  | Your internal user ID.                       |

***

## Errors

* 400 Bad Request – Invalid query parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access not allowed for this app or key.

***


# View message
Source: https://documentation.onesignal.com/reference/view-message

GET /notifications/{message_id}?app_id={app_id}
View the details of a single message and the Outcomes associated with it.

## Overview

The View message API allows you to fetch data from a single push, email, or SMS message at a time. If you want to get multiple messages at a time, use the [View messages](/reference/view-messages) API. In most cases, you will likely want to use [Event Streams](/docs/en/event-streams) instead.

Currently this API does not provide Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are only **accessible 30 days after creation**; however, messages sent using the OneSignal dashboard are accessible for the app's lifetime.

See our [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and (after giving your users some time to interact with the message) pull the data if desired.

For example, if you send a message targeting the `include_aliases` parameter, the response will include the aliases you set. If you send with the `included_segments` parameter, then the response will only provide the segments you set. When targeting segments or filters, you can use the [Export audience activity CSV](/reference/export-csv-of-events) API to get the user event data.

To view outcome data for the message, you must include the `outcome_name` parameter with the name of the outcome you want to fetch, along with the accompanying aggregation type (.count or .sum), for example: `os__click.count`. For more information on outcome definitions, see [View Outcomes](/reference/view-outcomes).

***


# View messages
Source: https://documentation.onesignal.com/reference/view-messages

GET /notifications?app_id={app_id}&limit={limit}&offset={offset}&kind={kind}&template_id={template_id}&time_offset={time_offset}
View the details for a collection of messages.

## Overview

The View messages API fetches data for up to 50 push, email, or SMS messages at a time. To fetch a single message, use the [View message](/reference/view-message) API. In most cases, use [Event Streams](/docs/en/event-streams) instead.

This API does not return Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are **retained for 30 days** after creation; messages sent through the OneSignal dashboard are retained for the app's lifetime.

See [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

Use time-offset pagination for sequential pulls of all messages, and standard pagination for ad-hoc queries. For ETL or bulk export pipelines, use [Event Streams](/docs/en/event-streams) instead.

Filter results to a specific message kind or template using the `kind` and `template_id` query parameters. Both filters work with either pagination style.

### Optimized pagination with time offset

To efficiently retrieve all available messages for an app, use `time_offset`-based pagination. When `time_offset` is specified, the sort order changes from descending to ascending — the oldest messages appear first based on the [`send_after` date](/reference/create-message#send-after).

#### Accepted `time_offset` values

* ISO 8601 formatted timestamp — for example, `2025-01-01T00:00:00.000Z` (January 1, 2025, at 00:00 UTC).
* Opaque cursor token (Base64-encoded) — provided in the API response as `next_time_offset`.

<Steps>
  <Step title="Initial fetch">
    To fetch messages from a specific date onward, set `time_offset` to an ISO 8601 formatted timestamp. For example, to retrieve messages sent since January 1, 2025: `time_offset=2025-01-01T00:00:00.000Z`.

    <Note>
      * `time_offset` cannot be used with the standard `offset` parameter.
      * `time_offset` excludes messages that match the exact timestamp to avoid duplicates.
      * The response includes `next_time_offset`, a cursor token for the next page. No decoding required. For example: `"next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="`
    </Note>
  </Step>

  <Step title="Fetch additional pages">
    Use `next_time_offset` from the previous response as the `time_offset` value in the next request. For example: `time_offset=MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw==`.
  </Step>

  <Step title="Continue until completion">
    Repeat the request until an empty `notifications` array is returned, indicating all messages have been fetched.
  </Step>

  <Step title="Handling new messages">
    Because results are sorted ascending, new messages are added to the end. To resume fetching from where you left off, reuse the last `next_time_offset` that returned an empty response.
  </Step>
</Steps>

### Standard pagination

Use the `limit` and `offset` parameters to page through notifications for an app. The maximum result size is 50, and the default `limit` is `50`. Use `limit` to specify the result size and `offset` to increment by the limit value with each request.

For example, the first request uses `offset=0`, the second `offset=50`, the third `offset=100`, and so on.

Standard pagination is convenient for ad-hoc queries but degrades as the `offset` value grows. For sequential pulls of all messages, use time-offset pagination.

***


# View outcomes
Source: https://documentation.onesignal.com/reference/view-outcomes

GET /apps/{app_id}/outcomes?outcome_names={outcome_names}&outcome_time_range={outcome_time_range}&outcome_platforms={outcome_platforms}&outcome_attribution={outcome_attribution}
View and export push notification outcome metrics such as clicks, conversions, and custom events.

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

## Overview

Use this API to retrieve Outcome metrics associated with your OneSignal app, including push notification interactions and custom-defined events. Outcomes include data points like:

* **Clicks**: Number of users who clicked on a push.
* **Confirmed Deliveries**: Number of confirmed message deliveries.
* **Session Durations**: Number of sessions initiated.
* **Custom Events**: Actions like purchases, form submissions, or any event your app tracks via custom Outcome names.

For details on configuring custom Outcomes, refer to the [Outcomes documentation](/docs/en/custom-outcomes).

<Info>
  Outcomes are stored for approximately 30 days. To retain this data, you should regularly export it before it expires.
</Info>

***

## How to use this API

This API allows you to filter and aggregate Outcome data using several query parameters.

### `outcome_names`

Specify one or more Outcome names with an aggregation type suffix (`.count` or `.sum`).

**Default Outcome names:**

* `os__click.count` – Push notification clicks.
* `os__confirmed_delivery.count` – Confirmed deliveries.
* `os__session_duration.count` – Total sessions.

**Custom Outcome names:**

* You can track any custom event name (e.g. `Purchase`, `Signup`).
* If the custom name contains a comma, include only one name per request to avoid parsing issues.
* Example: `outcome_names=os__click.count,Purchase.count`

### `outcome_time_range`

The time range values can be one of the following:

* `1h` = (default) the last 1 hour data.
* `1d` = the last 1 day data.
* `1mo` = the last 1 month data.

### `outcome_platforms`

Maps to the subscription type property. Default is data from all platforms enabled for your OneSignal App.

| `device_type` | `type`      |
| ------------- | ----------- |
| 0             | iOSPush     |
| 1             | AndroidPush |
| 2             | FireOSPush  |
| 5             | ChromePush  |
| 8             | FirefoxPush |
| 11            | Email       |
| 14            | SMS         |
| 17            | SafariPush  |

Example: `outcome_platform=0` for iOS `outcome_platform=17,8` for Safari and Firefox.

### `outcome_attribution`

The way in which the Outcome occurred:

* `direct` = the Outcome occurred when the user interacted with the message. Some Outcomes only have `direct` attribution like `os__click` and `os__confirmed_delivery` because they only occur as the direct result of the message.
* `influenced` = the Outcome occurred within the Time Window of the message being sent, but the user never interacted with the message. See [Outcomes](/docs/en/custom-outcomes) for details.
* `unattributed` = the Outcome occurred without a direct or influenced attribute.
* `total` = (default) the sum of direct+influenced+unattributed.

***


# View segment
Source: https://documentation.onesignal.com/reference/view-segment

GET /apps/{app_id}/segments/{segment_id}
Retrieve details for a single segment by its ID, including subscriber count and optionally segment metadata and filters.

## Overview

Retrieve details for a single segment by its ID. By default, this endpoint returns only the subscriber count. Use the optional `include-segment-detail` parameter to also retrieve segment metadata and filters.

<Note>
  The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard.
</Note>

<Warning>
  **User-based segments not supported**: Segments containing message event or custom event filters (user-based segments) are not yet supported via this API. Attempting to fetch these segments will return a 400 error. These segments can only be managed through the dashboard UI.
</Warning>

***

## How to use this API

### Basic usage

By default, this endpoint returns only the subscriber count for the segment:

```json theme={null}
{
  "subscriber_count": 12345
}
```

### Include segment details

To retrieve full segment details including metadata and filters, set `include-segment-detail=true`:

```
GET /apps/{app_id}/segments/{segment_id}?include-segment-detail=true
```

This returns the subscriber count along with a `payload` object containing segment details:

<CodeGroup>
  ```json Simple filter theme={null}
  {
    "subscriber_count": 12345,
    "payload": {
      "id": "4414c404-56a3-11ed-9b6a-0242ac120002",
      "name": "Subscribed Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {
          "field": "session_count",
          "relation": ">",
          "value": "5"
        }
      ]
    }
  }
  ```

  ```json With AND/OR operators theme={null}
  {
    "subscriber_count": 5678,
    "payload": {
      "id": "5525d515-67b4-22fe-0c7b-1353bd231113",
      "name": "Engaged Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {"field": "session_count", "relation": ">", "value": "2"},
        {"operator": "AND"},
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "last_session", "relation": "<", "hours_ago": "24"}
      ]
    }
  }
  ```
</CodeGroup>

### Filters format

The `filters` array uses the **same format** as the [Create segment](/reference/create-segments) API. This means you can:

* Read filters from this endpoint
* Modify them as needed
* Use them directly with the [Update segment](/reference/update-segment) or [Create segment](/reference/create-segments) APIs

The array contains filter objects and operator objects:

**Filter object** - defines a condition:

| Field                   | Type    | Description                                                                                                                                         |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field`                 | string  | The filter type: `tag`, `last_session`, `first_session`, `session_count`, `session_time`, `language`, `app_version`, `location`, `country`, `email` |
| `relation`              | string  | The comparison operator: `>`, `<`, `=`, `!=`, `exists`, `not_exists`, `in_array`, `not_in_array`, `time_elapsed_gt`, `time_elapsed_lt`              |
| `value`                 | string  | The filter value (for most filter types)                                                                                                            |
| `key`                   | string  | The filter key (required for `tag` filters)                                                                                                         |
| `hours_ago`             | string  | Hours ago value (for `last_session`/`first_session` filters)                                                                                        |
| `radius`, `lat`, `long` | string  | Location parameters (for `location` filters)                                                                                                        |
| `unsupported_in_api`    | boolean | If `true`, this filter cannot be used with Create/Update segment APIs (see note below)                                                              |

**Operator object** - combines filters:

| Field      | Type   | Description                                                                        |
| ---------- | ------ | ---------------------------------------------------------------------------------- |
| `operator` | string | Either `AND` or `OR`. Filters connected with `AND` have higher priority than `OR`. |

<Warning>
  Some segments created via the dashboard UI may contain filter types not supported by the public API (e.g., `message_event`, `custom_event`). These filters will include `unsupported_in_api: true`. You cannot use these filters when creating or updating segments via the API.
</Warning>

### Payload fields

| Field         | Type           | Description                                                                         |
| ------------- | -------------- | ----------------------------------------------------------------------------------- |
| `id`          | string         | The unique identifier for the segment (UUID v4).                                    |
| `name`        | string         | The segment name (max 128 characters).                                              |
| `description` | string \| null | Human-readable description for the segment (max 255 characters). `null` when unset. |
| `created_at`  | integer        | Unix timestamp when the segment was created.                                        |
| `source`      | string         | The source of the segment: `default`, `custom`, or `quickstart`.                    |
| `filters`     | array          | Array of filter and operator objects that define the segment criteria.              |

***


# View segments
Source: https://documentation.onesignal.com/reference/view-segments

GET /apps/{app_id}/segments
Retrieve a list of segments associated with a specific OneSignal app. Useful for programmatically accessing segment metadata such as name, creation date, and status.

## Overview

Retrieve a list of segments associated with a specific OneSignal app. This is helpful when you want to access segment metadata programmatically instead of using the OneSignal Dashboard UI.

<Warning>
  This endpoint only retrieves existing segment metadata. It does not provide the segment filters or user data.
</Warning>

***


# View template
Source: https://documentation.onesignal.com/reference/view-template

GET /templates/{template_id}?app_id={app_id}
Retrieve the details of a specific message template in your OneSignal app using its template ID. This API returns the template content, target channel, and timestamps for creation and last update.

## Overview

This endpoint returns metadata and content for a single template, including:

* Template body/content
* Target delivery channel (e.g., push, email, SMS)
* Creation and last updated timestamps

This is useful for inspecting existing templates before using or updating them.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Required parameters:

* `app_id` (query param): Your OneSignal App ID.
* `template_id` (path param): The unique ID of the template.

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# View templates
Source: https://documentation.onesignal.com/reference/view-templates

GET /templates?app_id={app_id}&limit={limit}&offset={offset}
Retrieve a paginated list of message templates from your OneSignal app. This endpoint returns summary information for each template, including ID, name, creation, and update timestamps.

## Overview

Use this endpoint to retrieve a list of message templates associated with a specific OneSignal app. The response provides summary information only:

* `template_id`
* `name`
* `created_at`
* `updated_at`

<Note>
  This endpoint does **not** return full template content such as message bodies, channel properties, or delivery configuration. For detailed template data, use the [View Template](/reference/view-template) endpoint.
</Note>

***

## How to Use This API

### Required Parameters

* **`app_id`** (query param): The OneSignal App ID whose templates you want to retrieve.

### Optional Parameters

* **`limit`** (query param): Number of templates to return (default: `50`, maximum: `50`).
* **`offset`** (query param): Number of templates to skip. Use for pagination.

### Pagination Example

If your app has 125 templates and you're using the default limit of 50:

1. First request (first 50 templates):\
   `GET /templates?app_id={app_id}&offset=0`

2. Second request (next 50 templates):\
   `GET /templates?app_id={app_id}&offset=50`

3. Third request (final 25 templates):\
   `GET /templates?app_id={app_id}&offset=100`

Repeat the request while adjusting the `offset` until you've retrieved all templates.

***


# View user
Source: https://documentation.onesignal.com/reference/view-user

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}
Retrieve a user including aliases, properties, and subscriptions.

## Overview

* Use this API to retrieve a user's full profile, including identity aliases, user properties, and messaging subscription details across channels.
* This is helpful for verifying user data, debugging subscription issues, or syncing OneSignal user data with your internal systems.

For detailed concepts and guides, see [Users](/docs/en/users), [Subscriptions](/docs/en/subscriptions), and [Aliases](/docs/en/aliases) documentation.

## How to use this API

To look up a user, you must provide both an `alias_label` and an `alias_id`. In most cases, your `external_id` will serve as the `alias_label`, and its value will be passed as the `alias_id`. While you may use a custom alias, we strongly recommend setting and using the `external_id` as your primary user identifier for consistency across platforms.

To retrieve a user using their OneSignal ID, set the `alias_label` to `onesignal_id`. **Note**: When querying with any alias other than `onesignal_id`, authentication is required.

***


# Changelog
Source: https://documentation.onesignal.com/release-notes/changelog

Learn about the latest updates to OneSignal.

Follow along with updates across OneSignal. We're launching new features and improving our product all the time!

<Update label="June 18 2026">
  **AI-assisted SDK installation updated and expanded**

  * AI install prompts have been rewritten and expanded to cover Android, iOS, React Native, Flutter, and Web SDKs.
  * Paste a single ready-made prompt into your AI coding assistant (Cursor, Claude, Copilot, or similar) and the assistant installs the SDK, drops in initialization code, and configures push and in-app messaging automatically.
  * No deep development experience required — marketers and non-technical users can complete SDK setup in minutes.
  * Prompt instructions were revised to fix errors identified during internal testing, so generated integrations are more accurate.
  * Available to all new sign-ups with no enablement required; requires an AI coding tool and access to the app codebase.
</Update>

<Update label="June 15 2026">
  **Extended `in_array` and `not_in_array` relations to the Device Type filter**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `device_type` filter field. Use them to match against a comma-separated list of device types in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "device_type", "relation": "in_array", "value": "iOS,Android"},
    {"operator": "AND"},
    {"field": "device_type", "relation": "not_in_array", "value": "Email"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="June 15 2026">
  **RCS editor experience improvements**

  We've improved how you build and send RCS, giving you a more intuitive editor, clearer approval visibility, and a more graceful SMS fallback experience:

  * **See carrier approval status in settings.** Each sender resource's carrier approval status is now visible at **Settings > SMS > Senders**, so you can track where each carrier stands in the approval process without leaving the dashboard.
  * **Select a sender per RCS template.** In Templates you now choose a specific sender instead of relying on a single global default, improving how RCS sends within Journeys and giving you automations for multiple SMS use cases.
  * **A more intuitive editor.** The composer automatically shows the right editor for the selected sender — the RCS editor for senders with an RCS resource, and the SMS editor for SMS-only senders.
  * **Text only RCS.** A new Text only content type sends plain branded RCS text.

  When a sender gains an approved RCS sending resource, OneSignal automatically prefers RCS for existing automations on that sender, mapping your existing SMS content to RCS so there's no manual rework.

  Available for all customers contracted for RCS. See [RCS messaging](/docs/en/rcs-messaging) for details.
</Update>

<Update label="June 8 2026">
  **Segment editor improvements: multi-value filters, copy filters, and filter JSON**

  Building segments in the dashboard is now faster and more flexible:

  * **Match multiple values in one filter.** The Language, Country, App Version, and User Tag filters now support the "is any of" and "is not any of" relations, so you can match a list of values in a single filter instead of chaining several filters with OR.
  * **Copy filters and filter groups.** Duplicate an individual filter or an entire filter group from the editor to reuse its configuration without rebuilding it by hand.
  * **View and copy filter JSON.** Open the filter JSON panel to see the REST API representation of your segment's filters, then copy it to use directly in the [Create segment](/reference/create-segments) API.
</Update>

<Update label="June 4 2026">
  **Retired Alexa and Windows Phone 8.0 as Device Type filter options**

  The `Alexa` and `Windows Phone 8.0` values are no longer available for the Device Type filter when you create or edit a segment, in both the dashboard and the Create segment API. Selecting either value in the dashboard is no longer possible, and the API rejects them with a validation error.

  Existing segments that already use these values continue to evaluate and deliver as before. To save changes to such a segment, replace the retired Device Type filter first.
</Update>

<Update label="June 2 2026">
  **Extended `in_array` and `not_in_array` relations to tag and app version filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `tag` and `app_version` filter fields, in addition to the `country` and `language` fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"},
    {"operator": "AND"},
    {"field": "app_version", "relation": "not_in_array", "value": "1.0.0,1.0.1"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="May 11 2026">
  **Email BCC is now generally available**

  You can now add BCC (blind carbon copy) recipients to email sends, including templates used in journeys and messages sent via the API. Use BCC to archive customer-facing email to a shared inbox or compliance system, forward sends to third-party services, or keep internal stakeholders copied on transactional sends.

  * Available on all plan types.
  * Maximum of 5 BCC addresses per send.
  * Each BCC recipient counts toward the total email volume for that send (for example, 1,000 primary recipients with 1 BCC address = 2,000 sends).
  * BCC metrics are excluded from analytics.

  See [BCC emails](/docs/en/email-bcc) for setup and usage details.
</Update>

<Update label="May 12 2026">
  **Added `in_array` and `not_in_array` relations for country and language filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `country` and `language` filter fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "in_array", "value": "US,GB,CA"},
    {"operator": "AND"},
    {"field": "language", "relation": "not_in_array", "value": "es,fr"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="April 21 2026">
  **Manage custom aliases from the User Profile**

  You can now view, add, edit, and delete a user's custom aliases directly from the **Aliases** section on the User Profile **Overview** tab, without using the API.

  * Add an alias by entering a label (alias key) and value (alias ID), copy any alias value to the clipboard, edit a value, or remove an alias.
  * Each user supports up to 10 aliases, and alias labels and values can each contain up to 128 characters.
  * `external_id` and `onesignal_id` are reserved and can't be used as custom alias labels.
  * A user must have an External ID set before you can add custom aliases. External ID is still managed separately in the Profile section.

  See [Aliases](/docs/en/aliases) for more details.
</Update>

<Update label="April 17 2026">
  **Role-based access control (RBAC) is now generally available**

  Granular role-based access control has been rolled out to all customers, giving teams more flexibility to support least-privilege access patterns and manage permissions as they scale.

  * **New `team_member` org-level default role.** A baseline role for new users added to an organization.
  * **New `composer` app-level role.** Lets users create and edit messages, templates, segments, and journeys without sending, activating, or deleting content.
  * **Updates to `editor` and `viewer` roles.** Refined permissions for clearer separation of duties.
  * Available roles vary by plan type.

  See [Manage team members](/docs/en/manage-team-members) for the full breakdown of roles, permissions, and plan availability.
</Update>

<Update label="April 16 2026">
  **Light/dark mode toggle for HTML in-app message previews**

  You can now switch between light and dark mode directly in the dashboard when previewing HTML in-app messages, so what you see matches what your users will actually see.

  * A light/dark mode toggle is now available in the in-app message preview for HTML messages.
  * The preview no longer reflects your OS theme. It reflects the mode you select in the dashboard.
  * Previously, the preview always rendered using whatever theme your own computer was set to, with no indication that was the cause, so there was no reliable way to check dark mode designs from the dashboard.

  HTML in-app messages do not automatically get a dark mode. The message still has to be coded for it using `@media (prefers-color-scheme: dark)` styles. If your message doesn't include those styles, toggling to dark mode in the preview won't change how it looks.

  The toggle is available for HTML in-app messages only. Block-type in-app messages are not included in this release. Generally available for all customers using HTML in-app messages.

  See [Design your in-app message with HTML](/docs/en/design-your-in-app-message-with-html) for how to add dark mode support.
</Update>

<Update label="April 15 2026">
  **Standardized delivery metrics across all channels**

  Delivery metric terminology is now consistent across every messaging channel in OneSignal. All channels now share a unified delivery hierarchy: Audience → Sent → Delivered, with the same definitions everywhere. Labels have been aligned across delivery reports, journey reports, engagement trends, and CSV exports. The [Metrics Glossary](/docs/en/analytics-metrics-glossary) has been fully rewritten as the canonical reference for every metric definition.
</Update>

<Update label="April 10 2026">
  **Audience counts now show subscribed and unsubscribed breakdowns**

  The segment editor now shows both subscribed and unsubscribed counts for every subscription-based segment, with a per-channel breakdown across push, email, and SMS. Previously, only the opted-in (subscribed) count was visible.

  Additional improvements:

  * Counts always return within approximately 15 seconds. Exact counts are shown when possible; estimates are used when an exact count can't be calculated in time.
  * Estimates are clearly labeled: above 10,000 with a +/- margin of error (e.g. 140,000 +/- 5,000), and below 10,000 as a less-than value (e.g. \<4,800).
  * Estimates will never show 0 for a segment. Previously for segments with very small but non-zero membership, estimates could incorrectly show as 0.

  This release covers subscription-based segments. User-based segment improvements are coming later in Q2 2026.
</Update>

<Update label="April 7 2026">
  **Updated User Profile page**

  The User Profile page has been redesigned with a tabbed layout and several new management actions directly on the page:

  * Add and remove Subscriptions from a User
  * Search across a User's data tags
  * Perform more direct edits and admin actions without leaving the profile

  The previous profile view is still accessible from the **Actions** menu if you need it.
</Update>

<Update label="March 25 2026">
  **test users now apply at the User level**
  Marking a Subscription as a test user now automatically marks all Subscriptions for that User as test users, effectively creating a Test User.

  * Any new Subscriptions added to a Test User will automatically be marked as test users.
  * Test User is now a User-level property rather than a Subscription-level one.

  **OneSignal Server SDKs just got their first v5 stable release!**

  After a period of testing and iteration, v5 is now the default version users will get when installing any of our server SDKs. Here are the current versions included in this release:

  | Language | Version |
  | -------- | ------- |
  | Node.js  | 5.4.0   |
  | Go       | 5.3.0   |
  | Java     | 5.3.0   |
  | .NET     | 5.4.0   |
  | Rust     | 5.3.0   |
  | Ruby     | 5.3.0   |
  | Python   | 5.3.0   |
  | PHP      | 5.3.0   |

  This release pairs well with our recently refreshed Server SDK Reference, giving developers a solid starting point for integrating with the OneSignal API.
</Update>

<Update label="March 20 2026">
  **Audit Log Export is now in GA**

  * Customers can now export audit logs. Customers can export 2 days for free tier and up to 90 days with security and legal entitlement (either as individual SKU or enterprise plan).
  * Provides customers additional metadata details and allows them to filter through data locally for their own audits and consumption with their own tools.

  **Failed Reasons in Audience Activity for everyone!**

  * Free plan users can now see exactly why individual audience members failed to receive a notification — directly in the Audience Activity view.
  * When a notification fails, especially common when troubleshooting set up, free users had no way to know whether the problem was a bad token, an unsubscribed user, or a device issue — leaving them guessing and unable to fix anything. Now they get the same failure visibility paid users have, so they can debug and get set up properly.
  * Same data retention as audience activity (30 days)
</Update>

<Update label="March 17 2026">
  **Data Model Updates and Field Deprecations**

  To improve platform performance, strengthen data integrity, and reduce the risk of configuration errors, we are introducing several updates to the OneSignal data model.

  These changes will take effect **April 15, 2026.**

  **Field Limits**

  We are introducing limits on two user fields to improve consistency and prevent unexpected behavior.

  Existing records exceeding these limits will not be modified to avoid disrupting current data and operations.

  **External ID**

  * `external_id` values can contain up to 128 characters.

  **Aliases**

  * Each user can have up to 10 aliases.
  * Each alias key and value can contain up to 128 characters.

  **Field Deprecations**

  We are deprecating several legacy Subscription fields that are no longer actively used:

  * `amount_spent`
  * `rooted`
  * `bought_sku`
  * `app_interests`
  * `purchased_items`

  After April 15, 2026, these fields will no longer be available in:

  * Segment Builder
  * API requests
  * Event streams
  * Webhooks

  **Impact for Customers Using These Fields**

  If your implementation currently references any of these fields:

  **Segments:** Segments using these fields will be paused and labeled for your review.

  **Journeys:** Journeys depending on those segments will be archived.

  **Event Streams and Webhooks:** These fields will return empty values.

  **What You Need to Do**

  Most customers do not need to take any action.

  If your implementation relies on any of the deprecated fields, we recommend reviewing your segments and integrations before **April 15, 2026.**
</Update>

<Update label="March 6 2026">
  Email Address Validation is now available!

  * When email addresses are added to OneSignal, they're now validated at three entry points:
    * API: syntax check
    * CSV import: full validation including typo detection, MX record lookup, disposable email flagging, and role-based address detection\*
    * Bulk validation: same full checks, runs against addresses already in your audience
  * Free plans have syntax and typo checks.
  * Paid plans will have syntax, typo, MX, disposable email, and role based email address checks.

  See [Email Address Validation](/docs/en/email-address-validation) for more details.
</Update>

<Update label="March 4 2026">
  **Dashboard layout redesign has shipped!**

  * Panel-based layout. The old floating card approach has been replaced with flat panels. The side nav sits in a clean gray panel, and the main content in a white panel. This simplifies the look and feel and gives us a more modern aesthetic.
  * New global top bar. Breadcrumbs, the new Create menu, Help/Support links, and Upgrade button all live in a new sticky top bar that follows you on scroll.

  **Richer date context across the dashboard**

  Dates show up everywhere in OneSignal — denoting message creation, notification send times, user sessions, etc. — but it wasn't always clear which timezone you were looking at, or how recent something actually was. This came up in a discussion last week among the dashboard engineers.

  Now, hovering over a date in the following areas of the Dashboard shows a tooltip with three pieces of context at once: the time in your local timezone, the time in UTC, and a relative timestamp (like "2 days ago").

  Where you'll see it:

  * Message lists and indexes
  * Message reports
  * Message review modals before sending
  * User and subscription profiles

  This is enabled for all apps — no action needed. Just hover a date and it's there!

  **In-App Message library with new quickstarts!**

  We've shipped a library of professionally designed, ready-to-use in-app message templates — available now to all plans in the dashboard.

  What's in it: 7 categories of quick starts covering the most common IAM use cases: push soft prompts, promotions, onboarding flows, feature announcements, location prompts, spin-to-win, and notification preference centers.

  How to access: Dashboard → Messages → In-App → New In-App → OneSignal Quick Starts. No feature flag or backend enablement required — available immediately. (See demo for the full experience in product)

  Go from zero to a production-ready in-app message in minutes, without writing HTML from scratch!
</Update>

<Update label="March 3 2026">
  **Enhanced Snowflake Integration Now Available!**

  Key improvements include:

  * 15-minute sync intervals (down from 24 hours)
  * Selective event syncing so customers only export what they need
  * Self-service setup directly in the OneSignal dashboard
  * New events like in-app impressions, email bounced/received, and separated Live Activity events.
  * We've also added richer properties including Template ID, last active timestamp, and subscription status.

  Customers get near real-time data in their Snowflake instance with full control over what gets synced meaning faster insights. Selective syncing alone can dramatically reduce event volume (and spend) by letting them export only the events that they need.

  This moves from the legacy flat annual fee to our Event Streams pricing model. Customers pre-purchase an event volume tier, and that tier covers all destinations (Snowflake, BigQuery, Databricks, etc.).

  Live now for all customers. All new customers will automatically have access to this new integration. Existing legacy Snowflake customers have until August 1st to migrate to the new integration before deprecation. Both integrations can run in parallel during the transition so they can ensure parity/consistency, and we will be doing outreach to those affected shortly.

  See [Snowflake](/docs/en/snowflake) for more details.
</Update>

<Update label="February 26 2026">
  **Audit Logs API is now available**

  Enterprise customers (with Legal & Security package) can now programmatically access the same audit log data surfaced in the OneSignal dashboard — pipe it directly into their SIEM, compliance tooling, or internal security workflows.

  * Returns a time-scoped record of actions taken in their org — who did what, when, and from where
  * Filter by app, action type, actor, target, or IP address
  * Supports cursor-based pagination for large result sets

  See [Audit Logs API](/reference/list-audit-logs) for more details.
</Update>

<Update label="February 9 2026">
  Huawei Badge Parameter Support

  We now support app icon badges on Huawei (HMS) devices via both the API and dashboard.

  * What's new: Three new parameters on `Notification#Create`
    * `huawei_badge_class` — the app's launcher activity class name (required for badge)
    * `huawei_badge_set_num` — set the badge to an exact number (0–99)
    * `huawei_badge_add_num` — increment the badge by a specific amount (1–99)

  On the dashboard, you'll see a new Badge option under Send to Huawei Android with "Don't set" / "Set to" / "Increase by" options.

  * Good to know:
    * Setting `huawei_badge_set_num` to 0 clears the badge
    * If neither set nor add is specified, the badge increments by 1 by default
    * Huawei does not auto-clear badges when the app opens
</Update>

<Update label="January 29 2026">
  API Documentation Improvements

  * New API endpoint: [View Segment](/reference/view-segment) - Retrieve details of a specific segment by ID, including optional segment filter details.
  * New API endpoint: [Update Segment](/reference/update-segment) - Update an existing segment's name and/or filters programmatically.
  * Fixed JSON example formatting across multiple API reference pages for improved readability:
    * Segments API: view-segments, create-segments, delete-segments
    * Users API: create-user, view-user, update-user, delete-user
    * Subscriptions API: create-subscription, delete-subscription, transfer-subscription, unsubscribe-with-token, create-alias-by-subscription
</Update>

<Update label="January 26 2026">
  **Audit Logs are now available!**

  * Customers now have the ability to determine exactly what's happening across their OneSignal account. Audit Logs gives them a complete timeline of every action taken in their organization—who did what, when, and from where.
  * Track 50+ action types including:
    * Authentication events (login, logout, API key operations)
    * Message activity (notifications sent, canceled, A/B tests, Journeys)
    * Team changes (member added, role changed, removed)
    * Configuration updates (webhooks, segments, templates, integrations)
    * Billing & subscription events
  * Powerful filtering:
    * Search by team member email
    * Filter by action type, app, IP address, or item type
    * Custom date ranges with presets
    * Shareable filtered URLs—customers can collaborate with their team instantly
  * Deep visibility:
    * Expandable rows reveal 30+ fields: IP address, browser, location, correlation ID, API version, and more
    * Available at both App and Organization levels
    * Quick-access links from Journeys, Segments, Templates, Notifications, and more
  * Retention:
    * Legal & Security package: 90-day lookback
    * All other plans: 2-day lookback
  * Perfect for security audits, debugging, and understanding team activity at a glance.
</Update>

<Update label="January 9 2026">
  * Standardized time series for charts are now available for:
    * Event Streams and webhooks
    * Email delivery reports
    * SMS/RCS delivery reports
</Update>

<Update label="December 22 2025">
  * confirmed receipt Now Available On Engagement Trends
    * Customers with access to confirmed receipt can now see confirmed receipt on the Engagement Trends Time Series Chart.
    * This missing data was a common point of confusion for customers. They could see confirmed receipt & click through rate, but had no access to the total confirmed deliveries metric.
    * This additional data point gives customers confidence in the rates we're showing and helps with confusion on the difference between "delivered" and "Confirmed receipt" for push notifications.
</Update>

<Update label="December 12 2025">
  * New integration - Self-serve Snowflake data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake without going through customer support
    * The legacy Snowflake documentation remains available for existing implementations
</Update>

<Update label="December 8 2025">
  Live Activities in Event Streams & Integrations

  Live Activities Analytics provides two key capabilities to optimize customers' live activity strategy:

  1. Better Troubleshooting with confirmed receipt
     Gain visibility into whether devices actually received live activity updates. confirmed receipt tracking identifies delivery issues quickly to understand the true reach of live activities.
     Available in:

  * Individual message reports with per-device confirmation
  * Data exports to BI tools (through event streams and integrations)

  2. Deeper Engagement Insights with data exports to integrations & event streams
     Answer critical questions about how users interact with your live activities:

  * How many users engaged with my live activity over its duration?
  * When did users drop off?
  * What was the peak engagement time?
  * When did users click? (coming soon)

  Export live activity data to BI tools to analyze engagement patterns, optimize timing, and improve future campaigns.
</Update>

<Update label="December 5 2025">
  We've launched a new [Metrics Glossary](/docs/en/analytics-metrics-glossary) in our documentation. This resource provides a single source of truth for delivery metric definitions, helping both our team and customers understand our metrics consistently across dashboards, APIs, and exports.
  While we continue working toward unified terminology across all touch points, this glossary establishes clear mappings and definitions as they exist today, making it easier for customers to navigate our current analytics landscape.

  Custom Events in User Activity Timeline
  Custom events are now visible per User on their profile page in a dedicated tab. You can:

  * Filter by event type and event source
  * Filter by date, to any time window in the past. Only limiting factor is customer's own events retention window setting!
  * Expand each event to see the full payload
  * Click through to the events index to see that event type's config and full cross-user activity log

  This is important because:

  * It helps paint the complete picture of user activity. At a basic level, customers ask the question, "what's going on with this user?" and this helps answer it.
  * Especially useful for zoomed-in troubleshooting, auditing, what-happened analysis.
  * Please note: this will only be visible to customers in Custom Events early access, but will be available to all as they gain access to Custom Events
</Update>

<Update label="November 26 2025">
  UX Improvements Now Live

  1. Row-Level Linking
     You can now click anywhere on a table row to navigate to its destination, instead of having to click a specific cell. This makes navigation faster and more intuitive.
  2. Row Highlighting on Hover
     All tables now highlight the entire row on hover, helping users track data more easily and reducing visual strain when scanning wide tables.
  3. Improved Responsiveness
     The actions column has been narrowed to preserve horizontal space and is now right-aligned at the end of every table.
     It also features sticky, floating behavior — especially useful on smaller screens where horizontal scrolling is required.
     Some tables better truncate long text (e.g., lengthy message names) more effectively to maintain a clean layout.
  4. Refined Sorting UX
     Updated sort icons make the sort direction easier to interpret. Clicking anywhere on a column header now toggles sorting, improving ease of use.
  5. Unified Column Visibility Menu (Applies to Journeys, Users, Subscriptions)
     Tables with customizable columns now use a consistent, cleaner UI. Column changes update live as you toggle them.
  6. Updated Search Bar UI
     The search bar now aligns with design standards, featuring a left-aligned search icon, and a button that shows after typing for easy input clearing.
  7. Improved Pagination Formatting
     Pagination controls now use comma formatting for large numbers, improving scannability and readability.

  Core Component Update
  Many of the enhancements above come from migrating these tables to our core design system’s DataTable component. Sorting and filtering improvements for tables are consistently among the most requested features we receive. While these updates don’t introduce new sorting or filtering behavior yet, this component upgrade provides a more consistent experience for the functionality we have today, and does lay the foundation for Product teams to build more advanced table capabilities once those initiatives are prioritized.

  Coming Soon

  * Most tables across the Dashboard already include these improvements. A few remaining areas still require component updates before they can adopt the full set of new enhancements:
    * In-app index
    * Templates index
    * Audience activity table
    * A/B tests stats table
</Update>

<Update label="November 12 2025">
  UX Enhancement: Duplicate Templates Directly from the Editor
  In usability tests and dogfooding sessions, we noticed users often duplicate Journey nodes and then edit their templates. Previously, you had to exit the template editor and duplicate the template from the index view, an extra step that interrupted the workflow.
  Now, you can duplicate templates directly from the actions dropdown in the template editor. This small but meaningful improvement streamlines your editing experience and makes iteration faster. While our long-term goal is to enable template/content editing directly within Journeys, this enhancement is a great step in that direction.

  New Platform Filters for Engagement Trends & Subscription Trends
  You can now filter push engagement trend data by platform (iOS, Google Android, Huawei, etc.) to get a more granular view of performance across specific devices.
  In the spirit of our Analytics Consistency project, we've also brought this same filtering experience to Subscription Trends.

  Analytics Consistency: Standardized Time Series Chart Filters
  We're standardizing filter options across our time series charts, giving customers a consistent experience and clear access based on their plan.
  Key Changes:

  * All charts will share the same set of granularity and look back filters
  * Consistent casing and terminology used on all filters
  * Consistent upgrade experience for customers on plans with limited access
    As an example, Subscription Trends now supports a 2 year look back after the change.

  Charts where we've already rolled out these changes:

  * Engagement Trends
  * Subscription Trends
  * Global Outcomes
  * Push Delivery
  * All Template Reports
  * Coming Soon:
  * Email Delivery
  * SMS Delivery
  * Journeys Reports

  Look back access based on plan type:

  * Free: 30 days
  * Growth: 90 days
  * Professional: 1 year
  * Enterprise: 2 years
  * Custom: Up to 90 days (based on plan types above)
</Update>

<Update label="October 6 2025">
  Nice UXE on Journey Settings. We’ve updated the Journeys Settings Side panel to be more user friendly by adding a side navigation to keep each section in focus. This is in tandem with the eventuality of having more settings available to the user as we look towards Journey Goals, and more.  We will accompany this release with an intercom slide letting the user know we have updated the settings area as to give them a heads up due to the abrupt pattern change.

  Every Setting, In Focus: Journey Settings are now grouped and spotlighted, helping you zero in on each choice without distraction.
</Update>

<Update label="October 2 2025">
  Custom Events are now available to all customers on paid plans! You can now send custom events via our API or SDK, and use them to trigger actions in Journeys with your own event data.
</Update>

<Update label="September 21 2025">
  Customers can now pause a segment that's counting towards their segments entitlement even though it's only being used in an archived journey or paused IAM. We also made it even easier to pause segments, if the user wants to pause a segment, we'll help the user pause or archive the active IAMs or journeys stopping the user from pausing a segment.
</Update>

<Update label="September 9 2025">
  Deactivate email senders

  Deactivate email domains that are no longer in use or were set up incorrectly. This includes fallback handling for your email templates and scheduled sends to make sure you don't break them by removing a domain, just in case it was being used more widely than you anticipated.
</Update>

<Update label="August 29 2025">
  Personalize emails with real-time Data Feeds

  You can now use Data Feeds to pull live content from your APIs directly into emails at send time. No more static CSVs or preloaded tags — every message can include the latest account details, product recommendations, or order updates.

  Available in the email template composer for emails sent via Journeys, Data Feeds includes preview tools and error handling to keep sends smooth.

  👉 See how to set up [Data Feeds](/docs/en/data-feeds)
</Update>

<Update label="August 04 2025">
  You can now hold users in a Journey step until specific conditions are met before they move forward with the *Wait Until* action. This new feature allows you to:

  * Hold users at a step until they enter a segment or trigger a message event (such as a specific message being delivered, opened, or clicked).
  * Add multiple conditions and branch users based on whichever condition they meet first.
  * Set an expiration path that moves users forward or removes them from the Journey if none of the conditions are met within your chosen timeframe. This gives you greater flexibility and control over how users progress through your Journeys. Learn more: [Journeys Actions](/docs/en/journeys-actions)

  AI Composer Push Notifications
  You can now generate or improve push notification message copy using the AI message composer. This update helps you craft high-performing content without leaving OneSignal. When creating a new push notification, select AI-generated push button to get started. To improve existing copy, select “Refine” in the Title, Subject, or Message fields.

  New [Integrations](/docs/en/integrations) index page contains the following enhancements:

  * Filtering by type of integration
  * Filtering by Inbound/Outbound directions of data flow
  * Includes our new inbound DWH/Data ingestion options for custom events
</Update>

<Update label="July 07 2025">
  * Quickly identify and manage segments tied to campaigns
    * We’ve made it easier to clean up outdated segments.
    * Previously, you couldn’t delete a segment if it was tied to an In-App Message (IAM) or Journey, even if that campaign was paused or archived. Now, when you try to delete a segment, you’ll see a modal listing all IAMs and Journeys that are preventing deletion.
    * This helps you quickly locate and update the associated campaigns, so you can keep your workspace clean and organized without having to hunt through every Journey or IAM.
</Update>

<Update label="June 30 2025">
  * Segment users based on real message engagement
    * You can now create user segments based on how they interacted with previous messages across push, email, SMS and in-app.
    * This update adds a new Message Event filter that allows you to segment users based on events like email opens, push clicks, SMS failures, and more - without relying on tags or external tools.
    * Available on all paid plans.
    * See [Segmentation](/docs/en/segmentation#message-event-filters) for more details.
</Update>

<Update label="June 27 2025">
  * New documentation with Mintlify!
    * We've updated our docs!
    * New AI features and easier readability.
    * Updated API reference and openapi spec.
    * New Tutorials page with common use cases and step-by-step details to get you setup quickly!
</Update>

<Update label="June 18 2025">
  * Track In-App engagement trends alongside push, email, and SMS
    * Customers can now see In-App Message impressions, clicks, and click-through rates directly in the Engagement Trends chart. This update gives marketers a unified view of how users are interacting with all message types over time—including In-App—making it easier to spot trends, report on performance, and optimize messaging across channels.
    * With this update, In-App engagement data is now included alongside push, email, and SMS across all views in the Engagement Trends chart. Stats are grouped by day and support up to two years of data (depending on plan). This data is exportable via CSV just like other channels, and can be filtered to look at specific date ranges or message types.
    * This feature is available to all customers.
</Update>

<Update label="June 12 2025">
  * Unlock deeper email engagement insights with multi-link tracking
    * Customers can now track engagement on every individual link within their emails. This update gives customers a much clearer view into what content or messaging is working so they can improve email performance over time.
    * Previously, when customers included multiple links within an email, they could only view total click counts across all links. Now, they can see which specific links get the most engagement and how links perform inside journeys. This helps them refine content and messaging strategies.
    * Multi-link tracking is automatically applied to most emails created in the Drag & Drop or HTML editor. Link-level performance metrics will also be available for emails sent using a template and emails in a Journey.
    * This feature is available to all customers with access to email.
</Update>

<Update label="May 23 2025">
  * View and optimize message performance with Template Analytics
    * OneSignal customers can quickly assess how individual templates are performing across all messages, without needing to download and stitch together separate reports.
    * When users click into a template, they now land on a detailed analytics view showing Delivered, Unique Opens, Unique Clicks, and Unsubscribes. They can track performance over time, filter by platform, explore delivery breakdowns like Failed or Capped, and review a list of messages that used the template.
    * Template analytics is especially useful for:
      * Marketers who test and iterate on message content
      * Developers who need visibility into transactional message delivery
      * High-volume senders seeking scalable insights
    * Transactional visibility is a key differentiator that sets us apart from Firebase and other open source solutions. Customers can now answer questions like “How many Account Confirmation emails did I send last week?” or “What was the click-through rate on my Password Reset messages?”
    * Important note: For templates created before April 17, 2025, enhanced metrics are only available for messages sent after that date. Customers can use the “Show historical data” toggle at the top of the page to see earlier performance data.
    * The feature is live and available by default. Reporting history varies by plan:
      * Free: 30 days
      * Growth: 90 days
      * Professional: 1 year
      * Enterprise: 2 years
</Update>

<Update label="May 16 2025">
  * Add users manually from the dashboard
    * You can now create new users directly from the *Users* tab in your OneSignal dashboard using a simple form. This update makes it easy to manually add a user with an email address, phone number, or both without needing an SDK, API call or CSV upload.
    * This is especially helpful for quickly testing campaigns or adding users who aren’t yet in your system.
</Update>

<Update label="May 14 2025">
  * Track SMS link performance directly in OneSignal
    * Customers can now track SMS link performance directly in OneSignal without needing third-party tools like Bit.ly or custom UTM parameters. This feature gives our customers a more streamlined, built-in way to measure engagement and optimize messages faster, removing friction and helping drive better results from their SMS efforts.
    * When composing an SMS message, customers simply click “Insert Trackable Link” and enter the full URL they want to send users to. OneSignal automatically shortens the link using the 1sgnl.co domain so it fits within SMS character limits and can be tracked.
    * All SMS users will have access to trackable links as part of their existing plan.
</Update>

<Update label="May 07 2025">
  * Simplify message organization with easier label management
    * Now you can add labels to your messages to help you organize and manage them.
    * See [Labels](/docs/en/labels) for more details.
</Update>

<Update label="May 01 2025">
  * Template analytics
    * You can now view and optimize template performance from a centralized reporting view. Click into any message template to view detailed performance data across every message a template is used in.
</Update>

<Update label="Apr 25 2025">
  * Improved CSV Importer
    * **Real-time validation:** Get instant feedback on formatting errors before upload.
    * **Smart column mapping:** Easily align your CSV headers with OneSignal fields.
    * **Email suppression support:** Add or manage your suppression list directly in the file.
    * **Upload history:** View the status of your past imports for up to 30 days.
    * **Helpful templates:** Start quickly with a pre-built CSV example.
</Update>

<Update label="Apr 21 2025">
  * Fine-tune your Live Activities with new API parameters
    * You can now add more control, reliability, and speed to your Live Activities with three new parameters in the OneSignal API: - ios\_relevance\_score: Helps determine which Live Activity displays most prominently on iOS. - include\_aliases: Allows you to target individual users directly rather than relying on segment-based delivery. - idempotency\_key: Prevents the creation of duplicate Live Activities when retrying start requests if not using the OneSignal SDK.
</Update>

<Update label="April 14 2025">
  * New integration - Databricks data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Databricks. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Databricks, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="April 08 2025">
  * View opt-out status by sender and support transactional messaging even with marketing opt-outs
    * You can now see SMS opt-out status by sender, giving you better visibility and control when managing marketing and transactional messages.
    * With this update, you can:
      * View subscription status by individual sender for any phone number
      * Continue sending transactional messages (like OTPs or alerts) even if a user has opted out of marketing
      * Maintain deliverability and avoid carrier filtering by respecting opt-out preferences
    * This is especially useful if you manage separate senders for promotional and transactional use cases.
    * To access this feature, go to **Consent Management > Advanced Opt-out Settings** and turn off the setting that globally unsubscribes a user when they reply with an opt-out keyword.
    * *Note: This option is only available to customers using advanced opt-out settings for SMS.*
</Update>

<Update label="March 19 2025">
  * Easily find and select the right templates with visual previews
    * Quickly identify and select your email and in-app message templates with the new updated card view.
    * Instead of relying on template names alone, you can now see clear visual previews, making it easier to choose the right template at a glance.
</Update>

<Update label="March 12 2025">
  * Create users in OneSignal via HubSpot workflows
    * Keep your users in sync across HubSpot and OneSignal! With this new workflow action, you can now create users in OneSignal whenever a HubSpot workflow trigger fires. This enables you to queue up personalization details (such as Tags) and plan engagement strategies before a user even interacts with your mobile platform. Additionally, you can trigger an SMS or email via HubSpot while simultaneously creating a user in OneSignal—ensuring seamless and immediate engagement.
    * [HubSpot Documentation](/docs/en/hubspot)
  * Push preview accuracy improvements
    * As operating systems update, they often introduce new changes in their push designs.
    * We've updated our previews so they match latest and greatest push notification designs across iOS (18), Android (15), Windows (11), macOS (Sequoia). This ensures you see what your users will see when testing in OneSignal.
  * PII Masking of Emails and Phone Numbers
    * Protect user privacy and reduce compliance risks by masking personally identifiable information (PII) such as emails and phone numbers. With PII masking, your team can work securely while still analyzing campaign performance and sharing insights across teams.
    * OneSignal automatically masks phone numbers and emails in the dashboard and any data exported directly from the platform. However, PII masking does not currently apply to data accessed via API requests, external IDs, or Tags.
</Update>

<Update label="March 07 2025">
  * Verify & Lookup Phone Numbers
    * Sends the user a one-time verification code to ensure the customer owns the phone #
    * Confirms the phone number entered by a user at onboarding is valid
</Update>

<Update label="February 28 2025">
  * Added New Integration - [BigQuery Data Export](/docs/en/bigquery)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to BigQuery. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in BigQuery, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
  * Channel subscriber counts have moved
    * The counts of subscribed counts for each channel have moved from the dashboard to the Subscriptions page in OneSignal. Now you will see the number of *Subscribed* subscriptions for each channel at the top of the Subscriptions page under Audience to get an overview of audience reach per channel in the context of your subscriptions.
    * If you still wish to view this information on the Dashboard, you can filter your Subscriptions trends chart by channel.
</Update>

<Update label="February 14 2025">
  * Improvements to Keywords
    * We've made a couple of improvements to our SMS keywords.
      * Segment by subscription status when sending a keyword to encourage converting your customers who are not yet subscribed into opting in to your SMS marketing messages
      * Setup an auto-responder for unrecognized keywords
</Update>

<Update label="February 12 2025">
  * New Engagement Analytics on the OneSignal Dashboard

    * Are you curious to learn more about how your end users engage with the messages you send from OneSignal? Head to your Dashboard to see the new Engagement Trends report.
    * With this report you will gain insight into how users engage with your messages across Push, Email, and SMS. Track click-through-rate, unsubscribes, and monitor trends over time to refine your messaging strategy and optimize communication frequency. This comprehensive report consolidates data from all message types (Dashboard, API, Journeys) for a clearer view of performance. Now available in your OneSignal dashboard!

    <Frame>
      <img alt="New Engagement Analytics on the OneSignal Dashboard" />
    </Frame>
</Update>

<Update label="January 29 2025">
  * Sort segments by Last edited, Created at and more
    * Finding and managing your segments just got easier!
    * You can now sort segments by Last edited, Created at and more.
      * This update is especially valuable for customers who:
        * Maintain numerous segments
        * Frequently update their segment configurations
        * Need to identify and clean up outdated segments
        * Want to quickly find recently modified segments
</Update>

<Update label="January 27 2025">
  * Email Senders (Multi-Domain Sending)
    * Create distinct senders for different types of communications:
      * Keep your marketing campaigns separate from crucial transactional emails
      * Maintain different brand voices for various product lines
      * Optimize sender reputation for each type of communication
      * [Email Senders](/docs/en/senders)
  * Improved In-app Message Analytics for Event Streams
    * We've added a new In-app Message Analytics for Event Streams.
</Update>

<Update label="January 21 2025">
  * Email Intelligent Delivery
    * We've added intelligent delivery to email.
    * Transform your email engagement with OneSignal's latest breakthrough: Intelligent Delivery. This powerful new feature automatically determines the optimal time to reach each individual user, maximizing your email campaign's impact.
    * Our algorithm continuously learns from:
      * User open patterns
      * Click-through behavior
      * Real human interactions (excluding bot activity)
</Update>

<Update label="January 16 2025">
  * Retirement of Automated Message for Free apps
    * Automated Messages are no longer supported and the feature has been retired in the free plan. Paid apps will continue to have access to this feature until further notice.
    * Active automated messages will remain live and continue functioning as expected. However, you can no longer create new automated messages, or reactivate paused automated messages. To build new automated sequences and enhance your campaigns, we recommend using [Journeys](/docs/en/journeys-overview).
</Update>

<Update label="January 15 2025">
  * Customize how your users re-enter split branches
    * Now you can customize how your users re-enter split branches. This feature is available for all Journeys.
    * [Journey Entry Triggers](/docs/en/journeys-actions)
  * Improving New Message Experience
    * We improved the new message experience by adding a library of templates (get inspiration for your next push, in-app, email, or SMS), or quickly start from a template you've made, or a previous message.
</Update>

<Update label="January 03 2025">
  * message.url - New Push Event Stream Property
    * `message.url` is now a supported property for push events. It enables the retrieval of the launch URL directly from your event stream payload.
</Update>

<Update label="December 24 2024">
  * Journeys Multi-split Branching
    * Now you can set up more personalized paths in your Journey. Create up to 20 branches to test channels, content, timing, ordering, and more. Assign different weights to each branch, or easily distribute audiences evenly across all branches. See how different paths perform against each other or against a control group.
</Update>

<Update label="December 20 2024">
  * WordPress Plugin v3
    * We've upgraded our Wordpress Web Push plugin to v3+. What's changed:
      * Upgrades the OneSignal Web SDK from version 15 to 16.
      * Setup more new prompts within the OneSignal dashboard, including the following. No custom code is required anymore to configure these.
        * Category Prompt
        * Email/Phone Slide Prompt
        * Custom Link Prompt.
      * When publishing a new post, check the "Send notification when post is published" box to send a push notification.
      * Choose which audience segment should receive notifications for each post.
      * Web Topics are included by default.
      * Send to mobile app subscribers, with an option to direct them to a different URL (Deep Link).
</Update>

<Update label="December 11 2024">
  * Improved Logs in Event Streams
    * We've improved the Event Streams feature to make troubleshooting simpler and faster. Now, you’ll find dedicated tabs for successful and failed events, making it easier to spot issues at a glance. Clear empty states show when there’s no data in either tab, and updated messaging ensures you know the logs display a sample of your data.
  * SMS Keywords
    * We've added keywords for SMS. Keyword engagement enables quick, two-way communication, enhancing personalization, accessibility, and user satisfaction. It drives conversions and higher engagement with your subscribers. Add a data tag to the keyword, and segment based on their preferences to send more targeted SMS.
  * Quickstart Segments

    * We are thrilled to launch three new segment templates designed to help you hit the ground running with proven strategies:
      * First-Time audience
      * Regional audience
      * Custom Audience based on tags
    * Our analysis of 6.3 billion message deliveries uncovered powerful insights. These templates are built to help you:
      * Create high-performing segments from day one.
      * Use proven filter combinations that drive higher engagement.

    <Frame>
      <img alt="Quickstart Segments" />
    </Frame>
</Update>

<Update label="December 02 2024">
  * Email Quickstart Templates
    * We've added a library of quickstart templates for email. Explore our library of professionally crafted email templates, designed to inspire your creativity and elevate your email campaigns. Use them as a starting point to create impactful messages that drive conversions and engage your audience effectively.
</Update>

<Update label="November 27 2024">
  * Scheduling Journeys
    * Now you can schedule Journeys to send at a specific time. This feature is available for all Journeys.
  * Settings Overview Page
    * Now you can access and manage all your settings in a centralized setting overview page. Platform-specific settings have been reorganized under their relevant channels for better clarity.
</Update>

<Update label="November 20 2024">
  * Bulk Archive and Delete Journeys

    * Now you can bulk archive or delete Journeys from the Journeys index. Select up to 20 Journeys, and then choose an action you'd like to take to clean up Journeys you're no longer using.

    <Frame>
      <img alt="Bulk Archive and Delete Journeys" />
    </Frame>
</Update>

<Update label="November 06 2024">
  * Improved Export for Global Outcomes
    * We've improved the export for Global Outcomes to include more data and make it easier to use in your reporting.
  * Preview allows you to preview the content of a message and can be very helpful when you have a message with personalization (i.e. Tags, dynamic content, custom data). With preview, you can preview content from a specific test user's perspective, or with example custom data.
  * Settings for Email & Side Navigation Updates
    * In the side navigation, you can now easily see your Push, SMS, and Email settings. What was once "Messaging" is now "Push" settings, and SMS and Email Settings will take you directly to your channel's settings.
    * For email, we've created a dedicated place to manage your email provider and senders. If you are a OneSignal mail user, you'll also be able to see your reputation and suppression lists here.
  * SMS Usage
    * We've added SMS Usage in the Usage page. We've also added a breakdown so you can see the message type, and a breakout by inbound and outbound. You may see an unknown country if a segment failed to send.
</Update>

<Update label="October 02 2024">
  * Add Notes on your Journeys
    * Now you can add notes to the steps of your Journeys to keep reminders and more effectively collaborate and share information with your team. This feature is available for all Journeys.
</Update>

<Update label="September 27 2024">
  * New Quickstart Journeys
    * We've added a new Quickstart Journeys to help you get started with Journeys. This feature is available for all Journeys.
  * SMS Text-to-Subscribe
    * It's now easier to set up double opt-in and text-to-subscribe phone number collection experiences for your customers!
</Update>

<Update label="September 12 2024">
  * Confirmed Click-Through-Rate (CCTR) metric

    * We have added a new metric to measure the CTR using confirmed receipt. Confirmed Click-Through-Rate (CCTR) is measured by (total clicks/confirmed delivered) \* 100%

    <Frame>
      <img alt="Confirmed Click-Through-Rate (CCTR) metric" />
    </Frame>
</Update>

<Update label="September 06 2024">
  * Export your Subscription Trends
    * Now you can export the data from your Subscription Trends report as a CSV. If you apply filters to the report, OneSignal will export based on the filters you've applied so that you can fine-tune the data that you use to evaluate your messaging audience.
</Update>

<Update label="August 05 2024">
  * Email Saved Rows
    * Saved Rows are reusable content blocks that help streamline email creation and management. Many companies, especially those that have a lot of templates, prefer to use saved rows in their emails for consistency and to save time. Saved Rows are easily attached to new emails so you don't have to create the same information from scratch each time. And when things change, you just have to update the saved row, and your updates will automatically sync across all campaigns that have that saved row attached.
    * Common use cases include:
      * headers (logo, slogan)
      * footers (company details, social media links, mailing addresses)
      * disclaimers
      * other elements that are used across multiple campaigns
    * You can now save Email Drag-and-Drop rows to use across many Campaigns or Templates. These re-suable **Saved Rows** make it easy to sync updates across many emails at once. Click on the **Rows** tab of a Drag-and-Drop email, to view your **Saved Rows**. To save your first row, click the save icon in the edit, in the top right corner of the row.
    * We recommend you set up all of your templates to use saved rows for your header and footer so that you need to update the branding or content; you only have to make those edits once.
</Update>

<Update label="July 30 2024">
  * Journeys now target anonymous users
    * Now, Journeys do not require External IDs to be set on subscriptions. Instead, Journeys will target your entire user base within OneSignal, including anonymous users. We recommend still configuring External IDs to identify individual users who have subscribed to multiple channels.
</Update>

<Update label="July 25 2024">
  * Have more visibility into SMS unsubscribes, resubscribes, and help keywords
    * We now make it easier to manage your Consent Keywords within Onesignal. Reach out to support if you'd like to update the default consent keywords and replies.
</Update>

<Update label="July 19 2024">
  * Email Reply-to field now supports custom properties
    * Now you can use [Message Personalization](/docs/en/message-personalization) within the `reply-to`field on an email. This allows you to direct message replies to the right inbox and can be helpful if you are sending from different brands or across different countries.
</Update>

<Update label="July 16 2024">
  * Push Failures and Unsubscribes in Audience Activity
    * Obtain a list of subscriptions that have faced errors - failures or unsubscribes, for a specific push notification in the push report page.
</Update>

<Update label="July 03 2024">
  * Integrations: OneSignal Message Events can be sent to Twilio Segment
    * Customers can now select and send message events from OneSignal to sync back to their Twilio Segment account, making the Segment integration bidirectional.
  * Use Audience Activity for Live Activities to get a list of recipients
    * Get a list of subscriptions that successfully or failed to receive a Live Activity on a Live Activity report page, which is accessible through the Delivery - Sent Index. This list can be exported as well.
</Update>

<Update label="June 06 2024">
  * In-app message audience activity
    * In the report page of an in-app message, you can now see which mobile subscriptions viewed (impression) or clicked on an in-app message. Audience activity is available for 30 days from the time the message is displayed
</Update>

<Update label="May 15 2024">
  * FCM Expired Tokens > Increased Android Unsubscribes
    * On May 15, 2024, Google's FCM service will start to expire stale push tokens for devices that have been inactive for more than 270 days. You may see a spike in Android unsubscribes when sending notifications due to this change. Don't panic! These are devices that have not been online in over 270 days and are part of Google's [Best practices for FCM registration token management](https://firebase.google.com/docs/cloud-messaging/manage-tokens). If the device does come back online and opens your app, OneSignal will automatically resubscribe them to push if they were previously subscribed already.
    * See [FCM Expired Token FAQ](/docs/en/fcm-expired-token-faq) for more details.
</Update>

<Update label="April 29 2024">
  * Configure more granular Frequency Capping rates for Push
    * Push notifications can now be capped at a rate of x notifications per any time frame (less than 1 week). Navigate to Settings > Messaging > Push Frequency Capping > Custom (in the time dropdown) to view these settings.
    * Read [Frequency Capping Documentation](/docs/en/frequency-capping) for more details.
</Update>

<Update label="April 11 2024">
  * Added Android Live Notifications
    * Android's Live Notifications deliver live, dynamic content in notifications to enhance user engagement and app interactivity. This is a feature similar to iOS's Live Activities feature (introduced with iOS 16), but uses its own set of tools and APIs that enable similar functionalities.
    * See [Android Live Notifications](/docs/en/android-live-notifications) for more details.
  * Major improvements to Android SDK
  * Push to start Live Activities
    * Live Activities can now be launched on a user's screen when the mobile app is in the background (app is not open). Live Activities can both be started and updated by a remote push notification.
    * [How to start a Live Activity with a remote push notification](/docs/en/live-activities)
</Update>

<Update label="April 01 2024">
  * Added Audience Activity reports for Journeys
    * We have added Audience Activity reports for Journeys so you can get a closer look at which subscriptions were sent messages during a Journey. To view this report, click into a message report on your Journey. [Learn more here](/docs/en/journeys-analytics#audience-activity).
</Update>

<Update label="March 18 2024">
  * Added a new Setup guide for Analytics
    * We have added a new Analytics Setup guide to our product documentation detailing how to track Confirmed Deliveries and set up Custom Outcomes with support from your development team.
</Update>

<Update label="March 12 2024">
  * Mobile SDK Updates
    * We recommend updating to the latest SDK versions listed below to benefit from critical bug fixes, stability improvements, and new features. These updates include key enhancements across all platforms, including iOS 5.1.3 and Android 5.1.6, which improve concurrency safety, crash resilience, and background thread handling. The updates also include important API adjustments like more accurate property handling in the `PushSubscriptionState`.
</Update>

<Update label="February 16 2024">
  * Journeys is now available on the Growth plan
    * Journeys is now available on the Growth plan. This means you can now create and manage Journeys with up to 100,000 users.
    * See [Journeys](/docs/en/journeys-overview) for more details.
</Update>

<Update label="February 12 2024">
  * Added Auto Warm Up
    * We have added a new feature that allows you to automatically warm up your app when a user opens it. This feature is available for all OneSignal customers.
    * See [Email Warm Up](/docs/en/email-warm-up) for more details.
</Update>

<Update label="February 02 2024">
  * Journeys has easier targeting based on user activity
    * We've added support for Segments with time-based rules (e.g., first session, last session, etc.) and also simplified targeting inactive users. Now you can target your inactive users by including a segment based on last session behavior.
  * Email: Schedule Sends Across Different Timezones
    * Email campaigns can now be scheduled to send across different timezones. This feature is available for all OneSignal customers.
</Update>

<Update label="January 30 2024">
  * Email now supports One Click Unsubscribe
    * Inbox Service Providers (ISP) like Gmail, Outlook, iOS Mail, and Yahoo! Mail, AOL, and Verison Mail require senders to provide a One Click Unsubscribe option. The unsubscribe button is rendered at the discretion of the ISP based on sending criteria, which may include a daily sending volume greater than 5,000 emails.
</Update>

<Update label="December 18 2023">
  * Filter your messages with labels
    * Now you can filter your messages with [labels](/docs/en/labels). This feature is available for all OneSignal customers.
  * CSV Importer can now update properties
    * CSV Importer for email now enables updates to user properties `language`, `country`, and `timezone_id`.
  * Send more personalized messages and multi-language emails
    * [Dynamic Content Documentation](/docs/en/dynamic-content)
</Update>

<Update label="December 14 2023">
  * All OneSignal apps now belong to an Organization
    * We have added a new feature that allows you to manage your OneSignal apps within an Organization. This feature is available for all OneSignal customers.
    * See [Apps, Orgs, and Accounts](/docs/en/apps-organizations)
  * Journeys now has better analytics
    * We've added a new Journeys Report. See [Journeys Analytics](/docs/en/journeys-analytics) for more details.
</Update>

<Update label="November 22 2023">
  * Removed Journey Notifications from Delivery Reports and the View Notifications endpoint
</Update>

<Update label="October 04 2023">
  * Added new integration - [Snowflake](/docs/en/snowflake)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Snowflake, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="September 27 2023">
  * You can now save and continue
    * Changed the default option for saving a message to save work without exiting the message.
</Update>

<Update label="September 13 2023">
  * Added the ability to adjust the default padding for IAM blocks
    * Learn more about [IAM blocks](/docs/en/design-your-in-app-message)
  * Added the ability to edit entry triggers and re-entry rules for live Journeys
    * Learn more about [Journey entry triggers](/docs/en/journeys-overview)
</Update>

<Update label="September 05 2023">
  * Added ability to create multi-language push messages by pasting your CSV
    * Learn more about [Multi-language messages](/docs/en/multi-language-messaging)
  * Added new "Editor" role permissions
    * Learn more about [Managing team members](/docs/en/manage-team-members)
  * Added enhanced Journey message stats and reports.
    * Learn more about [Journey message stats and reports](/docs/en/journeys-analytics)
</Update>

<Update label="September 01 2023">
  * Added a new feature to forward email templates to an app
    * Learn more at [Email Template Forwarding](/docs/en/email-template-forwarding)
  * Added FCM v1 API support for Android Push Notifications
    * Learn more about [Android Firebase credentials](/docs/en/android-firebase-credentials)
</Update>

<Update label="August 15 2022">
  * Android 13 changes
    * Android 13 introduces a runtime notification permission, meaning users must opt in to receive push notifications. Apps targeting Android 13 must explicitly prompt for permission at a time of their choosing, or the system will display the permission prompt automatically on first launch—often resulting in lower opt-in rates.
    * See [Android 13 Push Notification Developer Update Guide](/release-notes/android-13-push-notification-developer-update-guide) or our [Prompt for Push Permissions](/docs/en/prompt-for-push-permissions) guide for details.
</Update>


# SDK Releases
Source: https://documentation.onesignal.com/release-notes/sdk-releases

View the latest OneSignal SDK releases and updates.

## Mobile

<SdkReleasesIframe />

## Web

<SdkReleasesIframe />

## Server

<SdkReleasesIframe />

## Plugins

<SdkReleasesIframe />


# Add a player
Source: https://documentation.onesignal.com/reference/add-a-device

POST `https://onesignal.com/api/v1/players`

Register a new Subscription (aka player) to one of your OneSignal apps.

<Warning>
  This is a Legacy API. Use [Create User](/reference/create-user) or [Create Subscription](/reference/create-subscription) instead.
</Warning>

***

## Headers

| Header          | Value                     | Required | Description                      |
| --------------- | ------------------------- | -------- | -------------------------------- |
| `Content-Type`  | `application/json`        | Yes      | The content type of the request. |
| `Authorization` | `Basic YOUR_REST_API_KEY` | Yes      | Your OneSignal REST API key.     |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                                |
| -------------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                                     |
| `device_type`        | integer | Yes      | Device platform: 0 = iOS, 1 = Android, 2 = Amazon, 3 = Windows Phone, etc. |
| `identifier`         | string  | No       | Push token, email address, or phone number.                                |
| `language`           | string  | No       | Language code (e.g. "en").                                                 |
| `timezone`           | integer | No       | Time zone offset in seconds.                                               |
| `game_version`       | string  | No       | Version of your app.                                                       |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                                         |
| `device_os`          | string  | No       | Operating system version (e.g., "13.3").                                   |
| `ad_id`              | string  | No       | Advertising ID.                                                            |
| `sdk`                | string  | No       | OneSignal SDK version (e.g., "050201" for 5.2.1).                          |
| `session_count`      | integer | No       | Number of times the user has used the app.                                 |
| `tags`               | object  | No       | Custom tags as key-value pairs.                                            |
| `external_user_id`   | string  | No       | Your system's user ID for this device.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc.                 |

***

## Example Request

```json theme={null}
POST /api/v1/players HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "device_type": 1,
  "identifier": "abcdef123456",
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_model": "Pixel 4",
  "device_os": "12",
  "ad_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sdk": "050401",
  "session_count": 5,
  "tags": {
    "user_type": "free",
    "level": "10"
  },
  "external_user_id": "user123",
  "notification_types": 1
}
```

***

## Response

```json theme={null}
{
  "id": "Subscription_id_string"
}
```

## Errors

* 400 Bad Request – Invalid parameters or missing required fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Not allowed for your account type or plan.


# Cancel message
Source: https://documentation.onesignal.com/reference/cancel-message

DELETE /notifications/{message_id}?app_id={app_id}
Stop a scheduled or currently outgoing message.

## Overview

The Cancel message API can be used to stop scheduled messages from being sent. It does not delete or remove the message from the app. If a message is in the process of sending, then canceling it may not fully prevent all targeted users from receiving it.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users, scheduling the message in the future with `send_after`. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and use this API to cancel sending the message to the user if not needed anymore.

If you need a way to remove a notification already sent to a user, see [Remove notifications & TTL](/docs/en/push).

***


# Copy template to another app
Source: https://documentation.onesignal.com/reference/copy-template-to-another-app

POST /templates/{template_id}/copy_to_app?app_id={app_id}
Create a duplicate of a template in another app. The new template will be completely separate from the original (including having a new template_id) but will be created with all the same content.

## Overview

This API allows you to copy a template from one app (`app_id`) to another (`target_app_id`). The duplicated template will have the same content as the original, but a new unique `template_id`.

<Note>
  If you are trying to copy an email template, we also have an [Email Template Forwarding](/docs/en/email-template-forwarding) feature that does not require an API call.

  Both options support HTML and Drag & Drop email templates.
</Note>

***

## Requirements

* **Organization Membership:** Both the `app_id` and `target_app_id` must belong to the same [Organization](/docs/en/apps-organizations).
* **Authorization Required:** You must use your [Organization API key](/docs/en/keys-and-ids#organization-api-key), not an app-level REST API key.
* **Permissions Note:** Your user must have admin-level access to both the source and target apps. If not, the request will fail with a "permission denied" error.

***

## Parameters

* `template_id` (path param): UUID of the template to be copied.
* `app_id` (query param): ID of the app where the original template exists.
* `target_app_id` (body param): ID of the app where the template will be duplicated.

***

## How to Use

### 1. Locate the Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

### 2. Get App IDs

Refer to [Keys & IDs](/docs/en/keys-and-ids) to find your `app_id` and `target_app_id`.

***

## Response

The response will include:

* The new `template_id` for the copied template
* Confirmation of successful creation
* Any warnings if applicable (e.g., limited fields copied)

***


# Create or update alias
Source: https://documentation.onesignal.com/reference/create-alias

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Create or update one or more user aliases when you already know an existing alias. This API performs an upsert on the user’s identity object—either adding new aliases or updating existing ones.

## Overview

Use this API to manage user aliases by providing one known alias (such as `external_id`, `onesignal_id`, or a custom alias) and specifying additional aliases to add or update.

This endpoint focuses solely on the `identity` object. If you need to fully create a user with subscriptions and properties, use the [Create user](/reference/create-user) API instead.

<Note>
  * If an alias with the same `alias_label` already exists for the user, it will be updated. If it doesn’t exist, a new alias will be created.
  * Want to use a subscription instead of an alias to identify the user? Use [Create alias (by subscription)](/reference/create-alias-by-subscription).
</Note>

See also:

* [Users](/docs/en/users) – for details on OneSignal ID and External ID
* [Aliases](/docs/en/aliases) – for setting and managing custom aliases
* [Delete alias](/reference/delete-alias) – for removing aliases

***

## How to use this API

To identify the user:

* Use `alias_label` for the type of alias you know (e.g., `external_id`, `onesignal_id`, or a custom alias)
* Use `alias_id` for the value of that alias

<Note>
  We strongly recommend setting the `external_id` as your primary user identifier. This can be done through our frontend SDK's login method when a user signs in to your app or website. It helps OneSignal associate the user's push, email, and SMS subscriptions to a unified user identity.
</Note>

Changes to the identity object take effect immediately upon request.

Alias keys (`alias_label`) and values (`alias_id`) are each limited to **128 characters**. A user can have up to **10 custom aliases** total.

***


# Create alias (by subscription)
Source: https://documentation.onesignal.com/reference/create-alias-by-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Create or update an alias for a user using a known subscription ID.

Create or update an alias for a user using a known subscription ID.

# Overview

Use this API to add or update aliases associated with a user when you only know at least one subscription ID. This API is handy for scenarios where the user's identity is unknown, but a subscription is available.

To remove an alias, see [Delete alias](/reference/delete-alias) API.

***

# How to use this API

You must know the `subscription_id` of the subscription that belongs to the user in which you want to update. Subscription IDs are UUIDs generated by OneSignal and cannot change. See [Subscriptions](/docs/en/subscriptions) for details.

This endpoint performs an upsert—if the user already has an alias with the specified alias label, it gets updated; otherwise, a new alias will be created.

The request body must include an identity object containing one or more aliases to be created or updated.

The OneSignal ID is read-only and used only for fetching. See [Users](/docs/en/users) for details.

Aliases are updated immediately upon request.

***


# Create an app
Source: https://documentation.onesignal.com/reference/create-an-app

POST /apps
Programmatically create a new OneSignal app via the REST API. This guide explains required fields, supported platform configurations (Web, Android, iOS), and how to properly authenticate using your Organization API key.

## Overview

Use this API to programmatically create a new OneSignal app. This is useful for automating app setup, particularly when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need to Base64 encode your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns):

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates):

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Create API key
Source: https://documentation.onesignal.com/reference/create-api-key

POST /apps/{app_id}/auth/tokens
Use the OneSignal API to create a new Rich Authentication Token (App API Key) for a specific app. This guide explains how to authenticate with the Organization API key and configure optional IP allowlists using CIDR notation.

## Overview

Use this API to create a new **App API Key** (also called a **Rich Authentication Token**) for a specific OneSignal app. These keys are used to authenticate API requests at the app level and offer enhanced security features, including optional IP allowlisting.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

### IP allowlisting

By default, the API key will not be restricted to any specific IP addresses. To enable IP allowlisting, you need to set the `ip_allowlist_mode` parameter to `explicit` and provide a list of allowed IP addresses in the `ip_allowlist` parameter.

If you want to set the explicit range of IPs that can use this API key, add them by setting `ip_allowlist_mode` to `explicit` and in `ip_allowlist` add the IPs in CIDRs notation as an array of string values.

***


# Create custom events
Source: https://documentation.onesignal.com/reference/create-custom-events

POST /apps/{app_id}/custom_events
The Custom Events API allows you to record user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones.

## Overview

The Custom Events API allows you to track user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones. See [Custom events](/docs/en/custom-events) for more information.

### Use Cases

Custom events can be used to:

* Enter users into [Journeys](/docs/en/journeys-settings)
* Trigger Journey [Wait Until](/docs/en/journeys-actions) nodes

### Error handling

If individual events can't be processed, an `errors` key will be returned in the response (with HTTP status 202) containing information about each failing event. The most common event-specific error is a failure to find a user associated with the External ID or OneSignal ID in the event.

If you'd like to retry sending events in the case of a failure, you only need to re-send the events for which errors were returned -- events that don't have an error associated with them are still processed. However, if a 5xx HTTP response is returned, you must retry the entire batch of events.

In either case, if you are implementing retry, make sure to also pass an [`idempotency_key`](/reference/idempotent-notification-requests).

### Duplicate events

If you implement retry behavior for your custom event delivery, please provide the [`idempotency_key`](/reference/idempotent-notification-requests) field. Each unique event should get its own unique UUID, and when retrying delivery for events, the same UUID must be provided. Duplicate events with the same `idempotency_key` will be ignored on a best-effort basis within a 4-hour period. This allows you to avoid erroneously triggering Journeys multiple times or incurring charges for storing unnecessary duplicate events.

***


# Sending messages with the OneSignal API
Source: https://documentation.onesignal.com/reference/create-message

Send push notifications, emails, SMS, and Live Activities with the OneSignal API. Covers audience targeting, message composition, scheduling, and response handling.

## Overview

This guide walks you through sending messages with the OneSignal API — from choosing a target audience to composing content, scheduling delivery, and validating responses. Each section covers channel-specific options and performance guidance.

### Prerequisites

1. Complete [Channel Setup](/docs/en/channel-setup) for the channels you plan to use: push, email, SMS, Live Activities.
2. Start accumulating [Subscriptions](/docs/en/subscriptions) for your users.
3. Have your REST API Key and App ID ready. See [Keys and IDs](/docs/en/keys-and-ids).

***

## Choose your target audience

You can target users with **one of the following methods per request**:

* **Aliases**: Specific users via unique IDs, emails, or phone numbers.
* **Segments**: Groups based on predefined behaviors or attributes.
* **Filters**: Custom rules using tags, location, activity, and more.

<Warning>
  Only one targeting method is allowed per message. For example, you cannot mix aliases and filters.
</Warning>

You can also target specific platforms (for example, `isAndroid`, `isIos`, `isAnyWeb`) when sending push notifications. By default, all push platforms are enabled.

### Aliases, emails, phone numbers

Target specific users or lists of users (up to 20,000 entries per request). This method is best for [Transactional Messages](/docs/en/transactional-messages).

<Accordion title="Aliases, emails, and phone numbers targeting parameters">
  <ParamField type="object">
    Target up to 20,000 users by their `external_id`, `onesignal_id`, or a custom alias. Combine with `target_channel` to select the delivery channel.

    ```json theme={null}
    {
      "include_aliases": {
        "external_id": [
          "user1",
          "user2",
          "user3"
        ]
      },
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="string">
    The targeted delivery channel. Required when using `include_aliases` or `included_segments` and sending SMS/RCS. Accepts `"push"`, `"email"`, or `"sms"`. The `"sms"` value covers both SMS and RCS — RCS messages are delivered through the SMS channel.

    ```json theme={null}
    {
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="array">
    Target users' specific [Subscriptions](/docs/en/subscriptions) by ID. Max 20,000 `subscription_id` per request.

    ```json theme={null}
    {
      "include_subscription_ids": [
        "1dd608f2-c6a1-11e3-851d-000c2940e62c"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send to specific email addresses (max 20,000 per request). Can only be used when sending [email](/reference/email). If the email address does not exist within the OneSignal App, a new email subscription is created.

    ```json theme={null}
    {
      "email_to": [
        "user1@example.com",
        "user2@example.com"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send SMS/MMS/RCS to phone numbers in [E.164 format](/docs/en/sms-setup#what-is-e164-format) (max 20,000 per request). Can only be used when sending [SMS/MMS/RCS](/reference/sms). If the phone number does not exist within the OneSignal App, a new SMS subscription is created.

    ```json theme={null}
    {
      "include_phone_numbers": [
        "+19999999999"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Segments

Target users in existing [segments](/docs/en/segmentation). Users in multiple segments only receive the message once.

<Accordion title="Segments targeting parameters">
  <ParamField type="array">
    Target predefined [segments](/docs/en/segmentation). Users who are in multiple segments only receive the message once. Combine with `excluded_segments` to exclude users from specific segments. When sending SMS/RCS, set `target_channel` to `"sms"` (or use the legacy `isSms=true` field).

    ```json theme={null}
    {
      "included_segments": [
        "Active Users",
        "Inactive Users"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Exclude users in these [segments](/docs/en/segmentation) even if they're in `included_segments`.

    ```json theme={null}
    {
      "included_segments": [
        "Subscribed Users"
      ],
      "excluded_segments": [
        "Inactive Users"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Filters

Build real-time audiences with `AND`/`OR` logic without creating segments first.

You can include up to **200 total entries per request**. This includes filter rows (for example, each `field`) and logical operators like `{"operator": "OR"}`.

<Accordion title="Filters targeting parameter details">
  <Info>
    **Performance guidance:**

    * **Fast:** Tag filters using `"="` or `"exists"`, and filters on `last_session`, `session_count`, or `country`.
    * **Slower:** Negation filters (`"!="`, `"not_exists"`) — especially with users who have many tags. Contact support to request indexing optimizations.
    * **Slow by default:** Numeric comparisons (`">"`, `"<"`) on tags or custom properties. Indexing may be available on request.
    * **Mixed performance:** Combining tag filters with other fields may increase computation time.
  </Info>

  <ParamField type="string">
    * Implicit `AND` logic between filters. Use `"operator": "OR"` to start a new branch.
    * `OR` filters are mutually exclusive. Recipients only need to satisfy one condition.
    * Allowed values: `"AND"`, `"OR"`.

    <CodeGroup>
      ```json AND example theme={null}
      // Users must satisfy both filters to be included.
      // Notice the AND operator is not required

      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      // The same example using the AND operator. This is not required.
      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "AND"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      ```

      ```json OR example theme={null}
      // Users can satisfy either filter to be included.

      "filters": [
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "tag", "key": "level", "relation": "=", "value": "20"}
      ]
      ```

      ```json Combinations theme={null}
      // In this example, users must either have:
      // The specified session_count AND tag requirement
      // Or it will be all records where last_session is satisfied
      {
        "name": "2 filters or 1",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"}
        ]
      }

      // Similar to the first example, this shows how to require a specific field
      // across other filters

      {
        "name": "3 filters, 1 required across all",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
        ]
      }

      // Example of 3 user groups with 2 requirements
      // (group_1 OR group_2 OR group_3) AND (requirement_1 OR requirement_2)

      {
        "name": "3 groups with 2 requirements",
        "filters": [
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"}
        ]
      }
      ```
    </CodeGroup>
  </ParamField>

  <ParamField type="object">
    ### `tag`

    Target based on custom user [Tags](/docs/en/add-user-data-tags).

    <Warning>
      Do not use tags for targeting individual users like a "user id".
      Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
    </Warning>

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
      * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
    * `key` = Tag key to compare.
    * `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

    ```json theme={null}
    "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "OR"},
      {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
    ]
    ```

    ### `country`

    Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "country", "relation": "=", "value": "US"},
        {"operator": "OR"},
        {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
      ]
      ```

    ### `last_session`

    Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "last_session", "relation": ">","hours_ago": "10"}
      ]
      ```

    ### `first_session`

    Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "first_session", "relation": "<","hours_ago": "24"}
      ]
      ```

    ### `session_count`

    Total number of sessions by the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="` or `"!="`
    * `value` = number of sessions. Example: `"1"`

      ```json theme={null}
      "filters": [
        {"field": "session_count", "relation": ">","value": "5"}
      ]
      ```

    ### `session_time`

    Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

    * `relation` = `">"` or `"<"`
    * `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

      ```json theme={null}
      "filters": [
        {"field": "session_time", "relation": ">","value": "86400"}
      ]
      ```

    ### `language`

    [User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = 2 character language code. Example: `"en"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "language", "relation": "=","value": "en"},
        {"operator": "OR"},
        {"field": "language", "relation": "in_array","value": "es,fr,de"}
      ]
      ```

    ### `app_version`

    App version set on the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = app version. Example: `"1.0.0"`
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "app_version", "relation": "=","value": "1.0.1"},
        {"operator": "OR"},
        {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
      ]
      ```

    ### `location`

    Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

    * `radius` = in meters
    * `lat` = latitude
    * `long` = longitude

      ```json theme={null}
      "filters": [
        {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
      ]
      ```
  </ParamField>
</Accordion>

***

## Craft your message

Each channel has its own set of fields. At a minimum, you need the following to send a displayable message:

* **Push and SMS** use `contents`
* **Email** uses `email_subject` and `email_body`
* Or reuse `template_id` if you created [templates](/docs/en/templates).

<CodeGroup>
  ```json Push and SMS theme={null}
  // Message request body
  {
    "contents": {
      "en": "Hello, world",
      "es": "Hola Mundo",
      "fr": "Bonjour le monde",
      "zh-Hans": "你好世界"
    }
  }
  ```

  ```json Email theme={null}
  // Message request body
  {
    "email_subject": "Hello, world",
    "email_body": "<html><body><h1>Hello, world</h1></body></html>"
  }
  ```
</CodeGroup>

For advanced customization—like adding images, buttons, sounds, or tracking—see the channel-specific options below.

### Push notification options

Below are the most common parameters for push notifications. For the full list of options, see the [Push notification reference](/reference/push-notification).

<Accordion title="Push notification options">
  #### Content and text

  * [`contents`](/reference/push-notification#body-contents) – Main message body.
  * [`headings`](/reference/push-notification#body-headings) – Title of the notification.
  * [`subtitle`](/reference/push-notification#body-subtitle) – Secondary line of text.
  * [`template_id`](/reference/push-notification#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Appearance

  * [`ios_attachments`](/reference/push-notification#body-ios-attachments) – Images/video/media.
  * [`big_picture`](/reference/push-notification#body-big-picture) – Large image (Android).
  * [`chrome_web_image`](/reference/push-notification#body-chrome-web-image) – Large image (Chrome).
  * [`small_icon`](/reference/push-notification#body-small-icon)
  * [`large_icon`](/reference/push-notification#body-large-icon)
  * [`buttons`](/reference/push-notification#body-buttons) – Action buttons.

  #### Delivery and priority

  * [`android_channel_id`](/reference/push-notification#body-android-channel-id)
  * [`priority`](/reference/push-notification#body-priority) – Delivery urgency.
  * [`ios_interruption_level`](/reference/push-notification#body-ios-interruption-level)
  * [`collapse_id`](/reference/push-notification#body-collapse-id) – Replaces older messages.

  #### Data and extras

  * [`data`](/reference/push-notification#body-data) – Custom key-value pairs sent to your app.
  * [`url`](/reference/push-notification#body-url) – Opens when notification is tapped.
</Accordion>

### Email options

<Accordion title="Email options">
  #### Content

  * [`email_subject`](/reference/email#body-email-subject)
  * [`email_body`](/reference/email#body-email-body)
  * [`email_preheader`](/reference/email#body-email-preheader)

  #### Appearance

  * [`template_id`](/reference/email#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Sender info

  * [`email_from_name`](/reference/email#body-email-from-name)
  * [`email_reply_to`](/reference/email#body-email-reply-to)
</Accordion>

### SMS/MMS options

<Accordion title="SMS/MMS options">
  #### Content

  * [`contents`](/reference/sms#body-contents)
  * [`template_id`](/reference/sms#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Media (MMS only)

  * [`sms_media_urls`](/reference/sms#body-sms-media-urls)

  #### Sender info

  * [`sms_from`](/reference/sms#body-sms-from)
</Accordion>

***

## Schedule and per-user delivery

By default, messages are sent immediately. You can schedule delivery in advance and optimize timing per user based on their local timezone or recent activity.

<Accordion title="Schedule delivery and per-user optimization parameters">
  <ParamField type="string">
    Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript's Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring).

    ```json theme={null}
    {
      "send_after": "2025-09-24T14:00:00-07:00"
    }
    ```
  </ParamField>

  <ParamField type="string">
    Controls how push and email messages are delivered on a per-user basis. Not available for SMS.

    * `"timezone"`: Sends at the same local time across time zones.
    * `"last-active"`: Delivers based on each user's most recent session.

    Not compatible with [push throttling](/docs/en/throttling). When `delayed_option` is set, you must also set `throttle_rate_per_minute` to `0`.

    ```json theme={null}
    {
      "delayed_option": "last-active",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>

  <ParamField type="string">
    Use with `delayed_option: "timezone"` to set a consistent daily delivery time. Accepted formats:

    * `"9:00AM"` (12-hour)
    * `"21:45"` (24-hour)
    * `"09:45:30"` (HH:mm:ss)

    Example — Send every day at 9 AM in each user's local time:

    ```json theme={null}
    {
      "delayed_option": "timezone",
      "delivery_time_of_day": "9:00AM",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>
</Accordion>

***

## Submit the request

This final example sends a localized push notification to all subscribed users:

```curl theme={null}
curl -X "POST" "https://api.onesignal.com/notifications" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Key YOUR_API_KEY' \
     -d $'{
      "target_channel": "push",
      "included_segments": [
        "Subscribed Users"
      ],
      "app_id": "YOUR_APP_ID",
      "contents": {
        "en": "Hello, world",
        "es": "Hola mundo",
        "fr": "Bonjour le monde",
        "zh-Hans": "你好世界"
      }
    }'
```

Once the request is sent, OneSignal forwards it to the appropriate downstream provider, which then delivers it to the recipient:

* **Push:** FCM, APNs, or HMS
* **Email:** your email service provider
* **SMS:** Twilio

### Handle the response

You receive a `200` response code if the request is valid and accepted.

* If an `id` is returned, the message was created successfully. Save this `id` for future tracking and reference of message stats via the [View message API](/reference/view-message).
* If no `id` is returned, the message was not created, likely because there are no valid [subscriptions](/docs/en/subscriptions) in the target audience.

**Response details by channel:**

* [Push](/reference/push-notification#response-id)
* [Email](/reference/email#response-id)
* [SMS](/reference/sms#response-id)

<Note>
  See our [REST API Overview](/reference/rest-api-overview#reliability-and-delivery) page for details on retries and [rate limits](/reference/rate-limits).
</Note>

***

## FAQ

### Can I combine `include_aliases`, `included_segments`, and `filters` in one request?

No. Each request must use exactly one targeting method. Mixing them returns a validation error. Choose aliases for transactional sends to specific users, segments for predefined audiences, or filters for ad-hoc audiences built with `AND`/`OR` logic.

### Does `target_channel: "sms"` cover RCS?

Yes. The `target_channel` enum accepts `"push"`, `"email"`, and `"sms"`. RCS messages are delivered through the SMS channel — there is no separate `"rcs"` value. OneSignal decides whether to send via RCS or SMS based on the recipient's device and your sender configuration.

### My request returned `200` but no `id`. What happened?

The request was valid but no message was created, typically because the target audience contains no valid subscriptions for the selected channel. Common causes include a segment that resolves to zero users, all targeted aliases being unsubscribed, or phone numbers that don't match an existing SMS subscription.

### Can I use `//` comments in the JSON request body?

No. The `//` comments in the examples on this page are illustrative only. Strict JSON does not support comments — strip them before sending to the API.

### How is the `Sent` count in reports related to the API response?

The dashboard `Sent` metric is a composite. To derive it from the [View message API](/reference/view-message), sum `successful + failed + errored`. See the [Metrics glossary](/docs/en/analytics-metrics-glossary) for the full mapping between dashboard, API, CSV, and Event Streams names.

***

## Next steps

Refer to the channel-specific APIs to customize delivery further:

* [Push notification](/reference/push-notification)
* [Email](/reference/email)
* [SMS](/reference/sms)
* [Live Activities](/reference/start-live-activity)
* [Server-Side SDKs](/docs/en/server-sdk-reference)


# Create segment
Source: https://documentation.onesignal.com/reference/create-segments

POST /apps/{app_id}/segments
Programmatically create segments in your OneSignal app using flexible filters and targeting rules.

## Overview

Use this API to create new [Segments](/docs/en/segmentation) programmatically. These segments are then accessible in the OneSignal Dashboard and usable in messages, Journeys, and in-app messaging campaigns.

<Note>
  To modify an existing segment, use the [Update segment](/reference/update-segment) API.
</Note>

***

## How to use this API

This endpoint allows your backend to define audience segments by passing in a combination of filters and logical operators like `"AND"` and `"OR"`, mirroring the segmentation capabilities of the OneSignal Dashboard.

### Name the segment

The name of the segment as it shows in the OneSignal dashboard and accessible via the `included_segments` and `excluded_segments` targeting parameters.

### Describe the segment

Optionally include a `description` (max 255 characters) to record the segment's purpose. The description is returned by the [View segments](/reference/view-segments) and [View segment](/reference/view-segment) APIs.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "10"}
  ]
}
```

### Define the `filters`

Available filters:

* [operator](#operator)
* [tag](#tag)
* [last\_session](#last_session)
* [first\_session](#first_session)
* [session\_count](#session_count)
* [session\_time](#session_time-1)
* [language](#language)
* [app\_version](#app_version)
* [location](#location)
* [country](#country)

### `operator`

**Description**

Allows you to combine or separate properties. Filters combined with an `"AND"` have higher priority than `"OR"` filters.

* `"AND"` = the 2+ connected filters must be satisfied for the recipient to be included. Filter entries use this by default and its not required to be included.
* `"OR"` = the 2 filters separated by the `"OR"` operator are mutually exclusive. The recipients only need to satisfy the conditions on either side of the `"OR"` operator.

<CodeGroup>
  ```json AND example theme={null}
  // Users must satisfy both filters to be included.
  // Notice the AND operator is not required

  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  // The same example using the AND operator. This is not required.
  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "AND"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  ```

  ```json OR example theme={null}
  // Users can satisfy either filter to be included.

  "filters": [
    {"field": "tag", "key": "level", "relation": "=", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "level", "relation": "=", "value": "20"}
  ]
  ```

  ```json Combinations theme={null}
  // In this example, users must either have:
  // The specified session_count AND tag requirement
  // Or it will be all records where last_session is satisfied
  {
    "name": "2 filters or 1",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"}
    ]
  }

  // Similar to the first example, this shows how to require a specific field
  // across other filters

  {
    "name": "3 filters, 1 required across all",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
    ]
  }
  ```
</CodeGroup>

### `tag`

**Description**

Target based on custom user [Tags](/docs/en/add-user-data-tags).

<Warning>
  Do not use tags for targeting individual users like a "user id".
  Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
</Warning>

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
  * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
* `key` = Tag key to compare.
* `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

```json theme={null}
"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "OR"},
  {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
]
```

### `last_session`

**Description**

Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "last_session", "relation": ">","hours_ago": "10"}
  ]
  ```

### `first_session`

**Description**

Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "first_session", "relation": "<","hours_ago": "24"}
  ]
  ```

### `session_count`

**Description**

Total number of sessions by the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="` or `"!="`
* `value` = number of sessions. Example: `"1"`

  ```json theme={null}
  "filters": [
    {"field": "session_count", "relation": ">","value": "5"}
  ]
  ```

### `session_time`

**Description**

Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

* `relation` = `">"` or `"<"`
* `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

  ```json theme={null}
  "filters": [
    {"field": "session_time", "relation": ">","value": "86400"}
  ]
  ```

### `language`

**Description**

[User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = 2 character language code. Example: `"en"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "language", "relation": "=","value": "en"},
    {"operator": "OR"},
    {"field": "language", "relation": "in_array","value": "es,fr,de"}
  ]
  ```

### `app_version`

**Description**

App version set on the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = app version. Example: `"1.0.0"`
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "app_version", "relation": "=","value": "1.0.1"},
    {"operator": "OR"},
    {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
  ]
  ```

### `location`

**Description**

Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

* `radius` = in meters
* `lat` = latitude
* `long` = longitude

  ```json theme={null}
  "filters": [
    {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
  ]
  ```

### `country`

**Description**

Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "=", "value": "US"},
    {"operator": "OR"},
    {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
  ]
  ```

***


# Create Subscription by alias
Source: https://documentation.onesignal.com/reference/create-subscription

POST /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions
Use this API to attach a new subscription—such as email, SMS, or push notification—to an existing OneSignal user identified by an alias.

## Overview

This API allows you to add a **new Subscription** to an existing [User](/docs/en/users) via an alias identifier. A *Subscription* reflects a user's intent to receive messages through a specific communication channel, such as email, SMS, or push notifications. See [Subscriptions](/docs/en/subscriptions) for additional context.

If you're looking to **create a new user and add Subscriptions simultaneously**, use the [Create User](/reference/create-user) API instead.

***

## How to use this API

To attach a Subscription, the user must already exist and be referenced using an alias. The `alias_label` and `alias_id` path parameters define how the user is identified:

* Common alias: `external_id`
* Other options: `onesignal_id`, or custom aliases

For details, refer to [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

## Required Fields

Each Subscription must include at least:

* `type`: the channel (e.g., `Email`, `SMS`, `iOSPush`)
* `token`: the unique identifier for the channel (e.g., email address, phone number, push token)

If the specified `type` and `token` already exist in the app, the Subscription will be transferred to the user identified in the path parameters.

***


# Create template
Source: https://documentation.onesignal.com/reference/create-template

POST /templates
Create reusable message templates for push, email, and SMS channels. Templates can be accessed through both the dashboard and API using a `template_id`.

## Overview

Use this endpoint to create a new message template in your OneSignal app. Once created, the template becomes available for use when sending messages via both the Dashboard and the REST API by referencing the `template_id`.

Templates streamline and standardize message content across push, email, and SMS channels.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Before using this endpoint, ensure that the target channel (push, email, or SMS) is properly configured in your OneSignal app. See [Channel Setup](/docs/en/channel-setup) for guidance.

### Push Templates

**Requirements:**

* Set the `contents` property with the English (`en`) language key.
* All [Push Channel Properties](/reference/push-notification) are valid for use in push templates.
* By default, all push platforms are enabled. You can target specific platforms by explicitly setting them (e.g., `isAndroid: true` disables others).

### Email Templates

**Requirements:**

* Set `isEmail: true`.
* Include both `email_subject` and `email_body`.
* All [Email Channel Properties](/reference/email) are valid for use in email templates.

### SMS Templates

**Requirements:**

* Set `isSMS: true`.
* Provide SMS-specific parameters like `contents`.
* All [SMS Channel Properties](/reference/sms) are valid for use in SMS templates.

***


# Create user
Source: https://documentation.onesignal.com/reference/create-user

POST /apps/{app_id}/users
Create a new user or modify the subscriptions associated with an existing User.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint enables you to create and manage users outside of frontendSDK-based sessions. It's primarily used to:

* Import users from other systems.
* Programmatically define users by assigning identifiers (aliases), properties (e.g., tags), and messaging subscriptions (e.g., email, mobile, SMS).

If you're using the frontend SDKs, user creation is typically handled automatically via methods like `login`, `addEmail`, and `addSms`. See [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) for conceptual guidance.

***

## How to use this API

To successfully create a user via the API:

* You must provide at least one unique identifier via the `identity` and Subscription via the `subscriptions` fields.
* You can optionally include user profile data (`properties`) and one or more messaging `subscriptions`.

## Key Concepts

### Aliases

Aliases uniquely identify a user and should include an `external_id` (the recommended identifier). They allow you to reference users across platforms or external systems. Up to 10 custom aliases are supported. Each alias key and value has a maximum length of 128 characters.

### Properties

User properties store information such as tags, location, activity, and device data. These attributes help you personalize campaigns and optimize engagement strategies.

### Subscriptions

A user can have up to **20 subscriptions** (across email, SMS, push, etc.). Subscriptions connect users to channels for message delivery and are transferable across users. See [Subscriptions](/docs/en/subscriptions) for more.

***


# Export subscriptions CSV
Source: https://documentation.onesignal.com/reference/csv-export

POST /players/csv_export
Generate a GZip-compressed CSV export of your current subscription data using this API endpoint.

## Overview

Use this endpoint to request a GZip-compressed CSV export of all your [Subscriptions data](/docs/en/subscriptions) from OneSignal. The export includes both default and optional user data fields, and supports filters to refine the dataset. The file is downloadable via a URL returned in the API response.

***

## How to use this API

By default, this will export all Subscriptions within the app.

**Optional filters:**

You can narrow the export using:

* `segment_name`: Only export Subscriptions from a specific segment. Segment membership rules determine which subscription statuses are included. Use with `include_unsubscribed` to include unsubscribed subscriptions.
* `last_active_since`: Export Subscriptions where their `last_session` was after a specific Unix timestamp. Example: Use `1704067200` for Subscriptions active since January 1st, 2024.
* `include_unsubscribed`: When exporting a segment, set to `true` to include unsubscribed subscriptions alongside subscribed ones. By default, segment-filtered exports only return subscribed subscriptions. This parameter has no effect when `segment_name` is not provided.

**Example successful response:**

```json 200 OK theme={null}
{
  "csv_file_url": "https://onesignal.com/csv_exports/b2f7f966.../users_1849..._2024-11-10.csv.gz"
}
```

**Export time considerations:**

* Generation speed: \~2,000 records per second.
* File readiness: The `csv_file_url` may return a 404 until generation completes.
* Download retry: Poll the file URL at intervals until the file is ready.
* File expiration: The file remains available for 3 days after generation.
* Concurrency: Only one export per OneSignal account can run at a time.

**File not ready (404 response)**

```xml 404 CSV GET  theme={null}
This XML file does not appear to have any style information
associated with it. The document tree is shown below.
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

<Info>
  You can safely poll the `csv_file_url` until the file becomes available. Implement retry logic based on expected data volume and generation speed.

  Only one export is allowed at a time per account. Wait until the `.csv.gz` file is downloaded before triggering another export.
</Info>

***

## CSV data contents

The export includes two types of fields:

* **Default fields**: Always included unless excluded by schema changes.
* **Extra fields**: Must be explicitly requested using the `extra_fields` parameter.

### Default fields

* `id`: The Subscription ID.

* `identifier`: The push token, email address, or phone number depending on the Subscription type.

* `session_count`: The number of times the user has opened the app.

* `language`: The user's language in ISO 639-1 format.

* `timezone`: Deprecated — use `timezone_id` instead.

* `game_version`: The version of your app that the user is currently using.

* `device_os`: The device's operating system version.

* `device_type`: Integer representing channel/device type.
  * `0`: iOSPush
  * `1`: AndroidPush
  * `2`: FireOSPush
  * `5`: ChromePush
  * `7,17`: SafariPush
  * `11`: Email
  * `14`: SMS

* `device_model`: The device's hardware string.

* `ad_id`: Deprecated.

* `tags`: Custom key/value data.

* `last_active`: The last time the user was active.

* `playtime`: The total amount of time in seconds the user had the mobile app open.

* `created_at`: The first time the user was seen.

* `invalid_identifier`: Boolean flag for unsubscribed state.
  * `t`: Unsubscribed
  * `f`: Subscribed

### Extra fields (`extra_fields`)

Pass `extra_fields` in your request to include any of the following:

* `external_user_id`: Maps to the `external_id` of the user.

* `onesignal_id`: OneSignal's user ID.

* `location`: Adds the `lat` and `long` coordinates if set.

* `country`: The user's country in ISO 3166-1 Alpha 2 format.

* `ip`: The IP address if detected. Can be IPv4 or IPv6 format.

* `web_auth`: Only available to OneSignal SDKs. The `web_auth` key for web push.

* `web_p256`: Only available to OneSignal SDKs. The `web_p256` for web push.

* `unsubscribed_at`: The date and time the user last unsubscribed. They may resubscribe at any time. Check the `invalid_identifier` field to determine if they are currently subscribed.

* `notification_types`: Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/en/subscriptions#notification-types).

* `timezone_id`: The user's timezone in IANA format.

***


# Remove alias
Source: https://documentation.onesignal.com/reference/delete-alias

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}
Remove a specific alias from a user.

## Overview

Use this API to remove a specific alias from a user’s identity object without deleting the user. This operation only affects user identity labels—subscriptions and the core user record remain intact. To delete a user entirely, including all associated aliases and subscriptions, see the [Delete user](/reference/delete-user) API.

***

## How to use this API

To remove an alias from a user:

1. Identify the user via a known alias by specifying:

   * `alias_label` – the type of alias (e.g., email, external\_id)
   * `alias_id` – the unique identifier for that alias

2. Specify the alias to remove using:

   * `alias_label_to_delete` – the label of the alias to be deleted

   The `alias_label_to_delete` can be the same as the `alias_label` used to identify the user.

3. This action is performed synchronously—the alias is deleted immediately after the request is processed.

<Warning>
  The `onesignal_id` alias cannot be deleted. Only secondary aliases (like email, external\_id, etc.) are removable.
</Warning>

For a full explanation of identity management, see [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

***

## FAQ

### Can I delete the same alias that I used to look up the user?

Yes. This is a common scenario—especially if an alias was set incorrectly and needs to be removed. Just be sure to include that alias both as the identifier and as alias\_label\_to\_delete.

If you want to delete the entire user and all associated data, use the [Delete user](/reference/delete-user) API.

### What happens if I delete all aliases associated with the user?

A user will always retain at least one alias, the onesignal\_id. Even if you remove all other aliases, the user and their subscriptions remain linked to the onesignal\_id.

***


# Delete API key
Source: https://documentation.onesignal.com/reference/delete-api-key

DELETE /apps/{app_id}/auth/tokens/{token_id}
Delete a specific Rich Authentication Token (App API Key) for a OneSignal app. Requires your Organization API Key and the token's unique ID, not the token value itself.

## Overview

Use this API to delete a specific App API Key (Rich Authentication Token) for a single OneSignal.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Delete segment
Source: https://documentation.onesignal.com/reference/delete-segments

DELETE /apps/{app_id}/segments/{segment_id}
Delete segments from OneSignal. Does not delete users or subscriptions.

## Overview

The Delete segment method is used when you want to programmatically delete a segment from within the OneSignal Dashboard UI.

<Warning>
  Once a segment is deleted, it cannot be recovered. You will need to create a new segment with the same filters.
</Warning>

***

## How to use this API

You can pass in the `segment_id` dictating which segment from our dashboard will be deleted.

The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard as shown below:

<Frame>
  <img />
</Frame>

***


# Delete Subscription
Source: https://documentation.onesignal.com/reference/delete-subscription

DELETE /apps/{app_id}/subscriptions/{subscription_id}
Delete a specific subscription by its subscription_id. This stops messages from being sent to that subscription but does not prevent future subscriptions with the same token.

## Overview

Use this API to delete an existing Subscription and its associated properties. Deletion is **asynchronous**, and while the Subscription is being removed, messages will no longer be sent to it.

<Warning>
  This operation only deletes a **single Subscription**. To remove a **user and all their Subscriptions**, use the [Delete User](/reference/delete-user) API instead.
</Warning>

### What Happens When You Delete

* Messages will stop being sent to the deleted subscription.
* **Deleting a Subscription does not block new Subscriptions** with the same `token`.
  * If the app is reopened or a token is re-submitted (e.g., same email or phone), a **new Subscription** may be automatically created.
  * This ensures users can re-subscribe if needed without requiring manual intervention.

***

## How to Use This API

**Required:** `subscription_id`

You must provide the `subscription_id` of the subscription to be deleted. This ID is a UUID generated by OneSignal and is immutable.

To find the `subscription_id`:

1. Use the [View User](/reference/view-user) API.
2. Look at the `subscriptions` array in the response.
3. Identify the correct subscription by its `type`, `token`, or other metadata.
4. Use the corresponding `id` field as the `subscription_id`.

***


# Delete template
Source: https://documentation.onesignal.com/reference/delete-template

DELETE /templates/{template_id}?app_id={app_id}
Permanently delete a specific message template from your OneSignal app using its template ID. Templates used in Journeys must be removed from those Journeys before deletion.

## Overview

This endpoint allows you to delete a single template associated with your OneSignal app. Deletion is **immediate and irreversible**.

<Warning>
  If the template is currently used in a Journey, it cannot be deleted until that Journey has been deleted.
</Warning>

***

## How to use this API

Required Parameters

* `template_id` (path param): The OneSignal-generated UUID of the template to delete.
* `app_id` (query param): Your OneSignal App ID.

### Where to Find `template_id`

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# Delete user
Source: https://documentation.onesignal.com/reference/delete-user

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}
Delete a user including all associated properties, subscriptions, and identity.

## Overview

Use this API to permanently delete a user from your OneSignal project, including all associated subscriptions, properties, and aliases. The operation is asynchronous—user data will be deleted shortly after the request is accepted.

***

## How to use this API

To delete a user, you must be able to identify them using one of the following alias types:

* `external_id` (recommended and most common)
* `onesignal_id`
* A custom Alias that you have set

Pass the appropriate `alias_label` and corresponding `alias_id` in the request path.

<Warning>
  This operation deletes all data associated with the user, including:

  * All identity aliases
  * All channel subscriptions (push, email, SMS, etc.)
  * All custom user properties
</Warning>

## Because this is an irreversible operation, be sure that you really intend to delete the user and all their data.


# Delete player record
Source: https://documentation.onesignal.com/reference/delete-user-record

delete https://onesignal.com/api/v1/players/{player_id}?app_id={app_id}

Delete a player (aka Subscription).

<Warning>
  This is a Legacy API. Use [Delete User](/reference/delete-user) or [Delete Subscription](/reference/delete-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `app_id`    | string | Yes      | Your OneSignal App ID.         |
| `player_id` | string | Yes      | The Subscription ID to delete. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Example Request

```http theme={null}
DELETE /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json
```

***

## Example Response

```json theme={null}
{
  "success": true
}
```

The Subscription will be deleted from the OneSignal database.

***


# Edit player
Source: https://documentation.onesignal.com/reference/edit-device

put https://onesignal.com/api/v1/players/{player_id}

Update a player's (Subscription's) information using the Subscription ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `player_id` | string | Yes      | The OneSignal Subscription ID. |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request.    |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                |
| -------------------- | ------- | -------- | ---------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                     |
| `identifier`         | string  | No       | Push token, email, or phone number.                        |
| `language`           | string  | No       | Language code (e.g., "en").                                |
| `timezone`           | integer | No       | Time zone offset in seconds.                               |
| `game_version`       | string  | No       | App version.                                               |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                         |
| `device_os`          | string  | No       | OS version (e.g., "14.5").                                 |
| `ad_id`              | string  | No       | Advertising ID.                                            |
| `sdk`                | string  | No       | OneSignal SDK version.                                     |
| `tags`               | object  | No       | Custom key-value pairs.                                    |
| `external_user_id`   | string  | No       | Your internal user ID.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc. |
| `email_auth_hash`    | string  | No       | Required to update email identifiers securely.             |
| `sms_auth_hash`      | string  | No       | Required to update SMS identifiers securely.               |

> Only include fields you want to change. Fields left out will not be modified.

***

## Example Request

```json theme={null}
PUT /api/v1/players/player_id_string HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "external_user_id": "user123",
  "tags": {
    "level": "20",
    "subscription": "active"
  },
  "language": "fr",
  "timezone": 3600,
  "device_os": "16.0"
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Missing or invalid fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied.
* 404 Not Found – Device with player\_id not found.

***


# Edit tags with external user id
Source: https://documentation.onesignal.com/reference/edit-tags-with-external-user-id

put https://onesignal.com/api/v1/apps/{app_id}/users/{external_user_id}

Update a player's (Subscription's) information using the External ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter          | Type   | Required | Description             |
| ------------------ | ------ | -------- | ----------------------- |
| `app_id`           | string | Yes      | Your OneSignal App ID.  |
| `external_user_id` | string | Yes      | The user's External ID. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Request Body Parameters

| Field  | Type   | Required | Description                       |
| ------ | ------ | -------- | --------------------------------- |
| `tags` | object | Yes      | Key-value pairs to set or update. |

* To **delete a tag**, set its value to an empty string (`""`).
* Existing tags with the same keys will be **overwritten**.

***

## Example Request

```http theme={null}
PATCH /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json

{
  "tags": {
    "plan": "premium",
    "logged_in": "true",
    "referral": ""
  }
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Invalid request or payload.
* 401 Unauthorized – Invalid or missing keys.
* 403 Forbidden – Access denied due to insufficient permissions.
* 404 Not Found – No players found for given `external_user_id`.

***


# Email
Source: https://documentation.onesignal.com/reference/email

POST /notifications?c=email
Send a message using the email channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for email. See [Push notification](/reference/push-notification) or [SMS](/reference/sms) to send to those channels.

Ensure your [Email setup](/docs/en/email-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Export audience activity CSV
Source: https://documentation.onesignal.com/reference/export-csv-of-events

POST /notifications/{message_id}/export_events
Export a compressed CSV report of audience-level delivery and engagement data for a specific message. This includes sent, delivered, clicked, failed, and unsubscribed events across Push, Email, and SMS channels.

## Overview

Get a CSV of per-recipient audience activity events (sends, clicks, failures, etc.) for a push, email, or SMS message. This endpoint mirrors the **Export** button in the dashboard's Audience Activity section on each message report:

* [Push message reports](/docs/en/push-notification-message-reports)
* [Email message reports](/docs/en/email-message-reports)
* [SMS message reports](/docs/en/sms-message-reports)

The CSV schema varies by channel. See each channel's message reports page for column definitions.

***

## How to use this API

Get the message `id` from the [Sending messages API](/reference/create-message) or the [View messages API](/reference/view-messages).

A successful request returns `200 OK` with a `csv_file_url`:

```json 200 OK theme={null}
{
    "csv_file_url": "https://onesignal-data.onesignal.com/csv_exports/YOUR_APP_ID/events_audience-activity-YOUR_MESSAGE_ID-push-YYYY-MM-DDTHH-MM-SSTZ.csv.gz"
}
```

The generated file name follows the pattern `events_audience-activity-{message_id}-{channel}-{timestamp}.csv.gz`.

The file is generated at \~2,000 records per second. For large audiences, generation can take several minutes, and the URL may return `404` until the file is ready:

```xml 404 Not Found theme={null}
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

Poll the `csv_file_url` with GET and implement retries with exponential backoff. When the file is ready, the GET request downloads the `.csv.gz` file.

<Info>
  * The CSV download URL is valid for **3 days** after creation.
  * File names include a random UUID to prevent guessing.
</Info>

<Warning>
  Only **one concurrent export** is allowed per OneSignal account. Download the `.csv.gz` file before starting another export, or the new request fails.
</Warning>

***


# View user identity
Source: https://documentation.onesignal.com/reference/fetch-aliases

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Retrieve all aliases associated with a user using a known alias, such as an `external_id`, `onesignal_id`, or a custom alias. This API helps you map back to a user’s full identity from any one piece of identifying information.

## Overview

Use this API when you want to retrieve the complete identity object for a user, which includes all aliases tied to that user. It is ideal for cases where you know one alias and want to discover others—especially helpful for user mapping, debugging, or linking systems.

This endpoint is similar to the [View user](/reference/view-user) API but only returns the `identity` object—not subscriptions or properties.

<Tip>
  If you only know a subscription\_id, use View user identity (by subscription) instead.
</Tip>

For more context on user identity and aliasing:

* [Users](/docs/en/users)
* [Aliases](/docs/en/aliases)

***

## How to use this API

To identify the user, use:

* `alias_label` – the type of alias you’re using to find the user (e.g. `external_id`, `onesignal_id`, or a custom alias)
* `alias_id` – the actual value of that alias

Common usage patterns:

Using `external_id` (recommended):

* `alias_label`: `external_id`
* `alias_id`: your user ID (e.g., user-123)

Using `onesignal_id`:

* `alias_label`: `onesignal_id`
* `alias_id`: the OneSignal-assigned unique ID

Using a custom alias:

* Define your own alias label (e.g. `shopify_customer_id`) and its value

<Note>
  We strongly recommend setting and using the `external_id` as your primary user identifier for portability and simplicity across your systems.
</Note>

***


# View user identity (by subscription)
Source: https://documentation.onesignal.com/reference/fetch-identity-by-subscription

GET /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Retrieve all aliases linked to a user using a known `subscription_id`. This is useful when the user’s identity is unknown but you have access to one of their push, email, or SMS subscriptions.

## Overview

Use this API when you want to find the full identity (all aliases) of a user, starting from a known `subscription_id`. This is helpful for debugging, reverse lookups, or support use cases where only a subscription record is available.

<Note>
  Unlike the [View user identity](/reference/fetch-aliases) API which starts with an alias (e.g., `external_id`), this endpoint works when only a subscription ID is known.
</Note>

See [Subscriptions](/docs/en/subscriptions) for background on how subscriptions relate to users.

***

## How to use this API

To use this endpoint, you must provide:

* `subscription_id` – A UUID generated by OneSignal when a device or channel (e.g., push, email, SMS) is registered.

<Warning>
  `subscription_id` values are immutable and cannot be changed. Make sure you are using the correct value, as they are unique to each app and platform.
</Warning>

Once a valid `subscription_id` is provided, the API will return the user’s identity object, which includes all associated aliases like `external_id`, `onesignal_id`, and any custom aliases.

***


# Idempotent API requests
Source: https://documentation.onesignal.com/reference/idempotent-notification-requests

Prevent duplicate messages or custom events when retrying API requests.

## Overview

When you create messages or custom events via our REST API, network failures or timeouts can cause uncertainty about whether a request succeeded. **Idempotent requests** solve this problem by ensuring the same request is only processed once—even if it is sent multiple times.

This page explains how idempotency works in OneSignal, when to use it, and common pitfalls to avoid.

### When you should use idempotency

You should use idempotent requests any time you plan to retry API calls, especially when:

* You receive a timeout, 500-level error, or no response.
* Your infrastructure automatically retries failed requests.
* Delivering a duplicate message or custom event would be harmful.
* Missing a message or custom event would be harmful.

### The problem idempotency solves

Consider this common failure scenario:

1. You send a `notifications#create` or `custom_events#create` request.
2. OneSignal begins processing and sending the message or event.
3. A network error occurs before your client receives a response.

At this point, your system cannot know whether the request succeeded.

* If you retry and the request already succeeded, users may receive duplicates.
* If you do not retry and the request failed, users may miss important messages or events.

**Idempotency provides a safe retry mechanism.**

***

## How idempotency works

OneSignal supports idempotent operations for:

* [`notifications#create`](/reference/create-message)
* [`custom_events#create`](/reference/create-custom-events)

You provide a unique `idempotency_key` with each request.

### Request flow with idempotency

1. You send a request with an `idempotency_key`.
2. OneSignal processes the request and begins sending the message or creating the custom event.
3. A network error or timeout occurs.
4. You retry the request using the same `idempotency_key`.
5. OneSignal detects the duplicate and returns the result of the original request.
6. Only one notification or custom event is processed.

You can repeat this retry any number of times. As long as the `idempotency_key` remains the same, the operation will only be processed once.

***

## Idempotency key reference

<ParamField type="RFC 9562 UUID">
  A unique identifier used to prevent duplicate messages or custom events from repeat API calls. Keys must be unique [RFC 9562 UUID format](https://en.wikipedia.org/wiki/Universally_unique_identifier). Valid for 30 days.
</ParamField>

<Note>
  This `idempotency_key` property used to be called `external_id` but caused confusion with our [Users `external_id`](/docs/en/users) alias, so we have added this new property name to reduce confusion. Both will work in this case.
</Note>

***

## Important constraints and gotchas

<Warning> If you reuse the same `idempotency_key` for different messages or events, only the first request will be processed. </Warning>

Keep the following in mind:

* **Keys must be unique per logical operation**
  Generate a new UUID for every notification or custom event you intend to send.

* **Keys are retained for 30 days**
  After 30 days, OneSignal may delete the record. Reusing the same key after that window may result in a new message being sent.

* **Use a strong source of randomness**
  Predictable or reused UUIDs can cause unexpected deduplication.

* **Idempotency does not guarantee delivery**
  It only guarantees at-most-once processing. You should still monitor API responses and logs.

### Legacy behavior

The `idempotency_key` property was previously named `external_id`. This caused confusion with the Users `external_id` alias, so `idempotency_key` is now the recommended field name. Both names are currently supported.

### Best practices

* Always include `idempotency_key` when implementing retries.
* Store the `idempotency_key` alongside your request metadata for debugging.
* Retry only after honoring any `Retry-After` header returned by the API.
* Combine idempotency with proper timeout handling (for example, a 60-second HTTP timeout).

***


# Message history
Source: https://documentation.onesignal.com/reference/message-history

POST /notifications/{message_id}/history
View which subscriptions received a particular message

## Overview

This API enables you to retrieve all [Subscriptions](/docs/en/subscriptions) that received a specific push notification or email. You can access the notification's history for up to seven days after it was sent. Please note that notifications sent to fewer than 1,000 recipients will not record a "received" event, but they will still record "sent" events.

***

## How to Use this API

1. Submit a request to generate a report.

2. Decide delivery method

   * After receiving a successful response, **poll the destination URL** until the file becomes available. Exports typically complete within 1-3 minutes; we recommend a 10-second polling interval.
   * Alternatively, you can opt to receive an email to the address specified in the optional `email` parameter when the report is ready.

### Requirements

* A [OneSignal Professional or Enterprise Plan](https://onesignal.com/pricing).
* Enabled the "Send History via OneSignal API" option in Settings -> Integrations; notifications sent before this setting is enabled can't be retrieved.
* Requests must be made within seven days of sending the notification.

### Polling

Use the `csv_file_url` property in the response to test if the report is complete. If you receive a '403' error response, retry fetching the file after a short period; it only means we're still generating the report.

### Sample Report

The generated report is a simple CSV file that can be imported into any system for further processing.

```csv report.csv theme={null}
player_id,onesignal_id,external_id,target_channel,timestamp
"2c4fac95-7dfb-4113-9347-aba3a92ff557","ccddf35a-1233-4423-8a57-ac8c4b38eb81","a07aec27-2586-4b92-a24f-62660a1517fa","push","1628189160"
"68f5cf73-b20a-4de9-b6ee-79a863b8e7d8","d2f9f2f8-94af-4942-8183-115cef1213d5","4b66359f-3d94-4a73-806d-8ef5f0430b3d","push","1628187816"

```

### Limitations

* Querying for `opens` events are not supported.
* The `timestamp` column is included only for `clicked` events.

***


# Push notification
Source: https://documentation.onesignal.com/reference/push-notification

POST /notifications?c=push
Send a message using the push notification channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for push. See [Email](/reference/email) or [SMS](/reference/sms) to send to those channels.

Ensure your application is properly configured by following the [Mobile SDK Setup](/docs/en/mobile-sdk-setup) and/or [Web SDK Setup](/docs/en/web-sdk-setup) guides. You should see subscribed push [Subscriptions](/docs/en/subscriptions) in your OneSignal dashboard to send them messages.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Rate limits and error handling
Source: https://documentation.onesignal.com/reference/rate-limits

Understand OneSignal API and application rate limits, common errors, retry behavior, and how to safely recover from failures without sending duplicate messages or disabling your app.

OneSignal uses rate limits and error responses as safety mechanisms to protect your app from accidental overloads, duplicate sends, and retry storms.

There are three categories to understand:

* **API rate limits** return HTTP `429` errors when request volume is too high.
* **Network timeouts or temporary server failures** return `5xx` errors or no response at all.
* **Application message limits** may temporarily disable your app if too many messages are sent in a short period.

<Info>
  Most apps never hit these limits during normal usage. When they do occur, they are usually caused by retries, loops, or unexpected audience expansion.
</Info>

<Check>
  **Quick implementation checklist**

  * Expect `429`, `5xx`, and timeouts. They are normal at scale.
  * Never retry message sends without an `idempotency_key`.
  * For non-urgent retries, wait **100 seconds** before retrying.
  * API rate limits (`429`) never disable your app.
  * Only message volume limits can disable your app.
  * `POST /notifications` (create) and `DELETE /notifications` (cancel) count toward the same rate limit.
  * The [Create custom events](/reference/create-custom-events) endpoint has its own rate limit, separate from the notification endpoints.
</Check>

***

## API rate limits

API rate limits apply **per app and per endpoint**. They are evaluated when a request is received, not when a response is returned.

These limits are designed to throttle traffic, not block your app.

| Endpoint                                                                                  | Rate limit                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create message](/reference/create-message) / [Cancel message](/reference/cancel-message) | **Free plans:** 150 requests/sec/app<br />**Paid plans:** 6,000 requests/sec/app<br /><br />The `POST /notifications` and `DELETE /notifications` endpoints share the same limit. Requests count toward it regardless of method. For example, 3,000 creates + 3,000 cancels = 6,000 requests/sec on a paid plan.<br /><br />Each request can target many users or segments. |
| [Create custom events](/reference/create-custom-events)                                   | Rate-limited independently from Create Message.<br />**Request size limits:** 2,024 bytes per event · 1 MB per request body                                                                                                                                                                                                                                                 |
| Create, update, or delete users or subscriptions                                          | 1,000 requests/sec/app<br />1 request/sec per user or subscription<br />Up to 100 property updates per request                                                                                                                                                                                                                                                              |
| View endpoints (messages, templates, users)                                               | 1 request/sec/app<br />Up to 10 look-back requests/sec                                                                                                                                                                                                                                                                                                                      |
| Message History and CSV exports                                                           | Keep parallel exports under 100 GB per file                                                                                                                                                                                                                                                                                                                                 |

<Note>
  High-volume messaging should use fewer message creation requests with larger audiences instead of increasing request frequency.
</Note>

**Handling API rate limit errors (`429`):**

When you exceed an API rate limit, OneSignal returns an HTTP `429` response:

```json theme={null}
{
  "errors": ["API rate limit exceeded."]
}
```

The response includes a `Retry-After` header indicating how many seconds to wait before retrying.

**What to do when you receive a `429` error:**

1. Stop sending requests immediately.
2. Wait for the full duration specified in the `Retry-After` header.
3. Retry using exponential backoff.
4. Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for retries that send messages.

<Warning>
  Retrying before the `Retry-After` delay or retrying in tight loops can extend throttling and increase failure rates.
</Warning>

***

## Error handling and retry strategies

Retries are safe only when implemented correctly. Some failed requests may still be processing on our servers.

* Retriable errors generally include network timeouts, no responses, 429, and 5xx errors.
* Non-retryable errors include 400, 401, or 403 errors which indicate invalid input, authentication problems, or missing permissions. These are not temporary failures.

**Simple retry strategy:**

* Wait **100 seconds** before retrying.
  * This aligns with the maximum API response timeout.
  * If no response or network error occurs, the request may still be processing during this window.
* Retry **up to 3 total attempts** (original + 2 retries).
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

**Time-sensitive (advanced) retry strategy:**

* Retry using exponential backoff with jitter (for example: 2s, 4s, 8s… up to 60s).
* Cap retries to **10 total attempts** and stop after **10–15 minutes**.
* For `429` responses, treat `Retry-After` as a minimum delay: wait `max(Retry-After, backoff)`.
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

<Warning>
  Retrying message or custom event API requests without idempotency can result in duplicate messages or custom events.
</Warning>

<Accordion title="Example retry logic">
  ```text theme={null}
  attempt = 1
  max_attempts = 3

  send request with idempotency_key

  if response is success:
    stop

  if response is 429:
    wait Retry-After seconds
  elif response is 5xx or timeout:
    wait 100 seconds

  if attempt < max_attempts:
    retry with same idempotency_key
  else:
    fail safely
  ```
</Accordion>

### Retry decision guide

| Error type              | Retry? | When                 | Idempotency required |
| ----------------------- | ------ | -------------------- | -------------------- |
| `429 Too Many Requests` | Yes    | After `Retry-After`  | Yes                  |
| `5xx Server Error`      | Yes    | Backoff or 100s      | Yes                  |
| Timeout / no response   | Yes    | Immediate or delayed | Yes                  |
| `400 Bad Request`       | No     | Fix request          | No                   |
| `401 / 403`             | No     | Fix auth/permissions | No                   |

<Warning>
  Common implementation mistakes:

  * Retrying with a new idempotency key on each attempt.
  * Retrying indefinitely without a retry cap.
  * Retrying `400` or `401` errors without fixing the request.
  * Sending one request per user instead of batching audiences.
</Warning>

***

## Application message limits (app disablement)

Application message limits protect your users from receiving too many notifications in a short period of time.

**How the limit works:**

In any rolling 15-minute window, you may send up to **10 × your total number of subscribed [Subscriptions](/docs/en/subscriptions)**.

This limit is based on the total number of messages delivered, not the number of API requests.

* Sending 1 notification to 1,000 Subscriptions = 1,000 messages
* Sending 10 notifications to 1,000 Subscriptions each = 10,000 messages

The 15-minute window is rolling, not fixed.

* Messages are counted for 15 minutes after they are sent
* As time passes, older messages automatically stop counting
* You only exceed the limit if more than 10× your subscribed Subscriptions receive messages within the same 15-minute span

Example limits:

* App with 1,000 subscribed Subscriptions → up to 10,000 messages in any 15 minutes
* App with 10,000 subscribed Subscriptions → up to 100,000 messages in any 15 minutes

**Example scenarios:** App with 1,000 subscribed Subscriptions (limit: 10,000 messages per 15 minutes)

| Scenario                                                                              | Messages counted in any 15-minute period |    App disabled?    |
| ------------------------------------------------------------------------------------- | ---------------------------------------: | :-----------------: |
| At **12:00**, send 1 notification to 1,000 users                                      |                                    1,000 |          No         |
| At **12:00**, send 10 notifications to 1,000 users                                    |                                   10,000 |   Yes (hits limit)  |
| Between **12:00–12:14**, send 10,000 notifications to 1 user                          |                                   10,000 |   Yes (hits limit)  |
| Send **9,000 messages at 12:00**, then **9,000 more at 12:16**                        |                                    9,000 |          No         |
| Send **9,000 messages spread between 12:00–12:14**, then send **9,000 more at 12:15** |                                 \~18,000 | Yes (exceeds limit) |

<Note> This limit is evaluated continuously over a rolling 15-minute window, not in fixed time blocks. If any 15-minute span exceeds your limit, the app is disabled. </Note>

**What happens if the limit is exceeded:**

If your app sends more messages than allowed within a 15-minute window:

* Your app is temporarily disabled
* All app administrators receive an email notification
* A re-enable banner appears in the OneSignal Dashboard

<Warning> Only application message limits can disable your app. API rate limits (`429` errors) never disable apps. </Warning>

**What to do if your app is disabled:**

If your app is disabled, follow these steps in order:

1. Pause message sending from your backend, jobs, or automations.
2. Identify the cause, such as infinite loops, retry storms, or unexpected segment growth.
3. Log in to the OneSignal Dashboard.
4. Click **Re-enable** in the red banner at the top of the app.
5. If you need help re-enabling your app, contact `support@onesignal.com`.

***

## FAQ

### Do API rate limits disable my app?

No. API rate limits (`429` errors) only throttle your requests temporarily. Only [application message limits](#application-message-limits-app-disablement) — which track the total volume of messages delivered — can disable your app.

### What is an idempotency key and when do I need one?

An idempotency key is a unique identifier you include with a request so that retrying the same request does not create a duplicate message or event. You need one whenever you retry a `POST /notifications` or custom event request. Reuse the same key for every retry attempt. See [Idempotent API requests](/reference/idempotent-notification-requests).

### Can I increase my API rate limit?

Paid plans have higher rate limits (6,000 requests/sec vs. 150 for free plans). If you need limits beyond the paid tier, contact `support@onesignal.com` with your use case and expected volume.

### Why was my app disabled even though I didn't hit the API rate limit?

API rate limits and application message limits are separate. Your app can be disabled if the total number of messages delivered in any 15-minute window exceeds 10× your subscription count — even if every individual API request succeeded. Common causes include retry storms, runaway automations, or targeting a larger audience than intended.

***

## Related pages

<Columns>
  <Card title="Idempotent API requests" icon="rotate" href="/reference/idempotent-notification-requests">
    Prevent duplicate messages by reusing idempotency keys on retries.
  </Card>

  <Card title="Create message API" icon="paper-plane" href="/reference/create-message">
    API reference for sending push, email, SMS, and in-app messages.
  </Card>

  <Card title="Create custom event API" icon="bolt" href="/reference/create-custom-events">
    API reference for sending custom events that trigger Journeys.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="/docs/en/subscriptions">
    Understand how subscriptions are counted toward message limits.
  </Card>
</Columns>


# REST API overview
Source: https://documentation.onesignal.com/reference/rest-api-overview

Programmatic access to OneSignal messaging, user management, segments, and data exports over HTTPS with rate limiting and retry support.

The OneSignal REST API follows the [REST architecture](https://en.wikipedia.org/wiki/Representational_state_transfer) and provides programmatic access to core messaging and user features. Use the API to send push notifications, emails, and SMS, manage Users, Subscriptions, Segments, export data, and configure apps.

## Which API to use

| Goal                          | API                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| Send a push, email, or SMS    | [Create Message](/reference/create-message)                                                              |
| Add or update user data       | [Create User](/reference/create-user) / [Update User](/reference/update-user)                            |
| Target a group of users       | [Create Segments](/reference/create-segments) or use [Filters](/reference/create-message#filters) inline |
| Export analytics or user data | [CSV Export](/reference/csv-export) / [CSV of Events](/reference/export-csv-of-events)                   |
| Manage app configuration      | [Create App](/reference/create-an-app) / [Update App](/reference/update-an-app)                          |

***

## Requirements

**General**

* **HTTPS required**: All API requests must use HTTPS with **TLS 1.2 or higher** on port `443`.
* **Network access**: Firewalls or proxies must allow **outbound traffic** to `https://api.onesignal.com` on port `443`.
* **DNS TTL**: Clients must respect OneSignal’s DNS **TTL of 300 seconds** to avoid stale IP resolution.

**Incoming Traffic to OneSignal (API & SDK Requests)**

All incoming API traffic—whether from your backend, the OneSignal SDKs, or the dashboard—passes through **Cloudflare**, which serves as the global edge network.

* You may see Cloudflare IP addresses in logs.
* Cloudflare IPs may change over time.
* If you maintain a strict firewall, use Cloudflare’s official [IP ranges](https://www.cloudflare.com/ips/)

<Warning>
  Avoid allowlisting specific Cloudflare IPs, as they may change without notice.
</Warning>

**Outgoing Traffic from OneSignal (Webhooks & Event Streams)**

For features where OneSignal sends HTTP requests to your servers (such as webhooks or event streams), traffic originates from OneSignal infrastructure running on Google Cloud Platform (GCP) in the `europe-west4` region (Groningen, Netherlands).

* Allow inbound traffic from `https://api.onesignal.com`, **or**
* Use GCP’s maintained IP range list and filter by `europe-west4` region: [GCP IP ranges](https://www.gstatic.com/ipranges/cloud.json)

<Note>
  OneSignal supports [IP allowlisting](/docs/en/keys-and-ids) with REST API keys.
</Note>

***

### Platform-specific network requirements

#### FCM (Google Android and Chrome push)

* Required ports: `5228`, `443`, `5229`, and `5230`
* No IP allowlisting needed
* More info: [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

#### APNs (Apple iOS, iPadOS, Safari push)

* Required ports: `5223`, `443`, and `2197`
* Recommended servers:
  * Sandbox: `api.sandbox.push.apple.com:443`
  * Production: `api.push.apple.com:443`
  * IP range: `17.0.0.0/8`
* More info:
  * [Apple Support](https://support.apple.com/en-us/102266)
  * [APNs Developer Docs](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns?language=objc)

***

## Core API capabilities

### Send messages

See the [Create Message guide](/reference/create-message) to get started. Programmatically send:

<Columns>
  <Card title="Push Notifications" icon="bell" href="/reference/push-notification">
    Send push notifications to apps and websites.
  </Card>

  <Card title="Email" icon="envelope" href="/reference/email">
    Send transactional and promotional emails.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/reference/sms">
    Send SMS or MMS messages globally.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="/reference/start-live-activity">
    Send Live Activity updates to iOS devices.
  </Card>
</Columns>

<Note>
  For platform-specific features like personalization, throttling, and frequency capping, see the [Push](/docs/en/push), [Email](/docs/en/email-messaging), [SMS](/docs/en/sms-messaging), and [Live Activities](/docs/en/live-activities) overview guides.
</Note>

***

### Manage templates

[Templates](/docs/en/templates) are reusable push, email, and SMS messages that simplify development and improve consistency.

<Columns>
  <Card title="Create template" icon="plus" href="/reference/create-template">
    Save a reusable message layout for push, email, or SMS.
  </Card>

  <Card title="Update template" icon="pen-to-square" href="/reference/update-template">
    Modify an existing template's content or settings.
  </Card>

  <Card title="View templates" icon="eye" href="/reference/view-templates">
    List all templates in your app with their metadata.
  </Card>

  <Card title="Delete template" icon="trash" href="/reference/delete-template">
    Permanently remove a template from your app.
  </Card>
</Columns>

***

### Track custom events

[Custom events](/docs/en/custom-events) record user actions like purchases, content views, or milestones. Use them to enter users into [Journeys](/docs/en/journeys-settings) or trigger [Wait Until](/docs/en/journeys-actions) nodes.

<Card title="Create custom events" icon="bolt" href="/reference/create-custom-events">
  Record user events to trigger Journeys and track behavior.
</Card>

***

### Manage Users and Subscriptions

See the [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) guides for more details.

<Columns>
  <Card title="Create user" icon="user-plus" href="/reference/create-user">
    Create a user with optional aliases and subscriptions.
  </Card>

  <Card title="View user" icon="eye" href="/reference/view-user">
    View user details.
  </Card>

  <Card title="Update user" icon="user-pen" href="/reference/update-user">
    Modify a User's properties, tags, or aliases.
  </Card>

  <Card title="Delete user" icon="user-minus" href="/reference/delete-user">
    Permanently remove a User and all associated data.
  </Card>
</Columns>

***

### Manage Segments

[Segments](/docs/en/segmentation) group Users by filters for targeted messaging.

<Columns>
  <Card title="Create Segments" icon="plus" href="/reference/create-segments">
    Define a new Segment with filters to group Users.
  </Card>

  <Card title="Update Segment" icon="pen-to-square" href="/reference/update-segment">
    Modify a Segment's name or replace its filters.
  </Card>

  <Card title="Delete Segments" icon="trash" href="/reference/delete-segments">
    Permanently remove a Segment from your app.
  </Card>
</Columns>

<Note>
  You can also target users dynamically using [filters](/reference/create-message#filters) without creating persistent segments.
</Note>

***

### Export data

For analytics breakdowns, see [Analytics overview](/docs/en/analytics-overview).

<Columns>
  <Card title="Export CSV of subscriptions" icon="file-export" href="/reference/csv-export">
    Export all user and subscription data.
  </Card>

  <Card title="Export CSV of events" icon="file-export" href="/reference/export-csv-of-events">
    Export events like sent, received, and clicked.
  </Card>

  <Card title="View messages" icon="eye" href="/reference/view-messages">
    View message details and analytics.
  </Card>

  <Card title="View message" icon="magnifying-glass" href="/reference/view-message">
    View individual message details.
  </Card>
</Columns>

***

### Manage Apps & API Keys

OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See [Apps, orgs, & accounts](/docs/en/apps-organizations).

<Columns>
  <Card title="Create an app" icon="plus" href="/reference/create-an-app">
    Register a new app with platform credentials.
  </Card>

  <Card title="Update an app" icon="pen-to-square" href="/reference/update-an-app">
    Modify app settings or platform credentials.
  </Card>

  <Card title="View single app" icon="eye" href="/reference/view-an-app">
    Retrieve configuration and details for one app.
  </Card>

  <Card title="View multiple apps" icon="list" href="/reference/view-apps">
    List all apps in your account.
  </Card>
</Columns>

#### API key management

See [Keys & IDs](/docs/en/keys-and-ids) for more details.

<Columns>
  <Card title="Create API key" icon="key" href="/reference/create-api-key">
    Generate a new API key with specific permissions.
  </Card>

  <Card title="View API keys" icon="eye" href="/reference/view-api-keys">
    List all API keys and their permissions for your app.
  </Card>

  <Card title="Delete API key" icon="trash" href="/reference/delete-api-key">
    Revoke an API key permanently.
  </Card>

  <Card title="Update API key" icon="pen-to-square" href="/reference/update-api-key">
    Modify an API key's permissions or IP allowlist.
  </Card>
</Columns>

***

## Error handling and retries

The OneSignal API may return temporary errors such as `429` (rate limited), `5xx` (server errors), or timeouts. When this happens, the request may still be processing. If you retry failed requests, always use an `idempotency_key` and follow the recommended retry delays to avoid duplicate messages.

<Card title="Rate limits and error handling" icon="triangle-exclamation" href="/reference/rate-limits">
  Retry strategies, error definitions, and recovery steps.
</Card>

***

## FAQ

### What is the timeout for API responses?

* Default: **100 seconds**
* If you're unsure whether a request completed, use an [`idempotency_key`](/reference/idempotent-notification-requests) to safely retry.
* See [Rate limits and error handling](/reference/rate-limits) for more details.

### Do I need to download or renew certificates to call the OneSignal API?

No. The OneSignal API uses HTTPS with a publicly trusted TLS certificate managed by Cloudflare. These edge certificates renew automatically and are trusted by all major browsers, operating systems, and runtimes.

If your network pins a specific leaf certificate, it will expire and rotate every few months — this is normal Cloudflare behavior. Trust the root and intermediate CAs in the chain instead of the leaf certificate to avoid disruption.

<Accordion title="Certificate pinning details and workarounds">
  * **Best practice**: Trust the root and intermediate CAs in the chain instead of the rotating leaf certificate.
  * **If you must pin a certificate**: Pin the public key (SPKI) of the CA or use a backup key set, not the exact leaf certificate.
  * **Fetching the current certificate**: If your process requires the active leaf certificate, retrieve it directly:

  ```bash theme={null}
  SERVERNAME=api.onesignal.com
  echo -n | openssl s_client -connect $SERVERNAME:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/${SERVERNAME}_current.pem
  ```

  To retrieve the full chain, add the `-showcerts` flag to `openssl s_client`.

  See [Cloudflare SSL/TLS documentation](https://developers.cloudflare.com/ssl/get-started/) and [Cloudflare Edge Certificates documentation](https://developers.cloudflare.com/ssl/edge-certificates/) for more details.
</Accordion>

### Why am I getting a 403 Forbidden error?

A `403` response means the API key is valid but does not have permission for the requested operation. Check the following:

* **Wrong key type**: App API keys work for app-level endpoints (sending messages, managing Users). Organization API keys are required for org-level endpoints (creating apps, managing API keys). See [Keys & IDs](/docs/en/keys-and-ids) for details.
* **IP allowlisting**: If IP allowlisting is enabled on your API key, requests from IPs not on the list are denied. Verify your server's IP is included.
* **Revoked or rotated key**: If the key was recently rotated, the old key is no longer valid. Update your integration with the new key.

### Why am I getting "UnknownHostException - Unable to resolve host api.onesignal.com"?

This error means your environment cannot resolve the DNS for `api.onesignal.com`. Common causes:

* **Firewall or proxy blocking DNS**: Ensure your network allows outbound DNS queries and traffic to `api.onesignal.com` on port `443`.
* **No internet connectivity**: Verify the device or server has an active network connection.
* **DNS server misconfiguration**: Try a public DNS resolver like `8.8.8.8` (Google) or `1.1.1.1` (Cloudflare) to rule out local DNS issues.
* **Stale DNS cache**: Flush your local DNS cache and ensure your client respects the TTL of 300 seconds.


# Rotate API key
Source: https://documentation.onesignal.com/reference/rotate-api-key

POST /apps/{app_id}/auth/tokens/{token_id}/rotate
Rotate an existing App API Key (Rich Authentication Token) for a OneSignal app. Useful when a token is compromised or needs replacement without creating a new key from scratch.

## Overview

Use this API to rotate a **Rich Authentication Token** (App API Key) for a specific OneSignal app. Rotating a key revokes the current token and generates a new one under the same configuration—ideal when a token is lost or compromised but you don’t want to recreate and reconfigure it from scratch.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can rotate an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# SMS
Source: https://documentation.onesignal.com/reference/sms

POST /notifications?c=sms
Send a message using the SMS channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for SMS and MMS. See [Push notification](/reference/push-notification) or [Email](/reference/email) to send to those channels.

Ensure your [SMS setup](/docs/en/sms-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***

## Trackable links

Add trackable links to your SMS `contents` using [liquid syntax](/docs/en/using-liquid-syntax) in the format `{{'your_url' | track_link}}`.

Example:

```json JSON theme={null}
{
  "contents": {
    "en": "Hi, here's my link: {{'https://example.com' | track_link}} "
  }
}
```

In this example, the liquid syntax block will be replaced with a trackable short link and display in the message as: `1sgnl.co/XXXX`.

<Note>
  See [SMS trackable links](/docs/en/links#sms) for more details.
</Note>

***


# Start Live Activity
Source: https://documentation.onesignal.com/reference/start-live-activity

POST /apps/{app_id}/activities/activity/{activity_type}
Remotely start a Live Activity on iOS devices via OneSignal's REST API. Define the activity type, target users, and send dynamic, updatable content directly to a Live Activity interface.

## Overview

Remotely start an iOS Live Activity using OneSignal’s REST API. Live Activities provide real-time updates directly on the lock screen and Dynamic Island (on supported devices), enhancing user engagement with ongoing events like sports games, deliveries, or countdowns.

***

## How to use this API

1. Define a Live Activity in your app. See [Live Activities developer setup](/docs/en/live-activities-developer-setup) to get started.
2. Use the `activity_type` parameter to specify the type of the Live Activity UI to use.
3. Select your target audience to receive the Live Activity. Target all or individual users.
4. Generate a unique `activity_id` to track and manage your Live Activity.
5. Use the `event_attributes` parameter to initialize the Live Activity with static data.
6. Use the `event_updates` parameter to update the Live Activity with dynamic content.

### Select your target audience

Before sending a message, you need to determine who should receive it. OneSignal offers three targeting options:

1. **Aliases & Subscription IDs**: Send messages to specific users using unique identifiers such as External ID (recommended), OneSignal ID, custom alias, or subscription ID.
2. **Segments**: Target predefined user groups based on attributes and behavior.
3. **Filters**: Create custom targeting rules using user properties, such as tags, location, or activity.

<Note>
  You can only use one targeting method per message. For example, you cannot combine alias-based targeting with filters in the same request.

  See [Select your target audience](/reference/create-message#select-your-target-audience) for more information.
</Note>

### Set a unique `activity_id`

* Set a unique `activity_id` to track and manage the Live Activity. This value is crucial for maintaining a consistent reference to the Live Activity across different devices and sessions. Consider using a UUID, CUID, or NanoID for this parameter.
* Ensure that the `activity_id` is unique and consistently used for each Live Activity to avoid conflicts and ensure accurate tracking.

  ```json Example theme={null}
  {
    "activity_id": "217aae2b-42ee-4097-bc3f-b7a6e9d15b9b",
    ...
  }
  ```

<Info>
  See [Live Activities developer setup](/docs/en/live-activities-developer-setup) guide for more information.
</Info>

### Set `event_attributes` to initialize the Live Activity

Set default/static data to display in the Live Activity upon start.

```json Example theme={null}
{
  "event_attributes": {
  	"awayTeam": "Away Team Name",
    "homeTeam": "Home Team Name"
  }
}
```

### Set `event_updates` for dynamic content

The content used to update a running Live Activity. The object must conform to the `ContentState` interface defined within your app's Live Activity. See [Live Activities developer setup](/docs/en/live-activities-developer-setup).

Ensure that the `event_updates` object matches the [`ContentState`](https://developer.apple.com/documentation/activitykit/activityattributes/contentstate#) interface exactly as defined in your Live Activity implementation. Inconsistencies can cause Live Activities to fail to display.

```json Example theme={null}
{
  "event_updates": {
    "quarter": 1,
    "homeScore": 70,
    "awayScore": 78,
    "inTimeout": false
  }
}
```

***


# Transfer Subscription
Source: https://documentation.onesignal.com/reference/transfer-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/owner
Transfer a Subscription to a different user within the same OneSignal app. Useful for associating existing Subscriptions like push, email, or SMS with a new or updated user identity.

## Overview

Use this API to transfer a Subscription from one user to another within the same OneSignal app.

It is highly recommended to use our web and mobile SDKs to set and update the External ID with the `login` method instead of this API. Your app or website may continue to be setting the wrong External ID. Make sure to only use this API if you are setting the same External ID within your app or website.

This is typically used when:

* You want to reassign an existing push, email, or SMS Subscription to a new or updated user.
* You have changed how you're identifying users (e.g., migrating from anonymous to known users).

<Note>
  - Subscriptions **cannot be transferred across different OneSignal apps**.
  - For email and SMS Subscriptions, you can instead create new ones using [Create User](/reference/create-user).
  - For push Subscriptions, platform limitations may apply—see [Subscriptions](/docs/en/subscriptions#importing-push-subscriptions) for details.
</Note>

***

## How to Use This API

### Required Path Parameter: `subscription_id`

You must know the `subscription_id` of the subscription to be transferred. This is a unique UUID assigned by OneSignal.

### Required Body Parameter: `identity` (object)

This specifies the user the subscription should be moved to. Only **one alias** should be used per request. You can identify the target user using one of:

* `external_id` (recommended)
* `onesignal_id`
* A [custom alias](/docs/en/aliases)

***


# Unsubscribe email with token
Source: https://documentation.onesignal.com/reference/unsubscribe-with-token

POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
Unsubscribe an email address from future messages by calling this API from your custom unsubscribe page. Automatically disables the associated email subscription using a token-based approach.

## Overview

Use this API to unsubscribe an email address directly from your custom unsubscribe landing page. It is ideal when building branded opt-out experiences and enables you to track which email caused the unsubscribe.

When invoked, this endpoint:

* Sets the email Subscription's `enabled` property to `false`
* Prevents further messages from being sent to the email address unless explicitly overridden (see [Overriding unsubscribes](/reference/email#body-include-unsubscribed))
* Email Subscriptions can be re-subscribed using the [Update Subscription](/reference/update-subscription) API

<Tip>
  For instructions on setting up a custom unsubscribe page, see [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page).
</Tip>

***

## How to Use This API

### Step 1: Set Up Your Custom Unsubscribe Page

Follow the guide to [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page). You'll add a custom unsubscribe URL to your email templates using Liquid syntax.

Example URL in your email template:

```liquid theme={null}
https://yourdomain.com/unsubscribe?app_id={{ app_id }}&notification_id={{ notification_id }}&token={{ token }}
```

### Step 2: Extract the Parameters

When a user clicks the unsubscribe link, your custom unsubscribe page should extract the following from the URL:

* `app_id`: OneSignal app ID
* `notification_id`: The ID of the specific email message sent
* `token`: The email token, a secure reference to the subscription

### Step 3: Call the API

When the user confirms they want to unsubscribe (e.g., clicks a button on your unsubscribe page), make a POST request to this endpoint:

```
POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
```

Example Request (JavaScript):

```js theme={null}
fetch("https://api.onesignal.com/apps/your-app-id/notifications/your-notification-id/unsubscribe?token=abc123xyz", {
  method: "POST"
});
```

<Info>
  No request body or authentication is required. The token acts as a secure identifier.
</Info>

<Note>
  * This API only works for email subscriptions.
  * It should only be used from a server or frontend context that you control (e.g., your custom unsubscribe page).
  * Once unsubscribed, the email address will not receive future emails from your app unless resubscribed.
</Note>

***


# Update an app
Source: https://documentation.onesignal.com/reference/update-an-app

PUT /apps/{app_id}
Use to update the name or push platform configuration of an existing app. This guide explains required parameters and platform-specific update rules

## Overview

Use this API to programmatically update an existing OneSignal app. This is useful when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

***

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Warning>
  If you change your FCM Service Account JSON file to a different Firebase project, your Android Subscriptions tied to the current project will become invalid. They will not be able to receive push notifications until they open your app again with this new FCM Service Account JSON file.
</Warning>

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need help Base64 encoding your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns). **You will likely never need to update these parameters if set correctly during app creation**:

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates). **These must be updated every year which is why we recommend using p8 authentication**:

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Update API key
Source: https://documentation.onesignal.com/reference/update-api-key

PATCH /apps/{app_id}/auth/tokens/{token_id}
Update a Rich Authentication Token (App API Key) for a OneSignal app. Modify the token's name or IP allowlist settings using your Organization API Key.

## Overview

Use this API to update the properties of a specific **Rich Authentication Token** (App API Key) for a OneSignal app. You can change the name, IP allowlist mode, or the list of allowed IPs. This is helpful for adjusting access rules without needing to recreate the key.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Update Live Activity
Source: https://documentation.onesignal.com/reference/update-live-activity-api

POST /apps/{app_id}/live_activities/{activity_id}/notifications
Update or terminate running iOS Live Activities using OneSignal’s Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

## Overview

Update or terminate running iOS Live Activities using our REST API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

Before using this API, ensure your app is properly configured by following the [Live Activities developer setup](/docs/en/live-activities-developer-setup).

## How to Use this API

1. Select the Live Activity to update by specifying its `activity_id` in the URL. This is set when using the:

* [Start Live Activity API](/reference/start-live-activity)
* [Triggering it in-app](/docs/en/live-activities-developer-setup).
* [`LiveActivities.enter` SDK method](/docs/en/mobile-sdk-reference#enter)

2. Update the state of the Live Activity by setting the `event_updates` parameter to a JSON object that matches the structure of the `ActivityAttributes.ContentState` struct defined in your Live Activity widget extension.

3. When ready to terminate the Live Activity:

* Set the `event` parameter to `end`
* Include a `dismissal_date` if you want the Live Activity to be dismissed in less than 4 hours.
* Set the `dismissal_date` to a time in the past to dismiss the Live Activity immediately. User must have clicked "Allow" for the Live Activity to be removed programmatically.

<Warning>
  Once a Live Activity `activity_id` is ended, you cannot update it. This includes changing the `dismissal_date` or `event` parameter.

  If the Live Activity is not being dismissed immediately, it is either because:

  * The `activity_id` has already been ended.
  * The user has not clicked "Allow" for the Live Activity to be removed programmatically.
</Warning>

***


# Update segment
Source: https://documentation.onesignal.com/reference/update-segment

PATCH /apps/{app_id}/segments/{segment_id}
Update an existing segment's name and/or filters. The name parameter is always required. When filters are provided, all existing filters are replaced with the new ones.

## Overview

Update an existing segment's name and/or filters. This API allows you to modify [Segments](/docs/en/segmentation) programmatically without having to delete and recreate them.

<Note>
  The `name` parameter is always required, even if you're not changing it. When filters are provided, all existing filters are **replaced** with the new ones. Omit the `filters` parameter to keep existing filters intact. The `filters` array cannot be empty—if provided, it must contain at least one filter.
</Note>

***

## How to use this API

### Update segment name only

To update just the segment name without changing filters:

```json theme={null}
{
  "name": "New Segment Name"
}
```

### Update segment description

Update the optional `description` (max 255 characters). Pass an empty string to clear the existing description; omit the field to leave it unchanged.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION"
}
```

### Update segment filters

To update the segment filters (this replaces all existing filters), provide the `name` (required) and `filters`:

```json theme={null}
{
  "name": "Updated Segment",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "5"},
    {"operator": "AND"},
    {"field": "tag", "key": "subscription", "relation": "=", "value": "premium"}
  ]
}
```

### Filter syntax

The filter syntax is identical to the [Create segment](/reference/create-segments) API. Available filters include:

* `tag` - Filter by Tags
* `last_session` - Filter by last active time
* `first_session` - Filter by first session time
* `session_count` - Filter by number of sessions
* `session_time` - Filter by total usage duration
* `language` - Filter by user language
* `app_version` - Filter by app version
* `location` - Filter by GPS coordinates
* `country` - Filter by country

Use `AND` and `OR` operators to combine filters:

```json theme={null}
{
  "name": "Engaged Premium Users",
  "filters": [
    {"field": "tag", "key": "plan", "relation": "=", "value": "premium"},
    {"operator": "AND"},
    {"field": "session_count", "relation": ">", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "vip", "relation": "=", "value": "true"}
  ]
}
```

***

## Response

### Success response

```json theme={null}
{
  "success": true,
  "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19"
}
```

### Error responses

| Status Code | Description                                                                              |
| ----------- | ---------------------------------------------------------------------------------------- |
| 400         | Bad request - Invalid filters, duplicate segment name, or segment used by active Journey |
| 403         | Forbidden - API not available for your plan                                              |
| 404         | Not found - Segment does not exist                                                       |
| 429         | Rate limit exceeded                                                                      |

***


# Update Subscription by ID
Source: https://documentation.onesignal.com/reference/update-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}
Update properties on an existing OneSignal subscription using its subscription_id. Commonly used to enable or disable a subscription when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties by `subscription_id`.

This endpoint is primarily used by the OneSignal SDK to manage subscription state.

Most external use cases are better served by the [Update Subscription by token](/reference/update-subscription-by-token) API, which can use the Email Address or Phone Number as the `token` or the [Update User](/reference/update-user) API, which allows for updating user-level data.

<Note>
  For **email opt-outs**, it's recommended to use the [Unsubscribe Email (with token)](/reference/unsubscribe-with-token) API instead. This avoids the need to store or manage the `subscription_id`.
</Note>

***

## How to use this API

**Required:** `subscription_id`

To update a subscription, you **must know the `subscription_id`**. This is a UUID generated by OneSignal and is immutable.

* You can retrieve a subscription ID by querying the [User object](/docs/en/users).
* See the [Subscriptions](/docs/en/subscriptions) guide for an explanation of how subscription IDs are generated and used.

<Note>
  You **cannot** update the `type` of a Subscription. If the `type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the Subscription with the correct type.
</Note>

***


# Update Subscription by token
Source: https://documentation.onesignal.com/reference/update-subscription-by-token

PATCH /apps/{app_id}/subscriptions_by_token/{token_type}/{token}
Update properties on an existing Subscription using its token. Commonly used to enable or disable subscription status when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties.

This API can be useful if:

* You only know the `token` and `token_type` and want to update metadata or status flags directly.
* You are managing Subscription status outside of the OneSignal SDK. Like with a [custom preference page or unsubscribe page](/docs/en/create-custom-unsubscribe-page).

***

## How to use this API

To update a Subscription, you must know the `token_type` and the `token`.

The `token_type` is the [Subscription's type](/docs/en/server-sdk-reference#subscription-types) (e.g., `Email`, `SMS`, `iOSPush`, `AndroidPush`, etc.).

The `token` is the push token, email address, or phone number associated with the Subscription.

Ensure the `token` is valid and correctly formatted for the chosen `token_type`.

* **Email format:** Should be a valid email address that you confirmed can receive emails.
* **SMS format:** Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164).
* **iOSPush APNS token format:** 64 characters, hexadecimal characters only (0-9,a-f).
* **AndroidPush FCM token format:** Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.

<Warning>
  You **cannot** update the `token_type` and `token` of a Subscription with this API. If the `token_type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the subscription with the correct type.

  If multiple Subscriptions are found for the `token` and `token_type`, an `Http 400` error is returned with a list of subscription IDs that match the criteria.
</Warning>

***


# Update template
Source: https://documentation.onesignal.com/reference/update-template

PATCH /templates/{template_id}?app_id={app_id}
Update existing OneSignal message templates for push, email, or SMS. Changes apply immediately across dashboard and API usage via the `template_id` reference.

## Overview

This endpoint allows you to update an existing push, email, or SMS template in your OneSignal app. Once updated, the changes are applied immediately and reflected across both the Dashboard and API when using the associated `template_id`.

Templates are updated using the same structure as when [creating templates](/reference/create-template).

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

To update a template, you must supply:

* Your **OneSignal App ID** found in [Keys & IDs](/docs/en/keys-and-ids).
* The **Template ID**

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***

## Channel-Specific Requirements

### Push Templates

* The `contents` property must use the `en` (English) key along with other languages you want to support.
* All [Push Notification Properties](/reference/push-notification) are valid.
* All platforms are enabled by default. To limit, explicitly enable desired ones (e.g., `isAndroid: true` disables iOS and Web).

### Email Templates

* Set `isEmail: true`
* Include `email_subject` and `email_body`
* All [Email Channel Properties](/reference/email) are supported.

### SMS Templates

* Set `isSMS: true`
* All [SMS Channel Properties](/reference/sms) are supported.

***


# Update user
Source: https://documentation.onesignal.com/reference/update-user

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}
Modify a user's properties.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint updates user-level properties for an existing user in your OneSignal app.

* To change a user's `identity` like `external_id` or custom [Aliases](/docs/en/aliases), use the [Create alias](/reference/create-alias) and [Delete alias](/reference/delete-alias) APIs.
* To manage a user's `subscriptions`, use the [Create Subscription by alias](/reference/create-subscription) or [Create user](/reference/create-user) APIs.

***

## How to use this API

You must supply an alias in the request path:

* `alias_label`: The type of identifier (e.g., `external_id`, `onesignal_id`, or a custom alias label).
* `alias_id`: The corresponding value for that label.

See [Users](/docs/en/users) and [Aliases](/docs/en/aliases) for more info.

***


# View an app
Source: https://documentation.onesignal.com/reference/view-an-app

GET /apps/{app_id}
View the details of a single OneSignal app

## Overview

Use this API to retrieve metadata and platform configuration for a single OneSignal app associated with your account. This includes app names, App ID, Subscription counts, timestamps, and push platform credentials (Android/FCM, iOS/APNS, Web Push, Safari), making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

***

## How to use this API

To retrieve your app, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View API keys
Source: https://documentation.onesignal.com/reference/view-api-keys

GET /apps/{app_id}/auth/tokens
View the details of all of your current app API keys (Rich Authentication Token) for a single OneSignal app.

## Overview

This API is helpful for auditing and managing the API keys (Rich Authentication Tokens) associated with an app. It returns metadata for each token, including:

* Token name and ID
* IP allow list mode and associated CIDR ranges (if any)
* Creation and last updated timestamps

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

***


# View apps
Source: https://documentation.onesignal.com/reference/view-apps

GET /apps
Retrieve a list of all OneSignal apps associated with your account, including key app details like name, App ID, subscription counts, and timestamps. Useful for managing multiple apps through the OneSignal API.

## Overview

Use this API to retrieve metadata for all OneSignal apps associated with your account. This includes app names, App IDs, subscription counts, and timestamps, making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

<Warning>
  This API is limited to return a maximum of 1000 Apps. If you need access to more, then you should store the `app_id` and `name` for each of your apps on your own server to look up with the [View an app](/reference/view-an-app) API to get data for each app separately. Also, if you need to delete apps, then you can provide the `app_id` and `name` to OneSignal Support and ask for these to be deleted.
</Warning>

***

## How to use this API

To retrieve your apps, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View player
Source: https://documentation.onesignal.com/reference/view-device

GET https://onesignal.com/api/v1/players/{player_id}

Retrieve a single player record (Subscription) data registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `player_id` | string | Yes      | The OneSignal ID of the device. |

***

## Query Parameters

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `app_id`  | string | Yes      | Your OneSignal App ID. |

***

## Headers

| Header          | Value                            | Required | Description                        |
| --------------- | -------------------------------- | -------- | ---------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal LegacyREST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players/player_id_string?app_id=your_app_id HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json{ theme={null}
  "id": "player_id_string",
  "identifier": "push_token_or_email",
  "session_count": 5,
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_os": "14.4",
  "device_type": 1,
  "tags": {
    "level": "10",
    "user_type": "free"
  },
  "last_active": 1625253300,
  "created_at": 1625249800,
  "invalid_identifier": false,
  "external_user_id": "user123"
}
```

### Response Fields

| Field                | Type      | Description                                             |
| -------------------- | --------- | ------------------------------------------------------- |
| `id`                 | string    | OneSignal player ID.                                    |
| `identifier`         | string    | Push token, email, or phone number.                     |
| `session_count`      | integer   | Number of sessions associated with this device.         |
| `language`           | string    | Language set on the device (e.g., "en").                |
| `timezone`           | integer   | Time zone offset in seconds.                            |
| `game_version`       | string    | Version of your app the device is running.              |
| `device_os`          | string    | Operating system version.                               |
| `device_type`        | integer   | Numeric code for platform (0 = iOS, 1 = Android, etc.). |
| `tags`               | object    | Custom tags set on the device.                          |
| `last_active`        | timestamp | Last time the user was active (Unix timestamp).         |
| `created_at`         | timestamp | When the device record was created.                     |
| `invalid_identifier` | boolean   | Whether the push token or identifier is invalid.        |
| `external_user_id`   | string    | Your internal user ID mapped to this device.            |

***

## Errors

* 400 Bad Request – Missing or invalid parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied for this app or resource.
* 404 Not Found – The specified player\_id does not exist.

***


# View players
Source: https://documentation.onesignal.com/reference/view-devices

GET `https://onesignal.com/api/v1/players?app_id={app_id}&limit={limit}&offset={offset}`

Retrieve up to 80,000 player records (Subscriptions) registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Query Parameters

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `app_id`  | string | Yes      | Your OneSignal App ID.                                 |
| `limit`   | int    | No       | Number of entries to return (max 300, default is 300). |
| `offset`  | int    | No       | Result offset for pagination.                          |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players?app_id=your_app_id&limit=100&offset=0 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json theme={null}
{
  "total_count": 6,
  "offset": 0,
  "limit": 300,
  "players": [
    {
      "id": "player_id_1",
      "identifier": "push_token_or_email",
      "session_count": 3,
      "language": "en",
      "timezone": -28800,
      "game_version": "1.0",
      "device_os": "15.0",
      "device_type": 1,
      "tags": {
        "level": "15",
        "user_type": "free"
      },
      "last_active": 1625253300,
      "created_at": 1625249800,
      "invalid_identifier": false,
      "external_user_id": "user123"
    }
  ]
}
```

### Response Fields

| Field                        | Type    | Description                                  |
| ---------------------------- | ------- | -------------------------------------------- |
| `total_count`                | integer | Total number of devices for the app.         |
| `offset`                     | integer | Current pagination offset.                   |
| `limit`                      | integer | Number of devices returned in this response. |
| `players`                    | array   | List of device objects.                      |
| `players[].id`               | string  | Unique OneSignal player ID.                  |
| `players[].identifier`       | string  | Push token, email, or phone number.          |
| `players[].tags`             | object  | Custom tags set on the device.               |
| `players[].external_user_id` | string  | Your internal user ID.                       |

***

## Errors

* 400 Bad Request – Invalid query parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access not allowed for this app or key.

***


# View message
Source: https://documentation.onesignal.com/reference/view-message

GET /notifications/{message_id}?app_id={app_id}
View the details of a single message and the Outcomes associated with it.

## Overview

The View message API allows you to fetch data from a single push, email, or SMS message at a time. If you want to get multiple messages at a time, use the [View messages](/reference/view-messages) API. In most cases, you will likely want to use [Event Streams](/docs/en/event-streams) instead.

Currently this API does not provide Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are only **accessible 30 days after creation**; however, messages sent using the OneSignal dashboard are accessible for the app's lifetime.

See our [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and (after giving your users some time to interact with the message) pull the data if desired.

For example, if you send a message targeting the `include_aliases` parameter, the response will include the aliases you set. If you send with the `included_segments` parameter, then the response will only provide the segments you set. When targeting segments or filters, you can use the [Export audience activity CSV](/reference/export-csv-of-events) API to get the user event data.

To view outcome data for the message, you must include the `outcome_name` parameter with the name of the outcome you want to fetch, along with the accompanying aggregation type (.count or .sum), for example: `os__click.count`. For more information on outcome definitions, see [View Outcomes](/reference/view-outcomes).

***


# View messages
Source: https://documentation.onesignal.com/reference/view-messages

GET /notifications?app_id={app_id}&limit={limit}&offset={offset}&kind={kind}&template_id={template_id}&time_offset={time_offset}
View the details for a collection of messages.

## Overview

The View messages API fetches data for up to 50 push, email, or SMS messages at a time. To fetch a single message, use the [View message](/reference/view-message) API. In most cases, use [Event Streams](/docs/en/event-streams) instead.

This API does not return Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are **retained for 30 days** after creation; messages sent through the OneSignal dashboard are retained for the app's lifetime.

See [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

Use time-offset pagination for sequential pulls of all messages, and standard pagination for ad-hoc queries. For ETL or bulk export pipelines, use [Event Streams](/docs/en/event-streams) instead.

Filter results to a specific message kind or template using the `kind` and `template_id` query parameters. Both filters work with either pagination style.

### Optimized pagination with time offset

To efficiently retrieve all available messages for an app, use `time_offset`-based pagination. When `time_offset` is specified, the sort order changes from descending to ascending — the oldest messages appear first based on the [`send_after` date](/reference/create-message#send-after).

#### Accepted `time_offset` values

* ISO 8601 formatted timestamp — for example, `2025-01-01T00:00:00.000Z` (January 1, 2025, at 00:00 UTC).
* Opaque cursor token (Base64-encoded) — provided in the API response as `next_time_offset`.

<Steps>
  <Step title="Initial fetch">
    To fetch messages from a specific date onward, set `time_offset` to an ISO 8601 formatted timestamp. For example, to retrieve messages sent since January 1, 2025: `time_offset=2025-01-01T00:00:00.000Z`.

    <Note>
      * `time_offset` cannot be used with the standard `offset` parameter.
      * `time_offset` excludes messages that match the exact timestamp to avoid duplicates.
      * The response includes `next_time_offset`, a cursor token for the next page. No decoding required. For example: `"next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="`
    </Note>
  </Step>

  <Step title="Fetch additional pages">
    Use `next_time_offset` from the previous response as the `time_offset` value in the next request. For example: `time_offset=MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw==`.
  </Step>

  <Step title="Continue until completion">
    Repeat the request until an empty `notifications` array is returned, indicating all messages have been fetched.
  </Step>

  <Step title="Handling new messages">
    Because results are sorted ascending, new messages are added to the end. To resume fetching from where you left off, reuse the last `next_time_offset` that returned an empty response.
  </Step>
</Steps>

### Standard pagination

Use the `limit` and `offset` parameters to page through notifications for an app. The maximum result size is 50, and the default `limit` is `50`. Use `limit` to specify the result size and `offset` to increment by the limit value with each request.

For example, the first request uses `offset=0`, the second `offset=50`, the third `offset=100`, and so on.

Standard pagination is convenient for ad-hoc queries but degrades as the `offset` value grows. For sequential pulls of all messages, use time-offset pagination.

***


# View outcomes
Source: https://documentation.onesignal.com/reference/view-outcomes

GET /apps/{app_id}/outcomes?outcome_names={outcome_names}&outcome_time_range={outcome_time_range}&outcome_platforms={outcome_platforms}&outcome_attribution={outcome_attribution}
View and export push notification outcome metrics such as clicks, conversions, and custom events.

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

## Overview

Use this API to retrieve Outcome metrics associated with your OneSignal app, including push notification interactions and custom-defined events. Outcomes include data points like:

* **Clicks**: Number of users who clicked on a push.
* **Confirmed Deliveries**: Number of confirmed message deliveries.
* **Session Durations**: Number of sessions initiated.
* **Custom Events**: Actions like purchases, form submissions, or any event your app tracks via custom Outcome names.

For details on configuring custom Outcomes, refer to the [Outcomes documentation](/docs/en/custom-outcomes).

<Info>
  Outcomes are stored for approximately 30 days. To retain this data, you should regularly export it before it expires.
</Info>

***

## How to use this API

This API allows you to filter and aggregate Outcome data using several query parameters.

### `outcome_names`

Specify one or more Outcome names with an aggregation type suffix (`.count` or `.sum`).

**Default Outcome names:**

* `os__click.count` – Push notification clicks.
* `os__confirmed_delivery.count` – Confirmed deliveries.
* `os__session_duration.count` – Total sessions.

**Custom Outcome names:**

* You can track any custom event name (e.g. `Purchase`, `Signup`).
* If the custom name contains a comma, include only one name per request to avoid parsing issues.
* Example: `outcome_names=os__click.count,Purchase.count`

### `outcome_time_range`

The time range values can be one of the following:

* `1h` = (default) the last 1 hour data.
* `1d` = the last 1 day data.
* `1mo` = the last 1 month data.

### `outcome_platforms`

Maps to the subscription type property. Default is data from all platforms enabled for your OneSignal App.

| `device_type` | `type`      |
| ------------- | ----------- |
| 0             | iOSPush     |
| 1             | AndroidPush |
| 2             | FireOSPush  |
| 5             | ChromePush  |
| 8             | FirefoxPush |
| 11            | Email       |
| 14            | SMS         |
| 17            | SafariPush  |

Example: `outcome_platform=0` for iOS `outcome_platform=17,8` for Safari and Firefox.

### `outcome_attribution`

The way in which the Outcome occurred:

* `direct` = the Outcome occurred when the user interacted with the message. Some Outcomes only have `direct` attribution like `os__click` and `os__confirmed_delivery` because they only occur as the direct result of the message.
* `influenced` = the Outcome occurred within the Time Window of the message being sent, but the user never interacted with the message. See [Outcomes](/docs/en/custom-outcomes) for details.
* `unattributed` = the Outcome occurred without a direct or influenced attribute.
* `total` = (default) the sum of direct+influenced+unattributed.

***


# View segment
Source: https://documentation.onesignal.com/reference/view-segment

GET /apps/{app_id}/segments/{segment_id}
Retrieve details for a single segment by its ID, including subscriber count and optionally segment metadata and filters.

## Overview

Retrieve details for a single segment by its ID. By default, this endpoint returns only the subscriber count. Use the optional `include-segment-detail` parameter to also retrieve segment metadata and filters.

<Note>
  The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard.
</Note>

<Warning>
  **User-based segments not supported**: Segments containing message event or custom event filters (user-based segments) are not yet supported via this API. Attempting to fetch these segments will return a 400 error. These segments can only be managed through the dashboard UI.
</Warning>

***

## How to use this API

### Basic usage

By default, this endpoint returns only the subscriber count for the segment:

```json theme={null}
{
  "subscriber_count": 12345
}
```

### Include segment details

To retrieve full segment details including metadata and filters, set `include-segment-detail=true`:

```
GET /apps/{app_id}/segments/{segment_id}?include-segment-detail=true
```

This returns the subscriber count along with a `payload` object containing segment details:

<CodeGroup>
  ```json Simple filter theme={null}
  {
    "subscriber_count": 12345,
    "payload": {
      "id": "4414c404-56a3-11ed-9b6a-0242ac120002",
      "name": "Subscribed Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {
          "field": "session_count",
          "relation": ">",
          "value": "5"
        }
      ]
    }
  }
  ```

  ```json With AND/OR operators theme={null}
  {
    "subscriber_count": 5678,
    "payload": {
      "id": "5525d515-67b4-22fe-0c7b-1353bd231113",
      "name": "Engaged Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {"field": "session_count", "relation": ">", "value": "2"},
        {"operator": "AND"},
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "last_session", "relation": "<", "hours_ago": "24"}
      ]
    }
  }
  ```
</CodeGroup>

### Filters format

The `filters` array uses the **same format** as the [Create segment](/reference/create-segments) API. This means you can:

* Read filters from this endpoint
* Modify them as needed
* Use them directly with the [Update segment](/reference/update-segment) or [Create segment](/reference/create-segments) APIs

The array contains filter objects and operator objects:

**Filter object** - defines a condition:

| Field                   | Type    | Description                                                                                                                                         |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field`                 | string  | The filter type: `tag`, `last_session`, `first_session`, `session_count`, `session_time`, `language`, `app_version`, `location`, `country`, `email` |
| `relation`              | string  | The comparison operator: `>`, `<`, `=`, `!=`, `exists`, `not_exists`, `in_array`, `not_in_array`, `time_elapsed_gt`, `time_elapsed_lt`              |
| `value`                 | string  | The filter value (for most filter types)                                                                                                            |
| `key`                   | string  | The filter key (required for `tag` filters)                                                                                                         |
| `hours_ago`             | string  | Hours ago value (for `last_session`/`first_session` filters)                                                                                        |
| `radius`, `lat`, `long` | string  | Location parameters (for `location` filters)                                                                                                        |
| `unsupported_in_api`    | boolean | If `true`, this filter cannot be used with Create/Update segment APIs (see note below)                                                              |

**Operator object** - combines filters:

| Field      | Type   | Description                                                                        |
| ---------- | ------ | ---------------------------------------------------------------------------------- |
| `operator` | string | Either `AND` or `OR`. Filters connected with `AND` have higher priority than `OR`. |

<Warning>
  Some segments created via the dashboard UI may contain filter types not supported by the public API (e.g., `message_event`, `custom_event`). These filters will include `unsupported_in_api: true`. You cannot use these filters when creating or updating segments via the API.
</Warning>

### Payload fields

| Field         | Type           | Description                                                                         |
| ------------- | -------------- | ----------------------------------------------------------------------------------- |
| `id`          | string         | The unique identifier for the segment (UUID v4).                                    |
| `name`        | string         | The segment name (max 128 characters).                                              |
| `description` | string \| null | Human-readable description for the segment (max 255 characters). `null` when unset. |
| `created_at`  | integer        | Unix timestamp when the segment was created.                                        |
| `source`      | string         | The source of the segment: `default`, `custom`, or `quickstart`.                    |
| `filters`     | array          | Array of filter and operator objects that define the segment criteria.              |

***


# View segments
Source: https://documentation.onesignal.com/reference/view-segments

GET /apps/{app_id}/segments
Retrieve a list of segments associated with a specific OneSignal app. Useful for programmatically accessing segment metadata such as name, creation date, and status.

## Overview

Retrieve a list of segments associated with a specific OneSignal app. This is helpful when you want to access segment metadata programmatically instead of using the OneSignal Dashboard UI.

<Warning>
  This endpoint only retrieves existing segment metadata. It does not provide the segment filters or user data.
</Warning>

***


# View template
Source: https://documentation.onesignal.com/reference/view-template

GET /templates/{template_id}?app_id={app_id}
Retrieve the details of a specific message template in your OneSignal app using its template ID. This API returns the template content, target channel, and timestamps for creation and last update.

## Overview

This endpoint returns metadata and content for a single template, including:

* Template body/content
* Target delivery channel (e.g., push, email, SMS)
* Creation and last updated timestamps

This is useful for inspecting existing templates before using or updating them.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Required parameters:

* `app_id` (query param): Your OneSignal App ID.
* `template_id` (path param): The unique ID of the template.

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# View templates
Source: https://documentation.onesignal.com/reference/view-templates

GET /templates?app_id={app_id}&limit={limit}&offset={offset}
Retrieve a paginated list of message templates from your OneSignal app. This endpoint returns summary information for each template, including ID, name, creation, and update timestamps.

## Overview

Use this endpoint to retrieve a list of message templates associated with a specific OneSignal app. The response provides summary information only:

* `template_id`
* `name`
* `created_at`
* `updated_at`

<Note>
  This endpoint does **not** return full template content such as message bodies, channel properties, or delivery configuration. For detailed template data, use the [View Template](/reference/view-template) endpoint.
</Note>

***

## How to Use This API

### Required Parameters

* **`app_id`** (query param): The OneSignal App ID whose templates you want to retrieve.

### Optional Parameters

* **`limit`** (query param): Number of templates to return (default: `50`, maximum: `50`).
* **`offset`** (query param): Number of templates to skip. Use for pagination.

### Pagination Example

If your app has 125 templates and you're using the default limit of 50:

1. First request (first 50 templates):\
   `GET /templates?app_id={app_id}&offset=0`

2. Second request (next 50 templates):\
   `GET /templates?app_id={app_id}&offset=50`

3. Third request (final 25 templates):\
   `GET /templates?app_id={app_id}&offset=100`

Repeat the request while adjusting the `offset` until you've retrieved all templates.

***


# View user
Source: https://documentation.onesignal.com/reference/view-user

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}
Retrieve a user including aliases, properties, and subscriptions.

## Overview

* Use this API to retrieve a user's full profile, including identity aliases, user properties, and messaging subscription details across channels.
* This is helpful for verifying user data, debugging subscription issues, or syncing OneSignal user data with your internal systems.

For detailed concepts and guides, see [Users](/docs/en/users), [Subscriptions](/docs/en/subscriptions), and [Aliases](/docs/en/aliases) documentation.

## How to use this API

To look up a user, you must provide both an `alias_label` and an `alias_id`. In most cases, your `external_id` will serve as the `alias_label`, and its value will be passed as the `alias_id`. While you may use a custom alias, we strongly recommend setting and using the `external_id` as your primary user identifier for consistency across platforms.

To retrieve a user using their OneSignal ID, set the `alias_label` to `onesignal_id`. **Note**: When querying with any alias other than `onesignal_id`, authentication is required.

***


# Changelog
Source: https://documentation.onesignal.com/release-notes/changelog

Learn about the latest updates to OneSignal.

Follow along with updates across OneSignal. We're launching new features and improving our product all the time!

<Update label="June 18 2026">
  **AI-assisted SDK installation updated and expanded**

  * AI install prompts have been rewritten and expanded to cover Android, iOS, React Native, Flutter, and Web SDKs.
  * Paste a single ready-made prompt into your AI coding assistant (Cursor, Claude, Copilot, or similar) and the assistant installs the SDK, drops in initialization code, and configures push and in-app messaging automatically.
  * No deep development experience required — marketers and non-technical users can complete SDK setup in minutes.
  * Prompt instructions were revised to fix errors identified during internal testing, so generated integrations are more accurate.
  * Available to all new sign-ups with no enablement required; requires an AI coding tool and access to the app codebase.
</Update>

<Update label="June 15 2026">
  **Extended `in_array` and `not_in_array` relations to the Device Type filter**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `device_type` filter field. Use them to match against a comma-separated list of device types in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "device_type", "relation": "in_array", "value": "iOS,Android"},
    {"operator": "AND"},
    {"field": "device_type", "relation": "not_in_array", "value": "Email"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="June 15 2026">
  **RCS editor experience improvements**

  We've improved how you build and send RCS, giving you a more intuitive editor, clearer approval visibility, and a more graceful SMS fallback experience:

  * **See carrier approval status in settings.** Each sender resource's carrier approval status is now visible at **Settings > SMS > Senders**, so you can track where each carrier stands in the approval process without leaving the dashboard.
  * **Select a sender per RCS template.** In Templates you now choose a specific sender instead of relying on a single global default, improving how RCS sends within Journeys and giving you automations for multiple SMS use cases.
  * **A more intuitive editor.** The composer automatically shows the right editor for the selected sender — the RCS editor for senders with an RCS resource, and the SMS editor for SMS-only senders.
  * **Text only RCS.** A new Text only content type sends plain branded RCS text.

  When a sender gains an approved RCS sending resource, OneSignal automatically prefers RCS for existing automations on that sender, mapping your existing SMS content to RCS so there's no manual rework.

  Available for all customers contracted for RCS. See [RCS messaging](/docs/en/rcs-messaging) for details.
</Update>

<Update label="June 8 2026">
  **Segment editor improvements: multi-value filters, copy filters, and filter JSON**

  Building segments in the dashboard is now faster and more flexible:

  * **Match multiple values in one filter.** The Language, Country, App Version, and User Tag filters now support the "is any of" and "is not any of" relations, so you can match a list of values in a single filter instead of chaining several filters with OR.
  * **Copy filters and filter groups.** Duplicate an individual filter or an entire filter group from the editor to reuse its configuration without rebuilding it by hand.
  * **View and copy filter JSON.** Open the filter JSON panel to see the REST API representation of your segment's filters, then copy it to use directly in the [Create segment](/reference/create-segments) API.
</Update>

<Update label="June 4 2026">
  **Retired Alexa and Windows Phone 8.0 as Device Type filter options**

  The `Alexa` and `Windows Phone 8.0` values are no longer available for the Device Type filter when you create or edit a segment, in both the dashboard and the Create segment API. Selecting either value in the dashboard is no longer possible, and the API rejects them with a validation error.

  Existing segments that already use these values continue to evaluate and deliver as before. To save changes to such a segment, replace the retired Device Type filter first.
</Update>

<Update label="June 2 2026">
  **Extended `in_array` and `not_in_array` relations to tag and app version filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `tag` and `app_version` filter fields, in addition to the `country` and `language` fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"},
    {"operator": "AND"},
    {"field": "app_version", "relation": "not_in_array", "value": "1.0.0,1.0.1"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="May 11 2026">
  **Email BCC is now generally available**

  You can now add BCC (blind carbon copy) recipients to email sends, including templates used in journeys and messages sent via the API. Use BCC to archive customer-facing email to a shared inbox or compliance system, forward sends to third-party services, or keep internal stakeholders copied on transactional sends.

  * Available on all plan types.
  * Maximum of 5 BCC addresses per send.
  * Each BCC recipient counts toward the total email volume for that send (for example, 1,000 primary recipients with 1 BCC address = 2,000 sends).
  * BCC metrics are excluded from analytics.

  See [BCC emails](/docs/en/email-bcc) for setup and usage details.
</Update>

<Update label="May 12 2026">
  **Added `in_array` and `not_in_array` relations for country and language filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `country` and `language` filter fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "in_array", "value": "US,GB,CA"},
    {"operator": "AND"},
    {"field": "language", "relation": "not_in_array", "value": "es,fr"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="April 21 2026">
  **Manage custom aliases from the User Profile**

  You can now view, add, edit, and delete a user's custom aliases directly from the **Aliases** section on the User Profile **Overview** tab, without using the API.

  * Add an alias by entering a label (alias key) and value (alias ID), copy any alias value to the clipboard, edit a value, or remove an alias.
  * Each user supports up to 10 aliases, and alias labels and values can each contain up to 128 characters.
  * `external_id` and `onesignal_id` are reserved and can't be used as custom alias labels.
  * A user must have an External ID set before you can add custom aliases. External ID is still managed separately in the Profile section.

  See [Aliases](/docs/en/aliases) for more details.
</Update>

<Update label="April 17 2026">
  **Role-based access control (RBAC) is now generally available**

  Granular role-based access control has been rolled out to all customers, giving teams more flexibility to support least-privilege access patterns and manage permissions as they scale.

  * **New `team_member` org-level default role.** A baseline role for new users added to an organization.
  * **New `composer` app-level role.** Lets users create and edit messages, templates, segments, and journeys without sending, activating, or deleting content.
  * **Updates to `editor` and `viewer` roles.** Refined permissions for clearer separation of duties.
  * Available roles vary by plan type.

  See [Manage team members](/docs/en/manage-team-members) for the full breakdown of roles, permissions, and plan availability.
</Update>

<Update label="April 16 2026">
  **Light/dark mode toggle for HTML in-app message previews**

  You can now switch between light and dark mode directly in the dashboard when previewing HTML in-app messages, so what you see matches what your users will actually see.

  * A light/dark mode toggle is now available in the in-app message preview for HTML messages.
  * The preview no longer reflects your OS theme. It reflects the mode you select in the dashboard.
  * Previously, the preview always rendered using whatever theme your own computer was set to, with no indication that was the cause, so there was no reliable way to check dark mode designs from the dashboard.

  HTML in-app messages do not automatically get a dark mode. The message still has to be coded for it using `@media (prefers-color-scheme: dark)` styles. If your message doesn't include those styles, toggling to dark mode in the preview won't change how it looks.

  The toggle is available for HTML in-app messages only. Block-type in-app messages are not included in this release. Generally available for all customers using HTML in-app messages.

  See [Design your in-app message with HTML](/docs/en/design-your-in-app-message-with-html) for how to add dark mode support.
</Update>

<Update label="April 15 2026">
  **Standardized delivery metrics across all channels**

  Delivery metric terminology is now consistent across every messaging channel in OneSignal. All channels now share a unified delivery hierarchy: Audience → Sent → Delivered, with the same definitions everywhere. Labels have been aligned across delivery reports, journey reports, engagement trends, and CSV exports. The [Metrics Glossary](/docs/en/analytics-metrics-glossary) has been fully rewritten as the canonical reference for every metric definition.
</Update>

<Update label="April 10 2026">
  **Audience counts now show subscribed and unsubscribed breakdowns**

  The segment editor now shows both subscribed and unsubscribed counts for every subscription-based segment, with a per-channel breakdown across push, email, and SMS. Previously, only the opted-in (subscribed) count was visible.

  Additional improvements:

  * Counts always return within approximately 15 seconds. Exact counts are shown when possible; estimates are used when an exact count can't be calculated in time.
  * Estimates are clearly labeled: above 10,000 with a +/- margin of error (e.g. 140,000 +/- 5,000), and below 10,000 as a less-than value (e.g. \<4,800).
  * Estimates will never show 0 for a segment. Previously for segments with very small but non-zero membership, estimates could incorrectly show as 0.

  This release covers subscription-based segments. User-based segment improvements are coming later in Q2 2026.
</Update>

<Update label="April 7 2026">
  **Updated User Profile page**

  The User Profile page has been redesigned with a tabbed layout and several new management actions directly on the page:

  * Add and remove Subscriptions from a User
  * Search across a User's data tags
  * Perform more direct edits and admin actions without leaving the profile

  The previous profile view is still accessible from the **Actions** menu if you need it.
</Update>

<Update label="March 25 2026">
  **test users now apply at the User level**
  Marking a Subscription as a test user now automatically marks all Subscriptions for that User as test users, effectively creating a Test User.

  * Any new Subscriptions added to a Test User will automatically be marked as test users.
  * Test User is now a User-level property rather than a Subscription-level one.

  **OneSignal Server SDKs just got their first v5 stable release!**

  After a period of testing and iteration, v5 is now the default version users will get when installing any of our server SDKs. Here are the current versions included in this release:

  | Language | Version |
  | -------- | ------- |
  | Node.js  | 5.4.0   |
  | Go       | 5.3.0   |
  | Java     | 5.3.0   |
  | .NET     | 5.4.0   |
  | Rust     | 5.3.0   |
  | Ruby     | 5.3.0   |
  | Python   | 5.3.0   |
  | PHP      | 5.3.0   |

  This release pairs well with our recently refreshed Server SDK Reference, giving developers a solid starting point for integrating with the OneSignal API.
</Update>

<Update label="March 20 2026">
  **Audit Log Export is now in GA**

  * Customers can now export audit logs. Customers can export 2 days for free tier and up to 90 days with security and legal entitlement (either as individual SKU or enterprise plan).
  * Provides customers additional metadata details and allows them to filter through data locally for their own audits and consumption with their own tools.

  **Failed Reasons in Audience Activity for everyone!**

  * Free plan users can now see exactly why individual audience members failed to receive a notification — directly in the Audience Activity view.
  * When a notification fails, especially common when troubleshooting set up, free users had no way to know whether the problem was a bad token, an unsubscribed user, or a device issue — leaving them guessing and unable to fix anything. Now they get the same failure visibility paid users have, so they can debug and get set up properly.
  * Same data retention as audience activity (30 days)
</Update>

<Update label="March 17 2026">
  **Data Model Updates and Field Deprecations**

  To improve platform performance, strengthen data integrity, and reduce the risk of configuration errors, we are introducing several updates to the OneSignal data model.

  These changes will take effect **April 15, 2026.**

  **Field Limits**

  We are introducing limits on two user fields to improve consistency and prevent unexpected behavior.

  Existing records exceeding these limits will not be modified to avoid disrupting current data and operations.

  **External ID**

  * `external_id` values can contain up to 128 characters.

  **Aliases**

  * Each user can have up to 10 aliases.
  * Each alias key and value can contain up to 128 characters.

  **Field Deprecations**

  We are deprecating several legacy Subscription fields that are no longer actively used:

  * `amount_spent`
  * `rooted`
  * `bought_sku`
  * `app_interests`
  * `purchased_items`

  After April 15, 2026, these fields will no longer be available in:

  * Segment Builder
  * API requests
  * Event streams
  * Webhooks

  **Impact for Customers Using These Fields**

  If your implementation currently references any of these fields:

  **Segments:** Segments using these fields will be paused and labeled for your review.

  **Journeys:** Journeys depending on those segments will be archived.

  **Event Streams and Webhooks:** These fields will return empty values.

  **What You Need to Do**

  Most customers do not need to take any action.

  If your implementation relies on any of the deprecated fields, we recommend reviewing your segments and integrations before **April 15, 2026.**
</Update>

<Update label="March 6 2026">
  Email Address Validation is now available!

  * When email addresses are added to OneSignal, they're now validated at three entry points:
    * API: syntax check
    * CSV import: full validation including typo detection, MX record lookup, disposable email flagging, and role-based address detection\*
    * Bulk validation: same full checks, runs against addresses already in your audience
  * Free plans have syntax and typo checks.
  * Paid plans will have syntax, typo, MX, disposable email, and role based email address checks.

  See [Email Address Validation](/docs/en/email-address-validation) for more details.
</Update>

<Update label="March 4 2026">
  **Dashboard layout redesign has shipped!**

  * Panel-based layout. The old floating card approach has been replaced with flat panels. The side nav sits in a clean gray panel, and the main content in a white panel. This simplifies the look and feel and gives us a more modern aesthetic.
  * New global top bar. Breadcrumbs, the new Create menu, Help/Support links, and Upgrade button all live in a new sticky top bar that follows you on scroll.

  **Richer date context across the dashboard**

  Dates show up everywhere in OneSignal — denoting message creation, notification send times, user sessions, etc. — but it wasn't always clear which timezone you were looking at, or how recent something actually was. This came up in a discussion last week among the dashboard engineers.

  Now, hovering over a date in the following areas of the Dashboard shows a tooltip with three pieces of context at once: the time in your local timezone, the time in UTC, and a relative timestamp (like "2 days ago").

  Where you'll see it:

  * Message lists and indexes
  * Message reports
  * Message review modals before sending
  * User and subscription profiles

  This is enabled for all apps — no action needed. Just hover a date and it's there!

  **In-App Message library with new quickstarts!**

  We've shipped a library of professionally designed, ready-to-use in-app message templates — available now to all plans in the dashboard.

  What's in it: 7 categories of quick starts covering the most common IAM use cases: push soft prompts, promotions, onboarding flows, feature announcements, location prompts, spin-to-win, and notification preference centers.

  How to access: Dashboard → Messages → In-App → New In-App → OneSignal Quick Starts. No feature flag or backend enablement required — available immediately. (See demo for the full experience in product)

  Go from zero to a production-ready in-app message in minutes, without writing HTML from scratch!
</Update>

<Update label="March 3 2026">
  **Enhanced Snowflake Integration Now Available!**

  Key improvements include:

  * 15-minute sync intervals (down from 24 hours)
  * Selective event syncing so customers only export what they need
  * Self-service setup directly in the OneSignal dashboard
  * New events like in-app impressions, email bounced/received, and separated Live Activity events.
  * We've also added richer properties including Template ID, last active timestamp, and subscription status.

  Customers get near real-time data in their Snowflake instance with full control over what gets synced meaning faster insights. Selective syncing alone can dramatically reduce event volume (and spend) by letting them export only the events that they need.

  This moves from the legacy flat annual fee to our Event Streams pricing model. Customers pre-purchase an event volume tier, and that tier covers all destinations (Snowflake, BigQuery, Databricks, etc.).

  Live now for all customers. All new customers will automatically have access to this new integration. Existing legacy Snowflake customers have until August 1st to migrate to the new integration before deprecation. Both integrations can run in parallel during the transition so they can ensure parity/consistency, and we will be doing outreach to those affected shortly.

  See [Snowflake](/docs/en/snowflake) for more details.
</Update>

<Update label="February 26 2026">
  **Audit Logs API is now available**

  Enterprise customers (with Legal & Security package) can now programmatically access the same audit log data surfaced in the OneSignal dashboard — pipe it directly into their SIEM, compliance tooling, or internal security workflows.

  * Returns a time-scoped record of actions taken in their org — who did what, when, and from where
  * Filter by app, action type, actor, target, or IP address
  * Supports cursor-based pagination for large result sets

  See [Audit Logs API](/reference/list-audit-logs) for more details.
</Update>

<Update label="February 9 2026">
  Huawei Badge Parameter Support

  We now support app icon badges on Huawei (HMS) devices via both the API and dashboard.

  * What's new: Three new parameters on `Notification#Create`
    * `huawei_badge_class` — the app's launcher activity class name (required for badge)
    * `huawei_badge_set_num` — set the badge to an exact number (0–99)
    * `huawei_badge_add_num` — increment the badge by a specific amount (1–99)

  On the dashboard, you'll see a new Badge option under Send to Huawei Android with "Don't set" / "Set to" / "Increase by" options.

  * Good to know:
    * Setting `huawei_badge_set_num` to 0 clears the badge
    * If neither set nor add is specified, the badge increments by 1 by default
    * Huawei does not auto-clear badges when the app opens
</Update>

<Update label="January 29 2026">
  API Documentation Improvements

  * New API endpoint: [View Segment](/reference/view-segment) - Retrieve details of a specific segment by ID, including optional segment filter details.
  * New API endpoint: [Update Segment](/reference/update-segment) - Update an existing segment's name and/or filters programmatically.
  * Fixed JSON example formatting across multiple API reference pages for improved readability:
    * Segments API: view-segments, create-segments, delete-segments
    * Users API: create-user, view-user, update-user, delete-user
    * Subscriptions API: create-subscription, delete-subscription, transfer-subscription, unsubscribe-with-token, create-alias-by-subscription
</Update>

<Update label="January 26 2026">
  **Audit Logs are now available!**

  * Customers now have the ability to determine exactly what's happening across their OneSignal account. Audit Logs gives them a complete timeline of every action taken in their organization—who did what, when, and from where.
  * Track 50+ action types including:
    * Authentication events (login, logout, API key operations)
    * Message activity (notifications sent, canceled, A/B tests, Journeys)
    * Team changes (member added, role changed, removed)
    * Configuration updates (webhooks, segments, templates, integrations)
    * Billing & subscription events
  * Powerful filtering:
    * Search by team member email
    * Filter by action type, app, IP address, or item type
    * Custom date ranges with presets
    * Shareable filtered URLs—customers can collaborate with their team instantly
  * Deep visibility:
    * Expandable rows reveal 30+ fields: IP address, browser, location, correlation ID, API version, and more
    * Available at both App and Organization levels
    * Quick-access links from Journeys, Segments, Templates, Notifications, and more
  * Retention:
    * Legal & Security package: 90-day lookback
    * All other plans: 2-day lookback
  * Perfect for security audits, debugging, and understanding team activity at a glance.
</Update>

<Update label="January 9 2026">
  * Standardized time series for charts are now available for:
    * Event Streams and webhooks
    * Email delivery reports
    * SMS/RCS delivery reports
</Update>

<Update label="December 22 2025">
  * confirmed receipt Now Available On Engagement Trends
    * Customers with access to confirmed receipt can now see confirmed receipt on the Engagement Trends Time Series Chart.
    * This missing data was a common point of confusion for customers. They could see confirmed receipt & click through rate, but had no access to the total confirmed deliveries metric.
    * This additional data point gives customers confidence in the rates we're showing and helps with confusion on the difference between "delivered" and "Confirmed receipt" for push notifications.
</Update>

<Update label="December 12 2025">
  * New integration - Self-serve Snowflake data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake without going through customer support
    * The legacy Snowflake documentation remains available for existing implementations
</Update>

<Update label="December 8 2025">
  Live Activities in Event Streams & Integrations

  Live Activities Analytics provides two key capabilities to optimize customers' live activity strategy:

  1. Better Troubleshooting with confirmed receipt
     Gain visibility into whether devices actually received live activity updates. confirmed receipt tracking identifies delivery issues quickly to understand the true reach of live activities.
     Available in:

  * Individual message reports with per-device confirmation
  * Data exports to BI tools (through event streams and integrations)

  2. Deeper Engagement Insights with data exports to integrations & event streams
     Answer critical questions about how users interact with your live activities:

  * How many users engaged with my live activity over its duration?
  * When did users drop off?
  * What was the peak engagement time?
  * When did users click? (coming soon)

  Export live activity data to BI tools to analyze engagement patterns, optimize timing, and improve future campaigns.
</Update>

<Update label="December 5 2025">
  We've launched a new [Metrics Glossary](/docs/en/analytics-metrics-glossary) in our documentation. This resource provides a single source of truth for delivery metric definitions, helping both our team and customers understand our metrics consistently across dashboards, APIs, and exports.
  While we continue working toward unified terminology across all touch points, this glossary establishes clear mappings and definitions as they exist today, making it easier for customers to navigate our current analytics landscape.

  Custom Events in User Activity Timeline
  Custom events are now visible per User on their profile page in a dedicated tab. You can:

  * Filter by event type and event source
  * Filter by date, to any time window in the past. Only limiting factor is customer's own events retention window setting!
  * Expand each event to see the full payload
  * Click through to the events index to see that event type's config and full cross-user activity log

  This is important because:

  * It helps paint the complete picture of user activity. At a basic level, customers ask the question, "what's going on with this user?" and this helps answer it.
  * Especially useful for zoomed-in troubleshooting, auditing, what-happened analysis.
  * Please note: this will only be visible to customers in Custom Events early access, but will be available to all as they gain access to Custom Events
</Update>

<Update label="November 26 2025">
  UX Improvements Now Live

  1. Row-Level Linking
     You can now click anywhere on a table row to navigate to its destination, instead of having to click a specific cell. This makes navigation faster and more intuitive.
  2. Row Highlighting on Hover
     All tables now highlight the entire row on hover, helping users track data more easily and reducing visual strain when scanning wide tables.
  3. Improved Responsiveness
     The actions column has been narrowed to preserve horizontal space and is now right-aligned at the end of every table.
     It also features sticky, floating behavior — especially useful on smaller screens where horizontal scrolling is required.
     Some tables better truncate long text (e.g., lengthy message names) more effectively to maintain a clean layout.
  4. Refined Sorting UX
     Updated sort icons make the sort direction easier to interpret. Clicking anywhere on a column header now toggles sorting, improving ease of use.
  5. Unified Column Visibility Menu (Applies to Journeys, Users, Subscriptions)
     Tables with customizable columns now use a consistent, cleaner UI. Column changes update live as you toggle them.
  6. Updated Search Bar UI
     The search bar now aligns with design standards, featuring a left-aligned search icon, and a button that shows after typing for easy input clearing.
  7. Improved Pagination Formatting
     Pagination controls now use comma formatting for large numbers, improving scannability and readability.

  Core Component Update
  Many of the enhancements above come from migrating these tables to our core design system’s DataTable component. Sorting and filtering improvements for tables are consistently among the most requested features we receive. While these updates don’t introduce new sorting or filtering behavior yet, this component upgrade provides a more consistent experience for the functionality we have today, and does lay the foundation for Product teams to build more advanced table capabilities once those initiatives are prioritized.

  Coming Soon

  * Most tables across the Dashboard already include these improvements. A few remaining areas still require component updates before they can adopt the full set of new enhancements:
    * In-app index
    * Templates index
    * Audience activity table
    * A/B tests stats table
</Update>

<Update label="November 12 2025">
  UX Enhancement: Duplicate Templates Directly from the Editor
  In usability tests and dogfooding sessions, we noticed users often duplicate Journey nodes and then edit their templates. Previously, you had to exit the template editor and duplicate the template from the index view, an extra step that interrupted the workflow.
  Now, you can duplicate templates directly from the actions dropdown in the template editor. This small but meaningful improvement streamlines your editing experience and makes iteration faster. While our long-term goal is to enable template/content editing directly within Journeys, this enhancement is a great step in that direction.

  New Platform Filters for Engagement Trends & Subscription Trends
  You can now filter push engagement trend data by platform (iOS, Google Android, Huawei, etc.) to get a more granular view of performance across specific devices.
  In the spirit of our Analytics Consistency project, we've also brought this same filtering experience to Subscription Trends.

  Analytics Consistency: Standardized Time Series Chart Filters
  We're standardizing filter options across our time series charts, giving customers a consistent experience and clear access based on their plan.
  Key Changes:

  * All charts will share the same set of granularity and look back filters
  * Consistent casing and terminology used on all filters
  * Consistent upgrade experience for customers on plans with limited access
    As an example, Subscription Trends now supports a 2 year look back after the change.

  Charts where we've already rolled out these changes:

  * Engagement Trends
  * Subscription Trends
  * Global Outcomes
  * Push Delivery
  * All Template Reports
  * Coming Soon:
  * Email Delivery
  * SMS Delivery
  * Journeys Reports

  Look back access based on plan type:

  * Free: 30 days
  * Growth: 90 days
  * Professional: 1 year
  * Enterprise: 2 years
  * Custom: Up to 90 days (based on plan types above)
</Update>

<Update label="October 6 2025">
  Nice UXE on Journey Settings. We’ve updated the Journeys Settings Side panel to be more user friendly by adding a side navigation to keep each section in focus. This is in tandem with the eventuality of having more settings available to the user as we look towards Journey Goals, and more.  We will accompany this release with an intercom slide letting the user know we have updated the settings area as to give them a heads up due to the abrupt pattern change.

  Every Setting, In Focus: Journey Settings are now grouped and spotlighted, helping you zero in on each choice without distraction.
</Update>

<Update label="October 2 2025">
  Custom Events are now available to all customers on paid plans! You can now send custom events via our API or SDK, and use them to trigger actions in Journeys with your own event data.
</Update>

<Update label="September 21 2025">
  Customers can now pause a segment that's counting towards their segments entitlement even though it's only being used in an archived journey or paused IAM. We also made it even easier to pause segments, if the user wants to pause a segment, we'll help the user pause or archive the active IAMs or journeys stopping the user from pausing a segment.
</Update>

<Update label="September 9 2025">
  Deactivate email senders

  Deactivate email domains that are no longer in use or were set up incorrectly. This includes fallback handling for your email templates and scheduled sends to make sure you don't break them by removing a domain, just in case it was being used more widely than you anticipated.
</Update>

<Update label="August 29 2025">
  Personalize emails with real-time Data Feeds

  You can now use Data Feeds to pull live content from your APIs directly into emails at send time. No more static CSVs or preloaded tags — every message can include the latest account details, product recommendations, or order updates.

  Available in the email template composer for emails sent via Journeys, Data Feeds includes preview tools and error handling to keep sends smooth.

  👉 See how to set up [Data Feeds](/docs/en/data-feeds)
</Update>

<Update label="August 04 2025">
  You can now hold users in a Journey step until specific conditions are met before they move forward with the *Wait Until* action. This new feature allows you to:

  * Hold users at a step until they enter a segment or trigger a message event (such as a specific message being delivered, opened, or clicked).
  * Add multiple conditions and branch users based on whichever condition they meet first.
  * Set an expiration path that moves users forward or removes them from the Journey if none of the conditions are met within your chosen timeframe. This gives you greater flexibility and control over how users progress through your Journeys. Learn more: [Journeys Actions](/docs/en/journeys-actions)

  AI Composer Push Notifications
  You can now generate or improve push notification message copy using the AI message composer. This update helps you craft high-performing content without leaving OneSignal. When creating a new push notification, select AI-generated push button to get started. To improve existing copy, select “Refine” in the Title, Subject, or Message fields.

  New [Integrations](/docs/en/integrations) index page contains the following enhancements:

  * Filtering by type of integration
  * Filtering by Inbound/Outbound directions of data flow
  * Includes our new inbound DWH/Data ingestion options for custom events
</Update>

<Update label="July 07 2025">
  * Quickly identify and manage segments tied to campaigns
    * We’ve made it easier to clean up outdated segments.
    * Previously, you couldn’t delete a segment if it was tied to an In-App Message (IAM) or Journey, even if that campaign was paused or archived. Now, when you try to delete a segment, you’ll see a modal listing all IAMs and Journeys that are preventing deletion.
    * This helps you quickly locate and update the associated campaigns, so you can keep your workspace clean and organized without having to hunt through every Journey or IAM.
</Update>

<Update label="June 30 2025">
  * Segment users based on real message engagement
    * You can now create user segments based on how they interacted with previous messages across push, email, SMS and in-app.
    * This update adds a new Message Event filter that allows you to segment users based on events like email opens, push clicks, SMS failures, and more - without relying on tags or external tools.
    * Available on all paid plans.
    * See [Segmentation](/docs/en/segmentation#message-event-filters) for more details.
</Update>

<Update label="June 27 2025">
  * New documentation with Mintlify!
    * We've updated our docs!
    * New AI features and easier readability.
    * Updated API reference and openapi spec.
    * New Tutorials page with common use cases and step-by-step details to get you setup quickly!
</Update>

<Update label="June 18 2025">
  * Track In-App engagement trends alongside push, email, and SMS
    * Customers can now see In-App Message impressions, clicks, and click-through rates directly in the Engagement Trends chart. This update gives marketers a unified view of how users are interacting with all message types over time—including In-App—making it easier to spot trends, report on performance, and optimize messaging across channels.
    * With this update, In-App engagement data is now included alongside push, email, and SMS across all views in the Engagement Trends chart. Stats are grouped by day and support up to two years of data (depending on plan). This data is exportable via CSV just like other channels, and can be filtered to look at specific date ranges or message types.
    * This feature is available to all customers.
</Update>

<Update label="June 12 2025">
  * Unlock deeper email engagement insights with multi-link tracking
    * Customers can now track engagement on every individual link within their emails. This update gives customers a much clearer view into what content or messaging is working so they can improve email performance over time.
    * Previously, when customers included multiple links within an email, they could only view total click counts across all links. Now, they can see which specific links get the most engagement and how links perform inside journeys. This helps them refine content and messaging strategies.
    * Multi-link tracking is automatically applied to most emails created in the Drag & Drop or HTML editor. Link-level performance metrics will also be available for emails sent using a template and emails in a Journey.
    * This feature is available to all customers with access to email.
</Update>

<Update label="May 23 2025">
  * View and optimize message performance with Template Analytics
    * OneSignal customers can quickly assess how individual templates are performing across all messages, without needing to download and stitch together separate reports.
    * When users click into a template, they now land on a detailed analytics view showing Delivered, Unique Opens, Unique Clicks, and Unsubscribes. They can track performance over time, filter by platform, explore delivery breakdowns like Failed or Capped, and review a list of messages that used the template.
    * Template analytics is especially useful for:
      * Marketers who test and iterate on message content
      * Developers who need visibility into transactional message delivery
      * High-volume senders seeking scalable insights
    * Transactional visibility is a key differentiator that sets us apart from Firebase and other open source solutions. Customers can now answer questions like “How many Account Confirmation emails did I send last week?” or “What was the click-through rate on my Password Reset messages?”
    * Important note: For templates created before April 17, 2025, enhanced metrics are only available for messages sent after that date. Customers can use the “Show historical data” toggle at the top of the page to see earlier performance data.
    * The feature is live and available by default. Reporting history varies by plan:
      * Free: 30 days
      * Growth: 90 days
      * Professional: 1 year
      * Enterprise: 2 years
</Update>

<Update label="May 16 2025">
  * Add users manually from the dashboard
    * You can now create new users directly from the *Users* tab in your OneSignal dashboard using a simple form. This update makes it easy to manually add a user with an email address, phone number, or both without needing an SDK, API call or CSV upload.
    * This is especially helpful for quickly testing campaigns or adding users who aren’t yet in your system.
</Update>

<Update label="May 14 2025">
  * Track SMS link performance directly in OneSignal
    * Customers can now track SMS link performance directly in OneSignal without needing third-party tools like Bit.ly or custom UTM parameters. This feature gives our customers a more streamlined, built-in way to measure engagement and optimize messages faster, removing friction and helping drive better results from their SMS efforts.
    * When composing an SMS message, customers simply click “Insert Trackable Link” and enter the full URL they want to send users to. OneSignal automatically shortens the link using the 1sgnl.co domain so it fits within SMS character limits and can be tracked.
    * All SMS users will have access to trackable links as part of their existing plan.
</Update>

<Update label="May 07 2025">
  * Simplify message organization with easier label management
    * Now you can add labels to your messages to help you organize and manage them.
    * See [Labels](/docs/en/labels) for more details.
</Update>

<Update label="May 01 2025">
  * Template analytics
    * You can now view and optimize template performance from a centralized reporting view. Click into any message template to view detailed performance data across every message a template is used in.
</Update>

<Update label="Apr 25 2025">
  * Improved CSV Importer
    * **Real-time validation:** Get instant feedback on formatting errors before upload.
    * **Smart column mapping:** Easily align your CSV headers with OneSignal fields.
    * **Email suppression support:** Add or manage your suppression list directly in the file.
    * **Upload history:** View the status of your past imports for up to 30 days.
    * **Helpful templates:** Start quickly with a pre-built CSV example.
</Update>

<Update label="Apr 21 2025">
  * Fine-tune your Live Activities with new API parameters
    * You can now add more control, reliability, and speed to your Live Activities with three new parameters in the OneSignal API: - ios\_relevance\_score: Helps determine which Live Activity displays most prominently on iOS. - include\_aliases: Allows you to target individual users directly rather than relying on segment-based delivery. - idempotency\_key: Prevents the creation of duplicate Live Activities when retrying start requests if not using the OneSignal SDK.
</Update>

<Update label="April 14 2025">
  * New integration - Databricks data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Databricks. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Databricks, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="April 08 2025">
  * View opt-out status by sender and support transactional messaging even with marketing opt-outs
    * You can now see SMS opt-out status by sender, giving you better visibility and control when managing marketing and transactional messages.
    * With this update, you can:
      * View subscription status by individual sender for any phone number
      * Continue sending transactional messages (like OTPs or alerts) even if a user has opted out of marketing
      * Maintain deliverability and avoid carrier filtering by respecting opt-out preferences
    * This is especially useful if you manage separate senders for promotional and transactional use cases.
    * To access this feature, go to **Consent Management > Advanced Opt-out Settings** and turn off the setting that globally unsubscribes a user when they reply with an opt-out keyword.
    * *Note: This option is only available to customers using advanced opt-out settings for SMS.*
</Update>

<Update label="March 19 2025">
  * Easily find and select the right templates with visual previews
    * Quickly identify and select your email and in-app message templates with the new updated card view.
    * Instead of relying on template names alone, you can now see clear visual previews, making it easier to choose the right template at a glance.
</Update>

<Update label="March 12 2025">
  * Create users in OneSignal via HubSpot workflows
    * Keep your users in sync across HubSpot and OneSignal! With this new workflow action, you can now create users in OneSignal whenever a HubSpot workflow trigger fires. This enables you to queue up personalization details (such as Tags) and plan engagement strategies before a user even interacts with your mobile platform. Additionally, you can trigger an SMS or email via HubSpot while simultaneously creating a user in OneSignal—ensuring seamless and immediate engagement.
    * [HubSpot Documentation](/docs/en/hubspot)
  * Push preview accuracy improvements
    * As operating systems update, they often introduce new changes in their push designs.
    * We've updated our previews so they match latest and greatest push notification designs across iOS (18), Android (15), Windows (11), macOS (Sequoia). This ensures you see what your users will see when testing in OneSignal.
  * PII Masking of Emails and Phone Numbers
    * Protect user privacy and reduce compliance risks by masking personally identifiable information (PII) such as emails and phone numbers. With PII masking, your team can work securely while still analyzing campaign performance and sharing insights across teams.
    * OneSignal automatically masks phone numbers and emails in the dashboard and any data exported directly from the platform. However, PII masking does not currently apply to data accessed via API requests, external IDs, or Tags.
</Update>

<Update label="March 07 2025">
  * Verify & Lookup Phone Numbers
    * Sends the user a one-time verification code to ensure the customer owns the phone #
    * Confirms the phone number entered by a user at onboarding is valid
</Update>

<Update label="February 28 2025">
  * Added New Integration - [BigQuery Data Export](/docs/en/bigquery)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to BigQuery. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in BigQuery, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
  * Channel subscriber counts have moved
    * The counts of subscribed counts for each channel have moved from the dashboard to the Subscriptions page in OneSignal. Now you will see the number of *Subscribed* subscriptions for each channel at the top of the Subscriptions page under Audience to get an overview of audience reach per channel in the context of your subscriptions.
    * If you still wish to view this information on the Dashboard, you can filter your Subscriptions trends chart by channel.
</Update>

<Update label="February 14 2025">
  * Improvements to Keywords
    * We've made a couple of improvements to our SMS keywords.
      * Segment by subscription status when sending a keyword to encourage converting your customers who are not yet subscribed into opting in to your SMS marketing messages
      * Setup an auto-responder for unrecognized keywords
</Update>

<Update label="February 12 2025">
  * New Engagement Analytics on the OneSignal Dashboard

    * Are you curious to learn more about how your end users engage with the messages you send from OneSignal? Head to your Dashboard to see the new Engagement Trends report.
    * With this report you will gain insight into how users engage with your messages across Push, Email, and SMS. Track click-through-rate, unsubscribes, and monitor trends over time to refine your messaging strategy and optimize communication frequency. This comprehensive report consolidates data from all message types (Dashboard, API, Journeys) for a clearer view of performance. Now available in your OneSignal dashboard!

    <Frame>
      <img alt="New Engagement Analytics on the OneSignal Dashboard" />
    </Frame>
</Update>

<Update label="January 29 2025">
  * Sort segments by Last edited, Created at and more
    * Finding and managing your segments just got easier!
    * You can now sort segments by Last edited, Created at and more.
      * This update is especially valuable for customers who:
        * Maintain numerous segments
        * Frequently update their segment configurations
        * Need to identify and clean up outdated segments
        * Want to quickly find recently modified segments
</Update>

<Update label="January 27 2025">
  * Email Senders (Multi-Domain Sending)
    * Create distinct senders for different types of communications:
      * Keep your marketing campaigns separate from crucial transactional emails
      * Maintain different brand voices for various product lines
      * Optimize sender reputation for each type of communication
      * [Email Senders](/docs/en/senders)
  * Improved In-app Message Analytics for Event Streams
    * We've added a new In-app Message Analytics for Event Streams.
</Update>

<Update label="January 21 2025">
  * Email Intelligent Delivery
    * We've added intelligent delivery to email.
    * Transform your email engagement with OneSignal's latest breakthrough: Intelligent Delivery. This powerful new feature automatically determines the optimal time to reach each individual user, maximizing your email campaign's impact.
    * Our algorithm continuously learns from:
      * User open patterns
      * Click-through behavior
      * Real human interactions (excluding bot activity)
</Update>

<Update label="January 16 2025">
  * Retirement of Automated Message for Free apps
    * Automated Messages are no longer supported and the feature has been retired in the free plan. Paid apps will continue to have access to this feature until further notice.
    * Active automated messages will remain live and continue functioning as expected. However, you can no longer create new automated messages, or reactivate paused automated messages. To build new automated sequences and enhance your campaigns, we recommend using [Journeys](/docs/en/journeys-overview).
</Update>

<Update label="January 15 2025">
  * Customize how your users re-enter split branches
    * Now you can customize how your users re-enter split branches. This feature is available for all Journeys.
    * [Journey Entry Triggers](/docs/en/journeys-actions)
  * Improving New Message Experience
    * We improved the new message experience by adding a library of templates (get inspiration for your next push, in-app, email, or SMS), or quickly start from a template you've made, or a previous message.
</Update>

<Update label="January 03 2025">
  * message.url - New Push Event Stream Property
    * `message.url` is now a supported property for push events. It enables the retrieval of the launch URL directly from your event stream payload.
</Update>

<Update label="December 24 2024">
  * Journeys Multi-split Branching
    * Now you can set up more personalized paths in your Journey. Create up to 20 branches to test channels, content, timing, ordering, and more. Assign different weights to each branch, or easily distribute audiences evenly across all branches. See how different paths perform against each other or against a control group.
</Update>

<Update label="December 20 2024">
  * WordPress Plugin v3
    * We've upgraded our Wordpress Web Push plugin to v3+. What's changed:
      * Upgrades the OneSignal Web SDK from version 15 to 16.
      * Setup more new prompts within the OneSignal dashboard, including the following. No custom code is required anymore to configure these.
        * Category Prompt
        * Email/Phone Slide Prompt
        * Custom Link Prompt.
      * When publishing a new post, check the "Send notification when post is published" box to send a push notification.
      * Choose which audience segment should receive notifications for each post.
      * Web Topics are included by default.
      * Send to mobile app subscribers, with an option to direct them to a different URL (Deep Link).
</Update>

<Update label="December 11 2024">
  * Improved Logs in Event Streams
    * We've improved the Event Streams feature to make troubleshooting simpler and faster. Now, you’ll find dedicated tabs for successful and failed events, making it easier to spot issues at a glance. Clear empty states show when there’s no data in either tab, and updated messaging ensures you know the logs display a sample of your data.
  * SMS Keywords
    * We've added keywords for SMS. Keyword engagement enables quick, two-way communication, enhancing personalization, accessibility, and user satisfaction. It drives conversions and higher engagement with your subscribers. Add a data tag to the keyword, and segment based on their preferences to send more targeted SMS.
  * Quickstart Segments

    * We are thrilled to launch three new segment templates designed to help you hit the ground running with proven strategies:
      * First-Time audience
      * Regional audience
      * Custom Audience based on tags
    * Our analysis of 6.3 billion message deliveries uncovered powerful insights. These templates are built to help you:
      * Create high-performing segments from day one.
      * Use proven filter combinations that drive higher engagement.

    <Frame>
      <img alt="Quickstart Segments" />
    </Frame>
</Update>

<Update label="December 02 2024">
  * Email Quickstart Templates
    * We've added a library of quickstart templates for email. Explore our library of professionally crafted email templates, designed to inspire your creativity and elevate your email campaigns. Use them as a starting point to create impactful messages that drive conversions and engage your audience effectively.
</Update>

<Update label="November 27 2024">
  * Scheduling Journeys
    * Now you can schedule Journeys to send at a specific time. This feature is available for all Journeys.
  * Settings Overview Page
    * Now you can access and manage all your settings in a centralized setting overview page. Platform-specific settings have been reorganized under their relevant channels for better clarity.
</Update>

<Update label="November 20 2024">
  * Bulk Archive and Delete Journeys

    * Now you can bulk archive or delete Journeys from the Journeys index. Select up to 20 Journeys, and then choose an action you'd like to take to clean up Journeys you're no longer using.

    <Frame>
      <img alt="Bulk Archive and Delete Journeys" />
    </Frame>
</Update>

<Update label="November 06 2024">
  * Improved Export for Global Outcomes
    * We've improved the export for Global Outcomes to include more data and make it easier to use in your reporting.
  * Preview allows you to preview the content of a message and can be very helpful when you have a message with personalization (i.e. Tags, dynamic content, custom data). With preview, you can preview content from a specific test user's perspective, or with example custom data.
  * Settings for Email & Side Navigation Updates
    * In the side navigation, you can now easily see your Push, SMS, and Email settings. What was once "Messaging" is now "Push" settings, and SMS and Email Settings will take you directly to your channel's settings.
    * For email, we've created a dedicated place to manage your email provider and senders. If you are a OneSignal mail user, you'll also be able to see your reputation and suppression lists here.
  * SMS Usage
    * We've added SMS Usage in the Usage page. We've also added a breakdown so you can see the message type, and a breakout by inbound and outbound. You may see an unknown country if a segment failed to send.
</Update>

<Update label="October 02 2024">
  * Add Notes on your Journeys
    * Now you can add notes to the steps of your Journeys to keep reminders and more effectively collaborate and share information with your team. This feature is available for all Journeys.
</Update>

<Update label="September 27 2024">
  * New Quickstart Journeys
    * We've added a new Quickstart Journeys to help you get started with Journeys. This feature is available for all Journeys.
  * SMS Text-to-Subscribe
    * It's now easier to set up double opt-in and text-to-subscribe phone number collection experiences for your customers!
</Update>

<Update label="September 12 2024">
  * Confirmed Click-Through-Rate (CCTR) metric

    * We have added a new metric to measure the CTR using confirmed receipt. Confirmed Click-Through-Rate (CCTR) is measured by (total clicks/confirmed delivered) \* 100%

    <Frame>
      <img alt="Confirmed Click-Through-Rate (CCTR) metric" />
    </Frame>
</Update>

<Update label="September 06 2024">
  * Export your Subscription Trends
    * Now you can export the data from your Subscription Trends report as a CSV. If you apply filters to the report, OneSignal will export based on the filters you've applied so that you can fine-tune the data that you use to evaluate your messaging audience.
</Update>

<Update label="August 05 2024">
  * Email Saved Rows
    * Saved Rows are reusable content blocks that help streamline email creation and management. Many companies, especially those that have a lot of templates, prefer to use saved rows in their emails for consistency and to save time. Saved Rows are easily attached to new emails so you don't have to create the same information from scratch each time. And when things change, you just have to update the saved row, and your updates will automatically sync across all campaigns that have that saved row attached.
    * Common use cases include:
      * headers (logo, slogan)
      * footers (company details, social media links, mailing addresses)
      * disclaimers
      * other elements that are used across multiple campaigns
    * You can now save Email Drag-and-Drop rows to use across many Campaigns or Templates. These re-suable **Saved Rows** make it easy to sync updates across many emails at once. Click on the **Rows** tab of a Drag-and-Drop email, to view your **Saved Rows**. To save your first row, click the save icon in the edit, in the top right corner of the row.
    * We recommend you set up all of your templates to use saved rows for your header and footer so that you need to update the branding or content; you only have to make those edits once.
</Update>

<Update label="July 30 2024">
  * Journeys now target anonymous users
    * Now, Journeys do not require External IDs to be set on subscriptions. Instead, Journeys will target your entire user base within OneSignal, including anonymous users. We recommend still configuring External IDs to identify individual users who have subscribed to multiple channels.
</Update>

<Update label="July 25 2024">
  * Have more visibility into SMS unsubscribes, resubscribes, and help keywords
    * We now make it easier to manage your Consent Keywords within Onesignal. Reach out to support if you'd like to update the default consent keywords and replies.
</Update>

<Update label="July 19 2024">
  * Email Reply-to field now supports custom properties
    * Now you can use [Message Personalization](/docs/en/message-personalization) within the `reply-to`field on an email. This allows you to direct message replies to the right inbox and can be helpful if you are sending from different brands or across different countries.
</Update>

<Update label="July 16 2024">
  * Push Failures and Unsubscribes in Audience Activity
    * Obtain a list of subscriptions that have faced errors - failures or unsubscribes, for a specific push notification in the push report page.
</Update>

<Update label="July 03 2024">
  * Integrations: OneSignal Message Events can be sent to Twilio Segment
    * Customers can now select and send message events from OneSignal to sync back to their Twilio Segment account, making the Segment integration bidirectional.
  * Use Audience Activity for Live Activities to get a list of recipients
    * Get a list of subscriptions that successfully or failed to receive a Live Activity on a Live Activity report page, which is accessible through the Delivery - Sent Index. This list can be exported as well.
</Update>

<Update label="June 06 2024">
  * In-app message audience activity
    * In the report page of an in-app message, you can now see which mobile subscriptions viewed (impression) or clicked on an in-app message. Audience activity is available for 30 days from the time the message is displayed
</Update>

<Update label="May 15 2024">
  * FCM Expired Tokens > Increased Android Unsubscribes
    * On May 15, 2024, Google's FCM service will start to expire stale push tokens for devices that have been inactive for more than 270 days. You may see a spike in Android unsubscribes when sending notifications due to this change. Don't panic! These are devices that have not been online in over 270 days and are part of Google's [Best practices for FCM registration token management](https://firebase.google.com/docs/cloud-messaging/manage-tokens). If the device does come back online and opens your app, OneSignal will automatically resubscribe them to push if they were previously subscribed already.
    * See [FCM Expired Token FAQ](/docs/en/fcm-expired-token-faq) for more details.
</Update>

<Update label="April 29 2024">
  * Configure more granular Frequency Capping rates for Push
    * Push notifications can now be capped at a rate of x notifications per any time frame (less than 1 week). Navigate to Settings > Messaging > Push Frequency Capping > Custom (in the time dropdown) to view these settings.
    * Read [Frequency Capping Documentation](/docs/en/frequency-capping) for more details.
</Update>

<Update label="April 11 2024">
  * Added Android Live Notifications
    * Android's Live Notifications deliver live, dynamic content in notifications to enhance user engagement and app interactivity. This is a feature similar to iOS's Live Activities feature (introduced with iOS 16), but uses its own set of tools and APIs that enable similar functionalities.
    * See [Android Live Notifications](/docs/en/android-live-notifications) for more details.
  * Major improvements to Android SDK
  * Push to start Live Activities
    * Live Activities can now be launched on a user's screen when the mobile app is in the background (app is not open). Live Activities can both be started and updated by a remote push notification.
    * [How to start a Live Activity with a remote push notification](/docs/en/live-activities)
</Update>

<Update label="April 01 2024">
  * Added Audience Activity reports for Journeys
    * We have added Audience Activity reports for Journeys so you can get a closer look at which subscriptions were sent messages during a Journey. To view this report, click into a message report on your Journey. [Learn more here](/docs/en/journeys-analytics#audience-activity).
</Update>

<Update label="March 18 2024">
  * Added a new Setup guide for Analytics
    * We have added a new Analytics Setup guide to our product documentation detailing how to track Confirmed Deliveries and set up Custom Outcomes with support from your development team.
</Update>

<Update label="March 12 2024">
  * Mobile SDK Updates
    * We recommend updating to the latest SDK versions listed below to benefit from critical bug fixes, stability improvements, and new features. These updates include key enhancements across all platforms, including iOS 5.1.3 and Android 5.1.6, which improve concurrency safety, crash resilience, and background thread handling. The updates also include important API adjustments like more accurate property handling in the `PushSubscriptionState`.
</Update>

<Update label="February 16 2024">
  * Journeys is now available on the Growth plan
    * Journeys is now available on the Growth plan. This means you can now create and manage Journeys with up to 100,000 users.
    * See [Journeys](/docs/en/journeys-overview) for more details.
</Update>

<Update label="February 12 2024">
  * Added Auto Warm Up
    * We have added a new feature that allows you to automatically warm up your app when a user opens it. This feature is available for all OneSignal customers.
    * See [Email Warm Up](/docs/en/email-warm-up) for more details.
</Update>

<Update label="February 02 2024">
  * Journeys has easier targeting based on user activity
    * We've added support for Segments with time-based rules (e.g., first session, last session, etc.) and also simplified targeting inactive users. Now you can target your inactive users by including a segment based on last session behavior.
  * Email: Schedule Sends Across Different Timezones
    * Email campaigns can now be scheduled to send across different timezones. This feature is available for all OneSignal customers.
</Update>

<Update label="January 30 2024">
  * Email now supports One Click Unsubscribe
    * Inbox Service Providers (ISP) like Gmail, Outlook, iOS Mail, and Yahoo! Mail, AOL, and Verison Mail require senders to provide a One Click Unsubscribe option. The unsubscribe button is rendered at the discretion of the ISP based on sending criteria, which may include a daily sending volume greater than 5,000 emails.
</Update>

<Update label="December 18 2023">
  * Filter your messages with labels
    * Now you can filter your messages with [labels](/docs/en/labels). This feature is available for all OneSignal customers.
  * CSV Importer can now update properties
    * CSV Importer for email now enables updates to user properties `language`, `country`, and `timezone_id`.
  * Send more personalized messages and multi-language emails
    * [Dynamic Content Documentation](/docs/en/dynamic-content)
</Update>

<Update label="December 14 2023">
  * All OneSignal apps now belong to an Organization
    * We have added a new feature that allows you to manage your OneSignal apps within an Organization. This feature is available for all OneSignal customers.
    * See [Apps, Orgs, and Accounts](/docs/en/apps-organizations)
  * Journeys now has better analytics
    * We've added a new Journeys Report. See [Journeys Analytics](/docs/en/journeys-analytics) for more details.
</Update>

<Update label="November 22 2023">
  * Removed Journey Notifications from Delivery Reports and the View Notifications endpoint
</Update>

<Update label="October 04 2023">
  * Added new integration - [Snowflake](/docs/en/snowflake)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Snowflake, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="September 27 2023">
  * You can now save and continue
    * Changed the default option for saving a message to save work without exiting the message.
</Update>

<Update label="September 13 2023">
  * Added the ability to adjust the default padding for IAM blocks
    * Learn more about [IAM blocks](/docs/en/design-your-in-app-message)
  * Added the ability to edit entry triggers and re-entry rules for live Journeys
    * Learn more about [Journey entry triggers](/docs/en/journeys-overview)
</Update>

<Update label="September 05 2023">
  * Added ability to create multi-language push messages by pasting your CSV
    * Learn more about [Multi-language messages](/docs/en/multi-language-messaging)
  * Added new "Editor" role permissions
    * Learn more about [Managing team members](/docs/en/manage-team-members)
  * Added enhanced Journey message stats and reports.
    * Learn more about [Journey message stats and reports](/docs/en/journeys-analytics)
</Update>

<Update label="September 01 2023">
  * Added a new feature to forward email templates to an app
    * Learn more at [Email Template Forwarding](/docs/en/email-template-forwarding)
  * Added FCM v1 API support for Android Push Notifications
    * Learn more about [Android Firebase credentials](/docs/en/android-firebase-credentials)
</Update>

<Update label="August 15 2022">
  * Android 13 changes
    * Android 13 introduces a runtime notification permission, meaning users must opt in to receive push notifications. Apps targeting Android 13 must explicitly prompt for permission at a time of their choosing, or the system will display the permission prompt automatically on first launch—often resulting in lower opt-in rates.
    * See [Android 13 Push Notification Developer Update Guide](/release-notes/android-13-push-notification-developer-update-guide) or our [Prompt for Push Permissions](/docs/en/prompt-for-push-permissions) guide for details.
</Update>


# SDK Releases
Source: https://documentation.onesignal.com/release-notes/sdk-releases

View the latest OneSignal SDK releases and updates.

## Mobile

<SdkReleasesIframe />

## Web

<SdkReleasesIframe />

## Server

<SdkReleasesIframe />

## Plugins

<SdkReleasesIframe />


# Server SDK reference
Source: https://documentation.onesignal.com/docs/en/server-sdk-reference

Install, configure, and use OneSignal server SDKs to send push notifications, emails, and SMS from your backend in Node.js, Python, Java, Go, PHP, Ruby, C#, and Rust.

All OneSignal server SDKs are generated from the same OpenAPI specification, so they share a consistent interface regardless of language. Each SDK wraps the [OneSignal REST API](/reference/create-message) and provides typed models for requests and responses.

## Available SDKs

| Language  | Package                                                                                            | Repository                                                  |
| --------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Node.js   | [@onesignal/node-onesignal](https://www.npmjs.com/package/@onesignal/node-onesignal)               | [GitHub](https://github.com/OneSignal/node-onesignal)       |
| Python    | [onesignal-python-api](https://pypi.org/project/onesignal-python-api/)                             | [GitHub](https://github.com/OneSignal/onesignal-python-api) |
| Java      | [onesignal-java-client](https://central.sonatype.com/artifact/com.onesignal/onesignal-java-client) | [GitHub](https://github.com/OneSignal/onesignal-java-api)   |
| Go        | [onesignal-go-api](https://pkg.go.dev/github.com/OneSignal/onesignal-go-api)                       | [GitHub](https://github.com/OneSignal/onesignal-go-api)     |
| PHP       | [onesignal/onesignal-php-api](https://packagist.org/packages/onesignal/onesignal-php-api)          | [GitHub](https://github.com/OneSignal/onesignal-php-api)    |
| Ruby      | [onesignal](https://rubygems.org/gems/onesignal)                                                   | [GitHub](https://github.com/OneSignal/onesignal-ruby-api)   |
| C# (.NET) | [OneSignalApi](https://www.nuget.org/packages/OneSignalApi)                                        | [GitHub](https://github.com/OneSignal/onesignal-dotnet-api) |
| Rust      | [onesignal-rust-api](https://crates.io/crates/onesignal-rust-api)                                  | [GitHub](https://github.com/OneSignal/onesignal-rust-api)   |

***

## Installation

<Note>
  Version numbers below are examples. Check the package registry for each SDK to install the latest version.
</Note>

<Tabs>
  <Tab title="Node.js">
    ```bash theme={null}
    npm install @onesignal/node-onesignal
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install onesignal-python-api
    ```
  </Tab>

  <Tab title="Java">
    **Maven**

    ```xml theme={null}
    <dependency>
      <groupId>com.onesignal</groupId>
      <artifactId>onesignal-java-client</artifactId>
      <version>5.3.0</version>
    </dependency>
    ```

    **Gradle**

    ```groovy theme={null}
    implementation "com.onesignal:onesignal-java-client:5.3.0"
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/OneSignal/onesignal-go-api/v5
    ```
  </Tab>

  <Tab title="PHP">
    Add to `composer.json`:

    ```json theme={null}
    {
      "require": {
        "onesignal/onesignal-php-api": "^5.3"
      }
    }
    ```

    Then run `composer update`.
  </Tab>

  <Tab title="Ruby">
    Add to your `Gemfile`:

    ```ruby theme={null}
    gem 'onesignal', '~> 5.3'
    ```

    Then run `bundle install`.
  </Tab>

  <Tab title="C# (.NET)">
    ```bash theme={null}
    dotnet add package OneSignalApi
    ```
  </Tab>

  <Tab title="Rust">
    Add to `Cargo.toml` under `[dependencies]`:

    ```toml theme={null}
    onesignal-rust-api = "5.3.0"
    ```
  </Tab>
</Tabs>

***

## Configuration

Every SDK requires authentication via API keys. Two key types are available:

* **REST API Key** — required for most endpoints (sending notifications, managing users, etc.). Found in your app's **Settings > Keys & IDs**.
* **Organization API Key** — only required for organization-level endpoints like creating or listing apps. Found in **Organization Settings**.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const OneSignal = require('@onesignal/node-onesignal');

    const configuration = OneSignal.createConfiguration({
      restApiKey: 'YOUR_REST_API_KEY',
      organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',
    });

    const client = new OneSignal.DefaultApi(configuration);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import onesignal
    from onesignal.api import default_api

    configuration = onesignal.Configuration(
        rest_api_key='YOUR_REST_API_KEY',
        organization_api_key='YOUR_ORGANIZATION_API_KEY',
    )

    with onesignal.ApiClient(configuration) as api_client:
        client = default_api.DefaultApi(api_client)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.onesignal.client.ApiClient;
    import com.onesignal.client.Configuration;
    import com.onesignal.client.auth.HttpBearerAuth;
    import com.onesignal.client.api.DefaultApi;

    ApiClient defaultClient = Configuration.getDefaultApiClient();

    HttpBearerAuth restApiAuth = (HttpBearerAuth) defaultClient
        .getAuthentication("rest_api_key");
    restApiAuth.setBearerToken("YOUR_REST_API_KEY");

    HttpBearerAuth orgApiAuth = (HttpBearerAuth) defaultClient
        .getAuthentication("organization_api_key");
    orgApiAuth.setBearerToken("YOUR_ORGANIZATION_API_KEY");

    DefaultApi client = new DefaultApi(defaultClient);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import onesignal "github.com/OneSignal/onesignal-go-api"

    restAuth := context.WithValue(
        context.Background(),
        onesignal.RestApiKey,
        "YOUR_REST_API_KEY",
    )

    orgAuth := context.WithValue(
        restAuth,
        onesignal.OrganizationApiKey,
        "YOUR_ORGANIZATION_API_KEY",
    )

    apiClient := onesignal.NewAPIClient(onesignal.NewConfiguration())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use onesignal\client\api\DefaultApi;
    use onesignal\client\Configuration;
    use GuzzleHttp;

    $config = Configuration::getDefaultConfiguration()
        ->setRestApiKeyToken('YOUR_REST_API_KEY')
        ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');

    $client = new DefaultApi(
        new GuzzleHttp\Client(),
        $config
    );
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'onesignal'

    OneSignal.configure do |config|
      config.rest_api_key = 'YOUR_REST_API_KEY'
      config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'
    end

    client = OneSignal::DefaultApi.new
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    using OneSignalApi.Api;
    using OneSignalApi.Client;

    var config = new Configuration();
    config.BasePath = "https://api.onesignal.com";
    config.AccessToken = "YOUR_REST_API_KEY";

    var client = new DefaultApi(config);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use onesignal::apis::configuration::Configuration;

    fn create_configuration() -> Configuration {
        let mut config = Configuration::new();
        config.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
        config.organization_api_key_token = Some("YOUR_ORGANIZATION_API_KEY".to_string());
        config
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Store your API keys in environment variables or a secrets manager. Never commit them to source control.
</Warning>

***

## Send a push notification

Send push notifications to web and mobile [Subscriptions](./subscriptions) by targeting a segment. These examples show the happy path — add error handling (try/catch, error callbacks) for production use.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.contents = { en: 'Hello from OneSignal!' };
    notification.headings = { en: 'Push Notification' };
    notification.included_segments = ['Subscribed Users'];

    const response = await client.createNotification(notification);
    console.log('Notification ID:', response.id);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        contents=onesignal.StringMap(en='Hello from OneSignal!'),
        headings=onesignal.StringMap(en='Push Notification'),
        included_segments=['Subscribed Users'],
    )

    response = client.create_notification(notification)
    print('Notification ID:', response.id)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.onesignal.client.model.Notification;
    import com.onesignal.client.model.StringMap;

    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");

    StringMap contents = new StringMap();
    contents.en("Hello from OneSignal!");
    notification.setContents(contents);

    StringMap headings = new StringMap();
    headings.en("Push Notification");
    notification.setHeadings(headings);

    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));

    var response = client.createNotification(notification);
    System.out.println("Notification ID: " + response.getId());
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Hello from OneSignal!")})
    notification.SetHeadings(onesignal.StringMap{En: onesignal.PtrString("Push Notification")})
    notification.SetIncludedSegments([]string{"Subscribed Users"})

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()

    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Notification ID:", response.GetId())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use onesignal\client\model\Notification;
    use onesignal\client\model\StringMap;

    $content = new StringMap();
    $content->setEn('Hello from OneSignal!');

    $headings = new StringMap();
    $headings->setEn('Push Notification');

    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setContents($content);
    $notification->setHeadings($headings);
    $notification->setIncludedSegments(['Subscribed Users']);

    $response = $client->createNotification($notification);
    echo 'Notification ID: ' . $response->getId();
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      contents: { en: 'Hello from OneSignal!' },
      headings: { en: 'Push Notification' },
      included_segments: ['Subscribed Users']
    })

    response = client.create_notification(notification)
    puts "Notification ID: #{response.id}"
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    using OneSignalApi.Model;

    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        Contents = new StringMap(en: "Hello from OneSignal!"),
        Headings = new StringMap(en: "Push Notification"),
        IncludedSegments = new List<string> { "Subscribed Users" }
    };

    var response = client.CreateNotification(notification);
    Console.WriteLine("Notification ID: " + response.Id);
    ```

    Note: .NET SDK does not normalize newline characters automatically. If your content contains `\r\n` normalize it before passing to `Contents`:

    ```csharp theme={null}
    var normalizedContent = yourContent
       .Replace("\\r\\n", "\n")
       .Replace("\\n", "\n")
       .Replace("\r\n", "\n")
       .Replace("\r", "\n");
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use onesignal::apis::default_api;
    use onesignal::models::{Notification, StringMap};

    let mut contents = StringMap::new();
    contents.en = Some("Hello from OneSignal!".to_string());

    let mut headings = StringMap::new();
    headings.en = Some("Push Notification".to_string());

    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.contents = Some(Box::new(contents));
    notification.headings = Some(Box::new(headings));
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);

    let config = create_configuration();
    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Send an email

Send emails to [Subscriptions](./subscriptions) with the `email` channel.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.email_subject = 'Important Update';
    notification.email_body = '<h1>Hello!</h1><p>This is an HTML email.</p>';
    notification.included_segments = ['Subscribed Users'];
    notification.channel_for_external_user_ids = 'email';

    const response = await client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        email_subject='Important Update',
        email_body='<h1>Hello!</h1><p>This is an HTML email.</p>',
        included_segments=['Subscribed Users'],
        channel_for_external_user_ids='email',
    )

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");
    notification.setEmailSubject("Important Update");
    notification.setEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>");
    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
    notification.setChannelForExternalUserIds("email");

    var response = client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetEmailSubject("Important Update")
    notification.SetEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>")
    notification.SetIncludedSegments([]string{"Subscribed Users"})
    notification.SetChannelForExternalUserIds("email")

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setEmailSubject('Important Update');
    $notification->setEmailBody('<h1>Hello!</h1><p>This is an HTML email.</p>');
    $notification->setIncludedSegments(['Subscribed Users']);
    $notification->setChannelForExternalUserIds('email');

    $response = $client->createNotification($notification);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      email_subject: 'Important Update',
      email_body: '<h1>Hello!</h1><p>This is an HTML email.</p>',
      included_segments: ['Subscribed Users'],
      channel_for_external_user_ids: 'email'
    })

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        EmailSubject = "Important Update",
        EmailBody = "<h1>Hello!</h1><p>This is an HTML email.</p>",
        IncludedSegments = new List<string> { "Subscribed Users" },
        ChannelForExternalUserIds = "email"
    };

    var response = client.CreateNotification(notification);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.email_subject = Some("Important Update".to_string());
    notification.email_body = Some("<h1>Hello!</h1><p>This is an HTML email.</p>".to_string());
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
    notification.channel_for_external_user_ids = Some("email".to_string());

    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Send an SMS

Send SMS text messages to [Subscriptions](./subscriptions) with the `sms` channel.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.contents = { en: 'Your SMS message content here' };
    notification.included_segments = ['Subscribed Users'];
    notification.channel_for_external_user_ids = 'sms';
    notification.sms_from = '+15551234567';

    const response = await client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        contents=onesignal.StringMap(en='Your SMS message content here'),
        included_segments=['Subscribed Users'],
        channel_for_external_user_ids='sms',
        sms_from='+15551234567',
    )

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    StringMap contents = new StringMap();
    contents.en("Your SMS message content here");

    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");
    notification.setContents(contents);
    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
    notification.setChannelForExternalUserIds("sms");
    notification.setSmsFrom("+15551234567");

    var response = client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Your SMS message content here")})
    notification.SetIncludedSegments([]string{"Subscribed Users"})
    notification.SetChannelForExternalUserIds("sms")
    notification.SetSmsFrom("+15551234567")

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $content = new StringMap();
    $content->setEn('Your SMS message content here');

    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setContents($content);
    $notification->setIncludedSegments(['Subscribed Users']);
    $notification->setChannelForExternalUserIds('sms');
    $notification->setSmsFrom('+15551234567');

    $response = $client->createNotification($notification);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      contents: { en: 'Your SMS message content here' },
      included_segments: ['Subscribed Users'],
      channel_for_external_user_ids: 'sms',
      sms_from: '+15551234567'
    })

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        Contents = new StringMap(en: "Your SMS message content here"),
        IncludedSegments = new List<string> { "Subscribed Users" },
        ChannelForExternalUserIds = "sms",
        SmsFrom = "+15551234567"
    };

    var response = client.CreateNotification(notification);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let mut contents = StringMap::new();
    contents.en = Some("Your SMS message content here".to_string());

    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.contents = Some(Box::new(contents));
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
    notification.channel_for_external_user_ids = Some("sms".to_string());
    notification.sms_from = Some("+15551234567".to_string());

    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Full API reference

Each server SDK supports the same set of API endpoints. Refer to your SDK's API documentation for the complete method list, including users, subscriptions, segments, templates, and more.

| SDK       | API reference                                                                                     |
| --------- | ------------------------------------------------------------------------------------------------- |
| Node.js   | [DefaultApi.md](https://github.com/OneSignal/node-onesignal/blob/main/DefaultApi.md)              |
| Python    | [DefaultApi.md](https://github.com/OneSignal/onesignal-python-api/blob/main/docs/DefaultApi.md)   |
| Java      | [DefaultApi.md](https://github.com/OneSignal/onesignal-java-api/blob/main/docs/DefaultApi.md)     |
| Go        | [DefaultApi.md](https://github.com/OneSignal/onesignal-go-api/blob/main/docs/DefaultApi.md)       |
| PHP       | [DefaultApi.md](https://github.com/OneSignal/onesignal-php-api/blob/main/docs/Api/DefaultApi.md)  |
| Ruby      | [DefaultApi.md](https://github.com/OneSignal/onesignal-ruby-api/blob/main/docs/DefaultApi.md)     |
| C# (.NET) | [DefaultApi.md](https://github.com/OneSignal/onesignal-dotnet-api/blob/main/docs/DefaultApi.md)   |
| Rust      | [default\_api docs](https://github.com/OneSignal/onesignal-rust-api/blob/main/docs/DefaultApi.md) |

For the underlying REST API, see the [complete API reference](/reference/create-message).

***

## FAQ

### Which server SDK should I choose?

Use the SDK that matches your backend language. All server SDKs are generated from the same OpenAPI specification and support the same endpoints, so functionality is identical across languages.

### What is the difference between the REST API Key and Organization API Key?

The **REST API Key** is scoped to a single app and is required for most operations like sending notifications and managing users. The **Organization API Key** is scoped to your organization and is only needed for creating or listing apps. Most integrations only need the REST API Key.

### Can I use the REST API directly instead of an SDK?

Yes. The server SDKs are convenience wrappers around the [OneSignal REST API](/reference/create-message). You can call the API directly using any HTTP client with the `key` authentication scheme (`Authorization: key YOUR_REST_API_KEY`).

### Are these SDKs auto-generated?

Yes. All server SDKs are generated from the OneSignal OpenAPI specification using [OpenAPI Generator](https://openapi-generator.tech). This ensures consistent API coverage across all languages.

***

## Related pages

<Columns>
  <Card title="REST API overview" icon="code" href="/reference/rest-api-overview">
    Endpoints, authentication, rate limits, and request/response formats.
  </Card>

  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    Find your App ID, REST API key, and Organization API key.
  </Card>

  <Card title="Transactional messages" icon="paper-plane" href="./transactional-messages">
    Send OTPs, receipts, and time-sensitive alerts via API with personalized data.
  </Card>

  <Card title="Identity verification" icon="shield-halved" href="./identity-verification">
    Secure your integration with server-generated JWTs to prevent User impersonation.
  </Card>
</Columns>


# Add a player
Source: https://documentation.onesignal.com/reference/add-a-device

POST `https://onesignal.com/api/v1/players`

Register a new Subscription (aka player) to one of your OneSignal apps.

<Warning>
  This is a Legacy API. Use [Create User](/reference/create-user) or [Create Subscription](/reference/create-subscription) instead.
</Warning>

***

## Headers

| Header          | Value                     | Required | Description                      |
| --------------- | ------------------------- | -------- | -------------------------------- |
| `Content-Type`  | `application/json`        | Yes      | The content type of the request. |
| `Authorization` | `Basic YOUR_REST_API_KEY` | Yes      | Your OneSignal REST API key.     |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                                |
| -------------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                                     |
| `device_type`        | integer | Yes      | Device platform: 0 = iOS, 1 = Android, 2 = Amazon, 3 = Windows Phone, etc. |
| `identifier`         | string  | No       | Push token, email address, or phone number.                                |
| `language`           | string  | No       | Language code (e.g. "en").                                                 |
| `timezone`           | integer | No       | Time zone offset in seconds.                                               |
| `game_version`       | string  | No       | Version of your app.                                                       |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                                         |
| `device_os`          | string  | No       | Operating system version (e.g., "13.3").                                   |
| `ad_id`              | string  | No       | Advertising ID.                                                            |
| `sdk`                | string  | No       | OneSignal SDK version (e.g., "050201" for 5.2.1).                          |
| `session_count`      | integer | No       | Number of times the user has used the app.                                 |
| `tags`               | object  | No       | Custom tags as key-value pairs.                                            |
| `external_user_id`   | string  | No       | Your system's user ID for this device.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc.                 |

***

## Example Request

```json theme={null}
POST /api/v1/players HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "device_type": 1,
  "identifier": "abcdef123456",
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_model": "Pixel 4",
  "device_os": "12",
  "ad_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sdk": "050401",
  "session_count": 5,
  "tags": {
    "user_type": "free",
    "level": "10"
  },
  "external_user_id": "user123",
  "notification_types": 1
}
```

***

## Response

```json theme={null}
{
  "id": "Subscription_id_string"
}
```

## Errors

* 400 Bad Request – Invalid parameters or missing required fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Not allowed for your account type or plan.


# Cancel message
Source: https://documentation.onesignal.com/reference/cancel-message

DELETE /notifications/{message_id}?app_id={app_id}
Stop a scheduled or currently outgoing message.

## Overview

The Cancel message API can be used to stop scheduled messages from being sent. It does not delete or remove the message from the app. If a message is in the process of sending, then canceling it may not fully prevent all targeted users from receiving it.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users, scheduling the message in the future with `send_after`. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and use this API to cancel sending the message to the user if not needed anymore.

If you need a way to remove a notification already sent to a user, see [Remove notifications & TTL](/docs/en/push).

***


# Copy template to another app
Source: https://documentation.onesignal.com/reference/copy-template-to-another-app

POST /templates/{template_id}/copy_to_app?app_id={app_id}
Create a duplicate of a template in another app. The new template will be completely separate from the original (including having a new template_id) but will be created with all the same content.

## Overview

This API allows you to copy a template from one app (`app_id`) to another (`target_app_id`). The duplicated template will have the same content as the original, but a new unique `template_id`.

<Note>
  If you are trying to copy an email template, we also have an [Email Template Forwarding](/docs/en/email-template-forwarding) feature that does not require an API call.

  Both options support HTML and Drag & Drop email templates.
</Note>

***

## Requirements

* **Organization Membership:** Both the `app_id` and `target_app_id` must belong to the same [Organization](/docs/en/apps-organizations).
* **Authorization Required:** You must use your [Organization API key](/docs/en/keys-and-ids#organization-api-key), not an app-level REST API key.
* **Permissions Note:** Your user must have admin-level access to both the source and target apps. If not, the request will fail with a "permission denied" error.

***

## Parameters

* `template_id` (path param): UUID of the template to be copied.
* `app_id` (query param): ID of the app where the original template exists.
* `target_app_id` (body param): ID of the app where the template will be duplicated.

***

## How to Use

### 1. Locate the Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

### 2. Get App IDs

Refer to [Keys & IDs](/docs/en/keys-and-ids) to find your `app_id` and `target_app_id`.

***

## Response

The response will include:

* The new `template_id` for the copied template
* Confirmation of successful creation
* Any warnings if applicable (e.g., limited fields copied)

***


# Create or update alias
Source: https://documentation.onesignal.com/reference/create-alias

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Create or update one or more user aliases when you already know an existing alias. This API performs an upsert on the user’s identity object—either adding new aliases or updating existing ones.

## Overview

Use this API to manage user aliases by providing one known alias (such as `external_id`, `onesignal_id`, or a custom alias) and specifying additional aliases to add or update.

This endpoint focuses solely on the `identity` object. If you need to fully create a user with subscriptions and properties, use the [Create user](/reference/create-user) API instead.

<Note>
  * If an alias with the same `alias_label` already exists for the user, it will be updated. If it doesn’t exist, a new alias will be created.
  * Want to use a subscription instead of an alias to identify the user? Use [Create alias (by subscription)](/reference/create-alias-by-subscription).
</Note>

See also:

* [Users](/docs/en/users) – for details on OneSignal ID and External ID
* [Aliases](/docs/en/aliases) – for setting and managing custom aliases
* [Delete alias](/reference/delete-alias) – for removing aliases

***

## How to use this API

To identify the user:

* Use `alias_label` for the type of alias you know (e.g., `external_id`, `onesignal_id`, or a custom alias)
* Use `alias_id` for the value of that alias

<Note>
  We strongly recommend setting the `external_id` as your primary user identifier. This can be done through our frontend SDK's login method when a user signs in to your app or website. It helps OneSignal associate the user's push, email, and SMS subscriptions to a unified user identity.
</Note>

Changes to the identity object take effect immediately upon request.

Alias keys (`alias_label`) and values (`alias_id`) are each limited to **128 characters**. A user can have up to **10 custom aliases** total.

***


# Create alias (by subscription)
Source: https://documentation.onesignal.com/reference/create-alias-by-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Create or update an alias for a user using a known subscription ID.

Create or update an alias for a user using a known subscription ID.

# Overview

Use this API to add or update aliases associated with a user when you only know at least one subscription ID. This API is handy for scenarios where the user's identity is unknown, but a subscription is available.

To remove an alias, see [Delete alias](/reference/delete-alias) API.

***

# How to use this API

You must know the `subscription_id` of the subscription that belongs to the user in which you want to update. Subscription IDs are UUIDs generated by OneSignal and cannot change. See [Subscriptions](/docs/en/subscriptions) for details.

This endpoint performs an upsert—if the user already has an alias with the specified alias label, it gets updated; otherwise, a new alias will be created.

The request body must include an identity object containing one or more aliases to be created or updated.

The OneSignal ID is read-only and used only for fetching. See [Users](/docs/en/users) for details.

Aliases are updated immediately upon request.

***


# Create an app
Source: https://documentation.onesignal.com/reference/create-an-app

POST /apps
Programmatically create a new OneSignal app via the REST API. This guide explains required fields, supported platform configurations (Web, Android, iOS), and how to properly authenticate using your Organization API key.

## Overview

Use this API to programmatically create a new OneSignal app. This is useful for automating app setup, particularly when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need to Base64 encode your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns):

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates):

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Create API key
Source: https://documentation.onesignal.com/reference/create-api-key

POST /apps/{app_id}/auth/tokens
Use the OneSignal API to create a new Rich Authentication Token (App API Key) for a specific app. This guide explains how to authenticate with the Organization API key and configure optional IP allowlists using CIDR notation.

## Overview

Use this API to create a new **App API Key** (also called a **Rich Authentication Token**) for a specific OneSignal app. These keys are used to authenticate API requests at the app level and offer enhanced security features, including optional IP allowlisting.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

### IP allowlisting

By default, the API key will not be restricted to any specific IP addresses. To enable IP allowlisting, you need to set the `ip_allowlist_mode` parameter to `explicit` and provide a list of allowed IP addresses in the `ip_allowlist` parameter.

If you want to set the explicit range of IPs that can use this API key, add them by setting `ip_allowlist_mode` to `explicit` and in `ip_allowlist` add the IPs in CIDRs notation as an array of string values.

***


# Create custom events
Source: https://documentation.onesignal.com/reference/create-custom-events

POST /apps/{app_id}/custom_events
The Custom Events API allows you to record user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones.

## Overview

The Custom Events API allows you to track user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones. See [Custom events](/docs/en/custom-events) for more information.

### Use Cases

Custom events can be used to:

* Enter users into [Journeys](/docs/en/journeys-settings)
* Trigger Journey [Wait Until](/docs/en/journeys-actions) nodes

### Error handling

If individual events can't be processed, an `errors` key will be returned in the response (with HTTP status 202) containing information about each failing event. The most common event-specific error is a failure to find a user associated with the External ID or OneSignal ID in the event.

If you'd like to retry sending events in the case of a failure, you only need to re-send the events for which errors were returned -- events that don't have an error associated with them are still processed. However, if a 5xx HTTP response is returned, you must retry the entire batch of events.

In either case, if you are implementing retry, make sure to also pass an [`idempotency_key`](/reference/idempotent-notification-requests).

### Duplicate events

If you implement retry behavior for your custom event delivery, please provide the [`idempotency_key`](/reference/idempotent-notification-requests) field. Each unique event should get its own unique UUID, and when retrying delivery for events, the same UUID must be provided. Duplicate events with the same `idempotency_key` will be ignored on a best-effort basis within a 4-hour period. This allows you to avoid erroneously triggering Journeys multiple times or incurring charges for storing unnecessary duplicate events.

***


# Sending messages with the OneSignal API
Source: https://documentation.onesignal.com/reference/create-message

Send push notifications, emails, SMS, and Live Activities with the OneSignal API. Covers audience targeting, message composition, scheduling, and response handling.

## Overview

This guide walks you through sending messages with the OneSignal API — from choosing a target audience to composing content, scheduling delivery, and validating responses. Each section covers channel-specific options and performance guidance.

### Prerequisites

1. Complete [Channel Setup](/docs/en/channel-setup) for the channels you plan to use: push, email, SMS, Live Activities.
2. Start accumulating [Subscriptions](/docs/en/subscriptions) for your users.
3. Have your REST API Key and App ID ready. See [Keys and IDs](/docs/en/keys-and-ids).

***

## Choose your target audience

You can target users with **one of the following methods per request**:

* **Aliases**: Specific users via unique IDs, emails, or phone numbers.
* **Segments**: Groups based on predefined behaviors or attributes.
* **Filters**: Custom rules using tags, location, activity, and more.

<Warning>
  Only one targeting method is allowed per message. For example, you cannot mix aliases and filters.
</Warning>

You can also target specific platforms (for example, `isAndroid`, `isIos`, `isAnyWeb`) when sending push notifications. By default, all push platforms are enabled.

### Aliases, emails, phone numbers

Target specific users or lists of users (up to 20,000 entries per request). This method is best for [Transactional Messages](/docs/en/transactional-messages).

<Accordion title="Aliases, emails, and phone numbers targeting parameters">
  <ParamField type="object">
    Target up to 20,000 users by their `external_id`, `onesignal_id`, or a custom alias. Combine with `target_channel` to select the delivery channel.

    ```json theme={null}
    {
      "include_aliases": {
        "external_id": [
          "user1",
          "user2",
          "user3"
        ]
      },
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="string">
    The targeted delivery channel. Required when using `include_aliases` or `included_segments` and sending SMS/RCS. Accepts `"push"`, `"email"`, or `"sms"`. The `"sms"` value covers both SMS and RCS — RCS messages are delivered through the SMS channel.

    ```json theme={null}
    {
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="array">
    Target users' specific [Subscriptions](/docs/en/subscriptions) by ID. Max 20,000 `subscription_id` per request.

    ```json theme={null}
    {
      "include_subscription_ids": [
        "1dd608f2-c6a1-11e3-851d-000c2940e62c"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send to specific email addresses (max 20,000 per request). Can only be used when sending [email](/reference/email). If the email address does not exist within the OneSignal App, a new email subscription is created.

    ```json theme={null}
    {
      "email_to": [
        "user1@example.com",
        "user2@example.com"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send SMS/MMS/RCS to phone numbers in [E.164 format](/docs/en/sms-setup#what-is-e164-format) (max 20,000 per request). Can only be used when sending [SMS/MMS/RCS](/reference/sms). If the phone number does not exist within the OneSignal App, a new SMS subscription is created.

    ```json theme={null}
    {
      "include_phone_numbers": [
        "+19999999999"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Segments

Target users in existing [segments](/docs/en/segmentation). Users in multiple segments only receive the message once.

<Accordion title="Segments targeting parameters">
  <ParamField type="array">
    Target predefined [segments](/docs/en/segmentation). Users who are in multiple segments only receive the message once. Combine with `excluded_segments` to exclude users from specific segments. When sending SMS/RCS, set `target_channel` to `"sms"` (or use the legacy `isSms=true` field).

    ```json theme={null}
    {
      "included_segments": [
        "Active Users",
        "Inactive Users"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Exclude users in these [segments](/docs/en/segmentation) even if they're in `included_segments`.

    ```json theme={null}
    {
      "included_segments": [
        "Subscribed Users"
      ],
      "excluded_segments": [
        "Inactive Users"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Filters

Build real-time audiences with `AND`/`OR` logic without creating segments first.

You can include up to **200 total entries per request**. This includes filter rows (for example, each `field`) and logical operators like `{"operator": "OR"}`.

<Accordion title="Filters targeting parameter details">
  <Info>
    **Performance guidance:**

    * **Fast:** Tag filters using `"="` or `"exists"`, and filters on `last_session`, `session_count`, or `country`.
    * **Slower:** Negation filters (`"!="`, `"not_exists"`) — especially with users who have many tags. Contact support to request indexing optimizations.
    * **Slow by default:** Numeric comparisons (`">"`, `"<"`) on tags or custom properties. Indexing may be available on request.
    * **Mixed performance:** Combining tag filters with other fields may increase computation time.
  </Info>

  <ParamField type="string">
    * Implicit `AND` logic between filters. Use `"operator": "OR"` to start a new branch.
    * `OR` filters are mutually exclusive. Recipients only need to satisfy one condition.
    * Allowed values: `"AND"`, `"OR"`.

    <CodeGroup>
      ```json AND example theme={null}
      // Users must satisfy both filters to be included.
      // Notice the AND operator is not required

      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      // The same example using the AND operator. This is not required.
      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "AND"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      ```

      ```json OR example theme={null}
      // Users can satisfy either filter to be included.

      "filters": [
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "tag", "key": "level", "relation": "=", "value": "20"}
      ]
      ```

      ```json Combinations theme={null}
      // In this example, users must either have:
      // The specified session_count AND tag requirement
      // Or it will be all records where last_session is satisfied
      {
        "name": "2 filters or 1",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"}
        ]
      }

      // Similar to the first example, this shows how to require a specific field
      // across other filters

      {
        "name": "3 filters, 1 required across all",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
        ]
      }

      // Example of 3 user groups with 2 requirements
      // (group_1 OR group_2 OR group_3) AND (requirement_1 OR requirement_2)

      {
        "name": "3 groups with 2 requirements",
        "filters": [
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"}
        ]
      }
      ```
    </CodeGroup>
  </ParamField>

  <ParamField type="object">
    ### `tag`

    Target based on custom user [Tags](/docs/en/add-user-data-tags).

    <Warning>
      Do not use tags for targeting individual users like a "user id".
      Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
    </Warning>

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
      * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
    * `key` = Tag key to compare.
    * `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

    ```json theme={null}
    "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "OR"},
      {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
    ]
    ```

    ### `country`

    Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "country", "relation": "=", "value": "US"},
        {"operator": "OR"},
        {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
      ]
      ```

    ### `last_session`

    Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "last_session", "relation": ">","hours_ago": "10"}
      ]
      ```

    ### `first_session`

    Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "first_session", "relation": "<","hours_ago": "24"}
      ]
      ```

    ### `session_count`

    Total number of sessions by the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="` or `"!="`
    * `value` = number of sessions. Example: `"1"`

      ```json theme={null}
      "filters": [
        {"field": "session_count", "relation": ">","value": "5"}
      ]
      ```

    ### `session_time`

    Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

    * `relation` = `">"` or `"<"`
    * `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

      ```json theme={null}
      "filters": [
        {"field": "session_time", "relation": ">","value": "86400"}
      ]
      ```

    ### `language`

    [User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = 2 character language code. Example: `"en"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "language", "relation": "=","value": "en"},
        {"operator": "OR"},
        {"field": "language", "relation": "in_array","value": "es,fr,de"}
      ]
      ```

    ### `app_version`

    App version set on the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = app version. Example: `"1.0.0"`
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "app_version", "relation": "=","value": "1.0.1"},
        {"operator": "OR"},
        {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
      ]
      ```

    ### `location`

    Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

    * `radius` = in meters
    * `lat` = latitude
    * `long` = longitude

      ```json theme={null}
      "filters": [
        {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
      ]
      ```
  </ParamField>
</Accordion>

***

## Craft your message

Each channel has its own set of fields. At a minimum, you need the following to send a displayable message:

* **Push and SMS** use `contents`
* **Email** uses `email_subject` and `email_body`
* Or reuse `template_id` if you created [templates](/docs/en/templates).

<CodeGroup>
  ```json Push and SMS theme={null}
  // Message request body
  {
    "contents": {
      "en": "Hello, world",
      "es": "Hola Mundo",
      "fr": "Bonjour le monde",
      "zh-Hans": "你好世界"
    }
  }
  ```

  ```json Email theme={null}
  // Message request body
  {
    "email_subject": "Hello, world",
    "email_body": "<html><body><h1>Hello, world</h1></body></html>"
  }
  ```
</CodeGroup>

For advanced customization—like adding images, buttons, sounds, or tracking—see the channel-specific options below.

### Push notification options

Below are the most common parameters for push notifications. For the full list of options, see the [Push notification reference](/reference/push-notification).

<Accordion title="Push notification options">
  #### Content and text

  * [`contents`](/reference/push-notification#body-contents) – Main message body.
  * [`headings`](/reference/push-notification#body-headings) – Title of the notification.
  * [`subtitle`](/reference/push-notification#body-subtitle) – Secondary line of text.
  * [`template_id`](/reference/push-notification#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Appearance

  * [`ios_attachments`](/reference/push-notification#body-ios-attachments) – Images/video/media.
  * [`big_picture`](/reference/push-notification#body-big-picture) – Large image (Android).
  * [`chrome_web_image`](/reference/push-notification#body-chrome-web-image) – Large image (Chrome).
  * [`small_icon`](/reference/push-notification#body-small-icon)
  * [`large_icon`](/reference/push-notification#body-large-icon)
  * [`buttons`](/reference/push-notification#body-buttons) – Action buttons.

  #### Delivery and priority

  * [`android_channel_id`](/reference/push-notification#body-android-channel-id)
  * [`priority`](/reference/push-notification#body-priority) – Delivery urgency.
  * [`ios_interruption_level`](/reference/push-notification#body-ios-interruption-level)
  * [`collapse_id`](/reference/push-notification#body-collapse-id) – Replaces older messages.

  #### Data and extras

  * [`data`](/reference/push-notification#body-data) – Custom key-value pairs sent to your app.
  * [`url`](/reference/push-notification#body-url) – Opens when notification is tapped.
</Accordion>

### Email options

<Accordion title="Email options">
  #### Content

  * [`email_subject`](/reference/email#body-email-subject)
  * [`email_body`](/reference/email#body-email-body)
  * [`email_preheader`](/reference/email#body-email-preheader)

  #### Appearance

  * [`template_id`](/reference/email#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Sender info

  * [`email_from_name`](/reference/email#body-email-from-name)
  * [`email_reply_to`](/reference/email#body-email-reply-to)
</Accordion>

### SMS/MMS options

<Accordion title="SMS/MMS options">
  #### Content

  * [`contents`](/reference/sms#body-contents)
  * [`template_id`](/reference/sms#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Media (MMS only)

  * [`sms_media_urls`](/reference/sms#body-sms-media-urls)

  #### Sender info

  * [`sms_from`](/reference/sms#body-sms-from)
</Accordion>

***

## Schedule and per-user delivery

By default, messages are sent immediately. You can schedule delivery in advance and optimize timing per user based on their local timezone or recent activity.

<Accordion title="Schedule delivery and per-user optimization parameters">
  <ParamField type="string">
    Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript's Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring).

    ```json theme={null}
    {
      "send_after": "2025-09-24T14:00:00-07:00"
    }
    ```
  </ParamField>

  <ParamField type="string">
    Controls how push and email messages are delivered on a per-user basis. Not available for SMS.

    * `"timezone"`: Sends at the same local time across time zones.
    * `"last-active"`: Delivers based on each user's most recent session.

    Not compatible with [push throttling](/docs/en/throttling). When `delayed_option` is set, you must also set `throttle_rate_per_minute` to `0`.

    ```json theme={null}
    {
      "delayed_option": "last-active",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>

  <ParamField type="string">
    Use with `delayed_option: "timezone"` to set a consistent daily delivery time. Accepted formats:

    * `"9:00AM"` (12-hour)
    * `"21:45"` (24-hour)
    * `"09:45:30"` (HH:mm:ss)

    Example — Send every day at 9 AM in each user's local time:

    ```json theme={null}
    {
      "delayed_option": "timezone",
      "delivery_time_of_day": "9:00AM",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>
</Accordion>

***

## Submit the request

This final example sends a localized push notification to all subscribed users:

```curl theme={null}
curl -X "POST" "https://api.onesignal.com/notifications" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Key YOUR_API_KEY' \
     -d $'{
      "target_channel": "push",
      "included_segments": [
        "Subscribed Users"
      ],
      "app_id": "YOUR_APP_ID",
      "contents": {
        "en": "Hello, world",
        "es": "Hola mundo",
        "fr": "Bonjour le monde",
        "zh-Hans": "你好世界"
      }
    }'
```

Once the request is sent, OneSignal forwards it to the appropriate downstream provider, which then delivers it to the recipient:

* **Push:** FCM, APNs, or HMS
* **Email:** your email service provider
* **SMS:** Twilio

### Handle the response

You receive a `200` response code if the request is valid and accepted.

* If an `id` is returned, the message was created successfully. Save this `id` for future tracking and reference of message stats via the [View message API](/reference/view-message).
* If no `id` is returned, the message was not created, likely because there are no valid [subscriptions](/docs/en/subscriptions) in the target audience.

**Response details by channel:**

* [Push](/reference/push-notification#response-id)
* [Email](/reference/email#response-id)
* [SMS](/reference/sms#response-id)

<Note>
  See our [REST API Overview](/reference/rest-api-overview#reliability-and-delivery) page for details on retries and [rate limits](/reference/rate-limits).
</Note>

***

## FAQ

### Can I combine `include_aliases`, `included_segments`, and `filters` in one request?

No. Each request must use exactly one targeting method. Mixing them returns a validation error. Choose aliases for transactional sends to specific users, segments for predefined audiences, or filters for ad-hoc audiences built with `AND`/`OR` logic.

### Does `target_channel: "sms"` cover RCS?

Yes. The `target_channel` enum accepts `"push"`, `"email"`, and `"sms"`. RCS messages are delivered through the SMS channel — there is no separate `"rcs"` value. OneSignal decides whether to send via RCS or SMS based on the recipient's device and your sender configuration.

### My request returned `200` but no `id`. What happened?

The request was valid but no message was created, typically because the target audience contains no valid subscriptions for the selected channel. Common causes include a segment that resolves to zero users, all targeted aliases being unsubscribed, or phone numbers that don't match an existing SMS subscription.

### Can I use `//` comments in the JSON request body?

No. The `//` comments in the examples on this page are illustrative only. Strict JSON does not support comments — strip them before sending to the API.

### How is the `Sent` count in reports related to the API response?

The dashboard `Sent` metric is a composite. To derive it from the [View message API](/reference/view-message), sum `successful + failed + errored`. See the [Metrics glossary](/docs/en/analytics-metrics-glossary) for the full mapping between dashboard, API, CSV, and Event Streams names.

***

## Next steps

Refer to the channel-specific APIs to customize delivery further:

* [Push notification](/reference/push-notification)
* [Email](/reference/email)
* [SMS](/reference/sms)
* [Live Activities](/reference/start-live-activity)
* [Server-Side SDKs](/docs/en/server-sdk-reference)


# Create segment
Source: https://documentation.onesignal.com/reference/create-segments

POST /apps/{app_id}/segments
Programmatically create segments in your OneSignal app using flexible filters and targeting rules.

## Overview

Use this API to create new [Segments](/docs/en/segmentation) programmatically. These segments are then accessible in the OneSignal Dashboard and usable in messages, Journeys, and in-app messaging campaigns.

<Note>
  To modify an existing segment, use the [Update segment](/reference/update-segment) API.
</Note>

***

## How to use this API

This endpoint allows your backend to define audience segments by passing in a combination of filters and logical operators like `"AND"` and `"OR"`, mirroring the segmentation capabilities of the OneSignal Dashboard.

### Name the segment

The name of the segment as it shows in the OneSignal dashboard and accessible via the `included_segments` and `excluded_segments` targeting parameters.

### Describe the segment

Optionally include a `description` (max 255 characters) to record the segment's purpose. The description is returned by the [View segments](/reference/view-segments) and [View segment](/reference/view-segment) APIs.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "10"}
  ]
}
```

### Define the `filters`

Available filters:

* [operator](#operator)
* [tag](#tag)
* [last\_session](#last_session)
* [first\_session](#first_session)
* [session\_count](#session_count)
* [session\_time](#session_time-1)
* [language](#language)
* [app\_version](#app_version)
* [location](#location)
* [country](#country)

### `operator`

**Description**

Allows you to combine or separate properties. Filters combined with an `"AND"` have higher priority than `"OR"` filters.

* `"AND"` = the 2+ connected filters must be satisfied for the recipient to be included. Filter entries use this by default and its not required to be included.
* `"OR"` = the 2 filters separated by the `"OR"` operator are mutually exclusive. The recipients only need to satisfy the conditions on either side of the `"OR"` operator.

<CodeGroup>
  ```json AND example theme={null}
  // Users must satisfy both filters to be included.
  // Notice the AND operator is not required

  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  // The same example using the AND operator. This is not required.
  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "AND"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  ```

  ```json OR example theme={null}
  // Users can satisfy either filter to be included.

  "filters": [
    {"field": "tag", "key": "level", "relation": "=", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "level", "relation": "=", "value": "20"}
  ]
  ```

  ```json Combinations theme={null}
  // In this example, users must either have:
  // The specified session_count AND tag requirement
  // Or it will be all records where last_session is satisfied
  {
    "name": "2 filters or 1",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"}
    ]
  }

  // Similar to the first example, this shows how to require a specific field
  // across other filters

  {
    "name": "3 filters, 1 required across all",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
    ]
  }
  ```
</CodeGroup>

### `tag`

**Description**

Target based on custom user [Tags](/docs/en/add-user-data-tags).

<Warning>
  Do not use tags for targeting individual users like a "user id".
  Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
</Warning>

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
  * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
* `key` = Tag key to compare.
* `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

```json theme={null}
"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "OR"},
  {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
]
```

### `last_session`

**Description**

Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "last_session", "relation": ">","hours_ago": "10"}
  ]
  ```

### `first_session`

**Description**

Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "first_session", "relation": "<","hours_ago": "24"}
  ]
  ```

### `session_count`

**Description**

Total number of sessions by the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="` or `"!="`
* `value` = number of sessions. Example: `"1"`

  ```json theme={null}
  "filters": [
    {"field": "session_count", "relation": ">","value": "5"}
  ]
  ```

### `session_time`

**Description**

Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

* `relation` = `">"` or `"<"`
* `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

  ```json theme={null}
  "filters": [
    {"field": "session_time", "relation": ">","value": "86400"}
  ]
  ```

### `language`

**Description**

[User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = 2 character language code. Example: `"en"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "language", "relation": "=","value": "en"},
    {"operator": "OR"},
    {"field": "language", "relation": "in_array","value": "es,fr,de"}
  ]
  ```

### `app_version`

**Description**

App version set on the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = app version. Example: `"1.0.0"`
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "app_version", "relation": "=","value": "1.0.1"},
    {"operator": "OR"},
    {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
  ]
  ```

### `location`

**Description**

Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

* `radius` = in meters
* `lat` = latitude
* `long` = longitude

  ```json theme={null}
  "filters": [
    {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
  ]
  ```

### `country`

**Description**

Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "=", "value": "US"},
    {"operator": "OR"},
    {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
  ]
  ```

***


# Create Subscription by alias
Source: https://documentation.onesignal.com/reference/create-subscription

POST /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions
Use this API to attach a new subscription—such as email, SMS, or push notification—to an existing OneSignal user identified by an alias.

## Overview

This API allows you to add a **new Subscription** to an existing [User](/docs/en/users) via an alias identifier. A *Subscription* reflects a user's intent to receive messages through a specific communication channel, such as email, SMS, or push notifications. See [Subscriptions](/docs/en/subscriptions) for additional context.

If you're looking to **create a new user and add Subscriptions simultaneously**, use the [Create User](/reference/create-user) API instead.

***

## How to use this API

To attach a Subscription, the user must already exist and be referenced using an alias. The `alias_label` and `alias_id` path parameters define how the user is identified:

* Common alias: `external_id`
* Other options: `onesignal_id`, or custom aliases

For details, refer to [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

## Required Fields

Each Subscription must include at least:

* `type`: the channel (e.g., `Email`, `SMS`, `iOSPush`)
* `token`: the unique identifier for the channel (e.g., email address, phone number, push token)

If the specified `type` and `token` already exist in the app, the Subscription will be transferred to the user identified in the path parameters.

***


# Create template
Source: https://documentation.onesignal.com/reference/create-template

POST /templates
Create reusable message templates for push, email, and SMS channels. Templates can be accessed through both the dashboard and API using a `template_id`.

## Overview

Use this endpoint to create a new message template in your OneSignal app. Once created, the template becomes available for use when sending messages via both the Dashboard and the REST API by referencing the `template_id`.

Templates streamline and standardize message content across push, email, and SMS channels.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Before using this endpoint, ensure that the target channel (push, email, or SMS) is properly configured in your OneSignal app. See [Channel Setup](/docs/en/channel-setup) for guidance.

### Push Templates

**Requirements:**

* Set the `contents` property with the English (`en`) language key.
* All [Push Channel Properties](/reference/push-notification) are valid for use in push templates.
* By default, all push platforms are enabled. You can target specific platforms by explicitly setting them (e.g., `isAndroid: true` disables others).

### Email Templates

**Requirements:**

* Set `isEmail: true`.
* Include both `email_subject` and `email_body`.
* All [Email Channel Properties](/reference/email) are valid for use in email templates.

### SMS Templates

**Requirements:**

* Set `isSMS: true`.
* Provide SMS-specific parameters like `contents`.
* All [SMS Channel Properties](/reference/sms) are valid for use in SMS templates.

***


# Create user
Source: https://documentation.onesignal.com/reference/create-user

POST /apps/{app_id}/users
Create a new user or modify the subscriptions associated with an existing User.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint enables you to create and manage users outside of frontendSDK-based sessions. It's primarily used to:

* Import users from other systems.
* Programmatically define users by assigning identifiers (aliases), properties (e.g., tags), and messaging subscriptions (e.g., email, mobile, SMS).

If you're using the frontend SDKs, user creation is typically handled automatically via methods like `login`, `addEmail`, and `addSms`. See [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) for conceptual guidance.

***

## How to use this API

To successfully create a user via the API:

* You must provide at least one unique identifier via the `identity` and Subscription via the `subscriptions` fields.
* You can optionally include user profile data (`properties`) and one or more messaging `subscriptions`.

## Key Concepts

### Aliases

Aliases uniquely identify a user and should include an `external_id` (the recommended identifier). They allow you to reference users across platforms or external systems. Up to 10 custom aliases are supported. Each alias key and value has a maximum length of 128 characters.

### Properties

User properties store information such as tags, location, activity, and device data. These attributes help you personalize campaigns and optimize engagement strategies.

### Subscriptions

A user can have up to **20 subscriptions** (across email, SMS, push, etc.). Subscriptions connect users to channels for message delivery and are transferable across users. See [Subscriptions](/docs/en/subscriptions) for more.

***


# Export subscriptions CSV
Source: https://documentation.onesignal.com/reference/csv-export

POST /players/csv_export
Generate a GZip-compressed CSV export of your current subscription data using this API endpoint.

## Overview

Use this endpoint to request a GZip-compressed CSV export of all your [Subscriptions data](/docs/en/subscriptions) from OneSignal. The export includes both default and optional user data fields, and supports filters to refine the dataset. The file is downloadable via a URL returned in the API response.

***

## How to use this API

By default, this will export all Subscriptions within the app.

**Optional filters:**

You can narrow the export using:

* `segment_name`: Only export Subscriptions from a specific segment. Segment membership rules determine which subscription statuses are included. Use with `include_unsubscribed` to include unsubscribed subscriptions.
* `last_active_since`: Export Subscriptions where their `last_session` was after a specific Unix timestamp. Example: Use `1704067200` for Subscriptions active since January 1st, 2024.
* `include_unsubscribed`: When exporting a segment, set to `true` to include unsubscribed subscriptions alongside subscribed ones. By default, segment-filtered exports only return subscribed subscriptions. This parameter has no effect when `segment_name` is not provided.

**Example successful response:**

```json 200 OK theme={null}
{
  "csv_file_url": "https://onesignal.com/csv_exports/b2f7f966.../users_1849..._2024-11-10.csv.gz"
}
```

**Export time considerations:**

* Generation speed: \~2,000 records per second.
* File readiness: The `csv_file_url` may return a 404 until generation completes.
* Download retry: Poll the file URL at intervals until the file is ready.
* File expiration: The file remains available for 3 days after generation.
* Concurrency: Only one export per OneSignal account can run at a time.

**File not ready (404 response)**

```xml 404 CSV GET  theme={null}
This XML file does not appear to have any style information
associated with it. The document tree is shown below.
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

<Info>
  You can safely poll the `csv_file_url` until the file becomes available. Implement retry logic based on expected data volume and generation speed.

  Only one export is allowed at a time per account. Wait until the `.csv.gz` file is downloaded before triggering another export.
</Info>

***

## CSV data contents

The export includes two types of fields:

* **Default fields**: Always included unless excluded by schema changes.
* **Extra fields**: Must be explicitly requested using the `extra_fields` parameter.

### Default fields

* `id`: The Subscription ID.

* `identifier`: The push token, email address, or phone number depending on the Subscription type.

* `session_count`: The number of times the user has opened the app.

* `language`: The user's language in ISO 639-1 format.

* `timezone`: Deprecated — use `timezone_id` instead.

* `game_version`: The version of your app that the user is currently using.

* `device_os`: The device's operating system version.

* `device_type`: Integer representing channel/device type.
  * `0`: iOSPush
  * `1`: AndroidPush
  * `2`: FireOSPush
  * `5`: ChromePush
  * `7,17`: SafariPush
  * `11`: Email
  * `14`: SMS

* `device_model`: The device's hardware string.

* `ad_id`: Deprecated.

* `tags`: Custom key/value data.

* `last_active`: The last time the user was active.

* `playtime`: The total amount of time in seconds the user had the mobile app open.

* `created_at`: The first time the user was seen.

* `invalid_identifier`: Boolean flag for unsubscribed state.
  * `t`: Unsubscribed
  * `f`: Subscribed

### Extra fields (`extra_fields`)

Pass `extra_fields` in your request to include any of the following:

* `external_user_id`: Maps to the `external_id` of the user.

* `onesignal_id`: OneSignal's user ID.

* `location`: Adds the `lat` and `long` coordinates if set.

* `country`: The user's country in ISO 3166-1 Alpha 2 format.

* `ip`: The IP address if detected. Can be IPv4 or IPv6 format.

* `web_auth`: Only available to OneSignal SDKs. The `web_auth` key for web push.

* `web_p256`: Only available to OneSignal SDKs. The `web_p256` for web push.

* `unsubscribed_at`: The date and time the user last unsubscribed. They may resubscribe at any time. Check the `invalid_identifier` field to determine if they are currently subscribed.

* `notification_types`: Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/en/subscriptions#notification-types).

* `timezone_id`: The user's timezone in IANA format.

***


# Remove alias
Source: https://documentation.onesignal.com/reference/delete-alias

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}
Remove a specific alias from a user.

## Overview

Use this API to remove a specific alias from a user’s identity object without deleting the user. This operation only affects user identity labels—subscriptions and the core user record remain intact. To delete a user entirely, including all associated aliases and subscriptions, see the [Delete user](/reference/delete-user) API.

***

## How to use this API

To remove an alias from a user:

1. Identify the user via a known alias by specifying:

   * `alias_label` – the type of alias (e.g., email, external\_id)
   * `alias_id` – the unique identifier for that alias

2. Specify the alias to remove using:

   * `alias_label_to_delete` – the label of the alias to be deleted

   The `alias_label_to_delete` can be the same as the `alias_label` used to identify the user.

3. This action is performed synchronously—the alias is deleted immediately after the request is processed.

<Warning>
  The `onesignal_id` alias cannot be deleted. Only secondary aliases (like email, external\_id, etc.) are removable.
</Warning>

For a full explanation of identity management, see [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

***

## FAQ

### Can I delete the same alias that I used to look up the user?

Yes. This is a common scenario—especially if an alias was set incorrectly and needs to be removed. Just be sure to include that alias both as the identifier and as alias\_label\_to\_delete.

If you want to delete the entire user and all associated data, use the [Delete user](/reference/delete-user) API.

### What happens if I delete all aliases associated with the user?

A user will always retain at least one alias, the onesignal\_id. Even if you remove all other aliases, the user and their subscriptions remain linked to the onesignal\_id.

***


# Delete API key
Source: https://documentation.onesignal.com/reference/delete-api-key

DELETE /apps/{app_id}/auth/tokens/{token_id}
Delete a specific Rich Authentication Token (App API Key) for a OneSignal app. Requires your Organization API Key and the token's unique ID, not the token value itself.

## Overview

Use this API to delete a specific App API Key (Rich Authentication Token) for a single OneSignal.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Delete segment
Source: https://documentation.onesignal.com/reference/delete-segments

DELETE /apps/{app_id}/segments/{segment_id}
Delete segments from OneSignal. Does not delete users or subscriptions.

## Overview

The Delete segment method is used when you want to programmatically delete a segment from within the OneSignal Dashboard UI.

<Warning>
  Once a segment is deleted, it cannot be recovered. You will need to create a new segment with the same filters.
</Warning>

***

## How to use this API

You can pass in the `segment_id` dictating which segment from our dashboard will be deleted.

The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard as shown below:

<Frame>
  <img />
</Frame>

***


# Delete Subscription
Source: https://documentation.onesignal.com/reference/delete-subscription

DELETE /apps/{app_id}/subscriptions/{subscription_id}
Delete a specific subscription by its subscription_id. This stops messages from being sent to that subscription but does not prevent future subscriptions with the same token.

## Overview

Use this API to delete an existing Subscription and its associated properties. Deletion is **asynchronous**, and while the Subscription is being removed, messages will no longer be sent to it.

<Warning>
  This operation only deletes a **single Subscription**. To remove a **user and all their Subscriptions**, use the [Delete User](/reference/delete-user) API instead.
</Warning>

### What Happens When You Delete

* Messages will stop being sent to the deleted subscription.
* **Deleting a Subscription does not block new Subscriptions** with the same `token`.
  * If the app is reopened or a token is re-submitted (e.g., same email or phone), a **new Subscription** may be automatically created.
  * This ensures users can re-subscribe if needed without requiring manual intervention.

***

## How to Use This API

**Required:** `subscription_id`

You must provide the `subscription_id` of the subscription to be deleted. This ID is a UUID generated by OneSignal and is immutable.

To find the `subscription_id`:

1. Use the [View User](/reference/view-user) API.
2. Look at the `subscriptions` array in the response.
3. Identify the correct subscription by its `type`, `token`, or other metadata.
4. Use the corresponding `id` field as the `subscription_id`.

***


# Delete template
Source: https://documentation.onesignal.com/reference/delete-template

DELETE /templates/{template_id}?app_id={app_id}
Permanently delete a specific message template from your OneSignal app using its template ID. Templates used in Journeys must be removed from those Journeys before deletion.

## Overview

This endpoint allows you to delete a single template associated with your OneSignal app. Deletion is **immediate and irreversible**.

<Warning>
  If the template is currently used in a Journey, it cannot be deleted until that Journey has been deleted.
</Warning>

***

## How to use this API

Required Parameters

* `template_id` (path param): The OneSignal-generated UUID of the template to delete.
* `app_id` (query param): Your OneSignal App ID.

### Where to Find `template_id`

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# Delete user
Source: https://documentation.onesignal.com/reference/delete-user

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}
Delete a user including all associated properties, subscriptions, and identity.

## Overview

Use this API to permanently delete a user from your OneSignal project, including all associated subscriptions, properties, and aliases. The operation is asynchronous—user data will be deleted shortly after the request is accepted.

***

## How to use this API

To delete a user, you must be able to identify them using one of the following alias types:

* `external_id` (recommended and most common)
* `onesignal_id`
* A custom Alias that you have set

Pass the appropriate `alias_label` and corresponding `alias_id` in the request path.

<Warning>
  This operation deletes all data associated with the user, including:

  * All identity aliases
  * All channel subscriptions (push, email, SMS, etc.)
  * All custom user properties
</Warning>

## Because this is an irreversible operation, be sure that you really intend to delete the user and all their data.


# Delete player record
Source: https://documentation.onesignal.com/reference/delete-user-record

delete https://onesignal.com/api/v1/players/{player_id}?app_id={app_id}

Delete a player (aka Subscription).

<Warning>
  This is a Legacy API. Use [Delete User](/reference/delete-user) or [Delete Subscription](/reference/delete-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `app_id`    | string | Yes      | Your OneSignal App ID.         |
| `player_id` | string | Yes      | The Subscription ID to delete. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Example Request

```http theme={null}
DELETE /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json
```

***

## Example Response

```json theme={null}
{
  "success": true
}
```

The Subscription will be deleted from the OneSignal database.

***


# Edit player
Source: https://documentation.onesignal.com/reference/edit-device

put https://onesignal.com/api/v1/players/{player_id}

Update a player's (Subscription's) information using the Subscription ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `player_id` | string | Yes      | The OneSignal Subscription ID. |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request.    |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                |
| -------------------- | ------- | -------- | ---------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                     |
| `identifier`         | string  | No       | Push token, email, or phone number.                        |
| `language`           | string  | No       | Language code (e.g., "en").                                |
| `timezone`           | integer | No       | Time zone offset in seconds.                               |
| `game_version`       | string  | No       | App version.                                               |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                         |
| `device_os`          | string  | No       | OS version (e.g., "14.5").                                 |
| `ad_id`              | string  | No       | Advertising ID.                                            |
| `sdk`                | string  | No       | OneSignal SDK version.                                     |
| `tags`               | object  | No       | Custom key-value pairs.                                    |
| `external_user_id`   | string  | No       | Your internal user ID.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc. |
| `email_auth_hash`    | string  | No       | Required to update email identifiers securely.             |
| `sms_auth_hash`      | string  | No       | Required to update SMS identifiers securely.               |

> Only include fields you want to change. Fields left out will not be modified.

***

## Example Request

```json theme={null}
PUT /api/v1/players/player_id_string HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "external_user_id": "user123",
  "tags": {
    "level": "20",
    "subscription": "active"
  },
  "language": "fr",
  "timezone": 3600,
  "device_os": "16.0"
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Missing or invalid fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied.
* 404 Not Found – Device with player\_id not found.

***


# Edit tags with external user id
Source: https://documentation.onesignal.com/reference/edit-tags-with-external-user-id

put https://onesignal.com/api/v1/apps/{app_id}/users/{external_user_id}

Update a player's (Subscription's) information using the External ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter          | Type   | Required | Description             |
| ------------------ | ------ | -------- | ----------------------- |
| `app_id`           | string | Yes      | Your OneSignal App ID.  |
| `external_user_id` | string | Yes      | The user's External ID. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Request Body Parameters

| Field  | Type   | Required | Description                       |
| ------ | ------ | -------- | --------------------------------- |
| `tags` | object | Yes      | Key-value pairs to set or update. |

* To **delete a tag**, set its value to an empty string (`""`).
* Existing tags with the same keys will be **overwritten**.

***

## Example Request

```http theme={null}
PATCH /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json

{
  "tags": {
    "plan": "premium",
    "logged_in": "true",
    "referral": ""
  }
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Invalid request or payload.
* 401 Unauthorized – Invalid or missing keys.
* 403 Forbidden – Access denied due to insufficient permissions.
* 404 Not Found – No players found for given `external_user_id`.

***


# Email
Source: https://documentation.onesignal.com/reference/email

POST /notifications?c=email
Send a message using the email channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for email. See [Push notification](/reference/push-notification) or [SMS](/reference/sms) to send to those channels.

Ensure your [Email setup](/docs/en/email-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Export audience activity CSV
Source: https://documentation.onesignal.com/reference/export-csv-of-events

POST /notifications/{message_id}/export_events
Export a compressed CSV report of audience-level delivery and engagement data for a specific message. This includes sent, delivered, clicked, failed, and unsubscribed events across Push, Email, and SMS channels.

## Overview

Get a CSV of per-recipient audience activity events (sends, clicks, failures, etc.) for a push, email, or SMS message. This endpoint mirrors the **Export** button in the dashboard's Audience Activity section on each message report:

* [Push message reports](/docs/en/push-notification-message-reports)
* [Email message reports](/docs/en/email-message-reports)
* [SMS message reports](/docs/en/sms-message-reports)

The CSV schema varies by channel. See each channel's message reports page for column definitions.

***

## How to use this API

Get the message `id` from the [Sending messages API](/reference/create-message) or the [View messages API](/reference/view-messages).

A successful request returns `200 OK` with a `csv_file_url`:

```json 200 OK theme={null}
{
    "csv_file_url": "https://onesignal-data.onesignal.com/csv_exports/YOUR_APP_ID/events_audience-activity-YOUR_MESSAGE_ID-push-YYYY-MM-DDTHH-MM-SSTZ.csv.gz"
}
```

The generated file name follows the pattern `events_audience-activity-{message_id}-{channel}-{timestamp}.csv.gz`.

The file is generated at \~2,000 records per second. For large audiences, generation can take several minutes, and the URL may return `404` until the file is ready:

```xml 404 Not Found theme={null}
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

Poll the `csv_file_url` with GET and implement retries with exponential backoff. When the file is ready, the GET request downloads the `.csv.gz` file.

<Info>
  * The CSV download URL is valid for **3 days** after creation.
  * File names include a random UUID to prevent guessing.
</Info>

<Warning>
  Only **one concurrent export** is allowed per OneSignal account. Download the `.csv.gz` file before starting another export, or the new request fails.
</Warning>

***


# View user identity
Source: https://documentation.onesignal.com/reference/fetch-aliases

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Retrieve all aliases associated with a user using a known alias, such as an `external_id`, `onesignal_id`, or a custom alias. This API helps you map back to a user’s full identity from any one piece of identifying information.

## Overview

Use this API when you want to retrieve the complete identity object for a user, which includes all aliases tied to that user. It is ideal for cases where you know one alias and want to discover others—especially helpful for user mapping, debugging, or linking systems.

This endpoint is similar to the [View user](/reference/view-user) API but only returns the `identity` object—not subscriptions or properties.

<Tip>
  If you only know a subscription\_id, use View user identity (by subscription) instead.
</Tip>

For more context on user identity and aliasing:

* [Users](/docs/en/users)
* [Aliases](/docs/en/aliases)

***

## How to use this API

To identify the user, use:

* `alias_label` – the type of alias you’re using to find the user (e.g. `external_id`, `onesignal_id`, or a custom alias)
* `alias_id` – the actual value of that alias

Common usage patterns:

Using `external_id` (recommended):

* `alias_label`: `external_id`
* `alias_id`: your user ID (e.g., user-123)

Using `onesignal_id`:

* `alias_label`: `onesignal_id`
* `alias_id`: the OneSignal-assigned unique ID

Using a custom alias:

* Define your own alias label (e.g. `shopify_customer_id`) and its value

<Note>
  We strongly recommend setting and using the `external_id` as your primary user identifier for portability and simplicity across your systems.
</Note>

***


# View user identity (by subscription)
Source: https://documentation.onesignal.com/reference/fetch-identity-by-subscription

GET /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Retrieve all aliases linked to a user using a known `subscription_id`. This is useful when the user’s identity is unknown but you have access to one of their push, email, or SMS subscriptions.

## Overview

Use this API when you want to find the full identity (all aliases) of a user, starting from a known `subscription_id`. This is helpful for debugging, reverse lookups, or support use cases where only a subscription record is available.

<Note>
  Unlike the [View user identity](/reference/fetch-aliases) API which starts with an alias (e.g., `external_id`), this endpoint works when only a subscription ID is known.
</Note>

See [Subscriptions](/docs/en/subscriptions) for background on how subscriptions relate to users.

***

## How to use this API

To use this endpoint, you must provide:

* `subscription_id` – A UUID generated by OneSignal when a device or channel (e.g., push, email, SMS) is registered.

<Warning>
  `subscription_id` values are immutable and cannot be changed. Make sure you are using the correct value, as they are unique to each app and platform.
</Warning>

Once a valid `subscription_id` is provided, the API will return the user’s identity object, which includes all associated aliases like `external_id`, `onesignal_id`, and any custom aliases.

***


# Idempotent API requests
Source: https://documentation.onesignal.com/reference/idempotent-notification-requests

Prevent duplicate messages or custom events when retrying API requests.

## Overview

When you create messages or custom events via our REST API, network failures or timeouts can cause uncertainty about whether a request succeeded. **Idempotent requests** solve this problem by ensuring the same request is only processed once—even if it is sent multiple times.

This page explains how idempotency works in OneSignal, when to use it, and common pitfalls to avoid.

### When you should use idempotency

You should use idempotent requests any time you plan to retry API calls, especially when:

* You receive a timeout, 500-level error, or no response.
* Your infrastructure automatically retries failed requests.
* Delivering a duplicate message or custom event would be harmful.
* Missing a message or custom event would be harmful.

### The problem idempotency solves

Consider this common failure scenario:

1. You send a `notifications#create` or `custom_events#create` request.
2. OneSignal begins processing and sending the message or event.
3. A network error occurs before your client receives a response.

At this point, your system cannot know whether the request succeeded.

* If you retry and the request already succeeded, users may receive duplicates.
* If you do not retry and the request failed, users may miss important messages or events.

**Idempotency provides a safe retry mechanism.**

***

## How idempotency works

OneSignal supports idempotent operations for:

* [`notifications#create`](/reference/create-message)
* [`custom_events#create`](/reference/create-custom-events)

You provide a unique `idempotency_key` with each request.

### Request flow with idempotency

1. You send a request with an `idempotency_key`.
2. OneSignal processes the request and begins sending the message or creating the custom event.
3. A network error or timeout occurs.
4. You retry the request using the same `idempotency_key`.
5. OneSignal detects the duplicate and returns the result of the original request.
6. Only one notification or custom event is processed.

You can repeat this retry any number of times. As long as the `idempotency_key` remains the same, the operation will only be processed once.

***

## Idempotency key reference

<ParamField type="RFC 9562 UUID">
  A unique identifier used to prevent duplicate messages or custom events from repeat API calls. Keys must be unique [RFC 9562 UUID format](https://en.wikipedia.org/wiki/Universally_unique_identifier). Valid for 30 days.
</ParamField>

<Note>
  This `idempotency_key` property used to be called `external_id` but caused confusion with our [Users `external_id`](/docs/en/users) alias, so we have added this new property name to reduce confusion. Both will work in this case.
</Note>

***

## Important constraints and gotchas

<Warning> If you reuse the same `idempotency_key` for different messages or events, only the first request will be processed. </Warning>

Keep the following in mind:

* **Keys must be unique per logical operation**
  Generate a new UUID for every notification or custom event you intend to send.

* **Keys are retained for 30 days**
  After 30 days, OneSignal may delete the record. Reusing the same key after that window may result in a new message being sent.

* **Use a strong source of randomness**
  Predictable or reused UUIDs can cause unexpected deduplication.

* **Idempotency does not guarantee delivery**
  It only guarantees at-most-once processing. You should still monitor API responses and logs.

### Legacy behavior

The `idempotency_key` property was previously named `external_id`. This caused confusion with the Users `external_id` alias, so `idempotency_key` is now the recommended field name. Both names are currently supported.

### Best practices

* Always include `idempotency_key` when implementing retries.
* Store the `idempotency_key` alongside your request metadata for debugging.
* Retry only after honoring any `Retry-After` header returned by the API.
* Combine idempotency with proper timeout handling (for example, a 60-second HTTP timeout).

***


# Message history
Source: https://documentation.onesignal.com/reference/message-history

POST /notifications/{message_id}/history
View which subscriptions received a particular message

## Overview

This API enables you to retrieve all [Subscriptions](/docs/en/subscriptions) that received a specific push notification or email. You can access the notification's history for up to seven days after it was sent. Please note that notifications sent to fewer than 1,000 recipients will not record a "received" event, but they will still record "sent" events.

***

## How to Use this API

1. Submit a request to generate a report.

2. Decide delivery method

   * After receiving a successful response, **poll the destination URL** until the file becomes available. Exports typically complete within 1-3 minutes; we recommend a 10-second polling interval.
   * Alternatively, you can opt to receive an email to the address specified in the optional `email` parameter when the report is ready.

### Requirements

* A [OneSignal Professional or Enterprise Plan](https://onesignal.com/pricing).
* Enabled the "Send History via OneSignal API" option in Settings -> Integrations; notifications sent before this setting is enabled can't be retrieved.
* Requests must be made within seven days of sending the notification.

### Polling

Use the `csv_file_url` property in the response to test if the report is complete. If you receive a '403' error response, retry fetching the file after a short period; it only means we're still generating the report.

### Sample Report

The generated report is a simple CSV file that can be imported into any system for further processing.

```csv report.csv theme={null}
player_id,onesignal_id,external_id,target_channel,timestamp
"2c4fac95-7dfb-4113-9347-aba3a92ff557","ccddf35a-1233-4423-8a57-ac8c4b38eb81","a07aec27-2586-4b92-a24f-62660a1517fa","push","1628189160"
"68f5cf73-b20a-4de9-b6ee-79a863b8e7d8","d2f9f2f8-94af-4942-8183-115cef1213d5","4b66359f-3d94-4a73-806d-8ef5f0430b3d","push","1628187816"

```

### Limitations

* Querying for `opens` events are not supported.
* The `timestamp` column is included only for `clicked` events.

***


# Push notification
Source: https://documentation.onesignal.com/reference/push-notification

POST /notifications?c=push
Send a message using the push notification channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for push. See [Email](/reference/email) or [SMS](/reference/sms) to send to those channels.

Ensure your application is properly configured by following the [Mobile SDK Setup](/docs/en/mobile-sdk-setup) and/or [Web SDK Setup](/docs/en/web-sdk-setup) guides. You should see subscribed push [Subscriptions](/docs/en/subscriptions) in your OneSignal dashboard to send them messages.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Rate limits and error handling
Source: https://documentation.onesignal.com/reference/rate-limits

Understand OneSignal API and application rate limits, common errors, retry behavior, and how to safely recover from failures without sending duplicate messages or disabling your app.

OneSignal uses rate limits and error responses as safety mechanisms to protect your app from accidental overloads, duplicate sends, and retry storms.

There are three categories to understand:

* **API rate limits** return HTTP `429` errors when request volume is too high.
* **Network timeouts or temporary server failures** return `5xx` errors or no response at all.
* **Application message limits** may temporarily disable your app if too many messages are sent in a short period.

<Info>
  Most apps never hit these limits during normal usage. When they do occur, they are usually caused by retries, loops, or unexpected audience expansion.
</Info>

<Check>
  **Quick implementation checklist**

  * Expect `429`, `5xx`, and timeouts. They are normal at scale.
  * Never retry message sends without an `idempotency_key`.
  * For non-urgent retries, wait **100 seconds** before retrying.
  * API rate limits (`429`) never disable your app.
  * Only message volume limits can disable your app.
  * `POST /notifications` (create) and `DELETE /notifications` (cancel) count toward the same rate limit.
  * The [Create custom events](/reference/create-custom-events) endpoint has its own rate limit, separate from the notification endpoints.
</Check>

***

## API rate limits

API rate limits apply **per app and per endpoint**. They are evaluated when a request is received, not when a response is returned.

These limits are designed to throttle traffic, not block your app.

| Endpoint                                                                                  | Rate limit                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create message](/reference/create-message) / [Cancel message](/reference/cancel-message) | **Free plans:** 150 requests/sec/app<br />**Paid plans:** 6,000 requests/sec/app<br /><br />The `POST /notifications` and `DELETE /notifications` endpoints share the same limit. Requests count toward it regardless of method. For example, 3,000 creates + 3,000 cancels = 6,000 requests/sec on a paid plan.<br /><br />Each request can target many users or segments. |
| [Create custom events](/reference/create-custom-events)                                   | Rate-limited independently from Create Message.<br />**Request size limits:** 2,024 bytes per event · 1 MB per request body                                                                                                                                                                                                                                                 |
| Create, update, or delete users or subscriptions                                          | 1,000 requests/sec/app<br />1 request/sec per user or subscription<br />Up to 100 property updates per request                                                                                                                                                                                                                                                              |
| View endpoints (messages, templates, users)                                               | 1 request/sec/app<br />Up to 10 look-back requests/sec                                                                                                                                                                                                                                                                                                                      |
| Message History and CSV exports                                                           | Keep parallel exports under 100 GB per file                                                                                                                                                                                                                                                                                                                                 |

<Note>
  High-volume messaging should use fewer message creation requests with larger audiences instead of increasing request frequency.
</Note>

**Handling API rate limit errors (`429`):**

When you exceed an API rate limit, OneSignal returns an HTTP `429` response:

```json theme={null}
{
  "errors": ["API rate limit exceeded."]
}
```

The response includes a `Retry-After` header indicating how many seconds to wait before retrying.

**What to do when you receive a `429` error:**

1. Stop sending requests immediately.
2. Wait for the full duration specified in the `Retry-After` header.
3. Retry using exponential backoff.
4. Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for retries that send messages.

<Warning>
  Retrying before the `Retry-After` delay or retrying in tight loops can extend throttling and increase failure rates.
</Warning>

***

## Error handling and retry strategies

Retries are safe only when implemented correctly. Some failed requests may still be processing on our servers.

* Retriable errors generally include network timeouts, no responses, 429, and 5xx errors.
* Non-retryable errors include 400, 401, or 403 errors which indicate invalid input, authentication problems, or missing permissions. These are not temporary failures.

**Simple retry strategy:**

* Wait **100 seconds** before retrying.
  * This aligns with the maximum API response timeout.
  * If no response or network error occurs, the request may still be processing during this window.
* Retry **up to 3 total attempts** (original + 2 retries).
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

**Time-sensitive (advanced) retry strategy:**

* Retry using exponential backoff with jitter (for example: 2s, 4s, 8s… up to 60s).
* Cap retries to **10 total attempts** and stop after **10–15 minutes**.
* For `429` responses, treat `Retry-After` as a minimum delay: wait `max(Retry-After, backoff)`.
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

<Warning>
  Retrying message or custom event API requests without idempotency can result in duplicate messages or custom events.
</Warning>

<Accordion title="Example retry logic">
  ```text theme={null}
  attempt = 1
  max_attempts = 3

  send request with idempotency_key

  if response is success:
    stop

  if response is 429:
    wait Retry-After seconds
  elif response is 5xx or timeout:
    wait 100 seconds

  if attempt < max_attempts:
    retry with same idempotency_key
  else:
    fail safely
  ```
</Accordion>

### Retry decision guide

| Error type              | Retry? | When                 | Idempotency required |
| ----------------------- | ------ | -------------------- | -------------------- |
| `429 Too Many Requests` | Yes    | After `Retry-After`  | Yes                  |
| `5xx Server Error`      | Yes    | Backoff or 100s      | Yes                  |
| Timeout / no response   | Yes    | Immediate or delayed | Yes                  |
| `400 Bad Request`       | No     | Fix request          | No                   |
| `401 / 403`             | No     | Fix auth/permissions | No                   |

<Warning>
  Common implementation mistakes:

  * Retrying with a new idempotency key on each attempt.
  * Retrying indefinitely without a retry cap.
  * Retrying `400` or `401` errors without fixing the request.
  * Sending one request per user instead of batching audiences.
</Warning>

***

## Application message limits (app disablement)

Application message limits protect your users from receiving too many notifications in a short period of time.

**How the limit works:**

In any rolling 15-minute window, you may send up to **10 × your total number of subscribed [Subscriptions](/docs/en/subscriptions)**.

This limit is based on the total number of messages delivered, not the number of API requests.

* Sending 1 notification to 1,000 Subscriptions = 1,000 messages
* Sending 10 notifications to 1,000 Subscriptions each = 10,000 messages

The 15-minute window is rolling, not fixed.

* Messages are counted for 15 minutes after they are sent
* As time passes, older messages automatically stop counting
* You only exceed the limit if more than 10× your subscribed Subscriptions receive messages within the same 15-minute span

Example limits:

* App with 1,000 subscribed Subscriptions → up to 10,000 messages in any 15 minutes
* App with 10,000 subscribed Subscriptions → up to 100,000 messages in any 15 minutes

**Example scenarios:** App with 1,000 subscribed Subscriptions (limit: 10,000 messages per 15 minutes)

| Scenario                                                                              | Messages counted in any 15-minute period |    App disabled?    |
| ------------------------------------------------------------------------------------- | ---------------------------------------: | :-----------------: |
| At **12:00**, send 1 notification to 1,000 users                                      |                                    1,000 |          No         |
| At **12:00**, send 10 notifications to 1,000 users                                    |                                   10,000 |   Yes (hits limit)  |
| Between **12:00–12:14**, send 10,000 notifications to 1 user                          |                                   10,000 |   Yes (hits limit)  |
| Send **9,000 messages at 12:00**, then **9,000 more at 12:16**                        |                                    9,000 |          No         |
| Send **9,000 messages spread between 12:00–12:14**, then send **9,000 more at 12:15** |                                 \~18,000 | Yes (exceeds limit) |

<Note> This limit is evaluated continuously over a rolling 15-minute window, not in fixed time blocks. If any 15-minute span exceeds your limit, the app is disabled. </Note>

**What happens if the limit is exceeded:**

If your app sends more messages than allowed within a 15-minute window:

* Your app is temporarily disabled
* All app administrators receive an email notification
* A re-enable banner appears in the OneSignal Dashboard

<Warning> Only application message limits can disable your app. API rate limits (`429` errors) never disable apps. </Warning>

**What to do if your app is disabled:**

If your app is disabled, follow these steps in order:

1. Pause message sending from your backend, jobs, or automations.
2. Identify the cause, such as infinite loops, retry storms, or unexpected segment growth.
3. Log in to the OneSignal Dashboard.
4. Click **Re-enable** in the red banner at the top of the app.
5. If you need help re-enabling your app, contact `support@onesignal.com`.

***

## FAQ

### Do API rate limits disable my app?

No. API rate limits (`429` errors) only throttle your requests temporarily. Only [application message limits](#application-message-limits-app-disablement) — which track the total volume of messages delivered — can disable your app.

### What is an idempotency key and when do I need one?

An idempotency key is a unique identifier you include with a request so that retrying the same request does not create a duplicate message or event. You need one whenever you retry a `POST /notifications` or custom event request. Reuse the same key for every retry attempt. See [Idempotent API requests](/reference/idempotent-notification-requests).

### Can I increase my API rate limit?

Paid plans have higher rate limits (6,000 requests/sec vs. 150 for free plans). If you need limits beyond the paid tier, contact `support@onesignal.com` with your use case and expected volume.

### Why was my app disabled even though I didn't hit the API rate limit?

API rate limits and application message limits are separate. Your app can be disabled if the total number of messages delivered in any 15-minute window exceeds 10× your subscription count — even if every individual API request succeeded. Common causes include retry storms, runaway automations, or targeting a larger audience than intended.

***

## Related pages

<Columns>
  <Card title="Idempotent API requests" icon="rotate" href="/reference/idempotent-notification-requests">
    Prevent duplicate messages by reusing idempotency keys on retries.
  </Card>

  <Card title="Create message API" icon="paper-plane" href="/reference/create-message">
    API reference for sending push, email, SMS, and in-app messages.
  </Card>

  <Card title="Create custom event API" icon="bolt" href="/reference/create-custom-events">
    API reference for sending custom events that trigger Journeys.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="/docs/en/subscriptions">
    Understand how subscriptions are counted toward message limits.
  </Card>
</Columns>


# REST API overview
Source: https://documentation.onesignal.com/reference/rest-api-overview

Programmatic access to OneSignal messaging, user management, segments, and data exports over HTTPS with rate limiting and retry support.

The OneSignal REST API follows the [REST architecture](https://en.wikipedia.org/wiki/Representational_state_transfer) and provides programmatic access to core messaging and user features. Use the API to send push notifications, emails, and SMS, manage Users, Subscriptions, Segments, export data, and configure apps.

## Which API to use

| Goal                          | API                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| Send a push, email, or SMS    | [Create Message](/reference/create-message)                                                              |
| Add or update user data       | [Create User](/reference/create-user) / [Update User](/reference/update-user)                            |
| Target a group of users       | [Create Segments](/reference/create-segments) or use [Filters](/reference/create-message#filters) inline |
| Export analytics or user data | [CSV Export](/reference/csv-export) / [CSV of Events](/reference/export-csv-of-events)                   |
| Manage app configuration      | [Create App](/reference/create-an-app) / [Update App](/reference/update-an-app)                          |

***

## Requirements

**General**

* **HTTPS required**: All API requests must use HTTPS with **TLS 1.2 or higher** on port `443`.
* **Network access**: Firewalls or proxies must allow **outbound traffic** to `https://api.onesignal.com` on port `443`.
* **DNS TTL**: Clients must respect OneSignal’s DNS **TTL of 300 seconds** to avoid stale IP resolution.

**Incoming Traffic to OneSignal (API & SDK Requests)**

All incoming API traffic—whether from your backend, the OneSignal SDKs, or the dashboard—passes through **Cloudflare**, which serves as the global edge network.

* You may see Cloudflare IP addresses in logs.
* Cloudflare IPs may change over time.
* If you maintain a strict firewall, use Cloudflare’s official [IP ranges](https://www.cloudflare.com/ips/)

<Warning>
  Avoid allowlisting specific Cloudflare IPs, as they may change without notice.
</Warning>

**Outgoing Traffic from OneSignal (Webhooks & Event Streams)**

For features where OneSignal sends HTTP requests to your servers (such as webhooks or event streams), traffic originates from OneSignal infrastructure running on Google Cloud Platform (GCP) in the `europe-west4` region (Groningen, Netherlands).

* Allow inbound traffic from `https://api.onesignal.com`, **or**
* Use GCP’s maintained IP range list and filter by `europe-west4` region: [GCP IP ranges](https://www.gstatic.com/ipranges/cloud.json)

<Note>
  OneSignal supports [IP allowlisting](/docs/en/keys-and-ids) with REST API keys.
</Note>

***

### Platform-specific network requirements

#### FCM (Google Android and Chrome push)

* Required ports: `5228`, `443`, `5229`, and `5230`
* No IP allowlisting needed
* More info: [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

#### APNs (Apple iOS, iPadOS, Safari push)

* Required ports: `5223`, `443`, and `2197`
* Recommended servers:
  * Sandbox: `api.sandbox.push.apple.com:443`
  * Production: `api.push.apple.com:443`
  * IP range: `17.0.0.0/8`
* More info:
  * [Apple Support](https://support.apple.com/en-us/102266)
  * [APNs Developer Docs](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns?language=objc)

***

## Core API capabilities

### Send messages

See the [Create Message guide](/reference/create-message) to get started. Programmatically send:

<Columns>
  <Card title="Push Notifications" icon="bell" href="/reference/push-notification">
    Send push notifications to apps and websites.
  </Card>

  <Card title="Email" icon="envelope" href="/reference/email">
    Send transactional and promotional emails.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/reference/sms">
    Send SMS or MMS messages globally.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="/reference/start-live-activity">
    Send Live Activity updates to iOS devices.
  </Card>
</Columns>

<Note>
  For platform-specific features like personalization, throttling, and frequency capping, see the [Push](/docs/en/push), [Email](/docs/en/email-messaging), [SMS](/docs/en/sms-messaging), and [Live Activities](/docs/en/live-activities) overview guides.
</Note>

***

### Manage templates

[Templates](/docs/en/templates) are reusable push, email, and SMS messages that simplify development and improve consistency.

<Columns>
  <Card title="Create template" icon="plus" href="/reference/create-template">
    Save a reusable message layout for push, email, or SMS.
  </Card>

  <Card title="Update template" icon="pen-to-square" href="/reference/update-template">
    Modify an existing template's content or settings.
  </Card>

  <Card title="View templates" icon="eye" href="/reference/view-templates">
    List all templates in your app with their metadata.
  </Card>

  <Card title="Delete template" icon="trash" href="/reference/delete-template">
    Permanently remove a template from your app.
  </Card>
</Columns>

***

### Track custom events

[Custom events](/docs/en/custom-events) record user actions like purchases, content views, or milestones. Use them to enter users into [Journeys](/docs/en/journeys-settings) or trigger [Wait Until](/docs/en/journeys-actions) nodes.

<Card title="Create custom events" icon="bolt" href="/reference/create-custom-events">
  Record user events to trigger Journeys and track behavior.
</Card>

***

### Manage Users and Subscriptions

See the [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) guides for more details.

<Columns>
  <Card title="Create user" icon="user-plus" href="/reference/create-user">
    Create a user with optional aliases and subscriptions.
  </Card>

  <Card title="View user" icon="eye" href="/reference/view-user">
    View user details.
  </Card>

  <Card title="Update user" icon="user-pen" href="/reference/update-user">
    Modify a User's properties, tags, or aliases.
  </Card>

  <Card title="Delete user" icon="user-minus" href="/reference/delete-user">
    Permanently remove a User and all associated data.
  </Card>
</Columns>

***

### Manage Segments

[Segments](/docs/en/segmentation) group Users by filters for targeted messaging.

<Columns>
  <Card title="Create Segments" icon="plus" href="/reference/create-segments">
    Define a new Segment with filters to group Users.
  </Card>

  <Card title="Update Segment" icon="pen-to-square" href="/reference/update-segment">
    Modify a Segment's name or replace its filters.
  </Card>

  <Card title="Delete Segments" icon="trash" href="/reference/delete-segments">
    Permanently remove a Segment from your app.
  </Card>
</Columns>

<Note>
  You can also target users dynamically using [filters](/reference/create-message#filters) without creating persistent segments.
</Note>

***

### Export data

For analytics breakdowns, see [Analytics overview](/docs/en/analytics-overview).

<Columns>
  <Card title="Export CSV of subscriptions" icon="file-export" href="/reference/csv-export">
    Export all user and subscription data.
  </Card>

  <Card title="Export CSV of events" icon="file-export" href="/reference/export-csv-of-events">
    Export events like sent, received, and clicked.
  </Card>

  <Card title="View messages" icon="eye" href="/reference/view-messages">
    View message details and analytics.
  </Card>

  <Card title="View message" icon="magnifying-glass" href="/reference/view-message">
    View individual message details.
  </Card>
</Columns>

***

### Manage Apps & API Keys

OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See [Apps, orgs, & accounts](/docs/en/apps-organizations).

<Columns>
  <Card title="Create an app" icon="plus" href="/reference/create-an-app">
    Register a new app with platform credentials.
  </Card>

  <Card title="Update an app" icon="pen-to-square" href="/reference/update-an-app">
    Modify app settings or platform credentials.
  </Card>

  <Card title="View single app" icon="eye" href="/reference/view-an-app">
    Retrieve configuration and details for one app.
  </Card>

  <Card title="View multiple apps" icon="list" href="/reference/view-apps">
    List all apps in your account.
  </Card>
</Columns>

#### API key management

See [Keys & IDs](/docs/en/keys-and-ids) for more details.

<Columns>
  <Card title="Create API key" icon="key" href="/reference/create-api-key">
    Generate a new API key with specific permissions.
  </Card>

  <Card title="View API keys" icon="eye" href="/reference/view-api-keys">
    List all API keys and their permissions for your app.
  </Card>

  <Card title="Delete API key" icon="trash" href="/reference/delete-api-key">
    Revoke an API key permanently.
  </Card>

  <Card title="Update API key" icon="pen-to-square" href="/reference/update-api-key">
    Modify an API key's permissions or IP allowlist.
  </Card>
</Columns>

***

## Error handling and retries

The OneSignal API may return temporary errors such as `429` (rate limited), `5xx` (server errors), or timeouts. When this happens, the request may still be processing. If you retry failed requests, always use an `idempotency_key` and follow the recommended retry delays to avoid duplicate messages.

<Card title="Rate limits and error handling" icon="triangle-exclamation" href="/reference/rate-limits">
  Retry strategies, error definitions, and recovery steps.
</Card>

***

## FAQ

### What is the timeout for API responses?

* Default: **100 seconds**
* If you're unsure whether a request completed, use an [`idempotency_key`](/reference/idempotent-notification-requests) to safely retry.
* See [Rate limits and error handling](/reference/rate-limits) for more details.

### Do I need to download or renew certificates to call the OneSignal API?

No. The OneSignal API uses HTTPS with a publicly trusted TLS certificate managed by Cloudflare. These edge certificates renew automatically and are trusted by all major browsers, operating systems, and runtimes.

If your network pins a specific leaf certificate, it will expire and rotate every few months — this is normal Cloudflare behavior. Trust the root and intermediate CAs in the chain instead of the leaf certificate to avoid disruption.

<Accordion title="Certificate pinning details and workarounds">
  * **Best practice**: Trust the root and intermediate CAs in the chain instead of the rotating leaf certificate.
  * **If you must pin a certificate**: Pin the public key (SPKI) of the CA or use a backup key set, not the exact leaf certificate.
  * **Fetching the current certificate**: If your process requires the active leaf certificate, retrieve it directly:

  ```bash theme={null}
  SERVERNAME=api.onesignal.com
  echo -n | openssl s_client -connect $SERVERNAME:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/${SERVERNAME}_current.pem
  ```

  To retrieve the full chain, add the `-showcerts` flag to `openssl s_client`.

  See [Cloudflare SSL/TLS documentation](https://developers.cloudflare.com/ssl/get-started/) and [Cloudflare Edge Certificates documentation](https://developers.cloudflare.com/ssl/edge-certificates/) for more details.
</Accordion>

### Why am I getting a 403 Forbidden error?

A `403` response means the API key is valid but does not have permission for the requested operation. Check the following:

* **Wrong key type**: App API keys work for app-level endpoints (sending messages, managing Users). Organization API keys are required for org-level endpoints (creating apps, managing API keys). See [Keys & IDs](/docs/en/keys-and-ids) for details.
* **IP allowlisting**: If IP allowlisting is enabled on your API key, requests from IPs not on the list are denied. Verify your server's IP is included.
* **Revoked or rotated key**: If the key was recently rotated, the old key is no longer valid. Update your integration with the new key.

### Why am I getting "UnknownHostException - Unable to resolve host api.onesignal.com"?

This error means your environment cannot resolve the DNS for `api.onesignal.com`. Common causes:

* **Firewall or proxy blocking DNS**: Ensure your network allows outbound DNS queries and traffic to `api.onesignal.com` on port `443`.
* **No internet connectivity**: Verify the device or server has an active network connection.
* **DNS server misconfiguration**: Try a public DNS resolver like `8.8.8.8` (Google) or `1.1.1.1` (Cloudflare) to rule out local DNS issues.
* **Stale DNS cache**: Flush your local DNS cache and ensure your client respects the TTL of 300 seconds.


# Rotate API key
Source: https://documentation.onesignal.com/reference/rotate-api-key

POST /apps/{app_id}/auth/tokens/{token_id}/rotate
Rotate an existing App API Key (Rich Authentication Token) for a OneSignal app. Useful when a token is compromised or needs replacement without creating a new key from scratch.

## Overview

Use this API to rotate a **Rich Authentication Token** (App API Key) for a specific OneSignal app. Rotating a key revokes the current token and generates a new one under the same configuration—ideal when a token is lost or compromised but you don’t want to recreate and reconfigure it from scratch.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can rotate an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# SMS
Source: https://documentation.onesignal.com/reference/sms

POST /notifications?c=sms
Send a message using the SMS channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for SMS and MMS. See [Push notification](/reference/push-notification) or [Email](/reference/email) to send to those channels.

Ensure your [SMS setup](/docs/en/sms-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***

## Trackable links

Add trackable links to your SMS `contents` using [liquid syntax](/docs/en/using-liquid-syntax) in the format `{{'your_url' | track_link}}`.

Example:

```json JSON theme={null}
{
  "contents": {
    "en": "Hi, here's my link: {{'https://example.com' | track_link}} "
  }
}
```

In this example, the liquid syntax block will be replaced with a trackable short link and display in the message as: `1sgnl.co/XXXX`.

<Note>
  See [SMS trackable links](/docs/en/links#sms) for more details.
</Note>

***


# Start Live Activity
Source: https://documentation.onesignal.com/reference/start-live-activity

POST /apps/{app_id}/activities/activity/{activity_type}
Remotely start a Live Activity on iOS devices via OneSignal's REST API. Define the activity type, target users, and send dynamic, updatable content directly to a Live Activity interface.

## Overview

Remotely start an iOS Live Activity using OneSignal’s REST API. Live Activities provide real-time updates directly on the lock screen and Dynamic Island (on supported devices), enhancing user engagement with ongoing events like sports games, deliveries, or countdowns.

***

## How to use this API

1. Define a Live Activity in your app. See [Live Activities developer setup](/docs/en/live-activities-developer-setup) to get started.
2. Use the `activity_type` parameter to specify the type of the Live Activity UI to use.
3. Select your target audience to receive the Live Activity. Target all or individual users.
4. Generate a unique `activity_id` to track and manage your Live Activity.
5. Use the `event_attributes` parameter to initialize the Live Activity with static data.
6. Use the `event_updates` parameter to update the Live Activity with dynamic content.

### Select your target audience

Before sending a message, you need to determine who should receive it. OneSignal offers three targeting options:

1. **Aliases & Subscription IDs**: Send messages to specific users using unique identifiers such as External ID (recommended), OneSignal ID, custom alias, or subscription ID.
2. **Segments**: Target predefined user groups based on attributes and behavior.
3. **Filters**: Create custom targeting rules using user properties, such as tags, location, or activity.

<Note>
  You can only use one targeting method per message. For example, you cannot combine alias-based targeting with filters in the same request.

  See [Select your target audience](/reference/create-message#select-your-target-audience) for more information.
</Note>

### Set a unique `activity_id`

* Set a unique `activity_id` to track and manage the Live Activity. This value is crucial for maintaining a consistent reference to the Live Activity across different devices and sessions. Consider using a UUID, CUID, or NanoID for this parameter.
* Ensure that the `activity_id` is unique and consistently used for each Live Activity to avoid conflicts and ensure accurate tracking.

  ```json Example theme={null}
  {
    "activity_id": "217aae2b-42ee-4097-bc3f-b7a6e9d15b9b",
    ...
  }
  ```

<Info>
  See [Live Activities developer setup](/docs/en/live-activities-developer-setup) guide for more information.
</Info>

### Set `event_attributes` to initialize the Live Activity

Set default/static data to display in the Live Activity upon start.

```json Example theme={null}
{
  "event_attributes": {
  	"awayTeam": "Away Team Name",
    "homeTeam": "Home Team Name"
  }
}
```

### Set `event_updates` for dynamic content

The content used to update a running Live Activity. The object must conform to the `ContentState` interface defined within your app's Live Activity. See [Live Activities developer setup](/docs/en/live-activities-developer-setup).

Ensure that the `event_updates` object matches the [`ContentState`](https://developer.apple.com/documentation/activitykit/activityattributes/contentstate#) interface exactly as defined in your Live Activity implementation. Inconsistencies can cause Live Activities to fail to display.

```json Example theme={null}
{
  "event_updates": {
    "quarter": 1,
    "homeScore": 70,
    "awayScore": 78,
    "inTimeout": false
  }
}
```

***


# Transfer Subscription
Source: https://documentation.onesignal.com/reference/transfer-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/owner
Transfer a Subscription to a different user within the same OneSignal app. Useful for associating existing Subscriptions like push, email, or SMS with a new or updated user identity.

## Overview

Use this API to transfer a Subscription from one user to another within the same OneSignal app.

It is highly recommended to use our web and mobile SDKs to set and update the External ID with the `login` method instead of this API. Your app or website may continue to be setting the wrong External ID. Make sure to only use this API if you are setting the same External ID within your app or website.

This is typically used when:

* You want to reassign an existing push, email, or SMS Subscription to a new or updated user.
* You have changed how you're identifying users (e.g., migrating from anonymous to known users).

<Note>
  - Subscriptions **cannot be transferred across different OneSignal apps**.
  - For email and SMS Subscriptions, you can instead create new ones using [Create User](/reference/create-user).
  - For push Subscriptions, platform limitations may apply—see [Subscriptions](/docs/en/subscriptions#importing-push-subscriptions) for details.
</Note>

***

## How to Use This API

### Required Path Parameter: `subscription_id`

You must know the `subscription_id` of the subscription to be transferred. This is a unique UUID assigned by OneSignal.

### Required Body Parameter: `identity` (object)

This specifies the user the subscription should be moved to. Only **one alias** should be used per request. You can identify the target user using one of:

* `external_id` (recommended)
* `onesignal_id`
* A [custom alias](/docs/en/aliases)

***


# Unsubscribe email with token
Source: https://documentation.onesignal.com/reference/unsubscribe-with-token

POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
Unsubscribe an email address from future messages by calling this API from your custom unsubscribe page. Automatically disables the associated email subscription using a token-based approach.

## Overview

Use this API to unsubscribe an email address directly from your custom unsubscribe landing page. It is ideal when building branded opt-out experiences and enables you to track which email caused the unsubscribe.

When invoked, this endpoint:

* Sets the email Subscription's `enabled` property to `false`
* Prevents further messages from being sent to the email address unless explicitly overridden (see [Overriding unsubscribes](/reference/email#body-include-unsubscribed))
* Email Subscriptions can be re-subscribed using the [Update Subscription](/reference/update-subscription) API

<Tip>
  For instructions on setting up a custom unsubscribe page, see [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page).
</Tip>

***

## How to Use This API

### Step 1: Set Up Your Custom Unsubscribe Page

Follow the guide to [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page). You'll add a custom unsubscribe URL to your email templates using Liquid syntax.

Example URL in your email template:

```liquid theme={null}
https://yourdomain.com/unsubscribe?app_id={{ app_id }}&notification_id={{ notification_id }}&token={{ token }}
```

### Step 2: Extract the Parameters

When a user clicks the unsubscribe link, your custom unsubscribe page should extract the following from the URL:

* `app_id`: OneSignal app ID
* `notification_id`: The ID of the specific email message sent
* `token`: The email token, a secure reference to the subscription

### Step 3: Call the API

When the user confirms they want to unsubscribe (e.g., clicks a button on your unsubscribe page), make a POST request to this endpoint:

```
POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
```

Example Request (JavaScript):

```js theme={null}
fetch("https://api.onesignal.com/apps/your-app-id/notifications/your-notification-id/unsubscribe?token=abc123xyz", {
  method: "POST"
});
```

<Info>
  No request body or authentication is required. The token acts as a secure identifier.
</Info>

<Note>
  * This API only works for email subscriptions.
  * It should only be used from a server or frontend context that you control (e.g., your custom unsubscribe page).
  * Once unsubscribed, the email address will not receive future emails from your app unless resubscribed.
</Note>

***


# Update an app
Source: https://documentation.onesignal.com/reference/update-an-app

PUT /apps/{app_id}
Use to update the name or push platform configuration of an existing app. This guide explains required parameters and platform-specific update rules

## Overview

Use this API to programmatically update an existing OneSignal app. This is useful when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

***

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Warning>
  If you change your FCM Service Account JSON file to a different Firebase project, your Android Subscriptions tied to the current project will become invalid. They will not be able to receive push notifications until they open your app again with this new FCM Service Account JSON file.
</Warning>

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need help Base64 encoding your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns). **You will likely never need to update these parameters if set correctly during app creation**:

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates). **These must be updated every year which is why we recommend using p8 authentication**:

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Update API key
Source: https://documentation.onesignal.com/reference/update-api-key

PATCH /apps/{app_id}/auth/tokens/{token_id}
Update a Rich Authentication Token (App API Key) for a OneSignal app. Modify the token's name or IP allowlist settings using your Organization API Key.

## Overview

Use this API to update the properties of a specific **Rich Authentication Token** (App API Key) for a OneSignal app. You can change the name, IP allowlist mode, or the list of allowed IPs. This is helpful for adjusting access rules without needing to recreate the key.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Update Live Activity
Source: https://documentation.onesignal.com/reference/update-live-activity-api

POST /apps/{app_id}/live_activities/{activity_id}/notifications
Update or terminate running iOS Live Activities using OneSignal’s Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

## Overview

Update or terminate running iOS Live Activities using our REST API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

Before using this API, ensure your app is properly configured by following the [Live Activities developer setup](/docs/en/live-activities-developer-setup).

## How to Use this API

1. Select the Live Activity to update by specifying its `activity_id` in the URL. This is set when using the:

* [Start Live Activity API](/reference/start-live-activity)
* [Triggering it in-app](/docs/en/live-activities-developer-setup).
* [`LiveActivities.enter` SDK method](/docs/en/mobile-sdk-reference#enter)

2. Update the state of the Live Activity by setting the `event_updates` parameter to a JSON object that matches the structure of the `ActivityAttributes.ContentState` struct defined in your Live Activity widget extension.

3. When ready to terminate the Live Activity:

* Set the `event` parameter to `end`
* Include a `dismissal_date` if you want the Live Activity to be dismissed in less than 4 hours.
* Set the `dismissal_date` to a time in the past to dismiss the Live Activity immediately. User must have clicked "Allow" for the Live Activity to be removed programmatically.

<Warning>
  Once a Live Activity `activity_id` is ended, you cannot update it. This includes changing the `dismissal_date` or `event` parameter.

  If the Live Activity is not being dismissed immediately, it is either because:

  * The `activity_id` has already been ended.
  * The user has not clicked "Allow" for the Live Activity to be removed programmatically.
</Warning>

***


# Update segment
Source: https://documentation.onesignal.com/reference/update-segment

PATCH /apps/{app_id}/segments/{segment_id}
Update an existing segment's name and/or filters. The name parameter is always required. When filters are provided, all existing filters are replaced with the new ones.

## Overview

Update an existing segment's name and/or filters. This API allows you to modify [Segments](/docs/en/segmentation) programmatically without having to delete and recreate them.

<Note>
  The `name` parameter is always required, even if you're not changing it. When filters are provided, all existing filters are **replaced** with the new ones. Omit the `filters` parameter to keep existing filters intact. The `filters` array cannot be empty—if provided, it must contain at least one filter.
</Note>

***

## How to use this API

### Update segment name only

To update just the segment name without changing filters:

```json theme={null}
{
  "name": "New Segment Name"
}
```

### Update segment description

Update the optional `description` (max 255 characters). Pass an empty string to clear the existing description; omit the field to leave it unchanged.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION"
}
```

### Update segment filters

To update the segment filters (this replaces all existing filters), provide the `name` (required) and `filters`:

```json theme={null}
{
  "name": "Updated Segment",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "5"},
    {"operator": "AND"},
    {"field": "tag", "key": "subscription", "relation": "=", "value": "premium"}
  ]
}
```

### Filter syntax

The filter syntax is identical to the [Create segment](/reference/create-segments) API. Available filters include:

* `tag` - Filter by Tags
* `last_session` - Filter by last active time
* `first_session` - Filter by first session time
* `session_count` - Filter by number of sessions
* `session_time` - Filter by total usage duration
* `language` - Filter by user language
* `app_version` - Filter by app version
* `location` - Filter by GPS coordinates
* `country` - Filter by country

Use `AND` and `OR` operators to combine filters:

```json theme={null}
{
  "name": "Engaged Premium Users",
  "filters": [
    {"field": "tag", "key": "plan", "relation": "=", "value": "premium"},
    {"operator": "AND"},
    {"field": "session_count", "relation": ">", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "vip", "relation": "=", "value": "true"}
  ]
}
```

***

## Response

### Success response

```json theme={null}
{
  "success": true,
  "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19"
}
```

### Error responses

| Status Code | Description                                                                              |
| ----------- | ---------------------------------------------------------------------------------------- |
| 400         | Bad request - Invalid filters, duplicate segment name, or segment used by active Journey |
| 403         | Forbidden - API not available for your plan                                              |
| 404         | Not found - Segment does not exist                                                       |
| 429         | Rate limit exceeded                                                                      |

***


# Update Subscription by ID
Source: https://documentation.onesignal.com/reference/update-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}
Update properties on an existing OneSignal subscription using its subscription_id. Commonly used to enable or disable a subscription when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties by `subscription_id`.

This endpoint is primarily used by the OneSignal SDK to manage subscription state.

Most external use cases are better served by the [Update Subscription by token](/reference/update-subscription-by-token) API, which can use the Email Address or Phone Number as the `token` or the [Update User](/reference/update-user) API, which allows for updating user-level data.

<Note>
  For **email opt-outs**, it's recommended to use the [Unsubscribe Email (with token)](/reference/unsubscribe-with-token) API instead. This avoids the need to store or manage the `subscription_id`.
</Note>

***

## How to use this API

**Required:** `subscription_id`

To update a subscription, you **must know the `subscription_id`**. This is a UUID generated by OneSignal and is immutable.

* You can retrieve a subscription ID by querying the [User object](/docs/en/users).
* See the [Subscriptions](/docs/en/subscriptions) guide for an explanation of how subscription IDs are generated and used.

<Note>
  You **cannot** update the `type` of a Subscription. If the `type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the Subscription with the correct type.
</Note>

***


# Update Subscription by token
Source: https://documentation.onesignal.com/reference/update-subscription-by-token

PATCH /apps/{app_id}/subscriptions_by_token/{token_type}/{token}
Update properties on an existing Subscription using its token. Commonly used to enable or disable subscription status when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties.

This API can be useful if:

* You only know the `token` and `token_type` and want to update metadata or status flags directly.
* You are managing Subscription status outside of the OneSignal SDK. Like with a [custom preference page or unsubscribe page](/docs/en/create-custom-unsubscribe-page).

***

## How to use this API

To update a Subscription, you must know the `token_type` and the `token`.

The `token_type` is the [Subscription's type](/docs/en/server-sdk-reference#subscription-types) (e.g., `Email`, `SMS`, `iOSPush`, `AndroidPush`, etc.).

The `token` is the push token, email address, or phone number associated with the Subscription.

Ensure the `token` is valid and correctly formatted for the chosen `token_type`.

* **Email format:** Should be a valid email address that you confirmed can receive emails.
* **SMS format:** Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164).
* **iOSPush APNS token format:** 64 characters, hexadecimal characters only (0-9,a-f).
* **AndroidPush FCM token format:** Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.

<Warning>
  You **cannot** update the `token_type` and `token` of a Subscription with this API. If the `token_type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the subscription with the correct type.

  If multiple Subscriptions are found for the `token` and `token_type`, an `Http 400` error is returned with a list of subscription IDs that match the criteria.
</Warning>

***


# Update template
Source: https://documentation.onesignal.com/reference/update-template

PATCH /templates/{template_id}?app_id={app_id}
Update existing OneSignal message templates for push, email, or SMS. Changes apply immediately across dashboard and API usage via the `template_id` reference.

## Overview

This endpoint allows you to update an existing push, email, or SMS template in your OneSignal app. Once updated, the changes are applied immediately and reflected across both the Dashboard and API when using the associated `template_id`.

Templates are updated using the same structure as when [creating templates](/reference/create-template).

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

To update a template, you must supply:

* Your **OneSignal App ID** found in [Keys & IDs](/docs/en/keys-and-ids).
* The **Template ID**

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***

## Channel-Specific Requirements

### Push Templates

* The `contents` property must use the `en` (English) key along with other languages you want to support.
* All [Push Notification Properties](/reference/push-notification) are valid.
* All platforms are enabled by default. To limit, explicitly enable desired ones (e.g., `isAndroid: true` disables iOS and Web).

### Email Templates

* Set `isEmail: true`
* Include `email_subject` and `email_body`
* All [Email Channel Properties](/reference/email) are supported.

### SMS Templates

* Set `isSMS: true`
* All [SMS Channel Properties](/reference/sms) are supported.

***


# Update user
Source: https://documentation.onesignal.com/reference/update-user

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}
Modify a user's properties.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint updates user-level properties for an existing user in your OneSignal app.

* To change a user's `identity` like `external_id` or custom [Aliases](/docs/en/aliases), use the [Create alias](/reference/create-alias) and [Delete alias](/reference/delete-alias) APIs.
* To manage a user's `subscriptions`, use the [Create Subscription by alias](/reference/create-subscription) or [Create user](/reference/create-user) APIs.

***

## How to use this API

You must supply an alias in the request path:

* `alias_label`: The type of identifier (e.g., `external_id`, `onesignal_id`, or a custom alias label).
* `alias_id`: The corresponding value for that label.

See [Users](/docs/en/users) and [Aliases](/docs/en/aliases) for more info.

***


# View an app
Source: https://documentation.onesignal.com/reference/view-an-app

GET /apps/{app_id}
View the details of a single OneSignal app

## Overview

Use this API to retrieve metadata and platform configuration for a single OneSignal app associated with your account. This includes app names, App ID, Subscription counts, timestamps, and push platform credentials (Android/FCM, iOS/APNS, Web Push, Safari), making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

***

## How to use this API

To retrieve your app, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View API keys
Source: https://documentation.onesignal.com/reference/view-api-keys

GET /apps/{app_id}/auth/tokens
View the details of all of your current app API keys (Rich Authentication Token) for a single OneSignal app.

## Overview

This API is helpful for auditing and managing the API keys (Rich Authentication Tokens) associated with an app. It returns metadata for each token, including:

* Token name and ID
* IP allow list mode and associated CIDR ranges (if any)
* Creation and last updated timestamps

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

***


# View apps
Source: https://documentation.onesignal.com/reference/view-apps

GET /apps
Retrieve a list of all OneSignal apps associated with your account, including key app details like name, App ID, subscription counts, and timestamps. Useful for managing multiple apps through the OneSignal API.

## Overview

Use this API to retrieve metadata for all OneSignal apps associated with your account. This includes app names, App IDs, subscription counts, and timestamps, making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

<Warning>
  This API is limited to return a maximum of 1000 Apps. If you need access to more, then you should store the `app_id` and `name` for each of your apps on your own server to look up with the [View an app](/reference/view-an-app) API to get data for each app separately. Also, if you need to delete apps, then you can provide the `app_id` and `name` to OneSignal Support and ask for these to be deleted.
</Warning>

***

## How to use this API

To retrieve your apps, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View player
Source: https://documentation.onesignal.com/reference/view-device

GET https://onesignal.com/api/v1/players/{player_id}

Retrieve a single player record (Subscription) data registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `player_id` | string | Yes      | The OneSignal ID of the device. |

***

## Query Parameters

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `app_id`  | string | Yes      | Your OneSignal App ID. |

***

## Headers

| Header          | Value                            | Required | Description                        |
| --------------- | -------------------------------- | -------- | ---------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal LegacyREST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players/player_id_string?app_id=your_app_id HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json{ theme={null}
  "id": "player_id_string",
  "identifier": "push_token_or_email",
  "session_count": 5,
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_os": "14.4",
  "device_type": 1,
  "tags": {
    "level": "10",
    "user_type": "free"
  },
  "last_active": 1625253300,
  "created_at": 1625249800,
  "invalid_identifier": false,
  "external_user_id": "user123"
}
```

### Response Fields

| Field                | Type      | Description                                             |
| -------------------- | --------- | ------------------------------------------------------- |
| `id`                 | string    | OneSignal player ID.                                    |
| `identifier`         | string    | Push token, email, or phone number.                     |
| `session_count`      | integer   | Number of sessions associated with this device.         |
| `language`           | string    | Language set on the device (e.g., "en").                |
| `timezone`           | integer   | Time zone offset in seconds.                            |
| `game_version`       | string    | Version of your app the device is running.              |
| `device_os`          | string    | Operating system version.                               |
| `device_type`        | integer   | Numeric code for platform (0 = iOS, 1 = Android, etc.). |
| `tags`               | object    | Custom tags set on the device.                          |
| `last_active`        | timestamp | Last time the user was active (Unix timestamp).         |
| `created_at`         | timestamp | When the device record was created.                     |
| `invalid_identifier` | boolean   | Whether the push token or identifier is invalid.        |
| `external_user_id`   | string    | Your internal user ID mapped to this device.            |

***

## Errors

* 400 Bad Request – Missing or invalid parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied for this app or resource.
* 404 Not Found – The specified player\_id does not exist.

***


# View players
Source: https://documentation.onesignal.com/reference/view-devices

GET `https://onesignal.com/api/v1/players?app_id={app_id}&limit={limit}&offset={offset}`

Retrieve up to 80,000 player records (Subscriptions) registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Query Parameters

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `app_id`  | string | Yes      | Your OneSignal App ID.                                 |
| `limit`   | int    | No       | Number of entries to return (max 300, default is 300). |
| `offset`  | int    | No       | Result offset for pagination.                          |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players?app_id=your_app_id&limit=100&offset=0 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json theme={null}
{
  "total_count": 6,
  "offset": 0,
  "limit": 300,
  "players": [
    {
      "id": "player_id_1",
      "identifier": "push_token_or_email",
      "session_count": 3,
      "language": "en",
      "timezone": -28800,
      "game_version": "1.0",
      "device_os": "15.0",
      "device_type": 1,
      "tags": {
        "level": "15",
        "user_type": "free"
      },
      "last_active": 1625253300,
      "created_at": 1625249800,
      "invalid_identifier": false,
      "external_user_id": "user123"
    }
  ]
}
```

### Response Fields

| Field                        | Type    | Description                                  |
| ---------------------------- | ------- | -------------------------------------------- |
| `total_count`                | integer | Total number of devices for the app.         |
| `offset`                     | integer | Current pagination offset.                   |
| `limit`                      | integer | Number of devices returned in this response. |
| `players`                    | array   | List of device objects.                      |
| `players[].id`               | string  | Unique OneSignal player ID.                  |
| `players[].identifier`       | string  | Push token, email, or phone number.          |
| `players[].tags`             | object  | Custom tags set on the device.               |
| `players[].external_user_id` | string  | Your internal user ID.                       |

***

## Errors

* 400 Bad Request – Invalid query parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access not allowed for this app or key.

***


# View message
Source: https://documentation.onesignal.com/reference/view-message

GET /notifications/{message_id}?app_id={app_id}
View the details of a single message and the Outcomes associated with it.

## Overview

The View message API allows you to fetch data from a single push, email, or SMS message at a time. If you want to get multiple messages at a time, use the [View messages](/reference/view-messages) API. In most cases, you will likely want to use [Event Streams](/docs/en/event-streams) instead.

Currently this API does not provide Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are only **accessible 30 days after creation**; however, messages sent using the OneSignal dashboard are accessible for the app's lifetime.

See our [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and (after giving your users some time to interact with the message) pull the data if desired.

For example, if you send a message targeting the `include_aliases` parameter, the response will include the aliases you set. If you send with the `included_segments` parameter, then the response will only provide the segments you set. When targeting segments or filters, you can use the [Export audience activity CSV](/reference/export-csv-of-events) API to get the user event data.

To view outcome data for the message, you must include the `outcome_name` parameter with the name of the outcome you want to fetch, along with the accompanying aggregation type (.count or .sum), for example: `os__click.count`. For more information on outcome definitions, see [View Outcomes](/reference/view-outcomes).

***


# View messages
Source: https://documentation.onesignal.com/reference/view-messages

GET /notifications?app_id={app_id}&limit={limit}&offset={offset}&kind={kind}&template_id={template_id}&time_offset={time_offset}
View the details for a collection of messages.

## Overview

The View messages API fetches data for up to 50 push, email, or SMS messages at a time. To fetch a single message, use the [View message](/reference/view-message) API. In most cases, use [Event Streams](/docs/en/event-streams) instead.

This API does not return Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are **retained for 30 days** after creation; messages sent through the OneSignal dashboard are retained for the app's lifetime.

See [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

Use time-offset pagination for sequential pulls of all messages, and standard pagination for ad-hoc queries. For ETL or bulk export pipelines, use [Event Streams](/docs/en/event-streams) instead.

Filter results to a specific message kind or template using the `kind` and `template_id` query parameters. Both filters work with either pagination style.

### Optimized pagination with time offset

To efficiently retrieve all available messages for an app, use `time_offset`-based pagination. When `time_offset` is specified, the sort order changes from descending to ascending — the oldest messages appear first based on the [`send_after` date](/reference/create-message#send-after).

#### Accepted `time_offset` values

* ISO 8601 formatted timestamp — for example, `2025-01-01T00:00:00.000Z` (January 1, 2025, at 00:00 UTC).
* Opaque cursor token (Base64-encoded) — provided in the API response as `next_time_offset`.

<Steps>
  <Step title="Initial fetch">
    To fetch messages from a specific date onward, set `time_offset` to an ISO 8601 formatted timestamp. For example, to retrieve messages sent since January 1, 2025: `time_offset=2025-01-01T00:00:00.000Z`.

    <Note>
      * `time_offset` cannot be used with the standard `offset` parameter.
      * `time_offset` excludes messages that match the exact timestamp to avoid duplicates.
      * The response includes `next_time_offset`, a cursor token for the next page. No decoding required. For example: `"next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="`
    </Note>
  </Step>

  <Step title="Fetch additional pages">
    Use `next_time_offset` from the previous response as the `time_offset` value in the next request. For example: `time_offset=MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw==`.
  </Step>

  <Step title="Continue until completion">
    Repeat the request until an empty `notifications` array is returned, indicating all messages have been fetched.
  </Step>

  <Step title="Handling new messages">
    Because results are sorted ascending, new messages are added to the end. To resume fetching from where you left off, reuse the last `next_time_offset` that returned an empty response.
  </Step>
</Steps>

### Standard pagination

Use the `limit` and `offset` parameters to page through notifications for an app. The maximum result size is 50, and the default `limit` is `50`. Use `limit` to specify the result size and `offset` to increment by the limit value with each request.

For example, the first request uses `offset=0`, the second `offset=50`, the third `offset=100`, and so on.

Standard pagination is convenient for ad-hoc queries but degrades as the `offset` value grows. For sequential pulls of all messages, use time-offset pagination.

***


# View outcomes
Source: https://documentation.onesignal.com/reference/view-outcomes

GET /apps/{app_id}/outcomes?outcome_names={outcome_names}&outcome_time_range={outcome_time_range}&outcome_platforms={outcome_platforms}&outcome_attribution={outcome_attribution}
View and export push notification outcome metrics such as clicks, conversions, and custom events.

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

## Overview

Use this API to retrieve Outcome metrics associated with your OneSignal app, including push notification interactions and custom-defined events. Outcomes include data points like:

* **Clicks**: Number of users who clicked on a push.
* **Confirmed Deliveries**: Number of confirmed message deliveries.
* **Session Durations**: Number of sessions initiated.
* **Custom Events**: Actions like purchases, form submissions, or any event your app tracks via custom Outcome names.

For details on configuring custom Outcomes, refer to the [Outcomes documentation](/docs/en/custom-outcomes).

<Info>
  Outcomes are stored for approximately 30 days. To retain this data, you should regularly export it before it expires.
</Info>

***

## How to use this API

This API allows you to filter and aggregate Outcome data using several query parameters.

### `outcome_names`

Specify one or more Outcome names with an aggregation type suffix (`.count` or `.sum`).

**Default Outcome names:**

* `os__click.count` – Push notification clicks.
* `os__confirmed_delivery.count` – Confirmed deliveries.
* `os__session_duration.count` – Total sessions.

**Custom Outcome names:**

* You can track any custom event name (e.g. `Purchase`, `Signup`).
* If the custom name contains a comma, include only one name per request to avoid parsing issues.
* Example: `outcome_names=os__click.count,Purchase.count`

### `outcome_time_range`

The time range values can be one of the following:

* `1h` = (default) the last 1 hour data.
* `1d` = the last 1 day data.
* `1mo` = the last 1 month data.

### `outcome_platforms`

Maps to the subscription type property. Default is data from all platforms enabled for your OneSignal App.

| `device_type` | `type`      |
| ------------- | ----------- |
| 0             | iOSPush     |
| 1             | AndroidPush |
| 2             | FireOSPush  |
| 5             | ChromePush  |
| 8             | FirefoxPush |
| 11            | Email       |
| 14            | SMS         |
| 17            | SafariPush  |

Example: `outcome_platform=0` for iOS `outcome_platform=17,8` for Safari and Firefox.

### `outcome_attribution`

The way in which the Outcome occurred:

* `direct` = the Outcome occurred when the user interacted with the message. Some Outcomes only have `direct` attribution like `os__click` and `os__confirmed_delivery` because they only occur as the direct result of the message.
* `influenced` = the Outcome occurred within the Time Window of the message being sent, but the user never interacted with the message. See [Outcomes](/docs/en/custom-outcomes) for details.
* `unattributed` = the Outcome occurred without a direct or influenced attribute.
* `total` = (default) the sum of direct+influenced+unattributed.

***


# View segment
Source: https://documentation.onesignal.com/reference/view-segment

GET /apps/{app_id}/segments/{segment_id}
Retrieve details for a single segment by its ID, including subscriber count and optionally segment metadata and filters.

## Overview

Retrieve details for a single segment by its ID. By default, this endpoint returns only the subscriber count. Use the optional `include-segment-detail` parameter to also retrieve segment metadata and filters.

<Note>
  The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard.
</Note>

<Warning>
  **User-based segments not supported**: Segments containing message event or custom event filters (user-based segments) are not yet supported via this API. Attempting to fetch these segments will return a 400 error. These segments can only be managed through the dashboard UI.
</Warning>

***

## How to use this API

### Basic usage

By default, this endpoint returns only the subscriber count for the segment:

```json theme={null}
{
  "subscriber_count": 12345
}
```

### Include segment details

To retrieve full segment details including metadata and filters, set `include-segment-detail=true`:

```
GET /apps/{app_id}/segments/{segment_id}?include-segment-detail=true
```

This returns the subscriber count along with a `payload` object containing segment details:

<CodeGroup>
  ```json Simple filter theme={null}
  {
    "subscriber_count": 12345,
    "payload": {
      "id": "4414c404-56a3-11ed-9b6a-0242ac120002",
      "name": "Subscribed Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {
          "field": "session_count",
          "relation": ">",
          "value": "5"
        }
      ]
    }
  }
  ```

  ```json With AND/OR operators theme={null}
  {
    "subscriber_count": 5678,
    "payload": {
      "id": "5525d515-67b4-22fe-0c7b-1353bd231113",
      "name": "Engaged Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {"field": "session_count", "relation": ">", "value": "2"},
        {"operator": "AND"},
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "last_session", "relation": "<", "hours_ago": "24"}
      ]
    }
  }
  ```
</CodeGroup>

### Filters format

The `filters` array uses the **same format** as the [Create segment](/reference/create-segments) API. This means you can:

* Read filters from this endpoint
* Modify them as needed
* Use them directly with the [Update segment](/reference/update-segment) or [Create segment](/reference/create-segments) APIs

The array contains filter objects and operator objects:

**Filter object** - defines a condition:

| Field                   | Type    | Description                                                                                                                                         |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field`                 | string  | The filter type: `tag`, `last_session`, `first_session`, `session_count`, `session_time`, `language`, `app_version`, `location`, `country`, `email` |
| `relation`              | string  | The comparison operator: `>`, `<`, `=`, `!=`, `exists`, `not_exists`, `in_array`, `not_in_array`, `time_elapsed_gt`, `time_elapsed_lt`              |
| `value`                 | string  | The filter value (for most filter types)                                                                                                            |
| `key`                   | string  | The filter key (required for `tag` filters)                                                                                                         |
| `hours_ago`             | string  | Hours ago value (for `last_session`/`first_session` filters)                                                                                        |
| `radius`, `lat`, `long` | string  | Location parameters (for `location` filters)                                                                                                        |
| `unsupported_in_api`    | boolean | If `true`, this filter cannot be used with Create/Update segment APIs (see note below)                                                              |

**Operator object** - combines filters:

| Field      | Type   | Description                                                                        |
| ---------- | ------ | ---------------------------------------------------------------------------------- |
| `operator` | string | Either `AND` or `OR`. Filters connected with `AND` have higher priority than `OR`. |

<Warning>
  Some segments created via the dashboard UI may contain filter types not supported by the public API (e.g., `message_event`, `custom_event`). These filters will include `unsupported_in_api: true`. You cannot use these filters when creating or updating segments via the API.
</Warning>

### Payload fields

| Field         | Type           | Description                                                                         |
| ------------- | -------------- | ----------------------------------------------------------------------------------- |
| `id`          | string         | The unique identifier for the segment (UUID v4).                                    |
| `name`        | string         | The segment name (max 128 characters).                                              |
| `description` | string \| null | Human-readable description for the segment (max 255 characters). `null` when unset. |
| `created_at`  | integer        | Unix timestamp when the segment was created.                                        |
| `source`      | string         | The source of the segment: `default`, `custom`, or `quickstart`.                    |
| `filters`     | array          | Array of filter and operator objects that define the segment criteria.              |

***


# View segments
Source: https://documentation.onesignal.com/reference/view-segments

GET /apps/{app_id}/segments
Retrieve a list of segments associated with a specific OneSignal app. Useful for programmatically accessing segment metadata such as name, creation date, and status.

## Overview

Retrieve a list of segments associated with a specific OneSignal app. This is helpful when you want to access segment metadata programmatically instead of using the OneSignal Dashboard UI.

<Warning>
  This endpoint only retrieves existing segment metadata. It does not provide the segment filters or user data.
</Warning>

***


# View template
Source: https://documentation.onesignal.com/reference/view-template

GET /templates/{template_id}?app_id={app_id}
Retrieve the details of a specific message template in your OneSignal app using its template ID. This API returns the template content, target channel, and timestamps for creation and last update.

## Overview

This endpoint returns metadata and content for a single template, including:

* Template body/content
* Target delivery channel (e.g., push, email, SMS)
* Creation and last updated timestamps

This is useful for inspecting existing templates before using or updating them.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Required parameters:

* `app_id` (query param): Your OneSignal App ID.
* `template_id` (path param): The unique ID of the template.

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# View templates
Source: https://documentation.onesignal.com/reference/view-templates

GET /templates?app_id={app_id}&limit={limit}&offset={offset}
Retrieve a paginated list of message templates from your OneSignal app. This endpoint returns summary information for each template, including ID, name, creation, and update timestamps.

## Overview

Use this endpoint to retrieve a list of message templates associated with a specific OneSignal app. The response provides summary information only:

* `template_id`
* `name`
* `created_at`
* `updated_at`

<Note>
  This endpoint does **not** return full template content such as message bodies, channel properties, or delivery configuration. For detailed template data, use the [View Template](/reference/view-template) endpoint.
</Note>

***

## How to Use This API

### Required Parameters

* **`app_id`** (query param): The OneSignal App ID whose templates you want to retrieve.

### Optional Parameters

* **`limit`** (query param): Number of templates to return (default: `50`, maximum: `50`).
* **`offset`** (query param): Number of templates to skip. Use for pagination.

### Pagination Example

If your app has 125 templates and you're using the default limit of 50:

1. First request (first 50 templates):\
   `GET /templates?app_id={app_id}&offset=0`

2. Second request (next 50 templates):\
   `GET /templates?app_id={app_id}&offset=50`

3. Third request (final 25 templates):\
   `GET /templates?app_id={app_id}&offset=100`

Repeat the request while adjusting the `offset` until you've retrieved all templates.

***


# View user
Source: https://documentation.onesignal.com/reference/view-user

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}
Retrieve a user including aliases, properties, and subscriptions.

## Overview

* Use this API to retrieve a user's full profile, including identity aliases, user properties, and messaging subscription details across channels.
* This is helpful for verifying user data, debugging subscription issues, or syncing OneSignal user data with your internal systems.

For detailed concepts and guides, see [Users](/docs/en/users), [Subscriptions](/docs/en/subscriptions), and [Aliases](/docs/en/aliases) documentation.

## How to use this API

To look up a user, you must provide both an `alias_label` and an `alias_id`. In most cases, your `external_id` will serve as the `alias_label`, and its value will be passed as the `alias_id`. While you may use a custom alias, we strongly recommend setting and using the `external_id` as your primary user identifier for consistency across platforms.

To retrieve a user using their OneSignal ID, set the `alias_label` to `onesignal_id`. **Note**: When querying with any alias other than `onesignal_id`, authentication is required.

***


# Changelog
Source: https://documentation.onesignal.com/release-notes/changelog

Learn about the latest updates to OneSignal.

Follow along with updates across OneSignal. We're launching new features and improving our product all the time!

<Update label="June 18 2026">
  **AI-assisted SDK installation updated and expanded**

  * AI install prompts have been rewritten and expanded to cover Android, iOS, React Native, Flutter, and Web SDKs.
  * Paste a single ready-made prompt into your AI coding assistant (Cursor, Claude, Copilot, or similar) and the assistant installs the SDK, drops in initialization code, and configures push and in-app messaging automatically.
  * No deep development experience required — marketers and non-technical users can complete SDK setup in minutes.
  * Prompt instructions were revised to fix errors identified during internal testing, so generated integrations are more accurate.
  * Available to all new sign-ups with no enablement required; requires an AI coding tool and access to the app codebase.
</Update>

<Update label="June 15 2026">
  **Extended `in_array` and `not_in_array` relations to the Device Type filter**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `device_type` filter field. Use them to match against a comma-separated list of device types in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "device_type", "relation": "in_array", "value": "iOS,Android"},
    {"operator": "AND"},
    {"field": "device_type", "relation": "not_in_array", "value": "Email"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="June 15 2026">
  **RCS editor experience improvements**

  We've improved how you build and send RCS, giving you a more intuitive editor, clearer approval visibility, and a more graceful SMS fallback experience:

  * **See carrier approval status in settings.** Each sender resource's carrier approval status is now visible at **Settings > SMS > Senders**, so you can track where each carrier stands in the approval process without leaving the dashboard.
  * **Select a sender per RCS template.** In Templates you now choose a specific sender instead of relying on a single global default, improving how RCS sends within Journeys and giving you automations for multiple SMS use cases.
  * **A more intuitive editor.** The composer automatically shows the right editor for the selected sender — the RCS editor for senders with an RCS resource, and the SMS editor for SMS-only senders.
  * **Text only RCS.** A new Text only content type sends plain branded RCS text.

  When a sender gains an approved RCS sending resource, OneSignal automatically prefers RCS for existing automations on that sender, mapping your existing SMS content to RCS so there's no manual rework.

  Available for all customers contracted for RCS. See [RCS messaging](/docs/en/rcs-messaging) for details.
</Update>

<Update label="June 8 2026">
  **Segment editor improvements: multi-value filters, copy filters, and filter JSON**

  Building segments in the dashboard is now faster and more flexible:

  * **Match multiple values in one filter.** The Language, Country, App Version, and User Tag filters now support the "is any of" and "is not any of" relations, so you can match a list of values in a single filter instead of chaining several filters with OR.
  * **Copy filters and filter groups.** Duplicate an individual filter or an entire filter group from the editor to reuse its configuration without rebuilding it by hand.
  * **View and copy filter JSON.** Open the filter JSON panel to see the REST API representation of your segment's filters, then copy it to use directly in the [Create segment](/reference/create-segments) API.
</Update>

<Update label="June 4 2026">
  **Retired Alexa and Windows Phone 8.0 as Device Type filter options**

  The `Alexa` and `Windows Phone 8.0` values are no longer available for the Device Type filter when you create or edit a segment, in both the dashboard and the Create segment API. Selecting either value in the dashboard is no longer possible, and the API rejects them with a validation error.

  Existing segments that already use these values continue to evaluate and deliver as before. To save changes to such a segment, replace the retired Device Type filter first.
</Update>

<Update label="June 2 2026">
  **Extended `in_array` and `not_in_array` relations to tag and app version filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `tag` and `app_version` filter fields, in addition to the `country` and `language` fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"},
    {"operator": "AND"},
    {"field": "app_version", "relation": "not_in_array", "value": "1.0.0,1.0.1"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="May 11 2026">
  **Email BCC is now generally available**

  You can now add BCC (blind carbon copy) recipients to email sends, including templates used in journeys and messages sent via the API. Use BCC to archive customer-facing email to a shared inbox or compliance system, forward sends to third-party services, or keep internal stakeholders copied on transactional sends.

  * Available on all plan types.
  * Maximum of 5 BCC addresses per send.
  * Each BCC recipient counts toward the total email volume for that send (for example, 1,000 primary recipients with 1 BCC address = 2,000 sends).
  * BCC metrics are excluded from analytics.

  See [BCC emails](/docs/en/email-bcc) for setup and usage details.
</Update>

<Update label="May 12 2026">
  **Added `in_array` and `not_in_array` relations for country and language filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `country` and `language` filter fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "in_array", "value": "US,GB,CA"},
    {"operator": "AND"},
    {"field": "language", "relation": "not_in_array", "value": "es,fr"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="April 21 2026">
  **Manage custom aliases from the User Profile**

  You can now view, add, edit, and delete a user's custom aliases directly from the **Aliases** section on the User Profile **Overview** tab, without using the API.

  * Add an alias by entering a label (alias key) and value (alias ID), copy any alias value to the clipboard, edit a value, or remove an alias.
  * Each user supports up to 10 aliases, and alias labels and values can each contain up to 128 characters.
  * `external_id` and `onesignal_id` are reserved and can't be used as custom alias labels.
  * A user must have an External ID set before you can add custom aliases. External ID is still managed separately in the Profile section.

  See [Aliases](/docs/en/aliases) for more details.
</Update>

<Update label="April 17 2026">
  **Role-based access control (RBAC) is now generally available**

  Granular role-based access control has been rolled out to all customers, giving teams more flexibility to support least-privilege access patterns and manage permissions as they scale.

  * **New `team_member` org-level default role.** A baseline role for new users added to an organization.
  * **New `composer` app-level role.** Lets users create and edit messages, templates, segments, and journeys without sending, activating, or deleting content.
  * **Updates to `editor` and `viewer` roles.** Refined permissions for clearer separation of duties.
  * Available roles vary by plan type.

  See [Manage team members](/docs/en/manage-team-members) for the full breakdown of roles, permissions, and plan availability.
</Update>

<Update label="April 16 2026">
  **Light/dark mode toggle for HTML in-app message previews**

  You can now switch between light and dark mode directly in the dashboard when previewing HTML in-app messages, so what you see matches what your users will actually see.

  * A light/dark mode toggle is now available in the in-app message preview for HTML messages.
  * The preview no longer reflects your OS theme. It reflects the mode you select in the dashboard.
  * Previously, the preview always rendered using whatever theme your own computer was set to, with no indication that was the cause, so there was no reliable way to check dark mode designs from the dashboard.

  HTML in-app messages do not automatically get a dark mode. The message still has to be coded for it using `@media (prefers-color-scheme: dark)` styles. If your message doesn't include those styles, toggling to dark mode in the preview won't change how it looks.

  The toggle is available for HTML in-app messages only. Block-type in-app messages are not included in this release. Generally available for all customers using HTML in-app messages.

  See [Design your in-app message with HTML](/docs/en/design-your-in-app-message-with-html) for how to add dark mode support.
</Update>

<Update label="April 15 2026">
  **Standardized delivery metrics across all channels**

  Delivery metric terminology is now consistent across every messaging channel in OneSignal. All channels now share a unified delivery hierarchy: Audience → Sent → Delivered, with the same definitions everywhere. Labels have been aligned across delivery reports, journey reports, engagement trends, and CSV exports. The [Metrics Glossary](/docs/en/analytics-metrics-glossary) has been fully rewritten as the canonical reference for every metric definition.
</Update>

<Update label="April 10 2026">
  **Audience counts now show subscribed and unsubscribed breakdowns**

  The segment editor now shows both subscribed and unsubscribed counts for every subscription-based segment, with a per-channel breakdown across push, email, and SMS. Previously, only the opted-in (subscribed) count was visible.

  Additional improvements:

  * Counts always return within approximately 15 seconds. Exact counts are shown when possible; estimates are used when an exact count can't be calculated in time.
  * Estimates are clearly labeled: above 10,000 with a +/- margin of error (e.g. 140,000 +/- 5,000), and below 10,000 as a less-than value (e.g. \<4,800).
  * Estimates will never show 0 for a segment. Previously for segments with very small but non-zero membership, estimates could incorrectly show as 0.

  This release covers subscription-based segments. User-based segment improvements are coming later in Q2 2026.
</Update>

<Update label="April 7 2026">
  **Updated User Profile page**

  The User Profile page has been redesigned with a tabbed layout and several new management actions directly on the page:

  * Add and remove Subscriptions from a User
  * Search across a User's data tags
  * Perform more direct edits and admin actions without leaving the profile

  The previous profile view is still accessible from the **Actions** menu if you need it.
</Update>

<Update label="March 25 2026">
  **test users now apply at the User level**
  Marking a Subscription as a test user now automatically marks all Subscriptions for that User as test users, effectively creating a Test User.

  * Any new Subscriptions added to a Test User will automatically be marked as test users.
  * Test User is now a User-level property rather than a Subscription-level one.

  **OneSignal Server SDKs just got their first v5 stable release!**

  After a period of testing and iteration, v5 is now the default version users will get when installing any of our server SDKs. Here are the current versions included in this release:

  | Language | Version |
  | -------- | ------- |
  | Node.js  | 5.4.0   |
  | Go       | 5.3.0   |
  | Java     | 5.3.0   |
  | .NET     | 5.4.0   |
  | Rust     | 5.3.0   |
  | Ruby     | 5.3.0   |
  | Python   | 5.3.0   |
  | PHP      | 5.3.0   |

  This release pairs well with our recently refreshed Server SDK Reference, giving developers a solid starting point for integrating with the OneSignal API.
</Update>

<Update label="March 20 2026">
  **Audit Log Export is now in GA**

  * Customers can now export audit logs. Customers can export 2 days for free tier and up to 90 days with security and legal entitlement (either as individual SKU or enterprise plan).
  * Provides customers additional metadata details and allows them to filter through data locally for their own audits and consumption with their own tools.

  **Failed Reasons in Audience Activity for everyone!**

  * Free plan users can now see exactly why individual audience members failed to receive a notification — directly in the Audience Activity view.
  * When a notification fails, especially common when troubleshooting set up, free users had no way to know whether the problem was a bad token, an unsubscribed user, or a device issue — leaving them guessing and unable to fix anything. Now they get the same failure visibility paid users have, so they can debug and get set up properly.
  * Same data retention as audience activity (30 days)
</Update>

<Update label="March 17 2026">
  **Data Model Updates and Field Deprecations**

  To improve platform performance, strengthen data integrity, and reduce the risk of configuration errors, we are introducing several updates to the OneSignal data model.

  These changes will take effect **April 15, 2026.**

  **Field Limits**

  We are introducing limits on two user fields to improve consistency and prevent unexpected behavior.

  Existing records exceeding these limits will not be modified to avoid disrupting current data and operations.

  **External ID**

  * `external_id` values can contain up to 128 characters.

  **Aliases**

  * Each user can have up to 10 aliases.
  * Each alias key and value can contain up to 128 characters.

  **Field Deprecations**

  We are deprecating several legacy Subscription fields that are no longer actively used:

  * `amount_spent`
  * `rooted`
  * `bought_sku`
  * `app_interests`
  * `purchased_items`

  After April 15, 2026, these fields will no longer be available in:

  * Segment Builder
  * API requests
  * Event streams
  * Webhooks

  **Impact for Customers Using These Fields**

  If your implementation currently references any of these fields:

  **Segments:** Segments using these fields will be paused and labeled for your review.

  **Journeys:** Journeys depending on those segments will be archived.

  **Event Streams and Webhooks:** These fields will return empty values.

  **What You Need to Do**

  Most customers do not need to take any action.

  If your implementation relies on any of the deprecated fields, we recommend reviewing your segments and integrations before **April 15, 2026.**
</Update>

<Update label="March 6 2026">
  Email Address Validation is now available!

  * When email addresses are added to OneSignal, they're now validated at three entry points:
    * API: syntax check
    * CSV import: full validation including typo detection, MX record lookup, disposable email flagging, and role-based address detection\*
    * Bulk validation: same full checks, runs against addresses already in your audience
  * Free plans have syntax and typo checks.
  * Paid plans will have syntax, typo, MX, disposable email, and role based email address checks.

  See [Email Address Validation](/docs/en/email-address-validation) for more details.
</Update>

<Update label="March 4 2026">
  **Dashboard layout redesign has shipped!**

  * Panel-based layout. The old floating card approach has been replaced with flat panels. The side nav sits in a clean gray panel, and the main content in a white panel. This simplifies the look and feel and gives us a more modern aesthetic.
  * New global top bar. Breadcrumbs, the new Create menu, Help/Support links, and Upgrade button all live in a new sticky top bar that follows you on scroll.

  **Richer date context across the dashboard**

  Dates show up everywhere in OneSignal — denoting message creation, notification send times, user sessions, etc. — but it wasn't always clear which timezone you were looking at, or how recent something actually was. This came up in a discussion last week among the dashboard engineers.

  Now, hovering over a date in the following areas of the Dashboard shows a tooltip with three pieces of context at once: the time in your local timezone, the time in UTC, and a relative timestamp (like "2 days ago").

  Where you'll see it:

  * Message lists and indexes
  * Message reports
  * Message review modals before sending
  * User and subscription profiles

  This is enabled for all apps — no action needed. Just hover a date and it's there!

  **In-App Message library with new quickstarts!**

  We've shipped a library of professionally designed, ready-to-use in-app message templates — available now to all plans in the dashboard.

  What's in it: 7 categories of quick starts covering the most common IAM use cases: push soft prompts, promotions, onboarding flows, feature announcements, location prompts, spin-to-win, and notification preference centers.

  How to access: Dashboard → Messages → In-App → New In-App → OneSignal Quick Starts. No feature flag or backend enablement required — available immediately. (See demo for the full experience in product)

  Go from zero to a production-ready in-app message in minutes, without writing HTML from scratch!
</Update>

<Update label="March 3 2026">
  **Enhanced Snowflake Integration Now Available!**

  Key improvements include:

  * 15-minute sync intervals (down from 24 hours)
  * Selective event syncing so customers only export what they need
  * Self-service setup directly in the OneSignal dashboard
  * New events like in-app impressions, email bounced/received, and separated Live Activity events.
  * We've also added richer properties including Template ID, last active timestamp, and subscription status.

  Customers get near real-time data in their Snowflake instance with full control over what gets synced meaning faster insights. Selective syncing alone can dramatically reduce event volume (and spend) by letting them export only the events that they need.

  This moves from the legacy flat annual fee to our Event Streams pricing model. Customers pre-purchase an event volume tier, and that tier covers all destinations (Snowflake, BigQuery, Databricks, etc.).

  Live now for all customers. All new customers will automatically have access to this new integration. Existing legacy Snowflake customers have until August 1st to migrate to the new integration before deprecation. Both integrations can run in parallel during the transition so they can ensure parity/consistency, and we will be doing outreach to those affected shortly.

  See [Snowflake](/docs/en/snowflake) for more details.
</Update>

<Update label="February 26 2026">
  **Audit Logs API is now available**

  Enterprise customers (with Legal & Security package) can now programmatically access the same audit log data surfaced in the OneSignal dashboard — pipe it directly into their SIEM, compliance tooling, or internal security workflows.

  * Returns a time-scoped record of actions taken in their org — who did what, when, and from where
  * Filter by app, action type, actor, target, or IP address
  * Supports cursor-based pagination for large result sets

  See [Audit Logs API](/reference/list-audit-logs) for more details.
</Update>

<Update label="February 9 2026">
  Huawei Badge Parameter Support

  We now support app icon badges on Huawei (HMS) devices via both the API and dashboard.

  * What's new: Three new parameters on `Notification#Create`
    * `huawei_badge_class` — the app's launcher activity class name (required for badge)
    * `huawei_badge_set_num` — set the badge to an exact number (0–99)
    * `huawei_badge_add_num` — increment the badge by a specific amount (1–99)

  On the dashboard, you'll see a new Badge option under Send to Huawei Android with "Don't set" / "Set to" / "Increase by" options.

  * Good to know:
    * Setting `huawei_badge_set_num` to 0 clears the badge
    * If neither set nor add is specified, the badge increments by 1 by default
    * Huawei does not auto-clear badges when the app opens
</Update>

<Update label="January 29 2026">
  API Documentation Improvements

  * New API endpoint: [View Segment](/reference/view-segment) - Retrieve details of a specific segment by ID, including optional segment filter details.
  * New API endpoint: [Update Segment](/reference/update-segment) - Update an existing segment's name and/or filters programmatically.
  * Fixed JSON example formatting across multiple API reference pages for improved readability:
    * Segments API: view-segments, create-segments, delete-segments
    * Users API: create-user, view-user, update-user, delete-user
    * Subscriptions API: create-subscription, delete-subscription, transfer-subscription, unsubscribe-with-token, create-alias-by-subscription
</Update>

<Update label="January 26 2026">
  **Audit Logs are now available!**

  * Customers now have the ability to determine exactly what's happening across their OneSignal account. Audit Logs gives them a complete timeline of every action taken in their organization—who did what, when, and from where.
  * Track 50+ action types including:
    * Authentication events (login, logout, API key operations)
    * Message activity (notifications sent, canceled, A/B tests, Journeys)
    * Team changes (member added, role changed, removed)
    * Configuration updates (webhooks, segments, templates, integrations)
    * Billing & subscription events
  * Powerful filtering:
    * Search by team member email
    * Filter by action type, app, IP address, or item type
    * Custom date ranges with presets
    * Shareable filtered URLs—customers can collaborate with their team instantly
  * Deep visibility:
    * Expandable rows reveal 30+ fields: IP address, browser, location, correlation ID, API version, and more
    * Available at both App and Organization levels
    * Quick-access links from Journeys, Segments, Templates, Notifications, and more
  * Retention:
    * Legal & Security package: 90-day lookback
    * All other plans: 2-day lookback
  * Perfect for security audits, debugging, and understanding team activity at a glance.
</Update>

<Update label="January 9 2026">
  * Standardized time series for charts are now available for:
    * Event Streams and webhooks
    * Email delivery reports
    * SMS/RCS delivery reports
</Update>

<Update label="December 22 2025">
  * confirmed receipt Now Available On Engagement Trends
    * Customers with access to confirmed receipt can now see confirmed receipt on the Engagement Trends Time Series Chart.
    * This missing data was a common point of confusion for customers. They could see confirmed receipt & click through rate, but had no access to the total confirmed deliveries metric.
    * This additional data point gives customers confidence in the rates we're showing and helps with confusion on the difference between "delivered" and "Confirmed receipt" for push notifications.
</Update>

<Update label="December 12 2025">
  * New integration - Self-serve Snowflake data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake without going through customer support
    * The legacy Snowflake documentation remains available for existing implementations
</Update>

<Update label="December 8 2025">
  Live Activities in Event Streams & Integrations

  Live Activities Analytics provides two key capabilities to optimize customers' live activity strategy:

  1. Better Troubleshooting with confirmed receipt
     Gain visibility into whether devices actually received live activity updates. confirmed receipt tracking identifies delivery issues quickly to understand the true reach of live activities.
     Available in:

  * Individual message reports with per-device confirmation
  * Data exports to BI tools (through event streams and integrations)

  2. Deeper Engagement Insights with data exports to integrations & event streams
     Answer critical questions about how users interact with your live activities:

  * How many users engaged with my live activity over its duration?
  * When did users drop off?
  * What was the peak engagement time?
  * When did users click? (coming soon)

  Export live activity data to BI tools to analyze engagement patterns, optimize timing, and improve future campaigns.
</Update>

<Update label="December 5 2025">
  We've launched a new [Metrics Glossary](/docs/en/analytics-metrics-glossary) in our documentation. This resource provides a single source of truth for delivery metric definitions, helping both our team and customers understand our metrics consistently across dashboards, APIs, and exports.
  While we continue working toward unified terminology across all touch points, this glossary establishes clear mappings and definitions as they exist today, making it easier for customers to navigate our current analytics landscape.

  Custom Events in User Activity Timeline
  Custom events are now visible per User on their profile page in a dedicated tab. You can:

  * Filter by event type and event source
  * Filter by date, to any time window in the past. Only limiting factor is customer's own events retention window setting!
  * Expand each event to see the full payload
  * Click through to the events index to see that event type's config and full cross-user activity log

  This is important because:

  * It helps paint the complete picture of user activity. At a basic level, customers ask the question, "what's going on with this user?" and this helps answer it.
  * Especially useful for zoomed-in troubleshooting, auditing, what-happened analysis.
  * Please note: this will only be visible to customers in Custom Events early access, but will be available to all as they gain access to Custom Events
</Update>

<Update label="November 26 2025">
  UX Improvements Now Live

  1. Row-Level Linking
     You can now click anywhere on a table row to navigate to its destination, instead of having to click a specific cell. This makes navigation faster and more intuitive.
  2. Row Highlighting on Hover
     All tables now highlight the entire row on hover, helping users track data more easily and reducing visual strain when scanning wide tables.
  3. Improved Responsiveness
     The actions column has been narrowed to preserve horizontal space and is now right-aligned at the end of every table.
     It also features sticky, floating behavior — especially useful on smaller screens where horizontal scrolling is required.
     Some tables better truncate long text (e.g., lengthy message names) more effectively to maintain a clean layout.
  4. Refined Sorting UX
     Updated sort icons make the sort direction easier to interpret. Clicking anywhere on a column header now toggles sorting, improving ease of use.
  5. Unified Column Visibility Menu (Applies to Journeys, Users, Subscriptions)
     Tables with customizable columns now use a consistent, cleaner UI. Column changes update live as you toggle them.
  6. Updated Search Bar UI
     The search bar now aligns with design standards, featuring a left-aligned search icon, and a button that shows after typing for easy input clearing.
  7. Improved Pagination Formatting
     Pagination controls now use comma formatting for large numbers, improving scannability and readability.

  Core Component Update
  Many of the enhancements above come from migrating these tables to our core design system’s DataTable component. Sorting and filtering improvements for tables are consistently among the most requested features we receive. While these updates don’t introduce new sorting or filtering behavior yet, this component upgrade provides a more consistent experience for the functionality we have today, and does lay the foundation for Product teams to build more advanced table capabilities once those initiatives are prioritized.

  Coming Soon

  * Most tables across the Dashboard already include these improvements. A few remaining areas still require component updates before they can adopt the full set of new enhancements:
    * In-app index
    * Templates index
    * Audience activity table
    * A/B tests stats table
</Update>

<Update label="November 12 2025">
  UX Enhancement: Duplicate Templates Directly from the Editor
  In usability tests and dogfooding sessions, we noticed users often duplicate Journey nodes and then edit their templates. Previously, you had to exit the template editor and duplicate the template from the index view, an extra step that interrupted the workflow.
  Now, you can duplicate templates directly from the actions dropdown in the template editor. This small but meaningful improvement streamlines your editing experience and makes iteration faster. While our long-term goal is to enable template/content editing directly within Journeys, this enhancement is a great step in that direction.

  New Platform Filters for Engagement Trends & Subscription Trends
  You can now filter push engagement trend data by platform (iOS, Google Android, Huawei, etc.) to get a more granular view of performance across specific devices.
  In the spirit of our Analytics Consistency project, we've also brought this same filtering experience to Subscription Trends.

  Analytics Consistency: Standardized Time Series Chart Filters
  We're standardizing filter options across our time series charts, giving customers a consistent experience and clear access based on their plan.
  Key Changes:

  * All charts will share the same set of granularity and look back filters
  * Consistent casing and terminology used on all filters
  * Consistent upgrade experience for customers on plans with limited access
    As an example, Subscription Trends now supports a 2 year look back after the change.

  Charts where we've already rolled out these changes:

  * Engagement Trends
  * Subscription Trends
  * Global Outcomes
  * Push Delivery
  * All Template Reports
  * Coming Soon:
  * Email Delivery
  * SMS Delivery
  * Journeys Reports

  Look back access based on plan type:

  * Free: 30 days
  * Growth: 90 days
  * Professional: 1 year
  * Enterprise: 2 years
  * Custom: Up to 90 days (based on plan types above)
</Update>

<Update label="October 6 2025">
  Nice UXE on Journey Settings. We’ve updated the Journeys Settings Side panel to be more user friendly by adding a side navigation to keep each section in focus. This is in tandem with the eventuality of having more settings available to the user as we look towards Journey Goals, and more.  We will accompany this release with an intercom slide letting the user know we have updated the settings area as to give them a heads up due to the abrupt pattern change.

  Every Setting, In Focus: Journey Settings are now grouped and spotlighted, helping you zero in on each choice without distraction.
</Update>

<Update label="October 2 2025">
  Custom Events are now available to all customers on paid plans! You can now send custom events via our API or SDK, and use them to trigger actions in Journeys with your own event data.
</Update>

<Update label="September 21 2025">
  Customers can now pause a segment that's counting towards their segments entitlement even though it's only being used in an archived journey or paused IAM. We also made it even easier to pause segments, if the user wants to pause a segment, we'll help the user pause or archive the active IAMs or journeys stopping the user from pausing a segment.
</Update>

<Update label="September 9 2025">
  Deactivate email senders

  Deactivate email domains that are no longer in use or were set up incorrectly. This includes fallback handling for your email templates and scheduled sends to make sure you don't break them by removing a domain, just in case it was being used more widely than you anticipated.
</Update>

<Update label="August 29 2025">
  Personalize emails with real-time Data Feeds

  You can now use Data Feeds to pull live content from your APIs directly into emails at send time. No more static CSVs or preloaded tags — every message can include the latest account details, product recommendations, or order updates.

  Available in the email template composer for emails sent via Journeys, Data Feeds includes preview tools and error handling to keep sends smooth.

  👉 See how to set up [Data Feeds](/docs/en/data-feeds)
</Update>

<Update label="August 04 2025">
  You can now hold users in a Journey step until specific conditions are met before they move forward with the *Wait Until* action. This new feature allows you to:

  * Hold users at a step until they enter a segment or trigger a message event (such as a specific message being delivered, opened, or clicked).
  * Add multiple conditions and branch users based on whichever condition they meet first.
  * Set an expiration path that moves users forward or removes them from the Journey if none of the conditions are met within your chosen timeframe. This gives you greater flexibility and control over how users progress through your Journeys. Learn more: [Journeys Actions](/docs/en/journeys-actions)

  AI Composer Push Notifications
  You can now generate or improve push notification message copy using the AI message composer. This update helps you craft high-performing content without leaving OneSignal. When creating a new push notification, select AI-generated push button to get started. To improve existing copy, select “Refine” in the Title, Subject, or Message fields.

  New [Integrations](/docs/en/integrations) index page contains the following enhancements:

  * Filtering by type of integration
  * Filtering by Inbound/Outbound directions of data flow
  * Includes our new inbound DWH/Data ingestion options for custom events
</Update>

<Update label="July 07 2025">
  * Quickly identify and manage segments tied to campaigns
    * We’ve made it easier to clean up outdated segments.
    * Previously, you couldn’t delete a segment if it was tied to an In-App Message (IAM) or Journey, even if that campaign was paused or archived. Now, when you try to delete a segment, you’ll see a modal listing all IAMs and Journeys that are preventing deletion.
    * This helps you quickly locate and update the associated campaigns, so you can keep your workspace clean and organized without having to hunt through every Journey or IAM.
</Update>

<Update label="June 30 2025">
  * Segment users based on real message engagement
    * You can now create user segments based on how they interacted with previous messages across push, email, SMS and in-app.
    * This update adds a new Message Event filter that allows you to segment users based on events like email opens, push clicks, SMS failures, and more - without relying on tags or external tools.
    * Available on all paid plans.
    * See [Segmentation](/docs/en/segmentation#message-event-filters) for more details.
</Update>

<Update label="June 27 2025">
  * New documentation with Mintlify!
    * We've updated our docs!
    * New AI features and easier readability.
    * Updated API reference and openapi spec.
    * New Tutorials page with common use cases and step-by-step details to get you setup quickly!
</Update>

<Update label="June 18 2025">
  * Track In-App engagement trends alongside push, email, and SMS
    * Customers can now see In-App Message impressions, clicks, and click-through rates directly in the Engagement Trends chart. This update gives marketers a unified view of how users are interacting with all message types over time—including In-App—making it easier to spot trends, report on performance, and optimize messaging across channels.
    * With this update, In-App engagement data is now included alongside push, email, and SMS across all views in the Engagement Trends chart. Stats are grouped by day and support up to two years of data (depending on plan). This data is exportable via CSV just like other channels, and can be filtered to look at specific date ranges or message types.
    * This feature is available to all customers.
</Update>

<Update label="June 12 2025">
  * Unlock deeper email engagement insights with multi-link tracking
    * Customers can now track engagement on every individual link within their emails. This update gives customers a much clearer view into what content or messaging is working so they can improve email performance over time.
    * Previously, when customers included multiple links within an email, they could only view total click counts across all links. Now, they can see which specific links get the most engagement and how links perform inside journeys. This helps them refine content and messaging strategies.
    * Multi-link tracking is automatically applied to most emails created in the Drag & Drop or HTML editor. Link-level performance metrics will also be available for emails sent using a template and emails in a Journey.
    * This feature is available to all customers with access to email.
</Update>

<Update label="May 23 2025">
  * View and optimize message performance with Template Analytics
    * OneSignal customers can quickly assess how individual templates are performing across all messages, without needing to download and stitch together separate reports.
    * When users click into a template, they now land on a detailed analytics view showing Delivered, Unique Opens, Unique Clicks, and Unsubscribes. They can track performance over time, filter by platform, explore delivery breakdowns like Failed or Capped, and review a list of messages that used the template.
    * Template analytics is especially useful for:
      * Marketers who test and iterate on message content
      * Developers who need visibility into transactional message delivery
      * High-volume senders seeking scalable insights
    * Transactional visibility is a key differentiator that sets us apart from Firebase and other open source solutions. Customers can now answer questions like “How many Account Confirmation emails did I send last week?” or “What was the click-through rate on my Password Reset messages?”
    * Important note: For templates created before April 17, 2025, enhanced metrics are only available for messages sent after that date. Customers can use the “Show historical data” toggle at the top of the page to see earlier performance data.
    * The feature is live and available by default. Reporting history varies by plan:
      * Free: 30 days
      * Growth: 90 days
      * Professional: 1 year
      * Enterprise: 2 years
</Update>

<Update label="May 16 2025">
  * Add users manually from the dashboard
    * You can now create new users directly from the *Users* tab in your OneSignal dashboard using a simple form. This update makes it easy to manually add a user with an email address, phone number, or both without needing an SDK, API call or CSV upload.
    * This is especially helpful for quickly testing campaigns or adding users who aren’t yet in your system.
</Update>

<Update label="May 14 2025">
  * Track SMS link performance directly in OneSignal
    * Customers can now track SMS link performance directly in OneSignal without needing third-party tools like Bit.ly or custom UTM parameters. This feature gives our customers a more streamlined, built-in way to measure engagement and optimize messages faster, removing friction and helping drive better results from their SMS efforts.
    * When composing an SMS message, customers simply click “Insert Trackable Link” and enter the full URL they want to send users to. OneSignal automatically shortens the link using the 1sgnl.co domain so it fits within SMS character limits and can be tracked.
    * All SMS users will have access to trackable links as part of their existing plan.
</Update>

<Update label="May 07 2025">
  * Simplify message organization with easier label management
    * Now you can add labels to your messages to help you organize and manage them.
    * See [Labels](/docs/en/labels) for more details.
</Update>

<Update label="May 01 2025">
  * Template analytics
    * You can now view and optimize template performance from a centralized reporting view. Click into any message template to view detailed performance data across every message a template is used in.
</Update>

<Update label="Apr 25 2025">
  * Improved CSV Importer
    * **Real-time validation:** Get instant feedback on formatting errors before upload.
    * **Smart column mapping:** Easily align your CSV headers with OneSignal fields.
    * **Email suppression support:** Add or manage your suppression list directly in the file.
    * **Upload history:** View the status of your past imports for up to 30 days.
    * **Helpful templates:** Start quickly with a pre-built CSV example.
</Update>

<Update label="Apr 21 2025">
  * Fine-tune your Live Activities with new API parameters
    * You can now add more control, reliability, and speed to your Live Activities with three new parameters in the OneSignal API: - ios\_relevance\_score: Helps determine which Live Activity displays most prominently on iOS. - include\_aliases: Allows you to target individual users directly rather than relying on segment-based delivery. - idempotency\_key: Prevents the creation of duplicate Live Activities when retrying start requests if not using the OneSignal SDK.
</Update>

<Update label="April 14 2025">
  * New integration - Databricks data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Databricks. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Databricks, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="April 08 2025">
  * View opt-out status by sender and support transactional messaging even with marketing opt-outs
    * You can now see SMS opt-out status by sender, giving you better visibility and control when managing marketing and transactional messages.
    * With this update, you can:
      * View subscription status by individual sender for any phone number
      * Continue sending transactional messages (like OTPs or alerts) even if a user has opted out of marketing
      * Maintain deliverability and avoid carrier filtering by respecting opt-out preferences
    * This is especially useful if you manage separate senders for promotional and transactional use cases.
    * To access this feature, go to **Consent Management > Advanced Opt-out Settings** and turn off the setting that globally unsubscribes a user when they reply with an opt-out keyword.
    * *Note: This option is only available to customers using advanced opt-out settings for SMS.*
</Update>

<Update label="March 19 2025">
  * Easily find and select the right templates with visual previews
    * Quickly identify and select your email and in-app message templates with the new updated card view.
    * Instead of relying on template names alone, you can now see clear visual previews, making it easier to choose the right template at a glance.
</Update>

<Update label="March 12 2025">
  * Create users in OneSignal via HubSpot workflows
    * Keep your users in sync across HubSpot and OneSignal! With this new workflow action, you can now create users in OneSignal whenever a HubSpot workflow trigger fires. This enables you to queue up personalization details (such as Tags) and plan engagement strategies before a user even interacts with your mobile platform. Additionally, you can trigger an SMS or email via HubSpot while simultaneously creating a user in OneSignal—ensuring seamless and immediate engagement.
    * [HubSpot Documentation](/docs/en/hubspot)
  * Push preview accuracy improvements
    * As operating systems update, they often introduce new changes in their push designs.
    * We've updated our previews so they match latest and greatest push notification designs across iOS (18), Android (15), Windows (11), macOS (Sequoia). This ensures you see what your users will see when testing in OneSignal.
  * PII Masking of Emails and Phone Numbers
    * Protect user privacy and reduce compliance risks by masking personally identifiable information (PII) such as emails and phone numbers. With PII masking, your team can work securely while still analyzing campaign performance and sharing insights across teams.
    * OneSignal automatically masks phone numbers and emails in the dashboard and any data exported directly from the platform. However, PII masking does not currently apply to data accessed via API requests, external IDs, or Tags.
</Update>

<Update label="March 07 2025">
  * Verify & Lookup Phone Numbers
    * Sends the user a one-time verification code to ensure the customer owns the phone #
    * Confirms the phone number entered by a user at onboarding is valid
</Update>

<Update label="February 28 2025">
  * Added New Integration - [BigQuery Data Export](/docs/en/bigquery)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to BigQuery. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in BigQuery, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
  * Channel subscriber counts have moved
    * The counts of subscribed counts for each channel have moved from the dashboard to the Subscriptions page in OneSignal. Now you will see the number of *Subscribed* subscriptions for each channel at the top of the Subscriptions page under Audience to get an overview of audience reach per channel in the context of your subscriptions.
    * If you still wish to view this information on the Dashboard, you can filter your Subscriptions trends chart by channel.
</Update>

<Update label="February 14 2025">
  * Improvements to Keywords
    * We've made a couple of improvements to our SMS keywords.
      * Segment by subscription status when sending a keyword to encourage converting your customers who are not yet subscribed into opting in to your SMS marketing messages
      * Setup an auto-responder for unrecognized keywords
</Update>

<Update label="February 12 2025">
  * New Engagement Analytics on the OneSignal Dashboard

    * Are you curious to learn more about how your end users engage with the messages you send from OneSignal? Head to your Dashboard to see the new Engagement Trends report.
    * With this report you will gain insight into how users engage with your messages across Push, Email, and SMS. Track click-through-rate, unsubscribes, and monitor trends over time to refine your messaging strategy and optimize communication frequency. This comprehensive report consolidates data from all message types (Dashboard, API, Journeys) for a clearer view of performance. Now available in your OneSignal dashboard!

    <Frame>
      <img alt="New Engagement Analytics on the OneSignal Dashboard" />
    </Frame>
</Update>

<Update label="January 29 2025">
  * Sort segments by Last edited, Created at and more
    * Finding and managing your segments just got easier!
    * You can now sort segments by Last edited, Created at and more.
      * This update is especially valuable for customers who:
        * Maintain numerous segments
        * Frequently update their segment configurations
        * Need to identify and clean up outdated segments
        * Want to quickly find recently modified segments
</Update>

<Update label="January 27 2025">
  * Email Senders (Multi-Domain Sending)
    * Create distinct senders for different types of communications:
      * Keep your marketing campaigns separate from crucial transactional emails
      * Maintain different brand voices for various product lines
      * Optimize sender reputation for each type of communication
      * [Email Senders](/docs/en/senders)
  * Improved In-app Message Analytics for Event Streams
    * We've added a new In-app Message Analytics for Event Streams.
</Update>

<Update label="January 21 2025">
  * Email Intelligent Delivery
    * We've added intelligent delivery to email.
    * Transform your email engagement with OneSignal's latest breakthrough: Intelligent Delivery. This powerful new feature automatically determines the optimal time to reach each individual user, maximizing your email campaign's impact.
    * Our algorithm continuously learns from:
      * User open patterns
      * Click-through behavior
      * Real human interactions (excluding bot activity)
</Update>

<Update label="January 16 2025">
  * Retirement of Automated Message for Free apps
    * Automated Messages are no longer supported and the feature has been retired in the free plan. Paid apps will continue to have access to this feature until further notice.
    * Active automated messages will remain live and continue functioning as expected. However, you can no longer create new automated messages, or reactivate paused automated messages. To build new automated sequences and enhance your campaigns, we recommend using [Journeys](/docs/en/journeys-overview).
</Update>

<Update label="January 15 2025">
  * Customize how your users re-enter split branches
    * Now you can customize how your users re-enter split branches. This feature is available for all Journeys.
    * [Journey Entry Triggers](/docs/en/journeys-actions)
  * Improving New Message Experience
    * We improved the new message experience by adding a library of templates (get inspiration for your next push, in-app, email, or SMS), or quickly start from a template you've made, or a previous message.
</Update>

<Update label="January 03 2025">
  * message.url - New Push Event Stream Property
    * `message.url` is now a supported property for push events. It enables the retrieval of the launch URL directly from your event stream payload.
</Update>

<Update label="December 24 2024">
  * Journeys Multi-split Branching
    * Now you can set up more personalized paths in your Journey. Create up to 20 branches to test channels, content, timing, ordering, and more. Assign different weights to each branch, or easily distribute audiences evenly across all branches. See how different paths perform against each other or against a control group.
</Update>

<Update label="December 20 2024">
  * WordPress Plugin v3
    * We've upgraded our Wordpress Web Push plugin to v3+. What's changed:
      * Upgrades the OneSignal Web SDK from version 15 to 16.
      * Setup more new prompts within the OneSignal dashboard, including the following. No custom code is required anymore to configure these.
        * Category Prompt
        * Email/Phone Slide Prompt
        * Custom Link Prompt.
      * When publishing a new post, check the "Send notification when post is published" box to send a push notification.
      * Choose which audience segment should receive notifications for each post.
      * Web Topics are included by default.
      * Send to mobile app subscribers, with an option to direct them to a different URL (Deep Link).
</Update>

<Update label="December 11 2024">
  * Improved Logs in Event Streams
    * We've improved the Event Streams feature to make troubleshooting simpler and faster. Now, you’ll find dedicated tabs for successful and failed events, making it easier to spot issues at a glance. Clear empty states show when there’s no data in either tab, and updated messaging ensures you know the logs display a sample of your data.
  * SMS Keywords
    * We've added keywords for SMS. Keyword engagement enables quick, two-way communication, enhancing personalization, accessibility, and user satisfaction. It drives conversions and higher engagement with your subscribers. Add a data tag to the keyword, and segment based on their preferences to send more targeted SMS.
  * Quickstart Segments

    * We are thrilled to launch three new segment templates designed to help you hit the ground running with proven strategies:
      * First-Time audience
      * Regional audience
      * Custom Audience based on tags
    * Our analysis of 6.3 billion message deliveries uncovered powerful insights. These templates are built to help you:
      * Create high-performing segments from day one.
      * Use proven filter combinations that drive higher engagement.

    <Frame>
      <img alt="Quickstart Segments" />
    </Frame>
</Update>

<Update label="December 02 2024">
  * Email Quickstart Templates
    * We've added a library of quickstart templates for email. Explore our library of professionally crafted email templates, designed to inspire your creativity and elevate your email campaigns. Use them as a starting point to create impactful messages that drive conversions and engage your audience effectively.
</Update>

<Update label="November 27 2024">
  * Scheduling Journeys
    * Now you can schedule Journeys to send at a specific time. This feature is available for all Journeys.
  * Settings Overview Page
    * Now you can access and manage all your settings in a centralized setting overview page. Platform-specific settings have been reorganized under their relevant channels for better clarity.
</Update>

<Update label="November 20 2024">
  * Bulk Archive and Delete Journeys

    * Now you can bulk archive or delete Journeys from the Journeys index. Select up to 20 Journeys, and then choose an action you'd like to take to clean up Journeys you're no longer using.

    <Frame>
      <img alt="Bulk Archive and Delete Journeys" />
    </Frame>
</Update>

<Update label="November 06 2024">
  * Improved Export for Global Outcomes
    * We've improved the export for Global Outcomes to include more data and make it easier to use in your reporting.
  * Preview allows you to preview the content of a message and can be very helpful when you have a message with personalization (i.e. Tags, dynamic content, custom data). With preview, you can preview content from a specific test user's perspective, or with example custom data.
  * Settings for Email & Side Navigation Updates
    * In the side navigation, you can now easily see your Push, SMS, and Email settings. What was once "Messaging" is now "Push" settings, and SMS and Email Settings will take you directly to your channel's settings.
    * For email, we've created a dedicated place to manage your email provider and senders. If you are a OneSignal mail user, you'll also be able to see your reputation and suppression lists here.
  * SMS Usage
    * We've added SMS Usage in the Usage page. We've also added a breakdown so you can see the message type, and a breakout by inbound and outbound. You may see an unknown country if a segment failed to send.
</Update>

<Update label="October 02 2024">
  * Add Notes on your Journeys
    * Now you can add notes to the steps of your Journeys to keep reminders and more effectively collaborate and share information with your team. This feature is available for all Journeys.
</Update>

<Update label="September 27 2024">
  * New Quickstart Journeys
    * We've added a new Quickstart Journeys to help you get started with Journeys. This feature is available for all Journeys.
  * SMS Text-to-Subscribe
    * It's now easier to set up double opt-in and text-to-subscribe phone number collection experiences for your customers!
</Update>

<Update label="September 12 2024">
  * Confirmed Click-Through-Rate (CCTR) metric

    * We have added a new metric to measure the CTR using confirmed receipt. Confirmed Click-Through-Rate (CCTR) is measured by (total clicks/confirmed delivered) \* 100%

    <Frame>
      <img alt="Confirmed Click-Through-Rate (CCTR) metric" />
    </Frame>
</Update>

<Update label="September 06 2024">
  * Export your Subscription Trends
    * Now you can export the data from your Subscription Trends report as a CSV. If you apply filters to the report, OneSignal will export based on the filters you've applied so that you can fine-tune the data that you use to evaluate your messaging audience.
</Update>

<Update label="August 05 2024">
  * Email Saved Rows
    * Saved Rows are reusable content blocks that help streamline email creation and management. Many companies, especially those that have a lot of templates, prefer to use saved rows in their emails for consistency and to save time. Saved Rows are easily attached to new emails so you don't have to create the same information from scratch each time. And when things change, you just have to update the saved row, and your updates will automatically sync across all campaigns that have that saved row attached.
    * Common use cases include:
      * headers (logo, slogan)
      * footers (company details, social media links, mailing addresses)
      * disclaimers
      * other elements that are used across multiple campaigns
    * You can now save Email Drag-and-Drop rows to use across many Campaigns or Templates. These re-suable **Saved Rows** make it easy to sync updates across many emails at once. Click on the **Rows** tab of a Drag-and-Drop email, to view your **Saved Rows**. To save your first row, click the save icon in the edit, in the top right corner of the row.
    * We recommend you set up all of your templates to use saved rows for your header and footer so that you need to update the branding or content; you only have to make those edits once.
</Update>

<Update label="July 30 2024">
  * Journeys now target anonymous users
    * Now, Journeys do not require External IDs to be set on subscriptions. Instead, Journeys will target your entire user base within OneSignal, including anonymous users. We recommend still configuring External IDs to identify individual users who have subscribed to multiple channels.
</Update>

<Update label="July 25 2024">
  * Have more visibility into SMS unsubscribes, resubscribes, and help keywords
    * We now make it easier to manage your Consent Keywords within Onesignal. Reach out to support if you'd like to update the default consent keywords and replies.
</Update>

<Update label="July 19 2024">
  * Email Reply-to field now supports custom properties
    * Now you can use [Message Personalization](/docs/en/message-personalization) within the `reply-to`field on an email. This allows you to direct message replies to the right inbox and can be helpful if you are sending from different brands or across different countries.
</Update>

<Update label="July 16 2024">
  * Push Failures and Unsubscribes in Audience Activity
    * Obtain a list of subscriptions that have faced errors - failures or unsubscribes, for a specific push notification in the push report page.
</Update>

<Update label="July 03 2024">
  * Integrations: OneSignal Message Events can be sent to Twilio Segment
    * Customers can now select and send message events from OneSignal to sync back to their Twilio Segment account, making the Segment integration bidirectional.
  * Use Audience Activity for Live Activities to get a list of recipients
    * Get a list of subscriptions that successfully or failed to receive a Live Activity on a Live Activity report page, which is accessible through the Delivery - Sent Index. This list can be exported as well.
</Update>

<Update label="June 06 2024">
  * In-app message audience activity
    * In the report page of an in-app message, you can now see which mobile subscriptions viewed (impression) or clicked on an in-app message. Audience activity is available for 30 days from the time the message is displayed
</Update>

<Update label="May 15 2024">
  * FCM Expired Tokens > Increased Android Unsubscribes
    * On May 15, 2024, Google's FCM service will start to expire stale push tokens for devices that have been inactive for more than 270 days. You may see a spike in Android unsubscribes when sending notifications due to this change. Don't panic! These are devices that have not been online in over 270 days and are part of Google's [Best practices for FCM registration token management](https://firebase.google.com/docs/cloud-messaging/manage-tokens). If the device does come back online and opens your app, OneSignal will automatically resubscribe them to push if they were previously subscribed already.
    * See [FCM Expired Token FAQ](/docs/en/fcm-expired-token-faq) for more details.
</Update>

<Update label="April 29 2024">
  * Configure more granular Frequency Capping rates for Push
    * Push notifications can now be capped at a rate of x notifications per any time frame (less than 1 week). Navigate to Settings > Messaging > Push Frequency Capping > Custom (in the time dropdown) to view these settings.
    * Read [Frequency Capping Documentation](/docs/en/frequency-capping) for more details.
</Update>

<Update label="April 11 2024">
  * Added Android Live Notifications
    * Android's Live Notifications deliver live, dynamic content in notifications to enhance user engagement and app interactivity. This is a feature similar to iOS's Live Activities feature (introduced with iOS 16), but uses its own set of tools and APIs that enable similar functionalities.
    * See [Android Live Notifications](/docs/en/android-live-notifications) for more details.
  * Major improvements to Android SDK
  * Push to start Live Activities
    * Live Activities can now be launched on a user's screen when the mobile app is in the background (app is not open). Live Activities can both be started and updated by a remote push notification.
    * [How to start a Live Activity with a remote push notification](/docs/en/live-activities)
</Update>

<Update label="April 01 2024">
  * Added Audience Activity reports for Journeys
    * We have added Audience Activity reports for Journeys so you can get a closer look at which subscriptions were sent messages during a Journey. To view this report, click into a message report on your Journey. [Learn more here](/docs/en/journeys-analytics#audience-activity).
</Update>

<Update label="March 18 2024">
  * Added a new Setup guide for Analytics
    * We have added a new Analytics Setup guide to our product documentation detailing how to track Confirmed Deliveries and set up Custom Outcomes with support from your development team.
</Update>

<Update label="March 12 2024">
  * Mobile SDK Updates
    * We recommend updating to the latest SDK versions listed below to benefit from critical bug fixes, stability improvements, and new features. These updates include key enhancements across all platforms, including iOS 5.1.3 and Android 5.1.6, which improve concurrency safety, crash resilience, and background thread handling. The updates also include important API adjustments like more accurate property handling in the `PushSubscriptionState`.
</Update>

<Update label="February 16 2024">
  * Journeys is now available on the Growth plan
    * Journeys is now available on the Growth plan. This means you can now create and manage Journeys with up to 100,000 users.
    * See [Journeys](/docs/en/journeys-overview) for more details.
</Update>

<Update label="February 12 2024">
  * Added Auto Warm Up
    * We have added a new feature that allows you to automatically warm up your app when a user opens it. This feature is available for all OneSignal customers.
    * See [Email Warm Up](/docs/en/email-warm-up) for more details.
</Update>

<Update label="February 02 2024">
  * Journeys has easier targeting based on user activity
    * We've added support for Segments with time-based rules (e.g., first session, last session, etc.) and also simplified targeting inactive users. Now you can target your inactive users by including a segment based on last session behavior.
  * Email: Schedule Sends Across Different Timezones
    * Email campaigns can now be scheduled to send across different timezones. This feature is available for all OneSignal customers.
</Update>

<Update label="January 30 2024">
  * Email now supports One Click Unsubscribe
    * Inbox Service Providers (ISP) like Gmail, Outlook, iOS Mail, and Yahoo! Mail, AOL, and Verison Mail require senders to provide a One Click Unsubscribe option. The unsubscribe button is rendered at the discretion of the ISP based on sending criteria, which may include a daily sending volume greater than 5,000 emails.
</Update>

<Update label="December 18 2023">
  * Filter your messages with labels
    * Now you can filter your messages with [labels](/docs/en/labels). This feature is available for all OneSignal customers.
  * CSV Importer can now update properties
    * CSV Importer for email now enables updates to user properties `language`, `country`, and `timezone_id`.
  * Send more personalized messages and multi-language emails
    * [Dynamic Content Documentation](/docs/en/dynamic-content)
</Update>

<Update label="December 14 2023">
  * All OneSignal apps now belong to an Organization
    * We have added a new feature that allows you to manage your OneSignal apps within an Organization. This feature is available for all OneSignal customers.
    * See [Apps, Orgs, and Accounts](/docs/en/apps-organizations)
  * Journeys now has better analytics
    * We've added a new Journeys Report. See [Journeys Analytics](/docs/en/journeys-analytics) for more details.
</Update>

<Update label="November 22 2023">
  * Removed Journey Notifications from Delivery Reports and the View Notifications endpoint
</Update>

<Update label="October 04 2023">
  * Added new integration - [Snowflake](/docs/en/snowflake)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Snowflake, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="September 27 2023">
  * You can now save and continue
    * Changed the default option for saving a message to save work without exiting the message.
</Update>

<Update label="September 13 2023">
  * Added the ability to adjust the default padding for IAM blocks
    * Learn more about [IAM blocks](/docs/en/design-your-in-app-message)
  * Added the ability to edit entry triggers and re-entry rules for live Journeys
    * Learn more about [Journey entry triggers](/docs/en/journeys-overview)
</Update>

<Update label="September 05 2023">
  * Added ability to create multi-language push messages by pasting your CSV
    * Learn more about [Multi-language messages](/docs/en/multi-language-messaging)
  * Added new "Editor" role permissions
    * Learn more about [Managing team members](/docs/en/manage-team-members)
  * Added enhanced Journey message stats and reports.
    * Learn more about [Journey message stats and reports](/docs/en/journeys-analytics)
</Update>

<Update label="September 01 2023">
  * Added a new feature to forward email templates to an app
    * Learn more at [Email Template Forwarding](/docs/en/email-template-forwarding)
  * Added FCM v1 API support for Android Push Notifications
    * Learn more about [Android Firebase credentials](/docs/en/android-firebase-credentials)
</Update>

<Update label="August 15 2022">
  * Android 13 changes
    * Android 13 introduces a runtime notification permission, meaning users must opt in to receive push notifications. Apps targeting Android 13 must explicitly prompt for permission at a time of their choosing, or the system will display the permission prompt automatically on first launch—often resulting in lower opt-in rates.
    * See [Android 13 Push Notification Developer Update Guide](/release-notes/android-13-push-notification-developer-update-guide) or our [Prompt for Push Permissions](/docs/en/prompt-for-push-permissions) guide for details.
</Update>


# SDK Releases
Source: https://documentation.onesignal.com/release-notes/sdk-releases

View the latest OneSignal SDK releases and updates.

## Mobile

<SdkReleasesIframe />

## Web

<SdkReleasesIframe />

## Server

<SdkReleasesIframe />

## Plugins

<SdkReleasesIframe />


# Server SDK reference
Source: https://documentation.onesignal.com/docs/en/server-sdk-reference

Install, configure, and use OneSignal server SDKs to send push notifications, emails, and SMS from your backend in Node.js, Python, Java, Go, PHP, Ruby, C#, and Rust.

All OneSignal server SDKs are generated from the same OpenAPI specification, so they share a consistent interface regardless of language. Each SDK wraps the [OneSignal REST API](/reference/create-message) and provides typed models for requests and responses.

## Available SDKs

| Language  | Package                                                                                            | Repository                                                  |
| --------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Node.js   | [@onesignal/node-onesignal](https://www.npmjs.com/package/@onesignal/node-onesignal)               | [GitHub](https://github.com/OneSignal/node-onesignal)       |
| Python    | [onesignal-python-api](https://pypi.org/project/onesignal-python-api/)                             | [GitHub](https://github.com/OneSignal/onesignal-python-api) |
| Java      | [onesignal-java-client](https://central.sonatype.com/artifact/com.onesignal/onesignal-java-client) | [GitHub](https://github.com/OneSignal/onesignal-java-api)   |
| Go        | [onesignal-go-api](https://pkg.go.dev/github.com/OneSignal/onesignal-go-api)                       | [GitHub](https://github.com/OneSignal/onesignal-go-api)     |
| PHP       | [onesignal/onesignal-php-api](https://packagist.org/packages/onesignal/onesignal-php-api)          | [GitHub](https://github.com/OneSignal/onesignal-php-api)    |
| Ruby      | [onesignal](https://rubygems.org/gems/onesignal)                                                   | [GitHub](https://github.com/OneSignal/onesignal-ruby-api)   |
| C# (.NET) | [OneSignalApi](https://www.nuget.org/packages/OneSignalApi)                                        | [GitHub](https://github.com/OneSignal/onesignal-dotnet-api) |
| Rust      | [onesignal-rust-api](https://crates.io/crates/onesignal-rust-api)                                  | [GitHub](https://github.com/OneSignal/onesignal-rust-api)   |

***

## Installation

<Note>
  Version numbers below are examples. Check the package registry for each SDK to install the latest version.
</Note>

<Tabs>
  <Tab title="Node.js">
    ```bash theme={null}
    npm install @onesignal/node-onesignal
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install onesignal-python-api
    ```
  </Tab>

  <Tab title="Java">
    **Maven**

    ```xml theme={null}
    <dependency>
      <groupId>com.onesignal</groupId>
      <artifactId>onesignal-java-client</artifactId>
      <version>5.3.0</version>
    </dependency>
    ```

    **Gradle**

    ```groovy theme={null}
    implementation "com.onesignal:onesignal-java-client:5.3.0"
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/OneSignal/onesignal-go-api/v5
    ```
  </Tab>

  <Tab title="PHP">
    Add to `composer.json`:

    ```json theme={null}
    {
      "require": {
        "onesignal/onesignal-php-api": "^5.3"
      }
    }
    ```

    Then run `composer update`.
  </Tab>

  <Tab title="Ruby">
    Add to your `Gemfile`:

    ```ruby theme={null}
    gem 'onesignal', '~> 5.3'
    ```

    Then run `bundle install`.
  </Tab>

  <Tab title="C# (.NET)">
    ```bash theme={null}
    dotnet add package OneSignalApi
    ```
  </Tab>

  <Tab title="Rust">
    Add to `Cargo.toml` under `[dependencies]`:

    ```toml theme={null}
    onesignal-rust-api = "5.3.0"
    ```
  </Tab>
</Tabs>

***

## Configuration

Every SDK requires authentication via API keys. Two key types are available:

* **REST API Key** — required for most endpoints (sending notifications, managing users, etc.). Found in your app's **Settings > Keys & IDs**.
* **Organization API Key** — only required for organization-level endpoints like creating or listing apps. Found in **Organization Settings**.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const OneSignal = require('@onesignal/node-onesignal');

    const configuration = OneSignal.createConfiguration({
      restApiKey: 'YOUR_REST_API_KEY',
      organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',
    });

    const client = new OneSignal.DefaultApi(configuration);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import onesignal
    from onesignal.api import default_api

    configuration = onesignal.Configuration(
        rest_api_key='YOUR_REST_API_KEY',
        organization_api_key='YOUR_ORGANIZATION_API_KEY',
    )

    with onesignal.ApiClient(configuration) as api_client:
        client = default_api.DefaultApi(api_client)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.onesignal.client.ApiClient;
    import com.onesignal.client.Configuration;
    import com.onesignal.client.auth.HttpBearerAuth;
    import com.onesignal.client.api.DefaultApi;

    ApiClient defaultClient = Configuration.getDefaultApiClient();

    HttpBearerAuth restApiAuth = (HttpBearerAuth) defaultClient
        .getAuthentication("rest_api_key");
    restApiAuth.setBearerToken("YOUR_REST_API_KEY");

    HttpBearerAuth orgApiAuth = (HttpBearerAuth) defaultClient
        .getAuthentication("organization_api_key");
    orgApiAuth.setBearerToken("YOUR_ORGANIZATION_API_KEY");

    DefaultApi client = new DefaultApi(defaultClient);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import onesignal "github.com/OneSignal/onesignal-go-api"

    restAuth := context.WithValue(
        context.Background(),
        onesignal.RestApiKey,
        "YOUR_REST_API_KEY",
    )

    orgAuth := context.WithValue(
        restAuth,
        onesignal.OrganizationApiKey,
        "YOUR_ORGANIZATION_API_KEY",
    )

    apiClient := onesignal.NewAPIClient(onesignal.NewConfiguration())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use onesignal\client\api\DefaultApi;
    use onesignal\client\Configuration;
    use GuzzleHttp;

    $config = Configuration::getDefaultConfiguration()
        ->setRestApiKeyToken('YOUR_REST_API_KEY')
        ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');

    $client = new DefaultApi(
        new GuzzleHttp\Client(),
        $config
    );
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'onesignal'

    OneSignal.configure do |config|
      config.rest_api_key = 'YOUR_REST_API_KEY'
      config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'
    end

    client = OneSignal::DefaultApi.new
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    using OneSignalApi.Api;
    using OneSignalApi.Client;

    var config = new Configuration();
    config.BasePath = "https://api.onesignal.com";
    config.AccessToken = "YOUR_REST_API_KEY";

    var client = new DefaultApi(config);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use onesignal::apis::configuration::Configuration;

    fn create_configuration() -> Configuration {
        let mut config = Configuration::new();
        config.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
        config.organization_api_key_token = Some("YOUR_ORGANIZATION_API_KEY".to_string());
        config
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Store your API keys in environment variables or a secrets manager. Never commit them to source control.
</Warning>

***

## Send a push notification

Send push notifications to web and mobile [Subscriptions](./subscriptions) by targeting a segment. These examples show the happy path — add error handling (try/catch, error callbacks) for production use.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.contents = { en: 'Hello from OneSignal!' };
    notification.headings = { en: 'Push Notification' };
    notification.included_segments = ['Subscribed Users'];

    const response = await client.createNotification(notification);
    console.log('Notification ID:', response.id);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        contents=onesignal.StringMap(en='Hello from OneSignal!'),
        headings=onesignal.StringMap(en='Push Notification'),
        included_segments=['Subscribed Users'],
    )

    response = client.create_notification(notification)
    print('Notification ID:', response.id)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.onesignal.client.model.Notification;
    import com.onesignal.client.model.StringMap;

    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");

    StringMap contents = new StringMap();
    contents.en("Hello from OneSignal!");
    notification.setContents(contents);

    StringMap headings = new StringMap();
    headings.en("Push Notification");
    notification.setHeadings(headings);

    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));

    var response = client.createNotification(notification);
    System.out.println("Notification ID: " + response.getId());
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Hello from OneSignal!")})
    notification.SetHeadings(onesignal.StringMap{En: onesignal.PtrString("Push Notification")})
    notification.SetIncludedSegments([]string{"Subscribed Users"})

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()

    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Notification ID:", response.GetId())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use onesignal\client\model\Notification;
    use onesignal\client\model\StringMap;

    $content = new StringMap();
    $content->setEn('Hello from OneSignal!');

    $headings = new StringMap();
    $headings->setEn('Push Notification');

    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setContents($content);
    $notification->setHeadings($headings);
    $notification->setIncludedSegments(['Subscribed Users']);

    $response = $client->createNotification($notification);
    echo 'Notification ID: ' . $response->getId();
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      contents: { en: 'Hello from OneSignal!' },
      headings: { en: 'Push Notification' },
      included_segments: ['Subscribed Users']
    })

    response = client.create_notification(notification)
    puts "Notification ID: #{response.id}"
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    using OneSignalApi.Model;

    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        Contents = new StringMap(en: "Hello from OneSignal!"),
        Headings = new StringMap(en: "Push Notification"),
        IncludedSegments = new List<string> { "Subscribed Users" }
    };

    var response = client.CreateNotification(notification);
    Console.WriteLine("Notification ID: " + response.Id);
    ```

    Note: .NET SDK does not normalize newline characters automatically. If your content contains `\r\n` normalize it before passing to `Contents`:

    ```csharp theme={null}
    var normalizedContent = yourContent
       .Replace("\\r\\n", "\n")
       .Replace("\\n", "\n")
       .Replace("\r\n", "\n")
       .Replace("\r", "\n");
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use onesignal::apis::default_api;
    use onesignal::models::{Notification, StringMap};

    let mut contents = StringMap::new();
    contents.en = Some("Hello from OneSignal!".to_string());

    let mut headings = StringMap::new();
    headings.en = Some("Push Notification".to_string());

    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.contents = Some(Box::new(contents));
    notification.headings = Some(Box::new(headings));
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);

    let config = create_configuration();
    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Send an email

Send emails to [Subscriptions](./subscriptions) with the `email` channel.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.email_subject = 'Important Update';
    notification.email_body = '<h1>Hello!</h1><p>This is an HTML email.</p>';
    notification.included_segments = ['Subscribed Users'];
    notification.channel_for_external_user_ids = 'email';

    const response = await client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        email_subject='Important Update',
        email_body='<h1>Hello!</h1><p>This is an HTML email.</p>',
        included_segments=['Subscribed Users'],
        channel_for_external_user_ids='email',
    )

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");
    notification.setEmailSubject("Important Update");
    notification.setEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>");
    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
    notification.setChannelForExternalUserIds("email");

    var response = client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetEmailSubject("Important Update")
    notification.SetEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>")
    notification.SetIncludedSegments([]string{"Subscribed Users"})
    notification.SetChannelForExternalUserIds("email")

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setEmailSubject('Important Update');
    $notification->setEmailBody('<h1>Hello!</h1><p>This is an HTML email.</p>');
    $notification->setIncludedSegments(['Subscribed Users']);
    $notification->setChannelForExternalUserIds('email');

    $response = $client->createNotification($notification);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      email_subject: 'Important Update',
      email_body: '<h1>Hello!</h1><p>This is an HTML email.</p>',
      included_segments: ['Subscribed Users'],
      channel_for_external_user_ids: 'email'
    })

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        EmailSubject = "Important Update",
        EmailBody = "<h1>Hello!</h1><p>This is an HTML email.</p>",
        IncludedSegments = new List<string> { "Subscribed Users" },
        ChannelForExternalUserIds = "email"
    };

    var response = client.CreateNotification(notification);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.email_subject = Some("Important Update".to_string());
    notification.email_body = Some("<h1>Hello!</h1><p>This is an HTML email.</p>".to_string());
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
    notification.channel_for_external_user_ids = Some("email".to_string());

    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Send an SMS

Send SMS text messages to [Subscriptions](./subscriptions) with the `sms` channel.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.contents = { en: 'Your SMS message content here' };
    notification.included_segments = ['Subscribed Users'];
    notification.channel_for_external_user_ids = 'sms';
    notification.sms_from = '+15551234567';

    const response = await client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        contents=onesignal.StringMap(en='Your SMS message content here'),
        included_segments=['Subscribed Users'],
        channel_for_external_user_ids='sms',
        sms_from='+15551234567',
    )

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    StringMap contents = new StringMap();
    contents.en("Your SMS message content here");

    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");
    notification.setContents(contents);
    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
    notification.setChannelForExternalUserIds("sms");
    notification.setSmsFrom("+15551234567");

    var response = client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Your SMS message content here")})
    notification.SetIncludedSegments([]string{"Subscribed Users"})
    notification.SetChannelForExternalUserIds("sms")
    notification.SetSmsFrom("+15551234567")

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $content = new StringMap();
    $content->setEn('Your SMS message content here');

    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setContents($content);
    $notification->setIncludedSegments(['Subscribed Users']);
    $notification->setChannelForExternalUserIds('sms');
    $notification->setSmsFrom('+15551234567');

    $response = $client->createNotification($notification);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      contents: { en: 'Your SMS message content here' },
      included_segments: ['Subscribed Users'],
      channel_for_external_user_ids: 'sms',
      sms_from: '+15551234567'
    })

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        Contents = new StringMap(en: "Your SMS message content here"),
        IncludedSegments = new List<string> { "Subscribed Users" },
        ChannelForExternalUserIds = "sms",
        SmsFrom = "+15551234567"
    };

    var response = client.CreateNotification(notification);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let mut contents = StringMap::new();
    contents.en = Some("Your SMS message content here".to_string());

    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.contents = Some(Box::new(contents));
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
    notification.channel_for_external_user_ids = Some("sms".to_string());
    notification.sms_from = Some("+15551234567".to_string());

    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Full API reference

Each server SDK supports the same set of API endpoints. Refer to your SDK's API documentation for the complete method list, including users, subscriptions, segments, templates, and more.

| SDK       | API reference                                                                                     |
| --------- | ------------------------------------------------------------------------------------------------- |
| Node.js   | [DefaultApi.md](https://github.com/OneSignal/node-onesignal/blob/main/DefaultApi.md)              |
| Python    | [DefaultApi.md](https://github.com/OneSignal/onesignal-python-api/blob/main/docs/DefaultApi.md)   |
| Java      | [DefaultApi.md](https://github.com/OneSignal/onesignal-java-api/blob/main/docs/DefaultApi.md)     |
| Go        | [DefaultApi.md](https://github.com/OneSignal/onesignal-go-api/blob/main/docs/DefaultApi.md)       |
| PHP       | [DefaultApi.md](https://github.com/OneSignal/onesignal-php-api/blob/main/docs/Api/DefaultApi.md)  |
| Ruby      | [DefaultApi.md](https://github.com/OneSignal/onesignal-ruby-api/blob/main/docs/DefaultApi.md)     |
| C# (.NET) | [DefaultApi.md](https://github.com/OneSignal/onesignal-dotnet-api/blob/main/docs/DefaultApi.md)   |
| Rust      | [default\_api docs](https://github.com/OneSignal/onesignal-rust-api/blob/main/docs/DefaultApi.md) |

For the underlying REST API, see the [complete API reference](/reference/create-message).

***

## FAQ

### Which server SDK should I choose?

Use the SDK that matches your backend language. All server SDKs are generated from the same OpenAPI specification and support the same endpoints, so functionality is identical across languages.

### What is the difference between the REST API Key and Organization API Key?

The **REST API Key** is scoped to a single app and is required for most operations like sending notifications and managing users. The **Organization API Key** is scoped to your organization and is only needed for creating or listing apps. Most integrations only need the REST API Key.

### Can I use the REST API directly instead of an SDK?

Yes. The server SDKs are convenience wrappers around the [OneSignal REST API](/reference/create-message). You can call the API directly using any HTTP client with the `key` authentication scheme (`Authorization: key YOUR_REST_API_KEY`).

### Are these SDKs auto-generated?

Yes. All server SDKs are generated from the OneSignal OpenAPI specification using [OpenAPI Generator](https://openapi-generator.tech). This ensures consistent API coverage across all languages.

***

## Related pages

<Columns>
  <Card title="REST API overview" icon="code" href="/reference/rest-api-overview">
    Endpoints, authentication, rate limits, and request/response formats.
  </Card>

  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    Find your App ID, REST API key, and Organization API key.
  </Card>

  <Card title="Transactional messages" icon="paper-plane" href="./transactional-messages">
    Send OTPs, receipts, and time-sensitive alerts via API with personalized data.
  </Card>

  <Card title="Identity verification" icon="shield-halved" href="./identity-verification">
    Secure your integration with server-generated JWTs to prevent User impersonation.
  </Card>
</Columns>


# Add a player
Source: https://documentation.onesignal.com/reference/add-a-device

POST `https://onesignal.com/api/v1/players`

Register a new Subscription (aka player) to one of your OneSignal apps.

<Warning>
  This is a Legacy API. Use [Create User](/reference/create-user) or [Create Subscription](/reference/create-subscription) instead.
</Warning>

***

## Headers

| Header          | Value                     | Required | Description                      |
| --------------- | ------------------------- | -------- | -------------------------------- |
| `Content-Type`  | `application/json`        | Yes      | The content type of the request. |
| `Authorization` | `Basic YOUR_REST_API_KEY` | Yes      | Your OneSignal REST API key.     |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                                |
| -------------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                                     |
| `device_type`        | integer | Yes      | Device platform: 0 = iOS, 1 = Android, 2 = Amazon, 3 = Windows Phone, etc. |
| `identifier`         | string  | No       | Push token, email address, or phone number.                                |
| `language`           | string  | No       | Language code (e.g. "en").                                                 |
| `timezone`           | integer | No       | Time zone offset in seconds.                                               |
| `game_version`       | string  | No       | Version of your app.                                                       |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                                         |
| `device_os`          | string  | No       | Operating system version (e.g., "13.3").                                   |
| `ad_id`              | string  | No       | Advertising ID.                                                            |
| `sdk`                | string  | No       | OneSignal SDK version (e.g., "050201" for 5.2.1).                          |
| `session_count`      | integer | No       | Number of times the user has used the app.                                 |
| `tags`               | object  | No       | Custom tags as key-value pairs.                                            |
| `external_user_id`   | string  | No       | Your system's user ID for this device.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc.                 |

***

## Example Request

```json theme={null}
POST /api/v1/players HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "device_type": 1,
  "identifier": "abcdef123456",
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_model": "Pixel 4",
  "device_os": "12",
  "ad_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sdk": "050401",
  "session_count": 5,
  "tags": {
    "user_type": "free",
    "level": "10"
  },
  "external_user_id": "user123",
  "notification_types": 1
}
```

***

## Response

```json theme={null}
{
  "id": "Subscription_id_string"
}
```

## Errors

* 400 Bad Request – Invalid parameters or missing required fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Not allowed for your account type or plan.


# Cancel message
Source: https://documentation.onesignal.com/reference/cancel-message

DELETE /notifications/{message_id}?app_id={app_id}
Stop a scheduled or currently outgoing message.

## Overview

The Cancel message API can be used to stop scheduled messages from being sent. It does not delete or remove the message from the app. If a message is in the process of sending, then canceling it may not fully prevent all targeted users from receiving it.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users, scheduling the message in the future with `send_after`. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and use this API to cancel sending the message to the user if not needed anymore.

If you need a way to remove a notification already sent to a user, see [Remove notifications & TTL](/docs/en/push).

***


# Copy template to another app
Source: https://documentation.onesignal.com/reference/copy-template-to-another-app

POST /templates/{template_id}/copy_to_app?app_id={app_id}
Create a duplicate of a template in another app. The new template will be completely separate from the original (including having a new template_id) but will be created with all the same content.

## Overview

This API allows you to copy a template from one app (`app_id`) to another (`target_app_id`). The duplicated template will have the same content as the original, but a new unique `template_id`.

<Note>
  If you are trying to copy an email template, we also have an [Email Template Forwarding](/docs/en/email-template-forwarding) feature that does not require an API call.

  Both options support HTML and Drag & Drop email templates.
</Note>

***

## Requirements

* **Organization Membership:** Both the `app_id` and `target_app_id` must belong to the same [Organization](/docs/en/apps-organizations).
* **Authorization Required:** You must use your [Organization API key](/docs/en/keys-and-ids#organization-api-key), not an app-level REST API key.
* **Permissions Note:** Your user must have admin-level access to both the source and target apps. If not, the request will fail with a "permission denied" error.

***

## Parameters

* `template_id` (path param): UUID of the template to be copied.
* `app_id` (query param): ID of the app where the original template exists.
* `target_app_id` (body param): ID of the app where the template will be duplicated.

***

## How to Use

### 1. Locate the Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

### 2. Get App IDs

Refer to [Keys & IDs](/docs/en/keys-and-ids) to find your `app_id` and `target_app_id`.

***

## Response

The response will include:

* The new `template_id` for the copied template
* Confirmation of successful creation
* Any warnings if applicable (e.g., limited fields copied)

***


# Create or update alias
Source: https://documentation.onesignal.com/reference/create-alias

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Create or update one or more user aliases when you already know an existing alias. This API performs an upsert on the user’s identity object—either adding new aliases or updating existing ones.

## Overview

Use this API to manage user aliases by providing one known alias (such as `external_id`, `onesignal_id`, or a custom alias) and specifying additional aliases to add or update.

This endpoint focuses solely on the `identity` object. If you need to fully create a user with subscriptions and properties, use the [Create user](/reference/create-user) API instead.

<Note>
  * If an alias with the same `alias_label` already exists for the user, it will be updated. If it doesn’t exist, a new alias will be created.
  * Want to use a subscription instead of an alias to identify the user? Use [Create alias (by subscription)](/reference/create-alias-by-subscription).
</Note>

See also:

* [Users](/docs/en/users) – for details on OneSignal ID and External ID
* [Aliases](/docs/en/aliases) – for setting and managing custom aliases
* [Delete alias](/reference/delete-alias) – for removing aliases

***

## How to use this API

To identify the user:

* Use `alias_label` for the type of alias you know (e.g., `external_id`, `onesignal_id`, or a custom alias)
* Use `alias_id` for the value of that alias

<Note>
  We strongly recommend setting the `external_id` as your primary user identifier. This can be done through our frontend SDK's login method when a user signs in to your app or website. It helps OneSignal associate the user's push, email, and SMS subscriptions to a unified user identity.
</Note>

Changes to the identity object take effect immediately upon request.

Alias keys (`alias_label`) and values (`alias_id`) are each limited to **128 characters**. A user can have up to **10 custom aliases** total.

***


# Create alias (by subscription)
Source: https://documentation.onesignal.com/reference/create-alias-by-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Create or update an alias for a user using a known subscription ID.

Create or update an alias for a user using a known subscription ID.

# Overview

Use this API to add or update aliases associated with a user when you only know at least one subscription ID. This API is handy for scenarios where the user's identity is unknown, but a subscription is available.

To remove an alias, see [Delete alias](/reference/delete-alias) API.

***

# How to use this API

You must know the `subscription_id` of the subscription that belongs to the user in which you want to update. Subscription IDs are UUIDs generated by OneSignal and cannot change. See [Subscriptions](/docs/en/subscriptions) for details.

This endpoint performs an upsert—if the user already has an alias with the specified alias label, it gets updated; otherwise, a new alias will be created.

The request body must include an identity object containing one or more aliases to be created or updated.

The OneSignal ID is read-only and used only for fetching. See [Users](/docs/en/users) for details.

Aliases are updated immediately upon request.

***


# Create an app
Source: https://documentation.onesignal.com/reference/create-an-app

POST /apps
Programmatically create a new OneSignal app via the REST API. This guide explains required fields, supported platform configurations (Web, Android, iOS), and how to properly authenticate using your Organization API key.

## Overview

Use this API to programmatically create a new OneSignal app. This is useful for automating app setup, particularly when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need to Base64 encode your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns):

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates):

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Create API key
Source: https://documentation.onesignal.com/reference/create-api-key

POST /apps/{app_id}/auth/tokens
Use the OneSignal API to create a new Rich Authentication Token (App API Key) for a specific app. This guide explains how to authenticate with the Organization API key and configure optional IP allowlists using CIDR notation.

## Overview

Use this API to create a new **App API Key** (also called a **Rich Authentication Token**) for a specific OneSignal app. These keys are used to authenticate API requests at the app level and offer enhanced security features, including optional IP allowlisting.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

### IP allowlisting

By default, the API key will not be restricted to any specific IP addresses. To enable IP allowlisting, you need to set the `ip_allowlist_mode` parameter to `explicit` and provide a list of allowed IP addresses in the `ip_allowlist` parameter.

If you want to set the explicit range of IPs that can use this API key, add them by setting `ip_allowlist_mode` to `explicit` and in `ip_allowlist` add the IPs in CIDRs notation as an array of string values.

***


# Create custom events
Source: https://documentation.onesignal.com/reference/create-custom-events

POST /apps/{app_id}/custom_events
The Custom Events API allows you to record user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones.

## Overview

The Custom Events API allows you to track user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones. See [Custom events](/docs/en/custom-events) for more information.

### Use Cases

Custom events can be used to:

* Enter users into [Journeys](/docs/en/journeys-settings)
* Trigger Journey [Wait Until](/docs/en/journeys-actions) nodes

### Error handling

If individual events can't be processed, an `errors` key will be returned in the response (with HTTP status 202) containing information about each failing event. The most common event-specific error is a failure to find a user associated with the External ID or OneSignal ID in the event.

If you'd like to retry sending events in the case of a failure, you only need to re-send the events for which errors were returned -- events that don't have an error associated with them are still processed. However, if a 5xx HTTP response is returned, you must retry the entire batch of events.

In either case, if you are implementing retry, make sure to also pass an [`idempotency_key`](/reference/idempotent-notification-requests).

### Duplicate events

If you implement retry behavior for your custom event delivery, please provide the [`idempotency_key`](/reference/idempotent-notification-requests) field. Each unique event should get its own unique UUID, and when retrying delivery for events, the same UUID must be provided. Duplicate events with the same `idempotency_key` will be ignored on a best-effort basis within a 4-hour period. This allows you to avoid erroneously triggering Journeys multiple times or incurring charges for storing unnecessary duplicate events.

***


# Sending messages with the OneSignal API
Source: https://documentation.onesignal.com/reference/create-message

Send push notifications, emails, SMS, and Live Activities with the OneSignal API. Covers audience targeting, message composition, scheduling, and response handling.

## Overview

This guide walks you through sending messages with the OneSignal API — from choosing a target audience to composing content, scheduling delivery, and validating responses. Each section covers channel-specific options and performance guidance.

### Prerequisites

1. Complete [Channel Setup](/docs/en/channel-setup) for the channels you plan to use: push, email, SMS, Live Activities.
2. Start accumulating [Subscriptions](/docs/en/subscriptions) for your users.
3. Have your REST API Key and App ID ready. See [Keys and IDs](/docs/en/keys-and-ids).

***

## Choose your target audience

You can target users with **one of the following methods per request**:

* **Aliases**: Specific users via unique IDs, emails, or phone numbers.
* **Segments**: Groups based on predefined behaviors or attributes.
* **Filters**: Custom rules using tags, location, activity, and more.

<Warning>
  Only one targeting method is allowed per message. For example, you cannot mix aliases and filters.
</Warning>

You can also target specific platforms (for example, `isAndroid`, `isIos`, `isAnyWeb`) when sending push notifications. By default, all push platforms are enabled.

### Aliases, emails, phone numbers

Target specific users or lists of users (up to 20,000 entries per request). This method is best for [Transactional Messages](/docs/en/transactional-messages).

<Accordion title="Aliases, emails, and phone numbers targeting parameters">
  <ParamField type="object">
    Target up to 20,000 users by their `external_id`, `onesignal_id`, or a custom alias. Combine with `target_channel` to select the delivery channel.

    ```json theme={null}
    {
      "include_aliases": {
        "external_id": [
          "user1",
          "user2",
          "user3"
        ]
      },
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="string">
    The targeted delivery channel. Required when using `include_aliases` or `included_segments` and sending SMS/RCS. Accepts `"push"`, `"email"`, or `"sms"`. The `"sms"` value covers both SMS and RCS — RCS messages are delivered through the SMS channel.

    ```json theme={null}
    {
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="array">
    Target users' specific [Subscriptions](/docs/en/subscriptions) by ID. Max 20,000 `subscription_id` per request.

    ```json theme={null}
    {
      "include_subscription_ids": [
        "1dd608f2-c6a1-11e3-851d-000c2940e62c"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send to specific email addresses (max 20,000 per request). Can only be used when sending [email](/reference/email). If the email address does not exist within the OneSignal App, a new email subscription is created.

    ```json theme={null}
    {
      "email_to": [
        "user1@example.com",
        "user2@example.com"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send SMS/MMS/RCS to phone numbers in [E.164 format](/docs/en/sms-setup#what-is-e164-format) (max 20,000 per request). Can only be used when sending [SMS/MMS/RCS](/reference/sms). If the phone number does not exist within the OneSignal App, a new SMS subscription is created.

    ```json theme={null}
    {
      "include_phone_numbers": [
        "+19999999999"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Segments

Target users in existing [segments](/docs/en/segmentation). Users in multiple segments only receive the message once.

<Accordion title="Segments targeting parameters">
  <ParamField type="array">
    Target predefined [segments](/docs/en/segmentation). Users who are in multiple segments only receive the message once. Combine with `excluded_segments` to exclude users from specific segments. When sending SMS/RCS, set `target_channel` to `"sms"` (or use the legacy `isSms=true` field).

    ```json theme={null}
    {
      "included_segments": [
        "Active Users",
        "Inactive Users"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Exclude users in these [segments](/docs/en/segmentation) even if they're in `included_segments`.

    ```json theme={null}
    {
      "included_segments": [
        "Subscribed Users"
      ],
      "excluded_segments": [
        "Inactive Users"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Filters

Build real-time audiences with `AND`/`OR` logic without creating segments first.

You can include up to **200 total entries per request**. This includes filter rows (for example, each `field`) and logical operators like `{"operator": "OR"}`.

<Accordion title="Filters targeting parameter details">
  <Info>
    **Performance guidance:**

    * **Fast:** Tag filters using `"="` or `"exists"`, and filters on `last_session`, `session_count`, or `country`.
    * **Slower:** Negation filters (`"!="`, `"not_exists"`) — especially with users who have many tags. Contact support to request indexing optimizations.
    * **Slow by default:** Numeric comparisons (`">"`, `"<"`) on tags or custom properties. Indexing may be available on request.
    * **Mixed performance:** Combining tag filters with other fields may increase computation time.
  </Info>

  <ParamField type="string">
    * Implicit `AND` logic between filters. Use `"operator": "OR"` to start a new branch.
    * `OR` filters are mutually exclusive. Recipients only need to satisfy one condition.
    * Allowed values: `"AND"`, `"OR"`.

    <CodeGroup>
      ```json AND example theme={null}
      // Users must satisfy both filters to be included.
      // Notice the AND operator is not required

      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      // The same example using the AND operator. This is not required.
      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "AND"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      ```

      ```json OR example theme={null}
      // Users can satisfy either filter to be included.

      "filters": [
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "tag", "key": "level", "relation": "=", "value": "20"}
      ]
      ```

      ```json Combinations theme={null}
      // In this example, users must either have:
      // The specified session_count AND tag requirement
      // Or it will be all records where last_session is satisfied
      {
        "name": "2 filters or 1",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"}
        ]
      }

      // Similar to the first example, this shows how to require a specific field
      // across other filters

      {
        "name": "3 filters, 1 required across all",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
        ]
      }

      // Example of 3 user groups with 2 requirements
      // (group_1 OR group_2 OR group_3) AND (requirement_1 OR requirement_2)

      {
        "name": "3 groups with 2 requirements",
        "filters": [
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"}
        ]
      }
      ```
    </CodeGroup>
  </ParamField>

  <ParamField type="object">
    ### `tag`

    Target based on custom user [Tags](/docs/en/add-user-data-tags).

    <Warning>
      Do not use tags for targeting individual users like a "user id".
      Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
    </Warning>

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
      * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
    * `key` = Tag key to compare.
    * `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

    ```json theme={null}
    "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "OR"},
      {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
    ]
    ```

    ### `country`

    Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "country", "relation": "=", "value": "US"},
        {"operator": "OR"},
        {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
      ]
      ```

    ### `last_session`

    Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "last_session", "relation": ">","hours_ago": "10"}
      ]
      ```

    ### `first_session`

    Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "first_session", "relation": "<","hours_ago": "24"}
      ]
      ```

    ### `session_count`

    Total number of sessions by the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="` or `"!="`
    * `value` = number of sessions. Example: `"1"`

      ```json theme={null}
      "filters": [
        {"field": "session_count", "relation": ">","value": "5"}
      ]
      ```

    ### `session_time`

    Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

    * `relation` = `">"` or `"<"`
    * `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

      ```json theme={null}
      "filters": [
        {"field": "session_time", "relation": ">","value": "86400"}
      ]
      ```

    ### `language`

    [User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = 2 character language code. Example: `"en"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "language", "relation": "=","value": "en"},
        {"operator": "OR"},
        {"field": "language", "relation": "in_array","value": "es,fr,de"}
      ]
      ```

    ### `app_version`

    App version set on the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = app version. Example: `"1.0.0"`
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "app_version", "relation": "=","value": "1.0.1"},
        {"operator": "OR"},
        {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
      ]
      ```

    ### `location`

    Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

    * `radius` = in meters
    * `lat` = latitude
    * `long` = longitude

      ```json theme={null}
      "filters": [
        {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
      ]
      ```
  </ParamField>
</Accordion>

***

## Craft your message

Each channel has its own set of fields. At a minimum, you need the following to send a displayable message:

* **Push and SMS** use `contents`
* **Email** uses `email_subject` and `email_body`
* Or reuse `template_id` if you created [templates](/docs/en/templates).

<CodeGroup>
  ```json Push and SMS theme={null}
  // Message request body
  {
    "contents": {
      "en": "Hello, world",
      "es": "Hola Mundo",
      "fr": "Bonjour le monde",
      "zh-Hans": "你好世界"
    }
  }
  ```

  ```json Email theme={null}
  // Message request body
  {
    "email_subject": "Hello, world",
    "email_body": "<html><body><h1>Hello, world</h1></body></html>"
  }
  ```
</CodeGroup>

For advanced customization—like adding images, buttons, sounds, or tracking—see the channel-specific options below.

### Push notification options

Below are the most common parameters for push notifications. For the full list of options, see the [Push notification reference](/reference/push-notification).

<Accordion title="Push notification options">
  #### Content and text

  * [`contents`](/reference/push-notification#body-contents) – Main message body.
  * [`headings`](/reference/push-notification#body-headings) – Title of the notification.
  * [`subtitle`](/reference/push-notification#body-subtitle) – Secondary line of text.
  * [`template_id`](/reference/push-notification#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Appearance

  * [`ios_attachments`](/reference/push-notification#body-ios-attachments) – Images/video/media.
  * [`big_picture`](/reference/push-notification#body-big-picture) – Large image (Android).
  * [`chrome_web_image`](/reference/push-notification#body-chrome-web-image) – Large image (Chrome).
  * [`small_icon`](/reference/push-notification#body-small-icon)
  * [`large_icon`](/reference/push-notification#body-large-icon)
  * [`buttons`](/reference/push-notification#body-buttons) – Action buttons.

  #### Delivery and priority

  * [`android_channel_id`](/reference/push-notification#body-android-channel-id)
  * [`priority`](/reference/push-notification#body-priority) – Delivery urgency.
  * [`ios_interruption_level`](/reference/push-notification#body-ios-interruption-level)
  * [`collapse_id`](/reference/push-notification#body-collapse-id) – Replaces older messages.

  #### Data and extras

  * [`data`](/reference/push-notification#body-data) – Custom key-value pairs sent to your app.
  * [`url`](/reference/push-notification#body-url) – Opens when notification is tapped.
</Accordion>

### Email options

<Accordion title="Email options">
  #### Content

  * [`email_subject`](/reference/email#body-email-subject)
  * [`email_body`](/reference/email#body-email-body)
  * [`email_preheader`](/reference/email#body-email-preheader)

  #### Appearance

  * [`template_id`](/reference/email#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Sender info

  * [`email_from_name`](/reference/email#body-email-from-name)
  * [`email_reply_to`](/reference/email#body-email-reply-to)
</Accordion>

### SMS/MMS options

<Accordion title="SMS/MMS options">
  #### Content

  * [`contents`](/reference/sms#body-contents)
  * [`template_id`](/reference/sms#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Media (MMS only)

  * [`sms_media_urls`](/reference/sms#body-sms-media-urls)

  #### Sender info

  * [`sms_from`](/reference/sms#body-sms-from)
</Accordion>

***

## Schedule and per-user delivery

By default, messages are sent immediately. You can schedule delivery in advance and optimize timing per user based on their local timezone or recent activity.

<Accordion title="Schedule delivery and per-user optimization parameters">
  <ParamField type="string">
    Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript's Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring).

    ```json theme={null}
    {
      "send_after": "2025-09-24T14:00:00-07:00"
    }
    ```
  </ParamField>

  <ParamField type="string">
    Controls how push and email messages are delivered on a per-user basis. Not available for SMS.

    * `"timezone"`: Sends at the same local time across time zones.
    * `"last-active"`: Delivers based on each user's most recent session.

    Not compatible with [push throttling](/docs/en/throttling). When `delayed_option` is set, you must also set `throttle_rate_per_minute` to `0`.

    ```json theme={null}
    {
      "delayed_option": "last-active",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>

  <ParamField type="string">
    Use with `delayed_option: "timezone"` to set a consistent daily delivery time. Accepted formats:

    * `"9:00AM"` (12-hour)
    * `"21:45"` (24-hour)
    * `"09:45:30"` (HH:mm:ss)

    Example — Send every day at 9 AM in each user's local time:

    ```json theme={null}
    {
      "delayed_option": "timezone",
      "delivery_time_of_day": "9:00AM",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>
</Accordion>

***

## Submit the request

This final example sends a localized push notification to all subscribed users:

```curl theme={null}
curl -X "POST" "https://api.onesignal.com/notifications" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Key YOUR_API_KEY' \
     -d $'{
      "target_channel": "push",
      "included_segments": [
        "Subscribed Users"
      ],
      "app_id": "YOUR_APP_ID",
      "contents": {
        "en": "Hello, world",
        "es": "Hola mundo",
        "fr": "Bonjour le monde",
        "zh-Hans": "你好世界"
      }
    }'
```

Once the request is sent, OneSignal forwards it to the appropriate downstream provider, which then delivers it to the recipient:

* **Push:** FCM, APNs, or HMS
* **Email:** your email service provider
* **SMS:** Twilio

### Handle the response

You receive a `200` response code if the request is valid and accepted.

* If an `id` is returned, the message was created successfully. Save this `id` for future tracking and reference of message stats via the [View message API](/reference/view-message).
* If no `id` is returned, the message was not created, likely because there are no valid [subscriptions](/docs/en/subscriptions) in the target audience.

**Response details by channel:**

* [Push](/reference/push-notification#response-id)
* [Email](/reference/email#response-id)
* [SMS](/reference/sms#response-id)

<Note>
  See our [REST API Overview](/reference/rest-api-overview#reliability-and-delivery) page for details on retries and [rate limits](/reference/rate-limits).
</Note>

***

## FAQ

### Can I combine `include_aliases`, `included_segments`, and `filters` in one request?

No. Each request must use exactly one targeting method. Mixing them returns a validation error. Choose aliases for transactional sends to specific users, segments for predefined audiences, or filters for ad-hoc audiences built with `AND`/`OR` logic.

### Does `target_channel: "sms"` cover RCS?

Yes. The `target_channel` enum accepts `"push"`, `"email"`, and `"sms"`. RCS messages are delivered through the SMS channel — there is no separate `"rcs"` value. OneSignal decides whether to send via RCS or SMS based on the recipient's device and your sender configuration.

### My request returned `200` but no `id`. What happened?

The request was valid but no message was created, typically because the target audience contains no valid subscriptions for the selected channel. Common causes include a segment that resolves to zero users, all targeted aliases being unsubscribed, or phone numbers that don't match an existing SMS subscription.

### Can I use `//` comments in the JSON request body?

No. The `//` comments in the examples on this page are illustrative only. Strict JSON does not support comments — strip them before sending to the API.

### How is the `Sent` count in reports related to the API response?

The dashboard `Sent` metric is a composite. To derive it from the [View message API](/reference/view-message), sum `successful + failed + errored`. See the [Metrics glossary](/docs/en/analytics-metrics-glossary) for the full mapping between dashboard, API, CSV, and Event Streams names.

***

## Next steps

Refer to the channel-specific APIs to customize delivery further:

* [Push notification](/reference/push-notification)
* [Email](/reference/email)
* [SMS](/reference/sms)
* [Live Activities](/reference/start-live-activity)
* [Server-Side SDKs](/docs/en/server-sdk-reference)


# Create segment
Source: https://documentation.onesignal.com/reference/create-segments

POST /apps/{app_id}/segments
Programmatically create segments in your OneSignal app using flexible filters and targeting rules.

## Overview

Use this API to create new [Segments](/docs/en/segmentation) programmatically. These segments are then accessible in the OneSignal Dashboard and usable in messages, Journeys, and in-app messaging campaigns.

<Note>
  To modify an existing segment, use the [Update segment](/reference/update-segment) API.
</Note>

***

## How to use this API

This endpoint allows your backend to define audience segments by passing in a combination of filters and logical operators like `"AND"` and `"OR"`, mirroring the segmentation capabilities of the OneSignal Dashboard.

### Name the segment

The name of the segment as it shows in the OneSignal dashboard and accessible via the `included_segments` and `excluded_segments` targeting parameters.

### Describe the segment

Optionally include a `description` (max 255 characters) to record the segment's purpose. The description is returned by the [View segments](/reference/view-segments) and [View segment](/reference/view-segment) APIs.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "10"}
  ]
}
```

### Define the `filters`

Available filters:

* [operator](#operator)
* [tag](#tag)
* [last\_session](#last_session)
* [first\_session](#first_session)
* [session\_count](#session_count)
* [session\_time](#session_time-1)
* [language](#language)
* [app\_version](#app_version)
* [location](#location)
* [country](#country)

### `operator`

**Description**

Allows you to combine or separate properties. Filters combined with an `"AND"` have higher priority than `"OR"` filters.

* `"AND"` = the 2+ connected filters must be satisfied for the recipient to be included. Filter entries use this by default and its not required to be included.
* `"OR"` = the 2 filters separated by the `"OR"` operator are mutually exclusive. The recipients only need to satisfy the conditions on either side of the `"OR"` operator.

<CodeGroup>
  ```json AND example theme={null}
  // Users must satisfy both filters to be included.
  // Notice the AND operator is not required

  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  // The same example using the AND operator. This is not required.
  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "AND"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  ```

  ```json OR example theme={null}
  // Users can satisfy either filter to be included.

  "filters": [
    {"field": "tag", "key": "level", "relation": "=", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "level", "relation": "=", "value": "20"}
  ]
  ```

  ```json Combinations theme={null}
  // In this example, users must either have:
  // The specified session_count AND tag requirement
  // Or it will be all records where last_session is satisfied
  {
    "name": "2 filters or 1",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"}
    ]
  }

  // Similar to the first example, this shows how to require a specific field
  // across other filters

  {
    "name": "3 filters, 1 required across all",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
    ]
  }
  ```
</CodeGroup>

### `tag`

**Description**

Target based on custom user [Tags](/docs/en/add-user-data-tags).

<Warning>
  Do not use tags for targeting individual users like a "user id".
  Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
</Warning>

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
  * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
* `key` = Tag key to compare.
* `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

```json theme={null}
"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "OR"},
  {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
]
```

### `last_session`

**Description**

Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "last_session", "relation": ">","hours_ago": "10"}
  ]
  ```

### `first_session`

**Description**

Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "first_session", "relation": "<","hours_ago": "24"}
  ]
  ```

### `session_count`

**Description**

Total number of sessions by the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="` or `"!="`
* `value` = number of sessions. Example: `"1"`

  ```json theme={null}
  "filters": [
    {"field": "session_count", "relation": ">","value": "5"}
  ]
  ```

### `session_time`

**Description**

Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

* `relation` = `">"` or `"<"`
* `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

  ```json theme={null}
  "filters": [
    {"field": "session_time", "relation": ">","value": "86400"}
  ]
  ```

### `language`

**Description**

[User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = 2 character language code. Example: `"en"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "language", "relation": "=","value": "en"},
    {"operator": "OR"},
    {"field": "language", "relation": "in_array","value": "es,fr,de"}
  ]
  ```

### `app_version`

**Description**

App version set on the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = app version. Example: `"1.0.0"`
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "app_version", "relation": "=","value": "1.0.1"},
    {"operator": "OR"},
    {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
  ]
  ```

### `location`

**Description**

Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

* `radius` = in meters
* `lat` = latitude
* `long` = longitude

  ```json theme={null}
  "filters": [
    {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
  ]
  ```

### `country`

**Description**

Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "=", "value": "US"},
    {"operator": "OR"},
    {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
  ]
  ```

***


# Create Subscription by alias
Source: https://documentation.onesignal.com/reference/create-subscription

POST /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions
Use this API to attach a new subscription—such as email, SMS, or push notification—to an existing OneSignal user identified by an alias.

## Overview

This API allows you to add a **new Subscription** to an existing [User](/docs/en/users) via an alias identifier. A *Subscription* reflects a user's intent to receive messages through a specific communication channel, such as email, SMS, or push notifications. See [Subscriptions](/docs/en/subscriptions) for additional context.

If you're looking to **create a new user and add Subscriptions simultaneously**, use the [Create User](/reference/create-user) API instead.

***

## How to use this API

To attach a Subscription, the user must already exist and be referenced using an alias. The `alias_label` and `alias_id` path parameters define how the user is identified:

* Common alias: `external_id`
* Other options: `onesignal_id`, or custom aliases

For details, refer to [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

## Required Fields

Each Subscription must include at least:

* `type`: the channel (e.g., `Email`, `SMS`, `iOSPush`)
* `token`: the unique identifier for the channel (e.g., email address, phone number, push token)

If the specified `type` and `token` already exist in the app, the Subscription will be transferred to the user identified in the path parameters.

***


# Create template
Source: https://documentation.onesignal.com/reference/create-template

POST /templates
Create reusable message templates for push, email, and SMS channels. Templates can be accessed through both the dashboard and API using a `template_id`.

## Overview

Use this endpoint to create a new message template in your OneSignal app. Once created, the template becomes available for use when sending messages via both the Dashboard and the REST API by referencing the `template_id`.

Templates streamline and standardize message content across push, email, and SMS channels.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Before using this endpoint, ensure that the target channel (push, email, or SMS) is properly configured in your OneSignal app. See [Channel Setup](/docs/en/channel-setup) for guidance.

### Push Templates

**Requirements:**

* Set the `contents` property with the English (`en`) language key.
* All [Push Channel Properties](/reference/push-notification) are valid for use in push templates.
* By default, all push platforms are enabled. You can target specific platforms by explicitly setting them (e.g., `isAndroid: true` disables others).

### Email Templates

**Requirements:**

* Set `isEmail: true`.
* Include both `email_subject` and `email_body`.
* All [Email Channel Properties](/reference/email) are valid for use in email templates.

### SMS Templates

**Requirements:**

* Set `isSMS: true`.
* Provide SMS-specific parameters like `contents`.
* All [SMS Channel Properties](/reference/sms) are valid for use in SMS templates.

***


# Create user
Source: https://documentation.onesignal.com/reference/create-user

POST /apps/{app_id}/users
Create a new user or modify the subscriptions associated with an existing User.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint enables you to create and manage users outside of frontendSDK-based sessions. It's primarily used to:

* Import users from other systems.
* Programmatically define users by assigning identifiers (aliases), properties (e.g., tags), and messaging subscriptions (e.g., email, mobile, SMS).

If you're using the frontend SDKs, user creation is typically handled automatically via methods like `login`, `addEmail`, and `addSms`. See [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) for conceptual guidance.

***

## How to use this API

To successfully create a user via the API:

* You must provide at least one unique identifier via the `identity` and Subscription via the `subscriptions` fields.
* You can optionally include user profile data (`properties`) and one or more messaging `subscriptions`.

## Key Concepts

### Aliases

Aliases uniquely identify a user and should include an `external_id` (the recommended identifier). They allow you to reference users across platforms or external systems. Up to 10 custom aliases are supported. Each alias key and value has a maximum length of 128 characters.

### Properties

User properties store information such as tags, location, activity, and device data. These attributes help you personalize campaigns and optimize engagement strategies.

### Subscriptions

A user can have up to **20 subscriptions** (across email, SMS, push, etc.). Subscriptions connect users to channels for message delivery and are transferable across users. See [Subscriptions](/docs/en/subscriptions) for more.

***


# Export subscriptions CSV
Source: https://documentation.onesignal.com/reference/csv-export

POST /players/csv_export
Generate a GZip-compressed CSV export of your current subscription data using this API endpoint.

## Overview

Use this endpoint to request a GZip-compressed CSV export of all your [Subscriptions data](/docs/en/subscriptions) from OneSignal. The export includes both default and optional user data fields, and supports filters to refine the dataset. The file is downloadable via a URL returned in the API response.

***

## How to use this API

By default, this will export all Subscriptions within the app.

**Optional filters:**

You can narrow the export using:

* `segment_name`: Only export Subscriptions from a specific segment. Segment membership rules determine which subscription statuses are included. Use with `include_unsubscribed` to include unsubscribed subscriptions.
* `last_active_since`: Export Subscriptions where their `last_session` was after a specific Unix timestamp. Example: Use `1704067200` for Subscriptions active since January 1st, 2024.
* `include_unsubscribed`: When exporting a segment, set to `true` to include unsubscribed subscriptions alongside subscribed ones. By default, segment-filtered exports only return subscribed subscriptions. This parameter has no effect when `segment_name` is not provided.

**Example successful response:**

```json 200 OK theme={null}
{
  "csv_file_url": "https://onesignal.com/csv_exports/b2f7f966.../users_1849..._2024-11-10.csv.gz"
}
```

**Export time considerations:**

* Generation speed: \~2,000 records per second.
* File readiness: The `csv_file_url` may return a 404 until generation completes.
* Download retry: Poll the file URL at intervals until the file is ready.
* File expiration: The file remains available for 3 days after generation.
* Concurrency: Only one export per OneSignal account can run at a time.

**File not ready (404 response)**

```xml 404 CSV GET  theme={null}
This XML file does not appear to have any style information
associated with it. The document tree is shown below.
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

<Info>
  You can safely poll the `csv_file_url` until the file becomes available. Implement retry logic based on expected data volume and generation speed.

  Only one export is allowed at a time per account. Wait until the `.csv.gz` file is downloaded before triggering another export.
</Info>

***

## CSV data contents

The export includes two types of fields:

* **Default fields**: Always included unless excluded by schema changes.
* **Extra fields**: Must be explicitly requested using the `extra_fields` parameter.

### Default fields

* `id`: The Subscription ID.

* `identifier`: The push token, email address, or phone number depending on the Subscription type.

* `session_count`: The number of times the user has opened the app.

* `language`: The user's language in ISO 639-1 format.

* `timezone`: Deprecated — use `timezone_id` instead.

* `game_version`: The version of your app that the user is currently using.

* `device_os`: The device's operating system version.

* `device_type`: Integer representing channel/device type.
  * `0`: iOSPush
  * `1`: AndroidPush
  * `2`: FireOSPush
  * `5`: ChromePush
  * `7,17`: SafariPush
  * `11`: Email
  * `14`: SMS

* `device_model`: The device's hardware string.

* `ad_id`: Deprecated.

* `tags`: Custom key/value data.

* `last_active`: The last time the user was active.

* `playtime`: The total amount of time in seconds the user had the mobile app open.

* `created_at`: The first time the user was seen.

* `invalid_identifier`: Boolean flag for unsubscribed state.
  * `t`: Unsubscribed
  * `f`: Subscribed

### Extra fields (`extra_fields`)

Pass `extra_fields` in your request to include any of the following:

* `external_user_id`: Maps to the `external_id` of the user.

* `onesignal_id`: OneSignal's user ID.

* `location`: Adds the `lat` and `long` coordinates if set.

* `country`: The user's country in ISO 3166-1 Alpha 2 format.

* `ip`: The IP address if detected. Can be IPv4 or IPv6 format.

* `web_auth`: Only available to OneSignal SDKs. The `web_auth` key for web push.

* `web_p256`: Only available to OneSignal SDKs. The `web_p256` for web push.

* `unsubscribed_at`: The date and time the user last unsubscribed. They may resubscribe at any time. Check the `invalid_identifier` field to determine if they are currently subscribed.

* `notification_types`: Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/en/subscriptions#notification-types).

* `timezone_id`: The user's timezone in IANA format.

***


# Remove alias
Source: https://documentation.onesignal.com/reference/delete-alias

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}
Remove a specific alias from a user.

## Overview

Use this API to remove a specific alias from a user’s identity object without deleting the user. This operation only affects user identity labels—subscriptions and the core user record remain intact. To delete a user entirely, including all associated aliases and subscriptions, see the [Delete user](/reference/delete-user) API.

***

## How to use this API

To remove an alias from a user:

1. Identify the user via a known alias by specifying:

   * `alias_label` – the type of alias (e.g., email, external\_id)
   * `alias_id` – the unique identifier for that alias

2. Specify the alias to remove using:

   * `alias_label_to_delete` – the label of the alias to be deleted

   The `alias_label_to_delete` can be the same as the `alias_label` used to identify the user.

3. This action is performed synchronously—the alias is deleted immediately after the request is processed.

<Warning>
  The `onesignal_id` alias cannot be deleted. Only secondary aliases (like email, external\_id, etc.) are removable.
</Warning>

For a full explanation of identity management, see [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

***

## FAQ

### Can I delete the same alias that I used to look up the user?

Yes. This is a common scenario—especially if an alias was set incorrectly and needs to be removed. Just be sure to include that alias both as the identifier and as alias\_label\_to\_delete.

If you want to delete the entire user and all associated data, use the [Delete user](/reference/delete-user) API.

### What happens if I delete all aliases associated with the user?

A user will always retain at least one alias, the onesignal\_id. Even if you remove all other aliases, the user and their subscriptions remain linked to the onesignal\_id.

***


# Delete API key
Source: https://documentation.onesignal.com/reference/delete-api-key

DELETE /apps/{app_id}/auth/tokens/{token_id}
Delete a specific Rich Authentication Token (App API Key) for a OneSignal app. Requires your Organization API Key and the token's unique ID, not the token value itself.

## Overview

Use this API to delete a specific App API Key (Rich Authentication Token) for a single OneSignal.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Delete segment
Source: https://documentation.onesignal.com/reference/delete-segments

DELETE /apps/{app_id}/segments/{segment_id}
Delete segments from OneSignal. Does not delete users or subscriptions.

## Overview

The Delete segment method is used when you want to programmatically delete a segment from within the OneSignal Dashboard UI.

<Warning>
  Once a segment is deleted, it cannot be recovered. You will need to create a new segment with the same filters.
</Warning>

***

## How to use this API

You can pass in the `segment_id` dictating which segment from our dashboard will be deleted.

The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard as shown below:

<Frame>
  <img />
</Frame>

***


# Delete Subscription
Source: https://documentation.onesignal.com/reference/delete-subscription

DELETE /apps/{app_id}/subscriptions/{subscription_id}
Delete a specific subscription by its subscription_id. This stops messages from being sent to that subscription but does not prevent future subscriptions with the same token.

## Overview

Use this API to delete an existing Subscription and its associated properties. Deletion is **asynchronous**, and while the Subscription is being removed, messages will no longer be sent to it.

<Warning>
  This operation only deletes a **single Subscription**. To remove a **user and all their Subscriptions**, use the [Delete User](/reference/delete-user) API instead.
</Warning>

### What Happens When You Delete

* Messages will stop being sent to the deleted subscription.
* **Deleting a Subscription does not block new Subscriptions** with the same `token`.
  * If the app is reopened or a token is re-submitted (e.g., same email or phone), a **new Subscription** may be automatically created.
  * This ensures users can re-subscribe if needed without requiring manual intervention.

***

## How to Use This API

**Required:** `subscription_id`

You must provide the `subscription_id` of the subscription to be deleted. This ID is a UUID generated by OneSignal and is immutable.

To find the `subscription_id`:

1. Use the [View User](/reference/view-user) API.
2. Look at the `subscriptions` array in the response.
3. Identify the correct subscription by its `type`, `token`, or other metadata.
4. Use the corresponding `id` field as the `subscription_id`.

***


# Delete template
Source: https://documentation.onesignal.com/reference/delete-template

DELETE /templates/{template_id}?app_id={app_id}
Permanently delete a specific message template from your OneSignal app using its template ID. Templates used in Journeys must be removed from those Journeys before deletion.

## Overview

This endpoint allows you to delete a single template associated with your OneSignal app. Deletion is **immediate and irreversible**.

<Warning>
  If the template is currently used in a Journey, it cannot be deleted until that Journey has been deleted.
</Warning>

***

## How to use this API

Required Parameters

* `template_id` (path param): The OneSignal-generated UUID of the template to delete.
* `app_id` (query param): Your OneSignal App ID.

### Where to Find `template_id`

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# Delete user
Source: https://documentation.onesignal.com/reference/delete-user

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}
Delete a user including all associated properties, subscriptions, and identity.

## Overview

Use this API to permanently delete a user from your OneSignal project, including all associated subscriptions, properties, and aliases. The operation is asynchronous—user data will be deleted shortly after the request is accepted.

***

## How to use this API

To delete a user, you must be able to identify them using one of the following alias types:

* `external_id` (recommended and most common)
* `onesignal_id`
* A custom Alias that you have set

Pass the appropriate `alias_label` and corresponding `alias_id` in the request path.

<Warning>
  This operation deletes all data associated with the user, including:

  * All identity aliases
  * All channel subscriptions (push, email, SMS, etc.)
  * All custom user properties
</Warning>

## Because this is an irreversible operation, be sure that you really intend to delete the user and all their data.


# Delete player record
Source: https://documentation.onesignal.com/reference/delete-user-record

delete https://onesignal.com/api/v1/players/{player_id}?app_id={app_id}

Delete a player (aka Subscription).

<Warning>
  This is a Legacy API. Use [Delete User](/reference/delete-user) or [Delete Subscription](/reference/delete-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `app_id`    | string | Yes      | Your OneSignal App ID.         |
| `player_id` | string | Yes      | The Subscription ID to delete. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Example Request

```http theme={null}
DELETE /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json
```

***

## Example Response

```json theme={null}
{
  "success": true
}
```

The Subscription will be deleted from the OneSignal database.

***


# Edit player
Source: https://documentation.onesignal.com/reference/edit-device

put https://onesignal.com/api/v1/players/{player_id}

Update a player's (Subscription's) information using the Subscription ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `player_id` | string | Yes      | The OneSignal Subscription ID. |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request.    |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                |
| -------------------- | ------- | -------- | ---------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                     |
| `identifier`         | string  | No       | Push token, email, or phone number.                        |
| `language`           | string  | No       | Language code (e.g., "en").                                |
| `timezone`           | integer | No       | Time zone offset in seconds.                               |
| `game_version`       | string  | No       | App version.                                               |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                         |
| `device_os`          | string  | No       | OS version (e.g., "14.5").                                 |
| `ad_id`              | string  | No       | Advertising ID.                                            |
| `sdk`                | string  | No       | OneSignal SDK version.                                     |
| `tags`               | object  | No       | Custom key-value pairs.                                    |
| `external_user_id`   | string  | No       | Your internal user ID.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc. |
| `email_auth_hash`    | string  | No       | Required to update email identifiers securely.             |
| `sms_auth_hash`      | string  | No       | Required to update SMS identifiers securely.               |

> Only include fields you want to change. Fields left out will not be modified.

***

## Example Request

```json theme={null}
PUT /api/v1/players/player_id_string HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "external_user_id": "user123",
  "tags": {
    "level": "20",
    "subscription": "active"
  },
  "language": "fr",
  "timezone": 3600,
  "device_os": "16.0"
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Missing or invalid fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied.
* 404 Not Found – Device with player\_id not found.

***


# Edit tags with external user id
Source: https://documentation.onesignal.com/reference/edit-tags-with-external-user-id

put https://onesignal.com/api/v1/apps/{app_id}/users/{external_user_id}

Update a player's (Subscription's) information using the External ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter          | Type   | Required | Description             |
| ------------------ | ------ | -------- | ----------------------- |
| `app_id`           | string | Yes      | Your OneSignal App ID.  |
| `external_user_id` | string | Yes      | The user's External ID. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Request Body Parameters

| Field  | Type   | Required | Description                       |
| ------ | ------ | -------- | --------------------------------- |
| `tags` | object | Yes      | Key-value pairs to set or update. |

* To **delete a tag**, set its value to an empty string (`""`).
* Existing tags with the same keys will be **overwritten**.

***

## Example Request

```http theme={null}
PATCH /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json

{
  "tags": {
    "plan": "premium",
    "logged_in": "true",
    "referral": ""
  }
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Invalid request or payload.
* 401 Unauthorized – Invalid or missing keys.
* 403 Forbidden – Access denied due to insufficient permissions.
* 404 Not Found – No players found for given `external_user_id`.

***


# Email
Source: https://documentation.onesignal.com/reference/email

POST /notifications?c=email
Send a message using the email channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for email. See [Push notification](/reference/push-notification) or [SMS](/reference/sms) to send to those channels.

Ensure your [Email setup](/docs/en/email-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Export audience activity CSV
Source: https://documentation.onesignal.com/reference/export-csv-of-events

POST /notifications/{message_id}/export_events
Export a compressed CSV report of audience-level delivery and engagement data for a specific message. This includes sent, delivered, clicked, failed, and unsubscribed events across Push, Email, and SMS channels.

## Overview

Get a CSV of per-recipient audience activity events (sends, clicks, failures, etc.) for a push, email, or SMS message. This endpoint mirrors the **Export** button in the dashboard's Audience Activity section on each message report:

* [Push message reports](/docs/en/push-notification-message-reports)
* [Email message reports](/docs/en/email-message-reports)
* [SMS message reports](/docs/en/sms-message-reports)

The CSV schema varies by channel. See each channel's message reports page for column definitions.

***

## How to use this API

Get the message `id` from the [Sending messages API](/reference/create-message) or the [View messages API](/reference/view-messages).

A successful request returns `200 OK` with a `csv_file_url`:

```json 200 OK theme={null}
{
    "csv_file_url": "https://onesignal-data.onesignal.com/csv_exports/YOUR_APP_ID/events_audience-activity-YOUR_MESSAGE_ID-push-YYYY-MM-DDTHH-MM-SSTZ.csv.gz"
}
```

The generated file name follows the pattern `events_audience-activity-{message_id}-{channel}-{timestamp}.csv.gz`.

The file is generated at \~2,000 records per second. For large audiences, generation can take several minutes, and the URL may return `404` until the file is ready:

```xml 404 Not Found theme={null}
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

Poll the `csv_file_url` with GET and implement retries with exponential backoff. When the file is ready, the GET request downloads the `.csv.gz` file.

<Info>
  * The CSV download URL is valid for **3 days** after creation.
  * File names include a random UUID to prevent guessing.
</Info>

<Warning>
  Only **one concurrent export** is allowed per OneSignal account. Download the `.csv.gz` file before starting another export, or the new request fails.
</Warning>

***


# View user identity
Source: https://documentation.onesignal.com/reference/fetch-aliases

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Retrieve all aliases associated with a user using a known alias, such as an `external_id`, `onesignal_id`, or a custom alias. This API helps you map back to a user’s full identity from any one piece of identifying information.

## Overview

Use this API when you want to retrieve the complete identity object for a user, which includes all aliases tied to that user. It is ideal for cases where you know one alias and want to discover others—especially helpful for user mapping, debugging, or linking systems.

This endpoint is similar to the [View user](/reference/view-user) API but only returns the `identity` object—not subscriptions or properties.

<Tip>
  If you only know a subscription\_id, use View user identity (by subscription) instead.
</Tip>

For more context on user identity and aliasing:

* [Users](/docs/en/users)
* [Aliases](/docs/en/aliases)

***

## How to use this API

To identify the user, use:

* `alias_label` – the type of alias you’re using to find the user (e.g. `external_id`, `onesignal_id`, or a custom alias)
* `alias_id` – the actual value of that alias

Common usage patterns:

Using `external_id` (recommended):

* `alias_label`: `external_id`
* `alias_id`: your user ID (e.g., user-123)

Using `onesignal_id`:

* `alias_label`: `onesignal_id`
* `alias_id`: the OneSignal-assigned unique ID

Using a custom alias:

* Define your own alias label (e.g. `shopify_customer_id`) and its value

<Note>
  We strongly recommend setting and using the `external_id` as your primary user identifier for portability and simplicity across your systems.
</Note>

***


# View user identity (by subscription)
Source: https://documentation.onesignal.com/reference/fetch-identity-by-subscription

GET /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Retrieve all aliases linked to a user using a known `subscription_id`. This is useful when the user’s identity is unknown but you have access to one of their push, email, or SMS subscriptions.

## Overview

Use this API when you want to find the full identity (all aliases) of a user, starting from a known `subscription_id`. This is helpful for debugging, reverse lookups, or support use cases where only a subscription record is available.

<Note>
  Unlike the [View user identity](/reference/fetch-aliases) API which starts with an alias (e.g., `external_id`), this endpoint works when only a subscription ID is known.
</Note>

See [Subscriptions](/docs/en/subscriptions) for background on how subscriptions relate to users.

***

## How to use this API

To use this endpoint, you must provide:

* `subscription_id` – A UUID generated by OneSignal when a device or channel (e.g., push, email, SMS) is registered.

<Warning>
  `subscription_id` values are immutable and cannot be changed. Make sure you are using the correct value, as they are unique to each app and platform.
</Warning>

Once a valid `subscription_id` is provided, the API will return the user’s identity object, which includes all associated aliases like `external_id`, `onesignal_id`, and any custom aliases.

***


# Idempotent API requests
Source: https://documentation.onesignal.com/reference/idempotent-notification-requests

Prevent duplicate messages or custom events when retrying API requests.

## Overview

When you create messages or custom events via our REST API, network failures or timeouts can cause uncertainty about whether a request succeeded. **Idempotent requests** solve this problem by ensuring the same request is only processed once—even if it is sent multiple times.

This page explains how idempotency works in OneSignal, when to use it, and common pitfalls to avoid.

### When you should use idempotency

You should use idempotent requests any time you plan to retry API calls, especially when:

* You receive a timeout, 500-level error, or no response.
* Your infrastructure automatically retries failed requests.
* Delivering a duplicate message or custom event would be harmful.
* Missing a message or custom event would be harmful.

### The problem idempotency solves

Consider this common failure scenario:

1. You send a `notifications#create` or `custom_events#create` request.
2. OneSignal begins processing and sending the message or event.
3. A network error occurs before your client receives a response.

At this point, your system cannot know whether the request succeeded.

* If you retry and the request already succeeded, users may receive duplicates.
* If you do not retry and the request failed, users may miss important messages or events.

**Idempotency provides a safe retry mechanism.**

***

## How idempotency works

OneSignal supports idempotent operations for:

* [`notifications#create`](/reference/create-message)
* [`custom_events#create`](/reference/create-custom-events)

You provide a unique `idempotency_key` with each request.

### Request flow with idempotency

1. You send a request with an `idempotency_key`.
2. OneSignal processes the request and begins sending the message or creating the custom event.
3. A network error or timeout occurs.
4. You retry the request using the same `idempotency_key`.
5. OneSignal detects the duplicate and returns the result of the original request.
6. Only one notification or custom event is processed.

You can repeat this retry any number of times. As long as the `idempotency_key` remains the same, the operation will only be processed once.

***

## Idempotency key reference

<ParamField type="RFC 9562 UUID">
  A unique identifier used to prevent duplicate messages or custom events from repeat API calls. Keys must be unique [RFC 9562 UUID format](https://en.wikipedia.org/wiki/Universally_unique_identifier). Valid for 30 days.
</ParamField>

<Note>
  This `idempotency_key` property used to be called `external_id` but caused confusion with our [Users `external_id`](/docs/en/users) alias, so we have added this new property name to reduce confusion. Both will work in this case.
</Note>

***

## Important constraints and gotchas

<Warning> If you reuse the same `idempotency_key` for different messages or events, only the first request will be processed. </Warning>

Keep the following in mind:

* **Keys must be unique per logical operation**
  Generate a new UUID for every notification or custom event you intend to send.

* **Keys are retained for 30 days**
  After 30 days, OneSignal may delete the record. Reusing the same key after that window may result in a new message being sent.

* **Use a strong source of randomness**
  Predictable or reused UUIDs can cause unexpected deduplication.

* **Idempotency does not guarantee delivery**
  It only guarantees at-most-once processing. You should still monitor API responses and logs.

### Legacy behavior

The `idempotency_key` property was previously named `external_id`. This caused confusion with the Users `external_id` alias, so `idempotency_key` is now the recommended field name. Both names are currently supported.

### Best practices

* Always include `idempotency_key` when implementing retries.
* Store the `idempotency_key` alongside your request metadata for debugging.
* Retry only after honoring any `Retry-After` header returned by the API.
* Combine idempotency with proper timeout handling (for example, a 60-second HTTP timeout).

***


# Message history
Source: https://documentation.onesignal.com/reference/message-history

POST /notifications/{message_id}/history
View which subscriptions received a particular message

## Overview

This API enables you to retrieve all [Subscriptions](/docs/en/subscriptions) that received a specific push notification or email. You can access the notification's history for up to seven days after it was sent. Please note that notifications sent to fewer than 1,000 recipients will not record a "received" event, but they will still record "sent" events.

***

## How to Use this API

1. Submit a request to generate a report.

2. Decide delivery method

   * After receiving a successful response, **poll the destination URL** until the file becomes available. Exports typically complete within 1-3 minutes; we recommend a 10-second polling interval.
   * Alternatively, you can opt to receive an email to the address specified in the optional `email` parameter when the report is ready.

### Requirements

* A [OneSignal Professional or Enterprise Plan](https://onesignal.com/pricing).
* Enabled the "Send History via OneSignal API" option in Settings -> Integrations; notifications sent before this setting is enabled can't be retrieved.
* Requests must be made within seven days of sending the notification.

### Polling

Use the `csv_file_url` property in the response to test if the report is complete. If you receive a '403' error response, retry fetching the file after a short period; it only means we're still generating the report.

### Sample Report

The generated report is a simple CSV file that can be imported into any system for further processing.

```csv report.csv theme={null}
player_id,onesignal_id,external_id,target_channel,timestamp
"2c4fac95-7dfb-4113-9347-aba3a92ff557","ccddf35a-1233-4423-8a57-ac8c4b38eb81","a07aec27-2586-4b92-a24f-62660a1517fa","push","1628189160"
"68f5cf73-b20a-4de9-b6ee-79a863b8e7d8","d2f9f2f8-94af-4942-8183-115cef1213d5","4b66359f-3d94-4a73-806d-8ef5f0430b3d","push","1628187816"

```

### Limitations

* Querying for `opens` events are not supported.
* The `timestamp` column is included only for `clicked` events.

***


# Push notification
Source: https://documentation.onesignal.com/reference/push-notification

POST /notifications?c=push
Send a message using the push notification channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for push. See [Email](/reference/email) or [SMS](/reference/sms) to send to those channels.

Ensure your application is properly configured by following the [Mobile SDK Setup](/docs/en/mobile-sdk-setup) and/or [Web SDK Setup](/docs/en/web-sdk-setup) guides. You should see subscribed push [Subscriptions](/docs/en/subscriptions) in your OneSignal dashboard to send them messages.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Rate limits and error handling
Source: https://documentation.onesignal.com/reference/rate-limits

Understand OneSignal API and application rate limits, common errors, retry behavior, and how to safely recover from failures without sending duplicate messages or disabling your app.

OneSignal uses rate limits and error responses as safety mechanisms to protect your app from accidental overloads, duplicate sends, and retry storms.

There are three categories to understand:

* **API rate limits** return HTTP `429` errors when request volume is too high.
* **Network timeouts or temporary server failures** return `5xx` errors or no response at all.
* **Application message limits** may temporarily disable your app if too many messages are sent in a short period.

<Info>
  Most apps never hit these limits during normal usage. When they do occur, they are usually caused by retries, loops, or unexpected audience expansion.
</Info>

<Check>
  **Quick implementation checklist**

  * Expect `429`, `5xx`, and timeouts. They are normal at scale.
  * Never retry message sends without an `idempotency_key`.
  * For non-urgent retries, wait **100 seconds** before retrying.
  * API rate limits (`429`) never disable your app.
  * Only message volume limits can disable your app.
  * `POST /notifications` (create) and `DELETE /notifications` (cancel) count toward the same rate limit.
  * The [Create custom events](/reference/create-custom-events) endpoint has its own rate limit, separate from the notification endpoints.
</Check>

***

## API rate limits

API rate limits apply **per app and per endpoint**. They are evaluated when a request is received, not when a response is returned.

These limits are designed to throttle traffic, not block your app.

| Endpoint                                                                                  | Rate limit                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create message](/reference/create-message) / [Cancel message](/reference/cancel-message) | **Free plans:** 150 requests/sec/app<br />**Paid plans:** 6,000 requests/sec/app<br /><br />The `POST /notifications` and `DELETE /notifications` endpoints share the same limit. Requests count toward it regardless of method. For example, 3,000 creates + 3,000 cancels = 6,000 requests/sec on a paid plan.<br /><br />Each request can target many users or segments. |
| [Create custom events](/reference/create-custom-events)                                   | Rate-limited independently from Create Message.<br />**Request size limits:** 2,024 bytes per event · 1 MB per request body                                                                                                                                                                                                                                                 |
| Create, update, or delete users or subscriptions                                          | 1,000 requests/sec/app<br />1 request/sec per user or subscription<br />Up to 100 property updates per request                                                                                                                                                                                                                                                              |
| View endpoints (messages, templates, users)                                               | 1 request/sec/app<br />Up to 10 look-back requests/sec                                                                                                                                                                                                                                                                                                                      |
| Message History and CSV exports                                                           | Keep parallel exports under 100 GB per file                                                                                                                                                                                                                                                                                                                                 |

<Note>
  High-volume messaging should use fewer message creation requests with larger audiences instead of increasing request frequency.
</Note>

**Handling API rate limit errors (`429`):**

When you exceed an API rate limit, OneSignal returns an HTTP `429` response:

```json theme={null}
{
  "errors": ["API rate limit exceeded."]
}
```

The response includes a `Retry-After` header indicating how many seconds to wait before retrying.

**What to do when you receive a `429` error:**

1. Stop sending requests immediately.
2. Wait for the full duration specified in the `Retry-After` header.
3. Retry using exponential backoff.
4. Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for retries that send messages.

<Warning>
  Retrying before the `Retry-After` delay or retrying in tight loops can extend throttling and increase failure rates.
</Warning>

***

## Error handling and retry strategies

Retries are safe only when implemented correctly. Some failed requests may still be processing on our servers.

* Retriable errors generally include network timeouts, no responses, 429, and 5xx errors.
* Non-retryable errors include 400, 401, or 403 errors which indicate invalid input, authentication problems, or missing permissions. These are not temporary failures.

**Simple retry strategy:**

* Wait **100 seconds** before retrying.
  * This aligns with the maximum API response timeout.
  * If no response or network error occurs, the request may still be processing during this window.
* Retry **up to 3 total attempts** (original + 2 retries).
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

**Time-sensitive (advanced) retry strategy:**

* Retry using exponential backoff with jitter (for example: 2s, 4s, 8s… up to 60s).
* Cap retries to **10 total attempts** and stop after **10–15 minutes**.
* For `429` responses, treat `Retry-After` as a minimum delay: wait `max(Retry-After, backoff)`.
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

<Warning>
  Retrying message or custom event API requests without idempotency can result in duplicate messages or custom events.
</Warning>

<Accordion title="Example retry logic">
  ```text theme={null}
  attempt = 1
  max_attempts = 3

  send request with idempotency_key

  if response is success:
    stop

  if response is 429:
    wait Retry-After seconds
  elif response is 5xx or timeout:
    wait 100 seconds

  if attempt < max_attempts:
    retry with same idempotency_key
  else:
    fail safely
  ```
</Accordion>

### Retry decision guide

| Error type              | Retry? | When                 | Idempotency required |
| ----------------------- | ------ | -------------------- | -------------------- |
| `429 Too Many Requests` | Yes    | After `Retry-After`  | Yes                  |
| `5xx Server Error`      | Yes    | Backoff or 100s      | Yes                  |
| Timeout / no response   | Yes    | Immediate or delayed | Yes                  |
| `400 Bad Request`       | No     | Fix request          | No                   |
| `401 / 403`             | No     | Fix auth/permissions | No                   |

<Warning>
  Common implementation mistakes:

  * Retrying with a new idempotency key on each attempt.
  * Retrying indefinitely without a retry cap.
  * Retrying `400` or `401` errors without fixing the request.
  * Sending one request per user instead of batching audiences.
</Warning>

***

## Application message limits (app disablement)

Application message limits protect your users from receiving too many notifications in a short period of time.

**How the limit works:**

In any rolling 15-minute window, you may send up to **10 × your total number of subscribed [Subscriptions](/docs/en/subscriptions)**.

This limit is based on the total number of messages delivered, not the number of API requests.

* Sending 1 notification to 1,000 Subscriptions = 1,000 messages
* Sending 10 notifications to 1,000 Subscriptions each = 10,000 messages

The 15-minute window is rolling, not fixed.

* Messages are counted for 15 minutes after they are sent
* As time passes, older messages automatically stop counting
* You only exceed the limit if more than 10× your subscribed Subscriptions receive messages within the same 15-minute span

Example limits:

* App with 1,000 subscribed Subscriptions → up to 10,000 messages in any 15 minutes
* App with 10,000 subscribed Subscriptions → up to 100,000 messages in any 15 minutes

**Example scenarios:** App with 1,000 subscribed Subscriptions (limit: 10,000 messages per 15 minutes)

| Scenario                                                                              | Messages counted in any 15-minute period |    App disabled?    |
| ------------------------------------------------------------------------------------- | ---------------------------------------: | :-----------------: |
| At **12:00**, send 1 notification to 1,000 users                                      |                                    1,000 |          No         |
| At **12:00**, send 10 notifications to 1,000 users                                    |                                   10,000 |   Yes (hits limit)  |
| Between **12:00–12:14**, send 10,000 notifications to 1 user                          |                                   10,000 |   Yes (hits limit)  |
| Send **9,000 messages at 12:00**, then **9,000 more at 12:16**                        |                                    9,000 |          No         |
| Send **9,000 messages spread between 12:00–12:14**, then send **9,000 more at 12:15** |                                 \~18,000 | Yes (exceeds limit) |

<Note> This limit is evaluated continuously over a rolling 15-minute window, not in fixed time blocks. If any 15-minute span exceeds your limit, the app is disabled. </Note>

**What happens if the limit is exceeded:**

If your app sends more messages than allowed within a 15-minute window:

* Your app is temporarily disabled
* All app administrators receive an email notification
* A re-enable banner appears in the OneSignal Dashboard

<Warning> Only application message limits can disable your app. API rate limits (`429` errors) never disable apps. </Warning>

**What to do if your app is disabled:**

If your app is disabled, follow these steps in order:

1. Pause message sending from your backend, jobs, or automations.
2. Identify the cause, such as infinite loops, retry storms, or unexpected segment growth.
3. Log in to the OneSignal Dashboard.
4. Click **Re-enable** in the red banner at the top of the app.
5. If you need help re-enabling your app, contact `support@onesignal.com`.

***

## FAQ

### Do API rate limits disable my app?

No. API rate limits (`429` errors) only throttle your requests temporarily. Only [application message limits](#application-message-limits-app-disablement) — which track the total volume of messages delivered — can disable your app.

### What is an idempotency key and when do I need one?

An idempotency key is a unique identifier you include with a request so that retrying the same request does not create a duplicate message or event. You need one whenever you retry a `POST /notifications` or custom event request. Reuse the same key for every retry attempt. See [Idempotent API requests](/reference/idempotent-notification-requests).

### Can I increase my API rate limit?

Paid plans have higher rate limits (6,000 requests/sec vs. 150 for free plans). If you need limits beyond the paid tier, contact `support@onesignal.com` with your use case and expected volume.

### Why was my app disabled even though I didn't hit the API rate limit?

API rate limits and application message limits are separate. Your app can be disabled if the total number of messages delivered in any 15-minute window exceeds 10× your subscription count — even if every individual API request succeeded. Common causes include retry storms, runaway automations, or targeting a larger audience than intended.

***

## Related pages

<Columns>
  <Card title="Idempotent API requests" icon="rotate" href="/reference/idempotent-notification-requests">
    Prevent duplicate messages by reusing idempotency keys on retries.
  </Card>

  <Card title="Create message API" icon="paper-plane" href="/reference/create-message">
    API reference for sending push, email, SMS, and in-app messages.
  </Card>

  <Card title="Create custom event API" icon="bolt" href="/reference/create-custom-events">
    API reference for sending custom events that trigger Journeys.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="/docs/en/subscriptions">
    Understand how subscriptions are counted toward message limits.
  </Card>
</Columns>


# REST API overview
Source: https://documentation.onesignal.com/reference/rest-api-overview

Programmatic access to OneSignal messaging, user management, segments, and data exports over HTTPS with rate limiting and retry support.

The OneSignal REST API follows the [REST architecture](https://en.wikipedia.org/wiki/Representational_state_transfer) and provides programmatic access to core messaging and user features. Use the API to send push notifications, emails, and SMS, manage Users, Subscriptions, Segments, export data, and configure apps.

## Which API to use

| Goal                          | API                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| Send a push, email, or SMS    | [Create Message](/reference/create-message)                                                              |
| Add or update user data       | [Create User](/reference/create-user) / [Update User](/reference/update-user)                            |
| Target a group of users       | [Create Segments](/reference/create-segments) or use [Filters](/reference/create-message#filters) inline |
| Export analytics or user data | [CSV Export](/reference/csv-export) / [CSV of Events](/reference/export-csv-of-events)                   |
| Manage app configuration      | [Create App](/reference/create-an-app) / [Update App](/reference/update-an-app)                          |

***

## Requirements

**General**

* **HTTPS required**: All API requests must use HTTPS with **TLS 1.2 or higher** on port `443`.
* **Network access**: Firewalls or proxies must allow **outbound traffic** to `https://api.onesignal.com` on port `443`.
* **DNS TTL**: Clients must respect OneSignal’s DNS **TTL of 300 seconds** to avoid stale IP resolution.

**Incoming Traffic to OneSignal (API & SDK Requests)**

All incoming API traffic—whether from your backend, the OneSignal SDKs, or the dashboard—passes through **Cloudflare**, which serves as the global edge network.

* You may see Cloudflare IP addresses in logs.
* Cloudflare IPs may change over time.
* If you maintain a strict firewall, use Cloudflare’s official [IP ranges](https://www.cloudflare.com/ips/)

<Warning>
  Avoid allowlisting specific Cloudflare IPs, as they may change without notice.
</Warning>

**Outgoing Traffic from OneSignal (Webhooks & Event Streams)**

For features where OneSignal sends HTTP requests to your servers (such as webhooks or event streams), traffic originates from OneSignal infrastructure running on Google Cloud Platform (GCP) in the `europe-west4` region (Groningen, Netherlands).

* Allow inbound traffic from `https://api.onesignal.com`, **or**
* Use GCP’s maintained IP range list and filter by `europe-west4` region: [GCP IP ranges](https://www.gstatic.com/ipranges/cloud.json)

<Note>
  OneSignal supports [IP allowlisting](/docs/en/keys-and-ids) with REST API keys.
</Note>

***

### Platform-specific network requirements

#### FCM (Google Android and Chrome push)

* Required ports: `5228`, `443`, `5229`, and `5230`
* No IP allowlisting needed
* More info: [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

#### APNs (Apple iOS, iPadOS, Safari push)

* Required ports: `5223`, `443`, and `2197`
* Recommended servers:
  * Sandbox: `api.sandbox.push.apple.com:443`
  * Production: `api.push.apple.com:443`
  * IP range: `17.0.0.0/8`
* More info:
  * [Apple Support](https://support.apple.com/en-us/102266)
  * [APNs Developer Docs](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns?language=objc)

***

## Core API capabilities

### Send messages

See the [Create Message guide](/reference/create-message) to get started. Programmatically send:

<Columns>
  <Card title="Push Notifications" icon="bell" href="/reference/push-notification">
    Send push notifications to apps and websites.
  </Card>

  <Card title="Email" icon="envelope" href="/reference/email">
    Send transactional and promotional emails.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/reference/sms">
    Send SMS or MMS messages globally.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="/reference/start-live-activity">
    Send Live Activity updates to iOS devices.
  </Card>
</Columns>

<Note>
  For platform-specific features like personalization, throttling, and frequency capping, see the [Push](/docs/en/push), [Email](/docs/en/email-messaging), [SMS](/docs/en/sms-messaging), and [Live Activities](/docs/en/live-activities) overview guides.
</Note>

***

### Manage templates

[Templates](/docs/en/templates) are reusable push, email, and SMS messages that simplify development and improve consistency.

<Columns>
  <Card title="Create template" icon="plus" href="/reference/create-template">
    Save a reusable message layout for push, email, or SMS.
  </Card>

  <Card title="Update template" icon="pen-to-square" href="/reference/update-template">
    Modify an existing template's content or settings.
  </Card>

  <Card title="View templates" icon="eye" href="/reference/view-templates">
    List all templates in your app with their metadata.
  </Card>

  <Card title="Delete template" icon="trash" href="/reference/delete-template">
    Permanently remove a template from your app.
  </Card>
</Columns>

***

### Track custom events

[Custom events](/docs/en/custom-events) record user actions like purchases, content views, or milestones. Use them to enter users into [Journeys](/docs/en/journeys-settings) or trigger [Wait Until](/docs/en/journeys-actions) nodes.

<Card title="Create custom events" icon="bolt" href="/reference/create-custom-events">
  Record user events to trigger Journeys and track behavior.
</Card>

***

### Manage Users and Subscriptions

See the [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) guides for more details.

<Columns>
  <Card title="Create user" icon="user-plus" href="/reference/create-user">
    Create a user with optional aliases and subscriptions.
  </Card>

  <Card title="View user" icon="eye" href="/reference/view-user">
    View user details.
  </Card>

  <Card title="Update user" icon="user-pen" href="/reference/update-user">
    Modify a User's properties, tags, or aliases.
  </Card>

  <Card title="Delete user" icon="user-minus" href="/reference/delete-user">
    Permanently remove a User and all associated data.
  </Card>
</Columns>

***

### Manage Segments

[Segments](/docs/en/segmentation) group Users by filters for targeted messaging.

<Columns>
  <Card title="Create Segments" icon="plus" href="/reference/create-segments">
    Define a new Segment with filters to group Users.
  </Card>

  <Card title="Update Segment" icon="pen-to-square" href="/reference/update-segment">
    Modify a Segment's name or replace its filters.
  </Card>

  <Card title="Delete Segments" icon="trash" href="/reference/delete-segments">
    Permanently remove a Segment from your app.
  </Card>
</Columns>

<Note>
  You can also target users dynamically using [filters](/reference/create-message#filters) without creating persistent segments.
</Note>

***

### Export data

For analytics breakdowns, see [Analytics overview](/docs/en/analytics-overview).

<Columns>
  <Card title="Export CSV of subscriptions" icon="file-export" href="/reference/csv-export">
    Export all user and subscription data.
  </Card>

  <Card title="Export CSV of events" icon="file-export" href="/reference/export-csv-of-events">
    Export events like sent, received, and clicked.
  </Card>

  <Card title="View messages" icon="eye" href="/reference/view-messages">
    View message details and analytics.
  </Card>

  <Card title="View message" icon="magnifying-glass" href="/reference/view-message">
    View individual message details.
  </Card>
</Columns>

***

### Manage Apps & API Keys

OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See [Apps, orgs, & accounts](/docs/en/apps-organizations).

<Columns>
  <Card title="Create an app" icon="plus" href="/reference/create-an-app">
    Register a new app with platform credentials.
  </Card>

  <Card title="Update an app" icon="pen-to-square" href="/reference/update-an-app">
    Modify app settings or platform credentials.
  </Card>

  <Card title="View single app" icon="eye" href="/reference/view-an-app">
    Retrieve configuration and details for one app.
  </Card>

  <Card title="View multiple apps" icon="list" href="/reference/view-apps">
    List all apps in your account.
  </Card>
</Columns>

#### API key management

See [Keys & IDs](/docs/en/keys-and-ids) for more details.

<Columns>
  <Card title="Create API key" icon="key" href="/reference/create-api-key">
    Generate a new API key with specific permissions.
  </Card>

  <Card title="View API keys" icon="eye" href="/reference/view-api-keys">
    List all API keys and their permissions for your app.
  </Card>

  <Card title="Delete API key" icon="trash" href="/reference/delete-api-key">
    Revoke an API key permanently.
  </Card>

  <Card title="Update API key" icon="pen-to-square" href="/reference/update-api-key">
    Modify an API key's permissions or IP allowlist.
  </Card>
</Columns>

***

## Error handling and retries

The OneSignal API may return temporary errors such as `429` (rate limited), `5xx` (server errors), or timeouts. When this happens, the request may still be processing. If you retry failed requests, always use an `idempotency_key` and follow the recommended retry delays to avoid duplicate messages.

<Card title="Rate limits and error handling" icon="triangle-exclamation" href="/reference/rate-limits">
  Retry strategies, error definitions, and recovery steps.
</Card>

***

## FAQ

### What is the timeout for API responses?

* Default: **100 seconds**
* If you're unsure whether a request completed, use an [`idempotency_key`](/reference/idempotent-notification-requests) to safely retry.
* See [Rate limits and error handling](/reference/rate-limits) for more details.

### Do I need to download or renew certificates to call the OneSignal API?

No. The OneSignal API uses HTTPS with a publicly trusted TLS certificate managed by Cloudflare. These edge certificates renew automatically and are trusted by all major browsers, operating systems, and runtimes.

If your network pins a specific leaf certificate, it will expire and rotate every few months — this is normal Cloudflare behavior. Trust the root and intermediate CAs in the chain instead of the leaf certificate to avoid disruption.

<Accordion title="Certificate pinning details and workarounds">
  * **Best practice**: Trust the root and intermediate CAs in the chain instead of the rotating leaf certificate.
  * **If you must pin a certificate**: Pin the public key (SPKI) of the CA or use a backup key set, not the exact leaf certificate.
  * **Fetching the current certificate**: If your process requires the active leaf certificate, retrieve it directly:

  ```bash theme={null}
  SERVERNAME=api.onesignal.com
  echo -n | openssl s_client -connect $SERVERNAME:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/${SERVERNAME}_current.pem
  ```

  To retrieve the full chain, add the `-showcerts` flag to `openssl s_client`.

  See [Cloudflare SSL/TLS documentation](https://developers.cloudflare.com/ssl/get-started/) and [Cloudflare Edge Certificates documentation](https://developers.cloudflare.com/ssl/edge-certificates/) for more details.
</Accordion>

### Why am I getting a 403 Forbidden error?

A `403` response means the API key is valid but does not have permission for the requested operation. Check the following:

* **Wrong key type**: App API keys work for app-level endpoints (sending messages, managing Users). Organization API keys are required for org-level endpoints (creating apps, managing API keys). See [Keys & IDs](/docs/en/keys-and-ids) for details.
* **IP allowlisting**: If IP allowlisting is enabled on your API key, requests from IPs not on the list are denied. Verify your server's IP is included.
* **Revoked or rotated key**: If the key was recently rotated, the old key is no longer valid. Update your integration with the new key.

### Why am I getting "UnknownHostException - Unable to resolve host api.onesignal.com"?

This error means your environment cannot resolve the DNS for `api.onesignal.com`. Common causes:

* **Firewall or proxy blocking DNS**: Ensure your network allows outbound DNS queries and traffic to `api.onesignal.com` on port `443`.
* **No internet connectivity**: Verify the device or server has an active network connection.
* **DNS server misconfiguration**: Try a public DNS resolver like `8.8.8.8` (Google) or `1.1.1.1` (Cloudflare) to rule out local DNS issues.
* **Stale DNS cache**: Flush your local DNS cache and ensure your client respects the TTL of 300 seconds.


# Rotate API key
Source: https://documentation.onesignal.com/reference/rotate-api-key

POST /apps/{app_id}/auth/tokens/{token_id}/rotate
Rotate an existing App API Key (Rich Authentication Token) for a OneSignal app. Useful when a token is compromised or needs replacement without creating a new key from scratch.

## Overview

Use this API to rotate a **Rich Authentication Token** (App API Key) for a specific OneSignal app. Rotating a key revokes the current token and generates a new one under the same configuration—ideal when a token is lost or compromised but you don’t want to recreate and reconfigure it from scratch.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can rotate an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# SMS
Source: https://documentation.onesignal.com/reference/sms

POST /notifications?c=sms
Send a message using the SMS channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for SMS and MMS. See [Push notification](/reference/push-notification) or [Email](/reference/email) to send to those channels.

Ensure your [SMS setup](/docs/en/sms-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***

## Trackable links

Add trackable links to your SMS `contents` using [liquid syntax](/docs/en/using-liquid-syntax) in the format `{{'your_url' | track_link}}`.

Example:

```json JSON theme={null}
{
  "contents": {
    "en": "Hi, here's my link: {{'https://example.com' | track_link}} "
  }
}
```

In this example, the liquid syntax block will be replaced with a trackable short link and display in the message as: `1sgnl.co/XXXX`.

<Note>
  See [SMS trackable links](/docs/en/links#sms) for more details.
</Note>

***


# Start Live Activity
Source: https://documentation.onesignal.com/reference/start-live-activity

POST /apps/{app_id}/activities/activity/{activity_type}
Remotely start a Live Activity on iOS devices via OneSignal's REST API. Define the activity type, target users, and send dynamic, updatable content directly to a Live Activity interface.

## Overview

Remotely start an iOS Live Activity using OneSignal’s REST API. Live Activities provide real-time updates directly on the lock screen and Dynamic Island (on supported devices), enhancing user engagement with ongoing events like sports games, deliveries, or countdowns.

***

## How to use this API

1. Define a Live Activity in your app. See [Live Activities developer setup](/docs/en/live-activities-developer-setup) to get started.
2. Use the `activity_type` parameter to specify the type of the Live Activity UI to use.
3. Select your target audience to receive the Live Activity. Target all or individual users.
4. Generate a unique `activity_id` to track and manage your Live Activity.
5. Use the `event_attributes` parameter to initialize the Live Activity with static data.
6. Use the `event_updates` parameter to update the Live Activity with dynamic content.

### Select your target audience

Before sending a message, you need to determine who should receive it. OneSignal offers three targeting options:

1. **Aliases & Subscription IDs**: Send messages to specific users using unique identifiers such as External ID (recommended), OneSignal ID, custom alias, or subscription ID.
2. **Segments**: Target predefined user groups based on attributes and behavior.
3. **Filters**: Create custom targeting rules using user properties, such as tags, location, or activity.

<Note>
  You can only use one targeting method per message. For example, you cannot combine alias-based targeting with filters in the same request.

  See [Select your target audience](/reference/create-message#select-your-target-audience) for more information.
</Note>

### Set a unique `activity_id`

* Set a unique `activity_id` to track and manage the Live Activity. This value is crucial for maintaining a consistent reference to the Live Activity across different devices and sessions. Consider using a UUID, CUID, or NanoID for this parameter.
* Ensure that the `activity_id` is unique and consistently used for each Live Activity to avoid conflicts and ensure accurate tracking.

  ```json Example theme={null}
  {
    "activity_id": "217aae2b-42ee-4097-bc3f-b7a6e9d15b9b",
    ...
  }
  ```

<Info>
  See [Live Activities developer setup](/docs/en/live-activities-developer-setup) guide for more information.
</Info>

### Set `event_attributes` to initialize the Live Activity

Set default/static data to display in the Live Activity upon start.

```json Example theme={null}
{
  "event_attributes": {
  	"awayTeam": "Away Team Name",
    "homeTeam": "Home Team Name"
  }
}
```

### Set `event_updates` for dynamic content

The content used to update a running Live Activity. The object must conform to the `ContentState` interface defined within your app's Live Activity. See [Live Activities developer setup](/docs/en/live-activities-developer-setup).

Ensure that the `event_updates` object matches the [`ContentState`](https://developer.apple.com/documentation/activitykit/activityattributes/contentstate#) interface exactly as defined in your Live Activity implementation. Inconsistencies can cause Live Activities to fail to display.

```json Example theme={null}
{
  "event_updates": {
    "quarter": 1,
    "homeScore": 70,
    "awayScore": 78,
    "inTimeout": false
  }
}
```

***


# Transfer Subscription
Source: https://documentation.onesignal.com/reference/transfer-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/owner
Transfer a Subscription to a different user within the same OneSignal app. Useful for associating existing Subscriptions like push, email, or SMS with a new or updated user identity.

## Overview

Use this API to transfer a Subscription from one user to another within the same OneSignal app.

It is highly recommended to use our web and mobile SDKs to set and update the External ID with the `login` method instead of this API. Your app or website may continue to be setting the wrong External ID. Make sure to only use this API if you are setting the same External ID within your app or website.

This is typically used when:

* You want to reassign an existing push, email, or SMS Subscription to a new or updated user.
* You have changed how you're identifying users (e.g., migrating from anonymous to known users).

<Note>
  - Subscriptions **cannot be transferred across different OneSignal apps**.
  - For email and SMS Subscriptions, you can instead create new ones using [Create User](/reference/create-user).
  - For push Subscriptions, platform limitations may apply—see [Subscriptions](/docs/en/subscriptions#importing-push-subscriptions) for details.
</Note>

***

## How to Use This API

### Required Path Parameter: `subscription_id`

You must know the `subscription_id` of the subscription to be transferred. This is a unique UUID assigned by OneSignal.

### Required Body Parameter: `identity` (object)

This specifies the user the subscription should be moved to. Only **one alias** should be used per request. You can identify the target user using one of:

* `external_id` (recommended)
* `onesignal_id`
* A [custom alias](/docs/en/aliases)

***


# Unsubscribe email with token
Source: https://documentation.onesignal.com/reference/unsubscribe-with-token

POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
Unsubscribe an email address from future messages by calling this API from your custom unsubscribe page. Automatically disables the associated email subscription using a token-based approach.

## Overview

Use this API to unsubscribe an email address directly from your custom unsubscribe landing page. It is ideal when building branded opt-out experiences and enables you to track which email caused the unsubscribe.

When invoked, this endpoint:

* Sets the email Subscription's `enabled` property to `false`
* Prevents further messages from being sent to the email address unless explicitly overridden (see [Overriding unsubscribes](/reference/email#body-include-unsubscribed))
* Email Subscriptions can be re-subscribed using the [Update Subscription](/reference/update-subscription) API

<Tip>
  For instructions on setting up a custom unsubscribe page, see [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page).
</Tip>

***

## How to Use This API

### Step 1: Set Up Your Custom Unsubscribe Page

Follow the guide to [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page). You'll add a custom unsubscribe URL to your email templates using Liquid syntax.

Example URL in your email template:

```liquid theme={null}
https://yourdomain.com/unsubscribe?app_id={{ app_id }}&notification_id={{ notification_id }}&token={{ token }}
```

### Step 2: Extract the Parameters

When a user clicks the unsubscribe link, your custom unsubscribe page should extract the following from the URL:

* `app_id`: OneSignal app ID
* `notification_id`: The ID of the specific email message sent
* `token`: The email token, a secure reference to the subscription

### Step 3: Call the API

When the user confirms they want to unsubscribe (e.g., clicks a button on your unsubscribe page), make a POST request to this endpoint:

```
POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
```

Example Request (JavaScript):

```js theme={null}
fetch("https://api.onesignal.com/apps/your-app-id/notifications/your-notification-id/unsubscribe?token=abc123xyz", {
  method: "POST"
});
```

<Info>
  No request body or authentication is required. The token acts as a secure identifier.
</Info>

<Note>
  * This API only works for email subscriptions.
  * It should only be used from a server or frontend context that you control (e.g., your custom unsubscribe page).
  * Once unsubscribed, the email address will not receive future emails from your app unless resubscribed.
</Note>

***


# Update an app
Source: https://documentation.onesignal.com/reference/update-an-app

PUT /apps/{app_id}
Use to update the name or push platform configuration of an existing app. This guide explains required parameters and platform-specific update rules

## Overview

Use this API to programmatically update an existing OneSignal app. This is useful when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

***

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Warning>
  If you change your FCM Service Account JSON file to a different Firebase project, your Android Subscriptions tied to the current project will become invalid. They will not be able to receive push notifications until they open your app again with this new FCM Service Account JSON file.
</Warning>

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need help Base64 encoding your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns). **You will likely never need to update these parameters if set correctly during app creation**:

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates). **These must be updated every year which is why we recommend using p8 authentication**:

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Update API key
Source: https://documentation.onesignal.com/reference/update-api-key

PATCH /apps/{app_id}/auth/tokens/{token_id}
Update a Rich Authentication Token (App API Key) for a OneSignal app. Modify the token's name or IP allowlist settings using your Organization API Key.

## Overview

Use this API to update the properties of a specific **Rich Authentication Token** (App API Key) for a OneSignal app. You can change the name, IP allowlist mode, or the list of allowed IPs. This is helpful for adjusting access rules without needing to recreate the key.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Update Live Activity
Source: https://documentation.onesignal.com/reference/update-live-activity-api

POST /apps/{app_id}/live_activities/{activity_id}/notifications
Update or terminate running iOS Live Activities using OneSignal’s Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

## Overview

Update or terminate running iOS Live Activities using our REST API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

Before using this API, ensure your app is properly configured by following the [Live Activities developer setup](/docs/en/live-activities-developer-setup).

## How to Use this API

1. Select the Live Activity to update by specifying its `activity_id` in the URL. This is set when using the:

* [Start Live Activity API](/reference/start-live-activity)
* [Triggering it in-app](/docs/en/live-activities-developer-setup).
* [`LiveActivities.enter` SDK method](/docs/en/mobile-sdk-reference#enter)

2. Update the state of the Live Activity by setting the `event_updates` parameter to a JSON object that matches the structure of the `ActivityAttributes.ContentState` struct defined in your Live Activity widget extension.

3. When ready to terminate the Live Activity:

* Set the `event` parameter to `end`
* Include a `dismissal_date` if you want the Live Activity to be dismissed in less than 4 hours.
* Set the `dismissal_date` to a time in the past to dismiss the Live Activity immediately. User must have clicked "Allow" for the Live Activity to be removed programmatically.

<Warning>
  Once a Live Activity `activity_id` is ended, you cannot update it. This includes changing the `dismissal_date` or `event` parameter.

  If the Live Activity is not being dismissed immediately, it is either because:

  * The `activity_id` has already been ended.
  * The user has not clicked "Allow" for the Live Activity to be removed programmatically.
</Warning>

***


# Update segment
Source: https://documentation.onesignal.com/reference/update-segment

PATCH /apps/{app_id}/segments/{segment_id}
Update an existing segment's name and/or filters. The name parameter is always required. When filters are provided, all existing filters are replaced with the new ones.

## Overview

Update an existing segment's name and/or filters. This API allows you to modify [Segments](/docs/en/segmentation) programmatically without having to delete and recreate them.

<Note>
  The `name` parameter is always required, even if you're not changing it. When filters are provided, all existing filters are **replaced** with the new ones. Omit the `filters` parameter to keep existing filters intact. The `filters` array cannot be empty—if provided, it must contain at least one filter.
</Note>

***

## How to use this API

### Update segment name only

To update just the segment name without changing filters:

```json theme={null}
{
  "name": "New Segment Name"
}
```

### Update segment description

Update the optional `description` (max 255 characters). Pass an empty string to clear the existing description; omit the field to leave it unchanged.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION"
}
```

### Update segment filters

To update the segment filters (this replaces all existing filters), provide the `name` (required) and `filters`:

```json theme={null}
{
  "name": "Updated Segment",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "5"},
    {"operator": "AND"},
    {"field": "tag", "key": "subscription", "relation": "=", "value": "premium"}
  ]
}
```

### Filter syntax

The filter syntax is identical to the [Create segment](/reference/create-segments) API. Available filters include:

* `tag` - Filter by Tags
* `last_session` - Filter by last active time
* `first_session` - Filter by first session time
* `session_count` - Filter by number of sessions
* `session_time` - Filter by total usage duration
* `language` - Filter by user language
* `app_version` - Filter by app version
* `location` - Filter by GPS coordinates
* `country` - Filter by country

Use `AND` and `OR` operators to combine filters:

```json theme={null}
{
  "name": "Engaged Premium Users",
  "filters": [
    {"field": "tag", "key": "plan", "relation": "=", "value": "premium"},
    {"operator": "AND"},
    {"field": "session_count", "relation": ">", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "vip", "relation": "=", "value": "true"}
  ]
}
```

***

## Response

### Success response

```json theme={null}
{
  "success": true,
  "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19"
}
```

### Error responses

| Status Code | Description                                                                              |
| ----------- | ---------------------------------------------------------------------------------------- |
| 400         | Bad request - Invalid filters, duplicate segment name, or segment used by active Journey |
| 403         | Forbidden - API not available for your plan                                              |
| 404         | Not found - Segment does not exist                                                       |
| 429         | Rate limit exceeded                                                                      |

***


# Update Subscription by ID
Source: https://documentation.onesignal.com/reference/update-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}
Update properties on an existing OneSignal subscription using its subscription_id. Commonly used to enable or disable a subscription when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties by `subscription_id`.

This endpoint is primarily used by the OneSignal SDK to manage subscription state.

Most external use cases are better served by the [Update Subscription by token](/reference/update-subscription-by-token) API, which can use the Email Address or Phone Number as the `token` or the [Update User](/reference/update-user) API, which allows for updating user-level data.

<Note>
  For **email opt-outs**, it's recommended to use the [Unsubscribe Email (with token)](/reference/unsubscribe-with-token) API instead. This avoids the need to store or manage the `subscription_id`.
</Note>

***

## How to use this API

**Required:** `subscription_id`

To update a subscription, you **must know the `subscription_id`**. This is a UUID generated by OneSignal and is immutable.

* You can retrieve a subscription ID by querying the [User object](/docs/en/users).
* See the [Subscriptions](/docs/en/subscriptions) guide for an explanation of how subscription IDs are generated and used.

<Note>
  You **cannot** update the `type` of a Subscription. If the `type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the Subscription with the correct type.
</Note>

***


# Update Subscription by token
Source: https://documentation.onesignal.com/reference/update-subscription-by-token

PATCH /apps/{app_id}/subscriptions_by_token/{token_type}/{token}
Update properties on an existing Subscription using its token. Commonly used to enable or disable subscription status when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties.

This API can be useful if:

* You only know the `token` and `token_type` and want to update metadata or status flags directly.
* You are managing Subscription status outside of the OneSignal SDK. Like with a [custom preference page or unsubscribe page](/docs/en/create-custom-unsubscribe-page).

***

## How to use this API

To update a Subscription, you must know the `token_type` and the `token`.

The `token_type` is the [Subscription's type](/docs/en/server-sdk-reference#subscription-types) (e.g., `Email`, `SMS`, `iOSPush`, `AndroidPush`, etc.).

The `token` is the push token, email address, or phone number associated with the Subscription.

Ensure the `token` is valid and correctly formatted for the chosen `token_type`.

* **Email format:** Should be a valid email address that you confirmed can receive emails.
* **SMS format:** Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164).
* **iOSPush APNS token format:** 64 characters, hexadecimal characters only (0-9,a-f).
* **AndroidPush FCM token format:** Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.

<Warning>
  You **cannot** update the `token_type` and `token` of a Subscription with this API. If the `token_type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the subscription with the correct type.

  If multiple Subscriptions are found for the `token` and `token_type`, an `Http 400` error is returned with a list of subscription IDs that match the criteria.
</Warning>

***


# Update template
Source: https://documentation.onesignal.com/reference/update-template

PATCH /templates/{template_id}?app_id={app_id}
Update existing OneSignal message templates for push, email, or SMS. Changes apply immediately across dashboard and API usage via the `template_id` reference.

## Overview

This endpoint allows you to update an existing push, email, or SMS template in your OneSignal app. Once updated, the changes are applied immediately and reflected across both the Dashboard and API when using the associated `template_id`.

Templates are updated using the same structure as when [creating templates](/reference/create-template).

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

To update a template, you must supply:

* Your **OneSignal App ID** found in [Keys & IDs](/docs/en/keys-and-ids).
* The **Template ID**

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***

## Channel-Specific Requirements

### Push Templates

* The `contents` property must use the `en` (English) key along with other languages you want to support.
* All [Push Notification Properties](/reference/push-notification) are valid.
* All platforms are enabled by default. To limit, explicitly enable desired ones (e.g., `isAndroid: true` disables iOS and Web).

### Email Templates

* Set `isEmail: true`
* Include `email_subject` and `email_body`
* All [Email Channel Properties](/reference/email) are supported.

### SMS Templates

* Set `isSMS: true`
* All [SMS Channel Properties](/reference/sms) are supported.

***


# Update user
Source: https://documentation.onesignal.com/reference/update-user

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}
Modify a user's properties.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint updates user-level properties for an existing user in your OneSignal app.

* To change a user's `identity` like `external_id` or custom [Aliases](/docs/en/aliases), use the [Create alias](/reference/create-alias) and [Delete alias](/reference/delete-alias) APIs.
* To manage a user's `subscriptions`, use the [Create Subscription by alias](/reference/create-subscription) or [Create user](/reference/create-user) APIs.

***

## How to use this API

You must supply an alias in the request path:

* `alias_label`: The type of identifier (e.g., `external_id`, `onesignal_id`, or a custom alias label).
* `alias_id`: The corresponding value for that label.

See [Users](/docs/en/users) and [Aliases](/docs/en/aliases) for more info.

***


# View an app
Source: https://documentation.onesignal.com/reference/view-an-app

GET /apps/{app_id}
View the details of a single OneSignal app

## Overview

Use this API to retrieve metadata and platform configuration for a single OneSignal app associated with your account. This includes app names, App ID, Subscription counts, timestamps, and push platform credentials (Android/FCM, iOS/APNS, Web Push, Safari), making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

***

## How to use this API

To retrieve your app, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View API keys
Source: https://documentation.onesignal.com/reference/view-api-keys

GET /apps/{app_id}/auth/tokens
View the details of all of your current app API keys (Rich Authentication Token) for a single OneSignal app.

## Overview

This API is helpful for auditing and managing the API keys (Rich Authentication Tokens) associated with an app. It returns metadata for each token, including:

* Token name and ID
* IP allow list mode and associated CIDR ranges (if any)
* Creation and last updated timestamps

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

***


# View apps
Source: https://documentation.onesignal.com/reference/view-apps

GET /apps
Retrieve a list of all OneSignal apps associated with your account, including key app details like name, App ID, subscription counts, and timestamps. Useful for managing multiple apps through the OneSignal API.

## Overview

Use this API to retrieve metadata for all OneSignal apps associated with your account. This includes app names, App IDs, subscription counts, and timestamps, making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

<Warning>
  This API is limited to return a maximum of 1000 Apps. If you need access to more, then you should store the `app_id` and `name` for each of your apps on your own server to look up with the [View an app](/reference/view-an-app) API to get data for each app separately. Also, if you need to delete apps, then you can provide the `app_id` and `name` to OneSignal Support and ask for these to be deleted.
</Warning>

***

## How to use this API

To retrieve your apps, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View player
Source: https://documentation.onesignal.com/reference/view-device

GET https://onesignal.com/api/v1/players/{player_id}

Retrieve a single player record (Subscription) data registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `player_id` | string | Yes      | The OneSignal ID of the device. |

***

## Query Parameters

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `app_id`  | string | Yes      | Your OneSignal App ID. |

***

## Headers

| Header          | Value                            | Required | Description                        |
| --------------- | -------------------------------- | -------- | ---------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal LegacyREST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players/player_id_string?app_id=your_app_id HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json{ theme={null}
  "id": "player_id_string",
  "identifier": "push_token_or_email",
  "session_count": 5,
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_os": "14.4",
  "device_type": 1,
  "tags": {
    "level": "10",
    "user_type": "free"
  },
  "last_active": 1625253300,
  "created_at": 1625249800,
  "invalid_identifier": false,
  "external_user_id": "user123"
}
```

### Response Fields

| Field                | Type      | Description                                             |
| -------------------- | --------- | ------------------------------------------------------- |
| `id`                 | string    | OneSignal player ID.                                    |
| `identifier`         | string    | Push token, email, or phone number.                     |
| `session_count`      | integer   | Number of sessions associated with this device.         |
| `language`           | string    | Language set on the device (e.g., "en").                |
| `timezone`           | integer   | Time zone offset in seconds.                            |
| `game_version`       | string    | Version of your app the device is running.              |
| `device_os`          | string    | Operating system version.                               |
| `device_type`        | integer   | Numeric code for platform (0 = iOS, 1 = Android, etc.). |
| `tags`               | object    | Custom tags set on the device.                          |
| `last_active`        | timestamp | Last time the user was active (Unix timestamp).         |
| `created_at`         | timestamp | When the device record was created.                     |
| `invalid_identifier` | boolean   | Whether the push token or identifier is invalid.        |
| `external_user_id`   | string    | Your internal user ID mapped to this device.            |

***

## Errors

* 400 Bad Request – Missing or invalid parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied for this app or resource.
* 404 Not Found – The specified player\_id does not exist.

***


# View players
Source: https://documentation.onesignal.com/reference/view-devices

GET `https://onesignal.com/api/v1/players?app_id={app_id}&limit={limit}&offset={offset}`

Retrieve up to 80,000 player records (Subscriptions) registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Query Parameters

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `app_id`  | string | Yes      | Your OneSignal App ID.                                 |
| `limit`   | int    | No       | Number of entries to return (max 300, default is 300). |
| `offset`  | int    | No       | Result offset for pagination.                          |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players?app_id=your_app_id&limit=100&offset=0 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json theme={null}
{
  "total_count": 6,
  "offset": 0,
  "limit": 300,
  "players": [
    {
      "id": "player_id_1",
      "identifier": "push_token_or_email",
      "session_count": 3,
      "language": "en",
      "timezone": -28800,
      "game_version": "1.0",
      "device_os": "15.0",
      "device_type": 1,
      "tags": {
        "level": "15",
        "user_type": "free"
      },
      "last_active": 1625253300,
      "created_at": 1625249800,
      "invalid_identifier": false,
      "external_user_id": "user123"
    }
  ]
}
```

### Response Fields

| Field                        | Type    | Description                                  |
| ---------------------------- | ------- | -------------------------------------------- |
| `total_count`                | integer | Total number of devices for the app.         |
| `offset`                     | integer | Current pagination offset.                   |
| `limit`                      | integer | Number of devices returned in this response. |
| `players`                    | array   | List of device objects.                      |
| `players[].id`               | string  | Unique OneSignal player ID.                  |
| `players[].identifier`       | string  | Push token, email, or phone number.          |
| `players[].tags`             | object  | Custom tags set on the device.               |
| `players[].external_user_id` | string  | Your internal user ID.                       |

***

## Errors

* 400 Bad Request – Invalid query parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access not allowed for this app or key.

***


# View message
Source: https://documentation.onesignal.com/reference/view-message

GET /notifications/{message_id}?app_id={app_id}
View the details of a single message and the Outcomes associated with it.

## Overview

The View message API allows you to fetch data from a single push, email, or SMS message at a time. If you want to get multiple messages at a time, use the [View messages](/reference/view-messages) API. In most cases, you will likely want to use [Event Streams](/docs/en/event-streams) instead.

Currently this API does not provide Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are only **accessible 30 days after creation**; however, messages sent using the OneSignal dashboard are accessible for the app's lifetime.

See our [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and (after giving your users some time to interact with the message) pull the data if desired.

For example, if you send a message targeting the `include_aliases` parameter, the response will include the aliases you set. If you send with the `included_segments` parameter, then the response will only provide the segments you set. When targeting segments or filters, you can use the [Export audience activity CSV](/reference/export-csv-of-events) API to get the user event data.

To view outcome data for the message, you must include the `outcome_name` parameter with the name of the outcome you want to fetch, along with the accompanying aggregation type (.count or .sum), for example: `os__click.count`. For more information on outcome definitions, see [View Outcomes](/reference/view-outcomes).

***


# View messages
Source: https://documentation.onesignal.com/reference/view-messages

GET /notifications?app_id={app_id}&limit={limit}&offset={offset}&kind={kind}&template_id={template_id}&time_offset={time_offset}
View the details for a collection of messages.

## Overview

The View messages API fetches data for up to 50 push, email, or SMS messages at a time. To fetch a single message, use the [View message](/reference/view-message) API. In most cases, use [Event Streams](/docs/en/event-streams) instead.

This API does not return Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are **retained for 30 days** after creation; messages sent through the OneSignal dashboard are retained for the app's lifetime.

See [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

Use time-offset pagination for sequential pulls of all messages, and standard pagination for ad-hoc queries. For ETL or bulk export pipelines, use [Event Streams](/docs/en/event-streams) instead.

Filter results to a specific message kind or template using the `kind` and `template_id` query parameters. Both filters work with either pagination style.

### Optimized pagination with time offset

To efficiently retrieve all available messages for an app, use `time_offset`-based pagination. When `time_offset` is specified, the sort order changes from descending to ascending — the oldest messages appear first based on the [`send_after` date](/reference/create-message#send-after).

#### Accepted `time_offset` values

* ISO 8601 formatted timestamp — for example, `2025-01-01T00:00:00.000Z` (January 1, 2025, at 00:00 UTC).
* Opaque cursor token (Base64-encoded) — provided in the API response as `next_time_offset`.

<Steps>
  <Step title="Initial fetch">
    To fetch messages from a specific date onward, set `time_offset` to an ISO 8601 formatted timestamp. For example, to retrieve messages sent since January 1, 2025: `time_offset=2025-01-01T00:00:00.000Z`.

    <Note>
      * `time_offset` cannot be used with the standard `offset` parameter.
      * `time_offset` excludes messages that match the exact timestamp to avoid duplicates.
      * The response includes `next_time_offset`, a cursor token for the next page. No decoding required. For example: `"next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="`
    </Note>
  </Step>

  <Step title="Fetch additional pages">
    Use `next_time_offset` from the previous response as the `time_offset` value in the next request. For example: `time_offset=MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw==`.
  </Step>

  <Step title="Continue until completion">
    Repeat the request until an empty `notifications` array is returned, indicating all messages have been fetched.
  </Step>

  <Step title="Handling new messages">
    Because results are sorted ascending, new messages are added to the end. To resume fetching from where you left off, reuse the last `next_time_offset` that returned an empty response.
  </Step>
</Steps>

### Standard pagination

Use the `limit` and `offset` parameters to page through notifications for an app. The maximum result size is 50, and the default `limit` is `50`. Use `limit` to specify the result size and `offset` to increment by the limit value with each request.

For example, the first request uses `offset=0`, the second `offset=50`, the third `offset=100`, and so on.

Standard pagination is convenient for ad-hoc queries but degrades as the `offset` value grows. For sequential pulls of all messages, use time-offset pagination.

***


# View outcomes
Source: https://documentation.onesignal.com/reference/view-outcomes

GET /apps/{app_id}/outcomes?outcome_names={outcome_names}&outcome_time_range={outcome_time_range}&outcome_platforms={outcome_platforms}&outcome_attribution={outcome_attribution}
View and export push notification outcome metrics such as clicks, conversions, and custom events.

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

## Overview

Use this API to retrieve Outcome metrics associated with your OneSignal app, including push notification interactions and custom-defined events. Outcomes include data points like:

* **Clicks**: Number of users who clicked on a push.
* **Confirmed Deliveries**: Number of confirmed message deliveries.
* **Session Durations**: Number of sessions initiated.
* **Custom Events**: Actions like purchases, form submissions, or any event your app tracks via custom Outcome names.

For details on configuring custom Outcomes, refer to the [Outcomes documentation](/docs/en/custom-outcomes).

<Info>
  Outcomes are stored for approximately 30 days. To retain this data, you should regularly export it before it expires.
</Info>

***

## How to use this API

This API allows you to filter and aggregate Outcome data using several query parameters.

### `outcome_names`

Specify one or more Outcome names with an aggregation type suffix (`.count` or `.sum`).

**Default Outcome names:**

* `os__click.count` – Push notification clicks.
* `os__confirmed_delivery.count` – Confirmed deliveries.
* `os__session_duration.count` – Total sessions.

**Custom Outcome names:**

* You can track any custom event name (e.g. `Purchase`, `Signup`).
* If the custom name contains a comma, include only one name per request to avoid parsing issues.
* Example: `outcome_names=os__click.count,Purchase.count`

### `outcome_time_range`

The time range values can be one of the following:

* `1h` = (default) the last 1 hour data.
* `1d` = the last 1 day data.
* `1mo` = the last 1 month data.

### `outcome_platforms`

Maps to the subscription type property. Default is data from all platforms enabled for your OneSignal App.

| `device_type` | `type`      |
| ------------- | ----------- |
| 0             | iOSPush     |
| 1             | AndroidPush |
| 2             | FireOSPush  |
| 5             | ChromePush  |
| 8             | FirefoxPush |
| 11            | Email       |
| 14            | SMS         |
| 17            | SafariPush  |

Example: `outcome_platform=0` for iOS `outcome_platform=17,8` for Safari and Firefox.

### `outcome_attribution`

The way in which the Outcome occurred:

* `direct` = the Outcome occurred when the user interacted with the message. Some Outcomes only have `direct` attribution like `os__click` and `os__confirmed_delivery` because they only occur as the direct result of the message.
* `influenced` = the Outcome occurred within the Time Window of the message being sent, but the user never interacted with the message. See [Outcomes](/docs/en/custom-outcomes) for details.
* `unattributed` = the Outcome occurred without a direct or influenced attribute.
* `total` = (default) the sum of direct+influenced+unattributed.

***


# View segment
Source: https://documentation.onesignal.com/reference/view-segment

GET /apps/{app_id}/segments/{segment_id}
Retrieve details for a single segment by its ID, including subscriber count and optionally segment metadata and filters.

## Overview

Retrieve details for a single segment by its ID. By default, this endpoint returns only the subscriber count. Use the optional `include-segment-detail` parameter to also retrieve segment metadata and filters.

<Note>
  The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard.
</Note>

<Warning>
  **User-based segments not supported**: Segments containing message event or custom event filters (user-based segments) are not yet supported via this API. Attempting to fetch these segments will return a 400 error. These segments can only be managed through the dashboard UI.
</Warning>

***

## How to use this API

### Basic usage

By default, this endpoint returns only the subscriber count for the segment:

```json theme={null}
{
  "subscriber_count": 12345
}
```

### Include segment details

To retrieve full segment details including metadata and filters, set `include-segment-detail=true`:

```
GET /apps/{app_id}/segments/{segment_id}?include-segment-detail=true
```

This returns the subscriber count along with a `payload` object containing segment details:

<CodeGroup>
  ```json Simple filter theme={null}
  {
    "subscriber_count": 12345,
    "payload": {
      "id": "4414c404-56a3-11ed-9b6a-0242ac120002",
      "name": "Subscribed Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {
          "field": "session_count",
          "relation": ">",
          "value": "5"
        }
      ]
    }
  }
  ```

  ```json With AND/OR operators theme={null}
  {
    "subscriber_count": 5678,
    "payload": {
      "id": "5525d515-67b4-22fe-0c7b-1353bd231113",
      "name": "Engaged Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {"field": "session_count", "relation": ">", "value": "2"},
        {"operator": "AND"},
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "last_session", "relation": "<", "hours_ago": "24"}
      ]
    }
  }
  ```
</CodeGroup>

### Filters format

The `filters` array uses the **same format** as the [Create segment](/reference/create-segments) API. This means you can:

* Read filters from this endpoint
* Modify them as needed
* Use them directly with the [Update segment](/reference/update-segment) or [Create segment](/reference/create-segments) APIs

The array contains filter objects and operator objects:

**Filter object** - defines a condition:

| Field                   | Type    | Description                                                                                                                                         |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field`                 | string  | The filter type: `tag`, `last_session`, `first_session`, `session_count`, `session_time`, `language`, `app_version`, `location`, `country`, `email` |
| `relation`              | string  | The comparison operator: `>`, `<`, `=`, `!=`, `exists`, `not_exists`, `in_array`, `not_in_array`, `time_elapsed_gt`, `time_elapsed_lt`              |
| `value`                 | string  | The filter value (for most filter types)                                                                                                            |
| `key`                   | string  | The filter key (required for `tag` filters)                                                                                                         |
| `hours_ago`             | string  | Hours ago value (for `last_session`/`first_session` filters)                                                                                        |
| `radius`, `lat`, `long` | string  | Location parameters (for `location` filters)                                                                                                        |
| `unsupported_in_api`    | boolean | If `true`, this filter cannot be used with Create/Update segment APIs (see note below)                                                              |

**Operator object** - combines filters:

| Field      | Type   | Description                                                                        |
| ---------- | ------ | ---------------------------------------------------------------------------------- |
| `operator` | string | Either `AND` or `OR`. Filters connected with `AND` have higher priority than `OR`. |

<Warning>
  Some segments created via the dashboard UI may contain filter types not supported by the public API (e.g., `message_event`, `custom_event`). These filters will include `unsupported_in_api: true`. You cannot use these filters when creating or updating segments via the API.
</Warning>

### Payload fields

| Field         | Type           | Description                                                                         |
| ------------- | -------------- | ----------------------------------------------------------------------------------- |
| `id`          | string         | The unique identifier for the segment (UUID v4).                                    |
| `name`        | string         | The segment name (max 128 characters).                                              |
| `description` | string \| null | Human-readable description for the segment (max 255 characters). `null` when unset. |
| `created_at`  | integer        | Unix timestamp when the segment was created.                                        |
| `source`      | string         | The source of the segment: `default`, `custom`, or `quickstart`.                    |
| `filters`     | array          | Array of filter and operator objects that define the segment criteria.              |

***


# View segments
Source: https://documentation.onesignal.com/reference/view-segments

GET /apps/{app_id}/segments
Retrieve a list of segments associated with a specific OneSignal app. Useful for programmatically accessing segment metadata such as name, creation date, and status.

## Overview

Retrieve a list of segments associated with a specific OneSignal app. This is helpful when you want to access segment metadata programmatically instead of using the OneSignal Dashboard UI.

<Warning>
  This endpoint only retrieves existing segment metadata. It does not provide the segment filters or user data.
</Warning>

***


# View template
Source: https://documentation.onesignal.com/reference/view-template

GET /templates/{template_id}?app_id={app_id}
Retrieve the details of a specific message template in your OneSignal app using its template ID. This API returns the template content, target channel, and timestamps for creation and last update.

## Overview

This endpoint returns metadata and content for a single template, including:

* Template body/content
* Target delivery channel (e.g., push, email, SMS)
* Creation and last updated timestamps

This is useful for inspecting existing templates before using or updating them.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Required parameters:

* `app_id` (query param): Your OneSignal App ID.
* `template_id` (path param): The unique ID of the template.

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# View templates
Source: https://documentation.onesignal.com/reference/view-templates

GET /templates?app_id={app_id}&limit={limit}&offset={offset}
Retrieve a paginated list of message templates from your OneSignal app. This endpoint returns summary information for each template, including ID, name, creation, and update timestamps.

## Overview

Use this endpoint to retrieve a list of message templates associated with a specific OneSignal app. The response provides summary information only:

* `template_id`
* `name`
* `created_at`
* `updated_at`

<Note>
  This endpoint does **not** return full template content such as message bodies, channel properties, or delivery configuration. For detailed template data, use the [View Template](/reference/view-template) endpoint.
</Note>

***

## How to Use This API

### Required Parameters

* **`app_id`** (query param): The OneSignal App ID whose templates you want to retrieve.

### Optional Parameters

* **`limit`** (query param): Number of templates to return (default: `50`, maximum: `50`).
* **`offset`** (query param): Number of templates to skip. Use for pagination.

### Pagination Example

If your app has 125 templates and you're using the default limit of 50:

1. First request (first 50 templates):\
   `GET /templates?app_id={app_id}&offset=0`

2. Second request (next 50 templates):\
   `GET /templates?app_id={app_id}&offset=50`

3. Third request (final 25 templates):\
   `GET /templates?app_id={app_id}&offset=100`

Repeat the request while adjusting the `offset` until you've retrieved all templates.

***


# View user
Source: https://documentation.onesignal.com/reference/view-user

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}
Retrieve a user including aliases, properties, and subscriptions.

## Overview

* Use this API to retrieve a user's full profile, including identity aliases, user properties, and messaging subscription details across channels.
* This is helpful for verifying user data, debugging subscription issues, or syncing OneSignal user data with your internal systems.

For detailed concepts and guides, see [Users](/docs/en/users), [Subscriptions](/docs/en/subscriptions), and [Aliases](/docs/en/aliases) documentation.

## How to use this API

To look up a user, you must provide both an `alias_label` and an `alias_id`. In most cases, your `external_id` will serve as the `alias_label`, and its value will be passed as the `alias_id`. While you may use a custom alias, we strongly recommend setting and using the `external_id` as your primary user identifier for consistency across platforms.

To retrieve a user using their OneSignal ID, set the `alias_label` to `onesignal_id`. **Note**: When querying with any alias other than `onesignal_id`, authentication is required.

***


# Changelog
Source: https://documentation.onesignal.com/release-notes/changelog

Learn about the latest updates to OneSignal.

Follow along with updates across OneSignal. We're launching new features and improving our product all the time!

<Update label="June 18 2026">
  **AI-assisted SDK installation updated and expanded**

  * AI install prompts have been rewritten and expanded to cover Android, iOS, React Native, Flutter, and Web SDKs.
  * Paste a single ready-made prompt into your AI coding assistant (Cursor, Claude, Copilot, or similar) and the assistant installs the SDK, drops in initialization code, and configures push and in-app messaging automatically.
  * No deep development experience required — marketers and non-technical users can complete SDK setup in minutes.
  * Prompt instructions were revised to fix errors identified during internal testing, so generated integrations are more accurate.
  * Available to all new sign-ups with no enablement required; requires an AI coding tool and access to the app codebase.
</Update>

<Update label="June 15 2026">
  **Extended `in_array` and `not_in_array` relations to the Device Type filter**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `device_type` filter field. Use them to match against a comma-separated list of device types in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "device_type", "relation": "in_array", "value": "iOS,Android"},
    {"operator": "AND"},
    {"field": "device_type", "relation": "not_in_array", "value": "Email"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="June 15 2026">
  **RCS editor experience improvements**

  We've improved how you build and send RCS, giving you a more intuitive editor, clearer approval visibility, and a more graceful SMS fallback experience:

  * **See carrier approval status in settings.** Each sender resource's carrier approval status is now visible at **Settings > SMS > Senders**, so you can track where each carrier stands in the approval process without leaving the dashboard.
  * **Select a sender per RCS template.** In Templates you now choose a specific sender instead of relying on a single global default, improving how RCS sends within Journeys and giving you automations for multiple SMS use cases.
  * **A more intuitive editor.** The composer automatically shows the right editor for the selected sender — the RCS editor for senders with an RCS resource, and the SMS editor for SMS-only senders.
  * **Text only RCS.** A new Text only content type sends plain branded RCS text.

  When a sender gains an approved RCS sending resource, OneSignal automatically prefers RCS for existing automations on that sender, mapping your existing SMS content to RCS so there's no manual rework.

  Available for all customers contracted for RCS. See [RCS messaging](/docs/en/rcs-messaging) for details.
</Update>

<Update label="June 8 2026">
  **Segment editor improvements: multi-value filters, copy filters, and filter JSON**

  Building segments in the dashboard is now faster and more flexible:

  * **Match multiple values in one filter.** The Language, Country, App Version, and User Tag filters now support the "is any of" and "is not any of" relations, so you can match a list of values in a single filter instead of chaining several filters with OR.
  * **Copy filters and filter groups.** Duplicate an individual filter or an entire filter group from the editor to reuse its configuration without rebuilding it by hand.
  * **View and copy filter JSON.** Open the filter JSON panel to see the REST API representation of your segment's filters, then copy it to use directly in the [Create segment](/reference/create-segments) API.
</Update>

<Update label="June 4 2026">
  **Retired Alexa and Windows Phone 8.0 as Device Type filter options**

  The `Alexa` and `Windows Phone 8.0` values are no longer available for the Device Type filter when you create or edit a segment, in both the dashboard and the Create segment API. Selecting either value in the dashboard is no longer possible, and the API rejects them with a validation error.

  Existing segments that already use these values continue to evaluate and deliver as before. To save changes to such a segment, replace the retired Device Type filter first.
</Update>

<Update label="June 2 2026">
  **Extended `in_array` and `not_in_array` relations to tag and app version filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `tag` and `app_version` filter fields, in addition to the `country` and `language` fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"},
    {"operator": "AND"},
    {"field": "app_version", "relation": "not_in_array", "value": "1.0.0,1.0.1"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="May 11 2026">
  **Email BCC is now generally available**

  You can now add BCC (blind carbon copy) recipients to email sends, including templates used in journeys and messages sent via the API. Use BCC to archive customer-facing email to a shared inbox or compliance system, forward sends to third-party services, or keep internal stakeholders copied on transactional sends.

  * Available on all plan types.
  * Maximum of 5 BCC addresses per send.
  * Each BCC recipient counts toward the total email volume for that send (for example, 1,000 primary recipients with 1 BCC address = 2,000 sends).
  * BCC metrics are excluded from analytics.

  See [BCC emails](/docs/en/email-bcc) for setup and usage details.
</Update>

<Update label="May 12 2026">
  **Added `in_array` and `not_in_array` relations for country and language filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `country` and `language` filter fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "in_array", "value": "US,GB,CA"},
    {"operator": "AND"},
    {"field": "language", "relation": "not_in_array", "value": "es,fr"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="April 21 2026">
  **Manage custom aliases from the User Profile**

  You can now view, add, edit, and delete a user's custom aliases directly from the **Aliases** section on the User Profile **Overview** tab, without using the API.

  * Add an alias by entering a label (alias key) and value (alias ID), copy any alias value to the clipboard, edit a value, or remove an alias.
  * Each user supports up to 10 aliases, and alias labels and values can each contain up to 128 characters.
  * `external_id` and `onesignal_id` are reserved and can't be used as custom alias labels.
  * A user must have an External ID set before you can add custom aliases. External ID is still managed separately in the Profile section.

  See [Aliases](/docs/en/aliases) for more details.
</Update>

<Update label="April 17 2026">
  **Role-based access control (RBAC) is now generally available**

  Granular role-based access control has been rolled out to all customers, giving teams more flexibility to support least-privilege access patterns and manage permissions as they scale.

  * **New `team_member` org-level default role.** A baseline role for new users added to an organization.
  * **New `composer` app-level role.** Lets users create and edit messages, templates, segments, and journeys without sending, activating, or deleting content.
  * **Updates to `editor` and `viewer` roles.** Refined permissions for clearer separation of duties.
  * Available roles vary by plan type.

  See [Manage team members](/docs/en/manage-team-members) for the full breakdown of roles, permissions, and plan availability.
</Update>

<Update label="April 16 2026">
  **Light/dark mode toggle for HTML in-app message previews**

  You can now switch between light and dark mode directly in the dashboard when previewing HTML in-app messages, so what you see matches what your users will actually see.

  * A light/dark mode toggle is now available in the in-app message preview for HTML messages.
  * The preview no longer reflects your OS theme. It reflects the mode you select in the dashboard.
  * Previously, the preview always rendered using whatever theme your own computer was set to, with no indication that was the cause, so there was no reliable way to check dark mode designs from the dashboard.

  HTML in-app messages do not automatically get a dark mode. The message still has to be coded for it using `@media (prefers-color-scheme: dark)` styles. If your message doesn't include those styles, toggling to dark mode in the preview won't change how it looks.

  The toggle is available for HTML in-app messages only. Block-type in-app messages are not included in this release. Generally available for all customers using HTML in-app messages.

  See [Design your in-app message with HTML](/docs/en/design-your-in-app-message-with-html) for how to add dark mode support.
</Update>

<Update label="April 15 2026">
  **Standardized delivery metrics across all channels**

  Delivery metric terminology is now consistent across every messaging channel in OneSignal. All channels now share a unified delivery hierarchy: Audience → Sent → Delivered, with the same definitions everywhere. Labels have been aligned across delivery reports, journey reports, engagement trends, and CSV exports. The [Metrics Glossary](/docs/en/analytics-metrics-glossary) has been fully rewritten as the canonical reference for every metric definition.
</Update>

<Update label="April 10 2026">
  **Audience counts now show subscribed and unsubscribed breakdowns**

  The segment editor now shows both subscribed and unsubscribed counts for every subscription-based segment, with a per-channel breakdown across push, email, and SMS. Previously, only the opted-in (subscribed) count was visible.

  Additional improvements:

  * Counts always return within approximately 15 seconds. Exact counts are shown when possible; estimates are used when an exact count can't be calculated in time.
  * Estimates are clearly labeled: above 10,000 with a +/- margin of error (e.g. 140,000 +/- 5,000), and below 10,000 as a less-than value (e.g. \<4,800).
  * Estimates will never show 0 for a segment. Previously for segments with very small but non-zero membership, estimates could incorrectly show as 0.

  This release covers subscription-based segments. User-based segment improvements are coming later in Q2 2026.
</Update>

<Update label="April 7 2026">
  **Updated User Profile page**

  The User Profile page has been redesigned with a tabbed layout and several new management actions directly on the page:

  * Add and remove Subscriptions from a User
  * Search across a User's data tags
  * Perform more direct edits and admin actions without leaving the profile

  The previous profile view is still accessible from the **Actions** menu if you need it.
</Update>

<Update label="March 25 2026">
  **test users now apply at the User level**
  Marking a Subscription as a test user now automatically marks all Subscriptions for that User as test users, effectively creating a Test User.

  * Any new Subscriptions added to a Test User will automatically be marked as test users.
  * Test User is now a User-level property rather than a Subscription-level one.

  **OneSignal Server SDKs just got their first v5 stable release!**

  After a period of testing and iteration, v5 is now the default version users will get when installing any of our server SDKs. Here are the current versions included in this release:

  | Language | Version |
  | -------- | ------- |
  | Node.js  | 5.4.0   |
  | Go       | 5.3.0   |
  | Java     | 5.3.0   |
  | .NET     | 5.4.0   |
  | Rust     | 5.3.0   |
  | Ruby     | 5.3.0   |
  | Python   | 5.3.0   |
  | PHP      | 5.3.0   |

  This release pairs well with our recently refreshed Server SDK Reference, giving developers a solid starting point for integrating with the OneSignal API.
</Update>

<Update label="March 20 2026">
  **Audit Log Export is now in GA**

  * Customers can now export audit logs. Customers can export 2 days for free tier and up to 90 days with security and legal entitlement (either as individual SKU or enterprise plan).
  * Provides customers additional metadata details and allows them to filter through data locally for their own audits and consumption with their own tools.

  **Failed Reasons in Audience Activity for everyone!**

  * Free plan users can now see exactly why individual audience members failed to receive a notification — directly in the Audience Activity view.
  * When a notification fails, especially common when troubleshooting set up, free users had no way to know whether the problem was a bad token, an unsubscribed user, or a device issue — leaving them guessing and unable to fix anything. Now they get the same failure visibility paid users have, so they can debug and get set up properly.
  * Same data retention as audience activity (30 days)
</Update>

<Update label="March 17 2026">
  **Data Model Updates and Field Deprecations**

  To improve platform performance, strengthen data integrity, and reduce the risk of configuration errors, we are introducing several updates to the OneSignal data model.

  These changes will take effect **April 15, 2026.**

  **Field Limits**

  We are introducing limits on two user fields to improve consistency and prevent unexpected behavior.

  Existing records exceeding these limits will not be modified to avoid disrupting current data and operations.

  **External ID**

  * `external_id` values can contain up to 128 characters.

  **Aliases**

  * Each user can have up to 10 aliases.
  * Each alias key and value can contain up to 128 characters.

  **Field Deprecations**

  We are deprecating several legacy Subscription fields that are no longer actively used:

  * `amount_spent`
  * `rooted`
  * `bought_sku`
  * `app_interests`
  * `purchased_items`

  After April 15, 2026, these fields will no longer be available in:

  * Segment Builder
  * API requests
  * Event streams
  * Webhooks

  **Impact for Customers Using These Fields**

  If your implementation currently references any of these fields:

  **Segments:** Segments using these fields will be paused and labeled for your review.

  **Journeys:** Journeys depending on those segments will be archived.

  **Event Streams and Webhooks:** These fields will return empty values.

  **What You Need to Do**

  Most customers do not need to take any action.

  If your implementation relies on any of the deprecated fields, we recommend reviewing your segments and integrations before **April 15, 2026.**
</Update>

<Update label="March 6 2026">
  Email Address Validation is now available!

  * When email addresses are added to OneSignal, they're now validated at three entry points:
    * API: syntax check
    * CSV import: full validation including typo detection, MX record lookup, disposable email flagging, and role-based address detection\*
    * Bulk validation: same full checks, runs against addresses already in your audience
  * Free plans have syntax and typo checks.
  * Paid plans will have syntax, typo, MX, disposable email, and role based email address checks.

  See [Email Address Validation](/docs/en/email-address-validation) for more details.
</Update>

<Update label="March 4 2026">
  **Dashboard layout redesign has shipped!**

  * Panel-based layout. The old floating card approach has been replaced with flat panels. The side nav sits in a clean gray panel, and the main content in a white panel. This simplifies the look and feel and gives us a more modern aesthetic.
  * New global top bar. Breadcrumbs, the new Create menu, Help/Support links, and Upgrade button all live in a new sticky top bar that follows you on scroll.

  **Richer date context across the dashboard**

  Dates show up everywhere in OneSignal — denoting message creation, notification send times, user sessions, etc. — but it wasn't always clear which timezone you were looking at, or how recent something actually was. This came up in a discussion last week among the dashboard engineers.

  Now, hovering over a date in the following areas of the Dashboard shows a tooltip with three pieces of context at once: the time in your local timezone, the time in UTC, and a relative timestamp (like "2 days ago").

  Where you'll see it:

  * Message lists and indexes
  * Message reports
  * Message review modals before sending
  * User and subscription profiles

  This is enabled for all apps — no action needed. Just hover a date and it's there!

  **In-App Message library with new quickstarts!**

  We've shipped a library of professionally designed, ready-to-use in-app message templates — available now to all plans in the dashboard.

  What's in it: 7 categories of quick starts covering the most common IAM use cases: push soft prompts, promotions, onboarding flows, feature announcements, location prompts, spin-to-win, and notification preference centers.

  How to access: Dashboard → Messages → In-App → New In-App → OneSignal Quick Starts. No feature flag or backend enablement required — available immediately. (See demo for the full experience in product)

  Go from zero to a production-ready in-app message in minutes, without writing HTML from scratch!
</Update>

<Update label="March 3 2026">
  **Enhanced Snowflake Integration Now Available!**

  Key improvements include:

  * 15-minute sync intervals (down from 24 hours)
  * Selective event syncing so customers only export what they need
  * Self-service setup directly in the OneSignal dashboard
  * New events like in-app impressions, email bounced/received, and separated Live Activity events.
  * We've also added richer properties including Template ID, last active timestamp, and subscription status.

  Customers get near real-time data in their Snowflake instance with full control over what gets synced meaning faster insights. Selective syncing alone can dramatically reduce event volume (and spend) by letting them export only the events that they need.

  This moves from the legacy flat annual fee to our Event Streams pricing model. Customers pre-purchase an event volume tier, and that tier covers all destinations (Snowflake, BigQuery, Databricks, etc.).

  Live now for all customers. All new customers will automatically have access to this new integration. Existing legacy Snowflake customers have until August 1st to migrate to the new integration before deprecation. Both integrations can run in parallel during the transition so they can ensure parity/consistency, and we will be doing outreach to those affected shortly.

  See [Snowflake](/docs/en/snowflake) for more details.
</Update>

<Update label="February 26 2026">
  **Audit Logs API is now available**

  Enterprise customers (with Legal & Security package) can now programmatically access the same audit log data surfaced in the OneSignal dashboard — pipe it directly into their SIEM, compliance tooling, or internal security workflows.

  * Returns a time-scoped record of actions taken in their org — who did what, when, and from where
  * Filter by app, action type, actor, target, or IP address
  * Supports cursor-based pagination for large result sets

  See [Audit Logs API](/reference/list-audit-logs) for more details.
</Update>

<Update label="February 9 2026">
  Huawei Badge Parameter Support

  We now support app icon badges on Huawei (HMS) devices via both the API and dashboard.

  * What's new: Three new parameters on `Notification#Create`
    * `huawei_badge_class` — the app's launcher activity class name (required for badge)
    * `huawei_badge_set_num` — set the badge to an exact number (0–99)
    * `huawei_badge_add_num` — increment the badge by a specific amount (1–99)

  On the dashboard, you'll see a new Badge option under Send to Huawei Android with "Don't set" / "Set to" / "Increase by" options.

  * Good to know:
    * Setting `huawei_badge_set_num` to 0 clears the badge
    * If neither set nor add is specified, the badge increments by 1 by default
    * Huawei does not auto-clear badges when the app opens
</Update>

<Update label="January 29 2026">
  API Documentation Improvements

  * New API endpoint: [View Segment](/reference/view-segment) - Retrieve details of a specific segment by ID, including optional segment filter details.
  * New API endpoint: [Update Segment](/reference/update-segment) - Update an existing segment's name and/or filters programmatically.
  * Fixed JSON example formatting across multiple API reference pages for improved readability:
    * Segments API: view-segments, create-segments, delete-segments
    * Users API: create-user, view-user, update-user, delete-user
    * Subscriptions API: create-subscription, delete-subscription, transfer-subscription, unsubscribe-with-token, create-alias-by-subscription
</Update>

<Update label="January 26 2026">
  **Audit Logs are now available!**

  * Customers now have the ability to determine exactly what's happening across their OneSignal account. Audit Logs gives them a complete timeline of every action taken in their organization—who did what, when, and from where.
  * Track 50+ action types including:
    * Authentication events (login, logout, API key operations)
    * Message activity (notifications sent, canceled, A/B tests, Journeys)
    * Team changes (member added, role changed, removed)
    * Configuration updates (webhooks, segments, templates, integrations)
    * Billing & subscription events
  * Powerful filtering:
    * Search by team member email
    * Filter by action type, app, IP address, or item type
    * Custom date ranges with presets
    * Shareable filtered URLs—customers can collaborate with their team instantly
  * Deep visibility:
    * Expandable rows reveal 30+ fields: IP address, browser, location, correlation ID, API version, and more
    * Available at both App and Organization levels
    * Quick-access links from Journeys, Segments, Templates, Notifications, and more
  * Retention:
    * Legal & Security package: 90-day lookback
    * All other plans: 2-day lookback
  * Perfect for security audits, debugging, and understanding team activity at a glance.
</Update>

<Update label="January 9 2026">
  * Standardized time series for charts are now available for:
    * Event Streams and webhooks
    * Email delivery reports
    * SMS/RCS delivery reports
</Update>

<Update label="December 22 2025">
  * confirmed receipt Now Available On Engagement Trends
    * Customers with access to confirmed receipt can now see confirmed receipt on the Engagement Trends Time Series Chart.
    * This missing data was a common point of confusion for customers. They could see confirmed receipt & click through rate, but had no access to the total confirmed deliveries metric.
    * This additional data point gives customers confidence in the rates we're showing and helps with confusion on the difference between "delivered" and "Confirmed receipt" for push notifications.
</Update>

<Update label="December 12 2025">
  * New integration - Self-serve Snowflake data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake without going through customer support
    * The legacy Snowflake documentation remains available for existing implementations
</Update>

<Update label="December 8 2025">
  Live Activities in Event Streams & Integrations

  Live Activities Analytics provides two key capabilities to optimize customers' live activity strategy:

  1. Better Troubleshooting with confirmed receipt
     Gain visibility into whether devices actually received live activity updates. confirmed receipt tracking identifies delivery issues quickly to understand the true reach of live activities.
     Available in:

  * Individual message reports with per-device confirmation
  * Data exports to BI tools (through event streams and integrations)

  2. Deeper Engagement Insights with data exports to integrations & event streams
     Answer critical questions about how users interact with your live activities:

  * How many users engaged with my live activity over its duration?
  * When did users drop off?
  * What was the peak engagement time?
  * When did users click? (coming soon)

  Export live activity data to BI tools to analyze engagement patterns, optimize timing, and improve future campaigns.
</Update>

<Update label="December 5 2025">
  We've launched a new [Metrics Glossary](/docs/en/analytics-metrics-glossary) in our documentation. This resource provides a single source of truth for delivery metric definitions, helping both our team and customers understand our metrics consistently across dashboards, APIs, and exports.
  While we continue working toward unified terminology across all touch points, this glossary establishes clear mappings and definitions as they exist today, making it easier for customers to navigate our current analytics landscape.

  Custom Events in User Activity Timeline
  Custom events are now visible per User on their profile page in a dedicated tab. You can:

  * Filter by event type and event source
  * Filter by date, to any time window in the past. Only limiting factor is customer's own events retention window setting!
  * Expand each event to see the full payload
  * Click through to the events index to see that event type's config and full cross-user activity log

  This is important because:

  * It helps paint the complete picture of user activity. At a basic level, customers ask the question, "what's going on with this user?" and this helps answer it.
  * Especially useful for zoomed-in troubleshooting, auditing, what-happened analysis.
  * Please note: this will only be visible to customers in Custom Events early access, but will be available to all as they gain access to Custom Events
</Update>

<Update label="November 26 2025">
  UX Improvements Now Live

  1. Row-Level Linking
     You can now click anywhere on a table row to navigate to its destination, instead of having to click a specific cell. This makes navigation faster and more intuitive.
  2. Row Highlighting on Hover
     All tables now highlight the entire row on hover, helping users track data more easily and reducing visual strain when scanning wide tables.
  3. Improved Responsiveness
     The actions column has been narrowed to preserve horizontal space and is now right-aligned at the end of every table.
     It also features sticky, floating behavior — especially useful on smaller screens where horizontal scrolling is required.
     Some tables better truncate long text (e.g., lengthy message names) more effectively to maintain a clean layout.
  4. Refined Sorting UX
     Updated sort icons make the sort direction easier to interpret. Clicking anywhere on a column header now toggles sorting, improving ease of use.
  5. Unified Column Visibility Menu (Applies to Journeys, Users, Subscriptions)
     Tables with customizable columns now use a consistent, cleaner UI. Column changes update live as you toggle them.
  6. Updated Search Bar UI
     The search bar now aligns with design standards, featuring a left-aligned search icon, and a button that shows after typing for easy input clearing.
  7. Improved Pagination Formatting
     Pagination controls now use comma formatting for large numbers, improving scannability and readability.

  Core Component Update
  Many of the enhancements above come from migrating these tables to our core design system’s DataTable component. Sorting and filtering improvements for tables are consistently among the most requested features we receive. While these updates don’t introduce new sorting or filtering behavior yet, this component upgrade provides a more consistent experience for the functionality we have today, and does lay the foundation for Product teams to build more advanced table capabilities once those initiatives are prioritized.

  Coming Soon

  * Most tables across the Dashboard already include these improvements. A few remaining areas still require component updates before they can adopt the full set of new enhancements:
    * In-app index
    * Templates index
    * Audience activity table
    * A/B tests stats table
</Update>

<Update label="November 12 2025">
  UX Enhancement: Duplicate Templates Directly from the Editor
  In usability tests and dogfooding sessions, we noticed users often duplicate Journey nodes and then edit their templates. Previously, you had to exit the template editor and duplicate the template from the index view, an extra step that interrupted the workflow.
  Now, you can duplicate templates directly from the actions dropdown in the template editor. This small but meaningful improvement streamlines your editing experience and makes iteration faster. While our long-term goal is to enable template/content editing directly within Journeys, this enhancement is a great step in that direction.

  New Platform Filters for Engagement Trends & Subscription Trends
  You can now filter push engagement trend data by platform (iOS, Google Android, Huawei, etc.) to get a more granular view of performance across specific devices.
  In the spirit of our Analytics Consistency project, we've also brought this same filtering experience to Subscription Trends.

  Analytics Consistency: Standardized Time Series Chart Filters
  We're standardizing filter options across our time series charts, giving customers a consistent experience and clear access based on their plan.
  Key Changes:

  * All charts will share the same set of granularity and look back filters
  * Consistent casing and terminology used on all filters
  * Consistent upgrade experience for customers on plans with limited access
    As an example, Subscription Trends now supports a 2 year look back after the change.

  Charts where we've already rolled out these changes:

  * Engagement Trends
  * Subscription Trends
  * Global Outcomes
  * Push Delivery
  * All Template Reports
  * Coming Soon:
  * Email Delivery
  * SMS Delivery
  * Journeys Reports

  Look back access based on plan type:

  * Free: 30 days
  * Growth: 90 days
  * Professional: 1 year
  * Enterprise: 2 years
  * Custom: Up to 90 days (based on plan types above)
</Update>

<Update label="October 6 2025">
  Nice UXE on Journey Settings. We’ve updated the Journeys Settings Side panel to be more user friendly by adding a side navigation to keep each section in focus. This is in tandem with the eventuality of having more settings available to the user as we look towards Journey Goals, and more.  We will accompany this release with an intercom slide letting the user know we have updated the settings area as to give them a heads up due to the abrupt pattern change.

  Every Setting, In Focus: Journey Settings are now grouped and spotlighted, helping you zero in on each choice without distraction.
</Update>

<Update label="October 2 2025">
  Custom Events are now available to all customers on paid plans! You can now send custom events via our API or SDK, and use them to trigger actions in Journeys with your own event data.
</Update>

<Update label="September 21 2025">
  Customers can now pause a segment that's counting towards their segments entitlement even though it's only being used in an archived journey or paused IAM. We also made it even easier to pause segments, if the user wants to pause a segment, we'll help the user pause or archive the active IAMs or journeys stopping the user from pausing a segment.
</Update>

<Update label="September 9 2025">
  Deactivate email senders

  Deactivate email domains that are no longer in use or were set up incorrectly. This includes fallback handling for your email templates and scheduled sends to make sure you don't break them by removing a domain, just in case it was being used more widely than you anticipated.
</Update>

<Update label="August 29 2025">
  Personalize emails with real-time Data Feeds

  You can now use Data Feeds to pull live content from your APIs directly into emails at send time. No more static CSVs or preloaded tags — every message can include the latest account details, product recommendations, or order updates.

  Available in the email template composer for emails sent via Journeys, Data Feeds includes preview tools and error handling to keep sends smooth.

  👉 See how to set up [Data Feeds](/docs/en/data-feeds)
</Update>

<Update label="August 04 2025">
  You can now hold users in a Journey step until specific conditions are met before they move forward with the *Wait Until* action. This new feature allows you to:

  * Hold users at a step until they enter a segment or trigger a message event (such as a specific message being delivered, opened, or clicked).
  * Add multiple conditions and branch users based on whichever condition they meet first.
  * Set an expiration path that moves users forward or removes them from the Journey if none of the conditions are met within your chosen timeframe. This gives you greater flexibility and control over how users progress through your Journeys. Learn more: [Journeys Actions](/docs/en/journeys-actions)

  AI Composer Push Notifications
  You can now generate or improve push notification message copy using the AI message composer. This update helps you craft high-performing content without leaving OneSignal. When creating a new push notification, select AI-generated push button to get started. To improve existing copy, select “Refine” in the Title, Subject, or Message fields.

  New [Integrations](/docs/en/integrations) index page contains the following enhancements:

  * Filtering by type of integration
  * Filtering by Inbound/Outbound directions of data flow
  * Includes our new inbound DWH/Data ingestion options for custom events
</Update>

<Update label="July 07 2025">
  * Quickly identify and manage segments tied to campaigns
    * We’ve made it easier to clean up outdated segments.
    * Previously, you couldn’t delete a segment if it was tied to an In-App Message (IAM) or Journey, even if that campaign was paused or archived. Now, when you try to delete a segment, you’ll see a modal listing all IAMs and Journeys that are preventing deletion.
    * This helps you quickly locate and update the associated campaigns, so you can keep your workspace clean and organized without having to hunt through every Journey or IAM.
</Update>

<Update label="June 30 2025">
  * Segment users based on real message engagement
    * You can now create user segments based on how they interacted with previous messages across push, email, SMS and in-app.
    * This update adds a new Message Event filter that allows you to segment users based on events like email opens, push clicks, SMS failures, and more - without relying on tags or external tools.
    * Available on all paid plans.
    * See [Segmentation](/docs/en/segmentation#message-event-filters) for more details.
</Update>

<Update label="June 27 2025">
  * New documentation with Mintlify!
    * We've updated our docs!
    * New AI features and easier readability.
    * Updated API reference and openapi spec.
    * New Tutorials page with common use cases and step-by-step details to get you setup quickly!
</Update>

<Update label="June 18 2025">
  * Track In-App engagement trends alongside push, email, and SMS
    * Customers can now see In-App Message impressions, clicks, and click-through rates directly in the Engagement Trends chart. This update gives marketers a unified view of how users are interacting with all message types over time—including In-App—making it easier to spot trends, report on performance, and optimize messaging across channels.
    * With this update, In-App engagement data is now included alongside push, email, and SMS across all views in the Engagement Trends chart. Stats are grouped by day and support up to two years of data (depending on plan). This data is exportable via CSV just like other channels, and can be filtered to look at specific date ranges or message types.
    * This feature is available to all customers.
</Update>

<Update label="June 12 2025">
  * Unlock deeper email engagement insights with multi-link tracking
    * Customers can now track engagement on every individual link within their emails. This update gives customers a much clearer view into what content or messaging is working so they can improve email performance over time.
    * Previously, when customers included multiple links within an email, they could only view total click counts across all links. Now, they can see which specific links get the most engagement and how links perform inside journeys. This helps them refine content and messaging strategies.
    * Multi-link tracking is automatically applied to most emails created in the Drag & Drop or HTML editor. Link-level performance metrics will also be available for emails sent using a template and emails in a Journey.
    * This feature is available to all customers with access to email.
</Update>

<Update label="May 23 2025">
  * View and optimize message performance with Template Analytics
    * OneSignal customers can quickly assess how individual templates are performing across all messages, without needing to download and stitch together separate reports.
    * When users click into a template, they now land on a detailed analytics view showing Delivered, Unique Opens, Unique Clicks, and Unsubscribes. They can track performance over time, filter by platform, explore delivery breakdowns like Failed or Capped, and review a list of messages that used the template.
    * Template analytics is especially useful for:
      * Marketers who test and iterate on message content
      * Developers who need visibility into transactional message delivery
      * High-volume senders seeking scalable insights
    * Transactional visibility is a key differentiator that sets us apart from Firebase and other open source solutions. Customers can now answer questions like “How many Account Confirmation emails did I send last week?” or “What was the click-through rate on my Password Reset messages?”
    * Important note: For templates created before April 17, 2025, enhanced metrics are only available for messages sent after that date. Customers can use the “Show historical data” toggle at the top of the page to see earlier performance data.
    * The feature is live and available by default. Reporting history varies by plan:
      * Free: 30 days
      * Growth: 90 days
      * Professional: 1 year
      * Enterprise: 2 years
</Update>

<Update label="May 16 2025">
  * Add users manually from the dashboard
    * You can now create new users directly from the *Users* tab in your OneSignal dashboard using a simple form. This update makes it easy to manually add a user with an email address, phone number, or both without needing an SDK, API call or CSV upload.
    * This is especially helpful for quickly testing campaigns or adding users who aren’t yet in your system.
</Update>

<Update label="May 14 2025">
  * Track SMS link performance directly in OneSignal
    * Customers can now track SMS link performance directly in OneSignal without needing third-party tools like Bit.ly or custom UTM parameters. This feature gives our customers a more streamlined, built-in way to measure engagement and optimize messages faster, removing friction and helping drive better results from their SMS efforts.
    * When composing an SMS message, customers simply click “Insert Trackable Link” and enter the full URL they want to send users to. OneSignal automatically shortens the link using the 1sgnl.co domain so it fits within SMS character limits and can be tracked.
    * All SMS users will have access to trackable links as part of their existing plan.
</Update>

<Update label="May 07 2025">
  * Simplify message organization with easier label management
    * Now you can add labels to your messages to help you organize and manage them.
    * See [Labels](/docs/en/labels) for more details.
</Update>

<Update label="May 01 2025">
  * Template analytics
    * You can now view and optimize template performance from a centralized reporting view. Click into any message template to view detailed performance data across every message a template is used in.
</Update>

<Update label="Apr 25 2025">
  * Improved CSV Importer
    * **Real-time validation:** Get instant feedback on formatting errors before upload.
    * **Smart column mapping:** Easily align your CSV headers with OneSignal fields.
    * **Email suppression support:** Add or manage your suppression list directly in the file.
    * **Upload history:** View the status of your past imports for up to 30 days.
    * **Helpful templates:** Start quickly with a pre-built CSV example.
</Update>

<Update label="Apr 21 2025">
  * Fine-tune your Live Activities with new API parameters
    * You can now add more control, reliability, and speed to your Live Activities with three new parameters in the OneSignal API: - ios\_relevance\_score: Helps determine which Live Activity displays most prominently on iOS. - include\_aliases: Allows you to target individual users directly rather than relying on segment-based delivery. - idempotency\_key: Prevents the creation of duplicate Live Activities when retrying start requests if not using the OneSignal SDK.
</Update>

<Update label="April 14 2025">
  * New integration - Databricks data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Databricks. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Databricks, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="April 08 2025">
  * View opt-out status by sender and support transactional messaging even with marketing opt-outs
    * You can now see SMS opt-out status by sender, giving you better visibility and control when managing marketing and transactional messages.
    * With this update, you can:
      * View subscription status by individual sender for any phone number
      * Continue sending transactional messages (like OTPs or alerts) even if a user has opted out of marketing
      * Maintain deliverability and avoid carrier filtering by respecting opt-out preferences
    * This is especially useful if you manage separate senders for promotional and transactional use cases.
    * To access this feature, go to **Consent Management > Advanced Opt-out Settings** and turn off the setting that globally unsubscribes a user when they reply with an opt-out keyword.
    * *Note: This option is only available to customers using advanced opt-out settings for SMS.*
</Update>

<Update label="March 19 2025">
  * Easily find and select the right templates with visual previews
    * Quickly identify and select your email and in-app message templates with the new updated card view.
    * Instead of relying on template names alone, you can now see clear visual previews, making it easier to choose the right template at a glance.
</Update>

<Update label="March 12 2025">
  * Create users in OneSignal via HubSpot workflows
    * Keep your users in sync across HubSpot and OneSignal! With this new workflow action, you can now create users in OneSignal whenever a HubSpot workflow trigger fires. This enables you to queue up personalization details (such as Tags) and plan engagement strategies before a user even interacts with your mobile platform. Additionally, you can trigger an SMS or email via HubSpot while simultaneously creating a user in OneSignal—ensuring seamless and immediate engagement.
    * [HubSpot Documentation](/docs/en/hubspot)
  * Push preview accuracy improvements
    * As operating systems update, they often introduce new changes in their push designs.
    * We've updated our previews so they match latest and greatest push notification designs across iOS (18), Android (15), Windows (11), macOS (Sequoia). This ensures you see what your users will see when testing in OneSignal.
  * PII Masking of Emails and Phone Numbers
    * Protect user privacy and reduce compliance risks by masking personally identifiable information (PII) such as emails and phone numbers. With PII masking, your team can work securely while still analyzing campaign performance and sharing insights across teams.
    * OneSignal automatically masks phone numbers and emails in the dashboard and any data exported directly from the platform. However, PII masking does not currently apply to data accessed via API requests, external IDs, or Tags.
</Update>

<Update label="March 07 2025">
  * Verify & Lookup Phone Numbers
    * Sends the user a one-time verification code to ensure the customer owns the phone #
    * Confirms the phone number entered by a user at onboarding is valid
</Update>

<Update label="February 28 2025">
  * Added New Integration - [BigQuery Data Export](/docs/en/bigquery)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to BigQuery. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in BigQuery, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
  * Channel subscriber counts have moved
    * The counts of subscribed counts for each channel have moved from the dashboard to the Subscriptions page in OneSignal. Now you will see the number of *Subscribed* subscriptions for each channel at the top of the Subscriptions page under Audience to get an overview of audience reach per channel in the context of your subscriptions.
    * If you still wish to view this information on the Dashboard, you can filter your Subscriptions trends chart by channel.
</Update>

<Update label="February 14 2025">
  * Improvements to Keywords
    * We've made a couple of improvements to our SMS keywords.
      * Segment by subscription status when sending a keyword to encourage converting your customers who are not yet subscribed into opting in to your SMS marketing messages
      * Setup an auto-responder for unrecognized keywords
</Update>

<Update label="February 12 2025">
  * New Engagement Analytics on the OneSignal Dashboard

    * Are you curious to learn more about how your end users engage with the messages you send from OneSignal? Head to your Dashboard to see the new Engagement Trends report.
    * With this report you will gain insight into how users engage with your messages across Push, Email, and SMS. Track click-through-rate, unsubscribes, and monitor trends over time to refine your messaging strategy and optimize communication frequency. This comprehensive report consolidates data from all message types (Dashboard, API, Journeys) for a clearer view of performance. Now available in your OneSignal dashboard!

    <Frame>
      <img alt="New Engagement Analytics on the OneSignal Dashboard" />
    </Frame>
</Update>

<Update label="January 29 2025">
  * Sort segments by Last edited, Created at and more
    * Finding and managing your segments just got easier!
    * You can now sort segments by Last edited, Created at and more.
      * This update is especially valuable for customers who:
        * Maintain numerous segments
        * Frequently update their segment configurations
        * Need to identify and clean up outdated segments
        * Want to quickly find recently modified segments
</Update>

<Update label="January 27 2025">
  * Email Senders (Multi-Domain Sending)
    * Create distinct senders for different types of communications:
      * Keep your marketing campaigns separate from crucial transactional emails
      * Maintain different brand voices for various product lines
      * Optimize sender reputation for each type of communication
      * [Email Senders](/docs/en/senders)
  * Improved In-app Message Analytics for Event Streams
    * We've added a new In-app Message Analytics for Event Streams.
</Update>

<Update label="January 21 2025">
  * Email Intelligent Delivery
    * We've added intelligent delivery to email.
    * Transform your email engagement with OneSignal's latest breakthrough: Intelligent Delivery. This powerful new feature automatically determines the optimal time to reach each individual user, maximizing your email campaign's impact.
    * Our algorithm continuously learns from:
      * User open patterns
      * Click-through behavior
      * Real human interactions (excluding bot activity)
</Update>

<Update label="January 16 2025">
  * Retirement of Automated Message for Free apps
    * Automated Messages are no longer supported and the feature has been retired in the free plan. Paid apps will continue to have access to this feature until further notice.
    * Active automated messages will remain live and continue functioning as expected. However, you can no longer create new automated messages, or reactivate paused automated messages. To build new automated sequences and enhance your campaigns, we recommend using [Journeys](/docs/en/journeys-overview).
</Update>

<Update label="January 15 2025">
  * Customize how your users re-enter split branches
    * Now you can customize how your users re-enter split branches. This feature is available for all Journeys.
    * [Journey Entry Triggers](/docs/en/journeys-actions)
  * Improving New Message Experience
    * We improved the new message experience by adding a library of templates (get inspiration for your next push, in-app, email, or SMS), or quickly start from a template you've made, or a previous message.
</Update>

<Update label="January 03 2025">
  * message.url - New Push Event Stream Property
    * `message.url` is now a supported property for push events. It enables the retrieval of the launch URL directly from your event stream payload.
</Update>

<Update label="December 24 2024">
  * Journeys Multi-split Branching
    * Now you can set up more personalized paths in your Journey. Create up to 20 branches to test channels, content, timing, ordering, and more. Assign different weights to each branch, or easily distribute audiences evenly across all branches. See how different paths perform against each other or against a control group.
</Update>

<Update label="December 20 2024">
  * WordPress Plugin v3
    * We've upgraded our Wordpress Web Push plugin to v3+. What's changed:
      * Upgrades the OneSignal Web SDK from version 15 to 16.
      * Setup more new prompts within the OneSignal dashboard, including the following. No custom code is required anymore to configure these.
        * Category Prompt
        * Email/Phone Slide Prompt
        * Custom Link Prompt.
      * When publishing a new post, check the "Send notification when post is published" box to send a push notification.
      * Choose which audience segment should receive notifications for each post.
      * Web Topics are included by default.
      * Send to mobile app subscribers, with an option to direct them to a different URL (Deep Link).
</Update>

<Update label="December 11 2024">
  * Improved Logs in Event Streams
    * We've improved the Event Streams feature to make troubleshooting simpler and faster. Now, you’ll find dedicated tabs for successful and failed events, making it easier to spot issues at a glance. Clear empty states show when there’s no data in either tab, and updated messaging ensures you know the logs display a sample of your data.
  * SMS Keywords
    * We've added keywords for SMS. Keyword engagement enables quick, two-way communication, enhancing personalization, accessibility, and user satisfaction. It drives conversions and higher engagement with your subscribers. Add a data tag to the keyword, and segment based on their preferences to send more targeted SMS.
  * Quickstart Segments

    * We are thrilled to launch three new segment templates designed to help you hit the ground running with proven strategies:
      * First-Time audience
      * Regional audience
      * Custom Audience based on tags
    * Our analysis of 6.3 billion message deliveries uncovered powerful insights. These templates are built to help you:
      * Create high-performing segments from day one.
      * Use proven filter combinations that drive higher engagement.

    <Frame>
      <img alt="Quickstart Segments" />
    </Frame>
</Update>

<Update label="December 02 2024">
  * Email Quickstart Templates
    * We've added a library of quickstart templates for email. Explore our library of professionally crafted email templates, designed to inspire your creativity and elevate your email campaigns. Use them as a starting point to create impactful messages that drive conversions and engage your audience effectively.
</Update>

<Update label="November 27 2024">
  * Scheduling Journeys
    * Now you can schedule Journeys to send at a specific time. This feature is available for all Journeys.
  * Settings Overview Page
    * Now you can access and manage all your settings in a centralized setting overview page. Platform-specific settings have been reorganized under their relevant channels for better clarity.
</Update>

<Update label="November 20 2024">
  * Bulk Archive and Delete Journeys

    * Now you can bulk archive or delete Journeys from the Journeys index. Select up to 20 Journeys, and then choose an action you'd like to take to clean up Journeys you're no longer using.

    <Frame>
      <img alt="Bulk Archive and Delete Journeys" />
    </Frame>
</Update>

<Update label="November 06 2024">
  * Improved Export for Global Outcomes
    * We've improved the export for Global Outcomes to include more data and make it easier to use in your reporting.
  * Preview allows you to preview the content of a message and can be very helpful when you have a message with personalization (i.e. Tags, dynamic content, custom data). With preview, you can preview content from a specific test user's perspective, or with example custom data.
  * Settings for Email & Side Navigation Updates
    * In the side navigation, you can now easily see your Push, SMS, and Email settings. What was once "Messaging" is now "Push" settings, and SMS and Email Settings will take you directly to your channel's settings.
    * For email, we've created a dedicated place to manage your email provider and senders. If you are a OneSignal mail user, you'll also be able to see your reputation and suppression lists here.
  * SMS Usage
    * We've added SMS Usage in the Usage page. We've also added a breakdown so you can see the message type, and a breakout by inbound and outbound. You may see an unknown country if a segment failed to send.
</Update>

<Update label="October 02 2024">
  * Add Notes on your Journeys
    * Now you can add notes to the steps of your Journeys to keep reminders and more effectively collaborate and share information with your team. This feature is available for all Journeys.
</Update>

<Update label="September 27 2024">
  * New Quickstart Journeys
    * We've added a new Quickstart Journeys to help you get started with Journeys. This feature is available for all Journeys.
  * SMS Text-to-Subscribe
    * It's now easier to set up double opt-in and text-to-subscribe phone number collection experiences for your customers!
</Update>

<Update label="September 12 2024">
  * Confirmed Click-Through-Rate (CCTR) metric

    * We have added a new metric to measure the CTR using confirmed receipt. Confirmed Click-Through-Rate (CCTR) is measured by (total clicks/confirmed delivered) \* 100%

    <Frame>
      <img alt="Confirmed Click-Through-Rate (CCTR) metric" />
    </Frame>
</Update>

<Update label="September 06 2024">
  * Export your Subscription Trends
    * Now you can export the data from your Subscription Trends report as a CSV. If you apply filters to the report, OneSignal will export based on the filters you've applied so that you can fine-tune the data that you use to evaluate your messaging audience.
</Update>

<Update label="August 05 2024">
  * Email Saved Rows
    * Saved Rows are reusable content blocks that help streamline email creation and management. Many companies, especially those that have a lot of templates, prefer to use saved rows in their emails for consistency and to save time. Saved Rows are easily attached to new emails so you don't have to create the same information from scratch each time. And when things change, you just have to update the saved row, and your updates will automatically sync across all campaigns that have that saved row attached.
    * Common use cases include:
      * headers (logo, slogan)
      * footers (company details, social media links, mailing addresses)
      * disclaimers
      * other elements that are used across multiple campaigns
    * You can now save Email Drag-and-Drop rows to use across many Campaigns or Templates. These re-suable **Saved Rows** make it easy to sync updates across many emails at once. Click on the **Rows** tab of a Drag-and-Drop email, to view your **Saved Rows**. To save your first row, click the save icon in the edit, in the top right corner of the row.
    * We recommend you set up all of your templates to use saved rows for your header and footer so that you need to update the branding or content; you only have to make those edits once.
</Update>

<Update label="July 30 2024">
  * Journeys now target anonymous users
    * Now, Journeys do not require External IDs to be set on subscriptions. Instead, Journeys will target your entire user base within OneSignal, including anonymous users. We recommend still configuring External IDs to identify individual users who have subscribed to multiple channels.
</Update>

<Update label="July 25 2024">
  * Have more visibility into SMS unsubscribes, resubscribes, and help keywords
    * We now make it easier to manage your Consent Keywords within Onesignal. Reach out to support if you'd like to update the default consent keywords and replies.
</Update>

<Update label="July 19 2024">
  * Email Reply-to field now supports custom properties
    * Now you can use [Message Personalization](/docs/en/message-personalization) within the `reply-to`field on an email. This allows you to direct message replies to the right inbox and can be helpful if you are sending from different brands or across different countries.
</Update>

<Update label="July 16 2024">
  * Push Failures and Unsubscribes in Audience Activity
    * Obtain a list of subscriptions that have faced errors - failures or unsubscribes, for a specific push notification in the push report page.
</Update>

<Update label="July 03 2024">
  * Integrations: OneSignal Message Events can be sent to Twilio Segment
    * Customers can now select and send message events from OneSignal to sync back to their Twilio Segment account, making the Segment integration bidirectional.
  * Use Audience Activity for Live Activities to get a list of recipients
    * Get a list of subscriptions that successfully or failed to receive a Live Activity on a Live Activity report page, which is accessible through the Delivery - Sent Index. This list can be exported as well.
</Update>

<Update label="June 06 2024">
  * In-app message audience activity
    * In the report page of an in-app message, you can now see which mobile subscriptions viewed (impression) or clicked on an in-app message. Audience activity is available for 30 days from the time the message is displayed
</Update>

<Update label="May 15 2024">
  * FCM Expired Tokens > Increased Android Unsubscribes
    * On May 15, 2024, Google's FCM service will start to expire stale push tokens for devices that have been inactive for more than 270 days. You may see a spike in Android unsubscribes when sending notifications due to this change. Don't panic! These are devices that have not been online in over 270 days and are part of Google's [Best practices for FCM registration token management](https://firebase.google.com/docs/cloud-messaging/manage-tokens). If the device does come back online and opens your app, OneSignal will automatically resubscribe them to push if they were previously subscribed already.
    * See [FCM Expired Token FAQ](/docs/en/fcm-expired-token-faq) for more details.
</Update>

<Update label="April 29 2024">
  * Configure more granular Frequency Capping rates for Push
    * Push notifications can now be capped at a rate of x notifications per any time frame (less than 1 week). Navigate to Settings > Messaging > Push Frequency Capping > Custom (in the time dropdown) to view these settings.
    * Read [Frequency Capping Documentation](/docs/en/frequency-capping) for more details.
</Update>

<Update label="April 11 2024">
  * Added Android Live Notifications
    * Android's Live Notifications deliver live, dynamic content in notifications to enhance user engagement and app interactivity. This is a feature similar to iOS's Live Activities feature (introduced with iOS 16), but uses its own set of tools and APIs that enable similar functionalities.
    * See [Android Live Notifications](/docs/en/android-live-notifications) for more details.
  * Major improvements to Android SDK
  * Push to start Live Activities
    * Live Activities can now be launched on a user's screen when the mobile app is in the background (app is not open). Live Activities can both be started and updated by a remote push notification.
    * [How to start a Live Activity with a remote push notification](/docs/en/live-activities)
</Update>

<Update label="April 01 2024">
  * Added Audience Activity reports for Journeys
    * We have added Audience Activity reports for Journeys so you can get a closer look at which subscriptions were sent messages during a Journey. To view this report, click into a message report on your Journey. [Learn more here](/docs/en/journeys-analytics#audience-activity).
</Update>

<Update label="March 18 2024">
  * Added a new Setup guide for Analytics
    * We have added a new Analytics Setup guide to our product documentation detailing how to track Confirmed Deliveries and set up Custom Outcomes with support from your development team.
</Update>

<Update label="March 12 2024">
  * Mobile SDK Updates
    * We recommend updating to the latest SDK versions listed below to benefit from critical bug fixes, stability improvements, and new features. These updates include key enhancements across all platforms, including iOS 5.1.3 and Android 5.1.6, which improve concurrency safety, crash resilience, and background thread handling. The updates also include important API adjustments like more accurate property handling in the `PushSubscriptionState`.
</Update>

<Update label="February 16 2024">
  * Journeys is now available on the Growth plan
    * Journeys is now available on the Growth plan. This means you can now create and manage Journeys with up to 100,000 users.
    * See [Journeys](/docs/en/journeys-overview) for more details.
</Update>

<Update label="February 12 2024">
  * Added Auto Warm Up
    * We have added a new feature that allows you to automatically warm up your app when a user opens it. This feature is available for all OneSignal customers.
    * See [Email Warm Up](/docs/en/email-warm-up) for more details.
</Update>

<Update label="February 02 2024">
  * Journeys has easier targeting based on user activity
    * We've added support for Segments with time-based rules (e.g., first session, last session, etc.) and also simplified targeting inactive users. Now you can target your inactive users by including a segment based on last session behavior.
  * Email: Schedule Sends Across Different Timezones
    * Email campaigns can now be scheduled to send across different timezones. This feature is available for all OneSignal customers.
</Update>

<Update label="January 30 2024">
  * Email now supports One Click Unsubscribe
    * Inbox Service Providers (ISP) like Gmail, Outlook, iOS Mail, and Yahoo! Mail, AOL, and Verison Mail require senders to provide a One Click Unsubscribe option. The unsubscribe button is rendered at the discretion of the ISP based on sending criteria, which may include a daily sending volume greater than 5,000 emails.
</Update>

<Update label="December 18 2023">
  * Filter your messages with labels
    * Now you can filter your messages with [labels](/docs/en/labels). This feature is available for all OneSignal customers.
  * CSV Importer can now update properties
    * CSV Importer for email now enables updates to user properties `language`, `country`, and `timezone_id`.
  * Send more personalized messages and multi-language emails
    * [Dynamic Content Documentation](/docs/en/dynamic-content)
</Update>

<Update label="December 14 2023">
  * All OneSignal apps now belong to an Organization
    * We have added a new feature that allows you to manage your OneSignal apps within an Organization. This feature is available for all OneSignal customers.
    * See [Apps, Orgs, and Accounts](/docs/en/apps-organizations)
  * Journeys now has better analytics
    * We've added a new Journeys Report. See [Journeys Analytics](/docs/en/journeys-analytics) for more details.
</Update>

<Update label="November 22 2023">
  * Removed Journey Notifications from Delivery Reports and the View Notifications endpoint
</Update>

<Update label="October 04 2023">
  * Added new integration - [Snowflake](/docs/en/snowflake)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Snowflake, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="September 27 2023">
  * You can now save and continue
    * Changed the default option for saving a message to save work without exiting the message.
</Update>

<Update label="September 13 2023">
  * Added the ability to adjust the default padding for IAM blocks
    * Learn more about [IAM blocks](/docs/en/design-your-in-app-message)
  * Added the ability to edit entry triggers and re-entry rules for live Journeys
    * Learn more about [Journey entry triggers](/docs/en/journeys-overview)
</Update>

<Update label="September 05 2023">
  * Added ability to create multi-language push messages by pasting your CSV
    * Learn more about [Multi-language messages](/docs/en/multi-language-messaging)
  * Added new "Editor" role permissions
    * Learn more about [Managing team members](/docs/en/manage-team-members)
  * Added enhanced Journey message stats and reports.
    * Learn more about [Journey message stats and reports](/docs/en/journeys-analytics)
</Update>

<Update label="September 01 2023">
  * Added a new feature to forward email templates to an app
    * Learn more at [Email Template Forwarding](/docs/en/email-template-forwarding)
  * Added FCM v1 API support for Android Push Notifications
    * Learn more about [Android Firebase credentials](/docs/en/android-firebase-credentials)
</Update>

<Update label="August 15 2022">
  * Android 13 changes
    * Android 13 introduces a runtime notification permission, meaning users must opt in to receive push notifications. Apps targeting Android 13 must explicitly prompt for permission at a time of their choosing, or the system will display the permission prompt automatically on first launch—often resulting in lower opt-in rates.
    * See [Android 13 Push Notification Developer Update Guide](/release-notes/android-13-push-notification-developer-update-guide) or our [Prompt for Push Permissions](/docs/en/prompt-for-push-permissions) guide for details.
</Update>


# SDK Releases
Source: https://documentation.onesignal.com/release-notes/sdk-releases

View the latest OneSignal SDK releases and updates.

## Mobile

<SdkReleasesIframe />

## Web

<SdkReleasesIframe />

## Server

<SdkReleasesIframe />

## Plugins

<SdkReleasesIframe />


# Google Tag Manager setup
Source: https://documentation.onesignal.com/docs/en/google-tag-manager

Add OneSignal Web Push to your website using Google Tag Manager (GTM), including service worker setup, initialization, and sending Tags safely.

This guide shows you how to load and initialize the OneSignal Web SDK using Google Tag Manager (GTM), then optionally set an External ID and send OneSignal Tags after initialization.

## Prerequisites

* A site that supports HTTPS.
* You can publish changes in GTM for the site's container.
* You've completed the OneSignal [Web SDK setup](./web-sdk-setup) flow until **Add Code to Site**. This gives you:
  * A OneSignal Web Push app and App ID.
  * The [OneSignal Service Worker](./onesignal-service-worker) setup.

## Setup

### 1. Set up your OneSignal web app

Follow [Web SDK setup](./web-sdk-setup) until you reach **Add Code to Site**. This is where you will get the OneSignal App ID.

<Frame>
  <img alt="Add Code to Site step in OneSignal Web SDK setup dashboard" />
</Frame>

<Warning>
  You must upload the OneSignal Service Worker file to your server directly. See [OneSignal Service Worker](./onesignal-service-worker).
</Warning>

### 2. Create GTM variables

Create GTM variables for values you reference across tags. This avoids hardcoding and makes your setup easier to maintain.

**Create a `ONESIGNAL_APP_ID` variable**

1. In GTM, go to **Variables > New**.
2. Choose **Constant**.
3. Name it `ONESIGNAL_APP_ID`
4. Set the value to your OneSignal App ID.
5. Save

<Frame>
  <img alt="Creating a OneSignal App ID variable in Google Tag Manager" />
</Frame>

<Check>
  You can now reference your App ID anywhere in GTM using `{{ ONESIGNAL_APP_ID }}`.
</Check>

**Create an `ONESIGNAL_EXTERNAL_ID` variable (Recommended)**

Use this if you associate users with an external identifier (for example, a user ID from your database or auth system).

Choose a variable type based on where the value lives on your site. Common options:

* Data Layer Variable (recommended)
* First-Party Cookie
* DOM Variable (advanced)

### 3. Create the OneSignal init tag

1. In GTM, go to **Tags > New**
2. Name the tag: `OneSignal - Init`
3. Tag Type: **Custom HTML**
4. Paste the below code.
5. Under **Advanced Settings > Tag firing options**, set **Once per page**.
6. Under **Triggering**, select **Initialization - All Pages**.

```html HTML theme={null}
<!--
  OneSignal – Web SDK initialization using Google Tag Manager

  This snippet:
  - Loads the OneSignal Web SDK
  - Initializes OneSignal with your App ID
  - Enables the Subscription Bell (notifyButton)

  Works for most sites out of the box.
-->

<!-- 1. Load the OneSignal Web SDK (v16) -->
<!-- This script must load on every page where you want OneSignal available -->
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>

<script>
  // Ensure the GTM dataLayer exists
  // Used here only to optionally push a "OneSignalInitialized" event
  window.dataLayer = window.dataLayer || [];

  // OneSignalDeferred is a queue that runs once the SDK is fully loaded
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  // 2. Initialize OneSignal once the SDK is ready
  window.OneSignalDeferred.push(function (OneSignal) {

    OneSignal.init({
      /*
        REQUIRED
        It is recommended to set the OneSignal App ID as a GTM variable.
        You can find this in your OneSignal Dashboard under:
        Settings > Keys & IDs
      */
      appId: "{{ONESIGNAL_APP_ID}}",

      /*
        OPTIONAL – ONLY NEEDED IF YOUR SERVICE WORKER IS NOT AT THE ROOT

        If your service worker is hosted at:
          /OneSignalSDKWorker.js

        …then you should NOT set serviceWorkerPath or serviceWorkerParam.

        Uncomment and update the options below ONLY if your service worker
        is hosted in a subdirectory (for example: /push/onesignal/).
      */

      //serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      //serviceWorkerParam: { scope: "/push/onesignal/" },

      /*
        OPTIONAL
        Enable the OneSignal Subscription Bell (notifyButton),
        which allows users to subscribe or unsubscribe from notifications.
        For more prompt options, see: https://documentation.onesignal.com/docs/en/permission-requests
      */
      notifyButton: {
        enable: true
      }
    })
    .then(function () {
      // OneSignal initialized successfully
      console.log("[OneSignal] init success");

      // Recommended: push an event to GTM for triggering other tags
      window.dataLayer.push({
        event: "OneSignalInitialized"
      });
    })
    .catch(function (e) {
      // Initialization failed (invalid App ID, missing service worker, etc.)
      console.log("[OneSignal] init failed", e);
    });
  });
</script>
```

<Frame>
  <img alt="Configuring the OneSignal - Init tag in Google Tag Manager" />
</Frame>

<Warning>
  If you use a consent banner / CMP, see [Consent Mode and privacy considerations](#consent-mode-and-privacy-considerations) options below.
</Warning>

### 4. Set External ID and tags

Setting the [External ID](./users#external-id) is optional but recommended because it allows you to identify users across devices and syncs with your backend.

**Push `ONESIGNAL_EXTERNAL_ID` into the dataLayer**

This example shows how you might push a user ID into the dataLayer so GTM can read it via the `ONESIGNAL_EXTERNAL_ID` variable (created in step 2).

```html HTML theme={null}
<script>
  window.dataLayer = window.dataLayer || [];

  // Get your user ID from your database or auth system.
  // Ensure this is a string value.
  var userId = "your_user_id_here";

  dataLayer.push({
    ONESIGNAL_EXTERNAL_ID: String(userId),
  });
</script>
```

**Create a GTM Tag to set the External ID**
Tag configuration:

* Tag name: `OneSignal – Set External ID`
* Tag type: **Custom HTML**
* Tag firing options: **Once per page**
* Trigger:
  * Create a custom event trigger for `OneSignalInitialized` (set in the above **OneSignal - Init** tag) and
  * Optionally if you know the user ID is available on the page load.

<Warning>
  The required method to set the External ID is `OneSignal.login(externalId)` where `externalId` is a string.

  If `{{ONESIGNAL_EXTERNAL_ID}}` is empty (or GTM substitutes "undefined" / "null"), the login call will be skipped and the External ID will not be set. This is a common GTM timing issue.
</Warning>

```html HTML theme={null}
<script>
  // OneSignalDeferred ensures this runs after the OneSignal SDK is ready
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  window.OneSignalDeferred.push(function (OneSignal) {
    // Read the External ID from the GTM variable created in step 2
    var externalId = "{{ONESIGNAL_EXTERNAL_ID}}";

    console.log("[OneSignal] raw external ID from GTM:", externalId);

    // GTM may substitute undefined/null as literal strings — skip login if invalid
    if (!externalId || externalId === "undefined" || externalId === "null") {
      console.log("[OneSignal] External ID missing, skipping login");
      return;
    }

    // Ensure the External ID is a clean string
    externalId = String(externalId).trim();

    console.log("[OneSignal] Calling OneSignal.login with External ID:", externalId);

    /*
      Log the user into OneSignal using the External ID.
      This links the current browser/device to this user.
    */
    OneSignal.login(externalId)
  });
</script>
```

<Accordion title="Advanced example with retry logic (use if External ID is not being set)">
  ```html HTML theme={null}
  <script>
    window.dataLayer = window.dataLayer || [];
    window.OneSignalDeferred = window.OneSignalDeferred || [];

    OneSignalDeferred.push(function (OneSignal) {
      var rawExternalId = "{{ONESIGNAL_EXTERNAL_ID}}";

      // ---- Helpers ----
      function log() {
        console.log.apply(console, ["[OneSignal External ID]"].concat([].slice.call(arguments)));
      }

      function normalizeExternalId(v) {
        // GTM commonly substitutes these as strings
        if (
          v === undefined ||
          v === null ||
          v === "undefined" ||
          v === "null"
        ) return null;

        var s = String(v).trim();
        if (!s.length) return null;

        return s;
      }

      function pushDL(eventName, extra) {
        try {
          var payload = Object.assign({ event: eventName }, extra || {});
          window.dataLayer.push(payload);
        } catch (e) {
          // no-op
        }
      }

      function readStateSnapshot() {
        var snapshot = {
          onesignalId: null,
          externalId: null,
          pushSubscriptionId: null
        };

        try {
          snapshot.onesignalId = OneSignal.User && OneSignal.User.onesignalId;
          snapshot.externalId = OneSignal.User && OneSignal.User.externalId;
          snapshot.pushSubscriptionId =
            OneSignal.User &&
            OneSignal.User.PushSubscription &&
            OneSignal.User.PushSubscription.id;
        } catch (e) {
          log("Error reading OneSignal.User state", e);
        }

        return snapshot;
      }

      function isExternalIdApplied(targetExternalId) {
        var current = normalizeExternalId(OneSignal.User && OneSignal.User.externalId);
        return current === targetExternalId;
      }

      // ---- Initial logging ----
      log("Tag fired. rawExternalId:", rawExternalId, "type:", typeof rawExternalId);

      var externalId = normalizeExternalId(rawExternalId);
      log("Normalized externalId:", externalId, "type:", typeof externalId);

      if (!externalId) {
        log("Not calling login(): externalId missing/invalid");
        pushDL("OneSignalExternalIdMissing", { reason: "invalid_or_missing_external_id" });
        return;
      }

      // Optional: enable verbose OneSignal logs during testing
      if (OneSignal.Debug && OneSignal.Debug.setLogLevel) {
        OneSignal.Debug.setLogLevel("trace");
        log("Enabled OneSignal Debug log level: trace");
      }

      // ---- Attach User State observer ----
      var changeFired = false;

      OneSignal.User.addEventListener("change", function (event) {
        changeFired = true;

        log("User change event fired:", event);

        var snapshot = readStateSnapshot();
        log("User state snapshot:", snapshot);

        // Helpful: push snapshot-ish DL event (optional)
        pushDL("OneSignalUserStateChanged", {
          onesignal_id: snapshot.onesignalId || "",
          external_id: normalizeExternalId(snapshot.externalId) || "",
          push_subscription_id: snapshot.pushSubscriptionId || ""
        });
      });

      // ---- Login + confirm + retry ----
      var attempt = 0;
      var MAX_RETRIES = 3;
      var CONFIRM_WINDOW_MS = 1500;
      var BASE_BACKOFF_MS = 500;

      function doLogin() {
        attempt += 1;
        changeFired = false;

        log("Calling OneSignal.login()", { externalId: externalId, attempt: attempt });

        OneSignal.login(externalId)
          .then(function () {
            log("OneSignal.login() promise resolved");
            waitForConfirmation();
          })
          .catch(function (e) {
            log("OneSignal.login() promise rejected", e);
            retry("promise_rejected");
          });
      }

      function waitForConfirmation() {
        var start = Date.now();

        (function check() {
          if (isExternalIdApplied(externalId)) {
            log("Confirmed externalId applied via state check:", externalId);

            var snapshot = readStateSnapshot();
            log("Final state snapshot:", snapshot);

            pushDL("OneSignalExternalIdSet", {
              external_id: externalId,
              attempt: attempt,
              push_subscription_id: snapshot.pushSubscriptionId || ""
            });

            return;
          }

          if (changeFired) {
            log("Change event observed but externalId not yet reflected; waiting...");
          }

          if (Date.now() - start >= CONFIRM_WINDOW_MS) {
            log("No confirmation within window", {
              attempt: attempt,
              changeFired: changeFired,
              currentExternalId: normalizeExternalId(OneSignal.User && OneSignal.User.externalId)
            });

            retry("no_confirmation");
            return;
          }

          setTimeout(check, 100);
        })();
      }

      function retry(reason) {
        if (attempt >= MAX_RETRIES) {
          log("Giving up after max retries", { attempts: attempt, reason: reason });

          var snapshot = readStateSnapshot();
          log("State at give-up:", snapshot);

          pushDL("OneSignalExternalIdSetFailed", {
            external_id: externalId,
            reason: reason,
            attempts: attempt,
            push_subscription_id: snapshot.pushSubscriptionId || ""
          });

          return;
        }

        var delay = BASE_BACKOFF_MS * Math.pow(2, attempt - 1);
        log("Retrying login after delay", { delayMs: delay, reason: reason, nextAttempt: attempt + 1 });

        setTimeout(doLogin, delay);
      }

      // If already applied, don't spam login()
      if (isExternalIdApplied(externalId)) {
        log("ExternalId already applied; skipping login.", externalId);

        var snapshot = readStateSnapshot();
        log("Current state snapshot:", snapshot);

        pushDL("OneSignalExternalIdAlreadySet", {
          external_id: externalId,
          push_subscription_id: snapshot.pushSubscriptionId || ""
        });

        return;
      }

      // Kick it off
      doLogin();
    });
  </script>
  ```
</Accordion>

#### Set tags

This sends [OneSignal Tags](./add-user-data-tags) using our Web SDK.

Tag configuration:

* Name: `OneSignal - Add Tags`
* Tag Type: **Custom HTML**
* Tag firing options: **Once per page**
* Trigger:
  * `OneSignalInitialized`, and
  * Your condition for when tag data is available (for example: after login, on a profile page, after purchase).

Paste this code and replace `TAG_1`/`TAG_2` and `VALUE_1`/`VALUE_2` with your tag names and values.

```html HTML theme={null}
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  window.OneSignalDeferred.push(function (OneSignal) {
    OneSignal.User.addTags({
      TAG_1: "VALUE_1",
      TAG_2: "VALUE_2",
    });
  });
</script>
```

<Note> Only send tags when you actually have the user data available (for example: after login, after a profile loads, or after a known conversion event). </Note>

#### Listen for push subscription changes

You can monitor push subscription state changes (opt-in, opt-out, token updates) by adding an event listener. This is useful for syncing subscription status with your analytics or backend systems via the GTM dataLayer.

Tag configuration:

* Name: `OneSignal - Push Subscription Listener`
* Tag Type: **Custom HTML**
* Tag firing options: **Once per page**
* Trigger: `OneSignalInitialized`

```html HTML theme={null}
<script>
  /*
    Callback fired whenever the push subscription state changes.
    The event object contains previous and current snapshots so you
    can detect opt-ins, opt-outs, and token refreshes.
  */
  function pushSubscriptionChangeListener(event) {
    // Subscription ID before and after the change
    console.log("event.previous.id", event.previous.id);
    console.log("event.current.id", event.current.id);

    // Push token (device token) before and after the change
    console.log("event.previous.token", event.previous.token);
    console.log("event.current.token", event.current.token);

    // Whether the user was/is opted in to push notifications
    console.log("event.previous.optedIn", event.previous.optedIn);
    console.log("event.current.optedIn", event.current.optedIn);
  }

  // Ensure the OneSignalDeferred queue exists
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  OneSignalDeferred.push(function(OneSignal) {
    // Register the listener on the PushSubscription object
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });
</script>
```

### Consent Mode and privacy considerations

If your site uses Consent Mode / a CMP, decide whether OneSignal should load:

* Only after consent (common for EU/UK), or
* Immediately (common where "functional" storage is allowed by default).

GTM supports a Consent Initialization trigger and tag-level consent controls to manage tag behavior based on user consent. However, OneSignal also provides privacy consent methods to control when the SDK loads.

* [Handling personal data](./handling-personal-data)
* [Web SDK Privacy Methods](./web-sdk-reference#privacy)

***

## Testing

1. In GTM, open Preview mode.
2. Load your site and confirm:
   * `OneSignal - Init` fires once.
   * `OneSignalInitialized` appears in the GTM event timeline (if you kept the event push).
3. Subscribe to your website. See [Web permission prompts](./permission-requests) for prompting details.
4. In the OneSignal dashboard, go to **Audience > Subscriptions** and confirm:
   * A Subscription appears after you opt in.
   * An External ID is visible if you set one.
5. Send a test push from **Messages > New Push**.

<Check> If initialization is working, you’ll see subscriptions appearing in OneSignal after opt-in. </Check>

### Troubleshooting

* Init tag fires, but SDK never loads
  * Check for Content Security Policy (CSP) blocking `https://cdn.onesignal.com`.
  * Check for ad blockers/script blockers.

* `dataLayer` errors
  * Ensure `window.dataLayer = window.dataLayer || []` is set before any `dataLayer.push()` calls.

* Duplicate prompts / duplicate SDK load
  * Make sure you are not also loading OneSignal via site code, a CMS plugin, or another GTM tag.

* Add Tags runs but doesn’t appear in OneSignal
  * Confirm the Trigger Group waits for `OneSignalInitialized`.
  * Confirm your user action trigger actually fires.
  * Confirm tags are valid key/value pairs and within [Plan limits](https://onesignal.com/pricing).

<Note>
  For additional help, see [Web SDK troubleshooting](./troubleshooting-web-push).
</Note>

## FAQ

### Does OneSignal work with GTM Consent Mode?

Yes. You can control when OneSignal loads using GTM's consent controls or OneSignal's own privacy methods. If your site requires consent before loading scripts, configure the init tag's trigger to fire only after consent is granted, or use OneSignal's `setConsentRequired` and `setConsentGiven` methods. See [Handling personal data](./handling-personal-data) for details.

### Why isn't my External ID being set?

The most common cause is a GTM timing issue where `{{ONESIGNAL_EXTERNAL_ID}}` resolves to `"undefined"` or `"null"` because the dataLayer variable isn't populated yet when the tag fires. Verify the variable has a value in GTM Preview mode before the tag executes. If the value loads asynchronously, use the [advanced example with retry logic](#4-set-external-id-and-tags).

### Can I load OneSignal through both GTM and site code?

No. Loading the OneSignal SDK more than once causes duplicate prompts and unpredictable behavior. Use either GTM or direct site code, not both. Also check for CMS plugins that may inject OneSignal separately.

***

## Related pages

<Columns>
  <Card title="Web permission prompts" icon="bell" href="./permission-requests">
    Configure how and when to prompt visitors for web push permission.
  </Card>

  <Card title="Tags" icon="tags" href="./add-user-data-tags">
    Set key-value data on Users for personalization and segmentation.
  </Card>

  <Card title="Web SDK reference" icon="globe" href="./web-sdk-reference">
    Full method and event reference for the OneSignal Web SDK.
  </Card>

  <Card title="Handling personal data" icon="shield-halved" href="./handling-personal-data">
    Manage user consent and control which data the OneSignal SDK collects.
  </Card>
</Columns>


# Cancel message
Source: https://documentation.onesignal.com/reference/cancel-message

DELETE /notifications/{message_id}?app_id={app_id}
Stop a scheduled or currently outgoing message.

## Overview

The Cancel message API can be used to stop scheduled messages from being sent. It does not delete or remove the message from the app. If a message is in the process of sending, then canceling it may not fully prevent all targeted users from receiving it.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users, scheduling the message in the future with `send_after`. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and use this API to cancel sending the message to the user if not needed anymore.

If you need a way to remove a notification already sent to a user, see [Remove notifications & TTL](/docs/en/push).

***


# Copy template to another app
Source: https://documentation.onesignal.com/reference/copy-template-to-another-app

POST /templates/{template_id}/copy_to_app?app_id={app_id}
Create a duplicate of a template in another app. The new template will be completely separate from the original (including having a new template_id) but will be created with all the same content.

## Overview

This API allows you to copy a template from one app (`app_id`) to another (`target_app_id`). The duplicated template will have the same content as the original, but a new unique `template_id`.

<Note>
  If you are trying to copy an email template, we also have an [Email Template Forwarding](/docs/en/email-template-forwarding) feature that does not require an API call.

  Both options support HTML and Drag & Drop email templates.
</Note>

***

## Requirements

* **Organization Membership:** Both the `app_id` and `target_app_id` must belong to the same [Organization](/docs/en/apps-organizations).
* **Authorization Required:** You must use your [Organization API key](/docs/en/keys-and-ids#organization-api-key), not an app-level REST API key.
* **Permissions Note:** Your user must have admin-level access to both the source and target apps. If not, the request will fail with a "permission denied" error.

***

## Parameters

* `template_id` (path param): UUID of the template to be copied.
* `app_id` (query param): ID of the app where the original template exists.
* `target_app_id` (body param): ID of the app where the template will be duplicated.

***

## How to Use

### 1. Locate the Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

### 2. Get App IDs

Refer to [Keys & IDs](/docs/en/keys-and-ids) to find your `app_id` and `target_app_id`.

***

## Response

The response will include:

* The new `template_id` for the copied template
* Confirmation of successful creation
* Any warnings if applicable (e.g., limited fields copied)

***


# Create or update alias
Source: https://documentation.onesignal.com/reference/create-alias

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Create or update one or more user aliases when you already know an existing alias. This API performs an upsert on the user’s identity object—either adding new aliases or updating existing ones.

## Overview

Use this API to manage user aliases by providing one known alias (such as `external_id`, `onesignal_id`, or a custom alias) and specifying additional aliases to add or update.

This endpoint focuses solely on the `identity` object. If you need to fully create a user with subscriptions and properties, use the [Create user](/reference/create-user) API instead.

<Note>
  * If an alias with the same `alias_label` already exists for the user, it will be updated. If it doesn’t exist, a new alias will be created.
  * Want to use a subscription instead of an alias to identify the user? Use [Create alias (by subscription)](/reference/create-alias-by-subscription).
</Note>

See also:

* [Users](/docs/en/users) – for details on OneSignal ID and External ID
* [Aliases](/docs/en/aliases) – for setting and managing custom aliases
* [Delete alias](/reference/delete-alias) – for removing aliases

***

## How to use this API

To identify the user:

* Use `alias_label` for the type of alias you know (e.g., `external_id`, `onesignal_id`, or a custom alias)
* Use `alias_id` for the value of that alias

<Note>
  We strongly recommend setting the `external_id` as your primary user identifier. This can be done through our frontend SDK's login method when a user signs in to your app or website. It helps OneSignal associate the user's push, email, and SMS subscriptions to a unified user identity.
</Note>

Changes to the identity object take effect immediately upon request.

Alias keys (`alias_label`) and values (`alias_id`) are each limited to **128 characters**. A user can have up to **10 custom aliases** total.

***


# Create alias (by subscription)
Source: https://documentation.onesignal.com/reference/create-alias-by-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Create or update an alias for a user using a known subscription ID.

Create or update an alias for a user using a known subscription ID.

# Overview

Use this API to add or update aliases associated with a user when you only know at least one subscription ID. This API is handy for scenarios where the user's identity is unknown, but a subscription is available.

To remove an alias, see [Delete alias](/reference/delete-alias) API.

***

# How to use this API

You must know the `subscription_id` of the subscription that belongs to the user in which you want to update. Subscription IDs are UUIDs generated by OneSignal and cannot change. See [Subscriptions](/docs/en/subscriptions) for details.

This endpoint performs an upsert—if the user already has an alias with the specified alias label, it gets updated; otherwise, a new alias will be created.

The request body must include an identity object containing one or more aliases to be created or updated.

The OneSignal ID is read-only and used only for fetching. See [Users](/docs/en/users) for details.

Aliases are updated immediately upon request.

***


# Create an app
Source: https://documentation.onesignal.com/reference/create-an-app

POST /apps
Programmatically create a new OneSignal app via the REST API. This guide explains required fields, supported platform configurations (Web, Android, iOS), and how to properly authenticate using your Organization API key.

## Overview

Use this API to programmatically create a new OneSignal app. This is useful for automating app setup, particularly when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need to Base64 encode your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns):

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates):

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Create API key
Source: https://documentation.onesignal.com/reference/create-api-key

POST /apps/{app_id}/auth/tokens
Use the OneSignal API to create a new Rich Authentication Token (App API Key) for a specific app. This guide explains how to authenticate with the Organization API key and configure optional IP allowlists using CIDR notation.

## Overview

Use this API to create a new **App API Key** (also called a **Rich Authentication Token**) for a specific OneSignal app. These keys are used to authenticate API requests at the app level and offer enhanced security features, including optional IP allowlisting.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

### IP allowlisting

By default, the API key will not be restricted to any specific IP addresses. To enable IP allowlisting, you need to set the `ip_allowlist_mode` parameter to `explicit` and provide a list of allowed IP addresses in the `ip_allowlist` parameter.

If you want to set the explicit range of IPs that can use this API key, add them by setting `ip_allowlist_mode` to `explicit` and in `ip_allowlist` add the IPs in CIDRs notation as an array of string values.

***


# Create custom events
Source: https://documentation.onesignal.com/reference/create-custom-events

POST /apps/{app_id}/custom_events
The Custom Events API allows you to record user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones.

## Overview

The Custom Events API allows you to track user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones. See [Custom events](/docs/en/custom-events) for more information.

### Use Cases

Custom events can be used to:

* Enter users into [Journeys](/docs/en/journeys-settings)
* Trigger Journey [Wait Until](/docs/en/journeys-actions) nodes

### Error handling

If individual events can't be processed, an `errors` key will be returned in the response (with HTTP status 202) containing information about each failing event. The most common event-specific error is a failure to find a user associated with the External ID or OneSignal ID in the event.

If you'd like to retry sending events in the case of a failure, you only need to re-send the events for which errors were returned -- events that don't have an error associated with them are still processed. However, if a 5xx HTTP response is returned, you must retry the entire batch of events.

In either case, if you are implementing retry, make sure to also pass an [`idempotency_key`](/reference/idempotent-notification-requests).

### Duplicate events

If you implement retry behavior for your custom event delivery, please provide the [`idempotency_key`](/reference/idempotent-notification-requests) field. Each unique event should get its own unique UUID, and when retrying delivery for events, the same UUID must be provided. Duplicate events with the same `idempotency_key` will be ignored on a best-effort basis within a 4-hour period. This allows you to avoid erroneously triggering Journeys multiple times or incurring charges for storing unnecessary duplicate events.

***


# Sending messages with the OneSignal API
Source: https://documentation.onesignal.com/reference/create-message

Send push notifications, emails, SMS, and Live Activities with the OneSignal API. Covers audience targeting, message composition, scheduling, and response handling.

## Overview

This guide walks you through sending messages with the OneSignal API — from choosing a target audience to composing content, scheduling delivery, and validating responses. Each section covers channel-specific options and performance guidance.

### Prerequisites

1. Complete [Channel Setup](/docs/en/channel-setup) for the channels you plan to use: push, email, SMS, Live Activities.
2. Start accumulating [Subscriptions](/docs/en/subscriptions) for your users.
3. Have your REST API Key and App ID ready. See [Keys and IDs](/docs/en/keys-and-ids).

***

## Choose your target audience

You can target users with **one of the following methods per request**:

* **Aliases**: Specific users via unique IDs, emails, or phone numbers.
* **Segments**: Groups based on predefined behaviors or attributes.
* **Filters**: Custom rules using tags, location, activity, and more.

<Warning>
  Only one targeting method is allowed per message. For example, you cannot mix aliases and filters.
</Warning>

You can also target specific platforms (for example, `isAndroid`, `isIos`, `isAnyWeb`) when sending push notifications. By default, all push platforms are enabled.

### Aliases, emails, phone numbers

Target specific users or lists of users (up to 20,000 entries per request). This method is best for [Transactional Messages](/docs/en/transactional-messages).

<Accordion title="Aliases, emails, and phone numbers targeting parameters">
  <ParamField type="object">
    Target up to 20,000 users by their `external_id`, `onesignal_id`, or a custom alias. Combine with `target_channel` to select the delivery channel.

    ```json theme={null}
    {
      "include_aliases": {
        "external_id": [
          "user1",
          "user2",
          "user3"
        ]
      },
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="string">
    The targeted delivery channel. Required when using `include_aliases` or `included_segments` and sending SMS/RCS. Accepts `"push"`, `"email"`, or `"sms"`. The `"sms"` value covers both SMS and RCS — RCS messages are delivered through the SMS channel.

    ```json theme={null}
    {
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="array">
    Target users' specific [Subscriptions](/docs/en/subscriptions) by ID. Max 20,000 `subscription_id` per request.

    ```json theme={null}
    {
      "include_subscription_ids": [
        "1dd608f2-c6a1-11e3-851d-000c2940e62c"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send to specific email addresses (max 20,000 per request). Can only be used when sending [email](/reference/email). If the email address does not exist within the OneSignal App, a new email subscription is created.

    ```json theme={null}
    {
      "email_to": [
        "user1@example.com",
        "user2@example.com"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send SMS/MMS/RCS to phone numbers in [E.164 format](/docs/en/sms-setup#what-is-e164-format) (max 20,000 per request). Can only be used when sending [SMS/MMS/RCS](/reference/sms). If the phone number does not exist within the OneSignal App, a new SMS subscription is created.

    ```json theme={null}
    {
      "include_phone_numbers": [
        "+19999999999"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Segments

Target users in existing [segments](/docs/en/segmentation). Users in multiple segments only receive the message once.

<Accordion title="Segments targeting parameters">
  <ParamField type="array">
    Target predefined [segments](/docs/en/segmentation). Users who are in multiple segments only receive the message once. Combine with `excluded_segments` to exclude users from specific segments. When sending SMS/RCS, set `target_channel` to `"sms"` (or use the legacy `isSms=true` field).

    ```json theme={null}
    {
      "included_segments": [
        "Active Users",
        "Inactive Users"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Exclude users in these [segments](/docs/en/segmentation) even if they're in `included_segments`.

    ```json theme={null}
    {
      "included_segments": [
        "Subscribed Users"
      ],
      "excluded_segments": [
        "Inactive Users"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Filters

Build real-time audiences with `AND`/`OR` logic without creating segments first.

You can include up to **200 total entries per request**. This includes filter rows (for example, each `field`) and logical operators like `{"operator": "OR"}`.

<Accordion title="Filters targeting parameter details">
  <Info>
    **Performance guidance:**

    * **Fast:** Tag filters using `"="` or `"exists"`, and filters on `last_session`, `session_count`, or `country`.
    * **Slower:** Negation filters (`"!="`, `"not_exists"`) — especially with users who have many tags. Contact support to request indexing optimizations.
    * **Slow by default:** Numeric comparisons (`">"`, `"<"`) on tags or custom properties. Indexing may be available on request.
    * **Mixed performance:** Combining tag filters with other fields may increase computation time.
  </Info>

  <ParamField type="string">
    * Implicit `AND` logic between filters. Use `"operator": "OR"` to start a new branch.
    * `OR` filters are mutually exclusive. Recipients only need to satisfy one condition.
    * Allowed values: `"AND"`, `"OR"`.

    <CodeGroup>
      ```json AND example theme={null}
      // Users must satisfy both filters to be included.
      // Notice the AND operator is not required

      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      // The same example using the AND operator. This is not required.
      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "AND"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      ```

      ```json OR example theme={null}
      // Users can satisfy either filter to be included.

      "filters": [
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "tag", "key": "level", "relation": "=", "value": "20"}
      ]
      ```

      ```json Combinations theme={null}
      // In this example, users must either have:
      // The specified session_count AND tag requirement
      // Or it will be all records where last_session is satisfied
      {
        "name": "2 filters or 1",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"}
        ]
      }

      // Similar to the first example, this shows how to require a specific field
      // across other filters

      {
        "name": "3 filters, 1 required across all",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
        ]
      }

      // Example of 3 user groups with 2 requirements
      // (group_1 OR group_2 OR group_3) AND (requirement_1 OR requirement_2)

      {
        "name": "3 groups with 2 requirements",
        "filters": [
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"}
        ]
      }
      ```
    </CodeGroup>
  </ParamField>

  <ParamField type="object">
    ### `tag`

    Target based on custom user [Tags](/docs/en/add-user-data-tags).

    <Warning>
      Do not use tags for targeting individual users like a "user id".
      Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
    </Warning>

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
      * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
    * `key` = Tag key to compare.
    * `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

    ```json theme={null}
    "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "OR"},
      {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
    ]
    ```

    ### `country`

    Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "country", "relation": "=", "value": "US"},
        {"operator": "OR"},
        {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
      ]
      ```

    ### `last_session`

    Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "last_session", "relation": ">","hours_ago": "10"}
      ]
      ```

    ### `first_session`

    Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "first_session", "relation": "<","hours_ago": "24"}
      ]
      ```

    ### `session_count`

    Total number of sessions by the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="` or `"!="`
    * `value` = number of sessions. Example: `"1"`

      ```json theme={null}
      "filters": [
        {"field": "session_count", "relation": ">","value": "5"}
      ]
      ```

    ### `session_time`

    Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

    * `relation` = `">"` or `"<"`
    * `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

      ```json theme={null}
      "filters": [
        {"field": "session_time", "relation": ">","value": "86400"}
      ]
      ```

    ### `language`

    [User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = 2 character language code. Example: `"en"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "language", "relation": "=","value": "en"},
        {"operator": "OR"},
        {"field": "language", "relation": "in_array","value": "es,fr,de"}
      ]
      ```

    ### `app_version`

    App version set on the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = app version. Example: `"1.0.0"`
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "app_version", "relation": "=","value": "1.0.1"},
        {"operator": "OR"},
        {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
      ]
      ```

    ### `location`

    Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

    * `radius` = in meters
    * `lat` = latitude
    * `long` = longitude

      ```json theme={null}
      "filters": [
        {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
      ]
      ```
  </ParamField>
</Accordion>

***

## Craft your message

Each channel has its own set of fields. At a minimum, you need the following to send a displayable message:

* **Push and SMS** use `contents`
* **Email** uses `email_subject` and `email_body`
* Or reuse `template_id` if you created [templates](/docs/en/templates).

<CodeGroup>
  ```json Push and SMS theme={null}
  // Message request body
  {
    "contents": {
      "en": "Hello, world",
      "es": "Hola Mundo",
      "fr": "Bonjour le monde",
      "zh-Hans": "你好世界"
    }
  }
  ```

  ```json Email theme={null}
  // Message request body
  {
    "email_subject": "Hello, world",
    "email_body": "<html><body><h1>Hello, world</h1></body></html>"
  }
  ```
</CodeGroup>

For advanced customization—like adding images, buttons, sounds, or tracking—see the channel-specific options below.

### Push notification options

Below are the most common parameters for push notifications. For the full list of options, see the [Push notification reference](/reference/push-notification).

<Accordion title="Push notification options">
  #### Content and text

  * [`contents`](/reference/push-notification#body-contents) – Main message body.
  * [`headings`](/reference/push-notification#body-headings) – Title of the notification.
  * [`subtitle`](/reference/push-notification#body-subtitle) – Secondary line of text.
  * [`template_id`](/reference/push-notification#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Appearance

  * [`ios_attachments`](/reference/push-notification#body-ios-attachments) – Images/video/media.
  * [`big_picture`](/reference/push-notification#body-big-picture) – Large image (Android).
  * [`chrome_web_image`](/reference/push-notification#body-chrome-web-image) – Large image (Chrome).
  * [`small_icon`](/reference/push-notification#body-small-icon)
  * [`large_icon`](/reference/push-notification#body-large-icon)
  * [`buttons`](/reference/push-notification#body-buttons) – Action buttons.

  #### Delivery and priority

  * [`android_channel_id`](/reference/push-notification#body-android-channel-id)
  * [`priority`](/reference/push-notification#body-priority) – Delivery urgency.
  * [`ios_interruption_level`](/reference/push-notification#body-ios-interruption-level)
  * [`collapse_id`](/reference/push-notification#body-collapse-id) – Replaces older messages.

  #### Data and extras

  * [`data`](/reference/push-notification#body-data) – Custom key-value pairs sent to your app.
  * [`url`](/reference/push-notification#body-url) – Opens when notification is tapped.
</Accordion>

### Email options

<Accordion title="Email options">
  #### Content

  * [`email_subject`](/reference/email#body-email-subject)
  * [`email_body`](/reference/email#body-email-body)
  * [`email_preheader`](/reference/email#body-email-preheader)

  #### Appearance

  * [`template_id`](/reference/email#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Sender info

  * [`email_from_name`](/reference/email#body-email-from-name)
  * [`email_reply_to`](/reference/email#body-email-reply-to)
</Accordion>

### SMS/MMS options

<Accordion title="SMS/MMS options">
  #### Content

  * [`contents`](/reference/sms#body-contents)
  * [`template_id`](/reference/sms#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Media (MMS only)

  * [`sms_media_urls`](/reference/sms#body-sms-media-urls)

  #### Sender info

  * [`sms_from`](/reference/sms#body-sms-from)
</Accordion>

***

## Schedule and per-user delivery

By default, messages are sent immediately. You can schedule delivery in advance and optimize timing per user based on their local timezone or recent activity.

<Accordion title="Schedule delivery and per-user optimization parameters">
  <ParamField type="string">
    Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript's Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring).

    ```json theme={null}
    {
      "send_after": "2025-09-24T14:00:00-07:00"
    }
    ```
  </ParamField>

  <ParamField type="string">
    Controls how push and email messages are delivered on a per-user basis. Not available for SMS.

    * `"timezone"`: Sends at the same local time across time zones.
    * `"last-active"`: Delivers based on each user's most recent session.

    Not compatible with [push throttling](/docs/en/throttling). When `delayed_option` is set, you must also set `throttle_rate_per_minute` to `0`.

    ```json theme={null}
    {
      "delayed_option": "last-active",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>

  <ParamField type="string">
    Use with `delayed_option: "timezone"` to set a consistent daily delivery time. Accepted formats:

    * `"9:00AM"` (12-hour)
    * `"21:45"` (24-hour)
    * `"09:45:30"` (HH:mm:ss)

    Example — Send every day at 9 AM in each user's local time:

    ```json theme={null}
    {
      "delayed_option": "timezone",
      "delivery_time_of_day": "9:00AM",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>
</Accordion>

***

## Submit the request

This final example sends a localized push notification to all subscribed users:

```curl theme={null}
curl -X "POST" "https://api.onesignal.com/notifications" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Key YOUR_API_KEY' \
     -d $'{
      "target_channel": "push",
      "included_segments": [
        "Subscribed Users"
      ],
      "app_id": "YOUR_APP_ID",
      "contents": {
        "en": "Hello, world",
        "es": "Hola mundo",
        "fr": "Bonjour le monde",
        "zh-Hans": "你好世界"
      }
    }'
```

Once the request is sent, OneSignal forwards it to the appropriate downstream provider, which then delivers it to the recipient:

* **Push:** FCM, APNs, or HMS
* **Email:** your email service provider
* **SMS:** Twilio

### Handle the response

You receive a `200` response code if the request is valid and accepted.

* If an `id` is returned, the message was created successfully. Save this `id` for future tracking and reference of message stats via the [View message API](/reference/view-message).
* If no `id` is returned, the message was not created, likely because there are no valid [subscriptions](/docs/en/subscriptions) in the target audience.

**Response details by channel:**

* [Push](/reference/push-notification#response-id)
* [Email](/reference/email#response-id)
* [SMS](/reference/sms#response-id)

<Note>
  See our [REST API Overview](/reference/rest-api-overview#reliability-and-delivery) page for details on retries and [rate limits](/reference/rate-limits).
</Note>

***

## FAQ

### Can I combine `include_aliases`, `included_segments`, and `filters` in one request?

No. Each request must use exactly one targeting method. Mixing them returns a validation error. Choose aliases for transactional sends to specific users, segments for predefined audiences, or filters for ad-hoc audiences built with `AND`/`OR` logic.

### Does `target_channel: "sms"` cover RCS?

Yes. The `target_channel` enum accepts `"push"`, `"email"`, and `"sms"`. RCS messages are delivered through the SMS channel — there is no separate `"rcs"` value. OneSignal decides whether to send via RCS or SMS based on the recipient's device and your sender configuration.

### My request returned `200` but no `id`. What happened?

The request was valid but no message was created, typically because the target audience contains no valid subscriptions for the selected channel. Common causes include a segment that resolves to zero users, all targeted aliases being unsubscribed, or phone numbers that don't match an existing SMS subscription.

### Can I use `//` comments in the JSON request body?

No. The `//` comments in the examples on this page are illustrative only. Strict JSON does not support comments — strip them before sending to the API.

### How is the `Sent` count in reports related to the API response?

The dashboard `Sent` metric is a composite. To derive it from the [View message API](/reference/view-message), sum `successful + failed + errored`. See the [Metrics glossary](/docs/en/analytics-metrics-glossary) for the full mapping between dashboard, API, CSV, and Event Streams names.

***

## Next steps

Refer to the channel-specific APIs to customize delivery further:

* [Push notification](/reference/push-notification)
* [Email](/reference/email)
* [SMS](/reference/sms)
* [Live Activities](/reference/start-live-activity)
* [Server-Side SDKs](/docs/en/server-sdk-reference)


# Create segment
Source: https://documentation.onesignal.com/reference/create-segments

POST /apps/{app_id}/segments
Programmatically create segments in your OneSignal app using flexible filters and targeting rules.

## Overview

Use this API to create new [Segments](/docs/en/segmentation) programmatically. These segments are then accessible in the OneSignal Dashboard and usable in messages, Journeys, and in-app messaging campaigns.

<Note>
  To modify an existing segment, use the [Update segment](/reference/update-segment) API.
</Note>

***

## How to use this API

This endpoint allows your backend to define audience segments by passing in a combination of filters and logical operators like `"AND"` and `"OR"`, mirroring the segmentation capabilities of the OneSignal Dashboard.

### Name the segment

The name of the segment as it shows in the OneSignal dashboard and accessible via the `included_segments` and `excluded_segments` targeting parameters.

### Describe the segment

Optionally include a `description` (max 255 characters) to record the segment's purpose. The description is returned by the [View segments](/reference/view-segments) and [View segment](/reference/view-segment) APIs.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "10"}
  ]
}
```

### Define the `filters`

Available filters:

* [operator](#operator)
* [tag](#tag)
* [last\_session](#last_session)
* [first\_session](#first_session)
* [session\_count](#session_count)
* [session\_time](#session_time-1)
* [language](#language)
* [app\_version](#app_version)
* [location](#location)
* [country](#country)

### `operator`

**Description**

Allows you to combine or separate properties. Filters combined with an `"AND"` have higher priority than `"OR"` filters.

* `"AND"` = the 2+ connected filters must be satisfied for the recipient to be included. Filter entries use this by default and its not required to be included.
* `"OR"` = the 2 filters separated by the `"OR"` operator are mutually exclusive. The recipients only need to satisfy the conditions on either side of the `"OR"` operator.

<CodeGroup>
  ```json AND example theme={null}
  // Users must satisfy both filters to be included.
  // Notice the AND operator is not required

  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  // The same example using the AND operator. This is not required.
  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "AND"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  ```

  ```json OR example theme={null}
  // Users can satisfy either filter to be included.

  "filters": [
    {"field": "tag", "key": "level", "relation": "=", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "level", "relation": "=", "value": "20"}
  ]
  ```

  ```json Combinations theme={null}
  // In this example, users must either have:
  // The specified session_count AND tag requirement
  // Or it will be all records where last_session is satisfied
  {
    "name": "2 filters or 1",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"}
    ]
  }

  // Similar to the first example, this shows how to require a specific field
  // across other filters

  {
    "name": "3 filters, 1 required across all",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
    ]
  }
  ```
</CodeGroup>

### `tag`

**Description**

Target based on custom user [Tags](/docs/en/add-user-data-tags).

<Warning>
  Do not use tags for targeting individual users like a "user id".
  Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
</Warning>

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
  * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
* `key` = Tag key to compare.
* `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

```json theme={null}
"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "OR"},
  {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
]
```

### `last_session`

**Description**

Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "last_session", "relation": ">","hours_ago": "10"}
  ]
  ```

### `first_session`

**Description**

Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "first_session", "relation": "<","hours_ago": "24"}
  ]
  ```

### `session_count`

**Description**

Total number of sessions by the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="` or `"!="`
* `value` = number of sessions. Example: `"1"`

  ```json theme={null}
  "filters": [
    {"field": "session_count", "relation": ">","value": "5"}
  ]
  ```

### `session_time`

**Description**

Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

* `relation` = `">"` or `"<"`
* `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

  ```json theme={null}
  "filters": [
    {"field": "session_time", "relation": ">","value": "86400"}
  ]
  ```

### `language`

**Description**

[User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = 2 character language code. Example: `"en"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "language", "relation": "=","value": "en"},
    {"operator": "OR"},
    {"field": "language", "relation": "in_array","value": "es,fr,de"}
  ]
  ```

### `app_version`

**Description**

App version set on the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = app version. Example: `"1.0.0"`
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "app_version", "relation": "=","value": "1.0.1"},
    {"operator": "OR"},
    {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
  ]
  ```

### `location`

**Description**

Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

* `radius` = in meters
* `lat` = latitude
* `long` = longitude

  ```json theme={null}
  "filters": [
    {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
  ]
  ```

### `country`

**Description**

Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "=", "value": "US"},
    {"operator": "OR"},
    {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
  ]
  ```

***


# Create Subscription by alias
Source: https://documentation.onesignal.com/reference/create-subscription

POST /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions
Use this API to attach a new subscription—such as email, SMS, or push notification—to an existing OneSignal user identified by an alias.

## Overview

This API allows you to add a **new Subscription** to an existing [User](/docs/en/users) via an alias identifier. A *Subscription* reflects a user's intent to receive messages through a specific communication channel, such as email, SMS, or push notifications. See [Subscriptions](/docs/en/subscriptions) for additional context.

If you're looking to **create a new user and add Subscriptions simultaneously**, use the [Create User](/reference/create-user) API instead.

***

## How to use this API

To attach a Subscription, the user must already exist and be referenced using an alias. The `alias_label` and `alias_id` path parameters define how the user is identified:

* Common alias: `external_id`
* Other options: `onesignal_id`, or custom aliases

For details, refer to [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

## Required Fields

Each Subscription must include at least:

* `type`: the channel (e.g., `Email`, `SMS`, `iOSPush`)
* `token`: the unique identifier for the channel (e.g., email address, phone number, push token)

If the specified `type` and `token` already exist in the app, the Subscription will be transferred to the user identified in the path parameters.

***


# Create template
Source: https://documentation.onesignal.com/reference/create-template

POST /templates
Create reusable message templates for push, email, and SMS channels. Templates can be accessed through both the dashboard and API using a `template_id`.

## Overview

Use this endpoint to create a new message template in your OneSignal app. Once created, the template becomes available for use when sending messages via both the Dashboard and the REST API by referencing the `template_id`.

Templates streamline and standardize message content across push, email, and SMS channels.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Before using this endpoint, ensure that the target channel (push, email, or SMS) is properly configured in your OneSignal app. See [Channel Setup](/docs/en/channel-setup) for guidance.

### Push Templates

**Requirements:**

* Set the `contents` property with the English (`en`) language key.
* All [Push Channel Properties](/reference/push-notification) are valid for use in push templates.
* By default, all push platforms are enabled. You can target specific platforms by explicitly setting them (e.g., `isAndroid: true` disables others).

### Email Templates

**Requirements:**

* Set `isEmail: true`.
* Include both `email_subject` and `email_body`.
* All [Email Channel Properties](/reference/email) are valid for use in email templates.

### SMS Templates

**Requirements:**

* Set `isSMS: true`.
* Provide SMS-specific parameters like `contents`.
* All [SMS Channel Properties](/reference/sms) are valid for use in SMS templates.

***


# Create user
Source: https://documentation.onesignal.com/reference/create-user

POST /apps/{app_id}/users
Create a new user or modify the subscriptions associated with an existing User.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint enables you to create and manage users outside of frontendSDK-based sessions. It's primarily used to:

* Import users from other systems.
* Programmatically define users by assigning identifiers (aliases), properties (e.g., tags), and messaging subscriptions (e.g., email, mobile, SMS).

If you're using the frontend SDKs, user creation is typically handled automatically via methods like `login`, `addEmail`, and `addSms`. See [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) for conceptual guidance.

***

## How to use this API

To successfully create a user via the API:

* You must provide at least one unique identifier via the `identity` and Subscription via the `subscriptions` fields.
* You can optionally include user profile data (`properties`) and one or more messaging `subscriptions`.

## Key Concepts

### Aliases

Aliases uniquely identify a user and should include an `external_id` (the recommended identifier). They allow you to reference users across platforms or external systems. Up to 10 custom aliases are supported. Each alias key and value has a maximum length of 128 characters.

### Properties

User properties store information such as tags, location, activity, and device data. These attributes help you personalize campaigns and optimize engagement strategies.

### Subscriptions

A user can have up to **20 subscriptions** (across email, SMS, push, etc.). Subscriptions connect users to channels for message delivery and are transferable across users. See [Subscriptions](/docs/en/subscriptions) for more.

***


# Remove alias
Source: https://documentation.onesignal.com/reference/delete-alias

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}
Remove a specific alias from a user.

## Overview

Use this API to remove a specific alias from a user’s identity object without deleting the user. This operation only affects user identity labels—subscriptions and the core user record remain intact. To delete a user entirely, including all associated aliases and subscriptions, see the [Delete user](/reference/delete-user) API.

***

## How to use this API

To remove an alias from a user:

1. Identify the user via a known alias by specifying:

   * `alias_label` – the type of alias (e.g., email, external\_id)
   * `alias_id` – the unique identifier for that alias

2. Specify the alias to remove using:

   * `alias_label_to_delete` – the label of the alias to be deleted

   The `alias_label_to_delete` can be the same as the `alias_label` used to identify the user.

3. This action is performed synchronously—the alias is deleted immediately after the request is processed.

<Warning>
  The `onesignal_id` alias cannot be deleted. Only secondary aliases (like email, external\_id, etc.) are removable.
</Warning>

For a full explanation of identity management, see [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

***

## FAQ

### Can I delete the same alias that I used to look up the user?

Yes. This is a common scenario—especially if an alias was set incorrectly and needs to be removed. Just be sure to include that alias both as the identifier and as alias\_label\_to\_delete.

If you want to delete the entire user and all associated data, use the [Delete user](/reference/delete-user) API.

### What happens if I delete all aliases associated with the user?

A user will always retain at least one alias, the onesignal\_id. Even if you remove all other aliases, the user and their subscriptions remain linked to the onesignal\_id.

***


# Delete API key
Source: https://documentation.onesignal.com/reference/delete-api-key

DELETE /apps/{app_id}/auth/tokens/{token_id}
Delete a specific Rich Authentication Token (App API Key) for a OneSignal app. Requires your Organization API Key and the token's unique ID, not the token value itself.

## Overview

Use this API to delete a specific App API Key (Rich Authentication Token) for a single OneSignal.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Delete segment
Source: https://documentation.onesignal.com/reference/delete-segments

DELETE /apps/{app_id}/segments/{segment_id}
Delete segments from OneSignal. Does not delete users or subscriptions.

## Overview

The Delete segment method is used when you want to programmatically delete a segment from within the OneSignal Dashboard UI.

<Warning>
  Once a segment is deleted, it cannot be recovered. You will need to create a new segment with the same filters.
</Warning>

***

## How to use this API

You can pass in the `segment_id` dictating which segment from our dashboard will be deleted.

The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard as shown below:

<Frame>
  <img />
</Frame>

***


# Delete Subscription
Source: https://documentation.onesignal.com/reference/delete-subscription

DELETE /apps/{app_id}/subscriptions/{subscription_id}
Delete a specific subscription by its subscription_id. This stops messages from being sent to that subscription but does not prevent future subscriptions with the same token.

## Overview

Use this API to delete an existing Subscription and its associated properties. Deletion is **asynchronous**, and while the Subscription is being removed, messages will no longer be sent to it.

<Warning>
  This operation only deletes a **single Subscription**. To remove a **user and all their Subscriptions**, use the [Delete User](/reference/delete-user) API instead.
</Warning>

### What Happens When You Delete

* Messages will stop being sent to the deleted subscription.
* **Deleting a Subscription does not block new Subscriptions** with the same `token`.
  * If the app is reopened or a token is re-submitted (e.g., same email or phone), a **new Subscription** may be automatically created.
  * This ensures users can re-subscribe if needed without requiring manual intervention.

***

## How to Use This API

**Required:** `subscription_id`

You must provide the `subscription_id` of the subscription to be deleted. This ID is a UUID generated by OneSignal and is immutable.

To find the `subscription_id`:

1. Use the [View User](/reference/view-user) API.
2. Look at the `subscriptions` array in the response.
3. Identify the correct subscription by its `type`, `token`, or other metadata.
4. Use the corresponding `id` field as the `subscription_id`.

***


# Delete template
Source: https://documentation.onesignal.com/reference/delete-template

DELETE /templates/{template_id}?app_id={app_id}
Permanently delete a specific message template from your OneSignal app using its template ID. Templates used in Journeys must be removed from those Journeys before deletion.

## Overview

This endpoint allows you to delete a single template associated with your OneSignal app. Deletion is **immediate and irreversible**.

<Warning>
  If the template is currently used in a Journey, it cannot be deleted until that Journey has been deleted.
</Warning>

***

## How to use this API

Required Parameters

* `template_id` (path param): The OneSignal-generated UUID of the template to delete.
* `app_id` (query param): Your OneSignal App ID.

### Where to Find `template_id`

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# Delete user
Source: https://documentation.onesignal.com/reference/delete-user

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}
Delete a user including all associated properties, subscriptions, and identity.

## Overview

Use this API to permanently delete a user from your OneSignal project, including all associated subscriptions, properties, and aliases. The operation is asynchronous—user data will be deleted shortly after the request is accepted.

***

## How to use this API

To delete a user, you must be able to identify them using one of the following alias types:

* `external_id` (recommended and most common)
* `onesignal_id`
* A custom Alias that you have set

Pass the appropriate `alias_label` and corresponding `alias_id` in the request path.

<Warning>
  This operation deletes all data associated with the user, including:

  * All identity aliases
  * All channel subscriptions (push, email, SMS, etc.)
  * All custom user properties
</Warning>

## Because this is an irreversible operation, be sure that you really intend to delete the user and all their data.


# Email
Source: https://documentation.onesignal.com/reference/email

POST /notifications?c=email
Send a message using the email channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for email. See [Push notification](/reference/push-notification) or [SMS](/reference/sms) to send to those channels.

Ensure your [Email setup](/docs/en/email-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# View user identity
Source: https://documentation.onesignal.com/reference/fetch-aliases

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Retrieve all aliases associated with a user using a known alias, such as an `external_id`, `onesignal_id`, or a custom alias. This API helps you map back to a user’s full identity from any one piece of identifying information.

## Overview

Use this API when you want to retrieve the complete identity object for a user, which includes all aliases tied to that user. It is ideal for cases where you know one alias and want to discover others—especially helpful for user mapping, debugging, or linking systems.

This endpoint is similar to the [View user](/reference/view-user) API but only returns the `identity` object—not subscriptions or properties.

<Tip>
  If you only know a subscription\_id, use View user identity (by subscription) instead.
</Tip>

For more context on user identity and aliasing:

* [Users](/docs/en/users)
* [Aliases](/docs/en/aliases)

***

## How to use this API

To identify the user, use:

* `alias_label` – the type of alias you’re using to find the user (e.g. `external_id`, `onesignal_id`, or a custom alias)
* `alias_id` – the actual value of that alias

Common usage patterns:

Using `external_id` (recommended):

* `alias_label`: `external_id`
* `alias_id`: your user ID (e.g., user-123)

Using `onesignal_id`:

* `alias_label`: `onesignal_id`
* `alias_id`: the OneSignal-assigned unique ID

Using a custom alias:

* Define your own alias label (e.g. `shopify_customer_id`) and its value

<Note>
  We strongly recommend setting and using the `external_id` as your primary user identifier for portability and simplicity across your systems.
</Note>

***


# View user identity (by subscription)
Source: https://documentation.onesignal.com/reference/fetch-identity-by-subscription

GET /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Retrieve all aliases linked to a user using a known `subscription_id`. This is useful when the user’s identity is unknown but you have access to one of their push, email, or SMS subscriptions.

## Overview

Use this API when you want to find the full identity (all aliases) of a user, starting from a known `subscription_id`. This is helpful for debugging, reverse lookups, or support use cases where only a subscription record is available.

<Note>
  Unlike the [View user identity](/reference/fetch-aliases) API which starts with an alias (e.g., `external_id`), this endpoint works when only a subscription ID is known.
</Note>

See [Subscriptions](/docs/en/subscriptions) for background on how subscriptions relate to users.

***

## How to use this API

To use this endpoint, you must provide:

* `subscription_id` – A UUID generated by OneSignal when a device or channel (e.g., push, email, SMS) is registered.

<Warning>
  `subscription_id` values are immutable and cannot be changed. Make sure you are using the correct value, as they are unique to each app and platform.
</Warning>

Once a valid `subscription_id` is provided, the API will return the user’s identity object, which includes all associated aliases like `external_id`, `onesignal_id`, and any custom aliases.

***


# Idempotent API requests
Source: https://documentation.onesignal.com/reference/idempotent-notification-requests

Prevent duplicate messages or custom events when retrying API requests.

## Overview

When you create messages or custom events via our REST API, network failures or timeouts can cause uncertainty about whether a request succeeded. **Idempotent requests** solve this problem by ensuring the same request is only processed once—even if it is sent multiple times.

This page explains how idempotency works in OneSignal, when to use it, and common pitfalls to avoid.

### When you should use idempotency

You should use idempotent requests any time you plan to retry API calls, especially when:

* You receive a timeout, 500-level error, or no response.
* Your infrastructure automatically retries failed requests.
* Delivering a duplicate message or custom event would be harmful.
* Missing a message or custom event would be harmful.

### The problem idempotency solves

Consider this common failure scenario:

1. You send a `notifications#create` or `custom_events#create` request.
2. OneSignal begins processing and sending the message or event.
3. A network error occurs before your client receives a response.

At this point, your system cannot know whether the request succeeded.

* If you retry and the request already succeeded, users may receive duplicates.
* If you do not retry and the request failed, users may miss important messages or events.

**Idempotency provides a safe retry mechanism.**

***

## How idempotency works

OneSignal supports idempotent operations for:

* [`notifications#create`](/reference/create-message)
* [`custom_events#create`](/reference/create-custom-events)

You provide a unique `idempotency_key` with each request.

### Request flow with idempotency

1. You send a request with an `idempotency_key`.
2. OneSignal processes the request and begins sending the message or creating the custom event.
3. A network error or timeout occurs.
4. You retry the request using the same `idempotency_key`.
5. OneSignal detects the duplicate and returns the result of the original request.
6. Only one notification or custom event is processed.

You can repeat this retry any number of times. As long as the `idempotency_key` remains the same, the operation will only be processed once.

***

## Idempotency key reference

<ParamField type="RFC 9562 UUID">
  A unique identifier used to prevent duplicate messages or custom events from repeat API calls. Keys must be unique [RFC 9562 UUID format](https://en.wikipedia.org/wiki/Universally_unique_identifier). Valid for 30 days.
</ParamField>

<Note>
  This `idempotency_key` property used to be called `external_id` but caused confusion with our [Users `external_id`](/docs/en/users) alias, so we have added this new property name to reduce confusion. Both will work in this case.
</Note>

***

## Important constraints and gotchas

<Warning> If you reuse the same `idempotency_key` for different messages or events, only the first request will be processed. </Warning>

Keep the following in mind:

* **Keys must be unique per logical operation**
  Generate a new UUID for every notification or custom event you intend to send.

* **Keys are retained for 30 days**
  After 30 days, OneSignal may delete the record. Reusing the same key after that window may result in a new message being sent.

* **Use a strong source of randomness**
  Predictable or reused UUIDs can cause unexpected deduplication.

* **Idempotency does not guarantee delivery**
  It only guarantees at-most-once processing. You should still monitor API responses and logs.

### Legacy behavior

The `idempotency_key` property was previously named `external_id`. This caused confusion with the Users `external_id` alias, so `idempotency_key` is now the recommended field name. Both names are currently supported.

### Best practices

* Always include `idempotency_key` when implementing retries.
* Store the `idempotency_key` alongside your request metadata for debugging.
* Retry only after honoring any `Retry-After` header returned by the API.
* Combine idempotency with proper timeout handling (for example, a 60-second HTTP timeout).

***


# Message history
Source: https://documentation.onesignal.com/reference/message-history

POST /notifications/{message_id}/history
View which subscriptions received a particular message

## Overview

This API enables you to retrieve all [Subscriptions](/docs/en/subscriptions) that received a specific push notification or email. You can access the notification's history for up to seven days after it was sent. Please note that notifications sent to fewer than 1,000 recipients will not record a "received" event, but they will still record "sent" events.

***

## How to Use this API

1. Submit a request to generate a report.

2. Decide delivery method

   * After receiving a successful response, **poll the destination URL** until the file becomes available. Exports typically complete within 1-3 minutes; we recommend a 10-second polling interval.
   * Alternatively, you can opt to receive an email to the address specified in the optional `email` parameter when the report is ready.

### Requirements

* A [OneSignal Professional or Enterprise Plan](https://onesignal.com/pricing).
* Enabled the "Send History via OneSignal API" option in Settings -> Integrations; notifications sent before this setting is enabled can't be retrieved.
* Requests must be made within seven days of sending the notification.

### Polling

Use the `csv_file_url` property in the response to test if the report is complete. If you receive a '403' error response, retry fetching the file after a short period; it only means we're still generating the report.

### Sample Report

The generated report is a simple CSV file that can be imported into any system for further processing.

```csv report.csv theme={null}
player_id,onesignal_id,external_id,target_channel,timestamp
"2c4fac95-7dfb-4113-9347-aba3a92ff557","ccddf35a-1233-4423-8a57-ac8c4b38eb81","a07aec27-2586-4b92-a24f-62660a1517fa","push","1628189160"
"68f5cf73-b20a-4de9-b6ee-79a863b8e7d8","d2f9f2f8-94af-4942-8183-115cef1213d5","4b66359f-3d94-4a73-806d-8ef5f0430b3d","push","1628187816"

```

### Limitations

* Querying for `opens` events are not supported.
* The `timestamp` column is included only for `clicked` events.

***


# Push notification
Source: https://documentation.onesignal.com/reference/push-notification

POST /notifications?c=push
Send a message using the push notification channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for push. See [Email](/reference/email) or [SMS](/reference/sms) to send to those channels.

Ensure your application is properly configured by following the [Mobile SDK Setup](/docs/en/mobile-sdk-setup) and/or [Web SDK Setup](/docs/en/web-sdk-setup) guides. You should see subscribed push [Subscriptions](/docs/en/subscriptions) in your OneSignal dashboard to send them messages.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Rate limits and error handling
Source: https://documentation.onesignal.com/reference/rate-limits

Understand OneSignal API and application rate limits, common errors, retry behavior, and how to safely recover from failures without sending duplicate messages or disabling your app.

OneSignal uses rate limits and error responses as safety mechanisms to protect your app from accidental overloads, duplicate sends, and retry storms.

There are three categories to understand:

* **API rate limits** return HTTP `429` errors when request volume is too high.
* **Network timeouts or temporary server failures** return `5xx` errors or no response at all.
* **Application message limits** may temporarily disable your app if too many messages are sent in a short period.

<Info>
  Most apps never hit these limits during normal usage. When they do occur, they are usually caused by retries, loops, or unexpected audience expansion.
</Info>

<Check>
  **Quick implementation checklist**

  * Expect `429`, `5xx`, and timeouts. They are normal at scale.
  * Never retry message sends without an `idempotency_key`.
  * For non-urgent retries, wait **100 seconds** before retrying.
  * API rate limits (`429`) never disable your app.
  * Only message volume limits can disable your app.
  * `POST /notifications` (create) and `DELETE /notifications` (cancel) count toward the same rate limit.
  * The [Create custom events](/reference/create-custom-events) endpoint has its own rate limit, separate from the notification endpoints.
</Check>

***

## API rate limits

API rate limits apply **per app and per endpoint**. They are evaluated when a request is received, not when a response is returned.

These limits are designed to throttle traffic, not block your app.

| Endpoint                                                                                  | Rate limit                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create message](/reference/create-message) / [Cancel message](/reference/cancel-message) | **Free plans:** 150 requests/sec/app<br />**Paid plans:** 6,000 requests/sec/app<br /><br />The `POST /notifications` and `DELETE /notifications` endpoints share the same limit. Requests count toward it regardless of method. For example, 3,000 creates + 3,000 cancels = 6,000 requests/sec on a paid plan.<br /><br />Each request can target many users or segments. |
| [Create custom events](/reference/create-custom-events)                                   | Rate-limited independently from Create Message.<br />**Request size limits:** 2,024 bytes per event · 1 MB per request body                                                                                                                                                                                                                                                 |
| Create, update, or delete users or subscriptions                                          | 1,000 requests/sec/app<br />1 request/sec per user or subscription<br />Up to 100 property updates per request                                                                                                                                                                                                                                                              |
| View endpoints (messages, templates, users)                                               | 1 request/sec/app<br />Up to 10 look-back requests/sec                                                                                                                                                                                                                                                                                                                      |
| Message History and CSV exports                                                           | Keep parallel exports under 100 GB per file                                                                                                                                                                                                                                                                                                                                 |

<Note>
  High-volume messaging should use fewer message creation requests with larger audiences instead of increasing request frequency.
</Note>

**Handling API rate limit errors (`429`):**

When you exceed an API rate limit, OneSignal returns an HTTP `429` response:

```json theme={null}
{
  "errors": ["API rate limit exceeded."]
}
```

The response includes a `Retry-After` header indicating how many seconds to wait before retrying.

**What to do when you receive a `429` error:**

1. Stop sending requests immediately.
2. Wait for the full duration specified in the `Retry-After` header.
3. Retry using exponential backoff.
4. Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for retries that send messages.

<Warning>
  Retrying before the `Retry-After` delay or retrying in tight loops can extend throttling and increase failure rates.
</Warning>

***

## Error handling and retry strategies

Retries are safe only when implemented correctly. Some failed requests may still be processing on our servers.

* Retriable errors generally include network timeouts, no responses, 429, and 5xx errors.
* Non-retryable errors include 400, 401, or 403 errors which indicate invalid input, authentication problems, or missing permissions. These are not temporary failures.

**Simple retry strategy:**

* Wait **100 seconds** before retrying.
  * This aligns with the maximum API response timeout.
  * If no response or network error occurs, the request may still be processing during this window.
* Retry **up to 3 total attempts** (original + 2 retries).
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

**Time-sensitive (advanced) retry strategy:**

* Retry using exponential backoff with jitter (for example: 2s, 4s, 8s… up to 60s).
* Cap retries to **10 total attempts** and stop after **10–15 minutes**.
* For `429` responses, treat `Retry-After` as a minimum delay: wait `max(Retry-After, backoff)`.
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

<Warning>
  Retrying message or custom event API requests without idempotency can result in duplicate messages or custom events.
</Warning>

<Accordion title="Example retry logic">
  ```text theme={null}
  attempt = 1
  max_attempts = 3

  send request with idempotency_key

  if response is success:
    stop

  if response is 429:
    wait Retry-After seconds
  elif response is 5xx or timeout:
    wait 100 seconds

  if attempt < max_attempts:
    retry with same idempotency_key
  else:
    fail safely
  ```
</Accordion>

### Retry decision guide

| Error type              | Retry? | When                 | Idempotency required |
| ----------------------- | ------ | -------------------- | -------------------- |
| `429 Too Many Requests` | Yes    | After `Retry-After`  | Yes                  |
| `5xx Server Error`      | Yes    | Backoff or 100s      | Yes                  |
| Timeout / no response   | Yes    | Immediate or delayed | Yes                  |
| `400 Bad Request`       | No     | Fix request          | No                   |
| `401 / 403`             | No     | Fix auth/permissions | No                   |

<Warning>
  Common implementation mistakes:

  * Retrying with a new idempotency key on each attempt.
  * Retrying indefinitely without a retry cap.
  * Retrying `400` or `401` errors without fixing the request.
  * Sending one request per user instead of batching audiences.
</Warning>

***

## Application message limits (app disablement)

Application message limits protect your users from receiving too many notifications in a short period of time.

**How the limit works:**

In any rolling 15-minute window, you may send up to **10 × your total number of subscribed [Subscriptions](/docs/en/subscriptions)**.

This limit is based on the total number of messages delivered, not the number of API requests.

* Sending 1 notification to 1,000 Subscriptions = 1,000 messages
* Sending 10 notifications to 1,000 Subscriptions each = 10,000 messages

The 15-minute window is rolling, not fixed.

* Messages are counted for 15 minutes after they are sent
* As time passes, older messages automatically stop counting
* You only exceed the limit if more than 10× your subscribed Subscriptions receive messages within the same 15-minute span

Example limits:

* App with 1,000 subscribed Subscriptions → up to 10,000 messages in any 15 minutes
* App with 10,000 subscribed Subscriptions → up to 100,000 messages in any 15 minutes

**Example scenarios:** App with 1,000 subscribed Subscriptions (limit: 10,000 messages per 15 minutes)

| Scenario                                                                              | Messages counted in any 15-minute period |    App disabled?    |
| ------------------------------------------------------------------------------------- | ---------------------------------------: | :-----------------: |
| At **12:00**, send 1 notification to 1,000 users                                      |                                    1,000 |          No         |
| At **12:00**, send 10 notifications to 1,000 users                                    |                                   10,000 |   Yes (hits limit)  |
| Between **12:00–12:14**, send 10,000 notifications to 1 user                          |                                   10,000 |   Yes (hits limit)  |
| Send **9,000 messages at 12:00**, then **9,000 more at 12:16**                        |                                    9,000 |          No         |
| Send **9,000 messages spread between 12:00–12:14**, then send **9,000 more at 12:15** |                                 \~18,000 | Yes (exceeds limit) |

<Note> This limit is evaluated continuously over a rolling 15-minute window, not in fixed time blocks. If any 15-minute span exceeds your limit, the app is disabled. </Note>

**What happens if the limit is exceeded:**

If your app sends more messages than allowed within a 15-minute window:

* Your app is temporarily disabled
* All app administrators receive an email notification
* A re-enable banner appears in the OneSignal Dashboard

<Warning> Only application message limits can disable your app. API rate limits (`429` errors) never disable apps. </Warning>

**What to do if your app is disabled:**

If your app is disabled, follow these steps in order:

1. Pause message sending from your backend, jobs, or automations.
2. Identify the cause, such as infinite loops, retry storms, or unexpected segment growth.
3. Log in to the OneSignal Dashboard.
4. Click **Re-enable** in the red banner at the top of the app.
5. If you need help re-enabling your app, contact `support@onesignal.com`.

***

## FAQ

### Do API rate limits disable my app?

No. API rate limits (`429` errors) only throttle your requests temporarily. Only [application message limits](#application-message-limits-app-disablement) — which track the total volume of messages delivered — can disable your app.

### What is an idempotency key and when do I need one?

An idempotency key is a unique identifier you include with a request so that retrying the same request does not create a duplicate message or event. You need one whenever you retry a `POST /notifications` or custom event request. Reuse the same key for every retry attempt. See [Idempotent API requests](/reference/idempotent-notification-requests).

### Can I increase my API rate limit?

Paid plans have higher rate limits (6,000 requests/sec vs. 150 for free plans). If you need limits beyond the paid tier, contact `support@onesignal.com` with your use case and expected volume.

### Why was my app disabled even though I didn't hit the API rate limit?

API rate limits and application message limits are separate. Your app can be disabled if the total number of messages delivered in any 15-minute window exceeds 10× your subscription count — even if every individual API request succeeded. Common causes include retry storms, runaway automations, or targeting a larger audience than intended.

***

## Related pages

<Columns>
  <Card title="Idempotent API requests" icon="rotate" href="/reference/idempotent-notification-requests">
    Prevent duplicate messages by reusing idempotency keys on retries.
  </Card>

  <Card title="Create message API" icon="paper-plane" href="/reference/create-message">
    API reference for sending push, email, SMS, and in-app messages.
  </Card>

  <Card title="Create custom event API" icon="bolt" href="/reference/create-custom-events">
    API reference for sending custom events that trigger Journeys.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="/docs/en/subscriptions">
    Understand how subscriptions are counted toward message limits.
  </Card>
</Columns>


# REST API overview
Source: https://documentation.onesignal.com/reference/rest-api-overview

Programmatic access to OneSignal messaging, user management, segments, and data exports over HTTPS with rate limiting and retry support.

The OneSignal REST API follows the [REST architecture](https://en.wikipedia.org/wiki/Representational_state_transfer) and provides programmatic access to core messaging and user features. Use the API to send push notifications, emails, and SMS, manage Users, Subscriptions, Segments, export data, and configure apps.

## Which API to use

| Goal                          | API                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| Send a push, email, or SMS    | [Create Message](/reference/create-message)                                                              |
| Add or update user data       | [Create User](/reference/create-user) / [Update User](/reference/update-user)                            |
| Target a group of users       | [Create Segments](/reference/create-segments) or use [Filters](/reference/create-message#filters) inline |
| Export analytics or user data | [CSV Export](/reference/csv-export) / [CSV of Events](/reference/export-csv-of-events)                   |
| Manage app configuration      | [Create App](/reference/create-an-app) / [Update App](/reference/update-an-app)                          |

***

## Requirements

**General**

* **HTTPS required**: All API requests must use HTTPS with **TLS 1.2 or higher** on port `443`.
* **Network access**: Firewalls or proxies must allow **outbound traffic** to `https://api.onesignal.com` on port `443`.
* **DNS TTL**: Clients must respect OneSignal’s DNS **TTL of 300 seconds** to avoid stale IP resolution.

**Incoming Traffic to OneSignal (API & SDK Requests)**

All incoming API traffic—whether from your backend, the OneSignal SDKs, or the dashboard—passes through **Cloudflare**, which serves as the global edge network.

* You may see Cloudflare IP addresses in logs.
* Cloudflare IPs may change over time.
* If you maintain a strict firewall, use Cloudflare’s official [IP ranges](https://www.cloudflare.com/ips/)

<Warning>
  Avoid allowlisting specific Cloudflare IPs, as they may change without notice.
</Warning>

**Outgoing Traffic from OneSignal (Webhooks & Event Streams)**

For features where OneSignal sends HTTP requests to your servers (such as webhooks or event streams), traffic originates from OneSignal infrastructure running on Google Cloud Platform (GCP) in the `europe-west4` region (Groningen, Netherlands).

* Allow inbound traffic from `https://api.onesignal.com`, **or**
* Use GCP’s maintained IP range list and filter by `europe-west4` region: [GCP IP ranges](https://www.gstatic.com/ipranges/cloud.json)

<Note>
  OneSignal supports [IP allowlisting](/docs/en/keys-and-ids) with REST API keys.
</Note>

***

### Platform-specific network requirements

#### FCM (Google Android and Chrome push)

* Required ports: `5228`, `443`, `5229`, and `5230`
* No IP allowlisting needed
* More info: [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

#### APNs (Apple iOS, iPadOS, Safari push)

* Required ports: `5223`, `443`, and `2197`
* Recommended servers:
  * Sandbox: `api.sandbox.push.apple.com:443`
  * Production: `api.push.apple.com:443`
  * IP range: `17.0.0.0/8`
* More info:
  * [Apple Support](https://support.apple.com/en-us/102266)
  * [APNs Developer Docs](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns?language=objc)

***

## Core API capabilities

### Send messages

See the [Create Message guide](/reference/create-message) to get started. Programmatically send:

<Columns>
  <Card title="Push Notifications" icon="bell" href="/reference/push-notification">
    Send push notifications to apps and websites.
  </Card>

  <Card title="Email" icon="envelope" href="/reference/email">
    Send transactional and promotional emails.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/reference/sms">
    Send SMS or MMS messages globally.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="/reference/start-live-activity">
    Send Live Activity updates to iOS devices.
  </Card>
</Columns>

<Note>
  For platform-specific features like personalization, throttling, and frequency capping, see the [Push](/docs/en/push), [Email](/docs/en/email-messaging), [SMS](/docs/en/sms-messaging), and [Live Activities](/docs/en/live-activities) overview guides.
</Note>

***

### Manage templates

[Templates](/docs/en/templates) are reusable push, email, and SMS messages that simplify development and improve consistency.

<Columns>
  <Card title="Create template" icon="plus" href="/reference/create-template">
    Save a reusable message layout for push, email, or SMS.
  </Card>

  <Card title="Update template" icon="pen-to-square" href="/reference/update-template">
    Modify an existing template's content or settings.
  </Card>

  <Card title="View templates" icon="eye" href="/reference/view-templates">
    List all templates in your app with their metadata.
  </Card>

  <Card title="Delete template" icon="trash" href="/reference/delete-template">
    Permanently remove a template from your app.
  </Card>
</Columns>

***

### Track custom events

[Custom events](/docs/en/custom-events) record user actions like purchases, content views, or milestones. Use them to enter users into [Journeys](/docs/en/journeys-settings) or trigger [Wait Until](/docs/en/journeys-actions) nodes.

<Card title="Create custom events" icon="bolt" href="/reference/create-custom-events">
  Record user events to trigger Journeys and track behavior.
</Card>

***

### Manage Users and Subscriptions

See the [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) guides for more details.

<Columns>
  <Card title="Create user" icon="user-plus" href="/reference/create-user">
    Create a user with optional aliases and subscriptions.
  </Card>

  <Card title="View user" icon="eye" href="/reference/view-user">
    View user details.
  </Card>

  <Card title="Update user" icon="user-pen" href="/reference/update-user">
    Modify a User's properties, tags, or aliases.
  </Card>

  <Card title="Delete user" icon="user-minus" href="/reference/delete-user">
    Permanently remove a User and all associated data.
  </Card>
</Columns>

***

### Manage Segments

[Segments](/docs/en/segmentation) group Users by filters for targeted messaging.

<Columns>
  <Card title="Create Segments" icon="plus" href="/reference/create-segments">
    Define a new Segment with filters to group Users.
  </Card>

  <Card title="Update Segment" icon="pen-to-square" href="/reference/update-segment">
    Modify a Segment's name or replace its filters.
  </Card>

  <Card title="Delete Segments" icon="trash" href="/reference/delete-segments">
    Permanently remove a Segment from your app.
  </Card>
</Columns>

<Note>
  You can also target users dynamically using [filters](/reference/create-message#filters) without creating persistent segments.
</Note>

***

### Export data

For analytics breakdowns, see [Analytics overview](/docs/en/analytics-overview).

<Columns>
  <Card title="Export CSV of subscriptions" icon="file-export" href="/reference/csv-export">
    Export all user and subscription data.
  </Card>

  <Card title="Export CSV of events" icon="file-export" href="/reference/export-csv-of-events">
    Export events like sent, received, and clicked.
  </Card>

  <Card title="View messages" icon="eye" href="/reference/view-messages">
    View message details and analytics.
  </Card>

  <Card title="View message" icon="magnifying-glass" href="/reference/view-message">
    View individual message details.
  </Card>
</Columns>

***

### Manage Apps & API Keys

OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See [Apps, orgs, & accounts](/docs/en/apps-organizations).

<Columns>
  <Card title="Create an app" icon="plus" href="/reference/create-an-app">
    Register a new app with platform credentials.
  </Card>

  <Card title="Update an app" icon="pen-to-square" href="/reference/update-an-app">
    Modify app settings or platform credentials.
  </Card>

  <Card title="View single app" icon="eye" href="/reference/view-an-app">
    Retrieve configuration and details for one app.
  </Card>

  <Card title="View multiple apps" icon="list" href="/reference/view-apps">
    List all apps in your account.
  </Card>
</Columns>

#### API key management

See [Keys & IDs](/docs/en/keys-and-ids) for more details.

<Columns>
  <Card title="Create API key" icon="key" href="/reference/create-api-key">
    Generate a new API key with specific permissions.
  </Card>

  <Card title="View API keys" icon="eye" href="/reference/view-api-keys">
    List all API keys and their permissions for your app.
  </Card>

  <Card title="Delete API key" icon="trash" href="/reference/delete-api-key">
    Revoke an API key permanently.
  </Card>

  <Card title="Update API key" icon="pen-to-square" href="/reference/update-api-key">
    Modify an API key's permissions or IP allowlist.
  </Card>
</Columns>

***

## Error handling and retries

The OneSignal API may return temporary errors such as `429` (rate limited), `5xx` (server errors), or timeouts. When this happens, the request may still be processing. If you retry failed requests, always use an `idempotency_key` and follow the recommended retry delays to avoid duplicate messages.

<Card title="Rate limits and error handling" icon="triangle-exclamation" href="/reference/rate-limits">
  Retry strategies, error definitions, and recovery steps.
</Card>

***

## FAQ

### What is the timeout for API responses?

* Default: **100 seconds**
* If you're unsure whether a request completed, use an [`idempotency_key`](/reference/idempotent-notification-requests) to safely retry.
* See [Rate limits and error handling](/reference/rate-limits) for more details.

### Do I need to download or renew certificates to call the OneSignal API?

No. The OneSignal API uses HTTPS with a publicly trusted TLS certificate managed by Cloudflare. These edge certificates renew automatically and are trusted by all major browsers, operating systems, and runtimes.

If your network pins a specific leaf certificate, it will expire and rotate every few months — this is normal Cloudflare behavior. Trust the root and intermediate CAs in the chain instead of the leaf certificate to avoid disruption.

<Accordion title="Certificate pinning details and workarounds">
  * **Best practice**: Trust the root and intermediate CAs in the chain instead of the rotating leaf certificate.
  * **If you must pin a certificate**: Pin the public key (SPKI) of the CA or use a backup key set, not the exact leaf certificate.
  * **Fetching the current certificate**: If your process requires the active leaf certificate, retrieve it directly:

  ```bash theme={null}
  SERVERNAME=api.onesignal.com
  echo -n | openssl s_client -connect $SERVERNAME:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/${SERVERNAME}_current.pem
  ```

  To retrieve the full chain, add the `-showcerts` flag to `openssl s_client`.

  See [Cloudflare SSL/TLS documentation](https://developers.cloudflare.com/ssl/get-started/) and [Cloudflare Edge Certificates documentation](https://developers.cloudflare.com/ssl/edge-certificates/) for more details.
</Accordion>

### Why am I getting a 403 Forbidden error?

A `403` response means the API key is valid but does not have permission for the requested operation. Check the following:

* **Wrong key type**: App API keys work for app-level endpoints (sending messages, managing Users). Organization API keys are required for org-level endpoints (creating apps, managing API keys). See [Keys & IDs](/docs/en/keys-and-ids) for details.
* **IP allowlisting**: If IP allowlisting is enabled on your API key, requests from IPs not on the list are denied. Verify your server's IP is included.
* **Revoked or rotated key**: If the key was recently rotated, the old key is no longer valid. Update your integration with the new key.

### Why am I getting "UnknownHostException - Unable to resolve host api.onesignal.com"?

This error means your environment cannot resolve the DNS for `api.onesignal.com`. Common causes:

* **Firewall or proxy blocking DNS**: Ensure your network allows outbound DNS queries and traffic to `api.onesignal.com` on port `443`.
* **No internet connectivity**: Verify the device or server has an active network connection.
* **DNS server misconfiguration**: Try a public DNS resolver like `8.8.8.8` (Google) or `1.1.1.1` (Cloudflare) to rule out local DNS issues.
* **Stale DNS cache**: Flush your local DNS cache and ensure your client respects the TTL of 300 seconds.


# SMS
Source: https://documentation.onesignal.com/reference/sms

POST /notifications?c=sms
Send a message using the SMS channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for SMS and MMS. See [Push notification](/reference/push-notification) or [Email](/reference/email) to send to those channels.

Ensure your [SMS setup](/docs/en/sms-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***

## Trackable links

Add trackable links to your SMS `contents` using [liquid syntax](/docs/en/using-liquid-syntax) in the format `{{'your_url' | track_link}}`.

Example:

```json JSON theme={null}
{
  "contents": {
    "en": "Hi, here's my link: {{'https://example.com' | track_link}} "
  }
}
```

In this example, the liquid syntax block will be replaced with a trackable short link and display in the message as: `1sgnl.co/XXXX`.

<Note>
  See [SMS trackable links](/docs/en/links#sms) for more details.
</Note>

***


# Start Live Activity
Source: https://documentation.onesignal.com/reference/start-live-activity

POST /apps/{app_id}/activities/activity/{activity_type}
Remotely start a Live Activity on iOS devices via OneSignal's REST API. Define the activity type, target users, and send dynamic, updatable content directly to a Live Activity interface.

## Overview

Remotely start an iOS Live Activity using OneSignal’s REST API. Live Activities provide real-time updates directly on the lock screen and Dynamic Island (on supported devices), enhancing user engagement with ongoing events like sports games, deliveries, or countdowns.

***

## How to use this API

1. Define a Live Activity in your app. See [Live Activities developer setup](/docs/en/live-activities-developer-setup) to get started.
2. Use the `activity_type` parameter to specify the type of the Live Activity UI to use.
3. Select your target audience to receive the Live Activity. Target all or individual users.
4. Generate a unique `activity_id` to track and manage your Live Activity.
5. Use the `event_attributes` parameter to initialize the Live Activity with static data.
6. Use the `event_updates` parameter to update the Live Activity with dynamic content.

### Select your target audience

Before sending a message, you need to determine who should receive it. OneSignal offers three targeting options:

1. **Aliases & Subscription IDs**: Send messages to specific users using unique identifiers such as External ID (recommended), OneSignal ID, custom alias, or subscription ID.
2. **Segments**: Target predefined user groups based on attributes and behavior.
3. **Filters**: Create custom targeting rules using user properties, such as tags, location, or activity.

<Note>
  You can only use one targeting method per message. For example, you cannot combine alias-based targeting with filters in the same request.

  See [Select your target audience](/reference/create-message#select-your-target-audience) for more information.
</Note>

### Set a unique `activity_id`

* Set a unique `activity_id` to track and manage the Live Activity. This value is crucial for maintaining a consistent reference to the Live Activity across different devices and sessions. Consider using a UUID, CUID, or NanoID for this parameter.
* Ensure that the `activity_id` is unique and consistently used for each Live Activity to avoid conflicts and ensure accurate tracking.

  ```json Example theme={null}
  {
    "activity_id": "217aae2b-42ee-4097-bc3f-b7a6e9d15b9b",
    ...
  }
  ```

<Info>
  See [Live Activities developer setup](/docs/en/live-activities-developer-setup) guide for more information.
</Info>

### Set `event_attributes` to initialize the Live Activity

Set default/static data to display in the Live Activity upon start.

```json Example theme={null}
{
  "event_attributes": {
  	"awayTeam": "Away Team Name",
    "homeTeam": "Home Team Name"
  }
}
```

### Set `event_updates` for dynamic content

The content used to update a running Live Activity. The object must conform to the `ContentState` interface defined within your app's Live Activity. See [Live Activities developer setup](/docs/en/live-activities-developer-setup).

Ensure that the `event_updates` object matches the [`ContentState`](https://developer.apple.com/documentation/activitykit/activityattributes/contentstate#) interface exactly as defined in your Live Activity implementation. Inconsistencies can cause Live Activities to fail to display.

```json Example theme={null}
{
  "event_updates": {
    "quarter": 1,
    "homeScore": 70,
    "awayScore": 78,
    "inTimeout": false
  }
}
```

***


# Transfer Subscription
Source: https://documentation.onesignal.com/reference/transfer-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/owner
Transfer a Subscription to a different user within the same OneSignal app. Useful for associating existing Subscriptions like push, email, or SMS with a new or updated user identity.

## Overview

Use this API to transfer a Subscription from one user to another within the same OneSignal app.

It is highly recommended to use our web and mobile SDKs to set and update the External ID with the `login` method instead of this API. Your app or website may continue to be setting the wrong External ID. Make sure to only use this API if you are setting the same External ID within your app or website.

This is typically used when:

* You want to reassign an existing push, email, or SMS Subscription to a new or updated user.
* You have changed how you're identifying users (e.g., migrating from anonymous to known users).

<Note>
  - Subscriptions **cannot be transferred across different OneSignal apps**.
  - For email and SMS Subscriptions, you can instead create new ones using [Create User](/reference/create-user).
  - For push Subscriptions, platform limitations may apply—see [Subscriptions](/docs/en/subscriptions#importing-push-subscriptions) for details.
</Note>

***

## How to Use This API

### Required Path Parameter: `subscription_id`

You must know the `subscription_id` of the subscription to be transferred. This is a unique UUID assigned by OneSignal.

### Required Body Parameter: `identity` (object)

This specifies the user the subscription should be moved to. Only **one alias** should be used per request. You can identify the target user using one of:

* `external_id` (recommended)
* `onesignal_id`
* A [custom alias](/docs/en/aliases)

***


# Unsubscribe email with token
Source: https://documentation.onesignal.com/reference/unsubscribe-with-token

POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
Unsubscribe an email address from future messages by calling this API from your custom unsubscribe page. Automatically disables the associated email subscription using a token-based approach.

## Overview

Use this API to unsubscribe an email address directly from your custom unsubscribe landing page. It is ideal when building branded opt-out experiences and enables you to track which email caused the unsubscribe.

When invoked, this endpoint:

* Sets the email Subscription's `enabled` property to `false`
* Prevents further messages from being sent to the email address unless explicitly overridden (see [Overriding unsubscribes](/reference/email#body-include-unsubscribed))
* Email Subscriptions can be re-subscribed using the [Update Subscription](/reference/update-subscription) API

<Tip>
  For instructions on setting up a custom unsubscribe page, see [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page).
</Tip>

***

## How to Use This API

### Step 1: Set Up Your Custom Unsubscribe Page

Follow the guide to [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page). You'll add a custom unsubscribe URL to your email templates using Liquid syntax.

Example URL in your email template:

```liquid theme={null}
https://yourdomain.com/unsubscribe?app_id={{ app_id }}&notification_id={{ notification_id }}&token={{ token }}
```

### Step 2: Extract the Parameters

When a user clicks the unsubscribe link, your custom unsubscribe page should extract the following from the URL:

* `app_id`: OneSignal app ID
* `notification_id`: The ID of the specific email message sent
* `token`: The email token, a secure reference to the subscription

### Step 3: Call the API

When the user confirms they want to unsubscribe (e.g., clicks a button on your unsubscribe page), make a POST request to this endpoint:

```
POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
```

Example Request (JavaScript):

```js theme={null}
fetch("https://api.onesignal.com/apps/your-app-id/notifications/your-notification-id/unsubscribe?token=abc123xyz", {
  method: "POST"
});
```

<Info>
  No request body or authentication is required. The token acts as a secure identifier.
</Info>

<Note>
  * This API only works for email subscriptions.
  * It should only be used from a server or frontend context that you control (e.g., your custom unsubscribe page).
  * Once unsubscribed, the email address will not receive future emails from your app unless resubscribed.
</Note>

***


# Update an app
Source: https://documentation.onesignal.com/reference/update-an-app

PUT /apps/{app_id}
Use to update the name or push platform configuration of an existing app. This guide explains required parameters and platform-specific update rules

## Overview

Use this API to programmatically update an existing OneSignal app. This is useful when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

***

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Warning>
  If you change your FCM Service Account JSON file to a different Firebase project, your Android Subscriptions tied to the current project will become invalid. They will not be able to receive push notifications until they open your app again with this new FCM Service Account JSON file.
</Warning>

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need help Base64 encoding your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns). **You will likely never need to update these parameters if set correctly during app creation**:

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates). **These must be updated every year which is why we recommend using p8 authentication**:

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Update API key
Source: https://documentation.onesignal.com/reference/update-api-key

PATCH /apps/{app_id}/auth/tokens/{token_id}
Update a Rich Authentication Token (App API Key) for a OneSignal app. Modify the token's name or IP allowlist settings using your Organization API Key.

## Overview

Use this API to update the properties of a specific **Rich Authentication Token** (App API Key) for a OneSignal app. You can change the name, IP allowlist mode, or the list of allowed IPs. This is helpful for adjusting access rules without needing to recreate the key.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Update Live Activity
Source: https://documentation.onesignal.com/reference/update-live-activity-api

POST /apps/{app_id}/live_activities/{activity_id}/notifications
Update or terminate running iOS Live Activities using OneSignal’s Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

## Overview

Update or terminate running iOS Live Activities using our REST API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

Before using this API, ensure your app is properly configured by following the [Live Activities developer setup](/docs/en/live-activities-developer-setup).

## How to Use this API

1. Select the Live Activity to update by specifying its `activity_id` in the URL. This is set when using the:

* [Start Live Activity API](/reference/start-live-activity)
* [Triggering it in-app](/docs/en/live-activities-developer-setup).
* [`LiveActivities.enter` SDK method](/docs/en/mobile-sdk-reference#enter)

2. Update the state of the Live Activity by setting the `event_updates` parameter to a JSON object that matches the structure of the `ActivityAttributes.ContentState` struct defined in your Live Activity widget extension.

3. When ready to terminate the Live Activity:

* Set the `event` parameter to `end`
* Include a `dismissal_date` if you want the Live Activity to be dismissed in less than 4 hours.
* Set the `dismissal_date` to a time in the past to dismiss the Live Activity immediately. User must have clicked "Allow" for the Live Activity to be removed programmatically.

<Warning>
  Once a Live Activity `activity_id` is ended, you cannot update it. This includes changing the `dismissal_date` or `event` parameter.

  If the Live Activity is not being dismissed immediately, it is either because:

  * The `activity_id` has already been ended.
  * The user has not clicked "Allow" for the Live Activity to be removed programmatically.
</Warning>

***


# Update segment
Source: https://documentation.onesignal.com/reference/update-segment

PATCH /apps/{app_id}/segments/{segment_id}
Update an existing segment's name and/or filters. The name parameter is always required. When filters are provided, all existing filters are replaced with the new ones.

## Overview

Update an existing segment's name and/or filters. This API allows you to modify [Segments](/docs/en/segmentation) programmatically without having to delete and recreate them.

<Note>
  The `name` parameter is always required, even if you're not changing it. When filters are provided, all existing filters are **replaced** with the new ones. Omit the `filters` parameter to keep existing filters intact. The `filters` array cannot be empty—if provided, it must contain at least one filter.
</Note>

***

## How to use this API

### Update segment name only

To update just the segment name without changing filters:

```json theme={null}
{
  "name": "New Segment Name"
}
```

### Update segment description

Update the optional `description` (max 255 characters). Pass an empty string to clear the existing description; omit the field to leave it unchanged.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION"
}
```

### Update segment filters

To update the segment filters (this replaces all existing filters), provide the `name` (required) and `filters`:

```json theme={null}
{
  "name": "Updated Segment",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "5"},
    {"operator": "AND"},
    {"field": "tag", "key": "subscription", "relation": "=", "value": "premium"}
  ]
}
```

### Filter syntax

The filter syntax is identical to the [Create segment](/reference/create-segments) API. Available filters include:

* `tag` - Filter by Tags
* `last_session` - Filter by last active time
* `first_session` - Filter by first session time
* `session_count` - Filter by number of sessions
* `session_time` - Filter by total usage duration
* `language` - Filter by user language
* `app_version` - Filter by app version
* `location` - Filter by GPS coordinates
* `country` - Filter by country

Use `AND` and `OR` operators to combine filters:

```json theme={null}
{
  "name": "Engaged Premium Users",
  "filters": [
    {"field": "tag", "key": "plan", "relation": "=", "value": "premium"},
    {"operator": "AND"},
    {"field": "session_count", "relation": ">", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "vip", "relation": "=", "value": "true"}
  ]
}
```

***

## Response

### Success response

```json theme={null}
{
  "success": true,
  "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19"
}
```

### Error responses

| Status Code | Description                                                                              |
| ----------- | ---------------------------------------------------------------------------------------- |
| 400         | Bad request - Invalid filters, duplicate segment name, or segment used by active Journey |
| 403         | Forbidden - API not available for your plan                                              |
| 404         | Not found - Segment does not exist                                                       |
| 429         | Rate limit exceeded                                                                      |

***


# Update Subscription by ID
Source: https://documentation.onesignal.com/reference/update-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}
Update properties on an existing OneSignal subscription using its subscription_id. Commonly used to enable or disable a subscription when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties by `subscription_id`.

This endpoint is primarily used by the OneSignal SDK to manage subscription state.

Most external use cases are better served by the [Update Subscription by token](/reference/update-subscription-by-token) API, which can use the Email Address or Phone Number as the `token` or the [Update User](/reference/update-user) API, which allows for updating user-level data.

<Note>
  For **email opt-outs**, it's recommended to use the [Unsubscribe Email (with token)](/reference/unsubscribe-with-token) API instead. This avoids the need to store or manage the `subscription_id`.
</Note>

***

## How to use this API

**Required:** `subscription_id`

To update a subscription, you **must know the `subscription_id`**. This is a UUID generated by OneSignal and is immutable.

* You can retrieve a subscription ID by querying the [User object](/docs/en/users).
* See the [Subscriptions](/docs/en/subscriptions) guide for an explanation of how subscription IDs are generated and used.

<Note>
  You **cannot** update the `type` of a Subscription. If the `type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the Subscription with the correct type.
</Note>

***


# Update Subscription by token
Source: https://documentation.onesignal.com/reference/update-subscription-by-token

PATCH /apps/{app_id}/subscriptions_by_token/{token_type}/{token}
Update properties on an existing Subscription using its token. Commonly used to enable or disable subscription status when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties.

This API can be useful if:

* You only know the `token` and `token_type` and want to update metadata or status flags directly.
* You are managing Subscription status outside of the OneSignal SDK. Like with a [custom preference page or unsubscribe page](/docs/en/create-custom-unsubscribe-page).

***

## How to use this API

To update a Subscription, you must know the `token_type` and the `token`.

The `token_type` is the [Subscription's type](/docs/en/server-sdk-reference#subscription-types) (e.g., `Email`, `SMS`, `iOSPush`, `AndroidPush`, etc.).

The `token` is the push token, email address, or phone number associated with the Subscription.

Ensure the `token` is valid and correctly formatted for the chosen `token_type`.

* **Email format:** Should be a valid email address that you confirmed can receive emails.
* **SMS format:** Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164).
* **iOSPush APNS token format:** 64 characters, hexadecimal characters only (0-9,a-f).
* **AndroidPush FCM token format:** Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.

<Warning>
  You **cannot** update the `token_type` and `token` of a Subscription with this API. If the `token_type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the subscription with the correct type.

  If multiple Subscriptions are found for the `token` and `token_type`, an `Http 400` error is returned with a list of subscription IDs that match the criteria.
</Warning>

***


# Update template
Source: https://documentation.onesignal.com/reference/update-template

PATCH /templates/{template_id}?app_id={app_id}
Update existing OneSignal message templates for push, email, or SMS. Changes apply immediately across dashboard and API usage via the `template_id` reference.

## Overview

This endpoint allows you to update an existing push, email, or SMS template in your OneSignal app. Once updated, the changes are applied immediately and reflected across both the Dashboard and API when using the associated `template_id`.

Templates are updated using the same structure as when [creating templates](/reference/create-template).

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

To update a template, you must supply:

* Your **OneSignal App ID** found in [Keys & IDs](/docs/en/keys-and-ids).
* The **Template ID**

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***

## Channel-Specific Requirements

### Push Templates

* The `contents` property must use the `en` (English) key along with other languages you want to support.
* All [Push Notification Properties](/reference/push-notification) are valid.
* All platforms are enabled by default. To limit, explicitly enable desired ones (e.g., `isAndroid: true` disables iOS and Web).

### Email Templates

* Set `isEmail: true`
* Include `email_subject` and `email_body`
* All [Email Channel Properties](/reference/email) are supported.

### SMS Templates

* Set `isSMS: true`
* All [SMS Channel Properties](/reference/sms) are supported.

***


# Update user
Source: https://documentation.onesignal.com/reference/update-user

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}
Modify a user's properties.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint updates user-level properties for an existing user in your OneSignal app.

* To change a user's `identity` like `external_id` or custom [Aliases](/docs/en/aliases), use the [Create alias](/reference/create-alias) and [Delete alias](/reference/delete-alias) APIs.
* To manage a user's `subscriptions`, use the [Create Subscription by alias](/reference/create-subscription) or [Create user](/reference/create-user) APIs.

***

## How to use this API

You must supply an alias in the request path:

* `alias_label`: The type of identifier (e.g., `external_id`, `onesignal_id`, or a custom alias label).
* `alias_id`: The corresponding value for that label.

See [Users](/docs/en/users) and [Aliases](/docs/en/aliases) for more info.

***


# View an app
Source: https://documentation.onesignal.com/reference/view-an-app

GET /apps/{app_id}
View the details of a single OneSignal app

## Overview

Use this API to retrieve metadata and platform configuration for a single OneSignal app associated with your account. This includes app names, App ID, Subscription counts, timestamps, and push platform credentials (Android/FCM, iOS/APNS, Web Push, Safari), making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

***

## How to use this API

To retrieve your app, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View API keys
Source: https://documentation.onesignal.com/reference/view-api-keys

GET /apps/{app_id}/auth/tokens
View the details of all of your current app API keys (Rich Authentication Token) for a single OneSignal app.

## Overview

This API is helpful for auditing and managing the API keys (Rich Authentication Tokens) associated with an app. It returns metadata for each token, including:

* Token name and ID
* IP allow list mode and associated CIDR ranges (if any)
* Creation and last updated timestamps

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

***


# View apps
Source: https://documentation.onesignal.com/reference/view-apps

GET /apps
Retrieve a list of all OneSignal apps associated with your account, including key app details like name, App ID, subscription counts, and timestamps. Useful for managing multiple apps through the OneSignal API.

## Overview

Use this API to retrieve metadata for all OneSignal apps associated with your account. This includes app names, App IDs, subscription counts, and timestamps, making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

<Warning>
  This API is limited to return a maximum of 1000 Apps. If you need access to more, then you should store the `app_id` and `name` for each of your apps on your own server to look up with the [View an app](/reference/view-an-app) API to get data for each app separately. Also, if you need to delete apps, then you can provide the `app_id` and `name` to OneSignal Support and ask for these to be deleted.
</Warning>

***

## How to use this API

To retrieve your apps, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View message
Source: https://documentation.onesignal.com/reference/view-message

GET /notifications/{message_id}?app_id={app_id}
View the details of a single message and the Outcomes associated with it.

## Overview

The View message API allows you to fetch data from a single push, email, or SMS message at a time. If you want to get multiple messages at a time, use the [View messages](/reference/view-messages) API. In most cases, you will likely want to use [Event Streams](/docs/en/event-streams) instead.

Currently this API does not provide Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are only **accessible 30 days after creation**; however, messages sent using the OneSignal dashboard are accessible for the app's lifetime.

See our [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and (after giving your users some time to interact with the message) pull the data if desired.

For example, if you send a message targeting the `include_aliases` parameter, the response will include the aliases you set. If you send with the `included_segments` parameter, then the response will only provide the segments you set. When targeting segments or filters, you can use the [Export audience activity CSV](/reference/export-csv-of-events) API to get the user event data.

To view outcome data for the message, you must include the `outcome_name` parameter with the name of the outcome you want to fetch, along with the accompanying aggregation type (.count or .sum), for example: `os__click.count`. For more information on outcome definitions, see [View Outcomes](/reference/view-outcomes).

***


# View messages
Source: https://documentation.onesignal.com/reference/view-messages

GET /notifications?app_id={app_id}&limit={limit}&offset={offset}&kind={kind}&template_id={template_id}&time_offset={time_offset}
View the details for a collection of messages.

## Overview

The View messages API fetches data for up to 50 push, email, or SMS messages at a time. To fetch a single message, use the [View message](/reference/view-message) API. In most cases, use [Event Streams](/docs/en/event-streams) instead.

This API does not return Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are **retained for 30 days** after creation; messages sent through the OneSignal dashboard are retained for the app's lifetime.

See [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

Use time-offset pagination for sequential pulls of all messages, and standard pagination for ad-hoc queries. For ETL or bulk export pipelines, use [Event Streams](/docs/en/event-streams) instead.

Filter results to a specific message kind or template using the `kind` and `template_id` query parameters. Both filters work with either pagination style.

### Optimized pagination with time offset

To efficiently retrieve all available messages for an app, use `time_offset`-based pagination. When `time_offset` is specified, the sort order changes from descending to ascending — the oldest messages appear first based on the [`send_after` date](/reference/create-message#send-after).

#### Accepted `time_offset` values

* ISO 8601 formatted timestamp — for example, `2025-01-01T00:00:00.000Z` (January 1, 2025, at 00:00 UTC).
* Opaque cursor token (Base64-encoded) — provided in the API response as `next_time_offset`.

<Steps>
  <Step title="Initial fetch">
    To fetch messages from a specific date onward, set `time_offset` to an ISO 8601 formatted timestamp. For example, to retrieve messages sent since January 1, 2025: `time_offset=2025-01-01T00:00:00.000Z`.

    <Note>
      * `time_offset` cannot be used with the standard `offset` parameter.
      * `time_offset` excludes messages that match the exact timestamp to avoid duplicates.
      * The response includes `next_time_offset`, a cursor token for the next page. No decoding required. For example: `"next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="`
    </Note>
  </Step>

  <Step title="Fetch additional pages">
    Use `next_time_offset` from the previous response as the `time_offset` value in the next request. For example: `time_offset=MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw==`.
  </Step>

  <Step title="Continue until completion">
    Repeat the request until an empty `notifications` array is returned, indicating all messages have been fetched.
  </Step>

  <Step title="Handling new messages">
    Because results are sorted ascending, new messages are added to the end. To resume fetching from where you left off, reuse the last `next_time_offset` that returned an empty response.
  </Step>
</Steps>

### Standard pagination

Use the `limit` and `offset` parameters to page through notifications for an app. The maximum result size is 50, and the default `limit` is `50`. Use `limit` to specify the result size and `offset` to increment by the limit value with each request.

For example, the first request uses `offset=0`, the second `offset=50`, the third `offset=100`, and so on.

Standard pagination is convenient for ad-hoc queries but degrades as the `offset` value grows. For sequential pulls of all messages, use time-offset pagination.

***


# View segment
Source: https://documentation.onesignal.com/reference/view-segment

GET /apps/{app_id}/segments/{segment_id}
Retrieve details for a single segment by its ID, including subscriber count and optionally segment metadata and filters.

## Overview

Retrieve details for a single segment by its ID. By default, this endpoint returns only the subscriber count. Use the optional `include-segment-detail` parameter to also retrieve segment metadata and filters.

<Note>
  The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard.
</Note>

<Warning>
  **User-based segments not supported**: Segments containing message event or custom event filters (user-based segments) are not yet supported via this API. Attempting to fetch these segments will return a 400 error. These segments can only be managed through the dashboard UI.
</Warning>

***

## How to use this API

### Basic usage

By default, this endpoint returns only the subscriber count for the segment:

```json theme={null}
{
  "subscriber_count": 12345
}
```

### Include segment details

To retrieve full segment details including metadata and filters, set `include-segment-detail=true`:

```
GET /apps/{app_id}/segments/{segment_id}?include-segment-detail=true
```

This returns the subscriber count along with a `payload` object containing segment details:

<CodeGroup>
  ```json Simple filter theme={null}
  {
    "subscriber_count": 12345,
    "payload": {
      "id": "4414c404-56a3-11ed-9b6a-0242ac120002",
      "name": "Subscribed Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {
          "field": "session_count",
          "relation": ">",
          "value": "5"
        }
      ]
    }
  }
  ```

  ```json With AND/OR operators theme={null}
  {
    "subscriber_count": 5678,
    "payload": {
      "id": "5525d515-67b4-22fe-0c7b-1353bd231113",
      "name": "Engaged Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {"field": "session_count", "relation": ">", "value": "2"},
        {"operator": "AND"},
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "last_session", "relation": "<", "hours_ago": "24"}
      ]
    }
  }
  ```
</CodeGroup>

### Filters format

The `filters` array uses the **same format** as the [Create segment](/reference/create-segments) API. This means you can:

* Read filters from this endpoint
* Modify them as needed
* Use them directly with the [Update segment](/reference/update-segment) or [Create segment](/reference/create-segments) APIs

The array contains filter objects and operator objects:

**Filter object** - defines a condition:

| Field                   | Type    | Description                                                                                                                                         |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field`                 | string  | The filter type: `tag`, `last_session`, `first_session`, `session_count`, `session_time`, `language`, `app_version`, `location`, `country`, `email` |
| `relation`              | string  | The comparison operator: `>`, `<`, `=`, `!=`, `exists`, `not_exists`, `in_array`, `not_in_array`, `time_elapsed_gt`, `time_elapsed_lt`              |
| `value`                 | string  | The filter value (for most filter types)                                                                                                            |
| `key`                   | string  | The filter key (required for `tag` filters)                                                                                                         |
| `hours_ago`             | string  | Hours ago value (for `last_session`/`first_session` filters)                                                                                        |
| `radius`, `lat`, `long` | string  | Location parameters (for `location` filters)                                                                                                        |
| `unsupported_in_api`    | boolean | If `true`, this filter cannot be used with Create/Update segment APIs (see note below)                                                              |

**Operator object** - combines filters:

| Field      | Type   | Description                                                                        |
| ---------- | ------ | ---------------------------------------------------------------------------------- |
| `operator` | string | Either `AND` or `OR`. Filters connected with `AND` have higher priority than `OR`. |

<Warning>
  Some segments created via the dashboard UI may contain filter types not supported by the public API (e.g., `message_event`, `custom_event`). These filters will include `unsupported_in_api: true`. You cannot use these filters when creating or updating segments via the API.
</Warning>

### Payload fields

| Field         | Type           | Description                                                                         |
| ------------- | -------------- | ----------------------------------------------------------------------------------- |
| `id`          | string         | The unique identifier for the segment (UUID v4).                                    |
| `name`        | string         | The segment name (max 128 characters).                                              |
| `description` | string \| null | Human-readable description for the segment (max 255 characters). `null` when unset. |
| `created_at`  | integer        | Unix timestamp when the segment was created.                                        |
| `source`      | string         | The source of the segment: `default`, `custom`, or `quickstart`.                    |
| `filters`     | array          | Array of filter and operator objects that define the segment criteria.              |

***


# View segments
Source: https://documentation.onesignal.com/reference/view-segments

GET /apps/{app_id}/segments
Retrieve a list of segments associated with a specific OneSignal app. Useful for programmatically accessing segment metadata such as name, creation date, and status.

## Overview

Retrieve a list of segments associated with a specific OneSignal app. This is helpful when you want to access segment metadata programmatically instead of using the OneSignal Dashboard UI.

<Warning>
  This endpoint only retrieves existing segment metadata. It does not provide the segment filters or user data.
</Warning>

***


# View template
Source: https://documentation.onesignal.com/reference/view-template

GET /templates/{template_id}?app_id={app_id}
Retrieve the details of a specific message template in your OneSignal app using its template ID. This API returns the template content, target channel, and timestamps for creation and last update.

## Overview

This endpoint returns metadata and content for a single template, including:

* Template body/content
* Target delivery channel (e.g., push, email, SMS)
* Creation and last updated timestamps

This is useful for inspecting existing templates before using or updating them.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Required parameters:

* `app_id` (query param): Your OneSignal App ID.
* `template_id` (path param): The unique ID of the template.

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# View templates
Source: https://documentation.onesignal.com/reference/view-templates

GET /templates?app_id={app_id}&limit={limit}&offset={offset}
Retrieve a paginated list of message templates from your OneSignal app. This endpoint returns summary information for each template, including ID, name, creation, and update timestamps.

## Overview

Use this endpoint to retrieve a list of message templates associated with a specific OneSignal app. The response provides summary information only:

* `template_id`
* `name`
* `created_at`
* `updated_at`

<Note>
  This endpoint does **not** return full template content such as message bodies, channel properties, or delivery configuration. For detailed template data, use the [View Template](/reference/view-template) endpoint.
</Note>

***

## How to Use This API

### Required Parameters

* **`app_id`** (query param): The OneSignal App ID whose templates you want to retrieve.

### Optional Parameters

* **`limit`** (query param): Number of templates to return (default: `50`, maximum: `50`).
* **`offset`** (query param): Number of templates to skip. Use for pagination.

### Pagination Example

If your app has 125 templates and you're using the default limit of 50:

1. First request (first 50 templates):\
   `GET /templates?app_id={app_id}&offset=0`

2. Second request (next 50 templates):\
   `GET /templates?app_id={app_id}&offset=50`

3. Third request (final 25 templates):\
   `GET /templates?app_id={app_id}&offset=100`

Repeat the request while adjusting the `offset` until you've retrieved all templates.

***


# View user
Source: https://documentation.onesignal.com/reference/view-user

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}
Retrieve a user including aliases, properties, and subscriptions.

## Overview

* Use this API to retrieve a user's full profile, including identity aliases, user properties, and messaging subscription details across channels.
* This is helpful for verifying user data, debugging subscription issues, or syncing OneSignal user data with your internal systems.

For detailed concepts and guides, see [Users](/docs/en/users), [Subscriptions](/docs/en/subscriptions), and [Aliases](/docs/en/aliases) documentation.

## How to use this API

To look up a user, you must provide both an `alias_label` and an `alias_id`. In most cases, your `external_id` will serve as the `alias_label`, and its value will be passed as the `alias_id`. While you may use a custom alias, we strongly recommend setting and using the `external_id` as your primary user identifier for consistency across platforms.

To retrieve a user using their OneSignal ID, set the `alias_label` to `onesignal_id`. **Note**: When querying with any alias other than `onesignal_id`, authentication is required.

***


# Add a player
Source: https://documentation.onesignal.com/reference/add-a-device

POST `https://onesignal.com/api/v1/players`

Register a new Subscription (aka player) to one of your OneSignal apps.

<Warning>
  This is a Legacy API. Use [Create User](/reference/create-user) or [Create Subscription](/reference/create-subscription) instead.
</Warning>

***

## Headers

| Header          | Value                     | Required | Description                      |
| --------------- | ------------------------- | -------- | -------------------------------- |
| `Content-Type`  | `application/json`        | Yes      | The content type of the request. |
| `Authorization` | `Basic YOUR_REST_API_KEY` | Yes      | Your OneSignal REST API key.     |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                                |
| -------------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                                     |
| `device_type`        | integer | Yes      | Device platform: 0 = iOS, 1 = Android, 2 = Amazon, 3 = Windows Phone, etc. |
| `identifier`         | string  | No       | Push token, email address, or phone number.                                |
| `language`           | string  | No       | Language code (e.g. "en").                                                 |
| `timezone`           | integer | No       | Time zone offset in seconds.                                               |
| `game_version`       | string  | No       | Version of your app.                                                       |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                                         |
| `device_os`          | string  | No       | Operating system version (e.g., "13.3").                                   |
| `ad_id`              | string  | No       | Advertising ID.                                                            |
| `sdk`                | string  | No       | OneSignal SDK version (e.g., "050201" for 5.2.1).                          |
| `session_count`      | integer | No       | Number of times the user has used the app.                                 |
| `tags`               | object  | No       | Custom tags as key-value pairs.                                            |
| `external_user_id`   | string  | No       | Your system's user ID for this device.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc.                 |

***

## Example Request

```json theme={null}
POST /api/v1/players HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "device_type": 1,
  "identifier": "abcdef123456",
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_model": "Pixel 4",
  "device_os": "12",
  "ad_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sdk": "050401",
  "session_count": 5,
  "tags": {
    "user_type": "free",
    "level": "10"
  },
  "external_user_id": "user123",
  "notification_types": 1
}
```

***

## Response

```json theme={null}
{
  "id": "Subscription_id_string"
}
```

## Errors

* 400 Bad Request – Invalid parameters or missing required fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Not allowed for your account type or plan.


# Export subscriptions CSV
Source: https://documentation.onesignal.com/reference/csv-export

POST /players/csv_export
Generate a GZip-compressed CSV export of your current subscription data using this API endpoint.

## Overview

Use this endpoint to request a GZip-compressed CSV export of all your [Subscriptions data](/docs/en/subscriptions) from OneSignal. The export includes both default and optional user data fields, and supports filters to refine the dataset. The file is downloadable via a URL returned in the API response.

***

## How to use this API

By default, this will export all Subscriptions within the app.

**Optional filters:**

You can narrow the export using:

* `segment_name`: Only export Subscriptions from a specific segment. Segment membership rules determine which subscription statuses are included. Use with `include_unsubscribed` to include unsubscribed subscriptions.
* `last_active_since`: Export Subscriptions where their `last_session` was after a specific Unix timestamp. Example: Use `1704067200` for Subscriptions active since January 1st, 2024.
* `include_unsubscribed`: When exporting a segment, set to `true` to include unsubscribed subscriptions alongside subscribed ones. By default, segment-filtered exports only return subscribed subscriptions. This parameter has no effect when `segment_name` is not provided.

**Example successful response:**

```json 200 OK theme={null}
{
  "csv_file_url": "https://onesignal.com/csv_exports/b2f7f966.../users_1849..._2024-11-10.csv.gz"
}
```

**Export time considerations:**

* Generation speed: \~2,000 records per second.
* File readiness: The `csv_file_url` may return a 404 until generation completes.
* Download retry: Poll the file URL at intervals until the file is ready.
* File expiration: The file remains available for 3 days after generation.
* Concurrency: Only one export per OneSignal account can run at a time.

**File not ready (404 response)**

```xml 404 CSV GET  theme={null}
This XML file does not appear to have any style information
associated with it. The document tree is shown below.
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

<Info>
  You can safely poll the `csv_file_url` until the file becomes available. Implement retry logic based on expected data volume and generation speed.

  Only one export is allowed at a time per account. Wait until the `.csv.gz` file is downloaded before triggering another export.
</Info>

***

## CSV data contents

The export includes two types of fields:

* **Default fields**: Always included unless excluded by schema changes.
* **Extra fields**: Must be explicitly requested using the `extra_fields` parameter.

### Default fields

* `id`: The Subscription ID.

* `identifier`: The push token, email address, or phone number depending on the Subscription type.

* `session_count`: The number of times the user has opened the app.

* `language`: The user's language in ISO 639-1 format.

* `timezone`: Deprecated — use `timezone_id` instead.

* `game_version`: The version of your app that the user is currently using.

* `device_os`: The device's operating system version.

* `device_type`: Integer representing channel/device type.
  * `0`: iOSPush
  * `1`: AndroidPush
  * `2`: FireOSPush
  * `5`: ChromePush
  * `7,17`: SafariPush
  * `11`: Email
  * `14`: SMS

* `device_model`: The device's hardware string.

* `ad_id`: Deprecated.

* `tags`: Custom key/value data.

* `last_active`: The last time the user was active.

* `playtime`: The total amount of time in seconds the user had the mobile app open.

* `created_at`: The first time the user was seen.

* `invalid_identifier`: Boolean flag for unsubscribed state.
  * `t`: Unsubscribed
  * `f`: Subscribed

### Extra fields (`extra_fields`)

Pass `extra_fields` in your request to include any of the following:

* `external_user_id`: Maps to the `external_id` of the user.

* `onesignal_id`: OneSignal's user ID.

* `location`: Adds the `lat` and `long` coordinates if set.

* `country`: The user's country in ISO 3166-1 Alpha 2 format.

* `ip`: The IP address if detected. Can be IPv4 or IPv6 format.

* `web_auth`: Only available to OneSignal SDKs. The `web_auth` key for web push.

* `web_p256`: Only available to OneSignal SDKs. The `web_p256` for web push.

* `unsubscribed_at`: The date and time the user last unsubscribed. They may resubscribe at any time. Check the `invalid_identifier` field to determine if they are currently subscribed.

* `notification_types`: Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/en/subscriptions#notification-types).

* `timezone_id`: The user's timezone in IANA format.

***


# Delete player record
Source: https://documentation.onesignal.com/reference/delete-user-record

delete https://onesignal.com/api/v1/players/{player_id}?app_id={app_id}

Delete a player (aka Subscription).

<Warning>
  This is a Legacy API. Use [Delete User](/reference/delete-user) or [Delete Subscription](/reference/delete-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `app_id`    | string | Yes      | Your OneSignal App ID.         |
| `player_id` | string | Yes      | The Subscription ID to delete. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Example Request

```http theme={null}
DELETE /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json
```

***

## Example Response

```json theme={null}
{
  "success": true
}
```

The Subscription will be deleted from the OneSignal database.

***


# Edit player
Source: https://documentation.onesignal.com/reference/edit-device

put https://onesignal.com/api/v1/players/{player_id}

Update a player's (Subscription's) information using the Subscription ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `player_id` | string | Yes      | The OneSignal Subscription ID. |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request.    |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                |
| -------------------- | ------- | -------- | ---------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                     |
| `identifier`         | string  | No       | Push token, email, or phone number.                        |
| `language`           | string  | No       | Language code (e.g., "en").                                |
| `timezone`           | integer | No       | Time zone offset in seconds.                               |
| `game_version`       | string  | No       | App version.                                               |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                         |
| `device_os`          | string  | No       | OS version (e.g., "14.5").                                 |
| `ad_id`              | string  | No       | Advertising ID.                                            |
| `sdk`                | string  | No       | OneSignal SDK version.                                     |
| `tags`               | object  | No       | Custom key-value pairs.                                    |
| `external_user_id`   | string  | No       | Your internal user ID.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc. |
| `email_auth_hash`    | string  | No       | Required to update email identifiers securely.             |
| `sms_auth_hash`      | string  | No       | Required to update SMS identifiers securely.               |

> Only include fields you want to change. Fields left out will not be modified.

***

## Example Request

```json theme={null}
PUT /api/v1/players/player_id_string HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "external_user_id": "user123",
  "tags": {
    "level": "20",
    "subscription": "active"
  },
  "language": "fr",
  "timezone": 3600,
  "device_os": "16.0"
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Missing or invalid fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied.
* 404 Not Found – Device with player\_id not found.

***


# Edit tags with external user id
Source: https://documentation.onesignal.com/reference/edit-tags-with-external-user-id

put https://onesignal.com/api/v1/apps/{app_id}/users/{external_user_id}

Update a player's (Subscription's) information using the External ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter          | Type   | Required | Description             |
| ------------------ | ------ | -------- | ----------------------- |
| `app_id`           | string | Yes      | Your OneSignal App ID.  |
| `external_user_id` | string | Yes      | The user's External ID. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Request Body Parameters

| Field  | Type   | Required | Description                       |
| ------ | ------ | -------- | --------------------------------- |
| `tags` | object | Yes      | Key-value pairs to set or update. |

* To **delete a tag**, set its value to an empty string (`""`).
* Existing tags with the same keys will be **overwritten**.

***

## Example Request

```http theme={null}
PATCH /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json

{
  "tags": {
    "plan": "premium",
    "logged_in": "true",
    "referral": ""
  }
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Invalid request or payload.
* 401 Unauthorized – Invalid or missing keys.
* 403 Forbidden – Access denied due to insufficient permissions.
* 404 Not Found – No players found for given `external_user_id`.

***


# Export audience activity CSV
Source: https://documentation.onesignal.com/reference/export-csv-of-events

POST /notifications/{message_id}/export_events
Export a compressed CSV report of audience-level delivery and engagement data for a specific message. This includes sent, delivered, clicked, failed, and unsubscribed events across Push, Email, and SMS channels.

## Overview

Get a CSV of per-recipient audience activity events (sends, clicks, failures, etc.) for a push, email, or SMS message. This endpoint mirrors the **Export** button in the dashboard's Audience Activity section on each message report:

* [Push message reports](/docs/en/push-notification-message-reports)
* [Email message reports](/docs/en/email-message-reports)
* [SMS message reports](/docs/en/sms-message-reports)

The CSV schema varies by channel. See each channel's message reports page for column definitions.

***

## How to use this API

Get the message `id` from the [Sending messages API](/reference/create-message) or the [View messages API](/reference/view-messages).

A successful request returns `200 OK` with a `csv_file_url`:

```json 200 OK theme={null}
{
    "csv_file_url": "https://onesignal-data.onesignal.com/csv_exports/YOUR_APP_ID/events_audience-activity-YOUR_MESSAGE_ID-push-YYYY-MM-DDTHH-MM-SSTZ.csv.gz"
}
```

The generated file name follows the pattern `events_audience-activity-{message_id}-{channel}-{timestamp}.csv.gz`.

The file is generated at \~2,000 records per second. For large audiences, generation can take several minutes, and the URL may return `404` until the file is ready:

```xml 404 Not Found theme={null}
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

Poll the `csv_file_url` with GET and implement retries with exponential backoff. When the file is ready, the GET request downloads the `.csv.gz` file.

<Info>
  * The CSV download URL is valid for **3 days** after creation.
  * File names include a random UUID to prevent guessing.
</Info>

<Warning>
  Only **one concurrent export** is allowed per OneSignal account. Download the `.csv.gz` file before starting another export, or the new request fails.
</Warning>

***


# Rotate API key
Source: https://documentation.onesignal.com/reference/rotate-api-key

POST /apps/{app_id}/auth/tokens/{token_id}/rotate
Rotate an existing App API Key (Rich Authentication Token) for a OneSignal app. Useful when a token is compromised or needs replacement without creating a new key from scratch.

## Overview

Use this API to rotate a **Rich Authentication Token** (App API Key) for a specific OneSignal app. Rotating a key revokes the current token and generates a new one under the same configuration—ideal when a token is lost or compromised but you don’t want to recreate and reconfigure it from scratch.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can rotate an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# View player
Source: https://documentation.onesignal.com/reference/view-device

GET https://onesignal.com/api/v1/players/{player_id}

Retrieve a single player record (Subscription) data registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `player_id` | string | Yes      | The OneSignal ID of the device. |

***

## Query Parameters

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `app_id`  | string | Yes      | Your OneSignal App ID. |

***

## Headers

| Header          | Value                            | Required | Description                        |
| --------------- | -------------------------------- | -------- | ---------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal LegacyREST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players/player_id_string?app_id=your_app_id HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json{ theme={null}
  "id": "player_id_string",
  "identifier": "push_token_or_email",
  "session_count": 5,
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_os": "14.4",
  "device_type": 1,
  "tags": {
    "level": "10",
    "user_type": "free"
  },
  "last_active": 1625253300,
  "created_at": 1625249800,
  "invalid_identifier": false,
  "external_user_id": "user123"
}
```

### Response Fields

| Field                | Type      | Description                                             |
| -------------------- | --------- | ------------------------------------------------------- |
| `id`                 | string    | OneSignal player ID.                                    |
| `identifier`         | string    | Push token, email, or phone number.                     |
| `session_count`      | integer   | Number of sessions associated with this device.         |
| `language`           | string    | Language set on the device (e.g., "en").                |
| `timezone`           | integer   | Time zone offset in seconds.                            |
| `game_version`       | string    | Version of your app the device is running.              |
| `device_os`          | string    | Operating system version.                               |
| `device_type`        | integer   | Numeric code for platform (0 = iOS, 1 = Android, etc.). |
| `tags`               | object    | Custom tags set on the device.                          |
| `last_active`        | timestamp | Last time the user was active (Unix timestamp).         |
| `created_at`         | timestamp | When the device record was created.                     |
| `invalid_identifier` | boolean   | Whether the push token or identifier is invalid.        |
| `external_user_id`   | string    | Your internal user ID mapped to this device.            |

***

## Errors

* 400 Bad Request – Missing or invalid parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied for this app or resource.
* 404 Not Found – The specified player\_id does not exist.

***


# View players
Source: https://documentation.onesignal.com/reference/view-devices

GET `https://onesignal.com/api/v1/players?app_id={app_id}&limit={limit}&offset={offset}`

Retrieve up to 80,000 player records (Subscriptions) registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Query Parameters

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `app_id`  | string | Yes      | Your OneSignal App ID.                                 |
| `limit`   | int    | No       | Number of entries to return (max 300, default is 300). |
| `offset`  | int    | No       | Result offset for pagination.                          |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players?app_id=your_app_id&limit=100&offset=0 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json theme={null}
{
  "total_count": 6,
  "offset": 0,
  "limit": 300,
  "players": [
    {
      "id": "player_id_1",
      "identifier": "push_token_or_email",
      "session_count": 3,
      "language": "en",
      "timezone": -28800,
      "game_version": "1.0",
      "device_os": "15.0",
      "device_type": 1,
      "tags": {
        "level": "15",
        "user_type": "free"
      },
      "last_active": 1625253300,
      "created_at": 1625249800,
      "invalid_identifier": false,
      "external_user_id": "user123"
    }
  ]
}
```

### Response Fields

| Field                        | Type    | Description                                  |
| ---------------------------- | ------- | -------------------------------------------- |
| `total_count`                | integer | Total number of devices for the app.         |
| `offset`                     | integer | Current pagination offset.                   |
| `limit`                      | integer | Number of devices returned in this response. |
| `players`                    | array   | List of device objects.                      |
| `players[].id`               | string  | Unique OneSignal player ID.                  |
| `players[].identifier`       | string  | Push token, email, or phone number.          |
| `players[].tags`             | object  | Custom tags set on the device.               |
| `players[].external_user_id` | string  | Your internal user ID.                       |

***

## Errors

* 400 Bad Request – Invalid query parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access not allowed for this app or key.

***


# View outcomes
Source: https://documentation.onesignal.com/reference/view-outcomes

GET /apps/{app_id}/outcomes?outcome_names={outcome_names}&outcome_time_range={outcome_time_range}&outcome_platforms={outcome_platforms}&outcome_attribution={outcome_attribution}
View and export push notification outcome metrics such as clicks, conversions, and custom events.

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

## Overview

Use this API to retrieve Outcome metrics associated with your OneSignal app, including push notification interactions and custom-defined events. Outcomes include data points like:

* **Clicks**: Number of users who clicked on a push.
* **Confirmed Deliveries**: Number of confirmed message deliveries.
* **Session Durations**: Number of sessions initiated.
* **Custom Events**: Actions like purchases, form submissions, or any event your app tracks via custom Outcome names.

For details on configuring custom Outcomes, refer to the [Outcomes documentation](/docs/en/custom-outcomes).

<Info>
  Outcomes are stored for approximately 30 days. To retain this data, you should regularly export it before it expires.
</Info>

***

## How to use this API

This API allows you to filter and aggregate Outcome data using several query parameters.

### `outcome_names`

Specify one or more Outcome names with an aggregation type suffix (`.count` or `.sum`).

**Default Outcome names:**

* `os__click.count` – Push notification clicks.
* `os__confirmed_delivery.count` – Confirmed deliveries.
* `os__session_duration.count` – Total sessions.

**Custom Outcome names:**

* You can track any custom event name (e.g. `Purchase`, `Signup`).
* If the custom name contains a comma, include only one name per request to avoid parsing issues.
* Example: `outcome_names=os__click.count,Purchase.count`

### `outcome_time_range`

The time range values can be one of the following:

* `1h` = (default) the last 1 hour data.
* `1d` = the last 1 day data.
* `1mo` = the last 1 month data.

### `outcome_platforms`

Maps to the subscription type property. Default is data from all platforms enabled for your OneSignal App.

| `device_type` | `type`      |
| ------------- | ----------- |
| 0             | iOSPush     |
| 1             | AndroidPush |
| 2             | FireOSPush  |
| 5             | ChromePush  |
| 8             | FirefoxPush |
| 11            | Email       |
| 14            | SMS         |
| 17            | SafariPush  |

Example: `outcome_platform=0` for iOS `outcome_platform=17,8` for Safari and Firefox.

### `outcome_attribution`

The way in which the Outcome occurred:

* `direct` = the Outcome occurred when the user interacted with the message. Some Outcomes only have `direct` attribution like `os__click` and `os__confirmed_delivery` because they only occur as the direct result of the message.
* `influenced` = the Outcome occurred within the Time Window of the message being sent, but the user never interacted with the message. See [Outcomes](/docs/en/custom-outcomes) for details.
* `unattributed` = the Outcome occurred without a direct or influenced attribute.
* `total` = (default) the sum of direct+influenced+unattributed.

***


# Changelog
Source: https://documentation.onesignal.com/release-notes/changelog

Learn about the latest updates to OneSignal.

Follow along with updates across OneSignal. We're launching new features and improving our product all the time!

<Update label="June 18 2026">
  **AI-assisted SDK installation updated and expanded**

  * AI install prompts have been rewritten and expanded to cover Android, iOS, React Native, Flutter, and Web SDKs.
  * Paste a single ready-made prompt into your AI coding assistant (Cursor, Claude, Copilot, or similar) and the assistant installs the SDK, drops in initialization code, and configures push and in-app messaging automatically.
  * No deep development experience required — marketers and non-technical users can complete SDK setup in minutes.
  * Prompt instructions were revised to fix errors identified during internal testing, so generated integrations are more accurate.
  * Available to all new sign-ups with no enablement required; requires an AI coding tool and access to the app codebase.
</Update>

<Update label="June 15 2026">
  **Extended `in_array` and `not_in_array` relations to the Device Type filter**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `device_type` filter field. Use them to match against a comma-separated list of device types in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "device_type", "relation": "in_array", "value": "iOS,Android"},
    {"operator": "AND"},
    {"field": "device_type", "relation": "not_in_array", "value": "Email"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="June 15 2026">
  **RCS editor experience improvements**

  We've improved how you build and send RCS, giving you a more intuitive editor, clearer approval visibility, and a more graceful SMS fallback experience:

  * **See carrier approval status in settings.** Each sender resource's carrier approval status is now visible at **Settings > SMS > Senders**, so you can track where each carrier stands in the approval process without leaving the dashboard.
  * **Select a sender per RCS template.** In Templates you now choose a specific sender instead of relying on a single global default, improving how RCS sends within Journeys and giving you automations for multiple SMS use cases.
  * **A more intuitive editor.** The composer automatically shows the right editor for the selected sender — the RCS editor for senders with an RCS resource, and the SMS editor for SMS-only senders.
  * **Text only RCS.** A new Text only content type sends plain branded RCS text.

  When a sender gains an approved RCS sending resource, OneSignal automatically prefers RCS for existing automations on that sender, mapping your existing SMS content to RCS so there's no manual rework.

  Available for all customers contracted for RCS. See [RCS messaging](/docs/en/rcs-messaging) for details.
</Update>

<Update label="June 8 2026">
  **Segment editor improvements: multi-value filters, copy filters, and filter JSON**

  Building segments in the dashboard is now faster and more flexible:

  * **Match multiple values in one filter.** The Language, Country, App Version, and User Tag filters now support the "is any of" and "is not any of" relations, so you can match a list of values in a single filter instead of chaining several filters with OR.
  * **Copy filters and filter groups.** Duplicate an individual filter or an entire filter group from the editor to reuse its configuration without rebuilding it by hand.
  * **View and copy filter JSON.** Open the filter JSON panel to see the REST API representation of your segment's filters, then copy it to use directly in the [Create segment](/reference/create-segments) API.
</Update>

<Update label="June 4 2026">
  **Retired Alexa and Windows Phone 8.0 as Device Type filter options**

  The `Alexa` and `Windows Phone 8.0` values are no longer available for the Device Type filter when you create or edit a segment, in both the dashboard and the Create segment API. Selecting either value in the dashboard is no longer possible, and the API rejects them with a validation error.

  Existing segments that already use these values continue to evaluate and deliver as before. To save changes to such a segment, replace the retired Device Type filter first.
</Update>

<Update label="June 2 2026">
  **Extended `in_array` and `not_in_array` relations to tag and app version filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `tag` and `app_version` filter fields, in addition to the `country` and `language` fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"},
    {"operator": "AND"},
    {"field": "app_version", "relation": "not_in_array", "value": "1.0.0,1.0.1"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="May 11 2026">
  **Email BCC is now generally available**

  You can now add BCC (blind carbon copy) recipients to email sends, including templates used in journeys and messages sent via the API. Use BCC to archive customer-facing email to a shared inbox or compliance system, forward sends to third-party services, or keep internal stakeholders copied on transactional sends.

  * Available on all plan types.
  * Maximum of 5 BCC addresses per send.
  * Each BCC recipient counts toward the total email volume for that send (for example, 1,000 primary recipients with 1 BCC address = 2,000 sends).
  * BCC metrics are excluded from analytics.

  See [BCC emails](/docs/en/email-bcc) for setup and usage details.
</Update>

<Update label="May 12 2026">
  **Added `in_array` and `not_in_array` relations for country and language filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `country` and `language` filter fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "in_array", "value": "US,GB,CA"},
    {"operator": "AND"},
    {"field": "language", "relation": "not_in_array", "value": "es,fr"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="April 21 2026">
  **Manage custom aliases from the User Profile**

  You can now view, add, edit, and delete a user's custom aliases directly from the **Aliases** section on the User Profile **Overview** tab, without using the API.

  * Add an alias by entering a label (alias key) and value (alias ID), copy any alias value to the clipboard, edit a value, or remove an alias.
  * Each user supports up to 10 aliases, and alias labels and values can each contain up to 128 characters.
  * `external_id` and `onesignal_id` are reserved and can't be used as custom alias labels.
  * A user must have an External ID set before you can add custom aliases. External ID is still managed separately in the Profile section.

  See [Aliases](/docs/en/aliases) for more details.
</Update>

<Update label="April 17 2026">
  **Role-based access control (RBAC) is now generally available**

  Granular role-based access control has been rolled out to all customers, giving teams more flexibility to support least-privilege access patterns and manage permissions as they scale.

  * **New `team_member` org-level default role.** A baseline role for new users added to an organization.
  * **New `composer` app-level role.** Lets users create and edit messages, templates, segments, and journeys without sending, activating, or deleting content.
  * **Updates to `editor` and `viewer` roles.** Refined permissions for clearer separation of duties.
  * Available roles vary by plan type.

  See [Manage team members](/docs/en/manage-team-members) for the full breakdown of roles, permissions, and plan availability.
</Update>

<Update label="April 16 2026">
  **Light/dark mode toggle for HTML in-app message previews**

  You can now switch between light and dark mode directly in the dashboard when previewing HTML in-app messages, so what you see matches what your users will actually see.

  * A light/dark mode toggle is now available in the in-app message preview for HTML messages.
  * The preview no longer reflects your OS theme. It reflects the mode you select in the dashboard.
  * Previously, the preview always rendered using whatever theme your own computer was set to, with no indication that was the cause, so there was no reliable way to check dark mode designs from the dashboard.

  HTML in-app messages do not automatically get a dark mode. The message still has to be coded for it using `@media (prefers-color-scheme: dark)` styles. If your message doesn't include those styles, toggling to dark mode in the preview won't change how it looks.

  The toggle is available for HTML in-app messages only. Block-type in-app messages are not included in this release. Generally available for all customers using HTML in-app messages.

  See [Design your in-app message with HTML](/docs/en/design-your-in-app-message-with-html) for how to add dark mode support.
</Update>

<Update label="April 15 2026">
  **Standardized delivery metrics across all channels**

  Delivery metric terminology is now consistent across every messaging channel in OneSignal. All channels now share a unified delivery hierarchy: Audience → Sent → Delivered, with the same definitions everywhere. Labels have been aligned across delivery reports, journey reports, engagement trends, and CSV exports. The [Metrics Glossary](/docs/en/analytics-metrics-glossary) has been fully rewritten as the canonical reference for every metric definition.
</Update>

<Update label="April 10 2026">
  **Audience counts now show subscribed and unsubscribed breakdowns**

  The segment editor now shows both subscribed and unsubscribed counts for every subscription-based segment, with a per-channel breakdown across push, email, and SMS. Previously, only the opted-in (subscribed) count was visible.

  Additional improvements:

  * Counts always return within approximately 15 seconds. Exact counts are shown when possible; estimates are used when an exact count can't be calculated in time.
  * Estimates are clearly labeled: above 10,000 with a +/- margin of error (e.g. 140,000 +/- 5,000), and below 10,000 as a less-than value (e.g. \<4,800).
  * Estimates will never show 0 for a segment. Previously for segments with very small but non-zero membership, estimates could incorrectly show as 0.

  This release covers subscription-based segments. User-based segment improvements are coming later in Q2 2026.
</Update>

<Update label="April 7 2026">
  **Updated User Profile page**

  The User Profile page has been redesigned with a tabbed layout and several new management actions directly on the page:

  * Add and remove Subscriptions from a User
  * Search across a User's data tags
  * Perform more direct edits and admin actions without leaving the profile

  The previous profile view is still accessible from the **Actions** menu if you need it.
</Update>

<Update label="March 25 2026">
  **test users now apply at the User level**
  Marking a Subscription as a test user now automatically marks all Subscriptions for that User as test users, effectively creating a Test User.

  * Any new Subscriptions added to a Test User will automatically be marked as test users.
  * Test User is now a User-level property rather than a Subscription-level one.

  **OneSignal Server SDKs just got their first v5 stable release!**

  After a period of testing and iteration, v5 is now the default version users will get when installing any of our server SDKs. Here are the current versions included in this release:

  | Language | Version |
  | -------- | ------- |
  | Node.js  | 5.4.0   |
  | Go       | 5.3.0   |
  | Java     | 5.3.0   |
  | .NET     | 5.4.0   |
  | Rust     | 5.3.0   |
  | Ruby     | 5.3.0   |
  | Python   | 5.3.0   |
  | PHP      | 5.3.0   |

  This release pairs well with our recently refreshed Server SDK Reference, giving developers a solid starting point for integrating with the OneSignal API.
</Update>

<Update label="March 20 2026">
  **Audit Log Export is now in GA**

  * Customers can now export audit logs. Customers can export 2 days for free tier and up to 90 days with security and legal entitlement (either as individual SKU or enterprise plan).
  * Provides customers additional metadata details and allows them to filter through data locally for their own audits and consumption with their own tools.

  **Failed Reasons in Audience Activity for everyone!**

  * Free plan users can now see exactly why individual audience members failed to receive a notification — directly in the Audience Activity view.
  * When a notification fails, especially common when troubleshooting set up, free users had no way to know whether the problem was a bad token, an unsubscribed user, or a device issue — leaving them guessing and unable to fix anything. Now they get the same failure visibility paid users have, so they can debug and get set up properly.
  * Same data retention as audience activity (30 days)
</Update>

<Update label="March 17 2026">
  **Data Model Updates and Field Deprecations**

  To improve platform performance, strengthen data integrity, and reduce the risk of configuration errors, we are introducing several updates to the OneSignal data model.

  These changes will take effect **April 15, 2026.**

  **Field Limits**

  We are introducing limits on two user fields to improve consistency and prevent unexpected behavior.

  Existing records exceeding these limits will not be modified to avoid disrupting current data and operations.

  **External ID**

  * `external_id` values can contain up to 128 characters.

  **Aliases**

  * Each user can have up to 10 aliases.
  * Each alias key and value can contain up to 128 characters.

  **Field Deprecations**

  We are deprecating several legacy Subscription fields that are no longer actively used:

  * `amount_spent`
  * `rooted`
  * `bought_sku`
  * `app_interests`
  * `purchased_items`

  After April 15, 2026, these fields will no longer be available in:

  * Segment Builder
  * API requests
  * Event streams
  * Webhooks

  **Impact for Customers Using These Fields**

  If your implementation currently references any of these fields:

  **Segments:** Segments using these fields will be paused and labeled for your review.

  **Journeys:** Journeys depending on those segments will be archived.

  **Event Streams and Webhooks:** These fields will return empty values.

  **What You Need to Do**

  Most customers do not need to take any action.

  If your implementation relies on any of the deprecated fields, we recommend reviewing your segments and integrations before **April 15, 2026.**
</Update>

<Update label="March 6 2026">
  Email Address Validation is now available!

  * When email addresses are added to OneSignal, they're now validated at three entry points:
    * API: syntax check
    * CSV import: full validation including typo detection, MX record lookup, disposable email flagging, and role-based address detection\*
    * Bulk validation: same full checks, runs against addresses already in your audience
  * Free plans have syntax and typo checks.
  * Paid plans will have syntax, typo, MX, disposable email, and role based email address checks.

  See [Email Address Validation](/docs/en/email-address-validation) for more details.
</Update>

<Update label="March 4 2026">
  **Dashboard layout redesign has shipped!**

  * Panel-based layout. The old floating card approach has been replaced with flat panels. The side nav sits in a clean gray panel, and the main content in a white panel. This simplifies the look and feel and gives us a more modern aesthetic.
  * New global top bar. Breadcrumbs, the new Create menu, Help/Support links, and Upgrade button all live in a new sticky top bar that follows you on scroll.

  **Richer date context across the dashboard**

  Dates show up everywhere in OneSignal — denoting message creation, notification send times, user sessions, etc. — but it wasn't always clear which timezone you were looking at, or how recent something actually was. This came up in a discussion last week among the dashboard engineers.

  Now, hovering over a date in the following areas of the Dashboard shows a tooltip with three pieces of context at once: the time in your local timezone, the time in UTC, and a relative timestamp (like "2 days ago").

  Where you'll see it:

  * Message lists and indexes
  * Message reports
  * Message review modals before sending
  * User and subscription profiles

  This is enabled for all apps — no action needed. Just hover a date and it's there!

  **In-App Message library with new quickstarts!**

  We've shipped a library of professionally designed, ready-to-use in-app message templates — available now to all plans in the dashboard.

  What's in it: 7 categories of quick starts covering the most common IAM use cases: push soft prompts, promotions, onboarding flows, feature announcements, location prompts, spin-to-win, and notification preference centers.

  How to access: Dashboard → Messages → In-App → New In-App → OneSignal Quick Starts. No feature flag or backend enablement required — available immediately. (See demo for the full experience in product)

  Go from zero to a production-ready in-app message in minutes, without writing HTML from scratch!
</Update>

<Update label="March 3 2026">
  **Enhanced Snowflake Integration Now Available!**

  Key improvements include:

  * 15-minute sync intervals (down from 24 hours)
  * Selective event syncing so customers only export what they need
  * Self-service setup directly in the OneSignal dashboard
  * New events like in-app impressions, email bounced/received, and separated Live Activity events.
  * We've also added richer properties including Template ID, last active timestamp, and subscription status.

  Customers get near real-time data in their Snowflake instance with full control over what gets synced meaning faster insights. Selective syncing alone can dramatically reduce event volume (and spend) by letting them export only the events that they need.

  This moves from the legacy flat annual fee to our Event Streams pricing model. Customers pre-purchase an event volume tier, and that tier covers all destinations (Snowflake, BigQuery, Databricks, etc.).

  Live now for all customers. All new customers will automatically have access to this new integration. Existing legacy Snowflake customers have until August 1st to migrate to the new integration before deprecation. Both integrations can run in parallel during the transition so they can ensure parity/consistency, and we will be doing outreach to those affected shortly.

  See [Snowflake](/docs/en/snowflake) for more details.
</Update>

<Update label="February 26 2026">
  **Audit Logs API is now available**

  Enterprise customers (with Legal & Security package) can now programmatically access the same audit log data surfaced in the OneSignal dashboard — pipe it directly into their SIEM, compliance tooling, or internal security workflows.

  * Returns a time-scoped record of actions taken in their org — who did what, when, and from where
  * Filter by app, action type, actor, target, or IP address
  * Supports cursor-based pagination for large result sets

  See [Audit Logs API](/reference/list-audit-logs) for more details.
</Update>

<Update label="February 9 2026">
  Huawei Badge Parameter Support

  We now support app icon badges on Huawei (HMS) devices via both the API and dashboard.

  * What's new: Three new parameters on `Notification#Create`
    * `huawei_badge_class` — the app's launcher activity class name (required for badge)
    * `huawei_badge_set_num` — set the badge to an exact number (0–99)
    * `huawei_badge_add_num` — increment the badge by a specific amount (1–99)

  On the dashboard, you'll see a new Badge option under Send to Huawei Android with "Don't set" / "Set to" / "Increase by" options.

  * Good to know:
    * Setting `huawei_badge_set_num` to 0 clears the badge
    * If neither set nor add is specified, the badge increments by 1 by default
    * Huawei does not auto-clear badges when the app opens
</Update>

<Update label="January 29 2026">
  API Documentation Improvements

  * New API endpoint: [View Segment](/reference/view-segment) - Retrieve details of a specific segment by ID, including optional segment filter details.
  * New API endpoint: [Update Segment](/reference/update-segment) - Update an existing segment's name and/or filters programmatically.
  * Fixed JSON example formatting across multiple API reference pages for improved readability:
    * Segments API: view-segments, create-segments, delete-segments
    * Users API: create-user, view-user, update-user, delete-user
    * Subscriptions API: create-subscription, delete-subscription, transfer-subscription, unsubscribe-with-token, create-alias-by-subscription
</Update>

<Update label="January 26 2026">
  **Audit Logs are now available!**

  * Customers now have the ability to determine exactly what's happening across their OneSignal account. Audit Logs gives them a complete timeline of every action taken in their organization—who did what, when, and from where.
  * Track 50+ action types including:
    * Authentication events (login, logout, API key operations)
    * Message activity (notifications sent, canceled, A/B tests, Journeys)
    * Team changes (member added, role changed, removed)
    * Configuration updates (webhooks, segments, templates, integrations)
    * Billing & subscription events
  * Powerful filtering:
    * Search by team member email
    * Filter by action type, app, IP address, or item type
    * Custom date ranges with presets
    * Shareable filtered URLs—customers can collaborate with their team instantly
  * Deep visibility:
    * Expandable rows reveal 30+ fields: IP address, browser, location, correlation ID, API version, and more
    * Available at both App and Organization levels
    * Quick-access links from Journeys, Segments, Templates, Notifications, and more
  * Retention:
    * Legal & Security package: 90-day lookback
    * All other plans: 2-day lookback
  * Perfect for security audits, debugging, and understanding team activity at a glance.
</Update>

<Update label="January 9 2026">
  * Standardized time series for charts are now available for:
    * Event Streams and webhooks
    * Email delivery reports
    * SMS/RCS delivery reports
</Update>

<Update label="December 22 2025">
  * confirmed receipt Now Available On Engagement Trends
    * Customers with access to confirmed receipt can now see confirmed receipt on the Engagement Trends Time Series Chart.
    * This missing data was a common point of confusion for customers. They could see confirmed receipt & click through rate, but had no access to the total confirmed deliveries metric.
    * This additional data point gives customers confidence in the rates we're showing and helps with confusion on the difference between "delivered" and "Confirmed receipt" for push notifications.
</Update>

<Update label="December 12 2025">
  * New integration - Self-serve Snowflake data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake without going through customer support
    * The legacy Snowflake documentation remains available for existing implementations
</Update>

<Update label="December 8 2025">
  Live Activities in Event Streams & Integrations

  Live Activities Analytics provides two key capabilities to optimize customers' live activity strategy:

  1. Better Troubleshooting with confirmed receipt
     Gain visibility into whether devices actually received live activity updates. confirmed receipt tracking identifies delivery issues quickly to understand the true reach of live activities.
     Available in:

  * Individual message reports with per-device confirmation
  * Data exports to BI tools (through event streams and integrations)

  2. Deeper Engagement Insights with data exports to integrations & event streams
     Answer critical questions about how users interact with your live activities:

  * How many users engaged with my live activity over its duration?
  * When did users drop off?
  * What was the peak engagement time?
  * When did users click? (coming soon)

  Export live activity data to BI tools to analyze engagement patterns, optimize timing, and improve future campaigns.
</Update>

<Update label="December 5 2025">
  We've launched a new [Metrics Glossary](/docs/en/analytics-metrics-glossary) in our documentation. This resource provides a single source of truth for delivery metric definitions, helping both our team and customers understand our metrics consistently across dashboards, APIs, and exports.
  While we continue working toward unified terminology across all touch points, this glossary establishes clear mappings and definitions as they exist today, making it easier for customers to navigate our current analytics landscape.

  Custom Events in User Activity Timeline
  Custom events are now visible per User on their profile page in a dedicated tab. You can:

  * Filter by event type and event source
  * Filter by date, to any time window in the past. Only limiting factor is customer's own events retention window setting!
  * Expand each event to see the full payload
  * Click through to the events index to see that event type's config and full cross-user activity log

  This is important because:

  * It helps paint the complete picture of user activity. At a basic level, customers ask the question, "what's going on with this user?" and this helps answer it.
  * Especially useful for zoomed-in troubleshooting, auditing, what-happened analysis.
  * Please note: this will only be visible to customers in Custom Events early access, but will be available to all as they gain access to Custom Events
</Update>

<Update label="November 26 2025">
  UX Improvements Now Live

  1. Row-Level Linking
     You can now click anywhere on a table row to navigate to its destination, instead of having to click a specific cell. This makes navigation faster and more intuitive.
  2. Row Highlighting on Hover
     All tables now highlight the entire row on hover, helping users track data more easily and reducing visual strain when scanning wide tables.
  3. Improved Responsiveness
     The actions column has been narrowed to preserve horizontal space and is now right-aligned at the end of every table.
     It also features sticky, floating behavior — especially useful on smaller screens where horizontal scrolling is required.
     Some tables better truncate long text (e.g., lengthy message names) more effectively to maintain a clean layout.
  4. Refined Sorting UX
     Updated sort icons make the sort direction easier to interpret. Clicking anywhere on a column header now toggles sorting, improving ease of use.
  5. Unified Column Visibility Menu (Applies to Journeys, Users, Subscriptions)
     Tables with customizable columns now use a consistent, cleaner UI. Column changes update live as you toggle them.
  6. Updated Search Bar UI
     The search bar now aligns with design standards, featuring a left-aligned search icon, and a button that shows after typing for easy input clearing.
  7. Improved Pagination Formatting
     Pagination controls now use comma formatting for large numbers, improving scannability and readability.

  Core Component Update
  Many of the enhancements above come from migrating these tables to our core design system’s DataTable component. Sorting and filtering improvements for tables are consistently among the most requested features we receive. While these updates don’t introduce new sorting or filtering behavior yet, this component upgrade provides a more consistent experience for the functionality we have today, and does lay the foundation for Product teams to build more advanced table capabilities once those initiatives are prioritized.

  Coming Soon

  * Most tables across the Dashboard already include these improvements. A few remaining areas still require component updates before they can adopt the full set of new enhancements:
    * In-app index
    * Templates index
    * Audience activity table
    * A/B tests stats table
</Update>

<Update label="November 12 2025">
  UX Enhancement: Duplicate Templates Directly from the Editor
  In usability tests and dogfooding sessions, we noticed users often duplicate Journey nodes and then edit their templates. Previously, you had to exit the template editor and duplicate the template from the index view, an extra step that interrupted the workflow.
  Now, you can duplicate templates directly from the actions dropdown in the template editor. This small but meaningful improvement streamlines your editing experience and makes iteration faster. While our long-term goal is to enable template/content editing directly within Journeys, this enhancement is a great step in that direction.

  New Platform Filters for Engagement Trends & Subscription Trends
  You can now filter push engagement trend data by platform (iOS, Google Android, Huawei, etc.) to get a more granular view of performance across specific devices.
  In the spirit of our Analytics Consistency project, we've also brought this same filtering experience to Subscription Trends.

  Analytics Consistency: Standardized Time Series Chart Filters
  We're standardizing filter options across our time series charts, giving customers a consistent experience and clear access based on their plan.
  Key Changes:

  * All charts will share the same set of granularity and look back filters
  * Consistent casing and terminology used on all filters
  * Consistent upgrade experience for customers on plans with limited access
    As an example, Subscription Trends now supports a 2 year look back after the change.

  Charts where we've already rolled out these changes:

  * Engagement Trends
  * Subscription Trends
  * Global Outcomes
  * Push Delivery
  * All Template Reports
  * Coming Soon:
  * Email Delivery
  * SMS Delivery
  * Journeys Reports

  Look back access based on plan type:

  * Free: 30 days
  * Growth: 90 days
  * Professional: 1 year
  * Enterprise: 2 years
  * Custom: Up to 90 days (based on plan types above)
</Update>

<Update label="October 6 2025">
  Nice UXE on Journey Settings. We’ve updated the Journeys Settings Side panel to be more user friendly by adding a side navigation to keep each section in focus. This is in tandem with the eventuality of having more settings available to the user as we look towards Journey Goals, and more.  We will accompany this release with an intercom slide letting the user know we have updated the settings area as to give them a heads up due to the abrupt pattern change.

  Every Setting, In Focus: Journey Settings are now grouped and spotlighted, helping you zero in on each choice without distraction.
</Update>

<Update label="October 2 2025">
  Custom Events are now available to all customers on paid plans! You can now send custom events via our API or SDK, and use them to trigger actions in Journeys with your own event data.
</Update>

<Update label="September 21 2025">
  Customers can now pause a segment that's counting towards their segments entitlement even though it's only being used in an archived journey or paused IAM. We also made it even easier to pause segments, if the user wants to pause a segment, we'll help the user pause or archive the active IAMs or journeys stopping the user from pausing a segment.
</Update>

<Update label="September 9 2025">
  Deactivate email senders

  Deactivate email domains that are no longer in use or were set up incorrectly. This includes fallback handling for your email templates and scheduled sends to make sure you don't break them by removing a domain, just in case it was being used more widely than you anticipated.
</Update>

<Update label="August 29 2025">
  Personalize emails with real-time Data Feeds

  You can now use Data Feeds to pull live content from your APIs directly into emails at send time. No more static CSVs or preloaded tags — every message can include the latest account details, product recommendations, or order updates.

  Available in the email template composer for emails sent via Journeys, Data Feeds includes preview tools and error handling to keep sends smooth.

  👉 See how to set up [Data Feeds](/docs/en/data-feeds)
</Update>

<Update label="August 04 2025">
  You can now hold users in a Journey step until specific conditions are met before they move forward with the *Wait Until* action. This new feature allows you to:

  * Hold users at a step until they enter a segment or trigger a message event (such as a specific message being delivered, opened, or clicked).
  * Add multiple conditions and branch users based on whichever condition they meet first.
  * Set an expiration path that moves users forward or removes them from the Journey if none of the conditions are met within your chosen timeframe. This gives you greater flexibility and control over how users progress through your Journeys. Learn more: [Journeys Actions](/docs/en/journeys-actions)

  AI Composer Push Notifications
  You can now generate or improve push notification message copy using the AI message composer. This update helps you craft high-performing content without leaving OneSignal. When creating a new push notification, select AI-generated push button to get started. To improve existing copy, select “Refine” in the Title, Subject, or Message fields.

  New [Integrations](/docs/en/integrations) index page contains the following enhancements:

  * Filtering by type of integration
  * Filtering by Inbound/Outbound directions of data flow
  * Includes our new inbound DWH/Data ingestion options for custom events
</Update>

<Update label="July 07 2025">
  * Quickly identify and manage segments tied to campaigns
    * We’ve made it easier to clean up outdated segments.
    * Previously, you couldn’t delete a segment if it was tied to an In-App Message (IAM) or Journey, even if that campaign was paused or archived. Now, when you try to delete a segment, you’ll see a modal listing all IAMs and Journeys that are preventing deletion.
    * This helps you quickly locate and update the associated campaigns, so you can keep your workspace clean and organized without having to hunt through every Journey or IAM.
</Update>

<Update label="June 30 2025">
  * Segment users based on real message engagement
    * You can now create user segments based on how they interacted with previous messages across push, email, SMS and in-app.
    * This update adds a new Message Event filter that allows you to segment users based on events like email opens, push clicks, SMS failures, and more - without relying on tags or external tools.
    * Available on all paid plans.
    * See [Segmentation](/docs/en/segmentation#message-event-filters) for more details.
</Update>

<Update label="June 27 2025">
  * New documentation with Mintlify!
    * We've updated our docs!
    * New AI features and easier readability.
    * Updated API reference and openapi spec.
    * New Tutorials page with common use cases and step-by-step details to get you setup quickly!
</Update>

<Update label="June 18 2025">
  * Track In-App engagement trends alongside push, email, and SMS
    * Customers can now see In-App Message impressions, clicks, and click-through rates directly in the Engagement Trends chart. This update gives marketers a unified view of how users are interacting with all message types over time—including In-App—making it easier to spot trends, report on performance, and optimize messaging across channels.
    * With this update, In-App engagement data is now included alongside push, email, and SMS across all views in the Engagement Trends chart. Stats are grouped by day and support up to two years of data (depending on plan). This data is exportable via CSV just like other channels, and can be filtered to look at specific date ranges or message types.
    * This feature is available to all customers.
</Update>

<Update label="June 12 2025">
  * Unlock deeper email engagement insights with multi-link tracking
    * Customers can now track engagement on every individual link within their emails. This update gives customers a much clearer view into what content or messaging is working so they can improve email performance over time.
    * Previously, when customers included multiple links within an email, they could only view total click counts across all links. Now, they can see which specific links get the most engagement and how links perform inside journeys. This helps them refine content and messaging strategies.
    * Multi-link tracking is automatically applied to most emails created in the Drag & Drop or HTML editor. Link-level performance metrics will also be available for emails sent using a template and emails in a Journey.
    * This feature is available to all customers with access to email.
</Update>

<Update label="May 23 2025">
  * View and optimize message performance with Template Analytics
    * OneSignal customers can quickly assess how individual templates are performing across all messages, without needing to download and stitch together separate reports.
    * When users click into a template, they now land on a detailed analytics view showing Delivered, Unique Opens, Unique Clicks, and Unsubscribes. They can track performance over time, filter by platform, explore delivery breakdowns like Failed or Capped, and review a list of messages that used the template.
    * Template analytics is especially useful for:
      * Marketers who test and iterate on message content
      * Developers who need visibility into transactional message delivery
      * High-volume senders seeking scalable insights
    * Transactional visibility is a key differentiator that sets us apart from Firebase and other open source solutions. Customers can now answer questions like “How many Account Confirmation emails did I send last week?” or “What was the click-through rate on my Password Reset messages?”
    * Important note: For templates created before April 17, 2025, enhanced metrics are only available for messages sent after that date. Customers can use the “Show historical data” toggle at the top of the page to see earlier performance data.
    * The feature is live and available by default. Reporting history varies by plan:
      * Free: 30 days
      * Growth: 90 days
      * Professional: 1 year
      * Enterprise: 2 years
</Update>

<Update label="May 16 2025">
  * Add users manually from the dashboard
    * You can now create new users directly from the *Users* tab in your OneSignal dashboard using a simple form. This update makes it easy to manually add a user with an email address, phone number, or both without needing an SDK, API call or CSV upload.
    * This is especially helpful for quickly testing campaigns or adding users who aren’t yet in your system.
</Update>

<Update label="May 14 2025">
  * Track SMS link performance directly in OneSignal
    * Customers can now track SMS link performance directly in OneSignal without needing third-party tools like Bit.ly or custom UTM parameters. This feature gives our customers a more streamlined, built-in way to measure engagement and optimize messages faster, removing friction and helping drive better results from their SMS efforts.
    * When composing an SMS message, customers simply click “Insert Trackable Link” and enter the full URL they want to send users to. OneSignal automatically shortens the link using the 1sgnl.co domain so it fits within SMS character limits and can be tracked.
    * All SMS users will have access to trackable links as part of their existing plan.
</Update>

<Update label="May 07 2025">
  * Simplify message organization with easier label management
    * Now you can add labels to your messages to help you organize and manage them.
    * See [Labels](/docs/en/labels) for more details.
</Update>

<Update label="May 01 2025">
  * Template analytics
    * You can now view and optimize template performance from a centralized reporting view. Click into any message template to view detailed performance data across every message a template is used in.
</Update>

<Update label="Apr 25 2025">
  * Improved CSV Importer
    * **Real-time validation:** Get instant feedback on formatting errors before upload.
    * **Smart column mapping:** Easily align your CSV headers with OneSignal fields.
    * **Email suppression support:** Add or manage your suppression list directly in the file.
    * **Upload history:** View the status of your past imports for up to 30 days.
    * **Helpful templates:** Start quickly with a pre-built CSV example.
</Update>

<Update label="Apr 21 2025">
  * Fine-tune your Live Activities with new API parameters
    * You can now add more control, reliability, and speed to your Live Activities with three new parameters in the OneSignal API: - ios\_relevance\_score: Helps determine which Live Activity displays most prominently on iOS. - include\_aliases: Allows you to target individual users directly rather than relying on segment-based delivery. - idempotency\_key: Prevents the creation of duplicate Live Activities when retrying start requests if not using the OneSignal SDK.
</Update>

<Update label="April 14 2025">
  * New integration - Databricks data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Databricks. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Databricks, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="April 08 2025">
  * View opt-out status by sender and support transactional messaging even with marketing opt-outs
    * You can now see SMS opt-out status by sender, giving you better visibility and control when managing marketing and transactional messages.
    * With this update, you can:
      * View subscription status by individual sender for any phone number
      * Continue sending transactional messages (like OTPs or alerts) even if a user has opted out of marketing
      * Maintain deliverability and avoid carrier filtering by respecting opt-out preferences
    * This is especially useful if you manage separate senders for promotional and transactional use cases.
    * To access this feature, go to **Consent Management > Advanced Opt-out Settings** and turn off the setting that globally unsubscribes a user when they reply with an opt-out keyword.
    * *Note: This option is only available to customers using advanced opt-out settings for SMS.*
</Update>

<Update label="March 19 2025">
  * Easily find and select the right templates with visual previews
    * Quickly identify and select your email and in-app message templates with the new updated card view.
    * Instead of relying on template names alone, you can now see clear visual previews, making it easier to choose the right template at a glance.
</Update>

<Update label="March 12 2025">
  * Create users in OneSignal via HubSpot workflows
    * Keep your users in sync across HubSpot and OneSignal! With this new workflow action, you can now create users in OneSignal whenever a HubSpot workflow trigger fires. This enables you to queue up personalization details (such as Tags) and plan engagement strategies before a user even interacts with your mobile platform. Additionally, you can trigger an SMS or email via HubSpot while simultaneously creating a user in OneSignal—ensuring seamless and immediate engagement.
    * [HubSpot Documentation](/docs/en/hubspot)
  * Push preview accuracy improvements
    * As operating systems update, they often introduce new changes in their push designs.
    * We've updated our previews so they match latest and greatest push notification designs across iOS (18), Android (15), Windows (11), macOS (Sequoia). This ensures you see what your users will see when testing in OneSignal.
  * PII Masking of Emails and Phone Numbers
    * Protect user privacy and reduce compliance risks by masking personally identifiable information (PII) such as emails and phone numbers. With PII masking, your team can work securely while still analyzing campaign performance and sharing insights across teams.
    * OneSignal automatically masks phone numbers and emails in the dashboard and any data exported directly from the platform. However, PII masking does not currently apply to data accessed via API requests, external IDs, or Tags.
</Update>

<Update label="March 07 2025">
  * Verify & Lookup Phone Numbers
    * Sends the user a one-time verification code to ensure the customer owns the phone #
    * Confirms the phone number entered by a user at onboarding is valid
</Update>

<Update label="February 28 2025">
  * Added New Integration - [BigQuery Data Export](/docs/en/bigquery)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to BigQuery. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in BigQuery, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
  * Channel subscriber counts have moved
    * The counts of subscribed counts for each channel have moved from the dashboard to the Subscriptions page in OneSignal. Now you will see the number of *Subscribed* subscriptions for each channel at the top of the Subscriptions page under Audience to get an overview of audience reach per channel in the context of your subscriptions.
    * If you still wish to view this information on the Dashboard, you can filter your Subscriptions trends chart by channel.
</Update>

<Update label="February 14 2025">
  * Improvements to Keywords
    * We've made a couple of improvements to our SMS keywords.
      * Segment by subscription status when sending a keyword to encourage converting your customers who are not yet subscribed into opting in to your SMS marketing messages
      * Setup an auto-responder for unrecognized keywords
</Update>

<Update label="February 12 2025">
  * New Engagement Analytics on the OneSignal Dashboard

    * Are you curious to learn more about how your end users engage with the messages you send from OneSignal? Head to your Dashboard to see the new Engagement Trends report.
    * With this report you will gain insight into how users engage with your messages across Push, Email, and SMS. Track click-through-rate, unsubscribes, and monitor trends over time to refine your messaging strategy and optimize communication frequency. This comprehensive report consolidates data from all message types (Dashboard, API, Journeys) for a clearer view of performance. Now available in your OneSignal dashboard!

    <Frame>
      <img alt="New Engagement Analytics on the OneSignal Dashboard" />
    </Frame>
</Update>

<Update label="January 29 2025">
  * Sort segments by Last edited, Created at and more
    * Finding and managing your segments just got easier!
    * You can now sort segments by Last edited, Created at and more.
      * This update is especially valuable for customers who:
        * Maintain numerous segments
        * Frequently update their segment configurations
        * Need to identify and clean up outdated segments
        * Want to quickly find recently modified segments
</Update>

<Update label="January 27 2025">
  * Email Senders (Multi-Domain Sending)
    * Create distinct senders for different types of communications:
      * Keep your marketing campaigns separate from crucial transactional emails
      * Maintain different brand voices for various product lines
      * Optimize sender reputation for each type of communication
      * [Email Senders](/docs/en/senders)
  * Improved In-app Message Analytics for Event Streams
    * We've added a new In-app Message Analytics for Event Streams.
</Update>

<Update label="January 21 2025">
  * Email Intelligent Delivery
    * We've added intelligent delivery to email.
    * Transform your email engagement with OneSignal's latest breakthrough: Intelligent Delivery. This powerful new feature automatically determines the optimal time to reach each individual user, maximizing your email campaign's impact.
    * Our algorithm continuously learns from:
      * User open patterns
      * Click-through behavior
      * Real human interactions (excluding bot activity)
</Update>

<Update label="January 16 2025">
  * Retirement of Automated Message for Free apps
    * Automated Messages are no longer supported and the feature has been retired in the free plan. Paid apps will continue to have access to this feature until further notice.
    * Active automated messages will remain live and continue functioning as expected. However, you can no longer create new automated messages, or reactivate paused automated messages. To build new automated sequences and enhance your campaigns, we recommend using [Journeys](/docs/en/journeys-overview).
</Update>

<Update label="January 15 2025">
  * Customize how your users re-enter split branches
    * Now you can customize how your users re-enter split branches. This feature is available for all Journeys.
    * [Journey Entry Triggers](/docs/en/journeys-actions)
  * Improving New Message Experience
    * We improved the new message experience by adding a library of templates (get inspiration for your next push, in-app, email, or SMS), or quickly start from a template you've made, or a previous message.
</Update>

<Update label="January 03 2025">
  * message.url - New Push Event Stream Property
    * `message.url` is now a supported property for push events. It enables the retrieval of the launch URL directly from your event stream payload.
</Update>

<Update label="December 24 2024">
  * Journeys Multi-split Branching
    * Now you can set up more personalized paths in your Journey. Create up to 20 branches to test channels, content, timing, ordering, and more. Assign different weights to each branch, or easily distribute audiences evenly across all branches. See how different paths perform against each other or against a control group.
</Update>

<Update label="December 20 2024">
  * WordPress Plugin v3
    * We've upgraded our Wordpress Web Push plugin to v3+. What's changed:
      * Upgrades the OneSignal Web SDK from version 15 to 16.
      * Setup more new prompts within the OneSignal dashboard, including the following. No custom code is required anymore to configure these.
        * Category Prompt
        * Email/Phone Slide Prompt
        * Custom Link Prompt.
      * When publishing a new post, check the "Send notification when post is published" box to send a push notification.
      * Choose which audience segment should receive notifications for each post.
      * Web Topics are included by default.
      * Send to mobile app subscribers, with an option to direct them to a different URL (Deep Link).
</Update>

<Update label="December 11 2024">
  * Improved Logs in Event Streams
    * We've improved the Event Streams feature to make troubleshooting simpler and faster. Now, you’ll find dedicated tabs for successful and failed events, making it easier to spot issues at a glance. Clear empty states show when there’s no data in either tab, and updated messaging ensures you know the logs display a sample of your data.
  * SMS Keywords
    * We've added keywords for SMS. Keyword engagement enables quick, two-way communication, enhancing personalization, accessibility, and user satisfaction. It drives conversions and higher engagement with your subscribers. Add a data tag to the keyword, and segment based on their preferences to send more targeted SMS.
  * Quickstart Segments

    * We are thrilled to launch three new segment templates designed to help you hit the ground running with proven strategies:
      * First-Time audience
      * Regional audience
      * Custom Audience based on tags
    * Our analysis of 6.3 billion message deliveries uncovered powerful insights. These templates are built to help you:
      * Create high-performing segments from day one.
      * Use proven filter combinations that drive higher engagement.

    <Frame>
      <img alt="Quickstart Segments" />
    </Frame>
</Update>

<Update label="December 02 2024">
  * Email Quickstart Templates
    * We've added a library of quickstart templates for email. Explore our library of professionally crafted email templates, designed to inspire your creativity and elevate your email campaigns. Use them as a starting point to create impactful messages that drive conversions and engage your audience effectively.
</Update>

<Update label="November 27 2024">
  * Scheduling Journeys
    * Now you can schedule Journeys to send at a specific time. This feature is available for all Journeys.
  * Settings Overview Page
    * Now you can access and manage all your settings in a centralized setting overview page. Platform-specific settings have been reorganized under their relevant channels for better clarity.
</Update>

<Update label="November 20 2024">
  * Bulk Archive and Delete Journeys

    * Now you can bulk archive or delete Journeys from the Journeys index. Select up to 20 Journeys, and then choose an action you'd like to take to clean up Journeys you're no longer using.

    <Frame>
      <img alt="Bulk Archive and Delete Journeys" />
    </Frame>
</Update>

<Update label="November 06 2024">
  * Improved Export for Global Outcomes
    * We've improved the export for Global Outcomes to include more data and make it easier to use in your reporting.
  * Preview allows you to preview the content of a message and can be very helpful when you have a message with personalization (i.e. Tags, dynamic content, custom data). With preview, you can preview content from a specific test user's perspective, or with example custom data.
  * Settings for Email & Side Navigation Updates
    * In the side navigation, you can now easily see your Push, SMS, and Email settings. What was once "Messaging" is now "Push" settings, and SMS and Email Settings will take you directly to your channel's settings.
    * For email, we've created a dedicated place to manage your email provider and senders. If you are a OneSignal mail user, you'll also be able to see your reputation and suppression lists here.
  * SMS Usage
    * We've added SMS Usage in the Usage page. We've also added a breakdown so you can see the message type, and a breakout by inbound and outbound. You may see an unknown country if a segment failed to send.
</Update>

<Update label="October 02 2024">
  * Add Notes on your Journeys
    * Now you can add notes to the steps of your Journeys to keep reminders and more effectively collaborate and share information with your team. This feature is available for all Journeys.
</Update>

<Update label="September 27 2024">
  * New Quickstart Journeys
    * We've added a new Quickstart Journeys to help you get started with Journeys. This feature is available for all Journeys.
  * SMS Text-to-Subscribe
    * It's now easier to set up double opt-in and text-to-subscribe phone number collection experiences for your customers!
</Update>

<Update label="September 12 2024">
  * Confirmed Click-Through-Rate (CCTR) metric

    * We have added a new metric to measure the CTR using confirmed receipt. Confirmed Click-Through-Rate (CCTR) is measured by (total clicks/confirmed delivered) \* 100%

    <Frame>
      <img alt="Confirmed Click-Through-Rate (CCTR) metric" />
    </Frame>
</Update>

<Update label="September 06 2024">
  * Export your Subscription Trends
    * Now you can export the data from your Subscription Trends report as a CSV. If you apply filters to the report, OneSignal will export based on the filters you've applied so that you can fine-tune the data that you use to evaluate your messaging audience.
</Update>

<Update label="August 05 2024">
  * Email Saved Rows
    * Saved Rows are reusable content blocks that help streamline email creation and management. Many companies, especially those that have a lot of templates, prefer to use saved rows in their emails for consistency and to save time. Saved Rows are easily attached to new emails so you don't have to create the same information from scratch each time. And when things change, you just have to update the saved row, and your updates will automatically sync across all campaigns that have that saved row attached.
    * Common use cases include:
      * headers (logo, slogan)
      * footers (company details, social media links, mailing addresses)
      * disclaimers
      * other elements that are used across multiple campaigns
    * You can now save Email Drag-and-Drop rows to use across many Campaigns or Templates. These re-suable **Saved Rows** make it easy to sync updates across many emails at once. Click on the **Rows** tab of a Drag-and-Drop email, to view your **Saved Rows**. To save your first row, click the save icon in the edit, in the top right corner of the row.
    * We recommend you set up all of your templates to use saved rows for your header and footer so that you need to update the branding or content; you only have to make those edits once.
</Update>

<Update label="July 30 2024">
  * Journeys now target anonymous users
    * Now, Journeys do not require External IDs to be set on subscriptions. Instead, Journeys will target your entire user base within OneSignal, including anonymous users. We recommend still configuring External IDs to identify individual users who have subscribed to multiple channels.
</Update>

<Update label="July 25 2024">
  * Have more visibility into SMS unsubscribes, resubscribes, and help keywords
    * We now make it easier to manage your Consent Keywords within Onesignal. Reach out to support if you'd like to update the default consent keywords and replies.
</Update>

<Update label="July 19 2024">
  * Email Reply-to field now supports custom properties
    * Now you can use [Message Personalization](/docs/en/message-personalization) within the `reply-to`field on an email. This allows you to direct message replies to the right inbox and can be helpful if you are sending from different brands or across different countries.
</Update>

<Update label="July 16 2024">
  * Push Failures and Unsubscribes in Audience Activity
    * Obtain a list of subscriptions that have faced errors - failures or unsubscribes, for a specific push notification in the push report page.
</Update>

<Update label="July 03 2024">
  * Integrations: OneSignal Message Events can be sent to Twilio Segment
    * Customers can now select and send message events from OneSignal to sync back to their Twilio Segment account, making the Segment integration bidirectional.
  * Use Audience Activity for Live Activities to get a list of recipients
    * Get a list of subscriptions that successfully or failed to receive a Live Activity on a Live Activity report page, which is accessible through the Delivery - Sent Index. This list can be exported as well.
</Update>

<Update label="June 06 2024">
  * In-app message audience activity
    * In the report page of an in-app message, you can now see which mobile subscriptions viewed (impression) or clicked on an in-app message. Audience activity is available for 30 days from the time the message is displayed
</Update>

<Update label="May 15 2024">
  * FCM Expired Tokens > Increased Android Unsubscribes
    * On May 15, 2024, Google's FCM service will start to expire stale push tokens for devices that have been inactive for more than 270 days. You may see a spike in Android unsubscribes when sending notifications due to this change. Don't panic! These are devices that have not been online in over 270 days and are part of Google's [Best practices for FCM registration token management](https://firebase.google.com/docs/cloud-messaging/manage-tokens). If the device does come back online and opens your app, OneSignal will automatically resubscribe them to push if they were previously subscribed already.
    * See [FCM Expired Token FAQ](/docs/en/fcm-expired-token-faq) for more details.
</Update>

<Update label="April 29 2024">
  * Configure more granular Frequency Capping rates for Push
    * Push notifications can now be capped at a rate of x notifications per any time frame (less than 1 week). Navigate to Settings > Messaging > Push Frequency Capping > Custom (in the time dropdown) to view these settings.
    * Read [Frequency Capping Documentation](/docs/en/frequency-capping) for more details.
</Update>

<Update label="April 11 2024">
  * Added Android Live Notifications
    * Android's Live Notifications deliver live, dynamic content in notifications to enhance user engagement and app interactivity. This is a feature similar to iOS's Live Activities feature (introduced with iOS 16), but uses its own set of tools and APIs that enable similar functionalities.
    * See [Android Live Notifications](/docs/en/android-live-notifications) for more details.
  * Major improvements to Android SDK
  * Push to start Live Activities
    * Live Activities can now be launched on a user's screen when the mobile app is in the background (app is not open). Live Activities can both be started and updated by a remote push notification.
    * [How to start a Live Activity with a remote push notification](/docs/en/live-activities)
</Update>

<Update label="April 01 2024">
  * Added Audience Activity reports for Journeys
    * We have added Audience Activity reports for Journeys so you can get a closer look at which subscriptions were sent messages during a Journey. To view this report, click into a message report on your Journey. [Learn more here](/docs/en/journeys-analytics#audience-activity).
</Update>

<Update label="March 18 2024">
  * Added a new Setup guide for Analytics
    * We have added a new Analytics Setup guide to our product documentation detailing how to track Confirmed Deliveries and set up Custom Outcomes with support from your development team.
</Update>

<Update label="March 12 2024">
  * Mobile SDK Updates
    * We recommend updating to the latest SDK versions listed below to benefit from critical bug fixes, stability improvements, and new features. These updates include key enhancements across all platforms, including iOS 5.1.3 and Android 5.1.6, which improve concurrency safety, crash resilience, and background thread handling. The updates also include important API adjustments like more accurate property handling in the `PushSubscriptionState`.
</Update>

<Update label="February 16 2024">
  * Journeys is now available on the Growth plan
    * Journeys is now available on the Growth plan. This means you can now create and manage Journeys with up to 100,000 users.
    * See [Journeys](/docs/en/journeys-overview) for more details.
</Update>

<Update label="February 12 2024">
  * Added Auto Warm Up
    * We have added a new feature that allows you to automatically warm up your app when a user opens it. This feature is available for all OneSignal customers.
    * See [Email Warm Up](/docs/en/email-warm-up) for more details.
</Update>

<Update label="February 02 2024">
  * Journeys has easier targeting based on user activity
    * We've added support for Segments with time-based rules (e.g., first session, last session, etc.) and also simplified targeting inactive users. Now you can target your inactive users by including a segment based on last session behavior.
  * Email: Schedule Sends Across Different Timezones
    * Email campaigns can now be scheduled to send across different timezones. This feature is available for all OneSignal customers.
</Update>

<Update label="January 30 2024">
  * Email now supports One Click Unsubscribe
    * Inbox Service Providers (ISP) like Gmail, Outlook, iOS Mail, and Yahoo! Mail, AOL, and Verison Mail require senders to provide a One Click Unsubscribe option. The unsubscribe button is rendered at the discretion of the ISP based on sending criteria, which may include a daily sending volume greater than 5,000 emails.
</Update>

<Update label="December 18 2023">
  * Filter your messages with labels
    * Now you can filter your messages with [labels](/docs/en/labels). This feature is available for all OneSignal customers.
  * CSV Importer can now update properties
    * CSV Importer for email now enables updates to user properties `language`, `country`, and `timezone_id`.
  * Send more personalized messages and multi-language emails
    * [Dynamic Content Documentation](/docs/en/dynamic-content)
</Update>

<Update label="December 14 2023">
  * All OneSignal apps now belong to an Organization
    * We have added a new feature that allows you to manage your OneSignal apps within an Organization. This feature is available for all OneSignal customers.
    * See [Apps, Orgs, and Accounts](/docs/en/apps-organizations)
  * Journeys now has better analytics
    * We've added a new Journeys Report. See [Journeys Analytics](/docs/en/journeys-analytics) for more details.
</Update>

<Update label="November 22 2023">
  * Removed Journey Notifications from Delivery Reports and the View Notifications endpoint
</Update>

<Update label="October 04 2023">
  * Added new integration - [Snowflake](/docs/en/snowflake)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Snowflake, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="September 27 2023">
  * You can now save and continue
    * Changed the default option for saving a message to save work without exiting the message.
</Update>

<Update label="September 13 2023">
  * Added the ability to adjust the default padding for IAM blocks
    * Learn more about [IAM blocks](/docs/en/design-your-in-app-message)
  * Added the ability to edit entry triggers and re-entry rules for live Journeys
    * Learn more about [Journey entry triggers](/docs/en/journeys-overview)
</Update>

<Update label="September 05 2023">
  * Added ability to create multi-language push messages by pasting your CSV
    * Learn more about [Multi-language messages](/docs/en/multi-language-messaging)
  * Added new "Editor" role permissions
    * Learn more about [Managing team members](/docs/en/manage-team-members)
  * Added enhanced Journey message stats and reports.
    * Learn more about [Journey message stats and reports](/docs/en/journeys-analytics)
</Update>

<Update label="September 01 2023">
  * Added a new feature to forward email templates to an app
    * Learn more at [Email Template Forwarding](/docs/en/email-template-forwarding)
  * Added FCM v1 API support for Android Push Notifications
    * Learn more about [Android Firebase credentials](/docs/en/android-firebase-credentials)
</Update>

<Update label="August 15 2022">
  * Android 13 changes
    * Android 13 introduces a runtime notification permission, meaning users must opt in to receive push notifications. Apps targeting Android 13 must explicitly prompt for permission at a time of their choosing, or the system will display the permission prompt automatically on first launch—often resulting in lower opt-in rates.
    * See [Android 13 Push Notification Developer Update Guide](/release-notes/android-13-push-notification-developer-update-guide) or our [Prompt for Push Permissions](/docs/en/prompt-for-push-permissions) guide for details.
</Update>


# SDK Releases
Source: https://documentation.onesignal.com/release-notes/sdk-releases

View the latest OneSignal SDK releases and updates.

## Mobile

<SdkReleasesIframe />

## Web

<SdkReleasesIframe />

## Server

<SdkReleasesIframe />

## Plugins

<SdkReleasesIframe />


# Cancel message
Source: https://documentation.onesignal.com/reference/cancel-message

DELETE /notifications/{message_id}?app_id={app_id}
Stop a scheduled or currently outgoing message.

## Overview

The Cancel message API can be used to stop scheduled messages from being sent. It does not delete or remove the message from the app. If a message is in the process of sending, then canceling it may not fully prevent all targeted users from receiving it.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users, scheduling the message in the future with `send_after`. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and use this API to cancel sending the message to the user if not needed anymore.

If you need a way to remove a notification already sent to a user, see [Remove notifications & TTL](/docs/en/push).

***


# Create or update alias
Source: https://documentation.onesignal.com/reference/create-alias

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Create or update one or more user aliases when you already know an existing alias. This API performs an upsert on the user’s identity object—either adding new aliases or updating existing ones.

## Overview

Use this API to manage user aliases by providing one known alias (such as `external_id`, `onesignal_id`, or a custom alias) and specifying additional aliases to add or update.

This endpoint focuses solely on the `identity` object. If you need to fully create a user with subscriptions and properties, use the [Create user](/reference/create-user) API instead.

<Note>
  * If an alias with the same `alias_label` already exists for the user, it will be updated. If it doesn’t exist, a new alias will be created.
  * Want to use a subscription instead of an alias to identify the user? Use [Create alias (by subscription)](/reference/create-alias-by-subscription).
</Note>

See also:

* [Users](/docs/en/users) – for details on OneSignal ID and External ID
* [Aliases](/docs/en/aliases) – for setting and managing custom aliases
* [Delete alias](/reference/delete-alias) – for removing aliases

***

## How to use this API

To identify the user:

* Use `alias_label` for the type of alias you know (e.g., `external_id`, `onesignal_id`, or a custom alias)
* Use `alias_id` for the value of that alias

<Note>
  We strongly recommend setting the `external_id` as your primary user identifier. This can be done through our frontend SDK's login method when a user signs in to your app or website. It helps OneSignal associate the user's push, email, and SMS subscriptions to a unified user identity.
</Note>

Changes to the identity object take effect immediately upon request.

Alias keys (`alias_label`) and values (`alias_id`) are each limited to **128 characters**. A user can have up to **10 custom aliases** total.

***


# Create alias (by subscription)
Source: https://documentation.onesignal.com/reference/create-alias-by-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Create or update an alias for a user using a known subscription ID.

Create or update an alias for a user using a known subscription ID.

# Overview

Use this API to add or update aliases associated with a user when you only know at least one subscription ID. This API is handy for scenarios where the user's identity is unknown, but a subscription is available.

To remove an alias, see [Delete alias](/reference/delete-alias) API.

***

# How to use this API

You must know the `subscription_id` of the subscription that belongs to the user in which you want to update. Subscription IDs are UUIDs generated by OneSignal and cannot change. See [Subscriptions](/docs/en/subscriptions) for details.

This endpoint performs an upsert—if the user already has an alias with the specified alias label, it gets updated; otherwise, a new alias will be created.

The request body must include an identity object containing one or more aliases to be created or updated.

The OneSignal ID is read-only and used only for fetching. See [Users](/docs/en/users) for details.

Aliases are updated immediately upon request.

***


# Create custom events
Source: https://documentation.onesignal.com/reference/create-custom-events

POST /apps/{app_id}/custom_events
The Custom Events API allows you to record user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones.

## Overview

The Custom Events API allows you to track user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones. See [Custom events](/docs/en/custom-events) for more information.

### Use Cases

Custom events can be used to:

* Enter users into [Journeys](/docs/en/journeys-settings)
* Trigger Journey [Wait Until](/docs/en/journeys-actions) nodes

### Error handling

If individual events can't be processed, an `errors` key will be returned in the response (with HTTP status 202) containing information about each failing event. The most common event-specific error is a failure to find a user associated with the External ID or OneSignal ID in the event.

If you'd like to retry sending events in the case of a failure, you only need to re-send the events for which errors were returned -- events that don't have an error associated with them are still processed. However, if a 5xx HTTP response is returned, you must retry the entire batch of events.

In either case, if you are implementing retry, make sure to also pass an [`idempotency_key`](/reference/idempotent-notification-requests).

### Duplicate events

If you implement retry behavior for your custom event delivery, please provide the [`idempotency_key`](/reference/idempotent-notification-requests) field. Each unique event should get its own unique UUID, and when retrying delivery for events, the same UUID must be provided. Duplicate events with the same `idempotency_key` will be ignored on a best-effort basis within a 4-hour period. This allows you to avoid erroneously triggering Journeys multiple times or incurring charges for storing unnecessary duplicate events.

***


# Sending messages with the OneSignal API
Source: https://documentation.onesignal.com/reference/create-message

Send push notifications, emails, SMS, and Live Activities with the OneSignal API. Covers audience targeting, message composition, scheduling, and response handling.

## Overview

This guide walks you through sending messages with the OneSignal API — from choosing a target audience to composing content, scheduling delivery, and validating responses. Each section covers channel-specific options and performance guidance.

### Prerequisites

1. Complete [Channel Setup](/docs/en/channel-setup) for the channels you plan to use: push, email, SMS, Live Activities.
2. Start accumulating [Subscriptions](/docs/en/subscriptions) for your users.
3. Have your REST API Key and App ID ready. See [Keys and IDs](/docs/en/keys-and-ids).

***

## Choose your target audience

You can target users with **one of the following methods per request**:

* **Aliases**: Specific users via unique IDs, emails, or phone numbers.
* **Segments**: Groups based on predefined behaviors or attributes.
* **Filters**: Custom rules using tags, location, activity, and more.

<Warning>
  Only one targeting method is allowed per message. For example, you cannot mix aliases and filters.
</Warning>

You can also target specific platforms (for example, `isAndroid`, `isIos`, `isAnyWeb`) when sending push notifications. By default, all push platforms are enabled.

### Aliases, emails, phone numbers

Target specific users or lists of users (up to 20,000 entries per request). This method is best for [Transactional Messages](/docs/en/transactional-messages).

<Accordion title="Aliases, emails, and phone numbers targeting parameters">
  <ParamField type="object">
    Target up to 20,000 users by their `external_id`, `onesignal_id`, or a custom alias. Combine with `target_channel` to select the delivery channel.

    ```json theme={null}
    {
      "include_aliases": {
        "external_id": [
          "user1",
          "user2",
          "user3"
        ]
      },
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="string">
    The targeted delivery channel. Required when using `include_aliases` or `included_segments` and sending SMS/RCS. Accepts `"push"`, `"email"`, or `"sms"`. The `"sms"` value covers both SMS and RCS — RCS messages are delivered through the SMS channel.

    ```json theme={null}
    {
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="array">
    Target users' specific [Subscriptions](/docs/en/subscriptions) by ID. Max 20,000 `subscription_id` per request.

    ```json theme={null}
    {
      "include_subscription_ids": [
        "1dd608f2-c6a1-11e3-851d-000c2940e62c"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send to specific email addresses (max 20,000 per request). Can only be used when sending [email](/reference/email). If the email address does not exist within the OneSignal App, a new email subscription is created.

    ```json theme={null}
    {
      "email_to": [
        "user1@example.com",
        "user2@example.com"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send SMS/MMS/RCS to phone numbers in [E.164 format](/docs/en/sms-setup#what-is-e164-format) (max 20,000 per request). Can only be used when sending [SMS/MMS/RCS](/reference/sms). If the phone number does not exist within the OneSignal App, a new SMS subscription is created.

    ```json theme={null}
    {
      "include_phone_numbers": [
        "+19999999999"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Segments

Target users in existing [segments](/docs/en/segmentation). Users in multiple segments only receive the message once.

<Accordion title="Segments targeting parameters">
  <ParamField type="array">
    Target predefined [segments](/docs/en/segmentation). Users who are in multiple segments only receive the message once. Combine with `excluded_segments` to exclude users from specific segments. When sending SMS/RCS, set `target_channel` to `"sms"` (or use the legacy `isSms=true` field).

    ```json theme={null}
    {
      "included_segments": [
        "Active Users",
        "Inactive Users"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Exclude users in these [segments](/docs/en/segmentation) even if they're in `included_segments`.

    ```json theme={null}
    {
      "included_segments": [
        "Subscribed Users"
      ],
      "excluded_segments": [
        "Inactive Users"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Filters

Build real-time audiences with `AND`/`OR` logic without creating segments first.

You can include up to **200 total entries per request**. This includes filter rows (for example, each `field`) and logical operators like `{"operator": "OR"}`.

<Accordion title="Filters targeting parameter details">
  <Info>
    **Performance guidance:**

    * **Fast:** Tag filters using `"="` or `"exists"`, and filters on `last_session`, `session_count`, or `country`.
    * **Slower:** Negation filters (`"!="`, `"not_exists"`) — especially with users who have many tags. Contact support to request indexing optimizations.
    * **Slow by default:** Numeric comparisons (`">"`, `"<"`) on tags or custom properties. Indexing may be available on request.
    * **Mixed performance:** Combining tag filters with other fields may increase computation time.
  </Info>

  <ParamField type="string">
    * Implicit `AND` logic between filters. Use `"operator": "OR"` to start a new branch.
    * `OR` filters are mutually exclusive. Recipients only need to satisfy one condition.
    * Allowed values: `"AND"`, `"OR"`.

    <CodeGroup>
      ```json AND example theme={null}
      // Users must satisfy both filters to be included.
      // Notice the AND operator is not required

      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      // The same example using the AND operator. This is not required.
      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "AND"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      ```

      ```json OR example theme={null}
      // Users can satisfy either filter to be included.

      "filters": [
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "tag", "key": "level", "relation": "=", "value": "20"}
      ]
      ```

      ```json Combinations theme={null}
      // In this example, users must either have:
      // The specified session_count AND tag requirement
      // Or it will be all records where last_session is satisfied
      {
        "name": "2 filters or 1",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"}
        ]
      }

      // Similar to the first example, this shows how to require a specific field
      // across other filters

      {
        "name": "3 filters, 1 required across all",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
        ]
      }

      // Example of 3 user groups with 2 requirements
      // (group_1 OR group_2 OR group_3) AND (requirement_1 OR requirement_2)

      {
        "name": "3 groups with 2 requirements",
        "filters": [
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"}
        ]
      }
      ```
    </CodeGroup>
  </ParamField>

  <ParamField type="object">
    ### `tag`

    Target based on custom user [Tags](/docs/en/add-user-data-tags).

    <Warning>
      Do not use tags for targeting individual users like a "user id".
      Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
    </Warning>

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
      * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
    * `key` = Tag key to compare.
    * `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

    ```json theme={null}
    "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "OR"},
      {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
    ]
    ```

    ### `country`

    Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "country", "relation": "=", "value": "US"},
        {"operator": "OR"},
        {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
      ]
      ```

    ### `last_session`

    Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "last_session", "relation": ">","hours_ago": "10"}
      ]
      ```

    ### `first_session`

    Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "first_session", "relation": "<","hours_ago": "24"}
      ]
      ```

    ### `session_count`

    Total number of sessions by the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="` or `"!="`
    * `value` = number of sessions. Example: `"1"`

      ```json theme={null}
      "filters": [
        {"field": "session_count", "relation": ">","value": "5"}
      ]
      ```

    ### `session_time`

    Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

    * `relation` = `">"` or `"<"`
    * `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

      ```json theme={null}
      "filters": [
        {"field": "session_time", "relation": ">","value": "86400"}
      ]
      ```

    ### `language`

    [User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = 2 character language code. Example: `"en"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "language", "relation": "=","value": "en"},
        {"operator": "OR"},
        {"field": "language", "relation": "in_array","value": "es,fr,de"}
      ]
      ```

    ### `app_version`

    App version set on the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = app version. Example: `"1.0.0"`
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "app_version", "relation": "=","value": "1.0.1"},
        {"operator": "OR"},
        {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
      ]
      ```

    ### `location`

    Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

    * `radius` = in meters
    * `lat` = latitude
    * `long` = longitude

      ```json theme={null}
      "filters": [
        {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
      ]
      ```
  </ParamField>
</Accordion>

***

## Craft your message

Each channel has its own set of fields. At a minimum, you need the following to send a displayable message:

* **Push and SMS** use `contents`
* **Email** uses `email_subject` and `email_body`
* Or reuse `template_id` if you created [templates](/docs/en/templates).

<CodeGroup>
  ```json Push and SMS theme={null}
  // Message request body
  {
    "contents": {
      "en": "Hello, world",
      "es": "Hola Mundo",
      "fr": "Bonjour le monde",
      "zh-Hans": "你好世界"
    }
  }
  ```

  ```json Email theme={null}
  // Message request body
  {
    "email_subject": "Hello, world",
    "email_body": "<html><body><h1>Hello, world</h1></body></html>"
  }
  ```
</CodeGroup>

For advanced customization—like adding images, buttons, sounds, or tracking—see the channel-specific options below.

### Push notification options

Below are the most common parameters for push notifications. For the full list of options, see the [Push notification reference](/reference/push-notification).

<Accordion title="Push notification options">
  #### Content and text

  * [`contents`](/reference/push-notification#body-contents) – Main message body.
  * [`headings`](/reference/push-notification#body-headings) – Title of the notification.
  * [`subtitle`](/reference/push-notification#body-subtitle) – Secondary line of text.
  * [`template_id`](/reference/push-notification#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Appearance

  * [`ios_attachments`](/reference/push-notification#body-ios-attachments) – Images/video/media.
  * [`big_picture`](/reference/push-notification#body-big-picture) – Large image (Android).
  * [`chrome_web_image`](/reference/push-notification#body-chrome-web-image) – Large image (Chrome).
  * [`small_icon`](/reference/push-notification#body-small-icon)
  * [`large_icon`](/reference/push-notification#body-large-icon)
  * [`buttons`](/reference/push-notification#body-buttons) – Action buttons.

  #### Delivery and priority

  * [`android_channel_id`](/reference/push-notification#body-android-channel-id)
  * [`priority`](/reference/push-notification#body-priority) – Delivery urgency.
  * [`ios_interruption_level`](/reference/push-notification#body-ios-interruption-level)
  * [`collapse_id`](/reference/push-notification#body-collapse-id) – Replaces older messages.

  #### Data and extras

  * [`data`](/reference/push-notification#body-data) – Custom key-value pairs sent to your app.
  * [`url`](/reference/push-notification#body-url) – Opens when notification is tapped.
</Accordion>

### Email options

<Accordion title="Email options">
  #### Content

  * [`email_subject`](/reference/email#body-email-subject)
  * [`email_body`](/reference/email#body-email-body)
  * [`email_preheader`](/reference/email#body-email-preheader)

  #### Appearance

  * [`template_id`](/reference/email#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Sender info

  * [`email_from_name`](/reference/email#body-email-from-name)
  * [`email_reply_to`](/reference/email#body-email-reply-to)
</Accordion>

### SMS/MMS options

<Accordion title="SMS/MMS options">
  #### Content

  * [`contents`](/reference/sms#body-contents)
  * [`template_id`](/reference/sms#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Media (MMS only)

  * [`sms_media_urls`](/reference/sms#body-sms-media-urls)

  #### Sender info

  * [`sms_from`](/reference/sms#body-sms-from)
</Accordion>

***

## Schedule and per-user delivery

By default, messages are sent immediately. You can schedule delivery in advance and optimize timing per user based on their local timezone or recent activity.

<Accordion title="Schedule delivery and per-user optimization parameters">
  <ParamField type="string">
    Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript's Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring).

    ```json theme={null}
    {
      "send_after": "2025-09-24T14:00:00-07:00"
    }
    ```
  </ParamField>

  <ParamField type="string">
    Controls how push and email messages are delivered on a per-user basis. Not available for SMS.

    * `"timezone"`: Sends at the same local time across time zones.
    * `"last-active"`: Delivers based on each user's most recent session.

    Not compatible with [push throttling](/docs/en/throttling). When `delayed_option` is set, you must also set `throttle_rate_per_minute` to `0`.

    ```json theme={null}
    {
      "delayed_option": "last-active",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>

  <ParamField type="string">
    Use with `delayed_option: "timezone"` to set a consistent daily delivery time. Accepted formats:

    * `"9:00AM"` (12-hour)
    * `"21:45"` (24-hour)
    * `"09:45:30"` (HH:mm:ss)

    Example — Send every day at 9 AM in each user's local time:

    ```json theme={null}
    {
      "delayed_option": "timezone",
      "delivery_time_of_day": "9:00AM",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>
</Accordion>

***

## Submit the request

This final example sends a localized push notification to all subscribed users:

```curl theme={null}
curl -X "POST" "https://api.onesignal.com/notifications" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Key YOUR_API_KEY' \
     -d $'{
      "target_channel": "push",
      "included_segments": [
        "Subscribed Users"
      ],
      "app_id": "YOUR_APP_ID",
      "contents": {
        "en": "Hello, world",
        "es": "Hola mundo",
        "fr": "Bonjour le monde",
        "zh-Hans": "你好世界"
      }
    }'
```

Once the request is sent, OneSignal forwards it to the appropriate downstream provider, which then delivers it to the recipient:

* **Push:** FCM, APNs, or HMS
* **Email:** your email service provider
* **SMS:** Twilio

### Handle the response

You receive a `200` response code if the request is valid and accepted.

* If an `id` is returned, the message was created successfully. Save this `id` for future tracking and reference of message stats via the [View message API](/reference/view-message).
* If no `id` is returned, the message was not created, likely because there are no valid [subscriptions](/docs/en/subscriptions) in the target audience.

**Response details by channel:**

* [Push](/reference/push-notification#response-id)
* [Email](/reference/email#response-id)
* [SMS](/reference/sms#response-id)

<Note>
  See our [REST API Overview](/reference/rest-api-overview#reliability-and-delivery) page for details on retries and [rate limits](/reference/rate-limits).
</Note>

***

## FAQ

### Can I combine `include_aliases`, `included_segments`, and `filters` in one request?

No. Each request must use exactly one targeting method. Mixing them returns a validation error. Choose aliases for transactional sends to specific users, segments for predefined audiences, or filters for ad-hoc audiences built with `AND`/`OR` logic.

### Does `target_channel: "sms"` cover RCS?

Yes. The `target_channel` enum accepts `"push"`, `"email"`, and `"sms"`. RCS messages are delivered through the SMS channel — there is no separate `"rcs"` value. OneSignal decides whether to send via RCS or SMS based on the recipient's device and your sender configuration.

### My request returned `200` but no `id`. What happened?

The request was valid but no message was created, typically because the target audience contains no valid subscriptions for the selected channel. Common causes include a segment that resolves to zero users, all targeted aliases being unsubscribed, or phone numbers that don't match an existing SMS subscription.

### Can I use `//` comments in the JSON request body?

No. The `//` comments in the examples on this page are illustrative only. Strict JSON does not support comments — strip them before sending to the API.

### How is the `Sent` count in reports related to the API response?

The dashboard `Sent` metric is a composite. To derive it from the [View message API](/reference/view-message), sum `successful + failed + errored`. See the [Metrics glossary](/docs/en/analytics-metrics-glossary) for the full mapping between dashboard, API, CSV, and Event Streams names.

***

## Next steps

Refer to the channel-specific APIs to customize delivery further:

* [Push notification](/reference/push-notification)
* [Email](/reference/email)
* [SMS](/reference/sms)
* [Live Activities](/reference/start-live-activity)
* [Server-Side SDKs](/docs/en/server-sdk-reference)


# Create Subscription by alias
Source: https://documentation.onesignal.com/reference/create-subscription

POST /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions
Use this API to attach a new subscription—such as email, SMS, or push notification—to an existing OneSignal user identified by an alias.

## Overview

This API allows you to add a **new Subscription** to an existing [User](/docs/en/users) via an alias identifier. A *Subscription* reflects a user's intent to receive messages through a specific communication channel, such as email, SMS, or push notifications. See [Subscriptions](/docs/en/subscriptions) for additional context.

If you're looking to **create a new user and add Subscriptions simultaneously**, use the [Create User](/reference/create-user) API instead.

***

## How to use this API

To attach a Subscription, the user must already exist and be referenced using an alias. The `alias_label` and `alias_id` path parameters define how the user is identified:

* Common alias: `external_id`
* Other options: `onesignal_id`, or custom aliases

For details, refer to [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

## Required Fields

Each Subscription must include at least:

* `type`: the channel (e.g., `Email`, `SMS`, `iOSPush`)
* `token`: the unique identifier for the channel (e.g., email address, phone number, push token)

If the specified `type` and `token` already exist in the app, the Subscription will be transferred to the user identified in the path parameters.

***


# Create template
Source: https://documentation.onesignal.com/reference/create-template

POST /templates
Create reusable message templates for push, email, and SMS channels. Templates can be accessed through both the dashboard and API using a `template_id`.

## Overview

Use this endpoint to create a new message template in your OneSignal app. Once created, the template becomes available for use when sending messages via both the Dashboard and the REST API by referencing the `template_id`.

Templates streamline and standardize message content across push, email, and SMS channels.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Before using this endpoint, ensure that the target channel (push, email, or SMS) is properly configured in your OneSignal app. See [Channel Setup](/docs/en/channel-setup) for guidance.

### Push Templates

**Requirements:**

* Set the `contents` property with the English (`en`) language key.
* All [Push Channel Properties](/reference/push-notification) are valid for use in push templates.
* By default, all push platforms are enabled. You can target specific platforms by explicitly setting them (e.g., `isAndroid: true` disables others).

### Email Templates

**Requirements:**

* Set `isEmail: true`.
* Include both `email_subject` and `email_body`.
* All [Email Channel Properties](/reference/email) are valid for use in email templates.

### SMS Templates

**Requirements:**

* Set `isSMS: true`.
* Provide SMS-specific parameters like `contents`.
* All [SMS Channel Properties](/reference/sms) are valid for use in SMS templates.

***


# Create user
Source: https://documentation.onesignal.com/reference/create-user

POST /apps/{app_id}/users
Create a new user or modify the subscriptions associated with an existing User.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint enables you to create and manage users outside of frontendSDK-based sessions. It's primarily used to:

* Import users from other systems.
* Programmatically define users by assigning identifiers (aliases), properties (e.g., tags), and messaging subscriptions (e.g., email, mobile, SMS).

If you're using the frontend SDKs, user creation is typically handled automatically via methods like `login`, `addEmail`, and `addSms`. See [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) for conceptual guidance.

***

## How to use this API

To successfully create a user via the API:

* You must provide at least one unique identifier via the `identity` and Subscription via the `subscriptions` fields.
* You can optionally include user profile data (`properties`) and one or more messaging `subscriptions`.

## Key Concepts

### Aliases

Aliases uniquely identify a user and should include an `external_id` (the recommended identifier). They allow you to reference users across platforms or external systems. Up to 10 custom aliases are supported. Each alias key and value has a maximum length of 128 characters.

### Properties

User properties store information such as tags, location, activity, and device data. These attributes help you personalize campaigns and optimize engagement strategies.

### Subscriptions

A user can have up to **20 subscriptions** (across email, SMS, push, etc.). Subscriptions connect users to channels for message delivery and are transferable across users. See [Subscriptions](/docs/en/subscriptions) for more.

***


# Remove alias
Source: https://documentation.onesignal.com/reference/delete-alias

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}
Remove a specific alias from a user.

## Overview

Use this API to remove a specific alias from a user’s identity object without deleting the user. This operation only affects user identity labels—subscriptions and the core user record remain intact. To delete a user entirely, including all associated aliases and subscriptions, see the [Delete user](/reference/delete-user) API.

***

## How to use this API

To remove an alias from a user:

1. Identify the user via a known alias by specifying:

   * `alias_label` – the type of alias (e.g., email, external\_id)
   * `alias_id` – the unique identifier for that alias

2. Specify the alias to remove using:

   * `alias_label_to_delete` – the label of the alias to be deleted

   The `alias_label_to_delete` can be the same as the `alias_label` used to identify the user.

3. This action is performed synchronously—the alias is deleted immediately after the request is processed.

<Warning>
  The `onesignal_id` alias cannot be deleted. Only secondary aliases (like email, external\_id, etc.) are removable.
</Warning>

For a full explanation of identity management, see [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

***

## FAQ

### Can I delete the same alias that I used to look up the user?

Yes. This is a common scenario—especially if an alias was set incorrectly and needs to be removed. Just be sure to include that alias both as the identifier and as alias\_label\_to\_delete.

If you want to delete the entire user and all associated data, use the [Delete user](/reference/delete-user) API.

### What happens if I delete all aliases associated with the user?

A user will always retain at least one alias, the onesignal\_id. Even if you remove all other aliases, the user and their subscriptions remain linked to the onesignal\_id.

***


# Delete Subscription
Source: https://documentation.onesignal.com/reference/delete-subscription

DELETE /apps/{app_id}/subscriptions/{subscription_id}
Delete a specific subscription by its subscription_id. This stops messages from being sent to that subscription but does not prevent future subscriptions with the same token.

## Overview

Use this API to delete an existing Subscription and its associated properties. Deletion is **asynchronous**, and while the Subscription is being removed, messages will no longer be sent to it.

<Warning>
  This operation only deletes a **single Subscription**. To remove a **user and all their Subscriptions**, use the [Delete User](/reference/delete-user) API instead.
</Warning>

### What Happens When You Delete

* Messages will stop being sent to the deleted subscription.
* **Deleting a Subscription does not block new Subscriptions** with the same `token`.
  * If the app is reopened or a token is re-submitted (e.g., same email or phone), a **new Subscription** may be automatically created.
  * This ensures users can re-subscribe if needed without requiring manual intervention.

***

## How to Use This API

**Required:** `subscription_id`

You must provide the `subscription_id` of the subscription to be deleted. This ID is a UUID generated by OneSignal and is immutable.

To find the `subscription_id`:

1. Use the [View User](/reference/view-user) API.
2. Look at the `subscriptions` array in the response.
3. Identify the correct subscription by its `type`, `token`, or other metadata.
4. Use the corresponding `id` field as the `subscription_id`.

***


# Delete template
Source: https://documentation.onesignal.com/reference/delete-template

DELETE /templates/{template_id}?app_id={app_id}
Permanently delete a specific message template from your OneSignal app using its template ID. Templates used in Journeys must be removed from those Journeys before deletion.

## Overview

This endpoint allows you to delete a single template associated with your OneSignal app. Deletion is **immediate and irreversible**.

<Warning>
  If the template is currently used in a Journey, it cannot be deleted until that Journey has been deleted.
</Warning>

***

## How to use this API

Required Parameters

* `template_id` (path param): The OneSignal-generated UUID of the template to delete.
* `app_id` (query param): Your OneSignal App ID.

### Where to Find `template_id`

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# Delete user
Source: https://documentation.onesignal.com/reference/delete-user

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}
Delete a user including all associated properties, subscriptions, and identity.

## Overview

Use this API to permanently delete a user from your OneSignal project, including all associated subscriptions, properties, and aliases. The operation is asynchronous—user data will be deleted shortly after the request is accepted.

***

## How to use this API

To delete a user, you must be able to identify them using one of the following alias types:

* `external_id` (recommended and most common)
* `onesignal_id`
* A custom Alias that you have set

Pass the appropriate `alias_label` and corresponding `alias_id` in the request path.

<Warning>
  This operation deletes all data associated with the user, including:

  * All identity aliases
  * All channel subscriptions (push, email, SMS, etc.)
  * All custom user properties
</Warning>

## Because this is an irreversible operation, be sure that you really intend to delete the user and all their data.


# Email
Source: https://documentation.onesignal.com/reference/email

POST /notifications?c=email
Send a message using the email channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for email. See [Push notification](/reference/push-notification) or [SMS](/reference/sms) to send to those channels.

Ensure your [Email setup](/docs/en/email-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# View user identity
Source: https://documentation.onesignal.com/reference/fetch-aliases

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Retrieve all aliases associated with a user using a known alias, such as an `external_id`, `onesignal_id`, or a custom alias. This API helps you map back to a user’s full identity from any one piece of identifying information.

## Overview

Use this API when you want to retrieve the complete identity object for a user, which includes all aliases tied to that user. It is ideal for cases where you know one alias and want to discover others—especially helpful for user mapping, debugging, or linking systems.

This endpoint is similar to the [View user](/reference/view-user) API but only returns the `identity` object—not subscriptions or properties.

<Tip>
  If you only know a subscription\_id, use View user identity (by subscription) instead.
</Tip>

For more context on user identity and aliasing:

* [Users](/docs/en/users)
* [Aliases](/docs/en/aliases)

***

## How to use this API

To identify the user, use:

* `alias_label` – the type of alias you’re using to find the user (e.g. `external_id`, `onesignal_id`, or a custom alias)
* `alias_id` – the actual value of that alias

Common usage patterns:

Using `external_id` (recommended):

* `alias_label`: `external_id`
* `alias_id`: your user ID (e.g., user-123)

Using `onesignal_id`:

* `alias_label`: `onesignal_id`
* `alias_id`: the OneSignal-assigned unique ID

Using a custom alias:

* Define your own alias label (e.g. `shopify_customer_id`) and its value

<Note>
  We strongly recommend setting and using the `external_id` as your primary user identifier for portability and simplicity across your systems.
</Note>

***


# View user identity (by subscription)
Source: https://documentation.onesignal.com/reference/fetch-identity-by-subscription

GET /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Retrieve all aliases linked to a user using a known `subscription_id`. This is useful when the user’s identity is unknown but you have access to one of their push, email, or SMS subscriptions.

## Overview

Use this API when you want to find the full identity (all aliases) of a user, starting from a known `subscription_id`. This is helpful for debugging, reverse lookups, or support use cases where only a subscription record is available.

<Note>
  Unlike the [View user identity](/reference/fetch-aliases) API which starts with an alias (e.g., `external_id`), this endpoint works when only a subscription ID is known.
</Note>

See [Subscriptions](/docs/en/subscriptions) for background on how subscriptions relate to users.

***

## How to use this API

To use this endpoint, you must provide:

* `subscription_id` – A UUID generated by OneSignal when a device or channel (e.g., push, email, SMS) is registered.

<Warning>
  `subscription_id` values are immutable and cannot be changed. Make sure you are using the correct value, as they are unique to each app and platform.
</Warning>

Once a valid `subscription_id` is provided, the API will return the user’s identity object, which includes all associated aliases like `external_id`, `onesignal_id`, and any custom aliases.

***


# Idempotent API requests
Source: https://documentation.onesignal.com/reference/idempotent-notification-requests

Prevent duplicate messages or custom events when retrying API requests.

## Overview

When you create messages or custom events via our REST API, network failures or timeouts can cause uncertainty about whether a request succeeded. **Idempotent requests** solve this problem by ensuring the same request is only processed once—even if it is sent multiple times.

This page explains how idempotency works in OneSignal, when to use it, and common pitfalls to avoid.

### When you should use idempotency

You should use idempotent requests any time you plan to retry API calls, especially when:

* You receive a timeout, 500-level error, or no response.
* Your infrastructure automatically retries failed requests.
* Delivering a duplicate message or custom event would be harmful.
* Missing a message or custom event would be harmful.

### The problem idempotency solves

Consider this common failure scenario:

1. You send a `notifications#create` or `custom_events#create` request.
2. OneSignal begins processing and sending the message or event.
3. A network error occurs before your client receives a response.

At this point, your system cannot know whether the request succeeded.

* If you retry and the request already succeeded, users may receive duplicates.
* If you do not retry and the request failed, users may miss important messages or events.

**Idempotency provides a safe retry mechanism.**

***

## How idempotency works

OneSignal supports idempotent operations for:

* [`notifications#create`](/reference/create-message)
* [`custom_events#create`](/reference/create-custom-events)

You provide a unique `idempotency_key` with each request.

### Request flow with idempotency

1. You send a request with an `idempotency_key`.
2. OneSignal processes the request and begins sending the message or creating the custom event.
3. A network error or timeout occurs.
4. You retry the request using the same `idempotency_key`.
5. OneSignal detects the duplicate and returns the result of the original request.
6. Only one notification or custom event is processed.

You can repeat this retry any number of times. As long as the `idempotency_key` remains the same, the operation will only be processed once.

***

## Idempotency key reference

<ParamField type="RFC 9562 UUID">
  A unique identifier used to prevent duplicate messages or custom events from repeat API calls. Keys must be unique [RFC 9562 UUID format](https://en.wikipedia.org/wiki/Universally_unique_identifier). Valid for 30 days.
</ParamField>

<Note>
  This `idempotency_key` property used to be called `external_id` but caused confusion with our [Users `external_id`](/docs/en/users) alias, so we have added this new property name to reduce confusion. Both will work in this case.
</Note>

***

## Important constraints and gotchas

<Warning> If you reuse the same `idempotency_key` for different messages or events, only the first request will be processed. </Warning>

Keep the following in mind:

* **Keys must be unique per logical operation**
  Generate a new UUID for every notification or custom event you intend to send.

* **Keys are retained for 30 days**
  After 30 days, OneSignal may delete the record. Reusing the same key after that window may result in a new message being sent.

* **Use a strong source of randomness**
  Predictable or reused UUIDs can cause unexpected deduplication.

* **Idempotency does not guarantee delivery**
  It only guarantees at-most-once processing. You should still monitor API responses and logs.

### Legacy behavior

The `idempotency_key` property was previously named `external_id`. This caused confusion with the Users `external_id` alias, so `idempotency_key` is now the recommended field name. Both names are currently supported.

### Best practices

* Always include `idempotency_key` when implementing retries.
* Store the `idempotency_key` alongside your request metadata for debugging.
* Retry only after honoring any `Retry-After` header returned by the API.
* Combine idempotency with proper timeout handling (for example, a 60-second HTTP timeout).

***


# Message history
Source: https://documentation.onesignal.com/reference/message-history

POST /notifications/{message_id}/history
View which subscriptions received a particular message

## Overview

This API enables you to retrieve all [Subscriptions](/docs/en/subscriptions) that received a specific push notification or email. You can access the notification's history for up to seven days after it was sent. Please note that notifications sent to fewer than 1,000 recipients will not record a "received" event, but they will still record "sent" events.

***

## How to Use this API

1. Submit a request to generate a report.

2. Decide delivery method

   * After receiving a successful response, **poll the destination URL** until the file becomes available. Exports typically complete within 1-3 minutes; we recommend a 10-second polling interval.
   * Alternatively, you can opt to receive an email to the address specified in the optional `email` parameter when the report is ready.

### Requirements

* A [OneSignal Professional or Enterprise Plan](https://onesignal.com/pricing).
* Enabled the "Send History via OneSignal API" option in Settings -> Integrations; notifications sent before this setting is enabled can't be retrieved.
* Requests must be made within seven days of sending the notification.

### Polling

Use the `csv_file_url` property in the response to test if the report is complete. If you receive a '403' error response, retry fetching the file after a short period; it only means we're still generating the report.

### Sample Report

The generated report is a simple CSV file that can be imported into any system for further processing.

```csv report.csv theme={null}
player_id,onesignal_id,external_id,target_channel,timestamp
"2c4fac95-7dfb-4113-9347-aba3a92ff557","ccddf35a-1233-4423-8a57-ac8c4b38eb81","a07aec27-2586-4b92-a24f-62660a1517fa","push","1628189160"
"68f5cf73-b20a-4de9-b6ee-79a863b8e7d8","d2f9f2f8-94af-4942-8183-115cef1213d5","4b66359f-3d94-4a73-806d-8ef5f0430b3d","push","1628187816"

```

### Limitations

* Querying for `opens` events are not supported.
* The `timestamp` column is included only for `clicked` events.

***


# Push notification
Source: https://documentation.onesignal.com/reference/push-notification

POST /notifications?c=push
Send a message using the push notification channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for push. See [Email](/reference/email) or [SMS](/reference/sms) to send to those channels.

Ensure your application is properly configured by following the [Mobile SDK Setup](/docs/en/mobile-sdk-setup) and/or [Web SDK Setup](/docs/en/web-sdk-setup) guides. You should see subscribed push [Subscriptions](/docs/en/subscriptions) in your OneSignal dashboard to send them messages.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Rate limits and error handling
Source: https://documentation.onesignal.com/reference/rate-limits

Understand OneSignal API and application rate limits, common errors, retry behavior, and how to safely recover from failures without sending duplicate messages or disabling your app.

OneSignal uses rate limits and error responses as safety mechanisms to protect your app from accidental overloads, duplicate sends, and retry storms.

There are three categories to understand:

* **API rate limits** return HTTP `429` errors when request volume is too high.
* **Network timeouts or temporary server failures** return `5xx` errors or no response at all.
* **Application message limits** may temporarily disable your app if too many messages are sent in a short period.

<Info>
  Most apps never hit these limits during normal usage. When they do occur, they are usually caused by retries, loops, or unexpected audience expansion.
</Info>

<Check>
  **Quick implementation checklist**

  * Expect `429`, `5xx`, and timeouts. They are normal at scale.
  * Never retry message sends without an `idempotency_key`.
  * For non-urgent retries, wait **100 seconds** before retrying.
  * API rate limits (`429`) never disable your app.
  * Only message volume limits can disable your app.
  * `POST /notifications` (create) and `DELETE /notifications` (cancel) count toward the same rate limit.
  * The [Create custom events](/reference/create-custom-events) endpoint has its own rate limit, separate from the notification endpoints.
</Check>

***

## API rate limits

API rate limits apply **per app and per endpoint**. They are evaluated when a request is received, not when a response is returned.

These limits are designed to throttle traffic, not block your app.

| Endpoint                                                                                  | Rate limit                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create message](/reference/create-message) / [Cancel message](/reference/cancel-message) | **Free plans:** 150 requests/sec/app<br />**Paid plans:** 6,000 requests/sec/app<br /><br />The `POST /notifications` and `DELETE /notifications` endpoints share the same limit. Requests count toward it regardless of method. For example, 3,000 creates + 3,000 cancels = 6,000 requests/sec on a paid plan.<br /><br />Each request can target many users or segments. |
| [Create custom events](/reference/create-custom-events)                                   | Rate-limited independently from Create Message.<br />**Request size limits:** 2,024 bytes per event · 1 MB per request body                                                                                                                                                                                                                                                 |
| Create, update, or delete users or subscriptions                                          | 1,000 requests/sec/app<br />1 request/sec per user or subscription<br />Up to 100 property updates per request                                                                                                                                                                                                                                                              |
| View endpoints (messages, templates, users)                                               | 1 request/sec/app<br />Up to 10 look-back requests/sec                                                                                                                                                                                                                                                                                                                      |
| Message History and CSV exports                                                           | Keep parallel exports under 100 GB per file                                                                                                                                                                                                                                                                                                                                 |

<Note>
  High-volume messaging should use fewer message creation requests with larger audiences instead of increasing request frequency.
</Note>

**Handling API rate limit errors (`429`):**

When you exceed an API rate limit, OneSignal returns an HTTP `429` response:

```json theme={null}
{
  "errors": ["API rate limit exceeded."]
}
```

The response includes a `Retry-After` header indicating how many seconds to wait before retrying.

**What to do when you receive a `429` error:**

1. Stop sending requests immediately.
2. Wait for the full duration specified in the `Retry-After` header.
3. Retry using exponential backoff.
4. Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for retries that send messages.

<Warning>
  Retrying before the `Retry-After` delay or retrying in tight loops can extend throttling and increase failure rates.
</Warning>

***

## Error handling and retry strategies

Retries are safe only when implemented correctly. Some failed requests may still be processing on our servers.

* Retriable errors generally include network timeouts, no responses, 429, and 5xx errors.
* Non-retryable errors include 400, 401, or 403 errors which indicate invalid input, authentication problems, or missing permissions. These are not temporary failures.

**Simple retry strategy:**

* Wait **100 seconds** before retrying.
  * This aligns with the maximum API response timeout.
  * If no response or network error occurs, the request may still be processing during this window.
* Retry **up to 3 total attempts** (original + 2 retries).
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

**Time-sensitive (advanced) retry strategy:**

* Retry using exponential backoff with jitter (for example: 2s, 4s, 8s… up to 60s).
* Cap retries to **10 total attempts** and stop after **10–15 minutes**.
* For `429` responses, treat `Retry-After` as a minimum delay: wait `max(Retry-After, backoff)`.
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

<Warning>
  Retrying message or custom event API requests without idempotency can result in duplicate messages or custom events.
</Warning>

<Accordion title="Example retry logic">
  ```text theme={null}
  attempt = 1
  max_attempts = 3

  send request with idempotency_key

  if response is success:
    stop

  if response is 429:
    wait Retry-After seconds
  elif response is 5xx or timeout:
    wait 100 seconds

  if attempt < max_attempts:
    retry with same idempotency_key
  else:
    fail safely
  ```
</Accordion>

### Retry decision guide

| Error type              | Retry? | When                 | Idempotency required |
| ----------------------- | ------ | -------------------- | -------------------- |
| `429 Too Many Requests` | Yes    | After `Retry-After`  | Yes                  |
| `5xx Server Error`      | Yes    | Backoff or 100s      | Yes                  |
| Timeout / no response   | Yes    | Immediate or delayed | Yes                  |
| `400 Bad Request`       | No     | Fix request          | No                   |
| `401 / 403`             | No     | Fix auth/permissions | No                   |

<Warning>
  Common implementation mistakes:

  * Retrying with a new idempotency key on each attempt.
  * Retrying indefinitely without a retry cap.
  * Retrying `400` or `401` errors without fixing the request.
  * Sending one request per user instead of batching audiences.
</Warning>

***

## Application message limits (app disablement)

Application message limits protect your users from receiving too many notifications in a short period of time.

**How the limit works:**

In any rolling 15-minute window, you may send up to **10 × your total number of subscribed [Subscriptions](/docs/en/subscriptions)**.

This limit is based on the total number of messages delivered, not the number of API requests.

* Sending 1 notification to 1,000 Subscriptions = 1,000 messages
* Sending 10 notifications to 1,000 Subscriptions each = 10,000 messages

The 15-minute window is rolling, not fixed.

* Messages are counted for 15 minutes after they are sent
* As time passes, older messages automatically stop counting
* You only exceed the limit if more than 10× your subscribed Subscriptions receive messages within the same 15-minute span

Example limits:

* App with 1,000 subscribed Subscriptions → up to 10,000 messages in any 15 minutes
* App with 10,000 subscribed Subscriptions → up to 100,000 messages in any 15 minutes

**Example scenarios:** App with 1,000 subscribed Subscriptions (limit: 10,000 messages per 15 minutes)

| Scenario                                                                              | Messages counted in any 15-minute period |    App disabled?    |
| ------------------------------------------------------------------------------------- | ---------------------------------------: | :-----------------: |
| At **12:00**, send 1 notification to 1,000 users                                      |                                    1,000 |          No         |
| At **12:00**, send 10 notifications to 1,000 users                                    |                                   10,000 |   Yes (hits limit)  |
| Between **12:00–12:14**, send 10,000 notifications to 1 user                          |                                   10,000 |   Yes (hits limit)  |
| Send **9,000 messages at 12:00**, then **9,000 more at 12:16**                        |                                    9,000 |          No         |
| Send **9,000 messages spread between 12:00–12:14**, then send **9,000 more at 12:15** |                                 \~18,000 | Yes (exceeds limit) |

<Note> This limit is evaluated continuously over a rolling 15-minute window, not in fixed time blocks. If any 15-minute span exceeds your limit, the app is disabled. </Note>

**What happens if the limit is exceeded:**

If your app sends more messages than allowed within a 15-minute window:

* Your app is temporarily disabled
* All app administrators receive an email notification
* A re-enable banner appears in the OneSignal Dashboard

<Warning> Only application message limits can disable your app. API rate limits (`429` errors) never disable apps. </Warning>

**What to do if your app is disabled:**

If your app is disabled, follow these steps in order:

1. Pause message sending from your backend, jobs, or automations.
2. Identify the cause, such as infinite loops, retry storms, or unexpected segment growth.
3. Log in to the OneSignal Dashboard.
4. Click **Re-enable** in the red banner at the top of the app.
5. If you need help re-enabling your app, contact `support@onesignal.com`.

***

## FAQ

### Do API rate limits disable my app?

No. API rate limits (`429` errors) only throttle your requests temporarily. Only [application message limits](#application-message-limits-app-disablement) — which track the total volume of messages delivered — can disable your app.

### What is an idempotency key and when do I need one?

An idempotency key is a unique identifier you include with a request so that retrying the same request does not create a duplicate message or event. You need one whenever you retry a `POST /notifications` or custom event request. Reuse the same key for every retry attempt. See [Idempotent API requests](/reference/idempotent-notification-requests).

### Can I increase my API rate limit?

Paid plans have higher rate limits (6,000 requests/sec vs. 150 for free plans). If you need limits beyond the paid tier, contact `support@onesignal.com` with your use case and expected volume.

### Why was my app disabled even though I didn't hit the API rate limit?

API rate limits and application message limits are separate. Your app can be disabled if the total number of messages delivered in any 15-minute window exceeds 10× your subscription count — even if every individual API request succeeded. Common causes include retry storms, runaway automations, or targeting a larger audience than intended.

***

## Related pages

<Columns>
  <Card title="Idempotent API requests" icon="rotate" href="/reference/idempotent-notification-requests">
    Prevent duplicate messages by reusing idempotency keys on retries.
  </Card>

  <Card title="Create message API" icon="paper-plane" href="/reference/create-message">
    API reference for sending push, email, SMS, and in-app messages.
  </Card>

  <Card title="Create custom event API" icon="bolt" href="/reference/create-custom-events">
    API reference for sending custom events that trigger Journeys.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="/docs/en/subscriptions">
    Understand how subscriptions are counted toward message limits.
  </Card>
</Columns>


# REST API overview
Source: https://documentation.onesignal.com/reference/rest-api-overview

Programmatic access to OneSignal messaging, user management, segments, and data exports over HTTPS with rate limiting and retry support.

The OneSignal REST API follows the [REST architecture](https://en.wikipedia.org/wiki/Representational_state_transfer) and provides programmatic access to core messaging and user features. Use the API to send push notifications, emails, and SMS, manage Users, Subscriptions, Segments, export data, and configure apps.

## Which API to use

| Goal                          | API                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| Send a push, email, or SMS    | [Create Message](/reference/create-message)                                                              |
| Add or update user data       | [Create User](/reference/create-user) / [Update User](/reference/update-user)                            |
| Target a group of users       | [Create Segments](/reference/create-segments) or use [Filters](/reference/create-message#filters) inline |
| Export analytics or user data | [CSV Export](/reference/csv-export) / [CSV of Events](/reference/export-csv-of-events)                   |
| Manage app configuration      | [Create App](/reference/create-an-app) / [Update App](/reference/update-an-app)                          |

***

## Requirements

**General**

* **HTTPS required**: All API requests must use HTTPS with **TLS 1.2 or higher** on port `443`.
* **Network access**: Firewalls or proxies must allow **outbound traffic** to `https://api.onesignal.com` on port `443`.
* **DNS TTL**: Clients must respect OneSignal’s DNS **TTL of 300 seconds** to avoid stale IP resolution.

**Incoming Traffic to OneSignal (API & SDK Requests)**

All incoming API traffic—whether from your backend, the OneSignal SDKs, or the dashboard—passes through **Cloudflare**, which serves as the global edge network.

* You may see Cloudflare IP addresses in logs.
* Cloudflare IPs may change over time.
* If you maintain a strict firewall, use Cloudflare’s official [IP ranges](https://www.cloudflare.com/ips/)

<Warning>
  Avoid allowlisting specific Cloudflare IPs, as they may change without notice.
</Warning>

**Outgoing Traffic from OneSignal (Webhooks & Event Streams)**

For features where OneSignal sends HTTP requests to your servers (such as webhooks or event streams), traffic originates from OneSignal infrastructure running on Google Cloud Platform (GCP) in the `europe-west4` region (Groningen, Netherlands).

* Allow inbound traffic from `https://api.onesignal.com`, **or**
* Use GCP’s maintained IP range list and filter by `europe-west4` region: [GCP IP ranges](https://www.gstatic.com/ipranges/cloud.json)

<Note>
  OneSignal supports [IP allowlisting](/docs/en/keys-and-ids) with REST API keys.
</Note>

***

### Platform-specific network requirements

#### FCM (Google Android and Chrome push)

* Required ports: `5228`, `443`, `5229`, and `5230`
* No IP allowlisting needed
* More info: [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

#### APNs (Apple iOS, iPadOS, Safari push)

* Required ports: `5223`, `443`, and `2197`
* Recommended servers:
  * Sandbox: `api.sandbox.push.apple.com:443`
  * Production: `api.push.apple.com:443`
  * IP range: `17.0.0.0/8`
* More info:
  * [Apple Support](https://support.apple.com/en-us/102266)
  * [APNs Developer Docs](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns?language=objc)

***

## Core API capabilities

### Send messages

See the [Create Message guide](/reference/create-message) to get started. Programmatically send:

<Columns>
  <Card title="Push Notifications" icon="bell" href="/reference/push-notification">
    Send push notifications to apps and websites.
  </Card>

  <Card title="Email" icon="envelope" href="/reference/email">
    Send transactional and promotional emails.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/reference/sms">
    Send SMS or MMS messages globally.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="/reference/start-live-activity">
    Send Live Activity updates to iOS devices.
  </Card>
</Columns>

<Note>
  For platform-specific features like personalization, throttling, and frequency capping, see the [Push](/docs/en/push), [Email](/docs/en/email-messaging), [SMS](/docs/en/sms-messaging), and [Live Activities](/docs/en/live-activities) overview guides.
</Note>

***

### Manage templates

[Templates](/docs/en/templates) are reusable push, email, and SMS messages that simplify development and improve consistency.

<Columns>
  <Card title="Create template" icon="plus" href="/reference/create-template">
    Save a reusable message layout for push, email, or SMS.
  </Card>

  <Card title="Update template" icon="pen-to-square" href="/reference/update-template">
    Modify an existing template's content or settings.
  </Card>

  <Card title="View templates" icon="eye" href="/reference/view-templates">
    List all templates in your app with their metadata.
  </Card>

  <Card title="Delete template" icon="trash" href="/reference/delete-template">
    Permanently remove a template from your app.
  </Card>
</Columns>

***

### Track custom events

[Custom events](/docs/en/custom-events) record user actions like purchases, content views, or milestones. Use them to enter users into [Journeys](/docs/en/journeys-settings) or trigger [Wait Until](/docs/en/journeys-actions) nodes.

<Card title="Create custom events" icon="bolt" href="/reference/create-custom-events">
  Record user events to trigger Journeys and track behavior.
</Card>

***

### Manage Users and Subscriptions

See the [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) guides for more details.

<Columns>
  <Card title="Create user" icon="user-plus" href="/reference/create-user">
    Create a user with optional aliases and subscriptions.
  </Card>

  <Card title="View user" icon="eye" href="/reference/view-user">
    View user details.
  </Card>

  <Card title="Update user" icon="user-pen" href="/reference/update-user">
    Modify a User's properties, tags, or aliases.
  </Card>

  <Card title="Delete user" icon="user-minus" href="/reference/delete-user">
    Permanently remove a User and all associated data.
  </Card>
</Columns>

***

### Manage Segments

[Segments](/docs/en/segmentation) group Users by filters for targeted messaging.

<Columns>
  <Card title="Create Segments" icon="plus" href="/reference/create-segments">
    Define a new Segment with filters to group Users.
  </Card>

  <Card title="Update Segment" icon="pen-to-square" href="/reference/update-segment">
    Modify a Segment's name or replace its filters.
  </Card>

  <Card title="Delete Segments" icon="trash" href="/reference/delete-segments">
    Permanently remove a Segment from your app.
  </Card>
</Columns>

<Note>
  You can also target users dynamically using [filters](/reference/create-message#filters) without creating persistent segments.
</Note>

***

### Export data

For analytics breakdowns, see [Analytics overview](/docs/en/analytics-overview).

<Columns>
  <Card title="Export CSV of subscriptions" icon="file-export" href="/reference/csv-export">
    Export all user and subscription data.
  </Card>

  <Card title="Export CSV of events" icon="file-export" href="/reference/export-csv-of-events">
    Export events like sent, received, and clicked.
  </Card>

  <Card title="View messages" icon="eye" href="/reference/view-messages">
    View message details and analytics.
  </Card>

  <Card title="View message" icon="magnifying-glass" href="/reference/view-message">
    View individual message details.
  </Card>
</Columns>

***

### Manage Apps & API Keys

OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See [Apps, orgs, & accounts](/docs/en/apps-organizations).

<Columns>
  <Card title="Create an app" icon="plus" href="/reference/create-an-app">
    Register a new app with platform credentials.
  </Card>

  <Card title="Update an app" icon="pen-to-square" href="/reference/update-an-app">
    Modify app settings or platform credentials.
  </Card>

  <Card title="View single app" icon="eye" href="/reference/view-an-app">
    Retrieve configuration and details for one app.
  </Card>

  <Card title="View multiple apps" icon="list" href="/reference/view-apps">
    List all apps in your account.
  </Card>
</Columns>

#### API key management

See [Keys & IDs](/docs/en/keys-and-ids) for more details.

<Columns>
  <Card title="Create API key" icon="key" href="/reference/create-api-key">
    Generate a new API key with specific permissions.
  </Card>

  <Card title="View API keys" icon="eye" href="/reference/view-api-keys">
    List all API keys and their permissions for your app.
  </Card>

  <Card title="Delete API key" icon="trash" href="/reference/delete-api-key">
    Revoke an API key permanently.
  </Card>

  <Card title="Update API key" icon="pen-to-square" href="/reference/update-api-key">
    Modify an API key's permissions or IP allowlist.
  </Card>
</Columns>

***

## Error handling and retries

The OneSignal API may return temporary errors such as `429` (rate limited), `5xx` (server errors), or timeouts. When this happens, the request may still be processing. If you retry failed requests, always use an `idempotency_key` and follow the recommended retry delays to avoid duplicate messages.

<Card title="Rate limits and error handling" icon="triangle-exclamation" href="/reference/rate-limits">
  Retry strategies, error definitions, and recovery steps.
</Card>

***

## FAQ

### What is the timeout for API responses?

* Default: **100 seconds**
* If you're unsure whether a request completed, use an [`idempotency_key`](/reference/idempotent-notification-requests) to safely retry.
* See [Rate limits and error handling](/reference/rate-limits) for more details.

### Do I need to download or renew certificates to call the OneSignal API?

No. The OneSignal API uses HTTPS with a publicly trusted TLS certificate managed by Cloudflare. These edge certificates renew automatically and are trusted by all major browsers, operating systems, and runtimes.

If your network pins a specific leaf certificate, it will expire and rotate every few months — this is normal Cloudflare behavior. Trust the root and intermediate CAs in the chain instead of the leaf certificate to avoid disruption.

<Accordion title="Certificate pinning details and workarounds">
  * **Best practice**: Trust the root and intermediate CAs in the chain instead of the rotating leaf certificate.
  * **If you must pin a certificate**: Pin the public key (SPKI) of the CA or use a backup key set, not the exact leaf certificate.
  * **Fetching the current certificate**: If your process requires the active leaf certificate, retrieve it directly:

  ```bash theme={null}
  SERVERNAME=api.onesignal.com
  echo -n | openssl s_client -connect $SERVERNAME:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/${SERVERNAME}_current.pem
  ```

  To retrieve the full chain, add the `-showcerts` flag to `openssl s_client`.

  See [Cloudflare SSL/TLS documentation](https://developers.cloudflare.com/ssl/get-started/) and [Cloudflare Edge Certificates documentation](https://developers.cloudflare.com/ssl/edge-certificates/) for more details.
</Accordion>

### Why am I getting a 403 Forbidden error?

A `403` response means the API key is valid but does not have permission for the requested operation. Check the following:

* **Wrong key type**: App API keys work for app-level endpoints (sending messages, managing Users). Organization API keys are required for org-level endpoints (creating apps, managing API keys). See [Keys & IDs](/docs/en/keys-and-ids) for details.
* **IP allowlisting**: If IP allowlisting is enabled on your API key, requests from IPs not on the list are denied. Verify your server's IP is included.
* **Revoked or rotated key**: If the key was recently rotated, the old key is no longer valid. Update your integration with the new key.

### Why am I getting "UnknownHostException - Unable to resolve host api.onesignal.com"?

This error means your environment cannot resolve the DNS for `api.onesignal.com`. Common causes:

* **Firewall or proxy blocking DNS**: Ensure your network allows outbound DNS queries and traffic to `api.onesignal.com` on port `443`.
* **No internet connectivity**: Verify the device or server has an active network connection.
* **DNS server misconfiguration**: Try a public DNS resolver like `8.8.8.8` (Google) or `1.1.1.1` (Cloudflare) to rule out local DNS issues.
* **Stale DNS cache**: Flush your local DNS cache and ensure your client respects the TTL of 300 seconds.


# SMS
Source: https://documentation.onesignal.com/reference/sms

POST /notifications?c=sms
Send a message using the SMS channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for SMS and MMS. See [Push notification](/reference/push-notification) or [Email](/reference/email) to send to those channels.

Ensure your [SMS setup](/docs/en/sms-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***

## Trackable links

Add trackable links to your SMS `contents` using [liquid syntax](/docs/en/using-liquid-syntax) in the format `{{'your_url' | track_link}}`.

Example:

```json JSON theme={null}
{
  "contents": {
    "en": "Hi, here's my link: {{'https://example.com' | track_link}} "
  }
}
```

In this example, the liquid syntax block will be replaced with a trackable short link and display in the message as: `1sgnl.co/XXXX`.

<Note>
  See [SMS trackable links](/docs/en/links#sms) for more details.
</Note>

***


# Start Live Activity
Source: https://documentation.onesignal.com/reference/start-live-activity

POST /apps/{app_id}/activities/activity/{activity_type}
Remotely start a Live Activity on iOS devices via OneSignal's REST API. Define the activity type, target users, and send dynamic, updatable content directly to a Live Activity interface.

## Overview

Remotely start an iOS Live Activity using OneSignal’s REST API. Live Activities provide real-time updates directly on the lock screen and Dynamic Island (on supported devices), enhancing user engagement with ongoing events like sports games, deliveries, or countdowns.

***

## How to use this API

1. Define a Live Activity in your app. See [Live Activities developer setup](/docs/en/live-activities-developer-setup) to get started.
2. Use the `activity_type` parameter to specify the type of the Live Activity UI to use.
3. Select your target audience to receive the Live Activity. Target all or individual users.
4. Generate a unique `activity_id` to track and manage your Live Activity.
5. Use the `event_attributes` parameter to initialize the Live Activity with static data.
6. Use the `event_updates` parameter to update the Live Activity with dynamic content.

### Select your target audience

Before sending a message, you need to determine who should receive it. OneSignal offers three targeting options:

1. **Aliases & Subscription IDs**: Send messages to specific users using unique identifiers such as External ID (recommended), OneSignal ID, custom alias, or subscription ID.
2. **Segments**: Target predefined user groups based on attributes and behavior.
3. **Filters**: Create custom targeting rules using user properties, such as tags, location, or activity.

<Note>
  You can only use one targeting method per message. For example, you cannot combine alias-based targeting with filters in the same request.

  See [Select your target audience](/reference/create-message#select-your-target-audience) for more information.
</Note>

### Set a unique `activity_id`

* Set a unique `activity_id` to track and manage the Live Activity. This value is crucial for maintaining a consistent reference to the Live Activity across different devices and sessions. Consider using a UUID, CUID, or NanoID for this parameter.
* Ensure that the `activity_id` is unique and consistently used for each Live Activity to avoid conflicts and ensure accurate tracking.

  ```json Example theme={null}
  {
    "activity_id": "217aae2b-42ee-4097-bc3f-b7a6e9d15b9b",
    ...
  }
  ```

<Info>
  See [Live Activities developer setup](/docs/en/live-activities-developer-setup) guide for more information.
</Info>

### Set `event_attributes` to initialize the Live Activity

Set default/static data to display in the Live Activity upon start.

```json Example theme={null}
{
  "event_attributes": {
  	"awayTeam": "Away Team Name",
    "homeTeam": "Home Team Name"
  }
}
```

### Set `event_updates` for dynamic content

The content used to update a running Live Activity. The object must conform to the `ContentState` interface defined within your app's Live Activity. See [Live Activities developer setup](/docs/en/live-activities-developer-setup).

Ensure that the `event_updates` object matches the [`ContentState`](https://developer.apple.com/documentation/activitykit/activityattributes/contentstate#) interface exactly as defined in your Live Activity implementation. Inconsistencies can cause Live Activities to fail to display.

```json Example theme={null}
{
  "event_updates": {
    "quarter": 1,
    "homeScore": 70,
    "awayScore": 78,
    "inTimeout": false
  }
}
```

***


# Transfer Subscription
Source: https://documentation.onesignal.com/reference/transfer-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/owner
Transfer a Subscription to a different user within the same OneSignal app. Useful for associating existing Subscriptions like push, email, or SMS with a new or updated user identity.

## Overview

Use this API to transfer a Subscription from one user to another within the same OneSignal app.

It is highly recommended to use our web and mobile SDKs to set and update the External ID with the `login` method instead of this API. Your app or website may continue to be setting the wrong External ID. Make sure to only use this API if you are setting the same External ID within your app or website.

This is typically used when:

* You want to reassign an existing push, email, or SMS Subscription to a new or updated user.
* You have changed how you're identifying users (e.g., migrating from anonymous to known users).

<Note>
  - Subscriptions **cannot be transferred across different OneSignal apps**.
  - For email and SMS Subscriptions, you can instead create new ones using [Create User](/reference/create-user).
  - For push Subscriptions, platform limitations may apply—see [Subscriptions](/docs/en/subscriptions#importing-push-subscriptions) for details.
</Note>

***

## How to Use This API

### Required Path Parameter: `subscription_id`

You must know the `subscription_id` of the subscription to be transferred. This is a unique UUID assigned by OneSignal.

### Required Body Parameter: `identity` (object)

This specifies the user the subscription should be moved to. Only **one alias** should be used per request. You can identify the target user using one of:

* `external_id` (recommended)
* `onesignal_id`
* A [custom alias](/docs/en/aliases)

***


# Unsubscribe email with token
Source: https://documentation.onesignal.com/reference/unsubscribe-with-token

POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
Unsubscribe an email address from future messages by calling this API from your custom unsubscribe page. Automatically disables the associated email subscription using a token-based approach.

## Overview

Use this API to unsubscribe an email address directly from your custom unsubscribe landing page. It is ideal when building branded opt-out experiences and enables you to track which email caused the unsubscribe.

When invoked, this endpoint:

* Sets the email Subscription's `enabled` property to `false`
* Prevents further messages from being sent to the email address unless explicitly overridden (see [Overriding unsubscribes](/reference/email#body-include-unsubscribed))
* Email Subscriptions can be re-subscribed using the [Update Subscription](/reference/update-subscription) API

<Tip>
  For instructions on setting up a custom unsubscribe page, see [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page).
</Tip>

***

## How to Use This API

### Step 1: Set Up Your Custom Unsubscribe Page

Follow the guide to [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page). You'll add a custom unsubscribe URL to your email templates using Liquid syntax.

Example URL in your email template:

```liquid theme={null}
https://yourdomain.com/unsubscribe?app_id={{ app_id }}&notification_id={{ notification_id }}&token={{ token }}
```

### Step 2: Extract the Parameters

When a user clicks the unsubscribe link, your custom unsubscribe page should extract the following from the URL:

* `app_id`: OneSignal app ID
* `notification_id`: The ID of the specific email message sent
* `token`: The email token, a secure reference to the subscription

### Step 3: Call the API

When the user confirms they want to unsubscribe (e.g., clicks a button on your unsubscribe page), make a POST request to this endpoint:

```
POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
```

Example Request (JavaScript):

```js theme={null}
fetch("https://api.onesignal.com/apps/your-app-id/notifications/your-notification-id/unsubscribe?token=abc123xyz", {
  method: "POST"
});
```

<Info>
  No request body or authentication is required. The token acts as a secure identifier.
</Info>

<Note>
  * This API only works for email subscriptions.
  * It should only be used from a server or frontend context that you control (e.g., your custom unsubscribe page).
  * Once unsubscribed, the email address will not receive future emails from your app unless resubscribed.
</Note>

***


# Update Live Activity
Source: https://documentation.onesignal.com/reference/update-live-activity-api

POST /apps/{app_id}/live_activities/{activity_id}/notifications
Update or terminate running iOS Live Activities using OneSignal’s Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

## Overview

Update or terminate running iOS Live Activities using our REST API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

Before using this API, ensure your app is properly configured by following the [Live Activities developer setup](/docs/en/live-activities-developer-setup).

## How to Use this API

1. Select the Live Activity to update by specifying its `activity_id` in the URL. This is set when using the:

* [Start Live Activity API](/reference/start-live-activity)
* [Triggering it in-app](/docs/en/live-activities-developer-setup).
* [`LiveActivities.enter` SDK method](/docs/en/mobile-sdk-reference#enter)

2. Update the state of the Live Activity by setting the `event_updates` parameter to a JSON object that matches the structure of the `ActivityAttributes.ContentState` struct defined in your Live Activity widget extension.

3. When ready to terminate the Live Activity:

* Set the `event` parameter to `end`
* Include a `dismissal_date` if you want the Live Activity to be dismissed in less than 4 hours.
* Set the `dismissal_date` to a time in the past to dismiss the Live Activity immediately. User must have clicked "Allow" for the Live Activity to be removed programmatically.

<Warning>
  Once a Live Activity `activity_id` is ended, you cannot update it. This includes changing the `dismissal_date` or `event` parameter.

  If the Live Activity is not being dismissed immediately, it is either because:

  * The `activity_id` has already been ended.
  * The user has not clicked "Allow" for the Live Activity to be removed programmatically.
</Warning>

***


# Update Subscription by ID
Source: https://documentation.onesignal.com/reference/update-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}
Update properties on an existing OneSignal subscription using its subscription_id. Commonly used to enable or disable a subscription when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties by `subscription_id`.

This endpoint is primarily used by the OneSignal SDK to manage subscription state.

Most external use cases are better served by the [Update Subscription by token](/reference/update-subscription-by-token) API, which can use the Email Address or Phone Number as the `token` or the [Update User](/reference/update-user) API, which allows for updating user-level data.

<Note>
  For **email opt-outs**, it's recommended to use the [Unsubscribe Email (with token)](/reference/unsubscribe-with-token) API instead. This avoids the need to store or manage the `subscription_id`.
</Note>

***

## How to use this API

**Required:** `subscription_id`

To update a subscription, you **must know the `subscription_id`**. This is a UUID generated by OneSignal and is immutable.

* You can retrieve a subscription ID by querying the [User object](/docs/en/users).
* See the [Subscriptions](/docs/en/subscriptions) guide for an explanation of how subscription IDs are generated and used.

<Note>
  You **cannot** update the `type` of a Subscription. If the `type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the Subscription with the correct type.
</Note>

***


# Update Subscription by token
Source: https://documentation.onesignal.com/reference/update-subscription-by-token

PATCH /apps/{app_id}/subscriptions_by_token/{token_type}/{token}
Update properties on an existing Subscription using its token. Commonly used to enable or disable subscription status when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties.

This API can be useful if:

* You only know the `token` and `token_type` and want to update metadata or status flags directly.
* You are managing Subscription status outside of the OneSignal SDK. Like with a [custom preference page or unsubscribe page](/docs/en/create-custom-unsubscribe-page).

***

## How to use this API

To update a Subscription, you must know the `token_type` and the `token`.

The `token_type` is the [Subscription's type](/docs/en/server-sdk-reference#subscription-types) (e.g., `Email`, `SMS`, `iOSPush`, `AndroidPush`, etc.).

The `token` is the push token, email address, or phone number associated with the Subscription.

Ensure the `token` is valid and correctly formatted for the chosen `token_type`.

* **Email format:** Should be a valid email address that you confirmed can receive emails.
* **SMS format:** Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164).
* **iOSPush APNS token format:** 64 characters, hexadecimal characters only (0-9,a-f).
* **AndroidPush FCM token format:** Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.

<Warning>
  You **cannot** update the `token_type` and `token` of a Subscription with this API. If the `token_type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the subscription with the correct type.

  If multiple Subscriptions are found for the `token` and `token_type`, an `Http 400` error is returned with a list of subscription IDs that match the criteria.
</Warning>

***


# Update template
Source: https://documentation.onesignal.com/reference/update-template

PATCH /templates/{template_id}?app_id={app_id}
Update existing OneSignal message templates for push, email, or SMS. Changes apply immediately across dashboard and API usage via the `template_id` reference.

## Overview

This endpoint allows you to update an existing push, email, or SMS template in your OneSignal app. Once updated, the changes are applied immediately and reflected across both the Dashboard and API when using the associated `template_id`.

Templates are updated using the same structure as when [creating templates](/reference/create-template).

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

To update a template, you must supply:

* Your **OneSignal App ID** found in [Keys & IDs](/docs/en/keys-and-ids).
* The **Template ID**

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***

## Channel-Specific Requirements

### Push Templates

* The `contents` property must use the `en` (English) key along with other languages you want to support.
* All [Push Notification Properties](/reference/push-notification) are valid.
* All platforms are enabled by default. To limit, explicitly enable desired ones (e.g., `isAndroid: true` disables iOS and Web).

### Email Templates

* Set `isEmail: true`
* Include `email_subject` and `email_body`
* All [Email Channel Properties](/reference/email) are supported.

### SMS Templates

* Set `isSMS: true`
* All [SMS Channel Properties](/reference/sms) are supported.

***


# Update user
Source: https://documentation.onesignal.com/reference/update-user

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}
Modify a user's properties.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint updates user-level properties for an existing user in your OneSignal app.

* To change a user's `identity` like `external_id` or custom [Aliases](/docs/en/aliases), use the [Create alias](/reference/create-alias) and [Delete alias](/reference/delete-alias) APIs.
* To manage a user's `subscriptions`, use the [Create Subscription by alias](/reference/create-subscription) or [Create user](/reference/create-user) APIs.

***

## How to use this API

You must supply an alias in the request path:

* `alias_label`: The type of identifier (e.g., `external_id`, `onesignal_id`, or a custom alias label).
* `alias_id`: The corresponding value for that label.

See [Users](/docs/en/users) and [Aliases](/docs/en/aliases) for more info.

***


# View message
Source: https://documentation.onesignal.com/reference/view-message

GET /notifications/{message_id}?app_id={app_id}
View the details of a single message and the Outcomes associated with it.

## Overview

The View message API allows you to fetch data from a single push, email, or SMS message at a time. If you want to get multiple messages at a time, use the [View messages](/reference/view-messages) API. In most cases, you will likely want to use [Event Streams](/docs/en/event-streams) instead.

Currently this API does not provide Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are only **accessible 30 days after creation**; however, messages sent using the OneSignal dashboard are accessible for the app's lifetime.

See our [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and (after giving your users some time to interact with the message) pull the data if desired.

For example, if you send a message targeting the `include_aliases` parameter, the response will include the aliases you set. If you send with the `included_segments` parameter, then the response will only provide the segments you set. When targeting segments or filters, you can use the [Export audience activity CSV](/reference/export-csv-of-events) API to get the user event data.

To view outcome data for the message, you must include the `outcome_name` parameter with the name of the outcome you want to fetch, along with the accompanying aggregation type (.count or .sum), for example: `os__click.count`. For more information on outcome definitions, see [View Outcomes](/reference/view-outcomes).

***


# View messages
Source: https://documentation.onesignal.com/reference/view-messages

GET /notifications?app_id={app_id}&limit={limit}&offset={offset}&kind={kind}&template_id={template_id}&time_offset={time_offset}
View the details for a collection of messages.

## Overview

The View messages API fetches data for up to 50 push, email, or SMS messages at a time. To fetch a single message, use the [View message](/reference/view-message) API. In most cases, use [Event Streams](/docs/en/event-streams) instead.

This API does not return Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are **retained for 30 days** after creation; messages sent through the OneSignal dashboard are retained for the app's lifetime.

See [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

Use time-offset pagination for sequential pulls of all messages, and standard pagination for ad-hoc queries. For ETL or bulk export pipelines, use [Event Streams](/docs/en/event-streams) instead.

Filter results to a specific message kind or template using the `kind` and `template_id` query parameters. Both filters work with either pagination style.

### Optimized pagination with time offset

To efficiently retrieve all available messages for an app, use `time_offset`-based pagination. When `time_offset` is specified, the sort order changes from descending to ascending — the oldest messages appear first based on the [`send_after` date](/reference/create-message#send-after).

#### Accepted `time_offset` values

* ISO 8601 formatted timestamp — for example, `2025-01-01T00:00:00.000Z` (January 1, 2025, at 00:00 UTC).
* Opaque cursor token (Base64-encoded) — provided in the API response as `next_time_offset`.

<Steps>
  <Step title="Initial fetch">
    To fetch messages from a specific date onward, set `time_offset` to an ISO 8601 formatted timestamp. For example, to retrieve messages sent since January 1, 2025: `time_offset=2025-01-01T00:00:00.000Z`.

    <Note>
      * `time_offset` cannot be used with the standard `offset` parameter.
      * `time_offset` excludes messages that match the exact timestamp to avoid duplicates.
      * The response includes `next_time_offset`, a cursor token for the next page. No decoding required. For example: `"next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="`
    </Note>
  </Step>

  <Step title="Fetch additional pages">
    Use `next_time_offset` from the previous response as the `time_offset` value in the next request. For example: `time_offset=MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw==`.
  </Step>

  <Step title="Continue until completion">
    Repeat the request until an empty `notifications` array is returned, indicating all messages have been fetched.
  </Step>

  <Step title="Handling new messages">
    Because results are sorted ascending, new messages are added to the end. To resume fetching from where you left off, reuse the last `next_time_offset` that returned an empty response.
  </Step>
</Steps>

### Standard pagination

Use the `limit` and `offset` parameters to page through notifications for an app. The maximum result size is 50, and the default `limit` is `50`. Use `limit` to specify the result size and `offset` to increment by the limit value with each request.

For example, the first request uses `offset=0`, the second `offset=50`, the third `offset=100`, and so on.

Standard pagination is convenient for ad-hoc queries but degrades as the `offset` value grows. For sequential pulls of all messages, use time-offset pagination.

***


# View template
Source: https://documentation.onesignal.com/reference/view-template

GET /templates/{template_id}?app_id={app_id}
Retrieve the details of a specific message template in your OneSignal app using its template ID. This API returns the template content, target channel, and timestamps for creation and last update.

## Overview

This endpoint returns metadata and content for a single template, including:

* Template body/content
* Target delivery channel (e.g., push, email, SMS)
* Creation and last updated timestamps

This is useful for inspecting existing templates before using or updating them.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Required parameters:

* `app_id` (query param): Your OneSignal App ID.
* `template_id` (path param): The unique ID of the template.

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# View templates
Source: https://documentation.onesignal.com/reference/view-templates

GET /templates?app_id={app_id}&limit={limit}&offset={offset}
Retrieve a paginated list of message templates from your OneSignal app. This endpoint returns summary information for each template, including ID, name, creation, and update timestamps.

## Overview

Use this endpoint to retrieve a list of message templates associated with a specific OneSignal app. The response provides summary information only:

* `template_id`
* `name`
* `created_at`
* `updated_at`

<Note>
  This endpoint does **not** return full template content such as message bodies, channel properties, or delivery configuration. For detailed template data, use the [View Template](/reference/view-template) endpoint.
</Note>

***

## How to Use This API

### Required Parameters

* **`app_id`** (query param): The OneSignal App ID whose templates you want to retrieve.

### Optional Parameters

* **`limit`** (query param): Number of templates to return (default: `50`, maximum: `50`).
* **`offset`** (query param): Number of templates to skip. Use for pagination.

### Pagination Example

If your app has 125 templates and you're using the default limit of 50:

1. First request (first 50 templates):\
   `GET /templates?app_id={app_id}&offset=0`

2. Second request (next 50 templates):\
   `GET /templates?app_id={app_id}&offset=50`

3. Third request (final 25 templates):\
   `GET /templates?app_id={app_id}&offset=100`

Repeat the request while adjusting the `offset` until you've retrieved all templates.

***


# View user
Source: https://documentation.onesignal.com/reference/view-user

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}
Retrieve a user including aliases, properties, and subscriptions.

## Overview

* Use this API to retrieve a user's full profile, including identity aliases, user properties, and messaging subscription details across channels.
* This is helpful for verifying user data, debugging subscription issues, or syncing OneSignal user data with your internal systems.

For detailed concepts and guides, see [Users](/docs/en/users), [Subscriptions](/docs/en/subscriptions), and [Aliases](/docs/en/aliases) documentation.

## How to use this API

To look up a user, you must provide both an `alias_label` and an `alias_id`. In most cases, your `external_id` will serve as the `alias_label`, and its value will be passed as the `alias_id`. While you may use a custom alias, we strongly recommend setting and using the `external_id` as your primary user identifier for consistency across platforms.

To retrieve a user using their OneSignal ID, set the `alias_label` to `onesignal_id`. **Note**: When querying with any alias other than `onesignal_id`, authentication is required.

***


# Server SDK reference
Source: https://documentation.onesignal.com/docs/en/server-sdk-reference

Install, configure, and use OneSignal server SDKs to send push notifications, emails, and SMS from your backend in Node.js, Python, Java, Go, PHP, Ruby, C#, and Rust.

All OneSignal server SDKs are generated from the same OpenAPI specification, so they share a consistent interface regardless of language. Each SDK wraps the [OneSignal REST API](/reference/create-message) and provides typed models for requests and responses.

## Available SDKs

| Language  | Package                                                                                            | Repository                                                  |
| --------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Node.js   | [@onesignal/node-onesignal](https://www.npmjs.com/package/@onesignal/node-onesignal)               | [GitHub](https://github.com/OneSignal/node-onesignal)       |
| Python    | [onesignal-python-api](https://pypi.org/project/onesignal-python-api/)                             | [GitHub](https://github.com/OneSignal/onesignal-python-api) |
| Java      | [onesignal-java-client](https://central.sonatype.com/artifact/com.onesignal/onesignal-java-client) | [GitHub](https://github.com/OneSignal/onesignal-java-api)   |
| Go        | [onesignal-go-api](https://pkg.go.dev/github.com/OneSignal/onesignal-go-api)                       | [GitHub](https://github.com/OneSignal/onesignal-go-api)     |
| PHP       | [onesignal/onesignal-php-api](https://packagist.org/packages/onesignal/onesignal-php-api)          | [GitHub](https://github.com/OneSignal/onesignal-php-api)    |
| Ruby      | [onesignal](https://rubygems.org/gems/onesignal)                                                   | [GitHub](https://github.com/OneSignal/onesignal-ruby-api)   |
| C# (.NET) | [OneSignalApi](https://www.nuget.org/packages/OneSignalApi)                                        | [GitHub](https://github.com/OneSignal/onesignal-dotnet-api) |
| Rust      | [onesignal-rust-api](https://crates.io/crates/onesignal-rust-api)                                  | [GitHub](https://github.com/OneSignal/onesignal-rust-api)   |

***

## Installation

<Note>
  Version numbers below are examples. Check the package registry for each SDK to install the latest version.
</Note>

<Tabs>
  <Tab title="Node.js">
    ```bash theme={null}
    npm install @onesignal/node-onesignal
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install onesignal-python-api
    ```
  </Tab>

  <Tab title="Java">
    **Maven**

    ```xml theme={null}
    <dependency>
      <groupId>com.onesignal</groupId>
      <artifactId>onesignal-java-client</artifactId>
      <version>5.3.0</version>
    </dependency>
    ```

    **Gradle**

    ```groovy theme={null}
    implementation "com.onesignal:onesignal-java-client:5.3.0"
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/OneSignal/onesignal-go-api/v5
    ```
  </Tab>

  <Tab title="PHP">
    Add to `composer.json`:

    ```json theme={null}
    {
      "require": {
        "onesignal/onesignal-php-api": "^5.3"
      }
    }
    ```

    Then run `composer update`.
  </Tab>

  <Tab title="Ruby">
    Add to your `Gemfile`:

    ```ruby theme={null}
    gem 'onesignal', '~> 5.3'
    ```

    Then run `bundle install`.
  </Tab>

  <Tab title="C# (.NET)">
    ```bash theme={null}
    dotnet add package OneSignalApi
    ```
  </Tab>

  <Tab title="Rust">
    Add to `Cargo.toml` under `[dependencies]`:

    ```toml theme={null}
    onesignal-rust-api = "5.3.0"
    ```
  </Tab>
</Tabs>

***

## Configuration

Every SDK requires authentication via API keys. Two key types are available:

* **REST API Key** — required for most endpoints (sending notifications, managing users, etc.). Found in your app's **Settings > Keys & IDs**.
* **Organization API Key** — only required for organization-level endpoints like creating or listing apps. Found in **Organization Settings**.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const OneSignal = require('@onesignal/node-onesignal');

    const configuration = OneSignal.createConfiguration({
      restApiKey: 'YOUR_REST_API_KEY',
      organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',
    });

    const client = new OneSignal.DefaultApi(configuration);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import onesignal
    from onesignal.api import default_api

    configuration = onesignal.Configuration(
        rest_api_key='YOUR_REST_API_KEY',
        organization_api_key='YOUR_ORGANIZATION_API_KEY',
    )

    with onesignal.ApiClient(configuration) as api_client:
        client = default_api.DefaultApi(api_client)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.onesignal.client.ApiClient;
    import com.onesignal.client.Configuration;
    import com.onesignal.client.auth.HttpBearerAuth;
    import com.onesignal.client.api.DefaultApi;

    ApiClient defaultClient = Configuration.getDefaultApiClient();

    HttpBearerAuth restApiAuth = (HttpBearerAuth) defaultClient
        .getAuthentication("rest_api_key");
    restApiAuth.setBearerToken("YOUR_REST_API_KEY");

    HttpBearerAuth orgApiAuth = (HttpBearerAuth) defaultClient
        .getAuthentication("organization_api_key");
    orgApiAuth.setBearerToken("YOUR_ORGANIZATION_API_KEY");

    DefaultApi client = new DefaultApi(defaultClient);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import onesignal "github.com/OneSignal/onesignal-go-api"

    restAuth := context.WithValue(
        context.Background(),
        onesignal.RestApiKey,
        "YOUR_REST_API_KEY",
    )

    orgAuth := context.WithValue(
        restAuth,
        onesignal.OrganizationApiKey,
        "YOUR_ORGANIZATION_API_KEY",
    )

    apiClient := onesignal.NewAPIClient(onesignal.NewConfiguration())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use onesignal\client\api\DefaultApi;
    use onesignal\client\Configuration;
    use GuzzleHttp;

    $config = Configuration::getDefaultConfiguration()
        ->setRestApiKeyToken('YOUR_REST_API_KEY')
        ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');

    $client = new DefaultApi(
        new GuzzleHttp\Client(),
        $config
    );
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'onesignal'

    OneSignal.configure do |config|
      config.rest_api_key = 'YOUR_REST_API_KEY'
      config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'
    end

    client = OneSignal::DefaultApi.new
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    using OneSignalApi.Api;
    using OneSignalApi.Client;

    var config = new Configuration();
    config.BasePath = "https://api.onesignal.com";
    config.AccessToken = "YOUR_REST_API_KEY";

    var client = new DefaultApi(config);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use onesignal::apis::configuration::Configuration;

    fn create_configuration() -> Configuration {
        let mut config = Configuration::new();
        config.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
        config.organization_api_key_token = Some("YOUR_ORGANIZATION_API_KEY".to_string());
        config
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Store your API keys in environment variables or a secrets manager. Never commit them to source control.
</Warning>

***

## Send a push notification

Send push notifications to web and mobile [Subscriptions](./subscriptions) by targeting a segment. These examples show the happy path — add error handling (try/catch, error callbacks) for production use.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.contents = { en: 'Hello from OneSignal!' };
    notification.headings = { en: 'Push Notification' };
    notification.included_segments = ['Subscribed Users'];

    const response = await client.createNotification(notification);
    console.log('Notification ID:', response.id);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        contents=onesignal.StringMap(en='Hello from OneSignal!'),
        headings=onesignal.StringMap(en='Push Notification'),
        included_segments=['Subscribed Users'],
    )

    response = client.create_notification(notification)
    print('Notification ID:', response.id)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.onesignal.client.model.Notification;
    import com.onesignal.client.model.StringMap;

    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");

    StringMap contents = new StringMap();
    contents.en("Hello from OneSignal!");
    notification.setContents(contents);

    StringMap headings = new StringMap();
    headings.en("Push Notification");
    notification.setHeadings(headings);

    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));

    var response = client.createNotification(notification);
    System.out.println("Notification ID: " + response.getId());
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Hello from OneSignal!")})
    notification.SetHeadings(onesignal.StringMap{En: onesignal.PtrString("Push Notification")})
    notification.SetIncludedSegments([]string{"Subscribed Users"})

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()

    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Notification ID:", response.GetId())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use onesignal\client\model\Notification;
    use onesignal\client\model\StringMap;

    $content = new StringMap();
    $content->setEn('Hello from OneSignal!');

    $headings = new StringMap();
    $headings->setEn('Push Notification');

    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setContents($content);
    $notification->setHeadings($headings);
    $notification->setIncludedSegments(['Subscribed Users']);

    $response = $client->createNotification($notification);
    echo 'Notification ID: ' . $response->getId();
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      contents: { en: 'Hello from OneSignal!' },
      headings: { en: 'Push Notification' },
      included_segments: ['Subscribed Users']
    })

    response = client.create_notification(notification)
    puts "Notification ID: #{response.id}"
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    using OneSignalApi.Model;

    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        Contents = new StringMap(en: "Hello from OneSignal!"),
        Headings = new StringMap(en: "Push Notification"),
        IncludedSegments = new List<string> { "Subscribed Users" }
    };

    var response = client.CreateNotification(notification);
    Console.WriteLine("Notification ID: " + response.Id);
    ```

    Note: .NET SDK does not normalize newline characters automatically. If your content contains `\r\n` normalize it before passing to `Contents`:

    ```csharp theme={null}
    var normalizedContent = yourContent
       .Replace("\\r\\n", "\n")
       .Replace("\\n", "\n")
       .Replace("\r\n", "\n")
       .Replace("\r", "\n");
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use onesignal::apis::default_api;
    use onesignal::models::{Notification, StringMap};

    let mut contents = StringMap::new();
    contents.en = Some("Hello from OneSignal!".to_string());

    let mut headings = StringMap::new();
    headings.en = Some("Push Notification".to_string());

    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.contents = Some(Box::new(contents));
    notification.headings = Some(Box::new(headings));
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);

    let config = create_configuration();
    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Send an email

Send emails to [Subscriptions](./subscriptions) with the `email` channel.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.email_subject = 'Important Update';
    notification.email_body = '<h1>Hello!</h1><p>This is an HTML email.</p>';
    notification.included_segments = ['Subscribed Users'];
    notification.channel_for_external_user_ids = 'email';

    const response = await client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        email_subject='Important Update',
        email_body='<h1>Hello!</h1><p>This is an HTML email.</p>',
        included_segments=['Subscribed Users'],
        channel_for_external_user_ids='email',
    )

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");
    notification.setEmailSubject("Important Update");
    notification.setEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>");
    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
    notification.setChannelForExternalUserIds("email");

    var response = client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetEmailSubject("Important Update")
    notification.SetEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>")
    notification.SetIncludedSegments([]string{"Subscribed Users"})
    notification.SetChannelForExternalUserIds("email")

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setEmailSubject('Important Update');
    $notification->setEmailBody('<h1>Hello!</h1><p>This is an HTML email.</p>');
    $notification->setIncludedSegments(['Subscribed Users']);
    $notification->setChannelForExternalUserIds('email');

    $response = $client->createNotification($notification);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      email_subject: 'Important Update',
      email_body: '<h1>Hello!</h1><p>This is an HTML email.</p>',
      included_segments: ['Subscribed Users'],
      channel_for_external_user_ids: 'email'
    })

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        EmailSubject = "Important Update",
        EmailBody = "<h1>Hello!</h1><p>This is an HTML email.</p>",
        IncludedSegments = new List<string> { "Subscribed Users" },
        ChannelForExternalUserIds = "email"
    };

    var response = client.CreateNotification(notification);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.email_subject = Some("Important Update".to_string());
    notification.email_body = Some("<h1>Hello!</h1><p>This is an HTML email.</p>".to_string());
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
    notification.channel_for_external_user_ids = Some("email".to_string());

    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Send an SMS

Send SMS text messages to [Subscriptions](./subscriptions) with the `sms` channel.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.contents = { en: 'Your SMS message content here' };
    notification.included_segments = ['Subscribed Users'];
    notification.channel_for_external_user_ids = 'sms';
    notification.sms_from = '+15551234567';

    const response = await client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        contents=onesignal.StringMap(en='Your SMS message content here'),
        included_segments=['Subscribed Users'],
        channel_for_external_user_ids='sms',
        sms_from='+15551234567',
    )

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    StringMap contents = new StringMap();
    contents.en("Your SMS message content here");

    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");
    notification.setContents(contents);
    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
    notification.setChannelForExternalUserIds("sms");
    notification.setSmsFrom("+15551234567");

    var response = client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Your SMS message content here")})
    notification.SetIncludedSegments([]string{"Subscribed Users"})
    notification.SetChannelForExternalUserIds("sms")
    notification.SetSmsFrom("+15551234567")

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $content = new StringMap();
    $content->setEn('Your SMS message content here');

    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setContents($content);
    $notification->setIncludedSegments(['Subscribed Users']);
    $notification->setChannelForExternalUserIds('sms');
    $notification->setSmsFrom('+15551234567');

    $response = $client->createNotification($notification);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      contents: { en: 'Your SMS message content here' },
      included_segments: ['Subscribed Users'],
      channel_for_external_user_ids: 'sms',
      sms_from: '+15551234567'
    })

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        Contents = new StringMap(en: "Your SMS message content here"),
        IncludedSegments = new List<string> { "Subscribed Users" },
        ChannelForExternalUserIds = "sms",
        SmsFrom = "+15551234567"
    };

    var response = client.CreateNotification(notification);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let mut contents = StringMap::new();
    contents.en = Some("Your SMS message content here".to_string());

    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.contents = Some(Box::new(contents));
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
    notification.channel_for_external_user_ids = Some("sms".to_string());
    notification.sms_from = Some("+15551234567".to_string());

    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## Full API reference

Each server SDK supports the same set of API endpoints. Refer to your SDK's API documentation for the complete method list, including users, subscriptions, segments, templates, and more.

| SDK       | API reference                                                                                     |
| --------- | ------------------------------------------------------------------------------------------------- |
| Node.js   | [DefaultApi.md](https://github.com/OneSignal/node-onesignal/blob/main/DefaultApi.md)              |
| Python    | [DefaultApi.md](https://github.com/OneSignal/onesignal-python-api/blob/main/docs/DefaultApi.md)   |
| Java      | [DefaultApi.md](https://github.com/OneSignal/onesignal-java-api/blob/main/docs/DefaultApi.md)     |
| Go        | [DefaultApi.md](https://github.com/OneSignal/onesignal-go-api/blob/main/docs/DefaultApi.md)       |
| PHP       | [DefaultApi.md](https://github.com/OneSignal/onesignal-php-api/blob/main/docs/Api/DefaultApi.md)  |
| Ruby      | [DefaultApi.md](https://github.com/OneSignal/onesignal-ruby-api/blob/main/docs/DefaultApi.md)     |
| C# (.NET) | [DefaultApi.md](https://github.com/OneSignal/onesignal-dotnet-api/blob/main/docs/DefaultApi.md)   |
| Rust      | [default\_api docs](https://github.com/OneSignal/onesignal-rust-api/blob/main/docs/DefaultApi.md) |

For the underlying REST API, see the [complete API reference](/reference/create-message).

***

## FAQ

### Which server SDK should I choose?

Use the SDK that matches your backend language. All server SDKs are generated from the same OpenAPI specification and support the same endpoints, so functionality is identical across languages.

### What is the difference between the REST API Key and Organization API Key?

The **REST API Key** is scoped to a single app and is required for most operations like sending notifications and managing users. The **Organization API Key** is scoped to your organization and is only needed for creating or listing apps. Most integrations only need the REST API Key.

### Can I use the REST API directly instead of an SDK?

Yes. The server SDKs are convenience wrappers around the [OneSignal REST API](/reference/create-message). You can call the API directly using any HTTP client with the `key` authentication scheme (`Authorization: key YOUR_REST_API_KEY`).

### Are these SDKs auto-generated?

Yes. All server SDKs are generated from the OneSignal OpenAPI specification using [OpenAPI Generator](https://openapi-generator.tech). This ensures consistent API coverage across all languages.

***

## Related pages

<Columns>
  <Card title="REST API overview" icon="code" href="/reference/rest-api-overview">
    Endpoints, authentication, rate limits, and request/response formats.
  </Card>

  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    Find your App ID, REST API key, and Organization API key.
  </Card>

  <Card title="Transactional messages" icon="paper-plane" href="./transactional-messages">
    Send OTPs, receipts, and time-sensitive alerts via API with personalized data.
  </Card>

  <Card title="Identity verification" icon="shield-halved" href="./identity-verification">
    Secure your integration with server-generated JWTs to prevent User impersonation.
  </Card>
</Columns>


# Add a player
Source: https://documentation.onesignal.com/reference/add-a-device

POST `https://onesignal.com/api/v1/players`

Register a new Subscription (aka player) to one of your OneSignal apps.

<Warning>
  This is a Legacy API. Use [Create User](/reference/create-user) or [Create Subscription](/reference/create-subscription) instead.
</Warning>

***

## Headers

| Header          | Value                     | Required | Description                      |
| --------------- | ------------------------- | -------- | -------------------------------- |
| `Content-Type`  | `application/json`        | Yes      | The content type of the request. |
| `Authorization` | `Basic YOUR_REST_API_KEY` | Yes      | Your OneSignal REST API key.     |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                                |
| -------------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                                     |
| `device_type`        | integer | Yes      | Device platform: 0 = iOS, 1 = Android, 2 = Amazon, 3 = Windows Phone, etc. |
| `identifier`         | string  | No       | Push token, email address, or phone number.                                |
| `language`           | string  | No       | Language code (e.g. "en").                                                 |
| `timezone`           | integer | No       | Time zone offset in seconds.                                               |
| `game_version`       | string  | No       | Version of your app.                                                       |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                                         |
| `device_os`          | string  | No       | Operating system version (e.g., "13.3").                                   |
| `ad_id`              | string  | No       | Advertising ID.                                                            |
| `sdk`                | string  | No       | OneSignal SDK version (e.g., "050201" for 5.2.1).                          |
| `session_count`      | integer | No       | Number of times the user has used the app.                                 |
| `tags`               | object  | No       | Custom tags as key-value pairs.                                            |
| `external_user_id`   | string  | No       | Your system's user ID for this device.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc.                 |

***

## Example Request

```json theme={null}
POST /api/v1/players HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "device_type": 1,
  "identifier": "abcdef123456",
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_model": "Pixel 4",
  "device_os": "12",
  "ad_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sdk": "050401",
  "session_count": 5,
  "tags": {
    "user_type": "free",
    "level": "10"
  },
  "external_user_id": "user123",
  "notification_types": 1
}
```

***

## Response

```json theme={null}
{
  "id": "Subscription_id_string"
}
```

## Errors

* 400 Bad Request – Invalid parameters or missing required fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Not allowed for your account type or plan.


# Copy template to another app
Source: https://documentation.onesignal.com/reference/copy-template-to-another-app

POST /templates/{template_id}/copy_to_app?app_id={app_id}
Create a duplicate of a template in another app. The new template will be completely separate from the original (including having a new template_id) but will be created with all the same content.

## Overview

This API allows you to copy a template from one app (`app_id`) to another (`target_app_id`). The duplicated template will have the same content as the original, but a new unique `template_id`.

<Note>
  If you are trying to copy an email template, we also have an [Email Template Forwarding](/docs/en/email-template-forwarding) feature that does not require an API call.

  Both options support HTML and Drag & Drop email templates.
</Note>

***

## Requirements

* **Organization Membership:** Both the `app_id` and `target_app_id` must belong to the same [Organization](/docs/en/apps-organizations).
* **Authorization Required:** You must use your [Organization API key](/docs/en/keys-and-ids#organization-api-key), not an app-level REST API key.
* **Permissions Note:** Your user must have admin-level access to both the source and target apps. If not, the request will fail with a "permission denied" error.

***

## Parameters

* `template_id` (path param): UUID of the template to be copied.
* `app_id` (query param): ID of the app where the original template exists.
* `target_app_id` (body param): ID of the app where the template will be duplicated.

***

## How to Use

### 1. Locate the Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

### 2. Get App IDs

Refer to [Keys & IDs](/docs/en/keys-and-ids) to find your `app_id` and `target_app_id`.

***

## Response

The response will include:

* The new `template_id` for the copied template
* Confirmation of successful creation
* Any warnings if applicable (e.g., limited fields copied)

***


# Create an app
Source: https://documentation.onesignal.com/reference/create-an-app

POST /apps
Programmatically create a new OneSignal app via the REST API. This guide explains required fields, supported platform configurations (Web, Android, iOS), and how to properly authenticate using your Organization API key.

## Overview

Use this API to programmatically create a new OneSignal app. This is useful for automating app setup, particularly when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need to Base64 encode your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns):

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates):

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Create API key
Source: https://documentation.onesignal.com/reference/create-api-key

POST /apps/{app_id}/auth/tokens
Use the OneSignal API to create a new Rich Authentication Token (App API Key) for a specific app. This guide explains how to authenticate with the Organization API key and configure optional IP allowlists using CIDR notation.

## Overview

Use this API to create a new **App API Key** (also called a **Rich Authentication Token**) for a specific OneSignal app. These keys are used to authenticate API requests at the app level and offer enhanced security features, including optional IP allowlisting.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

### IP allowlisting

By default, the API key will not be restricted to any specific IP addresses. To enable IP allowlisting, you need to set the `ip_allowlist_mode` parameter to `explicit` and provide a list of allowed IP addresses in the `ip_allowlist` parameter.

If you want to set the explicit range of IPs that can use this API key, add them by setting `ip_allowlist_mode` to `explicit` and in `ip_allowlist` add the IPs in CIDRs notation as an array of string values.

***


# Create segment
Source: https://documentation.onesignal.com/reference/create-segments

POST /apps/{app_id}/segments
Programmatically create segments in your OneSignal app using flexible filters and targeting rules.

## Overview

Use this API to create new [Segments](/docs/en/segmentation) programmatically. These segments are then accessible in the OneSignal Dashboard and usable in messages, Journeys, and in-app messaging campaigns.

<Note>
  To modify an existing segment, use the [Update segment](/reference/update-segment) API.
</Note>

***

## How to use this API

This endpoint allows your backend to define audience segments by passing in a combination of filters and logical operators like `"AND"` and `"OR"`, mirroring the segmentation capabilities of the OneSignal Dashboard.

### Name the segment

The name of the segment as it shows in the OneSignal dashboard and accessible via the `included_segments` and `excluded_segments` targeting parameters.

### Describe the segment

Optionally include a `description` (max 255 characters) to record the segment's purpose. The description is returned by the [View segments](/reference/view-segments) and [View segment](/reference/view-segment) APIs.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "10"}
  ]
}
```

### Define the `filters`

Available filters:

* [operator](#operator)
* [tag](#tag)
* [last\_session](#last_session)
* [first\_session](#first_session)
* [session\_count](#session_count)
* [session\_time](#session_time-1)
* [language](#language)
* [app\_version](#app_version)
* [location](#location)
* [country](#country)

### `operator`

**Description**

Allows you to combine or separate properties. Filters combined with an `"AND"` have higher priority than `"OR"` filters.

* `"AND"` = the 2+ connected filters must be satisfied for the recipient to be included. Filter entries use this by default and its not required to be included.
* `"OR"` = the 2 filters separated by the `"OR"` operator are mutually exclusive. The recipients only need to satisfy the conditions on either side of the `"OR"` operator.

<CodeGroup>
  ```json AND example theme={null}
  // Users must satisfy both filters to be included.
  // Notice the AND operator is not required

  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  // The same example using the AND operator. This is not required.
  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "AND"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  ```

  ```json OR example theme={null}
  // Users can satisfy either filter to be included.

  "filters": [
    {"field": "tag", "key": "level", "relation": "=", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "level", "relation": "=", "value": "20"}
  ]
  ```

  ```json Combinations theme={null}
  // In this example, users must either have:
  // The specified session_count AND tag requirement
  // Or it will be all records where last_session is satisfied
  {
    "name": "2 filters or 1",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"}
    ]
  }

  // Similar to the first example, this shows how to require a specific field
  // across other filters

  {
    "name": "3 filters, 1 required across all",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
    ]
  }
  ```
</CodeGroup>

### `tag`

**Description**

Target based on custom user [Tags](/docs/en/add-user-data-tags).

<Warning>
  Do not use tags for targeting individual users like a "user id".
  Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
</Warning>

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
  * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
* `key` = Tag key to compare.
* `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

```json theme={null}
"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "OR"},
  {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
]
```

### `last_session`

**Description**

Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "last_session", "relation": ">","hours_ago": "10"}
  ]
  ```

### `first_session`

**Description**

Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "first_session", "relation": "<","hours_ago": "24"}
  ]
  ```

### `session_count`

**Description**

Total number of sessions by the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="` or `"!="`
* `value` = number of sessions. Example: `"1"`

  ```json theme={null}
  "filters": [
    {"field": "session_count", "relation": ">","value": "5"}
  ]
  ```

### `session_time`

**Description**

Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

* `relation` = `">"` or `"<"`
* `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

  ```json theme={null}
  "filters": [
    {"field": "session_time", "relation": ">","value": "86400"}
  ]
  ```

### `language`

**Description**

[User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = 2 character language code. Example: `"en"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "language", "relation": "=","value": "en"},
    {"operator": "OR"},
    {"field": "language", "relation": "in_array","value": "es,fr,de"}
  ]
  ```

### `app_version`

**Description**

App version set on the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = app version. Example: `"1.0.0"`
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "app_version", "relation": "=","value": "1.0.1"},
    {"operator": "OR"},
    {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
  ]
  ```

### `location`

**Description**

Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

* `radius` = in meters
* `lat` = latitude
* `long` = longitude

  ```json theme={null}
  "filters": [
    {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
  ]
  ```

### `country`

**Description**

Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "=", "value": "US"},
    {"operator": "OR"},
    {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
  ]
  ```

***


# Export subscriptions CSV
Source: https://documentation.onesignal.com/reference/csv-export

POST /players/csv_export
Generate a GZip-compressed CSV export of your current subscription data using this API endpoint.

## Overview

Use this endpoint to request a GZip-compressed CSV export of all your [Subscriptions data](/docs/en/subscriptions) from OneSignal. The export includes both default and optional user data fields, and supports filters to refine the dataset. The file is downloadable via a URL returned in the API response.

***

## How to use this API

By default, this will export all Subscriptions within the app.

**Optional filters:**

You can narrow the export using:

* `segment_name`: Only export Subscriptions from a specific segment. Segment membership rules determine which subscription statuses are included. Use with `include_unsubscribed` to include unsubscribed subscriptions.
* `last_active_since`: Export Subscriptions where their `last_session` was after a specific Unix timestamp. Example: Use `1704067200` for Subscriptions active since January 1st, 2024.
* `include_unsubscribed`: When exporting a segment, set to `true` to include unsubscribed subscriptions alongside subscribed ones. By default, segment-filtered exports only return subscribed subscriptions. This parameter has no effect when `segment_name` is not provided.

**Example successful response:**

```json 200 OK theme={null}
{
  "csv_file_url": "https://onesignal.com/csv_exports/b2f7f966.../users_1849..._2024-11-10.csv.gz"
}
```

**Export time considerations:**

* Generation speed: \~2,000 records per second.
* File readiness: The `csv_file_url` may return a 404 until generation completes.
* Download retry: Poll the file URL at intervals until the file is ready.
* File expiration: The file remains available for 3 days after generation.
* Concurrency: Only one export per OneSignal account can run at a time.

**File not ready (404 response)**

```xml 404 CSV GET  theme={null}
This XML file does not appear to have any style information
associated with it. The document tree is shown below.
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

<Info>
  You can safely poll the `csv_file_url` until the file becomes available. Implement retry logic based on expected data volume and generation speed.

  Only one export is allowed at a time per account. Wait until the `.csv.gz` file is downloaded before triggering another export.
</Info>

***

## CSV data contents

The export includes two types of fields:

* **Default fields**: Always included unless excluded by schema changes.
* **Extra fields**: Must be explicitly requested using the `extra_fields` parameter.

### Default fields

* `id`: The Subscription ID.

* `identifier`: The push token, email address, or phone number depending on the Subscription type.

* `session_count`: The number of times the user has opened the app.

* `language`: The user's language in ISO 639-1 format.

* `timezone`: Deprecated — use `timezone_id` instead.

* `game_version`: The version of your app that the user is currently using.

* `device_os`: The device's operating system version.

* `device_type`: Integer representing channel/device type.
  * `0`: iOSPush
  * `1`: AndroidPush
  * `2`: FireOSPush
  * `5`: ChromePush
  * `7,17`: SafariPush
  * `11`: Email
  * `14`: SMS

* `device_model`: The device's hardware string.

* `ad_id`: Deprecated.

* `tags`: Custom key/value data.

* `last_active`: The last time the user was active.

* `playtime`: The total amount of time in seconds the user had the mobile app open.

* `created_at`: The first time the user was seen.

* `invalid_identifier`: Boolean flag for unsubscribed state.
  * `t`: Unsubscribed
  * `f`: Subscribed

### Extra fields (`extra_fields`)

Pass `extra_fields` in your request to include any of the following:

* `external_user_id`: Maps to the `external_id` of the user.

* `onesignal_id`: OneSignal's user ID.

* `location`: Adds the `lat` and `long` coordinates if set.

* `country`: The user's country in ISO 3166-1 Alpha 2 format.

* `ip`: The IP address if detected. Can be IPv4 or IPv6 format.

* `web_auth`: Only available to OneSignal SDKs. The `web_auth` key for web push.

* `web_p256`: Only available to OneSignal SDKs. The `web_p256` for web push.

* `unsubscribed_at`: The date and time the user last unsubscribed. They may resubscribe at any time. Check the `invalid_identifier` field to determine if they are currently subscribed.

* `notification_types`: Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/en/subscriptions#notification-types).

* `timezone_id`: The user's timezone in IANA format.

***


# Delete API key
Source: https://documentation.onesignal.com/reference/delete-api-key

DELETE /apps/{app_id}/auth/tokens/{token_id}
Delete a specific Rich Authentication Token (App API Key) for a OneSignal app. Requires your Organization API Key and the token's unique ID, not the token value itself.

## Overview

Use this API to delete a specific App API Key (Rich Authentication Token) for a single OneSignal.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Delete segment
Source: https://documentation.onesignal.com/reference/delete-segments

DELETE /apps/{app_id}/segments/{segment_id}
Delete segments from OneSignal. Does not delete users or subscriptions.

## Overview

The Delete segment method is used when you want to programmatically delete a segment from within the OneSignal Dashboard UI.

<Warning>
  Once a segment is deleted, it cannot be recovered. You will need to create a new segment with the same filters.
</Warning>

***

## How to use this API

You can pass in the `segment_id` dictating which segment from our dashboard will be deleted.

The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard as shown below:

<Frame>
  <img />
</Frame>

***


# Delete player record
Source: https://documentation.onesignal.com/reference/delete-user-record

delete https://onesignal.com/api/v1/players/{player_id}?app_id={app_id}

Delete a player (aka Subscription).

<Warning>
  This is a Legacy API. Use [Delete User](/reference/delete-user) or [Delete Subscription](/reference/delete-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `app_id`    | string | Yes      | Your OneSignal App ID.         |
| `player_id` | string | Yes      | The Subscription ID to delete. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Example Request

```http theme={null}
DELETE /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json
```

***

## Example Response

```json theme={null}
{
  "success": true
}
```

The Subscription will be deleted from the OneSignal database.

***


# Edit player
Source: https://documentation.onesignal.com/reference/edit-device

put https://onesignal.com/api/v1/players/{player_id}

Update a player's (Subscription's) information using the Subscription ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `player_id` | string | Yes      | The OneSignal Subscription ID. |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request.    |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                |
| -------------------- | ------- | -------- | ---------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                     |
| `identifier`         | string  | No       | Push token, email, or phone number.                        |
| `language`           | string  | No       | Language code (e.g., "en").                                |
| `timezone`           | integer | No       | Time zone offset in seconds.                               |
| `game_version`       | string  | No       | App version.                                               |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                         |
| `device_os`          | string  | No       | OS version (e.g., "14.5").                                 |
| `ad_id`              | string  | No       | Advertising ID.                                            |
| `sdk`                | string  | No       | OneSignal SDK version.                                     |
| `tags`               | object  | No       | Custom key-value pairs.                                    |
| `external_user_id`   | string  | No       | Your internal user ID.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc. |
| `email_auth_hash`    | string  | No       | Required to update email identifiers securely.             |
| `sms_auth_hash`      | string  | No       | Required to update SMS identifiers securely.               |

> Only include fields you want to change. Fields left out will not be modified.

***

## Example Request

```json theme={null}
PUT /api/v1/players/player_id_string HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "external_user_id": "user123",
  "tags": {
    "level": "20",
    "subscription": "active"
  },
  "language": "fr",
  "timezone": 3600,
  "device_os": "16.0"
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Missing or invalid fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied.
* 404 Not Found – Device with player\_id not found.

***


# Edit tags with external user id
Source: https://documentation.onesignal.com/reference/edit-tags-with-external-user-id

put https://onesignal.com/api/v1/apps/{app_id}/users/{external_user_id}

Update a player's (Subscription's) information using the External ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter          | Type   | Required | Description             |
| ------------------ | ------ | -------- | ----------------------- |
| `app_id`           | string | Yes      | Your OneSignal App ID.  |
| `external_user_id` | string | Yes      | The user's External ID. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Request Body Parameters

| Field  | Type   | Required | Description                       |
| ------ | ------ | -------- | --------------------------------- |
| `tags` | object | Yes      | Key-value pairs to set or update. |

* To **delete a tag**, set its value to an empty string (`""`).
* Existing tags with the same keys will be **overwritten**.

***

## Example Request

```http theme={null}
PATCH /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json

{
  "tags": {
    "plan": "premium",
    "logged_in": "true",
    "referral": ""
  }
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Invalid request or payload.
* 401 Unauthorized – Invalid or missing keys.
* 403 Forbidden – Access denied due to insufficient permissions.
* 404 Not Found – No players found for given `external_user_id`.

***


# Export audience activity CSV
Source: https://documentation.onesignal.com/reference/export-csv-of-events

POST /notifications/{message_id}/export_events
Export a compressed CSV report of audience-level delivery and engagement data for a specific message. This includes sent, delivered, clicked, failed, and unsubscribed events across Push, Email, and SMS channels.

## Overview

Get a CSV of per-recipient audience activity events (sends, clicks, failures, etc.) for a push, email, or SMS message. This endpoint mirrors the **Export** button in the dashboard's Audience Activity section on each message report:

* [Push message reports](/docs/en/push-notification-message-reports)
* [Email message reports](/docs/en/email-message-reports)
* [SMS message reports](/docs/en/sms-message-reports)

The CSV schema varies by channel. See each channel's message reports page for column definitions.

***

## How to use this API

Get the message `id` from the [Sending messages API](/reference/create-message) or the [View messages API](/reference/view-messages).

A successful request returns `200 OK` with a `csv_file_url`:

```json 200 OK theme={null}
{
    "csv_file_url": "https://onesignal-data.onesignal.com/csv_exports/YOUR_APP_ID/events_audience-activity-YOUR_MESSAGE_ID-push-YYYY-MM-DDTHH-MM-SSTZ.csv.gz"
}
```

The generated file name follows the pattern `events_audience-activity-{message_id}-{channel}-{timestamp}.csv.gz`.

The file is generated at \~2,000 records per second. For large audiences, generation can take several minutes, and the URL may return `404` until the file is ready:

```xml 404 Not Found theme={null}
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

Poll the `csv_file_url` with GET and implement retries with exponential backoff. When the file is ready, the GET request downloads the `.csv.gz` file.

<Info>
  * The CSV download URL is valid for **3 days** after creation.
  * File names include a random UUID to prevent guessing.
</Info>

<Warning>
  Only **one concurrent export** is allowed per OneSignal account. Download the `.csv.gz` file before starting another export, or the new request fails.
</Warning>

***


# Rotate API key
Source: https://documentation.onesignal.com/reference/rotate-api-key

POST /apps/{app_id}/auth/tokens/{token_id}/rotate
Rotate an existing App API Key (Rich Authentication Token) for a OneSignal app. Useful when a token is compromised or needs replacement without creating a new key from scratch.

## Overview

Use this API to rotate a **Rich Authentication Token** (App API Key) for a specific OneSignal app. Rotating a key revokes the current token and generates a new one under the same configuration—ideal when a token is lost or compromised but you don’t want to recreate and reconfigure it from scratch.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can rotate an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Update an app
Source: https://documentation.onesignal.com/reference/update-an-app

PUT /apps/{app_id}
Use to update the name or push platform configuration of an existing app. This guide explains required parameters and platform-specific update rules

## Overview

Use this API to programmatically update an existing OneSignal app. This is useful when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

***

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Warning>
  If you change your FCM Service Account JSON file to a different Firebase project, your Android Subscriptions tied to the current project will become invalid. They will not be able to receive push notifications until they open your app again with this new FCM Service Account JSON file.
</Warning>

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need help Base64 encoding your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns). **You will likely never need to update these parameters if set correctly during app creation**:

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates). **These must be updated every year which is why we recommend using p8 authentication**:

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Update API key
Source: https://documentation.onesignal.com/reference/update-api-key

PATCH /apps/{app_id}/auth/tokens/{token_id}
Update a Rich Authentication Token (App API Key) for a OneSignal app. Modify the token's name or IP allowlist settings using your Organization API Key.

## Overview

Use this API to update the properties of a specific **Rich Authentication Token** (App API Key) for a OneSignal app. You can change the name, IP allowlist mode, or the list of allowed IPs. This is helpful for adjusting access rules without needing to recreate the key.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Update segment
Source: https://documentation.onesignal.com/reference/update-segment

PATCH /apps/{app_id}/segments/{segment_id}
Update an existing segment's name and/or filters. The name parameter is always required. When filters are provided, all existing filters are replaced with the new ones.

## Overview

Update an existing segment's name and/or filters. This API allows you to modify [Segments](/docs/en/segmentation) programmatically without having to delete and recreate them.

<Note>
  The `name` parameter is always required, even if you're not changing it. When filters are provided, all existing filters are **replaced** with the new ones. Omit the `filters` parameter to keep existing filters intact. The `filters` array cannot be empty—if provided, it must contain at least one filter.
</Note>

***

## How to use this API

### Update segment name only

To update just the segment name without changing filters:

```json theme={null}
{
  "name": "New Segment Name"
}
```

### Update segment description

Update the optional `description` (max 255 characters). Pass an empty string to clear the existing description; omit the field to leave it unchanged.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION"
}
```

### Update segment filters

To update the segment filters (this replaces all existing filters), provide the `name` (required) and `filters`:

```json theme={null}
{
  "name": "Updated Segment",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "5"},
    {"operator": "AND"},
    {"field": "tag", "key": "subscription", "relation": "=", "value": "premium"}
  ]
}
```

### Filter syntax

The filter syntax is identical to the [Create segment](/reference/create-segments) API. Available filters include:

* `tag` - Filter by Tags
* `last_session` - Filter by last active time
* `first_session` - Filter by first session time
* `session_count` - Filter by number of sessions
* `session_time` - Filter by total usage duration
* `language` - Filter by user language
* `app_version` - Filter by app version
* `location` - Filter by GPS coordinates
* `country` - Filter by country

Use `AND` and `OR` operators to combine filters:

```json theme={null}
{
  "name": "Engaged Premium Users",
  "filters": [
    {"field": "tag", "key": "plan", "relation": "=", "value": "premium"},
    {"operator": "AND"},
    {"field": "session_count", "relation": ">", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "vip", "relation": "=", "value": "true"}
  ]
}
```

***

## Response

### Success response

```json theme={null}
{
  "success": true,
  "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19"
}
```

### Error responses

| Status Code | Description                                                                              |
| ----------- | ---------------------------------------------------------------------------------------- |
| 400         | Bad request - Invalid filters, duplicate segment name, or segment used by active Journey |
| 403         | Forbidden - API not available for your plan                                              |
| 404         | Not found - Segment does not exist                                                       |
| 429         | Rate limit exceeded                                                                      |

***


# View an app
Source: https://documentation.onesignal.com/reference/view-an-app

GET /apps/{app_id}
View the details of a single OneSignal app

## Overview

Use this API to retrieve metadata and platform configuration for a single OneSignal app associated with your account. This includes app names, App ID, Subscription counts, timestamps, and push platform credentials (Android/FCM, iOS/APNS, Web Push, Safari), making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

***

## How to use this API

To retrieve your app, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View API keys
Source: https://documentation.onesignal.com/reference/view-api-keys

GET /apps/{app_id}/auth/tokens
View the details of all of your current app API keys (Rich Authentication Token) for a single OneSignal app.

## Overview

This API is helpful for auditing and managing the API keys (Rich Authentication Tokens) associated with an app. It returns metadata for each token, including:

* Token name and ID
* IP allow list mode and associated CIDR ranges (if any)
* Creation and last updated timestamps

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

***


# View apps
Source: https://documentation.onesignal.com/reference/view-apps

GET /apps
Retrieve a list of all OneSignal apps associated with your account, including key app details like name, App ID, subscription counts, and timestamps. Useful for managing multiple apps through the OneSignal API.

## Overview

Use this API to retrieve metadata for all OneSignal apps associated with your account. This includes app names, App IDs, subscription counts, and timestamps, making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

<Warning>
  This API is limited to return a maximum of 1000 Apps. If you need access to more, then you should store the `app_id` and `name` for each of your apps on your own server to look up with the [View an app](/reference/view-an-app) API to get data for each app separately. Also, if you need to delete apps, then you can provide the `app_id` and `name` to OneSignal Support and ask for these to be deleted.
</Warning>

***

## How to use this API

To retrieve your apps, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View player
Source: https://documentation.onesignal.com/reference/view-device

GET https://onesignal.com/api/v1/players/{player_id}

Retrieve a single player record (Subscription) data registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `player_id` | string | Yes      | The OneSignal ID of the device. |

***

## Query Parameters

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `app_id`  | string | Yes      | Your OneSignal App ID. |

***

## Headers

| Header          | Value                            | Required | Description                        |
| --------------- | -------------------------------- | -------- | ---------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal LegacyREST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players/player_id_string?app_id=your_app_id HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json{ theme={null}
  "id": "player_id_string",
  "identifier": "push_token_or_email",
  "session_count": 5,
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_os": "14.4",
  "device_type": 1,
  "tags": {
    "level": "10",
    "user_type": "free"
  },
  "last_active": 1625253300,
  "created_at": 1625249800,
  "invalid_identifier": false,
  "external_user_id": "user123"
}
```

### Response Fields

| Field                | Type      | Description                                             |
| -------------------- | --------- | ------------------------------------------------------- |
| `id`                 | string    | OneSignal player ID.                                    |
| `identifier`         | string    | Push token, email, or phone number.                     |
| `session_count`      | integer   | Number of sessions associated with this device.         |
| `language`           | string    | Language set on the device (e.g., "en").                |
| `timezone`           | integer   | Time zone offset in seconds.                            |
| `game_version`       | string    | Version of your app the device is running.              |
| `device_os`          | string    | Operating system version.                               |
| `device_type`        | integer   | Numeric code for platform (0 = iOS, 1 = Android, etc.). |
| `tags`               | object    | Custom tags set on the device.                          |
| `last_active`        | timestamp | Last time the user was active (Unix timestamp).         |
| `created_at`         | timestamp | When the device record was created.                     |
| `invalid_identifier` | boolean   | Whether the push token or identifier is invalid.        |
| `external_user_id`   | string    | Your internal user ID mapped to this device.            |

***

## Errors

* 400 Bad Request – Missing or invalid parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied for this app or resource.
* 404 Not Found – The specified player\_id does not exist.

***


# View players
Source: https://documentation.onesignal.com/reference/view-devices

GET `https://onesignal.com/api/v1/players?app_id={app_id}&limit={limit}&offset={offset}`

Retrieve up to 80,000 player records (Subscriptions) registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Query Parameters

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `app_id`  | string | Yes      | Your OneSignal App ID.                                 |
| `limit`   | int    | No       | Number of entries to return (max 300, default is 300). |
| `offset`  | int    | No       | Result offset for pagination.                          |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players?app_id=your_app_id&limit=100&offset=0 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json theme={null}
{
  "total_count": 6,
  "offset": 0,
  "limit": 300,
  "players": [
    {
      "id": "player_id_1",
      "identifier": "push_token_or_email",
      "session_count": 3,
      "language": "en",
      "timezone": -28800,
      "game_version": "1.0",
      "device_os": "15.0",
      "device_type": 1,
      "tags": {
        "level": "15",
        "user_type": "free"
      },
      "last_active": 1625253300,
      "created_at": 1625249800,
      "invalid_identifier": false,
      "external_user_id": "user123"
    }
  ]
}
```

### Response Fields

| Field                        | Type    | Description                                  |
| ---------------------------- | ------- | -------------------------------------------- |
| `total_count`                | integer | Total number of devices for the app.         |
| `offset`                     | integer | Current pagination offset.                   |
| `limit`                      | integer | Number of devices returned in this response. |
| `players`                    | array   | List of device objects.                      |
| `players[].id`               | string  | Unique OneSignal player ID.                  |
| `players[].identifier`       | string  | Push token, email, or phone number.          |
| `players[].tags`             | object  | Custom tags set on the device.               |
| `players[].external_user_id` | string  | Your internal user ID.                       |

***

## Errors

* 400 Bad Request – Invalid query parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access not allowed for this app or key.

***


# View outcomes
Source: https://documentation.onesignal.com/reference/view-outcomes

GET /apps/{app_id}/outcomes?outcome_names={outcome_names}&outcome_time_range={outcome_time_range}&outcome_platforms={outcome_platforms}&outcome_attribution={outcome_attribution}
View and export push notification outcome metrics such as clicks, conversions, and custom events.

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

## Overview

Use this API to retrieve Outcome metrics associated with your OneSignal app, including push notification interactions and custom-defined events. Outcomes include data points like:

* **Clicks**: Number of users who clicked on a push.
* **Confirmed Deliveries**: Number of confirmed message deliveries.
* **Session Durations**: Number of sessions initiated.
* **Custom Events**: Actions like purchases, form submissions, or any event your app tracks via custom Outcome names.

For details on configuring custom Outcomes, refer to the [Outcomes documentation](/docs/en/custom-outcomes).

<Info>
  Outcomes are stored for approximately 30 days. To retain this data, you should regularly export it before it expires.
</Info>

***

## How to use this API

This API allows you to filter and aggregate Outcome data using several query parameters.

### `outcome_names`

Specify one or more Outcome names with an aggregation type suffix (`.count` or `.sum`).

**Default Outcome names:**

* `os__click.count` – Push notification clicks.
* `os__confirmed_delivery.count` – Confirmed deliveries.
* `os__session_duration.count` – Total sessions.

**Custom Outcome names:**

* You can track any custom event name (e.g. `Purchase`, `Signup`).
* If the custom name contains a comma, include only one name per request to avoid parsing issues.
* Example: `outcome_names=os__click.count,Purchase.count`

### `outcome_time_range`

The time range values can be one of the following:

* `1h` = (default) the last 1 hour data.
* `1d` = the last 1 day data.
* `1mo` = the last 1 month data.

### `outcome_platforms`

Maps to the subscription type property. Default is data from all platforms enabled for your OneSignal App.

| `device_type` | `type`      |
| ------------- | ----------- |
| 0             | iOSPush     |
| 1             | AndroidPush |
| 2             | FireOSPush  |
| 5             | ChromePush  |
| 8             | FirefoxPush |
| 11            | Email       |
| 14            | SMS         |
| 17            | SafariPush  |

Example: `outcome_platform=0` for iOS `outcome_platform=17,8` for Safari and Firefox.

### `outcome_attribution`

The way in which the Outcome occurred:

* `direct` = the Outcome occurred when the user interacted with the message. Some Outcomes only have `direct` attribution like `os__click` and `os__confirmed_delivery` because they only occur as the direct result of the message.
* `influenced` = the Outcome occurred within the Time Window of the message being sent, but the user never interacted with the message. See [Outcomes](/docs/en/custom-outcomes) for details.
* `unattributed` = the Outcome occurred without a direct or influenced attribute.
* `total` = (default) the sum of direct+influenced+unattributed.

***


# View segment
Source: https://documentation.onesignal.com/reference/view-segment

GET /apps/{app_id}/segments/{segment_id}
Retrieve details for a single segment by its ID, including subscriber count and optionally segment metadata and filters.

## Overview

Retrieve details for a single segment by its ID. By default, this endpoint returns only the subscriber count. Use the optional `include-segment-detail` parameter to also retrieve segment metadata and filters.

<Note>
  The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard.
</Note>

<Warning>
  **User-based segments not supported**: Segments containing message event or custom event filters (user-based segments) are not yet supported via this API. Attempting to fetch these segments will return a 400 error. These segments can only be managed through the dashboard UI.
</Warning>

***

## How to use this API

### Basic usage

By default, this endpoint returns only the subscriber count for the segment:

```json theme={null}
{
  "subscriber_count": 12345
}
```

### Include segment details

To retrieve full segment details including metadata and filters, set `include-segment-detail=true`:

```
GET /apps/{app_id}/segments/{segment_id}?include-segment-detail=true
```

This returns the subscriber count along with a `payload` object containing segment details:

<CodeGroup>
  ```json Simple filter theme={null}
  {
    "subscriber_count": 12345,
    "payload": {
      "id": "4414c404-56a3-11ed-9b6a-0242ac120002",
      "name": "Subscribed Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {
          "field": "session_count",
          "relation": ">",
          "value": "5"
        }
      ]
    }
  }
  ```

  ```json With AND/OR operators theme={null}
  {
    "subscriber_count": 5678,
    "payload": {
      "id": "5525d515-67b4-22fe-0c7b-1353bd231113",
      "name": "Engaged Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {"field": "session_count", "relation": ">", "value": "2"},
        {"operator": "AND"},
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "last_session", "relation": "<", "hours_ago": "24"}
      ]
    }
  }
  ```
</CodeGroup>

### Filters format

The `filters` array uses the **same format** as the [Create segment](/reference/create-segments) API. This means you can:

* Read filters from this endpoint
* Modify them as needed
* Use them directly with the [Update segment](/reference/update-segment) or [Create segment](/reference/create-segments) APIs

The array contains filter objects and operator objects:

**Filter object** - defines a condition:

| Field                   | Type    | Description                                                                                                                                         |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field`                 | string  | The filter type: `tag`, `last_session`, `first_session`, `session_count`, `session_time`, `language`, `app_version`, `location`, `country`, `email` |
| `relation`              | string  | The comparison operator: `>`, `<`, `=`, `!=`, `exists`, `not_exists`, `in_array`, `not_in_array`, `time_elapsed_gt`, `time_elapsed_lt`              |
| `value`                 | string  | The filter value (for most filter types)                                                                                                            |
| `key`                   | string  | The filter key (required for `tag` filters)                                                                                                         |
| `hours_ago`             | string  | Hours ago value (for `last_session`/`first_session` filters)                                                                                        |
| `radius`, `lat`, `long` | string  | Location parameters (for `location` filters)                                                                                                        |
| `unsupported_in_api`    | boolean | If `true`, this filter cannot be used with Create/Update segment APIs (see note below)                                                              |

**Operator object** - combines filters:

| Field      | Type   | Description                                                                        |
| ---------- | ------ | ---------------------------------------------------------------------------------- |
| `operator` | string | Either `AND` or `OR`. Filters connected with `AND` have higher priority than `OR`. |

<Warning>
  Some segments created via the dashboard UI may contain filter types not supported by the public API (e.g., `message_event`, `custom_event`). These filters will include `unsupported_in_api: true`. You cannot use these filters when creating or updating segments via the API.
</Warning>

### Payload fields

| Field         | Type           | Description                                                                         |
| ------------- | -------------- | ----------------------------------------------------------------------------------- |
| `id`          | string         | The unique identifier for the segment (UUID v4).                                    |
| `name`        | string         | The segment name (max 128 characters).                                              |
| `description` | string \| null | Human-readable description for the segment (max 255 characters). `null` when unset. |
| `created_at`  | integer        | Unix timestamp when the segment was created.                                        |
| `source`      | string         | The source of the segment: `default`, `custom`, or `quickstart`.                    |
| `filters`     | array          | Array of filter and operator objects that define the segment criteria.              |

***


# View segments
Source: https://documentation.onesignal.com/reference/view-segments

GET /apps/{app_id}/segments
Retrieve a list of segments associated with a specific OneSignal app. Useful for programmatically accessing segment metadata such as name, creation date, and status.

## Overview

Retrieve a list of segments associated with a specific OneSignal app. This is helpful when you want to access segment metadata programmatically instead of using the OneSignal Dashboard UI.

<Warning>
  This endpoint only retrieves existing segment metadata. It does not provide the segment filters or user data.
</Warning>

***


# Changelog
Source: https://documentation.onesignal.com/release-notes/changelog

Learn about the latest updates to OneSignal.

Follow along with updates across OneSignal. We're launching new features and improving our product all the time!

<Update label="June 18 2026">
  **AI-assisted SDK installation updated and expanded**

  * AI install prompts have been rewritten and expanded to cover Android, iOS, React Native, Flutter, and Web SDKs.
  * Paste a single ready-made prompt into your AI coding assistant (Cursor, Claude, Copilot, or similar) and the assistant installs the SDK, drops in initialization code, and configures push and in-app messaging automatically.
  * No deep development experience required — marketers and non-technical users can complete SDK setup in minutes.
  * Prompt instructions were revised to fix errors identified during internal testing, so generated integrations are more accurate.
  * Available to all new sign-ups with no enablement required; requires an AI coding tool and access to the app codebase.
</Update>

<Update label="June 15 2026">
  **Extended `in_array` and `not_in_array` relations to the Device Type filter**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `device_type` filter field. Use them to match against a comma-separated list of device types in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "device_type", "relation": "in_array", "value": "iOS,Android"},
    {"operator": "AND"},
    {"field": "device_type", "relation": "not_in_array", "value": "Email"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="June 15 2026">
  **RCS editor experience improvements**

  We've improved how you build and send RCS, giving you a more intuitive editor, clearer approval visibility, and a more graceful SMS fallback experience:

  * **See carrier approval status in settings.** Each sender resource's carrier approval status is now visible at **Settings > SMS > Senders**, so you can track where each carrier stands in the approval process without leaving the dashboard.
  * **Select a sender per RCS template.** In Templates you now choose a specific sender instead of relying on a single global default, improving how RCS sends within Journeys and giving you automations for multiple SMS use cases.
  * **A more intuitive editor.** The composer automatically shows the right editor for the selected sender — the RCS editor for senders with an RCS resource, and the SMS editor for SMS-only senders.
  * **Text only RCS.** A new Text only content type sends plain branded RCS text.

  When a sender gains an approved RCS sending resource, OneSignal automatically prefers RCS for existing automations on that sender, mapping your existing SMS content to RCS so there's no manual rework.

  Available for all customers contracted for RCS. See [RCS messaging](/docs/en/rcs-messaging) for details.
</Update>

<Update label="June 8 2026">
  **Segment editor improvements: multi-value filters, copy filters, and filter JSON**

  Building segments in the dashboard is now faster and more flexible:

  * **Match multiple values in one filter.** The Language, Country, App Version, and User Tag filters now support the "is any of" and "is not any of" relations, so you can match a list of values in a single filter instead of chaining several filters with OR.
  * **Copy filters and filter groups.** Duplicate an individual filter or an entire filter group from the editor to reuse its configuration without rebuilding it by hand.
  * **View and copy filter JSON.** Open the filter JSON panel to see the REST API representation of your segment's filters, then copy it to use directly in the [Create segment](/reference/create-segments) API.
</Update>

<Update label="June 4 2026">
  **Retired Alexa and Windows Phone 8.0 as Device Type filter options**

  The `Alexa` and `Windows Phone 8.0` values are no longer available for the Device Type filter when you create or edit a segment, in both the dashboard and the Create segment API. Selecting either value in the dashboard is no longer possible, and the API rejects them with a validation error.

  Existing segments that already use these values continue to evaluate and deliver as before. To save changes to such a segment, replace the retired Device Type filter first.
</Update>

<Update label="June 2 2026">
  **Extended `in_array` and `not_in_array` relations to tag and app version filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `tag` and `app_version` filter fields, in addition to the `country` and `language` fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"},
    {"operator": "AND"},
    {"field": "app_version", "relation": "not_in_array", "value": "1.0.0,1.0.1"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="May 11 2026">
  **Email BCC is now generally available**

  You can now add BCC (blind carbon copy) recipients to email sends, including templates used in journeys and messages sent via the API. Use BCC to archive customer-facing email to a shared inbox or compliance system, forward sends to third-party services, or keep internal stakeholders copied on transactional sends.

  * Available on all plan types.
  * Maximum of 5 BCC addresses per send.
  * Each BCC recipient counts toward the total email volume for that send (for example, 1,000 primary recipients with 1 BCC address = 2,000 sends).
  * BCC metrics are excluded from analytics.

  See [BCC emails](/docs/en/email-bcc) for setup and usage details.
</Update>

<Update label="May 12 2026">
  **Added `in_array` and `not_in_array` relations for country and language filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `country` and `language` filter fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "in_array", "value": "US,GB,CA"},
    {"operator": "AND"},
    {"field": "language", "relation": "not_in_array", "value": "es,fr"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="April 21 2026">
  **Manage custom aliases from the User Profile**

  You can now view, add, edit, and delete a user's custom aliases directly from the **Aliases** section on the User Profile **Overview** tab, without using the API.

  * Add an alias by entering a label (alias key) and value (alias ID), copy any alias value to the clipboard, edit a value, or remove an alias.
  * Each user supports up to 10 aliases, and alias labels and values can each contain up to 128 characters.
  * `external_id` and `onesignal_id` are reserved and can't be used as custom alias labels.
  * A user must have an External ID set before you can add custom aliases. External ID is still managed separately in the Profile section.

  See [Aliases](/docs/en/aliases) for more details.
</Update>

<Update label="April 17 2026">
  **Role-based access control (RBAC) is now generally available**

  Granular role-based access control has been rolled out to all customers, giving teams more flexibility to support least-privilege access patterns and manage permissions as they scale.

  * **New `team_member` org-level default role.** A baseline role for new users added to an organization.
  * **New `composer` app-level role.** Lets users create and edit messages, templates, segments, and journeys without sending, activating, or deleting content.
  * **Updates to `editor` and `viewer` roles.** Refined permissions for clearer separation of duties.
  * Available roles vary by plan type.

  See [Manage team members](/docs/en/manage-team-members) for the full breakdown of roles, permissions, and plan availability.
</Update>

<Update label="April 16 2026">
  **Light/dark mode toggle for HTML in-app message previews**

  You can now switch between light and dark mode directly in the dashboard when previewing HTML in-app messages, so what you see matches what your users will actually see.

  * A light/dark mode toggle is now available in the in-app message preview for HTML messages.
  * The preview no longer reflects your OS theme. It reflects the mode you select in the dashboard.
  * Previously, the preview always rendered using whatever theme your own computer was set to, with no indication that was the cause, so there was no reliable way to check dark mode designs from the dashboard.

  HTML in-app messages do not automatically get a dark mode. The message still has to be coded for it using `@media (prefers-color-scheme: dark)` styles. If your message doesn't include those styles, toggling to dark mode in the preview won't change how it looks.

  The toggle is available for HTML in-app messages only. Block-type in-app messages are not included in this release. Generally available for all customers using HTML in-app messages.

  See [Design your in-app message with HTML](/docs/en/design-your-in-app-message-with-html) for how to add dark mode support.
</Update>

<Update label="April 15 2026">
  **Standardized delivery metrics across all channels**

  Delivery metric terminology is now consistent across every messaging channel in OneSignal. All channels now share a unified delivery hierarchy: Audience → Sent → Delivered, with the same definitions everywhere. Labels have been aligned across delivery reports, journey reports, engagement trends, and CSV exports. The [Metrics Glossary](/docs/en/analytics-metrics-glossary) has been fully rewritten as the canonical reference for every metric definition.
</Update>

<Update label="April 10 2026">
  **Audience counts now show subscribed and unsubscribed breakdowns**

  The segment editor now shows both subscribed and unsubscribed counts for every subscription-based segment, with a per-channel breakdown across push, email, and SMS. Previously, only the opted-in (subscribed) count was visible.

  Additional improvements:

  * Counts always return within approximately 15 seconds. Exact counts are shown when possible; estimates are used when an exact count can't be calculated in time.
  * Estimates are clearly labeled: above 10,000 with a +/- margin of error (e.g. 140,000 +/- 5,000), and below 10,000 as a less-than value (e.g. \<4,800).
  * Estimates will never show 0 for a segment. Previously for segments with very small but non-zero membership, estimates could incorrectly show as 0.

  This release covers subscription-based segments. User-based segment improvements are coming later in Q2 2026.
</Update>

<Update label="April 7 2026">
  **Updated User Profile page**

  The User Profile page has been redesigned with a tabbed layout and several new management actions directly on the page:

  * Add and remove Subscriptions from a User
  * Search across a User's data tags
  * Perform more direct edits and admin actions without leaving the profile

  The previous profile view is still accessible from the **Actions** menu if you need it.
</Update>

<Update label="March 25 2026">
  **test users now apply at the User level**
  Marking a Subscription as a test user now automatically marks all Subscriptions for that User as test users, effectively creating a Test User.

  * Any new Subscriptions added to a Test User will automatically be marked as test users.
  * Test User is now a User-level property rather than a Subscription-level one.

  **OneSignal Server SDKs just got their first v5 stable release!**

  After a period of testing and iteration, v5 is now the default version users will get when installing any of our server SDKs. Here are the current versions included in this release:

  | Language | Version |
  | -------- | ------- |
  | Node.js  | 5.4.0   |
  | Go       | 5.3.0   |
  | Java     | 5.3.0   |
  | .NET     | 5.4.0   |
  | Rust     | 5.3.0   |
  | Ruby     | 5.3.0   |
  | Python   | 5.3.0   |
  | PHP      | 5.3.0   |

  This release pairs well with our recently refreshed Server SDK Reference, giving developers a solid starting point for integrating with the OneSignal API.
</Update>

<Update label="March 20 2026">
  **Audit Log Export is now in GA**

  * Customers can now export audit logs. Customers can export 2 days for free tier and up to 90 days with security and legal entitlement (either as individual SKU or enterprise plan).
  * Provides customers additional metadata details and allows them to filter through data locally for their own audits and consumption with their own tools.

  **Failed Reasons in Audience Activity for everyone!**

  * Free plan users can now see exactly why individual audience members failed to receive a notification — directly in the Audience Activity view.
  * When a notification fails, especially common when troubleshooting set up, free users had no way to know whether the problem was a bad token, an unsubscribed user, or a device issue — leaving them guessing and unable to fix anything. Now they get the same failure visibility paid users have, so they can debug and get set up properly.
  * Same data retention as audience activity (30 days)
</Update>

<Update label="March 17 2026">
  **Data Model Updates and Field Deprecations**

  To improve platform performance, strengthen data integrity, and reduce the risk of configuration errors, we are introducing several updates to the OneSignal data model.

  These changes will take effect **April 15, 2026.**

  **Field Limits**

  We are introducing limits on two user fields to improve consistency and prevent unexpected behavior.

  Existing records exceeding these limits will not be modified to avoid disrupting current data and operations.

  **External ID**

  * `external_id` values can contain up to 128 characters.

  **Aliases**

  * Each user can have up to 10 aliases.
  * Each alias key and value can contain up to 128 characters.

  **Field Deprecations**

  We are deprecating several legacy Subscription fields that are no longer actively used:

  * `amount_spent`
  * `rooted`
  * `bought_sku`
  * `app_interests`
  * `purchased_items`

  After April 15, 2026, these fields will no longer be available in:

  * Segment Builder
  * API requests
  * Event streams
  * Webhooks

  **Impact for Customers Using These Fields**

  If your implementation currently references any of these fields:

  **Segments:** Segments using these fields will be paused and labeled for your review.

  **Journeys:** Journeys depending on those segments will be archived.

  **Event Streams and Webhooks:** These fields will return empty values.

  **What You Need to Do**

  Most customers do not need to take any action.

  If your implementation relies on any of the deprecated fields, we recommend reviewing your segments and integrations before **April 15, 2026.**
</Update>

<Update label="March 6 2026">
  Email Address Validation is now available!

  * When email addresses are added to OneSignal, they're now validated at three entry points:
    * API: syntax check
    * CSV import: full validation including typo detection, MX record lookup, disposable email flagging, and role-based address detection\*
    * Bulk validation: same full checks, runs against addresses already in your audience
  * Free plans have syntax and typo checks.
  * Paid plans will have syntax, typo, MX, disposable email, and role based email address checks.

  See [Email Address Validation](/docs/en/email-address-validation) for more details.
</Update>

<Update label="March 4 2026">
  **Dashboard layout redesign has shipped!**

  * Panel-based layout. The old floating card approach has been replaced with flat panels. The side nav sits in a clean gray panel, and the main content in a white panel. This simplifies the look and feel and gives us a more modern aesthetic.
  * New global top bar. Breadcrumbs, the new Create menu, Help/Support links, and Upgrade button all live in a new sticky top bar that follows you on scroll.

  **Richer date context across the dashboard**

  Dates show up everywhere in OneSignal — denoting message creation, notification send times, user sessions, etc. — but it wasn't always clear which timezone you were looking at, or how recent something actually was. This came up in a discussion last week among the dashboard engineers.

  Now, hovering over a date in the following areas of the Dashboard shows a tooltip with three pieces of context at once: the time in your local timezone, the time in UTC, and a relative timestamp (like "2 days ago").

  Where you'll see it:

  * Message lists and indexes
  * Message reports
  * Message review modals before sending
  * User and subscription profiles

  This is enabled for all apps — no action needed. Just hover a date and it's there!

  **In-App Message library with new quickstarts!**

  We've shipped a library of professionally designed, ready-to-use in-app message templates — available now to all plans in the dashboard.

  What's in it: 7 categories of quick starts covering the most common IAM use cases: push soft prompts, promotions, onboarding flows, feature announcements, location prompts, spin-to-win, and notification preference centers.

  How to access: Dashboard → Messages → In-App → New In-App → OneSignal Quick Starts. No feature flag or backend enablement required — available immediately. (See demo for the full experience in product)

  Go from zero to a production-ready in-app message in minutes, without writing HTML from scratch!
</Update>

<Update label="March 3 2026">
  **Enhanced Snowflake Integration Now Available!**

  Key improvements include:

  * 15-minute sync intervals (down from 24 hours)
  * Selective event syncing so customers only export what they need
  * Self-service setup directly in the OneSignal dashboard
  * New events like in-app impressions, email bounced/received, and separated Live Activity events.
  * We've also added richer properties including Template ID, last active timestamp, and subscription status.

  Customers get near real-time data in their Snowflake instance with full control over what gets synced meaning faster insights. Selective syncing alone can dramatically reduce event volume (and spend) by letting them export only the events that they need.

  This moves from the legacy flat annual fee to our Event Streams pricing model. Customers pre-purchase an event volume tier, and that tier covers all destinations (Snowflake, BigQuery, Databricks, etc.).

  Live now for all customers. All new customers will automatically have access to this new integration. Existing legacy Snowflake customers have until August 1st to migrate to the new integration before deprecation. Both integrations can run in parallel during the transition so they can ensure parity/consistency, and we will be doing outreach to those affected shortly.

  See [Snowflake](/docs/en/snowflake) for more details.
</Update>

<Update label="February 26 2026">
  **Audit Logs API is now available**

  Enterprise customers (with Legal & Security package) can now programmatically access the same audit log data surfaced in the OneSignal dashboard — pipe it directly into their SIEM, compliance tooling, or internal security workflows.

  * Returns a time-scoped record of actions taken in their org — who did what, when, and from where
  * Filter by app, action type, actor, target, or IP address
  * Supports cursor-based pagination for large result sets

  See [Audit Logs API](/reference/list-audit-logs) for more details.
</Update>

<Update label="February 9 2026">
  Huawei Badge Parameter Support

  We now support app icon badges on Huawei (HMS) devices via both the API and dashboard.

  * What's new: Three new parameters on `Notification#Create`
    * `huawei_badge_class` — the app's launcher activity class name (required for badge)
    * `huawei_badge_set_num` — set the badge to an exact number (0–99)
    * `huawei_badge_add_num` — increment the badge by a specific amount (1–99)

  On the dashboard, you'll see a new Badge option under Send to Huawei Android with "Don't set" / "Set to" / "Increase by" options.

  * Good to know:
    * Setting `huawei_badge_set_num` to 0 clears the badge
    * If neither set nor add is specified, the badge increments by 1 by default
    * Huawei does not auto-clear badges when the app opens
</Update>

<Update label="January 29 2026">
  API Documentation Improvements

  * New API endpoint: [View Segment](/reference/view-segment) - Retrieve details of a specific segment by ID, including optional segment filter details.
  * New API endpoint: [Update Segment](/reference/update-segment) - Update an existing segment's name and/or filters programmatically.
  * Fixed JSON example formatting across multiple API reference pages for improved readability:
    * Segments API: view-segments, create-segments, delete-segments
    * Users API: create-user, view-user, update-user, delete-user
    * Subscriptions API: create-subscription, delete-subscription, transfer-subscription, unsubscribe-with-token, create-alias-by-subscription
</Update>

<Update label="January 26 2026">
  **Audit Logs are now available!**

  * Customers now have the ability to determine exactly what's happening across their OneSignal account. Audit Logs gives them a complete timeline of every action taken in their organization—who did what, when, and from where.
  * Track 50+ action types including:
    * Authentication events (login, logout, API key operations)
    * Message activity (notifications sent, canceled, A/B tests, Journeys)
    * Team changes (member added, role changed, removed)
    * Configuration updates (webhooks, segments, templates, integrations)
    * Billing & subscription events
  * Powerful filtering:
    * Search by team member email
    * Filter by action type, app, IP address, or item type
    * Custom date ranges with presets
    * Shareable filtered URLs—customers can collaborate with their team instantly
  * Deep visibility:
    * Expandable rows reveal 30+ fields: IP address, browser, location, correlation ID, API version, and more
    * Available at both App and Organization levels
    * Quick-access links from Journeys, Segments, Templates, Notifications, and more
  * Retention:
    * Legal & Security package: 90-day lookback
    * All other plans: 2-day lookback
  * Perfect for security audits, debugging, and understanding team activity at a glance.
</Update>

<Update label="January 9 2026">
  * Standardized time series for charts are now available for:
    * Event Streams and webhooks
    * Email delivery reports
    * SMS/RCS delivery reports
</Update>

<Update label="December 22 2025">
  * confirmed receipt Now Available On Engagement Trends
    * Customers with access to confirmed receipt can now see confirmed receipt on the Engagement Trends Time Series Chart.
    * This missing data was a common point of confusion for customers. They could see confirmed receipt & click through rate, but had no access to the total confirmed deliveries metric.
    * This additional data point gives customers confidence in the rates we're showing and helps with confusion on the difference between "delivered" and "Confirmed receipt" for push notifications.
</Update>

<Update label="December 12 2025">
  * New integration - Self-serve Snowflake data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake without going through customer support
    * The legacy Snowflake documentation remains available for existing implementations
</Update>

<Update label="December 8 2025">
  Live Activities in Event Streams & Integrations

  Live Activities Analytics provides two key capabilities to optimize customers' live activity strategy:

  1. Better Troubleshooting with confirmed receipt
     Gain visibility into whether devices actually received live activity updates. confirmed receipt tracking identifies delivery issues quickly to understand the true reach of live activities.
     Available in:

  * Individual message reports with per-device confirmation
  * Data exports to BI tools (through event streams and integrations)

  2. Deeper Engagement Insights with data exports to integrations & event streams
     Answer critical questions about how users interact with your live activities:

  * How many users engaged with my live activity over its duration?
  * When did users drop off?
  * What was the peak engagement time?
  * When did users click? (coming soon)

  Export live activity data to BI tools to analyze engagement patterns, optimize timing, and improve future campaigns.
</Update>

<Update label="December 5 2025">
  We've launched a new [Metrics Glossary](/docs/en/analytics-metrics-glossary) in our documentation. This resource provides a single source of truth for delivery metric definitions, helping both our team and customers understand our metrics consistently across dashboards, APIs, and exports.
  While we continue working toward unified terminology across all touch points, this glossary establishes clear mappings and definitions as they exist today, making it easier for customers to navigate our current analytics landscape.

  Custom Events in User Activity Timeline
  Custom events are now visible per User on their profile page in a dedicated tab. You can:

  * Filter by event type and event source
  * Filter by date, to any time window in the past. Only limiting factor is customer's own events retention window setting!
  * Expand each event to see the full payload
  * Click through to the events index to see that event type's config and full cross-user activity log

  This is important because:

  * It helps paint the complete picture of user activity. At a basic level, customers ask the question, "what's going on with this user?" and this helps answer it.
  * Especially useful for zoomed-in troubleshooting, auditing, what-happened analysis.
  * Please note: this will only be visible to customers in Custom Events early access, but will be available to all as they gain access to Custom Events
</Update>

<Update label="November 26 2025">
  UX Improvements Now Live

  1. Row-Level Linking
     You can now click anywhere on a table row to navigate to its destination, instead of having to click a specific cell. This makes navigation faster and more intuitive.
  2. Row Highlighting on Hover
     All tables now highlight the entire row on hover, helping users track data more easily and reducing visual strain when scanning wide tables.
  3. Improved Responsiveness
     The actions column has been narrowed to preserve horizontal space and is now right-aligned at the end of every table.
     It also features sticky, floating behavior — especially useful on smaller screens where horizontal scrolling is required.
     Some tables better truncate long text (e.g., lengthy message names) more effectively to maintain a clean layout.
  4. Refined Sorting UX
     Updated sort icons make the sort direction easier to interpret. Clicking anywhere on a column header now toggles sorting, improving ease of use.
  5. Unified Column Visibility Menu (Applies to Journeys, Users, Subscriptions)
     Tables with customizable columns now use a consistent, cleaner UI. Column changes update live as you toggle them.
  6. Updated Search Bar UI
     The search bar now aligns with design standards, featuring a left-aligned search icon, and a button that shows after typing for easy input clearing.
  7. Improved Pagination Formatting
     Pagination controls now use comma formatting for large numbers, improving scannability and readability.

  Core Component Update
  Many of the enhancements above come from migrating these tables to our core design system’s DataTable component. Sorting and filtering improvements for tables are consistently among the most requested features we receive. While these updates don’t introduce new sorting or filtering behavior yet, this component upgrade provides a more consistent experience for the functionality we have today, and does lay the foundation for Product teams to build more advanced table capabilities once those initiatives are prioritized.

  Coming Soon

  * Most tables across the Dashboard already include these improvements. A few remaining areas still require component updates before they can adopt the full set of new enhancements:
    * In-app index
    * Templates index
    * Audience activity table
    * A/B tests stats table
</Update>

<Update label="November 12 2025">
  UX Enhancement: Duplicate Templates Directly from the Editor
  In usability tests and dogfooding sessions, we noticed users often duplicate Journey nodes and then edit their templates. Previously, you had to exit the template editor and duplicate the template from the index view, an extra step that interrupted the workflow.
  Now, you can duplicate templates directly from the actions dropdown in the template editor. This small but meaningful improvement streamlines your editing experience and makes iteration faster. While our long-term goal is to enable template/content editing directly within Journeys, this enhancement is a great step in that direction.

  New Platform Filters for Engagement Trends & Subscription Trends
  You can now filter push engagement trend data by platform (iOS, Google Android, Huawei, etc.) to get a more granular view of performance across specific devices.
  In the spirit of our Analytics Consistency project, we've also brought this same filtering experience to Subscription Trends.

  Analytics Consistency: Standardized Time Series Chart Filters
  We're standardizing filter options across our time series charts, giving customers a consistent experience and clear access based on their plan.
  Key Changes:

  * All charts will share the same set of granularity and look back filters
  * Consistent casing and terminology used on all filters
  * Consistent upgrade experience for customers on plans with limited access
    As an example, Subscription Trends now supports a 2 year look back after the change.

  Charts where we've already rolled out these changes:

  * Engagement Trends
  * Subscription Trends
  * Global Outcomes
  * Push Delivery
  * All Template Reports
  * Coming Soon:
  * Email Delivery
  * SMS Delivery
  * Journeys Reports

  Look back access based on plan type:

  * Free: 30 days
  * Growth: 90 days
  * Professional: 1 year
  * Enterprise: 2 years
  * Custom: Up to 90 days (based on plan types above)
</Update>

<Update label="October 6 2025">
  Nice UXE on Journey Settings. We’ve updated the Journeys Settings Side panel to be more user friendly by adding a side navigation to keep each section in focus. This is in tandem with the eventuality of having more settings available to the user as we look towards Journey Goals, and more.  We will accompany this release with an intercom slide letting the user know we have updated the settings area as to give them a heads up due to the abrupt pattern change.

  Every Setting, In Focus: Journey Settings are now grouped and spotlighted, helping you zero in on each choice without distraction.
</Update>

<Update label="October 2 2025">
  Custom Events are now available to all customers on paid plans! You can now send custom events via our API or SDK, and use them to trigger actions in Journeys with your own event data.
</Update>

<Update label="September 21 2025">
  Customers can now pause a segment that's counting towards their segments entitlement even though it's only being used in an archived journey or paused IAM. We also made it even easier to pause segments, if the user wants to pause a segment, we'll help the user pause or archive the active IAMs or journeys stopping the user from pausing a segment.
</Update>

<Update label="September 9 2025">
  Deactivate email senders

  Deactivate email domains that are no longer in use or were set up incorrectly. This includes fallback handling for your email templates and scheduled sends to make sure you don't break them by removing a domain, just in case it was being used more widely than you anticipated.
</Update>

<Update label="August 29 2025">
  Personalize emails with real-time Data Feeds

  You can now use Data Feeds to pull live content from your APIs directly into emails at send time. No more static CSVs or preloaded tags — every message can include the latest account details, product recommendations, or order updates.

  Available in the email template composer for emails sent via Journeys, Data Feeds includes preview tools and error handling to keep sends smooth.

  👉 See how to set up [Data Feeds](/docs/en/data-feeds)
</Update>

<Update label="August 04 2025">
  You can now hold users in a Journey step until specific conditions are met before they move forward with the *Wait Until* action. This new feature allows you to:

  * Hold users at a step until they enter a segment or trigger a message event (such as a specific message being delivered, opened, or clicked).
  * Add multiple conditions and branch users based on whichever condition they meet first.
  * Set an expiration path that moves users forward or removes them from the Journey if none of the conditions are met within your chosen timeframe. This gives you greater flexibility and control over how users progress through your Journeys. Learn more: [Journeys Actions](/docs/en/journeys-actions)

  AI Composer Push Notifications
  You can now generate or improve push notification message copy using the AI message composer. This update helps you craft high-performing content without leaving OneSignal. When creating a new push notification, select AI-generated push button to get started. To improve existing copy, select “Refine” in the Title, Subject, or Message fields.

  New [Integrations](/docs/en/integrations) index page contains the following enhancements:

  * Filtering by type of integration
  * Filtering by Inbound/Outbound directions of data flow
  * Includes our new inbound DWH/Data ingestion options for custom events
</Update>

<Update label="July 07 2025">
  * Quickly identify and manage segments tied to campaigns
    * We’ve made it easier to clean up outdated segments.
    * Previously, you couldn’t delete a segment if it was tied to an In-App Message (IAM) or Journey, even if that campaign was paused or archived. Now, when you try to delete a segment, you’ll see a modal listing all IAMs and Journeys that are preventing deletion.
    * This helps you quickly locate and update the associated campaigns, so you can keep your workspace clean and organized without having to hunt through every Journey or IAM.
</Update>

<Update label="June 30 2025">
  * Segment users based on real message engagement
    * You can now create user segments based on how they interacted with previous messages across push, email, SMS and in-app.
    * This update adds a new Message Event filter that allows you to segment users based on events like email opens, push clicks, SMS failures, and more - without relying on tags or external tools.
    * Available on all paid plans.
    * See [Segmentation](/docs/en/segmentation#message-event-filters) for more details.
</Update>

<Update label="June 27 2025">
  * New documentation with Mintlify!
    * We've updated our docs!
    * New AI features and easier readability.
    * Updated API reference and openapi spec.
    * New Tutorials page with common use cases and step-by-step details to get you setup quickly!
</Update>

<Update label="June 18 2025">
  * Track In-App engagement trends alongside push, email, and SMS
    * Customers can now see In-App Message impressions, clicks, and click-through rates directly in the Engagement Trends chart. This update gives marketers a unified view of how users are interacting with all message types over time—including In-App—making it easier to spot trends, report on performance, and optimize messaging across channels.
    * With this update, In-App engagement data is now included alongside push, email, and SMS across all views in the Engagement Trends chart. Stats are grouped by day and support up to two years of data (depending on plan). This data is exportable via CSV just like other channels, and can be filtered to look at specific date ranges or message types.
    * This feature is available to all customers.
</Update>

<Update label="June 12 2025">
  * Unlock deeper email engagement insights with multi-link tracking
    * Customers can now track engagement on every individual link within their emails. This update gives customers a much clearer view into what content or messaging is working so they can improve email performance over time.
    * Previously, when customers included multiple links within an email, they could only view total click counts across all links. Now, they can see which specific links get the most engagement and how links perform inside journeys. This helps them refine content and messaging strategies.
    * Multi-link tracking is automatically applied to most emails created in the Drag & Drop or HTML editor. Link-level performance metrics will also be available for emails sent using a template and emails in a Journey.
    * This feature is available to all customers with access to email.
</Update>

<Update label="May 23 2025">
  * View and optimize message performance with Template Analytics
    * OneSignal customers can quickly assess how individual templates are performing across all messages, without needing to download and stitch together separate reports.
    * When users click into a template, they now land on a detailed analytics view showing Delivered, Unique Opens, Unique Clicks, and Unsubscribes. They can track performance over time, filter by platform, explore delivery breakdowns like Failed or Capped, and review a list of messages that used the template.
    * Template analytics is especially useful for:
      * Marketers who test and iterate on message content
      * Developers who need visibility into transactional message delivery
      * High-volume senders seeking scalable insights
    * Transactional visibility is a key differentiator that sets us apart from Firebase and other open source solutions. Customers can now answer questions like “How many Account Confirmation emails did I send last week?” or “What was the click-through rate on my Password Reset messages?”
    * Important note: For templates created before April 17, 2025, enhanced metrics are only available for messages sent after that date. Customers can use the “Show historical data” toggle at the top of the page to see earlier performance data.
    * The feature is live and available by default. Reporting history varies by plan:
      * Free: 30 days
      * Growth: 90 days
      * Professional: 1 year
      * Enterprise: 2 years
</Update>

<Update label="May 16 2025">
  * Add users manually from the dashboard
    * You can now create new users directly from the *Users* tab in your OneSignal dashboard using a simple form. This update makes it easy to manually add a user with an email address, phone number, or both without needing an SDK, API call or CSV upload.
    * This is especially helpful for quickly testing campaigns or adding users who aren’t yet in your system.
</Update>

<Update label="May 14 2025">
  * Track SMS link performance directly in OneSignal
    * Customers can now track SMS link performance directly in OneSignal without needing third-party tools like Bit.ly or custom UTM parameters. This feature gives our customers a more streamlined, built-in way to measure engagement and optimize messages faster, removing friction and helping drive better results from their SMS efforts.
    * When composing an SMS message, customers simply click “Insert Trackable Link” and enter the full URL they want to send users to. OneSignal automatically shortens the link using the 1sgnl.co domain so it fits within SMS character limits and can be tracked.
    * All SMS users will have access to trackable links as part of their existing plan.
</Update>

<Update label="May 07 2025">
  * Simplify message organization with easier label management
    * Now you can add labels to your messages to help you organize and manage them.
    * See [Labels](/docs/en/labels) for more details.
</Update>

<Update label="May 01 2025">
  * Template analytics
    * You can now view and optimize template performance from a centralized reporting view. Click into any message template to view detailed performance data across every message a template is used in.
</Update>

<Update label="Apr 25 2025">
  * Improved CSV Importer
    * **Real-time validation:** Get instant feedback on formatting errors before upload.
    * **Smart column mapping:** Easily align your CSV headers with OneSignal fields.
    * **Email suppression support:** Add or manage your suppression list directly in the file.
    * **Upload history:** View the status of your past imports for up to 30 days.
    * **Helpful templates:** Start quickly with a pre-built CSV example.
</Update>

<Update label="Apr 21 2025">
  * Fine-tune your Live Activities with new API parameters
    * You can now add more control, reliability, and speed to your Live Activities with three new parameters in the OneSignal API: - ios\_relevance\_score: Helps determine which Live Activity displays most prominently on iOS. - include\_aliases: Allows you to target individual users directly rather than relying on segment-based delivery. - idempotency\_key: Prevents the creation of duplicate Live Activities when retrying start requests if not using the OneSignal SDK.
</Update>

<Update label="April 14 2025">
  * New integration - Databricks data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Databricks. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Databricks, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="April 08 2025">
  * View opt-out status by sender and support transactional messaging even with marketing opt-outs
    * You can now see SMS opt-out status by sender, giving you better visibility and control when managing marketing and transactional messages.
    * With this update, you can:
      * View subscription status by individual sender for any phone number
      * Continue sending transactional messages (like OTPs or alerts) even if a user has opted out of marketing
      * Maintain deliverability and avoid carrier filtering by respecting opt-out preferences
    * This is especially useful if you manage separate senders for promotional and transactional use cases.
    * To access this feature, go to **Consent Management > Advanced Opt-out Settings** and turn off the setting that globally unsubscribes a user when they reply with an opt-out keyword.
    * *Note: This option is only available to customers using advanced opt-out settings for SMS.*
</Update>

<Update label="March 19 2025">
  * Easily find and select the right templates with visual previews
    * Quickly identify and select your email and in-app message templates with the new updated card view.
    * Instead of relying on template names alone, you can now see clear visual previews, making it easier to choose the right template at a glance.
</Update>

<Update label="March 12 2025">
  * Create users in OneSignal via HubSpot workflows
    * Keep your users in sync across HubSpot and OneSignal! With this new workflow action, you can now create users in OneSignal whenever a HubSpot workflow trigger fires. This enables you to queue up personalization details (such as Tags) and plan engagement strategies before a user even interacts with your mobile platform. Additionally, you can trigger an SMS or email via HubSpot while simultaneously creating a user in OneSignal—ensuring seamless and immediate engagement.
    * [HubSpot Documentation](/docs/en/hubspot)
  * Push preview accuracy improvements
    * As operating systems update, they often introduce new changes in their push designs.
    * We've updated our previews so they match latest and greatest push notification designs across iOS (18), Android (15), Windows (11), macOS (Sequoia). This ensures you see what your users will see when testing in OneSignal.
  * PII Masking of Emails and Phone Numbers
    * Protect user privacy and reduce compliance risks by masking personally identifiable information (PII) such as emails and phone numbers. With PII masking, your team can work securely while still analyzing campaign performance and sharing insights across teams.
    * OneSignal automatically masks phone numbers and emails in the dashboard and any data exported directly from the platform. However, PII masking does not currently apply to data accessed via API requests, external IDs, or Tags.
</Update>

<Update label="March 07 2025">
  * Verify & Lookup Phone Numbers
    * Sends the user a one-time verification code to ensure the customer owns the phone #
    * Confirms the phone number entered by a user at onboarding is valid
</Update>

<Update label="February 28 2025">
  * Added New Integration - [BigQuery Data Export](/docs/en/bigquery)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to BigQuery. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in BigQuery, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
  * Channel subscriber counts have moved
    * The counts of subscribed counts for each channel have moved from the dashboard to the Subscriptions page in OneSignal. Now you will see the number of *Subscribed* subscriptions for each channel at the top of the Subscriptions page under Audience to get an overview of audience reach per channel in the context of your subscriptions.
    * If you still wish to view this information on the Dashboard, you can filter your Subscriptions trends chart by channel.
</Update>

<Update label="February 14 2025">
  * Improvements to Keywords
    * We've made a couple of improvements to our SMS keywords.
      * Segment by subscription status when sending a keyword to encourage converting your customers who are not yet subscribed into opting in to your SMS marketing messages
      * Setup an auto-responder for unrecognized keywords
</Update>

<Update label="February 12 2025">
  * New Engagement Analytics on the OneSignal Dashboard

    * Are you curious to learn more about how your end users engage with the messages you send from OneSignal? Head to your Dashboard to see the new Engagement Trends report.
    * With this report you will gain insight into how users engage with your messages across Push, Email, and SMS. Track click-through-rate, unsubscribes, and monitor trends over time to refine your messaging strategy and optimize communication frequency. This comprehensive report consolidates data from all message types (Dashboard, API, Journeys) for a clearer view of performance. Now available in your OneSignal dashboard!

    <Frame>
      <img alt="New Engagement Analytics on the OneSignal Dashboard" />
    </Frame>
</Update>

<Update label="January 29 2025">
  * Sort segments by Last edited, Created at and more
    * Finding and managing your segments just got easier!
    * You can now sort segments by Last edited, Created at and more.
      * This update is especially valuable for customers who:
        * Maintain numerous segments
        * Frequently update their segment configurations
        * Need to identify and clean up outdated segments
        * Want to quickly find recently modified segments
</Update>

<Update label="January 27 2025">
  * Email Senders (Multi-Domain Sending)
    * Create distinct senders for different types of communications:
      * Keep your marketing campaigns separate from crucial transactional emails
      * Maintain different brand voices for various product lines
      * Optimize sender reputation for each type of communication
      * [Email Senders](/docs/en/senders)
  * Improved In-app Message Analytics for Event Streams
    * We've added a new In-app Message Analytics for Event Streams.
</Update>

<Update label="January 21 2025">
  * Email Intelligent Delivery
    * We've added intelligent delivery to email.
    * Transform your email engagement with OneSignal's latest breakthrough: Intelligent Delivery. This powerful new feature automatically determines the optimal time to reach each individual user, maximizing your email campaign's impact.
    * Our algorithm continuously learns from:
      * User open patterns
      * Click-through behavior
      * Real human interactions (excluding bot activity)
</Update>

<Update label="January 16 2025">
  * Retirement of Automated Message for Free apps
    * Automated Messages are no longer supported and the feature has been retired in the free plan. Paid apps will continue to have access to this feature until further notice.
    * Active automated messages will remain live and continue functioning as expected. However, you can no longer create new automated messages, or reactivate paused automated messages. To build new automated sequences and enhance your campaigns, we recommend using [Journeys](/docs/en/journeys-overview).
</Update>

<Update label="January 15 2025">
  * Customize how your users re-enter split branches
    * Now you can customize how your users re-enter split branches. This feature is available for all Journeys.
    * [Journey Entry Triggers](/docs/en/journeys-actions)
  * Improving New Message Experience
    * We improved the new message experience by adding a library of templates (get inspiration for your next push, in-app, email, or SMS), or quickly start from a template you've made, or a previous message.
</Update>

<Update label="January 03 2025">
  * message.url - New Push Event Stream Property
    * `message.url` is now a supported property for push events. It enables the retrieval of the launch URL directly from your event stream payload.
</Update>

<Update label="December 24 2024">
  * Journeys Multi-split Branching
    * Now you can set up more personalized paths in your Journey. Create up to 20 branches to test channels, content, timing, ordering, and more. Assign different weights to each branch, or easily distribute audiences evenly across all branches. See how different paths perform against each other or against a control group.
</Update>

<Update label="December 20 2024">
  * WordPress Plugin v3
    * We've upgraded our Wordpress Web Push plugin to v3+. What's changed:
      * Upgrades the OneSignal Web SDK from version 15 to 16.
      * Setup more new prompts within the OneSignal dashboard, including the following. No custom code is required anymore to configure these.
        * Category Prompt
        * Email/Phone Slide Prompt
        * Custom Link Prompt.
      * When publishing a new post, check the "Send notification when post is published" box to send a push notification.
      * Choose which audience segment should receive notifications for each post.
      * Web Topics are included by default.
      * Send to mobile app subscribers, with an option to direct them to a different URL (Deep Link).
</Update>

<Update label="December 11 2024">
  * Improved Logs in Event Streams
    * We've improved the Event Streams feature to make troubleshooting simpler and faster. Now, you’ll find dedicated tabs for successful and failed events, making it easier to spot issues at a glance. Clear empty states show when there’s no data in either tab, and updated messaging ensures you know the logs display a sample of your data.
  * SMS Keywords
    * We've added keywords for SMS. Keyword engagement enables quick, two-way communication, enhancing personalization, accessibility, and user satisfaction. It drives conversions and higher engagement with your subscribers. Add a data tag to the keyword, and segment based on their preferences to send more targeted SMS.
  * Quickstart Segments

    * We are thrilled to launch three new segment templates designed to help you hit the ground running with proven strategies:
      * First-Time audience
      * Regional audience
      * Custom Audience based on tags
    * Our analysis of 6.3 billion message deliveries uncovered powerful insights. These templates are built to help you:
      * Create high-performing segments from day one.
      * Use proven filter combinations that drive higher engagement.

    <Frame>
      <img alt="Quickstart Segments" />
    </Frame>
</Update>

<Update label="December 02 2024">
  * Email Quickstart Templates
    * We've added a library of quickstart templates for email. Explore our library of professionally crafted email templates, designed to inspire your creativity and elevate your email campaigns. Use them as a starting point to create impactful messages that drive conversions and engage your audience effectively.
</Update>

<Update label="November 27 2024">
  * Scheduling Journeys
    * Now you can schedule Journeys to send at a specific time. This feature is available for all Journeys.
  * Settings Overview Page
    * Now you can access and manage all your settings in a centralized setting overview page. Platform-specific settings have been reorganized under their relevant channels for better clarity.
</Update>

<Update label="November 20 2024">
  * Bulk Archive and Delete Journeys

    * Now you can bulk archive or delete Journeys from the Journeys index. Select up to 20 Journeys, and then choose an action you'd like to take to clean up Journeys you're no longer using.

    <Frame>
      <img alt="Bulk Archive and Delete Journeys" />
    </Frame>
</Update>

<Update label="November 06 2024">
  * Improved Export for Global Outcomes
    * We've improved the export for Global Outcomes to include more data and make it easier to use in your reporting.
  * Preview allows you to preview the content of a message and can be very helpful when you have a message with personalization (i.e. Tags, dynamic content, custom data). With preview, you can preview content from a specific test user's perspective, or with example custom data.
  * Settings for Email & Side Navigation Updates
    * In the side navigation, you can now easily see your Push, SMS, and Email settings. What was once "Messaging" is now "Push" settings, and SMS and Email Settings will take you directly to your channel's settings.
    * For email, we've created a dedicated place to manage your email provider and senders. If you are a OneSignal mail user, you'll also be able to see your reputation and suppression lists here.
  * SMS Usage
    * We've added SMS Usage in the Usage page. We've also added a breakdown so you can see the message type, and a breakout by inbound and outbound. You may see an unknown country if a segment failed to send.
</Update>

<Update label="October 02 2024">
  * Add Notes on your Journeys
    * Now you can add notes to the steps of your Journeys to keep reminders and more effectively collaborate and share information with your team. This feature is available for all Journeys.
</Update>

<Update label="September 27 2024">
  * New Quickstart Journeys
    * We've added a new Quickstart Journeys to help you get started with Journeys. This feature is available for all Journeys.
  * SMS Text-to-Subscribe
    * It's now easier to set up double opt-in and text-to-subscribe phone number collection experiences for your customers!
</Update>

<Update label="September 12 2024">
  * Confirmed Click-Through-Rate (CCTR) metric

    * We have added a new metric to measure the CTR using confirmed receipt. Confirmed Click-Through-Rate (CCTR) is measured by (total clicks/confirmed delivered) \* 100%

    <Frame>
      <img alt="Confirmed Click-Through-Rate (CCTR) metric" />
    </Frame>
</Update>

<Update label="September 06 2024">
  * Export your Subscription Trends
    * Now you can export the data from your Subscription Trends report as a CSV. If you apply filters to the report, OneSignal will export based on the filters you've applied so that you can fine-tune the data that you use to evaluate your messaging audience.
</Update>

<Update label="August 05 2024">
  * Email Saved Rows
    * Saved Rows are reusable content blocks that help streamline email creation and management. Many companies, especially those that have a lot of templates, prefer to use saved rows in their emails for consistency and to save time. Saved Rows are easily attached to new emails so you don't have to create the same information from scratch each time. And when things change, you just have to update the saved row, and your updates will automatically sync across all campaigns that have that saved row attached.
    * Common use cases include:
      * headers (logo, slogan)
      * footers (company details, social media links, mailing addresses)
      * disclaimers
      * other elements that are used across multiple campaigns
    * You can now save Email Drag-and-Drop rows to use across many Campaigns or Templates. These re-suable **Saved Rows** make it easy to sync updates across many emails at once. Click on the **Rows** tab of a Drag-and-Drop email, to view your **Saved Rows**. To save your first row, click the save icon in the edit, in the top right corner of the row.
    * We recommend you set up all of your templates to use saved rows for your header and footer so that you need to update the branding or content; you only have to make those edits once.
</Update>

<Update label="July 30 2024">
  * Journeys now target anonymous users
    * Now, Journeys do not require External IDs to be set on subscriptions. Instead, Journeys will target your entire user base within OneSignal, including anonymous users. We recommend still configuring External IDs to identify individual users who have subscribed to multiple channels.
</Update>

<Update label="July 25 2024">
  * Have more visibility into SMS unsubscribes, resubscribes, and help keywords
    * We now make it easier to manage your Consent Keywords within Onesignal. Reach out to support if you'd like to update the default consent keywords and replies.
</Update>

<Update label="July 19 2024">
  * Email Reply-to field now supports custom properties
    * Now you can use [Message Personalization](/docs/en/message-personalization) within the `reply-to`field on an email. This allows you to direct message replies to the right inbox and can be helpful if you are sending from different brands or across different countries.
</Update>

<Update label="July 16 2024">
  * Push Failures and Unsubscribes in Audience Activity
    * Obtain a list of subscriptions that have faced errors - failures or unsubscribes, for a specific push notification in the push report page.
</Update>

<Update label="July 03 2024">
  * Integrations: OneSignal Message Events can be sent to Twilio Segment
    * Customers can now select and send message events from OneSignal to sync back to their Twilio Segment account, making the Segment integration bidirectional.
  * Use Audience Activity for Live Activities to get a list of recipients
    * Get a list of subscriptions that successfully or failed to receive a Live Activity on a Live Activity report page, which is accessible through the Delivery - Sent Index. This list can be exported as well.
</Update>

<Update label="June 06 2024">
  * In-app message audience activity
    * In the report page of an in-app message, you can now see which mobile subscriptions viewed (impression) or clicked on an in-app message. Audience activity is available for 30 days from the time the message is displayed
</Update>

<Update label="May 15 2024">
  * FCM Expired Tokens > Increased Android Unsubscribes
    * On May 15, 2024, Google's FCM service will start to expire stale push tokens for devices that have been inactive for more than 270 days. You may see a spike in Android unsubscribes when sending notifications due to this change. Don't panic! These are devices that have not been online in over 270 days and are part of Google's [Best practices for FCM registration token management](https://firebase.google.com/docs/cloud-messaging/manage-tokens). If the device does come back online and opens your app, OneSignal will automatically resubscribe them to push if they were previously subscribed already.
    * See [FCM Expired Token FAQ](/docs/en/fcm-expired-token-faq) for more details.
</Update>

<Update label="April 29 2024">
  * Configure more granular Frequency Capping rates for Push
    * Push notifications can now be capped at a rate of x notifications per any time frame (less than 1 week). Navigate to Settings > Messaging > Push Frequency Capping > Custom (in the time dropdown) to view these settings.
    * Read [Frequency Capping Documentation](/docs/en/frequency-capping) for more details.
</Update>

<Update label="April 11 2024">
  * Added Android Live Notifications
    * Android's Live Notifications deliver live, dynamic content in notifications to enhance user engagement and app interactivity. This is a feature similar to iOS's Live Activities feature (introduced with iOS 16), but uses its own set of tools and APIs that enable similar functionalities.
    * See [Android Live Notifications](/docs/en/android-live-notifications) for more details.
  * Major improvements to Android SDK
  * Push to start Live Activities
    * Live Activities can now be launched on a user's screen when the mobile app is in the background (app is not open). Live Activities can both be started and updated by a remote push notification.
    * [How to start a Live Activity with a remote push notification](/docs/en/live-activities)
</Update>

<Update label="April 01 2024">
  * Added Audience Activity reports for Journeys
    * We have added Audience Activity reports for Journeys so you can get a closer look at which subscriptions were sent messages during a Journey. To view this report, click into a message report on your Journey. [Learn more here](/docs/en/journeys-analytics#audience-activity).
</Update>

<Update label="March 18 2024">
  * Added a new Setup guide for Analytics
    * We have added a new Analytics Setup guide to our product documentation detailing how to track Confirmed Deliveries and set up Custom Outcomes with support from your development team.
</Update>

<Update label="March 12 2024">
  * Mobile SDK Updates
    * We recommend updating to the latest SDK versions listed below to benefit from critical bug fixes, stability improvements, and new features. These updates include key enhancements across all platforms, including iOS 5.1.3 and Android 5.1.6, which improve concurrency safety, crash resilience, and background thread handling. The updates also include important API adjustments like more accurate property handling in the `PushSubscriptionState`.
</Update>

<Update label="February 16 2024">
  * Journeys is now available on the Growth plan
    * Journeys is now available on the Growth plan. This means you can now create and manage Journeys with up to 100,000 users.
    * See [Journeys](/docs/en/journeys-overview) for more details.
</Update>

<Update label="February 12 2024">
  * Added Auto Warm Up
    * We have added a new feature that allows you to automatically warm up your app when a user opens it. This feature is available for all OneSignal customers.
    * See [Email Warm Up](/docs/en/email-warm-up) for more details.
</Update>

<Update label="February 02 2024">
  * Journeys has easier targeting based on user activity
    * We've added support for Segments with time-based rules (e.g., first session, last session, etc.) and also simplified targeting inactive users. Now you can target your inactive users by including a segment based on last session behavior.
  * Email: Schedule Sends Across Different Timezones
    * Email campaigns can now be scheduled to send across different timezones. This feature is available for all OneSignal customers.
</Update>

<Update label="January 30 2024">
  * Email now supports One Click Unsubscribe
    * Inbox Service Providers (ISP) like Gmail, Outlook, iOS Mail, and Yahoo! Mail, AOL, and Verison Mail require senders to provide a One Click Unsubscribe option. The unsubscribe button is rendered at the discretion of the ISP based on sending criteria, which may include a daily sending volume greater than 5,000 emails.
</Update>

<Update label="December 18 2023">
  * Filter your messages with labels
    * Now you can filter your messages with [labels](/docs/en/labels). This feature is available for all OneSignal customers.
  * CSV Importer can now update properties
    * CSV Importer for email now enables updates to user properties `language`, `country`, and `timezone_id`.
  * Send more personalized messages and multi-language emails
    * [Dynamic Content Documentation](/docs/en/dynamic-content)
</Update>

<Update label="December 14 2023">
  * All OneSignal apps now belong to an Organization
    * We have added a new feature that allows you to manage your OneSignal apps within an Organization. This feature is available for all OneSignal customers.
    * See [Apps, Orgs, and Accounts](/docs/en/apps-organizations)
  * Journeys now has better analytics
    * We've added a new Journeys Report. See [Journeys Analytics](/docs/en/journeys-analytics) for more details.
</Update>

<Update label="November 22 2023">
  * Removed Journey Notifications from Delivery Reports and the View Notifications endpoint
</Update>

<Update label="October 04 2023">
  * Added new integration - [Snowflake](/docs/en/snowflake)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Snowflake, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="September 27 2023">
  * You can now save and continue
    * Changed the default option for saving a message to save work without exiting the message.
</Update>

<Update label="September 13 2023">
  * Added the ability to adjust the default padding for IAM blocks
    * Learn more about [IAM blocks](/docs/en/design-your-in-app-message)
  * Added the ability to edit entry triggers and re-entry rules for live Journeys
    * Learn more about [Journey entry triggers](/docs/en/journeys-overview)
</Update>

<Update label="September 05 2023">
  * Added ability to create multi-language push messages by pasting your CSV
    * Learn more about [Multi-language messages](/docs/en/multi-language-messaging)
  * Added new "Editor" role permissions
    * Learn more about [Managing team members](/docs/en/manage-team-members)
  * Added enhanced Journey message stats and reports.
    * Learn more about [Journey message stats and reports](/docs/en/journeys-analytics)
</Update>

<Update label="September 01 2023">
  * Added a new feature to forward email templates to an app
    * Learn more at [Email Template Forwarding](/docs/en/email-template-forwarding)
  * Added FCM v1 API support for Android Push Notifications
    * Learn more about [Android Firebase credentials](/docs/en/android-firebase-credentials)
</Update>

<Update label="August 15 2022">
  * Android 13 changes
    * Android 13 introduces a runtime notification permission, meaning users must opt in to receive push notifications. Apps targeting Android 13 must explicitly prompt for permission at a time of their choosing, or the system will display the permission prompt automatically on first launch—often resulting in lower opt-in rates.
    * See [Android 13 Push Notification Developer Update Guide](/release-notes/android-13-push-notification-developer-update-guide) or our [Prompt for Push Permissions](/docs/en/prompt-for-push-permissions) guide for details.
</Update>


# SDK Releases
Source: https://documentation.onesignal.com/release-notes/sdk-releases

View the latest OneSignal SDK releases and updates.

## Mobile

<SdkReleasesIframe />

## Web

<SdkReleasesIframe />

## Server

<SdkReleasesIframe />

## Plugins

<SdkReleasesIframe />


# Cancel message
Source: https://documentation.onesignal.com/reference/cancel-message

DELETE /notifications/{message_id}?app_id={app_id}
Stop a scheduled or currently outgoing message.

## Overview

The Cancel message API can be used to stop scheduled messages from being sent. It does not delete or remove the message from the app. If a message is in the process of sending, then canceling it may not fully prevent all targeted users from receiving it.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users, scheduling the message in the future with `send_after`. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and use this API to cancel sending the message to the user if not needed anymore.

If you need a way to remove a notification already sent to a user, see [Remove notifications & TTL](/docs/en/push).

***


# Create custom events
Source: https://documentation.onesignal.com/reference/create-custom-events

POST /apps/{app_id}/custom_events
The Custom Events API allows you to record user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones.

## Overview

The Custom Events API allows you to track user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones. See [Custom events](/docs/en/custom-events) for more information.

### Use Cases

Custom events can be used to:

* Enter users into [Journeys](/docs/en/journeys-settings)
* Trigger Journey [Wait Until](/docs/en/journeys-actions) nodes

### Error handling

If individual events can't be processed, an `errors` key will be returned in the response (with HTTP status 202) containing information about each failing event. The most common event-specific error is a failure to find a user associated with the External ID or OneSignal ID in the event.

If you'd like to retry sending events in the case of a failure, you only need to re-send the events for which errors were returned -- events that don't have an error associated with them are still processed. However, if a 5xx HTTP response is returned, you must retry the entire batch of events.

In either case, if you are implementing retry, make sure to also pass an [`idempotency_key`](/reference/idempotent-notification-requests).

### Duplicate events

If you implement retry behavior for your custom event delivery, please provide the [`idempotency_key`](/reference/idempotent-notification-requests) field. Each unique event should get its own unique UUID, and when retrying delivery for events, the same UUID must be provided. Duplicate events with the same `idempotency_key` will be ignored on a best-effort basis within a 4-hour period. This allows you to avoid erroneously triggering Journeys multiple times or incurring charges for storing unnecessary duplicate events.

***


# Sending messages with the OneSignal API
Source: https://documentation.onesignal.com/reference/create-message

Send push notifications, emails, SMS, and Live Activities with the OneSignal API. Covers audience targeting, message composition, scheduling, and response handling.

## Overview

This guide walks you through sending messages with the OneSignal API — from choosing a target audience to composing content, scheduling delivery, and validating responses. Each section covers channel-specific options and performance guidance.

### Prerequisites

1. Complete [Channel Setup](/docs/en/channel-setup) for the channels you plan to use: push, email, SMS, Live Activities.
2. Start accumulating [Subscriptions](/docs/en/subscriptions) for your users.
3. Have your REST API Key and App ID ready. See [Keys and IDs](/docs/en/keys-and-ids).

***

## Choose your target audience

You can target users with **one of the following methods per request**:

* **Aliases**: Specific users via unique IDs, emails, or phone numbers.
* **Segments**: Groups based on predefined behaviors or attributes.
* **Filters**: Custom rules using tags, location, activity, and more.

<Warning>
  Only one targeting method is allowed per message. For example, you cannot mix aliases and filters.
</Warning>

You can also target specific platforms (for example, `isAndroid`, `isIos`, `isAnyWeb`) when sending push notifications. By default, all push platforms are enabled.

### Aliases, emails, phone numbers

Target specific users or lists of users (up to 20,000 entries per request). This method is best for [Transactional Messages](/docs/en/transactional-messages).

<Accordion title="Aliases, emails, and phone numbers targeting parameters">
  <ParamField type="object">
    Target up to 20,000 users by their `external_id`, `onesignal_id`, or a custom alias. Combine with `target_channel` to select the delivery channel.

    ```json theme={null}
    {
      "include_aliases": {
        "external_id": [
          "user1",
          "user2",
          "user3"
        ]
      },
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="string">
    The targeted delivery channel. Required when using `include_aliases` or `included_segments` and sending SMS/RCS. Accepts `"push"`, `"email"`, or `"sms"`. The `"sms"` value covers both SMS and RCS — RCS messages are delivered through the SMS channel.

    ```json theme={null}
    {
      "target_channel": "push"
    }
    ```
  </ParamField>

  <ParamField type="array">
    Target users' specific [Subscriptions](/docs/en/subscriptions) by ID. Max 20,000 `subscription_id` per request.

    ```json theme={null}
    {
      "include_subscription_ids": [
        "1dd608f2-c6a1-11e3-851d-000c2940e62c"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send to specific email addresses (max 20,000 per request). Can only be used when sending [email](/reference/email). If the email address does not exist within the OneSignal App, a new email subscription is created.

    ```json theme={null}
    {
      "email_to": [
        "user1@example.com",
        "user2@example.com"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Send SMS/MMS/RCS to phone numbers in [E.164 format](/docs/en/sms-setup#what-is-e164-format) (max 20,000 per request). Can only be used when sending [SMS/MMS/RCS](/reference/sms). If the phone number does not exist within the OneSignal App, a new SMS subscription is created.

    ```json theme={null}
    {
      "include_phone_numbers": [
        "+19999999999"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Segments

Target users in existing [segments](/docs/en/segmentation). Users in multiple segments only receive the message once.

<Accordion title="Segments targeting parameters">
  <ParamField type="array">
    Target predefined [segments](/docs/en/segmentation). Users who are in multiple segments only receive the message once. Combine with `excluded_segments` to exclude users from specific segments. When sending SMS/RCS, set `target_channel` to `"sms"` (or use the legacy `isSms=true` field).

    ```json theme={null}
    {
      "included_segments": [
        "Active Users",
        "Inactive Users"
      ]
    }
    ```
  </ParamField>

  <ParamField type="array">
    Exclude users in these [segments](/docs/en/segmentation) even if they're in `included_segments`.

    ```json theme={null}
    {
      "included_segments": [
        "Subscribed Users"
      ],
      "excluded_segments": [
        "Inactive Users"
      ]
    }
    ```
  </ParamField>
</Accordion>

***

### Filters

Build real-time audiences with `AND`/`OR` logic without creating segments first.

You can include up to **200 total entries per request**. This includes filter rows (for example, each `field`) and logical operators like `{"operator": "OR"}`.

<Accordion title="Filters targeting parameter details">
  <Info>
    **Performance guidance:**

    * **Fast:** Tag filters using `"="` or `"exists"`, and filters on `last_session`, `session_count`, or `country`.
    * **Slower:** Negation filters (`"!="`, `"not_exists"`) — especially with users who have many tags. Contact support to request indexing optimizations.
    * **Slow by default:** Numeric comparisons (`">"`, `"<"`) on tags or custom properties. Indexing may be available on request.
    * **Mixed performance:** Combining tag filters with other fields may increase computation time.
  </Info>

  <ParamField type="string">
    * Implicit `AND` logic between filters. Use `"operator": "OR"` to start a new branch.
    * `OR` filters are mutually exclusive. Recipients only need to satisfy one condition.
    * Allowed values: `"AND"`, `"OR"`.

    <CodeGroup>
      ```json AND example theme={null}
      // Users must satisfy both filters to be included.
      // Notice the AND operator is not required

      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      // The same example using the AND operator. This is not required.
      "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "AND"},
      {"field": "session_count", "relation": ">", "value": "1"}
      ]

      ```

      ```json OR example theme={null}
      // Users can satisfy either filter to be included.

      "filters": [
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "tag", "key": "level", "relation": "=", "value": "20"}
      ]
      ```

      ```json Combinations theme={null}
      // In this example, users must either have:
      // The specified session_count AND tag requirement
      // Or it will be all records where last_session is satisfied
      {
        "name": "2 filters or 1",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"}
        ]
      }

      // Similar to the first example, this shows how to require a specific field
      // across other filters

      {
        "name": "3 filters, 1 required across all",
        "filters": [
          {"field": "session_count", "relation": ">", "value": "2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
          {"operator": "OR"},
          {"field": "last_session", "relation": "<", "hours_ago": "30"},
          {"operator": "AND"},
          {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
        ]
      }

      // Example of 3 user groups with 2 requirements
      // (group_1 OR group_2 OR group_3) AND (requirement_1 OR requirement_2)

      {
        "name": "3 groups with 2 requirements",
        "filters": [
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_1"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_2"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_1"},
          {"operator": "OR"},
          {"field": "tag", "relation": "exists", "key": "group_3"},
          {"operator": "AND"},
          {"field": "tag", "relation": "exists", "key": "requirement_2"}
        ]
      }
      ```
    </CodeGroup>
  </ParamField>

  <ParamField type="object">
    ### `tag`

    Target based on custom user [Tags](/docs/en/add-user-data-tags).

    <Warning>
      Do not use tags for targeting individual users like a "user id".
      Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
    </Warning>

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
      * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
    * `key` = Tag key to compare.
    * `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

    ```json theme={null}
    "filters": [
      {"field": "tag", "key": "level", "relation": "=", "value": "10"},
      {"operator": "OR"},
      {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
    ]
    ```

    ### `country`

    Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "country", "relation": "=", "value": "US"},
        {"operator": "OR"},
        {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
      ]
      ```

    ### `last_session`

    Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "last_session", "relation": ">","hours_ago": "10"}
      ]
      ```

    ### `first_session`

    Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

    * `relation` = `">"` or `"<"`
    * `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

      ```json theme={null}
      "filters": [
        {"field": "first_session", "relation": "<","hours_ago": "24"}
      ]
      ```

    ### `session_count`

    Total number of sessions by the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="` or `"!="`
    * `value` = number of sessions. Example: `"1"`

      ```json theme={null}
      "filters": [
        {"field": "session_count", "relation": ">","value": "5"}
      ]
      ```

    ### `session_time`

    Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

    * `relation` = `">"` or `"<"`
    * `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

      ```json theme={null}
      "filters": [
        {"field": "session_time", "relation": ">","value": "86400"}
      ]
      ```

    ### `language`

    [User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

    * `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = 2 character language code. Example: `"en"`.
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "language", "relation": "=","value": "en"},
        {"operator": "OR"},
        {"field": "language", "relation": "in_array","value": "es,fr,de"}
      ]
      ```

    ### `app_version`

    App version set on the [Subscription](/docs/en/subscriptions).

    * `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
    * `value` = app version. Example: `"1.0.0"`
      For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

      ```json theme={null}
      "filters": [
        {"field": "app_version", "relation": "=","value": "1.0.1"},
        {"operator": "OR"},
        {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
      ]
      ```

    ### `location`

    Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

    * `radius` = in meters
    * `lat` = latitude
    * `long` = longitude

      ```json theme={null}
      "filters": [
        {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
      ]
      ```
  </ParamField>
</Accordion>

***

## Craft your message

Each channel has its own set of fields. At a minimum, you need the following to send a displayable message:

* **Push and SMS** use `contents`
* **Email** uses `email_subject` and `email_body`
* Or reuse `template_id` if you created [templates](/docs/en/templates).

<CodeGroup>
  ```json Push and SMS theme={null}
  // Message request body
  {
    "contents": {
      "en": "Hello, world",
      "es": "Hola Mundo",
      "fr": "Bonjour le monde",
      "zh-Hans": "你好世界"
    }
  }
  ```

  ```json Email theme={null}
  // Message request body
  {
    "email_subject": "Hello, world",
    "email_body": "<html><body><h1>Hello, world</h1></body></html>"
  }
  ```
</CodeGroup>

For advanced customization—like adding images, buttons, sounds, or tracking—see the channel-specific options below.

### Push notification options

Below are the most common parameters for push notifications. For the full list of options, see the [Push notification reference](/reference/push-notification).

<Accordion title="Push notification options">
  #### Content and text

  * [`contents`](/reference/push-notification#body-contents) – Main message body.
  * [`headings`](/reference/push-notification#body-headings) – Title of the notification.
  * [`subtitle`](/reference/push-notification#body-subtitle) – Secondary line of text.
  * [`template_id`](/reference/push-notification#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Appearance

  * [`ios_attachments`](/reference/push-notification#body-ios-attachments) – Images/video/media.
  * [`big_picture`](/reference/push-notification#body-big-picture) – Large image (Android).
  * [`chrome_web_image`](/reference/push-notification#body-chrome-web-image) – Large image (Chrome).
  * [`small_icon`](/reference/push-notification#body-small-icon)
  * [`large_icon`](/reference/push-notification#body-large-icon)
  * [`buttons`](/reference/push-notification#body-buttons) – Action buttons.

  #### Delivery and priority

  * [`android_channel_id`](/reference/push-notification#body-android-channel-id)
  * [`priority`](/reference/push-notification#body-priority) – Delivery urgency.
  * [`ios_interruption_level`](/reference/push-notification#body-ios-interruption-level)
  * [`collapse_id`](/reference/push-notification#body-collapse-id) – Replaces older messages.

  #### Data and extras

  * [`data`](/reference/push-notification#body-data) – Custom key-value pairs sent to your app.
  * [`url`](/reference/push-notification#body-url) – Opens when notification is tapped.
</Accordion>

### Email options

<Accordion title="Email options">
  #### Content

  * [`email_subject`](/reference/email#body-email-subject)
  * [`email_body`](/reference/email#body-email-body)
  * [`email_preheader`](/reference/email#body-email-preheader)

  #### Appearance

  * [`template_id`](/reference/email#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Sender info

  * [`email_from_name`](/reference/email#body-email-from-name)
  * [`email_reply_to`](/reference/email#body-email-reply-to)
</Accordion>

### SMS/MMS options

<Accordion title="SMS/MMS options">
  #### Content

  * [`contents`](/reference/sms#body-contents)
  * [`template_id`](/reference/sms#body-template-id) – Use a [pre-defined template](/docs/en/templates) for common message types.

  #### Media (MMS only)

  * [`sms_media_urls`](/reference/sms#body-sms-media-urls)

  #### Sender info

  * [`sms_from`](/reference/sms#body-sms-from)
</Accordion>

***

## Schedule and per-user delivery

By default, messages are sent immediately. You can schedule delivery in advance and optimize timing per user based on their local timezone or recent activity.

<Accordion title="Schedule delivery and per-user optimization parameters">
  <ParamField type="string">
    Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript's Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring).

    ```json theme={null}
    {
      "send_after": "2025-09-24T14:00:00-07:00"
    }
    ```
  </ParamField>

  <ParamField type="string">
    Controls how push and email messages are delivered on a per-user basis. Not available for SMS.

    * `"timezone"`: Sends at the same local time across time zones.
    * `"last-active"`: Delivers based on each user's most recent session.

    Not compatible with [push throttling](/docs/en/throttling). When `delayed_option` is set, you must also set `throttle_rate_per_minute` to `0`.

    ```json theme={null}
    {
      "delayed_option": "last-active",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>

  <ParamField type="string">
    Use with `delayed_option: "timezone"` to set a consistent daily delivery time. Accepted formats:

    * `"9:00AM"` (12-hour)
    * `"21:45"` (24-hour)
    * `"09:45:30"` (HH:mm:ss)

    Example — Send every day at 9 AM in each user's local time:

    ```json theme={null}
    {
      "delayed_option": "timezone",
      "delivery_time_of_day": "9:00AM",
      "throttle_rate_per_minute": 0
    }
    ```
  </ParamField>
</Accordion>

***

## Submit the request

This final example sends a localized push notification to all subscribed users:

```curl theme={null}
curl -X "POST" "https://api.onesignal.com/notifications" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Key YOUR_API_KEY' \
     -d $'{
      "target_channel": "push",
      "included_segments": [
        "Subscribed Users"
      ],
      "app_id": "YOUR_APP_ID",
      "contents": {
        "en": "Hello, world",
        "es": "Hola mundo",
        "fr": "Bonjour le monde",
        "zh-Hans": "你好世界"
      }
    }'
```

Once the request is sent, OneSignal forwards it to the appropriate downstream provider, which then delivers it to the recipient:

* **Push:** FCM, APNs, or HMS
* **Email:** your email service provider
* **SMS:** Twilio

### Handle the response

You receive a `200` response code if the request is valid and accepted.

* If an `id` is returned, the message was created successfully. Save this `id` for future tracking and reference of message stats via the [View message API](/reference/view-message).
* If no `id` is returned, the message was not created, likely because there are no valid [subscriptions](/docs/en/subscriptions) in the target audience.

**Response details by channel:**

* [Push](/reference/push-notification#response-id)
* [Email](/reference/email#response-id)
* [SMS](/reference/sms#response-id)

<Note>
  See our [REST API Overview](/reference/rest-api-overview#reliability-and-delivery) page for details on retries and [rate limits](/reference/rate-limits).
</Note>

***

## FAQ

### Can I combine `include_aliases`, `included_segments`, and `filters` in one request?

No. Each request must use exactly one targeting method. Mixing them returns a validation error. Choose aliases for transactional sends to specific users, segments for predefined audiences, or filters for ad-hoc audiences built with `AND`/`OR` logic.

### Does `target_channel: "sms"` cover RCS?

Yes. The `target_channel` enum accepts `"push"`, `"email"`, and `"sms"`. RCS messages are delivered through the SMS channel — there is no separate `"rcs"` value. OneSignal decides whether to send via RCS or SMS based on the recipient's device and your sender configuration.

### My request returned `200` but no `id`. What happened?

The request was valid but no message was created, typically because the target audience contains no valid subscriptions for the selected channel. Common causes include a segment that resolves to zero users, all targeted aliases being unsubscribed, or phone numbers that don't match an existing SMS subscription.

### Can I use `//` comments in the JSON request body?

No. The `//` comments in the examples on this page are illustrative only. Strict JSON does not support comments — strip them before sending to the API.

### How is the `Sent` count in reports related to the API response?

The dashboard `Sent` metric is a composite. To derive it from the [View message API](/reference/view-message), sum `successful + failed + errored`. See the [Metrics glossary](/docs/en/analytics-metrics-glossary) for the full mapping between dashboard, API, CSV, and Event Streams names.

***

## Next steps

Refer to the channel-specific APIs to customize delivery further:

* [Push notification](/reference/push-notification)
* [Email](/reference/email)
* [SMS](/reference/sms)
* [Live Activities](/reference/start-live-activity)
* [Server-Side SDKs](/docs/en/server-sdk-reference)


# Create user
Source: https://documentation.onesignal.com/reference/create-user

POST /apps/{app_id}/users
Create a new user or modify the subscriptions associated with an existing User.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint enables you to create and manage users outside of frontendSDK-based sessions. It's primarily used to:

* Import users from other systems.
* Programmatically define users by assigning identifiers (aliases), properties (e.g., tags), and messaging subscriptions (e.g., email, mobile, SMS).

If you're using the frontend SDKs, user creation is typically handled automatically via methods like `login`, `addEmail`, and `addSms`. See [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) for conceptual guidance.

***

## How to use this API

To successfully create a user via the API:

* You must provide at least one unique identifier via the `identity` and Subscription via the `subscriptions` fields.
* You can optionally include user profile data (`properties`) and one or more messaging `subscriptions`.

## Key Concepts

### Aliases

Aliases uniquely identify a user and should include an `external_id` (the recommended identifier). They allow you to reference users across platforms or external systems. Up to 10 custom aliases are supported. Each alias key and value has a maximum length of 128 characters.

### Properties

User properties store information such as tags, location, activity, and device data. These attributes help you personalize campaigns and optimize engagement strategies.

### Subscriptions

A user can have up to **20 subscriptions** (across email, SMS, push, etc.). Subscriptions connect users to channels for message delivery and are transferable across users. See [Subscriptions](/docs/en/subscriptions) for more.

***


# Delete user
Source: https://documentation.onesignal.com/reference/delete-user

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}
Delete a user including all associated properties, subscriptions, and identity.

## Overview

Use this API to permanently delete a user from your OneSignal project, including all associated subscriptions, properties, and aliases. The operation is asynchronous—user data will be deleted shortly after the request is accepted.

***

## How to use this API

To delete a user, you must be able to identify them using one of the following alias types:

* `external_id` (recommended and most common)
* `onesignal_id`
* A custom Alias that you have set

Pass the appropriate `alias_label` and corresponding `alias_id` in the request path.

<Warning>
  This operation deletes all data associated with the user, including:

  * All identity aliases
  * All channel subscriptions (push, email, SMS, etc.)
  * All custom user properties
</Warning>

## Because this is an irreversible operation, be sure that you really intend to delete the user and all their data.


# Email
Source: https://documentation.onesignal.com/reference/email

POST /notifications?c=email
Send a message using the email channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for email. See [Push notification](/reference/push-notification) or [SMS](/reference/sms) to send to those channels.

Ensure your [Email setup](/docs/en/email-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# View user identity
Source: https://documentation.onesignal.com/reference/fetch-aliases

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Retrieve all aliases associated with a user using a known alias, such as an `external_id`, `onesignal_id`, or a custom alias. This API helps you map back to a user’s full identity from any one piece of identifying information.

## Overview

Use this API when you want to retrieve the complete identity object for a user, which includes all aliases tied to that user. It is ideal for cases where you know one alias and want to discover others—especially helpful for user mapping, debugging, or linking systems.

This endpoint is similar to the [View user](/reference/view-user) API but only returns the `identity` object—not subscriptions or properties.

<Tip>
  If you only know a subscription\_id, use View user identity (by subscription) instead.
</Tip>

For more context on user identity and aliasing:

* [Users](/docs/en/users)
* [Aliases](/docs/en/aliases)

***

## How to use this API

To identify the user, use:

* `alias_label` – the type of alias you’re using to find the user (e.g. `external_id`, `onesignal_id`, or a custom alias)
* `alias_id` – the actual value of that alias

Common usage patterns:

Using `external_id` (recommended):

* `alias_label`: `external_id`
* `alias_id`: your user ID (e.g., user-123)

Using `onesignal_id`:

* `alias_label`: `onesignal_id`
* `alias_id`: the OneSignal-assigned unique ID

Using a custom alias:

* Define your own alias label (e.g. `shopify_customer_id`) and its value

<Note>
  We strongly recommend setting and using the `external_id` as your primary user identifier for portability and simplicity across your systems.
</Note>

***


# View user identity (by subscription)
Source: https://documentation.onesignal.com/reference/fetch-identity-by-subscription

GET /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Retrieve all aliases linked to a user using a known `subscription_id`. This is useful when the user’s identity is unknown but you have access to one of their push, email, or SMS subscriptions.

## Overview

Use this API when you want to find the full identity (all aliases) of a user, starting from a known `subscription_id`. This is helpful for debugging, reverse lookups, or support use cases where only a subscription record is available.

<Note>
  Unlike the [View user identity](/reference/fetch-aliases) API which starts with an alias (e.g., `external_id`), this endpoint works when only a subscription ID is known.
</Note>

See [Subscriptions](/docs/en/subscriptions) for background on how subscriptions relate to users.

***

## How to use this API

To use this endpoint, you must provide:

* `subscription_id` – A UUID generated by OneSignal when a device or channel (e.g., push, email, SMS) is registered.

<Warning>
  `subscription_id` values are immutable and cannot be changed. Make sure you are using the correct value, as they are unique to each app and platform.
</Warning>

Once a valid `subscription_id` is provided, the API will return the user’s identity object, which includes all associated aliases like `external_id`, `onesignal_id`, and any custom aliases.

***


# Idempotent API requests
Source: https://documentation.onesignal.com/reference/idempotent-notification-requests

Prevent duplicate messages or custom events when retrying API requests.

## Overview

When you create messages or custom events via our REST API, network failures or timeouts can cause uncertainty about whether a request succeeded. **Idempotent requests** solve this problem by ensuring the same request is only processed once—even if it is sent multiple times.

This page explains how idempotency works in OneSignal, when to use it, and common pitfalls to avoid.

### When you should use idempotency

You should use idempotent requests any time you plan to retry API calls, especially when:

* You receive a timeout, 500-level error, or no response.
* Your infrastructure automatically retries failed requests.
* Delivering a duplicate message or custom event would be harmful.
* Missing a message or custom event would be harmful.

### The problem idempotency solves

Consider this common failure scenario:

1. You send a `notifications#create` or `custom_events#create` request.
2. OneSignal begins processing and sending the message or event.
3. A network error occurs before your client receives a response.

At this point, your system cannot know whether the request succeeded.

* If you retry and the request already succeeded, users may receive duplicates.
* If you do not retry and the request failed, users may miss important messages or events.

**Idempotency provides a safe retry mechanism.**

***

## How idempotency works

OneSignal supports idempotent operations for:

* [`notifications#create`](/reference/create-message)
* [`custom_events#create`](/reference/create-custom-events)

You provide a unique `idempotency_key` with each request.

### Request flow with idempotency

1. You send a request with an `idempotency_key`.
2. OneSignal processes the request and begins sending the message or creating the custom event.
3. A network error or timeout occurs.
4. You retry the request using the same `idempotency_key`.
5. OneSignal detects the duplicate and returns the result of the original request.
6. Only one notification or custom event is processed.

You can repeat this retry any number of times. As long as the `idempotency_key` remains the same, the operation will only be processed once.

***

## Idempotency key reference

<ParamField type="RFC 9562 UUID">
  A unique identifier used to prevent duplicate messages or custom events from repeat API calls. Keys must be unique [RFC 9562 UUID format](https://en.wikipedia.org/wiki/Universally_unique_identifier). Valid for 30 days.
</ParamField>

<Note>
  This `idempotency_key` property used to be called `external_id` but caused confusion with our [Users `external_id`](/docs/en/users) alias, so we have added this new property name to reduce confusion. Both will work in this case.
</Note>

***

## Important constraints and gotchas

<Warning> If you reuse the same `idempotency_key` for different messages or events, only the first request will be processed. </Warning>

Keep the following in mind:

* **Keys must be unique per logical operation**
  Generate a new UUID for every notification or custom event you intend to send.

* **Keys are retained for 30 days**
  After 30 days, OneSignal may delete the record. Reusing the same key after that window may result in a new message being sent.

* **Use a strong source of randomness**
  Predictable or reused UUIDs can cause unexpected deduplication.

* **Idempotency does not guarantee delivery**
  It only guarantees at-most-once processing. You should still monitor API responses and logs.

### Legacy behavior

The `idempotency_key` property was previously named `external_id`. This caused confusion with the Users `external_id` alias, so `idempotency_key` is now the recommended field name. Both names are currently supported.

### Best practices

* Always include `idempotency_key` when implementing retries.
* Store the `idempotency_key` alongside your request metadata for debugging.
* Retry only after honoring any `Retry-After` header returned by the API.
* Combine idempotency with proper timeout handling (for example, a 60-second HTTP timeout).

***


# Message history
Source: https://documentation.onesignal.com/reference/message-history

POST /notifications/{message_id}/history
View which subscriptions received a particular message

## Overview

This API enables you to retrieve all [Subscriptions](/docs/en/subscriptions) that received a specific push notification or email. You can access the notification's history for up to seven days after it was sent. Please note that notifications sent to fewer than 1,000 recipients will not record a "received" event, but they will still record "sent" events.

***

## How to Use this API

1. Submit a request to generate a report.

2. Decide delivery method

   * After receiving a successful response, **poll the destination URL** until the file becomes available. Exports typically complete within 1-3 minutes; we recommend a 10-second polling interval.
   * Alternatively, you can opt to receive an email to the address specified in the optional `email` parameter when the report is ready.

### Requirements

* A [OneSignal Professional or Enterprise Plan](https://onesignal.com/pricing).
* Enabled the "Send History via OneSignal API" option in Settings -> Integrations; notifications sent before this setting is enabled can't be retrieved.
* Requests must be made within seven days of sending the notification.

### Polling

Use the `csv_file_url` property in the response to test if the report is complete. If you receive a '403' error response, retry fetching the file after a short period; it only means we're still generating the report.

### Sample Report

The generated report is a simple CSV file that can be imported into any system for further processing.

```csv report.csv theme={null}
player_id,onesignal_id,external_id,target_channel,timestamp
"2c4fac95-7dfb-4113-9347-aba3a92ff557","ccddf35a-1233-4423-8a57-ac8c4b38eb81","a07aec27-2586-4b92-a24f-62660a1517fa","push","1628189160"
"68f5cf73-b20a-4de9-b6ee-79a863b8e7d8","d2f9f2f8-94af-4942-8183-115cef1213d5","4b66359f-3d94-4a73-806d-8ef5f0430b3d","push","1628187816"

```

### Limitations

* Querying for `opens` events are not supported.
* The `timestamp` column is included only for `clicked` events.

***


# Push notification
Source: https://documentation.onesignal.com/reference/push-notification

POST /notifications?c=push
Send a message using the push notification channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for push. See [Email](/reference/email) or [SMS](/reference/sms) to send to those channels.

Ensure your application is properly configured by following the [Mobile SDK Setup](/docs/en/mobile-sdk-setup) and/or [Web SDK Setup](/docs/en/web-sdk-setup) guides. You should see subscribed push [Subscriptions](/docs/en/subscriptions) in your OneSignal dashboard to send them messages.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***


# Rate limits and error handling
Source: https://documentation.onesignal.com/reference/rate-limits

Understand OneSignal API and application rate limits, common errors, retry behavior, and how to safely recover from failures without sending duplicate messages or disabling your app.

OneSignal uses rate limits and error responses as safety mechanisms to protect your app from accidental overloads, duplicate sends, and retry storms.

There are three categories to understand:

* **API rate limits** return HTTP `429` errors when request volume is too high.
* **Network timeouts or temporary server failures** return `5xx` errors or no response at all.
* **Application message limits** may temporarily disable your app if too many messages are sent in a short period.

<Info>
  Most apps never hit these limits during normal usage. When they do occur, they are usually caused by retries, loops, or unexpected audience expansion.
</Info>

<Check>
  **Quick implementation checklist**

  * Expect `429`, `5xx`, and timeouts. They are normal at scale.
  * Never retry message sends without an `idempotency_key`.
  * For non-urgent retries, wait **100 seconds** before retrying.
  * API rate limits (`429`) never disable your app.
  * Only message volume limits can disable your app.
  * `POST /notifications` (create) and `DELETE /notifications` (cancel) count toward the same rate limit.
  * The [Create custom events](/reference/create-custom-events) endpoint has its own rate limit, separate from the notification endpoints.
</Check>

***

## API rate limits

API rate limits apply **per app and per endpoint**. They are evaluated when a request is received, not when a response is returned.

These limits are designed to throttle traffic, not block your app.

| Endpoint                                                                                  | Rate limit                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create message](/reference/create-message) / [Cancel message](/reference/cancel-message) | **Free plans:** 150 requests/sec/app<br />**Paid plans:** 6,000 requests/sec/app<br /><br />The `POST /notifications` and `DELETE /notifications` endpoints share the same limit. Requests count toward it regardless of method. For example, 3,000 creates + 3,000 cancels = 6,000 requests/sec on a paid plan.<br /><br />Each request can target many users or segments. |
| [Create custom events](/reference/create-custom-events)                                   | Rate-limited independently from Create Message.<br />**Request size limits:** 2,024 bytes per event · 1 MB per request body                                                                                                                                                                                                                                                 |
| Create, update, or delete users or subscriptions                                          | 1,000 requests/sec/app<br />1 request/sec per user or subscription<br />Up to 100 property updates per request                                                                                                                                                                                                                                                              |
| View endpoints (messages, templates, users)                                               | 1 request/sec/app<br />Up to 10 look-back requests/sec                                                                                                                                                                                                                                                                                                                      |
| Message History and CSV exports                                                           | Keep parallel exports under 100 GB per file                                                                                                                                                                                                                                                                                                                                 |

<Note>
  High-volume messaging should use fewer message creation requests with larger audiences instead of increasing request frequency.
</Note>

**Handling API rate limit errors (`429`):**

When you exceed an API rate limit, OneSignal returns an HTTP `429` response:

```json theme={null}
{
  "errors": ["API rate limit exceeded."]
}
```

The response includes a `Retry-After` header indicating how many seconds to wait before retrying.

**What to do when you receive a `429` error:**

1. Stop sending requests immediately.
2. Wait for the full duration specified in the `Retry-After` header.
3. Retry using exponential backoff.
4. Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for retries that send messages.

<Warning>
  Retrying before the `Retry-After` delay or retrying in tight loops can extend throttling and increase failure rates.
</Warning>

***

## Error handling and retry strategies

Retries are safe only when implemented correctly. Some failed requests may still be processing on our servers.

* Retriable errors generally include network timeouts, no responses, 429, and 5xx errors.
* Non-retryable errors include 400, 401, or 403 errors which indicate invalid input, authentication problems, or missing permissions. These are not temporary failures.

**Simple retry strategy:**

* Wait **100 seconds** before retrying.
  * This aligns with the maximum API response timeout.
  * If no response or network error occurs, the request may still be processing during this window.
* Retry **up to 3 total attempts** (original + 2 retries).
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

**Time-sensitive (advanced) retry strategy:**

* Retry using exponential backoff with jitter (for example: 2s, 4s, 8s… up to 60s).
* Cap retries to **10 total attempts** and stop after **10–15 minutes**.
* For `429` responses, treat `Retry-After` as a minimum delay: wait `max(Retry-After, backoff)`.
* Always reuse the same [`idempotency_key`](/reference/idempotent-notification-requests) for each retry.

<Warning>
  Retrying message or custom event API requests without idempotency can result in duplicate messages or custom events.
</Warning>

<Accordion title="Example retry logic">
  ```text theme={null}
  attempt = 1
  max_attempts = 3

  send request with idempotency_key

  if response is success:
    stop

  if response is 429:
    wait Retry-After seconds
  elif response is 5xx or timeout:
    wait 100 seconds

  if attempt < max_attempts:
    retry with same idempotency_key
  else:
    fail safely
  ```
</Accordion>

### Retry decision guide

| Error type              | Retry? | When                 | Idempotency required |
| ----------------------- | ------ | -------------------- | -------------------- |
| `429 Too Many Requests` | Yes    | After `Retry-After`  | Yes                  |
| `5xx Server Error`      | Yes    | Backoff or 100s      | Yes                  |
| Timeout / no response   | Yes    | Immediate or delayed | Yes                  |
| `400 Bad Request`       | No     | Fix request          | No                   |
| `401 / 403`             | No     | Fix auth/permissions | No                   |

<Warning>
  Common implementation mistakes:

  * Retrying with a new idempotency key on each attempt.
  * Retrying indefinitely without a retry cap.
  * Retrying `400` or `401` errors without fixing the request.
  * Sending one request per user instead of batching audiences.
</Warning>

***

## Application message limits (app disablement)

Application message limits protect your users from receiving too many notifications in a short period of time.

**How the limit works:**

In any rolling 15-minute window, you may send up to **10 × your total number of subscribed [Subscriptions](/docs/en/subscriptions)**.

This limit is based on the total number of messages delivered, not the number of API requests.

* Sending 1 notification to 1,000 Subscriptions = 1,000 messages
* Sending 10 notifications to 1,000 Subscriptions each = 10,000 messages

The 15-minute window is rolling, not fixed.

* Messages are counted for 15 minutes after they are sent
* As time passes, older messages automatically stop counting
* You only exceed the limit if more than 10× your subscribed Subscriptions receive messages within the same 15-minute span

Example limits:

* App with 1,000 subscribed Subscriptions → up to 10,000 messages in any 15 minutes
* App with 10,000 subscribed Subscriptions → up to 100,000 messages in any 15 minutes

**Example scenarios:** App with 1,000 subscribed Subscriptions (limit: 10,000 messages per 15 minutes)

| Scenario                                                                              | Messages counted in any 15-minute period |    App disabled?    |
| ------------------------------------------------------------------------------------- | ---------------------------------------: | :-----------------: |
| At **12:00**, send 1 notification to 1,000 users                                      |                                    1,000 |          No         |
| At **12:00**, send 10 notifications to 1,000 users                                    |                                   10,000 |   Yes (hits limit)  |
| Between **12:00–12:14**, send 10,000 notifications to 1 user                          |                                   10,000 |   Yes (hits limit)  |
| Send **9,000 messages at 12:00**, then **9,000 more at 12:16**                        |                                    9,000 |          No         |
| Send **9,000 messages spread between 12:00–12:14**, then send **9,000 more at 12:15** |                                 \~18,000 | Yes (exceeds limit) |

<Note> This limit is evaluated continuously over a rolling 15-minute window, not in fixed time blocks. If any 15-minute span exceeds your limit, the app is disabled. </Note>

**What happens if the limit is exceeded:**

If your app sends more messages than allowed within a 15-minute window:

* Your app is temporarily disabled
* All app administrators receive an email notification
* A re-enable banner appears in the OneSignal Dashboard

<Warning> Only application message limits can disable your app. API rate limits (`429` errors) never disable apps. </Warning>

**What to do if your app is disabled:**

If your app is disabled, follow these steps in order:

1. Pause message sending from your backend, jobs, or automations.
2. Identify the cause, such as infinite loops, retry storms, or unexpected segment growth.
3. Log in to the OneSignal Dashboard.
4. Click **Re-enable** in the red banner at the top of the app.
5. If you need help re-enabling your app, contact `support@onesignal.com`.

***

## FAQ

### Do API rate limits disable my app?

No. API rate limits (`429` errors) only throttle your requests temporarily. Only [application message limits](#application-message-limits-app-disablement) — which track the total volume of messages delivered — can disable your app.

### What is an idempotency key and when do I need one?

An idempotency key is a unique identifier you include with a request so that retrying the same request does not create a duplicate message or event. You need one whenever you retry a `POST /notifications` or custom event request. Reuse the same key for every retry attempt. See [Idempotent API requests](/reference/idempotent-notification-requests).

### Can I increase my API rate limit?

Paid plans have higher rate limits (6,000 requests/sec vs. 150 for free plans). If you need limits beyond the paid tier, contact `support@onesignal.com` with your use case and expected volume.

### Why was my app disabled even though I didn't hit the API rate limit?

API rate limits and application message limits are separate. Your app can be disabled if the total number of messages delivered in any 15-minute window exceeds 10× your subscription count — even if every individual API request succeeded. Common causes include retry storms, runaway automations, or targeting a larger audience than intended.

***

## Related pages

<Columns>
  <Card title="Idempotent API requests" icon="rotate" href="/reference/idempotent-notification-requests">
    Prevent duplicate messages by reusing idempotency keys on retries.
  </Card>

  <Card title="Create message API" icon="paper-plane" href="/reference/create-message">
    API reference for sending push, email, SMS, and in-app messages.
  </Card>

  <Card title="Create custom event API" icon="bolt" href="/reference/create-custom-events">
    API reference for sending custom events that trigger Journeys.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="/docs/en/subscriptions">
    Understand how subscriptions are counted toward message limits.
  </Card>
</Columns>


# REST API overview
Source: https://documentation.onesignal.com/reference/rest-api-overview

Programmatic access to OneSignal messaging, user management, segments, and data exports over HTTPS with rate limiting and retry support.

The OneSignal REST API follows the [REST architecture](https://en.wikipedia.org/wiki/Representational_state_transfer) and provides programmatic access to core messaging and user features. Use the API to send push notifications, emails, and SMS, manage Users, Subscriptions, Segments, export data, and configure apps.

## Which API to use

| Goal                          | API                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| Send a push, email, or SMS    | [Create Message](/reference/create-message)                                                              |
| Add or update user data       | [Create User](/reference/create-user) / [Update User](/reference/update-user)                            |
| Target a group of users       | [Create Segments](/reference/create-segments) or use [Filters](/reference/create-message#filters) inline |
| Export analytics or user data | [CSV Export](/reference/csv-export) / [CSV of Events](/reference/export-csv-of-events)                   |
| Manage app configuration      | [Create App](/reference/create-an-app) / [Update App](/reference/update-an-app)                          |

***

## Requirements

**General**

* **HTTPS required**: All API requests must use HTTPS with **TLS 1.2 or higher** on port `443`.
* **Network access**: Firewalls or proxies must allow **outbound traffic** to `https://api.onesignal.com` on port `443`.
* **DNS TTL**: Clients must respect OneSignal’s DNS **TTL of 300 seconds** to avoid stale IP resolution.

**Incoming Traffic to OneSignal (API & SDK Requests)**

All incoming API traffic—whether from your backend, the OneSignal SDKs, or the dashboard—passes through **Cloudflare**, which serves as the global edge network.

* You may see Cloudflare IP addresses in logs.
* Cloudflare IPs may change over time.
* If you maintain a strict firewall, use Cloudflare’s official [IP ranges](https://www.cloudflare.com/ips/)

<Warning>
  Avoid allowlisting specific Cloudflare IPs, as they may change without notice.
</Warning>

**Outgoing Traffic from OneSignal (Webhooks & Event Streams)**

For features where OneSignal sends HTTP requests to your servers (such as webhooks or event streams), traffic originates from OneSignal infrastructure running on Google Cloud Platform (GCP) in the `europe-west4` region (Groningen, Netherlands).

* Allow inbound traffic from `https://api.onesignal.com`, **or**
* Use GCP’s maintained IP range list and filter by `europe-west4` region: [GCP IP ranges](https://www.gstatic.com/ipranges/cloud.json)

<Note>
  OneSignal supports [IP allowlisting](/docs/en/keys-and-ids) with REST API keys.
</Note>

***

### Platform-specific network requirements

#### FCM (Google Android and Chrome push)

* Required ports: `5228`, `443`, `5229`, and `5230`
* No IP allowlisting needed
* More info: [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

#### APNs (Apple iOS, iPadOS, Safari push)

* Required ports: `5223`, `443`, and `2197`
* Recommended servers:
  * Sandbox: `api.sandbox.push.apple.com:443`
  * Production: `api.push.apple.com:443`
  * IP range: `17.0.0.0/8`
* More info:
  * [Apple Support](https://support.apple.com/en-us/102266)
  * [APNs Developer Docs](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns?language=objc)

***

## Core API capabilities

### Send messages

See the [Create Message guide](/reference/create-message) to get started. Programmatically send:

<Columns>
  <Card title="Push Notifications" icon="bell" href="/reference/push-notification">
    Send push notifications to apps and websites.
  </Card>

  <Card title="Email" icon="envelope" href="/reference/email">
    Send transactional and promotional emails.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/reference/sms">
    Send SMS or MMS messages globally.
  </Card>

  <Card title="Live Activities" icon="tower-broadcast" href="/reference/start-live-activity">
    Send Live Activity updates to iOS devices.
  </Card>
</Columns>

<Note>
  For platform-specific features like personalization, throttling, and frequency capping, see the [Push](/docs/en/push), [Email](/docs/en/email-messaging), [SMS](/docs/en/sms-messaging), and [Live Activities](/docs/en/live-activities) overview guides.
</Note>

***

### Manage templates

[Templates](/docs/en/templates) are reusable push, email, and SMS messages that simplify development and improve consistency.

<Columns>
  <Card title="Create template" icon="plus" href="/reference/create-template">
    Save a reusable message layout for push, email, or SMS.
  </Card>

  <Card title="Update template" icon="pen-to-square" href="/reference/update-template">
    Modify an existing template's content or settings.
  </Card>

  <Card title="View templates" icon="eye" href="/reference/view-templates">
    List all templates in your app with their metadata.
  </Card>

  <Card title="Delete template" icon="trash" href="/reference/delete-template">
    Permanently remove a template from your app.
  </Card>
</Columns>

***

### Track custom events

[Custom events](/docs/en/custom-events) record user actions like purchases, content views, or milestones. Use them to enter users into [Journeys](/docs/en/journeys-settings) or trigger [Wait Until](/docs/en/journeys-actions) nodes.

<Card title="Create custom events" icon="bolt" href="/reference/create-custom-events">
  Record user events to trigger Journeys and track behavior.
</Card>

***

### Manage Users and Subscriptions

See the [Users](/docs/en/users) and [Subscriptions](/docs/en/subscriptions) guides for more details.

<Columns>
  <Card title="Create user" icon="user-plus" href="/reference/create-user">
    Create a user with optional aliases and subscriptions.
  </Card>

  <Card title="View user" icon="eye" href="/reference/view-user">
    View user details.
  </Card>

  <Card title="Update user" icon="user-pen" href="/reference/update-user">
    Modify a User's properties, tags, or aliases.
  </Card>

  <Card title="Delete user" icon="user-minus" href="/reference/delete-user">
    Permanently remove a User and all associated data.
  </Card>
</Columns>

***

### Manage Segments

[Segments](/docs/en/segmentation) group Users by filters for targeted messaging.

<Columns>
  <Card title="Create Segments" icon="plus" href="/reference/create-segments">
    Define a new Segment with filters to group Users.
  </Card>

  <Card title="Update Segment" icon="pen-to-square" href="/reference/update-segment">
    Modify a Segment's name or replace its filters.
  </Card>

  <Card title="Delete Segments" icon="trash" href="/reference/delete-segments">
    Permanently remove a Segment from your app.
  </Card>
</Columns>

<Note>
  You can also target users dynamically using [filters](/reference/create-message#filters) without creating persistent segments.
</Note>

***

### Export data

For analytics breakdowns, see [Analytics overview](/docs/en/analytics-overview).

<Columns>
  <Card title="Export CSV of subscriptions" icon="file-export" href="/reference/csv-export">
    Export all user and subscription data.
  </Card>

  <Card title="Export CSV of events" icon="file-export" href="/reference/export-csv-of-events">
    Export events like sent, received, and clicked.
  </Card>

  <Card title="View messages" icon="eye" href="/reference/view-messages">
    View message details and analytics.
  </Card>

  <Card title="View message" icon="magnifying-glass" href="/reference/view-message">
    View individual message details.
  </Card>
</Columns>

***

### Manage Apps & API Keys

OneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See [Apps, orgs, & accounts](/docs/en/apps-organizations).

<Columns>
  <Card title="Create an app" icon="plus" href="/reference/create-an-app">
    Register a new app with platform credentials.
  </Card>

  <Card title="Update an app" icon="pen-to-square" href="/reference/update-an-app">
    Modify app settings or platform credentials.
  </Card>

  <Card title="View single app" icon="eye" href="/reference/view-an-app">
    Retrieve configuration and details for one app.
  </Card>

  <Card title="View multiple apps" icon="list" href="/reference/view-apps">
    List all apps in your account.
  </Card>
</Columns>

#### API key management

See [Keys & IDs](/docs/en/keys-and-ids) for more details.

<Columns>
  <Card title="Create API key" icon="key" href="/reference/create-api-key">
    Generate a new API key with specific permissions.
  </Card>

  <Card title="View API keys" icon="eye" href="/reference/view-api-keys">
    List all API keys and their permissions for your app.
  </Card>

  <Card title="Delete API key" icon="trash" href="/reference/delete-api-key">
    Revoke an API key permanently.
  </Card>

  <Card title="Update API key" icon="pen-to-square" href="/reference/update-api-key">
    Modify an API key's permissions or IP allowlist.
  </Card>
</Columns>

***

## Error handling and retries

The OneSignal API may return temporary errors such as `429` (rate limited), `5xx` (server errors), or timeouts. When this happens, the request may still be processing. If you retry failed requests, always use an `idempotency_key` and follow the recommended retry delays to avoid duplicate messages.

<Card title="Rate limits and error handling" icon="triangle-exclamation" href="/reference/rate-limits">
  Retry strategies, error definitions, and recovery steps.
</Card>

***

## FAQ

### What is the timeout for API responses?

* Default: **100 seconds**
* If you're unsure whether a request completed, use an [`idempotency_key`](/reference/idempotent-notification-requests) to safely retry.
* See [Rate limits and error handling](/reference/rate-limits) for more details.

### Do I need to download or renew certificates to call the OneSignal API?

No. The OneSignal API uses HTTPS with a publicly trusted TLS certificate managed by Cloudflare. These edge certificates renew automatically and are trusted by all major browsers, operating systems, and runtimes.

If your network pins a specific leaf certificate, it will expire and rotate every few months — this is normal Cloudflare behavior. Trust the root and intermediate CAs in the chain instead of the leaf certificate to avoid disruption.

<Accordion title="Certificate pinning details and workarounds">
  * **Best practice**: Trust the root and intermediate CAs in the chain instead of the rotating leaf certificate.
  * **If you must pin a certificate**: Pin the public key (SPKI) of the CA or use a backup key set, not the exact leaf certificate.
  * **Fetching the current certificate**: If your process requires the active leaf certificate, retrieve it directly:

  ```bash theme={null}
  SERVERNAME=api.onesignal.com
  echo -n | openssl s_client -connect $SERVERNAME:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/${SERVERNAME}_current.pem
  ```

  To retrieve the full chain, add the `-showcerts` flag to `openssl s_client`.

  See [Cloudflare SSL/TLS documentation](https://developers.cloudflare.com/ssl/get-started/) and [Cloudflare Edge Certificates documentation](https://developers.cloudflare.com/ssl/edge-certificates/) for more details.
</Accordion>

### Why am I getting a 403 Forbidden error?

A `403` response means the API key is valid but does not have permission for the requested operation. Check the following:

* **Wrong key type**: App API keys work for app-level endpoints (sending messages, managing Users). Organization API keys are required for org-level endpoints (creating apps, managing API keys). See [Keys & IDs](/docs/en/keys-and-ids) for details.
* **IP allowlisting**: If IP allowlisting is enabled on your API key, requests from IPs not on the list are denied. Verify your server's IP is included.
* **Revoked or rotated key**: If the key was recently rotated, the old key is no longer valid. Update your integration with the new key.

### Why am I getting "UnknownHostException - Unable to resolve host api.onesignal.com"?

This error means your environment cannot resolve the DNS for `api.onesignal.com`. Common causes:

* **Firewall or proxy blocking DNS**: Ensure your network allows outbound DNS queries and traffic to `api.onesignal.com` on port `443`.
* **No internet connectivity**: Verify the device or server has an active network connection.
* **DNS server misconfiguration**: Try a public DNS resolver like `8.8.8.8` (Google) or `1.1.1.1` (Cloudflare) to rule out local DNS issues.
* **Stale DNS cache**: Flush your local DNS cache and ensure your client respects the TTL of 300 seconds.


# SMS
Source: https://documentation.onesignal.com/reference/sms

POST /notifications?c=sms
Send a message using the SMS channel.

## Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for SMS and MMS. See [Push notification](/reference/push-notification) or [Email](/reference/email) to send to those channels.

Ensure your [SMS setup](/docs/en/sms-setup) is complete.

<Note>
  Review the [Sending messages with the OneSignal API](/reference/create-message) guide for details on how to structure your messages.

  * [Select your target audience](/reference/create-message#choose-your-target-audience)
  * [Craft your message](/reference/create-message#craft-your-message)
  * [Schedule & per-user delivery options](/reference/create-message#schedule-%26-per-user-delivery)
</Note>

***

## Trackable links

Add trackable links to your SMS `contents` using [liquid syntax](/docs/en/using-liquid-syntax) in the format `{{'your_url' | track_link}}`.

Example:

```json JSON theme={null}
{
  "contents": {
    "en": "Hi, here's my link: {{'https://example.com' | track_link}} "
  }
}
```

In this example, the liquid syntax block will be replaced with a trackable short link and display in the message as: `1sgnl.co/XXXX`.

<Note>
  See [SMS trackable links](/docs/en/links#sms) for more details.
</Note>

***


# Start Live Activity
Source: https://documentation.onesignal.com/reference/start-live-activity

POST /apps/{app_id}/activities/activity/{activity_type}
Remotely start a Live Activity on iOS devices via OneSignal's REST API. Define the activity type, target users, and send dynamic, updatable content directly to a Live Activity interface.

## Overview

Remotely start an iOS Live Activity using OneSignal’s REST API. Live Activities provide real-time updates directly on the lock screen and Dynamic Island (on supported devices), enhancing user engagement with ongoing events like sports games, deliveries, or countdowns.

***

## How to use this API

1. Define a Live Activity in your app. See [Live Activities developer setup](/docs/en/live-activities-developer-setup) to get started.
2. Use the `activity_type` parameter to specify the type of the Live Activity UI to use.
3. Select your target audience to receive the Live Activity. Target all or individual users.
4. Generate a unique `activity_id` to track and manage your Live Activity.
5. Use the `event_attributes` parameter to initialize the Live Activity with static data.
6. Use the `event_updates` parameter to update the Live Activity with dynamic content.

### Select your target audience

Before sending a message, you need to determine who should receive it. OneSignal offers three targeting options:

1. **Aliases & Subscription IDs**: Send messages to specific users using unique identifiers such as External ID (recommended), OneSignal ID, custom alias, or subscription ID.
2. **Segments**: Target predefined user groups based on attributes and behavior.
3. **Filters**: Create custom targeting rules using user properties, such as tags, location, or activity.

<Note>
  You can only use one targeting method per message. For example, you cannot combine alias-based targeting with filters in the same request.

  See [Select your target audience](/reference/create-message#select-your-target-audience) for more information.
</Note>

### Set a unique `activity_id`

* Set a unique `activity_id` to track and manage the Live Activity. This value is crucial for maintaining a consistent reference to the Live Activity across different devices and sessions. Consider using a UUID, CUID, or NanoID for this parameter.
* Ensure that the `activity_id` is unique and consistently used for each Live Activity to avoid conflicts and ensure accurate tracking.

  ```json Example theme={null}
  {
    "activity_id": "217aae2b-42ee-4097-bc3f-b7a6e9d15b9b",
    ...
  }
  ```

<Info>
  See [Live Activities developer setup](/docs/en/live-activities-developer-setup) guide for more information.
</Info>

### Set `event_attributes` to initialize the Live Activity

Set default/static data to display in the Live Activity upon start.

```json Example theme={null}
{
  "event_attributes": {
  	"awayTeam": "Away Team Name",
    "homeTeam": "Home Team Name"
  }
}
```

### Set `event_updates` for dynamic content

The content used to update a running Live Activity. The object must conform to the `ContentState` interface defined within your app's Live Activity. See [Live Activities developer setup](/docs/en/live-activities-developer-setup).

Ensure that the `event_updates` object matches the [`ContentState`](https://developer.apple.com/documentation/activitykit/activityattributes/contentstate#) interface exactly as defined in your Live Activity implementation. Inconsistencies can cause Live Activities to fail to display.

```json Example theme={null}
{
  "event_updates": {
    "quarter": 1,
    "homeScore": 70,
    "awayScore": 78,
    "inTimeout": false
  }
}
```

***


# Update Live Activity
Source: https://documentation.onesignal.com/reference/update-live-activity-api

POST /apps/{app_id}/live_activities/{activity_id}/notifications
Update or terminate running iOS Live Activities using OneSignal’s Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

## Overview

Update or terminate running iOS Live Activities using our REST API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

Before using this API, ensure your app is properly configured by following the [Live Activities developer setup](/docs/en/live-activities-developer-setup).

## How to Use this API

1. Select the Live Activity to update by specifying its `activity_id` in the URL. This is set when using the:

* [Start Live Activity API](/reference/start-live-activity)
* [Triggering it in-app](/docs/en/live-activities-developer-setup).
* [`LiveActivities.enter` SDK method](/docs/en/mobile-sdk-reference#enter)

2. Update the state of the Live Activity by setting the `event_updates` parameter to a JSON object that matches the structure of the `ActivityAttributes.ContentState` struct defined in your Live Activity widget extension.

3. When ready to terminate the Live Activity:

* Set the `event` parameter to `end`
* Include a `dismissal_date` if you want the Live Activity to be dismissed in less than 4 hours.
* Set the `dismissal_date` to a time in the past to dismiss the Live Activity immediately. User must have clicked "Allow" for the Live Activity to be removed programmatically.

<Warning>
  Once a Live Activity `activity_id` is ended, you cannot update it. This includes changing the `dismissal_date` or `event` parameter.

  If the Live Activity is not being dismissed immediately, it is either because:

  * The `activity_id` has already been ended.
  * The user has not clicked "Allow" for the Live Activity to be removed programmatically.
</Warning>

***


# Update user
Source: https://documentation.onesignal.com/reference/update-user

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}
Modify a user's properties.

<Warning>
  If you are still using pre-User Model APIs or SDKs (Mobile SDKs version 4 or
  lower, Web SDKs version 15 or lower), we recommend thorough testing of this
  endpoint before switching to the new User Model. Discrepancies may occur where
  the External ID set through the SDK and the External ID set through the API do
  not generate matching OneSignal IDs. To ensure a smooth transition, consider
  the following options:

  * **Update to the User Model SDKs:** Upgrade to the latest User Model SDKs (Mobile SDK 5+, Web SDK 16+). For more details, refer to the [User Model Migration Guide](/docs/en/user-model-migration-guide).
  * **Continue Using Pre-User Model APIs:** If you are not ready to migrate, continue using the existing APIs for [Adding a Device](/reference/add-a-device), [Editing Tags with External User ID](/reference/edit-tags-with-external-user-id), and [Editing a Device](/reference/edit-device) until the SDK migration is complete.
</Warning>

## Overview

This endpoint updates user-level properties for an existing user in your OneSignal app.

* To change a user's `identity` like `external_id` or custom [Aliases](/docs/en/aliases), use the [Create alias](/reference/create-alias) and [Delete alias](/reference/delete-alias) APIs.
* To manage a user's `subscriptions`, use the [Create Subscription by alias](/reference/create-subscription) or [Create user](/reference/create-user) APIs.

***

## How to use this API

You must supply an alias in the request path:

* `alias_label`: The type of identifier (e.g., `external_id`, `onesignal_id`, or a custom alias label).
* `alias_id`: The corresponding value for that label.

See [Users](/docs/en/users) and [Aliases](/docs/en/aliases) for more info.

***


# View message
Source: https://documentation.onesignal.com/reference/view-message

GET /notifications/{message_id}?app_id={app_id}
View the details of a single message and the Outcomes associated with it.

## Overview

The View message API allows you to fetch data from a single push, email, or SMS message at a time. If you want to get multiple messages at a time, use the [View messages](/reference/view-messages) API. In most cases, you will likely want to use [Event Streams](/docs/en/event-streams) instead.

Currently this API does not provide Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are only **accessible 30 days after creation**; however, messages sent using the OneSignal dashboard are accessible for the app's lifetime.

See our [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

This API is most commonly used when sending [Transactional messages](/docs/en/transactional-messages) to individual users. The response of our Create message API has an `id` which corresponds to the `message_id` used in this request. You can store this `message_id` on your server and (after giving your users some time to interact with the message) pull the data if desired.

For example, if you send a message targeting the `include_aliases` parameter, the response will include the aliases you set. If you send with the `included_segments` parameter, then the response will only provide the segments you set. When targeting segments or filters, you can use the [Export audience activity CSV](/reference/export-csv-of-events) API to get the user event data.

To view outcome data for the message, you must include the `outcome_name` parameter with the name of the outcome you want to fetch, along with the accompanying aggregation type (.count or .sum), for example: `os__click.count`. For more information on outcome definitions, see [View Outcomes](/reference/view-outcomes).

***


# View messages
Source: https://documentation.onesignal.com/reference/view-messages

GET /notifications?app_id={app_id}&limit={limit}&offset={offset}&kind={kind}&template_id={template_id}&time_offset={time_offset}
View the details for a collection of messages.

## Overview

The View messages API fetches data for up to 50 push, email, or SMS messages at a time. To fetch a single message, use the [View message](/reference/view-message) API. In most cases, use [Event Streams](/docs/en/event-streams) instead.

This API does not return Journey-sent messages. See [Journey analytics](/docs/en/journeys-analytics) for details.

Messages sent through the API are **retained for 30 days** after creation; messages sent through the OneSignal dashboard are retained for the app's lifetime.

See [Rate limits](/reference/rate-limits) for details on how often you can pull your message data with this API.

***

## How to use this API

Use time-offset pagination for sequential pulls of all messages, and standard pagination for ad-hoc queries. For ETL or bulk export pipelines, use [Event Streams](/docs/en/event-streams) instead.

Filter results to a specific message kind or template using the `kind` and `template_id` query parameters. Both filters work with either pagination style.

### Optimized pagination with time offset

To efficiently retrieve all available messages for an app, use `time_offset`-based pagination. When `time_offset` is specified, the sort order changes from descending to ascending — the oldest messages appear first based on the [`send_after` date](/reference/create-message#send-after).

#### Accepted `time_offset` values

* ISO 8601 formatted timestamp — for example, `2025-01-01T00:00:00.000Z` (January 1, 2025, at 00:00 UTC).
* Opaque cursor token (Base64-encoded) — provided in the API response as `next_time_offset`.

<Steps>
  <Step title="Initial fetch">
    To fetch messages from a specific date onward, set `time_offset` to an ISO 8601 formatted timestamp. For example, to retrieve messages sent since January 1, 2025: `time_offset=2025-01-01T00:00:00.000Z`.

    <Note>
      * `time_offset` cannot be used with the standard `offset` parameter.
      * `time_offset` excludes messages that match the exact timestamp to avoid duplicates.
      * The response includes `next_time_offset`, a cursor token for the next page. No decoding required. For example: `"next_time_offset": "MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw=="`
    </Note>
  </Step>

  <Step title="Fetch additional pages">
    Use `next_time_offset` from the previous response as the `time_offset` value in the next request. For example: `time_offset=MjAyNS0wMi0xOVQxOToxNjo0OS41Njg5NTFaIzQ2ZWVjMTAzLWQ5OGYtNGQzZC04MzA5LWQxNWI1M2QzMjQ5Nw==`.
  </Step>

  <Step title="Continue until completion">
    Repeat the request until an empty `notifications` array is returned, indicating all messages have been fetched.
  </Step>

  <Step title="Handling new messages">
    Because results are sorted ascending, new messages are added to the end. To resume fetching from where you left off, reuse the last `next_time_offset` that returned an empty response.
  </Step>
</Steps>

### Standard pagination

Use the `limit` and `offset` parameters to page through notifications for an app. The maximum result size is 50, and the default `limit` is `50`. Use `limit` to specify the result size and `offset` to increment by the limit value with each request.

For example, the first request uses `offset=0`, the second `offset=50`, the third `offset=100`, and so on.

Standard pagination is convenient for ad-hoc queries but degrades as the `offset` value grows. For sequential pulls of all messages, use time-offset pagination.

***


# View user
Source: https://documentation.onesignal.com/reference/view-user

GET /apps/{app_id}/users/by/{alias_label}/{alias_id}
Retrieve a user including aliases, properties, and subscriptions.

## Overview

* Use this API to retrieve a user's full profile, including identity aliases, user properties, and messaging subscription details across channels.
* This is helpful for verifying user data, debugging subscription issues, or syncing OneSignal user data with your internal systems.

For detailed concepts and guides, see [Users](/docs/en/users), [Subscriptions](/docs/en/subscriptions), and [Aliases](/docs/en/aliases) documentation.

## How to use this API

To look up a user, you must provide both an `alias_label` and an `alias_id`. In most cases, your `external_id` will serve as the `alias_label`, and its value will be passed as the `alias_id`. While you may use a custom alias, we strongly recommend setting and using the `external_id` as your primary user identifier for consistency across platforms.

To retrieve a user using their OneSignal ID, set the `alias_label` to `onesignal_id`. **Note**: When querying with any alias other than `onesignal_id`, authentication is required.

***


# Add a player
Source: https://documentation.onesignal.com/reference/add-a-device

POST `https://onesignal.com/api/v1/players`

Register a new Subscription (aka player) to one of your OneSignal apps.

<Warning>
  This is a Legacy API. Use [Create User](/reference/create-user) or [Create Subscription](/reference/create-subscription) instead.
</Warning>

***

## Headers

| Header          | Value                     | Required | Description                      |
| --------------- | ------------------------- | -------- | -------------------------------- |
| `Content-Type`  | `application/json`        | Yes      | The content type of the request. |
| `Authorization` | `Basic YOUR_REST_API_KEY` | Yes      | Your OneSignal REST API key.     |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                                |
| -------------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                                     |
| `device_type`        | integer | Yes      | Device platform: 0 = iOS, 1 = Android, 2 = Amazon, 3 = Windows Phone, etc. |
| `identifier`         | string  | No       | Push token, email address, or phone number.                                |
| `language`           | string  | No       | Language code (e.g. "en").                                                 |
| `timezone`           | integer | No       | Time zone offset in seconds.                                               |
| `game_version`       | string  | No       | Version of your app.                                                       |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                                         |
| `device_os`          | string  | No       | Operating system version (e.g., "13.3").                                   |
| `ad_id`              | string  | No       | Advertising ID.                                                            |
| `sdk`                | string  | No       | OneSignal SDK version (e.g., "050201" for 5.2.1).                          |
| `session_count`      | integer | No       | Number of times the user has used the app.                                 |
| `tags`               | object  | No       | Custom tags as key-value pairs.                                            |
| `external_user_id`   | string  | No       | Your system's user ID for this device.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc.                 |

***

## Example Request

```json theme={null}
POST /api/v1/players HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "device_type": 1,
  "identifier": "abcdef123456",
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_model": "Pixel 4",
  "device_os": "12",
  "ad_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sdk": "050401",
  "session_count": 5,
  "tags": {
    "user_type": "free",
    "level": "10"
  },
  "external_user_id": "user123",
  "notification_types": 1
}
```

***

## Response

```json theme={null}
{
  "id": "Subscription_id_string"
}
```

## Errors

* 400 Bad Request – Invalid parameters or missing required fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Not allowed for your account type or plan.


# Copy template to another app
Source: https://documentation.onesignal.com/reference/copy-template-to-another-app

POST /templates/{template_id}/copy_to_app?app_id={app_id}
Create a duplicate of a template in another app. The new template will be completely separate from the original (including having a new template_id) but will be created with all the same content.

## Overview

This API allows you to copy a template from one app (`app_id`) to another (`target_app_id`). The duplicated template will have the same content as the original, but a new unique `template_id`.

<Note>
  If you are trying to copy an email template, we also have an [Email Template Forwarding](/docs/en/email-template-forwarding) feature that does not require an API call.

  Both options support HTML and Drag & Drop email templates.
</Note>

***

## Requirements

* **Organization Membership:** Both the `app_id` and `target_app_id` must belong to the same [Organization](/docs/en/apps-organizations).
* **Authorization Required:** You must use your [Organization API key](/docs/en/keys-and-ids#organization-api-key), not an app-level REST API key.
* **Permissions Note:** Your user must have admin-level access to both the source and target apps. If not, the request will fail with a "permission denied" error.

***

## Parameters

* `template_id` (path param): UUID of the template to be copied.
* `app_id` (query param): ID of the app where the original template exists.
* `target_app_id` (body param): ID of the app where the template will be duplicated.

***

## How to Use

### 1. Locate the Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

### 2. Get App IDs

Refer to [Keys & IDs](/docs/en/keys-and-ids) to find your `app_id` and `target_app_id`.

***

## Response

The response will include:

* The new `template_id` for the copied template
* Confirmation of successful creation
* Any warnings if applicable (e.g., limited fields copied)

***


# Create or update alias
Source: https://documentation.onesignal.com/reference/create-alias

PATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
Create or update one or more user aliases when you already know an existing alias. This API performs an upsert on the user’s identity object—either adding new aliases or updating existing ones.

## Overview

Use this API to manage user aliases by providing one known alias (such as `external_id`, `onesignal_id`, or a custom alias) and specifying additional aliases to add or update.

This endpoint focuses solely on the `identity` object. If you need to fully create a user with subscriptions and properties, use the [Create user](/reference/create-user) API instead.

<Note>
  * If an alias with the same `alias_label` already exists for the user, it will be updated. If it doesn’t exist, a new alias will be created.
  * Want to use a subscription instead of an alias to identify the user? Use [Create alias (by subscription)](/reference/create-alias-by-subscription).
</Note>

See also:

* [Users](/docs/en/users) – for details on OneSignal ID and External ID
* [Aliases](/docs/en/aliases) – for setting and managing custom aliases
* [Delete alias](/reference/delete-alias) – for removing aliases

***

## How to use this API

To identify the user:

* Use `alias_label` for the type of alias you know (e.g., `external_id`, `onesignal_id`, or a custom alias)
* Use `alias_id` for the value of that alias

<Note>
  We strongly recommend setting the `external_id` as your primary user identifier. This can be done through our frontend SDK's login method when a user signs in to your app or website. It helps OneSignal associate the user's push, email, and SMS subscriptions to a unified user identity.
</Note>

Changes to the identity object take effect immediately upon request.

Alias keys (`alias_label`) and values (`alias_id`) are each limited to **128 characters**. A user can have up to **10 custom aliases** total.

***


# Create alias (by subscription)
Source: https://documentation.onesignal.com/reference/create-alias-by-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/user/identity
Create or update an alias for a user using a known subscription ID.

Create or update an alias for a user using a known subscription ID.

# Overview

Use this API to add or update aliases associated with a user when you only know at least one subscription ID. This API is handy for scenarios where the user's identity is unknown, but a subscription is available.

To remove an alias, see [Delete alias](/reference/delete-alias) API.

***

# How to use this API

You must know the `subscription_id` of the subscription that belongs to the user in which you want to update. Subscription IDs are UUIDs generated by OneSignal and cannot change. See [Subscriptions](/docs/en/subscriptions) for details.

This endpoint performs an upsert—if the user already has an alias with the specified alias label, it gets updated; otherwise, a new alias will be created.

The request body must include an identity object containing one or more aliases to be created or updated.

The OneSignal ID is read-only and used only for fetching. See [Users](/docs/en/users) for details.

Aliases are updated immediately upon request.

***


# Create an app
Source: https://documentation.onesignal.com/reference/create-an-app

POST /apps
Programmatically create a new OneSignal app via the REST API. This guide explains required fields, supported platform configurations (Web, Android, iOS), and how to properly authenticate using your Organization API key.

## Overview

Use this API to programmatically create a new OneSignal app. This is useful for automating app setup, particularly when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need to Base64 encode your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns):

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates):

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Create API key
Source: https://documentation.onesignal.com/reference/create-api-key

POST /apps/{app_id}/auth/tokens
Use the OneSignal API to create a new Rich Authentication Token (App API Key) for a specific app. This guide explains how to authenticate with the Organization API key and configure optional IP allowlists using CIDR notation.

## Overview

Use this API to create a new **App API Key** (also called a **Rich Authentication Token**) for a specific OneSignal app. These keys are used to authenticate API requests at the app level and offer enhanced security features, including optional IP allowlisting.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

### IP allowlisting

By default, the API key will not be restricted to any specific IP addresses. To enable IP allowlisting, you need to set the `ip_allowlist_mode` parameter to `explicit` and provide a list of allowed IP addresses in the `ip_allowlist` parameter.

If you want to set the explicit range of IPs that can use this API key, add them by setting `ip_allowlist_mode` to `explicit` and in `ip_allowlist` add the IPs in CIDRs notation as an array of string values.

***


# Create segment
Source: https://documentation.onesignal.com/reference/create-segments

POST /apps/{app_id}/segments
Programmatically create segments in your OneSignal app using flexible filters and targeting rules.

## Overview

Use this API to create new [Segments](/docs/en/segmentation) programmatically. These segments are then accessible in the OneSignal Dashboard and usable in messages, Journeys, and in-app messaging campaigns.

<Note>
  To modify an existing segment, use the [Update segment](/reference/update-segment) API.
</Note>

***

## How to use this API

This endpoint allows your backend to define audience segments by passing in a combination of filters and logical operators like `"AND"` and `"OR"`, mirroring the segmentation capabilities of the OneSignal Dashboard.

### Name the segment

The name of the segment as it shows in the OneSignal dashboard and accessible via the `included_segments` and `excluded_segments` targeting parameters.

### Describe the segment

Optionally include a `description` (max 255 characters) to record the segment's purpose. The description is returned by the [View segments](/reference/view-segments) and [View segment](/reference/view-segment) APIs.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "10"}
  ]
}
```

### Define the `filters`

Available filters:

* [operator](#operator)
* [tag](#tag)
* [last\_session](#last_session)
* [first\_session](#first_session)
* [session\_count](#session_count)
* [session\_time](#session_time-1)
* [language](#language)
* [app\_version](#app_version)
* [location](#location)
* [country](#country)

### `operator`

**Description**

Allows you to combine or separate properties. Filters combined with an `"AND"` have higher priority than `"OR"` filters.

* `"AND"` = the 2+ connected filters must be satisfied for the recipient to be included. Filter entries use this by default and its not required to be included.
* `"OR"` = the 2 filters separated by the `"OR"` operator are mutually exclusive. The recipients only need to satisfy the conditions on either side of the `"OR"` operator.

<CodeGroup>
  ```json AND example theme={null}
  // Users must satisfy both filters to be included.
  // Notice the AND operator is not required

  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  // The same example using the AND operator. This is not required.
  "filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "AND"},
  {"field": "language", "relation": "=","value": "en"}
  ]

  ```

  ```json OR example theme={null}
  // Users can satisfy either filter to be included.

  "filters": [
    {"field": "tag", "key": "level", "relation": "=", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "level", "relation": "=", "value": "20"}
  ]
  ```

  ```json Combinations theme={null}
  // In this example, users must either have:
  // The specified session_count AND tag requirement
  // Or it will be all records where last_session is satisfied
  {
    "name": "2 filters or 1",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"}
    ]
  }

  // Similar to the first example, this shows how to require a specific field
  // across other filters

  {
    "name": "3 filters, 1 required across all",
    "filters": [
      {"field": "session_count", "relation": ">", "value": "2"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"},
      {"operator": "OR"},
      {"field": "last_session", "relation": "<", "hours_ago": "30"},
      {"operator": "AND"},
      {"field": "tag", "relation": "!=", "key": "tag_key", "value": "1"}
    ]
  }
  ```
</CodeGroup>

### `tag`

**Description**

Target based on custom user [Tags](/docs/en/add-user-data-tags).

<Warning>
  Do not use tags for targeting individual users like a "user id".
  Instead use [External ID](/docs/en/users) or custom [Aliases](/docs/en/aliases) and the `include_aliases` targeting property.
</Warning>

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"exists"`, `"not_exists"`, `"in_array"`, `"not_in_array"`, `"time_elapsed_gt"`, (time elapsed greater than) and `"time_elapsed_lt"` (time elapsed less than)
  * `time_elapsed_gt/lt` fields correspond to [Time Operators](/docs/en/time-operators) and require a paid plan.
* `key` = Tag key to compare.
* `value` = Tag value to compare. Not required for `"exists"` or `"not_exists"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

```json theme={null}
"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"operator": "OR"},
  {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"}
]
```

### `last_session`

**Description**

Time since the [Subscription](/docs/en/subscriptions) last used the app (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's last session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "last_session", "relation": ">","hours_ago": "10"}
  ]
  ```

### `first_session`

**Description**

Time since the [User](/docs/en/users) first used the app or was created within OneSignal (in `hours_ago`).

* `relation` = `">"` or `"<"`
* `hours_ago` = number of hours before or after the user's first session. Example: `"1.1"`

  ```json theme={null}
  "filters": [
    {"field": "first_session", "relation": "<","hours_ago": "24"}
  ]
  ```

### `session_count`

**Description**

Total number of sessions by the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="` or `"!="`
* `value` = number of sessions. Example: `"1"`

  ```json theme={null}
  "filters": [
    {"field": "session_count", "relation": ">","value": "5"}
  ]
  ```

### `session_time`

**Description**

Total time the [Subscription](/docs/en/subscriptions) has spent in the app, in seconds.

* `relation` = `">"` or `"<"`
* `value` = time in seconds the user has been in your app. Example: 1 day is `"86400"` seconds.

  ```json theme={null}
  "filters": [
    {"field": "session_time", "relation": ">","value": "86400"}
  ]
  ```

### `language`

**Description**

[User’s](/docs/en/users) language code (e.g., "en"). See [Multi-Language Messaging](/docs/en/multi-language-messaging) for details and [supported language codes](/docs/en/multi-language-messaging#supported-languages).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = 2 character language code. Example: `"en"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "language", "relation": "=","value": "en"},
    {"operator": "OR"},
    {"field": "language", "relation": "in_array","value": "es,fr,de"}
  ]
  ```

### `app_version`

**Description**

App version set on the [Subscription](/docs/en/subscriptions).

* `relation` = `">"`, `"<"`, `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = app version. Example: `"1.0.0"`
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "app_version", "relation": "=","value": "1.0.1"},
    {"operator": "OR"},
    {"field": "app_version", "relation": "in_array","value": "1.0.0,1.0.1"}
  ]
  ```

### `location`

**Description**

Target by GPS coordinates and radius. Location tracking must be turned on and accepted by the user. See [Location-Triggered Notifications](/docs/en/location-triggered-event) for details.

* `radius` = in meters
* `lat` = latitude
* `long` = longitude

  ```json theme={null}
  "filters": [
    {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
  ]
  ```

### `country`

**Description**

Country code of your [Users](/docs/en/users). Uses ISO 3166-1 Alpha-2 format (two-letter country code).

* `relation` = `"="`, `"!="`, `"in_array"`, or `"not_in_array"`
* `value` = Two-letter country code in uppercase. Example: `"US"`, `"GB"`, `"CA"`.
  For `"in_array"` and `"not_in_array"`, the value should be a comma-separated list of up to 20 values.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "=", "value": "US"},
    {"operator": "OR"},
    {"field": "country", "relation": "in_array", "value": "MA,GB,LK"}
  ]
  ```

***


# Create Subscription by alias
Source: https://documentation.onesignal.com/reference/create-subscription

POST /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions
Use this API to attach a new subscription—such as email, SMS, or push notification—to an existing OneSignal user identified by an alias.

## Overview

This API allows you to add a **new Subscription** to an existing [User](/docs/en/users) via an alias identifier. A *Subscription* reflects a user's intent to receive messages through a specific communication channel, such as email, SMS, or push notifications. See [Subscriptions](/docs/en/subscriptions) for additional context.

If you're looking to **create a new user and add Subscriptions simultaneously**, use the [Create User](/reference/create-user) API instead.

***

## How to use this API

To attach a Subscription, the user must already exist and be referenced using an alias. The `alias_label` and `alias_id` path parameters define how the user is identified:

* Common alias: `external_id`
* Other options: `onesignal_id`, or custom aliases

For details, refer to [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

## Required Fields

Each Subscription must include at least:

* `type`: the channel (e.g., `Email`, `SMS`, `iOSPush`)
* `token`: the unique identifier for the channel (e.g., email address, phone number, push token)

If the specified `type` and `token` already exist in the app, the Subscription will be transferred to the user identified in the path parameters.

***


# Create template
Source: https://documentation.onesignal.com/reference/create-template

POST /templates
Create reusable message templates for push, email, and SMS channels. Templates can be accessed through both the dashboard and API using a `template_id`.

## Overview

Use this endpoint to create a new message template in your OneSignal app. Once created, the template becomes available for use when sending messages via both the Dashboard and the REST API by referencing the `template_id`.

Templates streamline and standardize message content across push, email, and SMS channels.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Before using this endpoint, ensure that the target channel (push, email, or SMS) is properly configured in your OneSignal app. See [Channel Setup](/docs/en/channel-setup) for guidance.

### Push Templates

**Requirements:**

* Set the `contents` property with the English (`en`) language key.
* All [Push Channel Properties](/reference/push-notification) are valid for use in push templates.
* By default, all push platforms are enabled. You can target specific platforms by explicitly setting them (e.g., `isAndroid: true` disables others).

### Email Templates

**Requirements:**

* Set `isEmail: true`.
* Include both `email_subject` and `email_body`.
* All [Email Channel Properties](/reference/email) are valid for use in email templates.

### SMS Templates

**Requirements:**

* Set `isSMS: true`.
* Provide SMS-specific parameters like `contents`.
* All [SMS Channel Properties](/reference/sms) are valid for use in SMS templates.

***


# Export subscriptions CSV
Source: https://documentation.onesignal.com/reference/csv-export

POST /players/csv_export
Generate a GZip-compressed CSV export of your current subscription data using this API endpoint.

## Overview

Use this endpoint to request a GZip-compressed CSV export of all your [Subscriptions data](/docs/en/subscriptions) from OneSignal. The export includes both default and optional user data fields, and supports filters to refine the dataset. The file is downloadable via a URL returned in the API response.

***

## How to use this API

By default, this will export all Subscriptions within the app.

**Optional filters:**

You can narrow the export using:

* `segment_name`: Only export Subscriptions from a specific segment. Segment membership rules determine which subscription statuses are included. Use with `include_unsubscribed` to include unsubscribed subscriptions.
* `last_active_since`: Export Subscriptions where their `last_session` was after a specific Unix timestamp. Example: Use `1704067200` for Subscriptions active since January 1st, 2024.
* `include_unsubscribed`: When exporting a segment, set to `true` to include unsubscribed subscriptions alongside subscribed ones. By default, segment-filtered exports only return subscribed subscriptions. This parameter has no effect when `segment_name` is not provided.

**Example successful response:**

```json 200 OK theme={null}
{
  "csv_file_url": "https://onesignal.com/csv_exports/b2f7f966.../users_1849..._2024-11-10.csv.gz"
}
```

**Export time considerations:**

* Generation speed: \~2,000 records per second.
* File readiness: The `csv_file_url` may return a 404 until generation completes.
* Download retry: Poll the file URL at intervals until the file is ready.
* File expiration: The file remains available for 3 days after generation.
* Concurrency: Only one export per OneSignal account can run at a time.

**File not ready (404 response)**

```xml 404 CSV GET  theme={null}
This XML file does not appear to have any style information
associated with it. The document tree is shown below.
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

<Info>
  You can safely poll the `csv_file_url` until the file becomes available. Implement retry logic based on expected data volume and generation speed.

  Only one export is allowed at a time per account. Wait until the `.csv.gz` file is downloaded before triggering another export.
</Info>

***

## CSV data contents

The export includes two types of fields:

* **Default fields**: Always included unless excluded by schema changes.
* **Extra fields**: Must be explicitly requested using the `extra_fields` parameter.

### Default fields

* `id`: The Subscription ID.

* `identifier`: The push token, email address, or phone number depending on the Subscription type.

* `session_count`: The number of times the user has opened the app.

* `language`: The user's language in ISO 639-1 format.

* `timezone`: Deprecated — use `timezone_id` instead.

* `game_version`: The version of your app that the user is currently using.

* `device_os`: The device's operating system version.

* `device_type`: Integer representing channel/device type.
  * `0`: iOSPush
  * `1`: AndroidPush
  * `2`: FireOSPush
  * `5`: ChromePush
  * `7,17`: SafariPush
  * `11`: Email
  * `14`: SMS

* `device_model`: The device's hardware string.

* `ad_id`: Deprecated.

* `tags`: Custom key/value data.

* `last_active`: The last time the user was active.

* `playtime`: The total amount of time in seconds the user had the mobile app open.

* `created_at`: The first time the user was seen.

* `invalid_identifier`: Boolean flag for unsubscribed state.
  * `t`: Unsubscribed
  * `f`: Subscribed

### Extra fields (`extra_fields`)

Pass `extra_fields` in your request to include any of the following:

* `external_user_id`: Maps to the `external_id` of the user.

* `onesignal_id`: OneSignal's user ID.

* `location`: Adds the `lat` and `long` coordinates if set.

* `country`: The user's country in ISO 3166-1 Alpha 2 format.

* `ip`: The IP address if detected. Can be IPv4 or IPv6 format.

* `web_auth`: Only available to OneSignal SDKs. The `web_auth` key for web push.

* `web_p256`: Only available to OneSignal SDKs. The `web_p256` for web push.

* `unsubscribed_at`: The date and time the user last unsubscribed. They may resubscribe at any time. Check the `invalid_identifier` field to determine if they are currently subscribed.

* `notification_types`: Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/en/subscriptions#notification-types).

* `timezone_id`: The user's timezone in IANA format.

***


# Remove alias
Source: https://documentation.onesignal.com/reference/delete-alias

DELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}
Remove a specific alias from a user.

## Overview

Use this API to remove a specific alias from a user’s identity object without deleting the user. This operation only affects user identity labels—subscriptions and the core user record remain intact. To delete a user entirely, including all associated aliases and subscriptions, see the [Delete user](/reference/delete-user) API.

***

## How to use this API

To remove an alias from a user:

1. Identify the user via a known alias by specifying:

   * `alias_label` – the type of alias (e.g., email, external\_id)
   * `alias_id` – the unique identifier for that alias

2. Specify the alias to remove using:

   * `alias_label_to_delete` – the label of the alias to be deleted

   The `alias_label_to_delete` can be the same as the `alias_label` used to identify the user.

3. This action is performed synchronously—the alias is deleted immediately after the request is processed.

<Warning>
  The `onesignal_id` alias cannot be deleted. Only secondary aliases (like email, external\_id, etc.) are removable.
</Warning>

For a full explanation of identity management, see [Users](/docs/en/users) and [Aliases](/docs/en/aliases).

***

## FAQ

### Can I delete the same alias that I used to look up the user?

Yes. This is a common scenario—especially if an alias was set incorrectly and needs to be removed. Just be sure to include that alias both as the identifier and as alias\_label\_to\_delete.

If you want to delete the entire user and all associated data, use the [Delete user](/reference/delete-user) API.

### What happens if I delete all aliases associated with the user?

A user will always retain at least one alias, the onesignal\_id. Even if you remove all other aliases, the user and their subscriptions remain linked to the onesignal\_id.

***


# Delete API key
Source: https://documentation.onesignal.com/reference/delete-api-key

DELETE /apps/{app_id}/auth/tokens/{token_id}
Delete a specific Rich Authentication Token (App API Key) for a OneSignal app. Requires your Organization API Key and the token's unique ID, not the token value itself.

## Overview

Use this API to delete a specific App API Key (Rich Authentication Token) for a single OneSignal.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Delete segment
Source: https://documentation.onesignal.com/reference/delete-segments

DELETE /apps/{app_id}/segments/{segment_id}
Delete segments from OneSignal. Does not delete users or subscriptions.

## Overview

The Delete segment method is used when you want to programmatically delete a segment from within the OneSignal Dashboard UI.

<Warning>
  Once a segment is deleted, it cannot be recovered. You will need to create a new segment with the same filters.
</Warning>

***

## How to use this API

You can pass in the `segment_id` dictating which segment from our dashboard will be deleted.

The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard as shown below:

<Frame>
  <img />
</Frame>

***


# Delete Subscription
Source: https://documentation.onesignal.com/reference/delete-subscription

DELETE /apps/{app_id}/subscriptions/{subscription_id}
Delete a specific subscription by its subscription_id. This stops messages from being sent to that subscription but does not prevent future subscriptions with the same token.

## Overview

Use this API to delete an existing Subscription and its associated properties. Deletion is **asynchronous**, and while the Subscription is being removed, messages will no longer be sent to it.

<Warning>
  This operation only deletes a **single Subscription**. To remove a **user and all their Subscriptions**, use the [Delete User](/reference/delete-user) API instead.
</Warning>

### What Happens When You Delete

* Messages will stop being sent to the deleted subscription.
* **Deleting a Subscription does not block new Subscriptions** with the same `token`.
  * If the app is reopened or a token is re-submitted (e.g., same email or phone), a **new Subscription** may be automatically created.
  * This ensures users can re-subscribe if needed without requiring manual intervention.

***

## How to Use This API

**Required:** `subscription_id`

You must provide the `subscription_id` of the subscription to be deleted. This ID is a UUID generated by OneSignal and is immutable.

To find the `subscription_id`:

1. Use the [View User](/reference/view-user) API.
2. Look at the `subscriptions` array in the response.
3. Identify the correct subscription by its `type`, `token`, or other metadata.
4. Use the corresponding `id` field as the `subscription_id`.

***


# Delete template
Source: https://documentation.onesignal.com/reference/delete-template

DELETE /templates/{template_id}?app_id={app_id}
Permanently delete a specific message template from your OneSignal app using its template ID. Templates used in Journeys must be removed from those Journeys before deletion.

## Overview

This endpoint allows you to delete a single template associated with your OneSignal app. Deletion is **immediate and irreversible**.

<Warning>
  If the template is currently used in a Journey, it cannot be deleted until that Journey has been deleted.
</Warning>

***

## How to use this API

Required Parameters

* `template_id` (path param): The OneSignal-generated UUID of the template to delete.
* `app_id` (query param): Your OneSignal App ID.

### Where to Find `template_id`

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# Delete player record
Source: https://documentation.onesignal.com/reference/delete-user-record

delete https://onesignal.com/api/v1/players/{player_id}?app_id={app_id}

Delete a player (aka Subscription).

<Warning>
  This is a Legacy API. Use [Delete User](/reference/delete-user) or [Delete Subscription](/reference/delete-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `app_id`    | string | Yes      | Your OneSignal App ID.         |
| `player_id` | string | Yes      | The Subscription ID to delete. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Example Request

```http theme={null}
DELETE /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json
```

***

## Example Response

```json theme={null}
{
  "success": true
}
```

The Subscription will be deleted from the OneSignal database.

***


# Edit player
Source: https://documentation.onesignal.com/reference/edit-device

put https://onesignal.com/api/v1/players/{player_id}

Update a player's (Subscription's) information using the Subscription ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `player_id` | string | Yes      | The OneSignal Subscription ID. |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request.    |

***

## Request Body Parameters

| Field                | Type    | Required | Description                                                |
| -------------------- | ------- | -------- | ---------------------------------------------------------- |
| `app_id`             | string  | Yes      | Your OneSignal App ID.                                     |
| `identifier`         | string  | No       | Push token, email, or phone number.                        |
| `language`           | string  | No       | Language code (e.g., "en").                                |
| `timezone`           | integer | No       | Time zone offset in seconds.                               |
| `game_version`       | string  | No       | App version.                                               |
| `device_model`       | string  | No       | Device model (e.g., "iPhone12,1").                         |
| `device_os`          | string  | No       | OS version (e.g., "14.5").                                 |
| `ad_id`              | string  | No       | Advertising ID.                                            |
| `sdk`                | string  | No       | OneSignal SDK version.                                     |
| `tags`               | object  | No       | Custom key-value pairs.                                    |
| `external_user_id`   | string  | No       | Your internal user ID.                                     |
| `notification_types` | integer | No       | 1 = subscribed, -2 = unsubscribed, 0 = no permission, etc. |
| `email_auth_hash`    | string  | No       | Required to update email identifiers securely.             |
| `sms_auth_hash`      | string  | No       | Required to update SMS identifiers securely.               |

> Only include fields you want to change. Fields left out will not be modified.

***

## Example Request

```json theme={null}
PUT /api/v1/players/player_id_string HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_REST_API_KEY
Content-Type: application/json

{
  "app_id": "your_app_id",
  "external_user_id": "user123",
  "tags": {
    "level": "20",
    "subscription": "active"
  },
  "language": "fr",
  "timezone": 3600,
  "device_os": "16.0"
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Missing or invalid fields.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied.
* 404 Not Found – Device with player\_id not found.

***


# Edit tags with external user id
Source: https://documentation.onesignal.com/reference/edit-tags-with-external-user-id

put https://onesignal.com/api/v1/apps/{app_id}/users/{external_user_id}

Update a player's (Subscription's) information using the External ID.

<Warning>
  This is a Legacy API. Use [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) instead.
</Warning>

***

## Path Parameters

| Parameter          | Type   | Required | Description             |
| ------------------ | ------ | -------- | ----------------------- |
| `app_id`           | string | Yes      | Your OneSignal App ID.  |
| `external_user_id` | string | Yes      | The user's External ID. |

***

## Headers

| Header          | Value                            | Required | Description                      |
| --------------- | -------------------------------- | -------- | -------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your Legacy OneSignal API key.   |
| `Content-Type`  | `application/json`               | Yes      | The content type of the request. |

***

## Request Body Parameters

| Field  | Type   | Required | Description                       |
| ------ | ------ | -------- | --------------------------------- |
| `tags` | object | Yes      | Key-value pairs to set or update. |

* To **delete a tag**, set its value to an empty string (`""`).
* Existing tags with the same keys will be **overwritten**.

***

## Example Request

```http theme={null}
PATCH /api/v1/apps/your_app_id/users/user123 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
Content-Type: application/json

{
  "tags": {
    "plan": "premium",
    "logged_in": "true",
    "referral": ""
  }
}
```

***

## Response

```json theme={null}
{
  "success": true
}
```

***

## Errors

* 400 Bad Request – Invalid request or payload.
* 401 Unauthorized – Invalid or missing keys.
* 403 Forbidden – Access denied due to insufficient permissions.
* 404 Not Found – No players found for given `external_user_id`.

***


# Export audience activity CSV
Source: https://documentation.onesignal.com/reference/export-csv-of-events

POST /notifications/{message_id}/export_events
Export a compressed CSV report of audience-level delivery and engagement data for a specific message. This includes sent, delivered, clicked, failed, and unsubscribed events across Push, Email, and SMS channels.

## Overview

Get a CSV of per-recipient audience activity events (sends, clicks, failures, etc.) for a push, email, or SMS message. This endpoint mirrors the **Export** button in the dashboard's Audience Activity section on each message report:

* [Push message reports](/docs/en/push-notification-message-reports)
* [Email message reports](/docs/en/email-message-reports)
* [SMS message reports](/docs/en/sms-message-reports)

The CSV schema varies by channel. See each channel's message reports page for column definitions.

***

## How to use this API

Get the message `id` from the [Sending messages API](/reference/create-message) or the [View messages API](/reference/view-messages).

A successful request returns `200 OK` with a `csv_file_url`:

```json 200 OK theme={null}
{
    "csv_file_url": "https://onesignal-data.onesignal.com/csv_exports/YOUR_APP_ID/events_audience-activity-YOUR_MESSAGE_ID-push-YYYY-MM-DDTHH-MM-SSTZ.csv.gz"
}
```

The generated file name follows the pattern `events_audience-activity-{message_id}-{channel}-{timestamp}.csv.gz`.

The file is generated at \~2,000 records per second. For large audiences, generation can take several minutes, and the URL may return `404` until the file is ready:

```xml 404 Not Found theme={null}
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>
```

Poll the `csv_file_url` with GET and implement retries with exponential backoff. When the file is ready, the GET request downloads the `.csv.gz` file.

<Info>
  * The CSV download URL is valid for **3 days** after creation.
  * File names include a random UUID to prevent guessing.
</Info>

<Warning>
  Only **one concurrent export** is allowed per OneSignal account. Download the `.csv.gz` file before starting another export, or the new request fails.
</Warning>

***


# Rotate API key
Source: https://documentation.onesignal.com/reference/rotate-api-key

POST /apps/{app_id}/auth/tokens/{token_id}/rotate
Rotate an existing App API Key (Rich Authentication Token) for a OneSignal app. Useful when a token is compromised or needs replacement without creating a new key from scratch.

## Overview

Use this API to rotate a **Rich Authentication Token** (App API Key) for a specific OneSignal app. Rotating a key revokes the current token and generates a new one under the same configuration—ideal when a token is lost or compromised but you don’t want to recreate and reconfigure it from scratch.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can rotate an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Transfer Subscription
Source: https://documentation.onesignal.com/reference/transfer-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}/owner
Transfer a Subscription to a different user within the same OneSignal app. Useful for associating existing Subscriptions like push, email, or SMS with a new or updated user identity.

## Overview

Use this API to transfer a Subscription from one user to another within the same OneSignal app.

It is highly recommended to use our web and mobile SDKs to set and update the External ID with the `login` method instead of this API. Your app or website may continue to be setting the wrong External ID. Make sure to only use this API if you are setting the same External ID within your app or website.

This is typically used when:

* You want to reassign an existing push, email, or SMS Subscription to a new or updated user.
* You have changed how you're identifying users (e.g., migrating from anonymous to known users).

<Note>
  - Subscriptions **cannot be transferred across different OneSignal apps**.
  - For email and SMS Subscriptions, you can instead create new ones using [Create User](/reference/create-user).
  - For push Subscriptions, platform limitations may apply—see [Subscriptions](/docs/en/subscriptions#importing-push-subscriptions) for details.
</Note>

***

## How to Use This API

### Required Path Parameter: `subscription_id`

You must know the `subscription_id` of the subscription to be transferred. This is a unique UUID assigned by OneSignal.

### Required Body Parameter: `identity` (object)

This specifies the user the subscription should be moved to. Only **one alias** should be used per request. You can identify the target user using one of:

* `external_id` (recommended)
* `onesignal_id`
* A [custom alias](/docs/en/aliases)

***


# Unsubscribe email with token
Source: https://documentation.onesignal.com/reference/unsubscribe-with-token

POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
Unsubscribe an email address from future messages by calling this API from your custom unsubscribe page. Automatically disables the associated email subscription using a token-based approach.

## Overview

Use this API to unsubscribe an email address directly from your custom unsubscribe landing page. It is ideal when building branded opt-out experiences and enables you to track which email caused the unsubscribe.

When invoked, this endpoint:

* Sets the email Subscription's `enabled` property to `false`
* Prevents further messages from being sent to the email address unless explicitly overridden (see [Overriding unsubscribes](/reference/email#body-include-unsubscribed))
* Email Subscriptions can be re-subscribed using the [Update Subscription](/reference/update-subscription) API

<Tip>
  For instructions on setting up a custom unsubscribe page, see [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page).
</Tip>

***

## How to Use This API

### Step 1: Set Up Your Custom Unsubscribe Page

Follow the guide to [Create a Custom Unsubscribe Page](/docs/en/create-custom-unsubscribe-page). You'll add a custom unsubscribe URL to your email templates using Liquid syntax.

Example URL in your email template:

```liquid theme={null}
https://yourdomain.com/unsubscribe?app_id={{ app_id }}&notification_id={{ notification_id }}&token={{ token }}
```

### Step 2: Extract the Parameters

When a user clicks the unsubscribe link, your custom unsubscribe page should extract the following from the URL:

* `app_id`: OneSignal app ID
* `notification_id`: The ID of the specific email message sent
* `token`: The email token, a secure reference to the subscription

### Step 3: Call the API

When the user confirms they want to unsubscribe (e.g., clicks a button on your unsubscribe page), make a POST request to this endpoint:

```
POST /apps/{app_id}/notifications/{notification_id}/unsubscribe?token={token}
```

Example Request (JavaScript):

```js theme={null}
fetch("https://api.onesignal.com/apps/your-app-id/notifications/your-notification-id/unsubscribe?token=abc123xyz", {
  method: "POST"
});
```

<Info>
  No request body or authentication is required. The token acts as a secure identifier.
</Info>

<Note>
  * This API only works for email subscriptions.
  * It should only be used from a server or frontend context that you control (e.g., your custom unsubscribe page).
  * Once unsubscribed, the email address will not receive future emails from your app unless resubscribed.
</Note>

***


# Update an app
Source: https://documentation.onesignal.com/reference/update-an-app

PUT /apps/{app_id}
Use to update the name or push platform configuration of an existing app. This guide explains required parameters and platform-specific update rules

## Overview

Use this API to programmatically update an existing OneSignal app. This is useful when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.

You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).

<Note>
  For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

The Organization API key must be assocated with the `organization_id` in the request body.

***

### Web push configuration

The following parameters are **required** for web push setup:

* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.

URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).

<Note>
  `safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.

  If you use your own p12 certificate, you must update it every year.
  If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

**Recommended parameters**:

* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.

***

### Android mobile push configuration

The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).

* `fcm_v1_service_account_json`

<Warning>
  If you change your FCM Service Account JSON file to a different Firebase project, your Android Subscriptions tied to the current project will become invalid. They will not be able to receive push notifications until they open your app again with this new FCM Service Account JSON file.
</Warning>

<Note>
  If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

***

### iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

<Note>
  If you need help Base64 encoding your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
</Note>

The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns). **You will likely never need to update these parameters if set correctly during app creation**:

* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`

The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates). **These must be updated every year which is why we recommend using p8 authentication**:

* `apns_p12`
* `apns_p12_password`

**Optional parameters** :

* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).

***


# Update API key
Source: https://documentation.onesignal.com/reference/update-api-key

PATCH /apps/{app_id}/auth/tokens/{token_id}
Update a Rich Authentication Token (App API Key) for a OneSignal app. Modify the token's name or IP allowlist settings using your Organization API Key.

## Overview

Use this API to update the properties of a specific **Rich Authentication Token** (App API Key) for a OneSignal app. You can change the name, IP allowlist mode, or the list of allowed IPs. This is helpful for adjusting access rules without needing to recreate the key.

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Using your Organization API key (available in [Organizations > Keys & IDs](/docs/en/keys-and-ids#organization-api-key)) you can delete an app token associated with a given app.

The `token_id` is a OneSignal-generated ID specific for the API key. This is not the API key itself. It is returned when creating an API key with [Create API key](/reference/create-api-key). It can be found in the OneSignal dashboard and in the response body of the [View API keys](/reference/view-api-keys) request.

***


# Update segment
Source: https://documentation.onesignal.com/reference/update-segment

PATCH /apps/{app_id}/segments/{segment_id}
Update an existing segment's name and/or filters. The name parameter is always required. When filters are provided, all existing filters are replaced with the new ones.

## Overview

Update an existing segment's name and/or filters. This API allows you to modify [Segments](/docs/en/segmentation) programmatically without having to delete and recreate them.

<Note>
  The `name` parameter is always required, even if you're not changing it. When filters are provided, all existing filters are **replaced** with the new ones. Omit the `filters` parameter to keep existing filters intact. The `filters` array cannot be empty—if provided, it must contain at least one filter.
</Note>

***

## How to use this API

### Update segment name only

To update just the segment name without changing filters:

```json theme={null}
{
  "name": "New Segment Name"
}
```

### Update segment description

Update the optional `description` (max 255 characters). Pass an empty string to clear the existing description; omit the field to leave it unchanged.

```json theme={null}
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION"
}
```

### Update segment filters

To update the segment filters (this replaces all existing filters), provide the `name` (required) and `filters`:

```json theme={null}
{
  "name": "Updated Segment",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "5"},
    {"operator": "AND"},
    {"field": "tag", "key": "subscription", "relation": "=", "value": "premium"}
  ]
}
```

### Filter syntax

The filter syntax is identical to the [Create segment](/reference/create-segments) API. Available filters include:

* `tag` - Filter by Tags
* `last_session` - Filter by last active time
* `first_session` - Filter by first session time
* `session_count` - Filter by number of sessions
* `session_time` - Filter by total usage duration
* `language` - Filter by user language
* `app_version` - Filter by app version
* `location` - Filter by GPS coordinates
* `country` - Filter by country

Use `AND` and `OR` operators to combine filters:

```json theme={null}
{
  "name": "Engaged Premium Users",
  "filters": [
    {"field": "tag", "key": "plan", "relation": "=", "value": "premium"},
    {"operator": "AND"},
    {"field": "session_count", "relation": ">", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "vip", "relation": "=", "value": "true"}
  ]
}
```

***

## Response

### Success response

```json theme={null}
{
  "success": true,
  "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19"
}
```

### Error responses

| Status Code | Description                                                                              |
| ----------- | ---------------------------------------------------------------------------------------- |
| 400         | Bad request - Invalid filters, duplicate segment name, or segment used by active Journey |
| 403         | Forbidden - API not available for your plan                                              |
| 404         | Not found - Segment does not exist                                                       |
| 429         | Rate limit exceeded                                                                      |

***


# Update Subscription by ID
Source: https://documentation.onesignal.com/reference/update-subscription

PATCH /apps/{app_id}/subscriptions/{subscription_id}
Update properties on an existing OneSignal subscription using its subscription_id. Commonly used to enable or disable a subscription when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties by `subscription_id`.

This endpoint is primarily used by the OneSignal SDK to manage subscription state.

Most external use cases are better served by the [Update Subscription by token](/reference/update-subscription-by-token) API, which can use the Email Address or Phone Number as the `token` or the [Update User](/reference/update-user) API, which allows for updating user-level data.

<Note>
  For **email opt-outs**, it's recommended to use the [Unsubscribe Email (with token)](/reference/unsubscribe-with-token) API instead. This avoids the need to store or manage the `subscription_id`.
</Note>

***

## How to use this API

**Required:** `subscription_id`

To update a subscription, you **must know the `subscription_id`**. This is a UUID generated by OneSignal and is immutable.

* You can retrieve a subscription ID by querying the [User object](/docs/en/users).
* See the [Subscriptions](/docs/en/subscriptions) guide for an explanation of how subscription IDs are generated and used.

<Note>
  You **cannot** update the `type` of a Subscription. If the `type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the Subscription with the correct type.
</Note>

***


# Update Subscription by token
Source: https://documentation.onesignal.com/reference/update-subscription-by-token

PATCH /apps/{app_id}/subscriptions_by_token/{token_type}/{token}
Update properties on an existing Subscription using its token. Commonly used to enable or disable subscription status when managing outside of the OneSignal SDK.

## Overview

Use this API to update an existing Subscription's properties.

This API can be useful if:

* You only know the `token` and `token_type` and want to update metadata or status flags directly.
* You are managing Subscription status outside of the OneSignal SDK. Like with a [custom preference page or unsubscribe page](/docs/en/create-custom-unsubscribe-page).

***

## How to use this API

To update a Subscription, you must know the `token_type` and the `token`.

The `token_type` is the [Subscription's type](/docs/en/server-sdk-reference#subscription-types) (e.g., `Email`, `SMS`, `iOSPush`, `AndroidPush`, etc.).

The `token` is the push token, email address, or phone number associated with the Subscription.

Ensure the `token` is valid and correctly formatted for the chosen `token_type`.

* **Email format:** Should be a valid email address that you confirmed can receive emails.
* **SMS format:** Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164).
* **iOSPush APNS token format:** 64 characters, hexadecimal characters only (0-9,a-f).
* **AndroidPush FCM token format:** Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.

<Warning>
  You **cannot** update the `token_type` and `token` of a Subscription with this API. If the `token_type` is incorrect:

  1. Use [Delete Subscription](/reference/delete-subscription) to remove the incorrect entry.
  2. Use [Create Subscription by alias](/reference/create-subscription) to recreate the subscription with the correct type.

  If multiple Subscriptions are found for the `token` and `token_type`, an `Http 400` error is returned with a list of subscription IDs that match the criteria.
</Warning>

***


# Update template
Source: https://documentation.onesignal.com/reference/update-template

PATCH /templates/{template_id}?app_id={app_id}
Update existing OneSignal message templates for push, email, or SMS. Changes apply immediately across dashboard and API usage via the `template_id` reference.

## Overview

This endpoint allows you to update an existing push, email, or SMS template in your OneSignal app. Once updated, the changes are applied immediately and reflected across both the Dashboard and API when using the associated `template_id`.

Templates are updated using the same structure as when [creating templates](/reference/create-template).

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

To update a template, you must supply:

* Your **OneSignal App ID** found in [Keys & IDs](/docs/en/keys-and-ids).
* The **Template ID**

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***

## Channel-Specific Requirements

### Push Templates

* The `contents` property must use the `en` (English) key along with other languages you want to support.
* All [Push Notification Properties](/reference/push-notification) are valid.
* All platforms are enabled by default. To limit, explicitly enable desired ones (e.g., `isAndroid: true` disables iOS and Web).

### Email Templates

* Set `isEmail: true`
* Include `email_subject` and `email_body`
* All [Email Channel Properties](/reference/email) are supported.

### SMS Templates

* Set `isSMS: true`
* All [SMS Channel Properties](/reference/sms) are supported.

***


# View an app
Source: https://documentation.onesignal.com/reference/view-an-app

GET /apps/{app_id}
View the details of a single OneSignal app

## Overview

Use this API to retrieve metadata and platform configuration for a single OneSignal app associated with your account. This includes app names, App ID, Subscription counts, timestamps, and push platform credentials (Android/FCM, iOS/APNS, Web Push, Safari), making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

***

## How to use this API

To retrieve your app, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View API keys
Source: https://documentation.onesignal.com/reference/view-api-keys

GET /apps/{app_id}/auth/tokens
View the details of all of your current app API keys (Rich Authentication Token) for a single OneSignal app.

## Overview

This API is helpful for auditing and managing the API keys (Rich Authentication Tokens) associated with an app. It returns metadata for each token, including:

* Token name and ID
* IP allow list mode and associated CIDR ranges (if any)
* Creation and last updated timestamps

<Note>
  For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids).
</Note>

***

## How to use this API

Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.

***


# View apps
Source: https://documentation.onesignal.com/reference/view-apps

GET /apps
Retrieve a list of all OneSignal apps associated with your account, including key app details like name, App ID, subscription counts, and timestamps. Useful for managing multiple apps through the OneSignal API.

## Overview

Use this API to retrieve metadata for all OneSignal apps associated with your account. This includes app names, App IDs, subscription counts, and timestamps, making it easy to programmatically manage or audit your applications.

<Note>
  This API does not return the app's API keys. To manage API keys, use the [Create API Key](/reference/create-api-key), [Rotate API Key](/reference/rotate-api-key), and [Delete API Key](/reference/delete-api-key) APIs.
</Note>

<Warning>
  This API is limited to return a maximum of 1000 Apps. If you need access to more, then you should store the `app_id` and `name` for each of your apps on your own server to look up with the [View an app](/reference/view-an-app) API to get data for each app separately. Also, if you need to delete apps, then you can provide the `app_id` and `name` to OneSignal Support and ask for these to be deleted.
</Warning>

***

## How to use this API

To retrieve your apps, send a `GET` request to the `/apps` endpoint using your **Organization API Key**. This key can be found in your OneSignal dashboard under [Organization > Keys & IDs](/docs/en/keys-and-ids#organization-api-key).

***


# View player
Source: https://documentation.onesignal.com/reference/view-device

GET https://onesignal.com/api/v1/players/{player_id}

Retrieve a single player record (Subscription) data registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Path Parameters

| Parameter   | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `player_id` | string | Yes      | The OneSignal ID of the device. |

***

## Query Parameters

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `app_id`  | string | Yes      | Your OneSignal App ID. |

***

## Headers

| Header          | Value                            | Required | Description                        |
| --------------- | -------------------------------- | -------- | ---------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal LegacyREST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players/player_id_string?app_id=your_app_id HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json{ theme={null}
  "id": "player_id_string",
  "identifier": "push_token_or_email",
  "session_count": 5,
  "language": "en",
  "timezone": -28800,
  "game_version": "1.0",
  "device_os": "14.4",
  "device_type": 1,
  "tags": {
    "level": "10",
    "user_type": "free"
  },
  "last_active": 1625253300,
  "created_at": 1625249800,
  "invalid_identifier": false,
  "external_user_id": "user123"
}
```

### Response Fields

| Field                | Type      | Description                                             |
| -------------------- | --------- | ------------------------------------------------------- |
| `id`                 | string    | OneSignal player ID.                                    |
| `identifier`         | string    | Push token, email, or phone number.                     |
| `session_count`      | integer   | Number of sessions associated with this device.         |
| `language`           | string    | Language set on the device (e.g., "en").                |
| `timezone`           | integer   | Time zone offset in seconds.                            |
| `game_version`       | string    | Version of your app the device is running.              |
| `device_os`          | string    | Operating system version.                               |
| `device_type`        | integer   | Numeric code for platform (0 = iOS, 1 = Android, etc.). |
| `tags`               | object    | Custom tags set on the device.                          |
| `last_active`        | timestamp | Last time the user was active (Unix timestamp).         |
| `created_at`         | timestamp | When the device record was created.                     |
| `invalid_identifier` | boolean   | Whether the push token or identifier is invalid.        |
| `external_user_id`   | string    | Your internal user ID mapped to this device.            |

***

## Errors

* 400 Bad Request – Missing or invalid parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access denied for this app or resource.
* 404 Not Found – The specified player\_id does not exist.

***


# View players
Source: https://documentation.onesignal.com/reference/view-devices

GET `https://onesignal.com/api/v1/players?app_id={app_id}&limit={limit}&offset={offset}`

Retrieve up to 80,000 player records (Subscriptions) registered to a specific OneSignal app.

<Warning>
  This is a Legacy API. Use [View User](/reference/view-user) or [CSV Export API](/reference/csv-export) instead.
</Warning>

***

## Query Parameters

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `app_id`  | string | Yes      | Your OneSignal App ID.                                 |
| `limit`   | int    | No       | Number of entries to return (max 300, default is 300). |
| `offset`  | int    | No       | Result offset for pagination.                          |

***

## Headers

| Header          | Value                            | Required | Description                         |
| --------------- | -------------------------------- | -------- | ----------------------------------- |
| `Authorization` | `Basic YOUR_LEGACY_REST_API_KEY` | Yes      | Your OneSignal Legacy REST API Key. |

***

## Example Request

```http theme={null}
GET /api/v1/players?app_id=your_app_id&limit=100&offset=0 HTTP/1.1
Host: onesignal.com
Authorization: Basic YOUR_LEGACY_REST_API_KEY
```

***

## Example Response

```json theme={null}
{
  "total_count": 6,
  "offset": 0,
  "limit": 300,
  "players": [
    {
      "id": "player_id_1",
      "identifier": "push_token_or_email",
      "session_count": 3,
      "language": "en",
      "timezone": -28800,
      "game_version": "1.0",
      "device_os": "15.0",
      "device_type": 1,
      "tags": {
        "level": "15",
        "user_type": "free"
      },
      "last_active": 1625253300,
      "created_at": 1625249800,
      "invalid_identifier": false,
      "external_user_id": "user123"
    }
  ]
}
```

### Response Fields

| Field                        | Type    | Description                                  |
| ---------------------------- | ------- | -------------------------------------------- |
| `total_count`                | integer | Total number of devices for the app.         |
| `offset`                     | integer | Current pagination offset.                   |
| `limit`                      | integer | Number of devices returned in this response. |
| `players`                    | array   | List of device objects.                      |
| `players[].id`               | string  | Unique OneSignal player ID.                  |
| `players[].identifier`       | string  | Push token, email, or phone number.          |
| `players[].tags`             | object  | Custom tags set on the device.               |
| `players[].external_user_id` | string  | Your internal user ID.                       |

***

## Errors

* 400 Bad Request – Invalid query parameters.
* 401 Unauthorized – Invalid or missing API key.
* 403 Forbidden – Access not allowed for this app or key.

***


# View outcomes
Source: https://documentation.onesignal.com/reference/view-outcomes

GET /apps/{app_id}/outcomes?outcome_names={outcome_names}&outcome_time_range={outcome_time_range}&outcome_platforms={outcome_platforms}&outcome_attribution={outcome_attribution}
View and export push notification outcome metrics such as clicks, conversions, and custom events.

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

## Overview

Use this API to retrieve Outcome metrics associated with your OneSignal app, including push notification interactions and custom-defined events. Outcomes include data points like:

* **Clicks**: Number of users who clicked on a push.
* **Confirmed Deliveries**: Number of confirmed message deliveries.
* **Session Durations**: Number of sessions initiated.
* **Custom Events**: Actions like purchases, form submissions, or any event your app tracks via custom Outcome names.

For details on configuring custom Outcomes, refer to the [Outcomes documentation](/docs/en/custom-outcomes).

<Info>
  Outcomes are stored for approximately 30 days. To retain this data, you should regularly export it before it expires.
</Info>

***

## How to use this API

This API allows you to filter and aggregate Outcome data using several query parameters.

### `outcome_names`

Specify one or more Outcome names with an aggregation type suffix (`.count` or `.sum`).

**Default Outcome names:**

* `os__click.count` – Push notification clicks.
* `os__confirmed_delivery.count` – Confirmed deliveries.
* `os__session_duration.count` – Total sessions.

**Custom Outcome names:**

* You can track any custom event name (e.g. `Purchase`, `Signup`).
* If the custom name contains a comma, include only one name per request to avoid parsing issues.
* Example: `outcome_names=os__click.count,Purchase.count`

### `outcome_time_range`

The time range values can be one of the following:

* `1h` = (default) the last 1 hour data.
* `1d` = the last 1 day data.
* `1mo` = the last 1 month data.

### `outcome_platforms`

Maps to the subscription type property. Default is data from all platforms enabled for your OneSignal App.

| `device_type` | `type`      |
| ------------- | ----------- |
| 0             | iOSPush     |
| 1             | AndroidPush |
| 2             | FireOSPush  |
| 5             | ChromePush  |
| 8             | FirefoxPush |
| 11            | Email       |
| 14            | SMS         |
| 17            | SafariPush  |

Example: `outcome_platform=0` for iOS `outcome_platform=17,8` for Safari and Firefox.

### `outcome_attribution`

The way in which the Outcome occurred:

* `direct` = the Outcome occurred when the user interacted with the message. Some Outcomes only have `direct` attribution like `os__click` and `os__confirmed_delivery` because they only occur as the direct result of the message.
* `influenced` = the Outcome occurred within the Time Window of the message being sent, but the user never interacted with the message. See [Outcomes](/docs/en/custom-outcomes) for details.
* `unattributed` = the Outcome occurred without a direct or influenced attribute.
* `total` = (default) the sum of direct+influenced+unattributed.

***


# View segment
Source: https://documentation.onesignal.com/reference/view-segment

GET /apps/{app_id}/segments/{segment_id}
Retrieve details for a single segment by its ID, including subscriber count and optionally segment metadata and filters.

## Overview

Retrieve details for a single segment by its ID. By default, this endpoint returns only the subscriber count. Use the optional `include-segment-detail` parameter to also retrieve segment metadata and filters.

<Note>
  The `segment_id` can be found using the [View segments](/reference/view-segments) API or in the URL of the segment when viewing it in the dashboard.
</Note>

<Warning>
  **User-based segments not supported**: Segments containing message event or custom event filters (user-based segments) are not yet supported via this API. Attempting to fetch these segments will return a 400 error. These segments can only be managed through the dashboard UI.
</Warning>

***

## How to use this API

### Basic usage

By default, this endpoint returns only the subscriber count for the segment:

```json theme={null}
{
  "subscriber_count": 12345
}
```

### Include segment details

To retrieve full segment details including metadata and filters, set `include-segment-detail=true`:

```
GET /apps/{app_id}/segments/{segment_id}?include-segment-detail=true
```

This returns the subscriber count along with a `payload` object containing segment details:

<CodeGroup>
  ```json Simple filter theme={null}
  {
    "subscriber_count": 12345,
    "payload": {
      "id": "4414c404-56a3-11ed-9b6a-0242ac120002",
      "name": "Subscribed Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {
          "field": "session_count",
          "relation": ">",
          "value": "5"
        }
      ]
    }
  }
  ```

  ```json With AND/OR operators theme={null}
  {
    "subscriber_count": 5678,
    "payload": {
      "id": "5525d515-67b4-22fe-0c7b-1353bd231113",
      "name": "Engaged Users",
      "description": "YOUR_SEGMENT_DESCRIPTION",
      "created_at": 1658584650,
      "source": "custom",
      "filters": [
        {"field": "session_count", "relation": ">", "value": "2"},
        {"operator": "AND"},
        {"field": "tag", "key": "level", "relation": "=", "value": "10"},
        {"operator": "OR"},
        {"field": "last_session", "relation": "<", "hours_ago": "24"}
      ]
    }
  }
  ```
</CodeGroup>

### Filters format

The `filters` array uses the **same format** as the [Create segment](/reference/create-segments) API. This means you can:

* Read filters from this endpoint
* Modify them as needed
* Use them directly with the [Update segment](/reference/update-segment) or [Create segment](/reference/create-segments) APIs

The array contains filter objects and operator objects:

**Filter object** - defines a condition:

| Field                   | Type    | Description                                                                                                                                         |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field`                 | string  | The filter type: `tag`, `last_session`, `first_session`, `session_count`, `session_time`, `language`, `app_version`, `location`, `country`, `email` |
| `relation`              | string  | The comparison operator: `>`, `<`, `=`, `!=`, `exists`, `not_exists`, `in_array`, `not_in_array`, `time_elapsed_gt`, `time_elapsed_lt`              |
| `value`                 | string  | The filter value (for most filter types)                                                                                                            |
| `key`                   | string  | The filter key (required for `tag` filters)                                                                                                         |
| `hours_ago`             | string  | Hours ago value (for `last_session`/`first_session` filters)                                                                                        |
| `radius`, `lat`, `long` | string  | Location parameters (for `location` filters)                                                                                                        |
| `unsupported_in_api`    | boolean | If `true`, this filter cannot be used with Create/Update segment APIs (see note below)                                                              |

**Operator object** - combines filters:

| Field      | Type   | Description                                                                        |
| ---------- | ------ | ---------------------------------------------------------------------------------- |
| `operator` | string | Either `AND` or `OR`. Filters connected with `AND` have higher priority than `OR`. |

<Warning>
  Some segments created via the dashboard UI may contain filter types not supported by the public API (e.g., `message_event`, `custom_event`). These filters will include `unsupported_in_api: true`. You cannot use these filters when creating or updating segments via the API.
</Warning>

### Payload fields

| Field         | Type           | Description                                                                         |
| ------------- | -------------- | ----------------------------------------------------------------------------------- |
| `id`          | string         | The unique identifier for the segment (UUID v4).                                    |
| `name`        | string         | The segment name (max 128 characters).                                              |
| `description` | string \| null | Human-readable description for the segment (max 255 characters). `null` when unset. |
| `created_at`  | integer        | Unix timestamp when the segment was created.                                        |
| `source`      | string         | The source of the segment: `default`, `custom`, or `quickstart`.                    |
| `filters`     | array          | Array of filter and operator objects that define the segment criteria.              |

***


# View segments
Source: https://documentation.onesignal.com/reference/view-segments

GET /apps/{app_id}/segments
Retrieve a list of segments associated with a specific OneSignal app. Useful for programmatically accessing segment metadata such as name, creation date, and status.

## Overview

Retrieve a list of segments associated with a specific OneSignal app. This is helpful when you want to access segment metadata programmatically instead of using the OneSignal Dashboard UI.

<Warning>
  This endpoint only retrieves existing segment metadata. It does not provide the segment filters or user data.
</Warning>

***


# View template
Source: https://documentation.onesignal.com/reference/view-template

GET /templates/{template_id}?app_id={app_id}
Retrieve the details of a specific message template in your OneSignal app using its template ID. This API returns the template content, target channel, and timestamps for creation and last update.

## Overview

This endpoint returns metadata and content for a single template, including:

* Template body/content
* Target delivery channel (e.g., push, email, SMS)
* Creation and last updated timestamps

This is useful for inspecting existing templates before using or updating them.

<Note>See [Templates](/docs/en/templates) for more information.</Note>

***

## How to use this API

Required parameters:

* `app_id` (query param): Your OneSignal App ID.
* `template_id` (path param): The unique ID of the template.

### Template ID

Each template has a unique OneSignal-generated `template_id` (UUID v4). You can find it:

* Using the [View Templates API](/reference/view-templates)
* In the OneSignal Dashboard under **Messages > Templates > Options > Copy Template ID**

<Frame>
  <img alt="Copy Template ID in OneSignal Dashboard" />
</Frame>

***


# View templates
Source: https://documentation.onesignal.com/reference/view-templates

GET /templates?app_id={app_id}&limit={limit}&offset={offset}
Retrieve a paginated list of message templates from your OneSignal app. This endpoint returns summary information for each template, including ID, name, creation, and update timestamps.

## Overview

Use this endpoint to retrieve a list of message templates associated with a specific OneSignal app. The response provides summary information only:

* `template_id`
* `name`
* `created_at`
* `updated_at`

<Note>
  This endpoint does **not** return full template content such as message bodies, channel properties, or delivery configuration. For detailed template data, use the [View Template](/reference/view-template) endpoint.
</Note>

***

## How to Use This API

### Required Parameters

* **`app_id`** (query param): The OneSignal App ID whose templates you want to retrieve.

### Optional Parameters

* **`limit`** (query param): Number of templates to return (default: `50`, maximum: `50`).
* **`offset`** (query param): Number of templates to skip. Use for pagination.

### Pagination Example

If your app has 125 templates and you're using the default limit of 50:

1. First request (first 50 templates):\
   `GET /templates?app_id={app_id}&offset=0`

2. Second request (next 50 templates):\
   `GET /templates?app_id={app_id}&offset=50`

3. Third request (final 25 templates):\
   `GET /templates?app_id={app_id}&offset=100`

Repeat the request while adjusting the `offset` until you've retrieved all templates.

***


# Changelog
Source: https://documentation.onesignal.com/release-notes/changelog

Learn about the latest updates to OneSignal.

Follow along with updates across OneSignal. We're launching new features and improving our product all the time!

<Update label="June 18 2026">
  **AI-assisted SDK installation updated and expanded**

  * AI install prompts have been rewritten and expanded to cover Android, iOS, React Native, Flutter, and Web SDKs.
  * Paste a single ready-made prompt into your AI coding assistant (Cursor, Claude, Copilot, or similar) and the assistant installs the SDK, drops in initialization code, and configures push and in-app messaging automatically.
  * No deep development experience required — marketers and non-technical users can complete SDK setup in minutes.
  * Prompt instructions were revised to fix errors identified during internal testing, so generated integrations are more accurate.
  * Available to all new sign-ups with no enablement required; requires an AI coding tool and access to the app codebase.
</Update>

<Update label="June 15 2026">
  **Extended `in_array` and `not_in_array` relations to the Device Type filter**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `device_type` filter field. Use them to match against a comma-separated list of device types in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "device_type", "relation": "in_array", "value": "iOS,Android"},
    {"operator": "AND"},
    {"field": "device_type", "relation": "not_in_array", "value": "Email"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="June 15 2026">
  **RCS editor experience improvements**

  We've improved how you build and send RCS, giving you a more intuitive editor, clearer approval visibility, and a more graceful SMS fallback experience:

  * **See carrier approval status in settings.** Each sender resource's carrier approval status is now visible at **Settings > SMS > Senders**, so you can track where each carrier stands in the approval process without leaving the dashboard.
  * **Select a sender per RCS template.** In Templates you now choose a specific sender instead of relying on a single global default, improving how RCS sends within Journeys and giving you automations for multiple SMS use cases.
  * **A more intuitive editor.** The composer automatically shows the right editor for the selected sender — the RCS editor for senders with an RCS resource, and the SMS editor for SMS-only senders.
  * **Text only RCS.** A new Text only content type sends plain branded RCS text.

  When a sender gains an approved RCS sending resource, OneSignal automatically prefers RCS for existing automations on that sender, mapping your existing SMS content to RCS so there's no manual rework.

  Available for all customers contracted for RCS. See [RCS messaging](/docs/en/rcs-messaging) for details.
</Update>

<Update label="June 8 2026">
  **Segment editor improvements: multi-value filters, copy filters, and filter JSON**

  Building segments in the dashboard is now faster and more flexible:

  * **Match multiple values in one filter.** The Language, Country, App Version, and User Tag filters now support the "is any of" and "is not any of" relations, so you can match a list of values in a single filter instead of chaining several filters with OR.
  * **Copy filters and filter groups.** Duplicate an individual filter or an entire filter group from the editor to reuse its configuration without rebuilding it by hand.
  * **View and copy filter JSON.** Open the filter JSON panel to see the REST API representation of your segment's filters, then copy it to use directly in the [Create segment](/reference/create-segments) API.
</Update>

<Update label="June 4 2026">
  **Retired Alexa and Windows Phone 8.0 as Device Type filter options**

  The `Alexa` and `Windows Phone 8.0` values are no longer available for the Device Type filter when you create or edit a segment, in both the dashboard and the Create segment API. Selecting either value in the dashboard is no longer possible, and the API rejects them with a validation error.

  Existing segments that already use these values continue to evaluate and deliver as before. To save changes to such a segment, replace the retired Device Type filter first.
</Update>

<Update label="June 2 2026">
  **Extended `in_array` and `not_in_array` relations to tag and app version filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `tag` and `app_version` filter fields, in addition to the `country` and `language` fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "tag", "key": "level", "relation": "in_array", "value": "10,20,30"},
    {"operator": "AND"},
    {"field": "app_version", "relation": "not_in_array", "value": "1.0.0,1.0.1"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="May 11 2026">
  **Email BCC is now generally available**

  You can now add BCC (blind carbon copy) recipients to email sends, including templates used in journeys and messages sent via the API. Use BCC to archive customer-facing email to a shared inbox or compliance system, forward sends to third-party services, or keep internal stakeholders copied on transactional sends.

  * Available on all plan types.
  * Maximum of 5 BCC addresses per send.
  * Each BCC recipient counts toward the total email volume for that send (for example, 1,000 primary recipients with 1 BCC address = 2,000 sends).
  * BCC metrics are excluded from analytics.

  See [BCC emails](/docs/en/email-bcc) for setup and usage details.
</Update>

<Update label="May 12 2026">
  **Added `in_array` and `not_in_array` relations for country and language filters**

  The Create message and Create segments APIs now support `in_array` and `not_in_array` relations on the `country` and `language` filter fields. Use them to match against a comma-separated list of values in a single filter entry, instead of chaining multiple `"="` filters with `"OR"` operators.

  ```json theme={null}
  "filters": [
    {"field": "country", "relation": "in_array", "value": "US,GB,CA"},
    {"operator": "AND"},
    {"field": "language", "relation": "not_in_array", "value": "es,fr"}
  ]
  ```

  See the [Create message](/reference/create-message) and [Create segment](/reference/create-segments) API references for the full filter list.
</Update>

<Update label="April 21 2026">
  **Manage custom aliases from the User Profile**

  You can now view, add, edit, and delete a user's custom aliases directly from the **Aliases** section on the User Profile **Overview** tab, without using the API.

  * Add an alias by entering a label (alias key) and value (alias ID), copy any alias value to the clipboard, edit a value, or remove an alias.
  * Each user supports up to 10 aliases, and alias labels and values can each contain up to 128 characters.
  * `external_id` and `onesignal_id` are reserved and can't be used as custom alias labels.
  * A user must have an External ID set before you can add custom aliases. External ID is still managed separately in the Profile section.

  See [Aliases](/docs/en/aliases) for more details.
</Update>

<Update label="April 17 2026">
  **Role-based access control (RBAC) is now generally available**

  Granular role-based access control has been rolled out to all customers, giving teams more flexibility to support least-privilege access patterns and manage permissions as they scale.

  * **New `team_member` org-level default role.** A baseline role for new users added to an organization.
  * **New `composer` app-level role.** Lets users create and edit messages, templates, segments, and journeys without sending, activating, or deleting content.
  * **Updates to `editor` and `viewer` roles.** Refined permissions for clearer separation of duties.
  * Available roles vary by plan type.

  See [Manage team members](/docs/en/manage-team-members) for the full breakdown of roles, permissions, and plan availability.
</Update>

<Update label="April 16 2026">
  **Light/dark mode toggle for HTML in-app message previews**

  You can now switch between light and dark mode directly in the dashboard when previewing HTML in-app messages, so what you see matches what your users will actually see.

  * A light/dark mode toggle is now available in the in-app message preview for HTML messages.
  * The preview no longer reflects your OS theme. It reflects the mode you select in the dashboard.
  * Previously, the preview always rendered using whatever theme your own computer was set to, with no indication that was the cause, so there was no reliable way to check dark mode designs from the dashboard.

  HTML in-app messages do not automatically get a dark mode. The message still has to be coded for it using `@media (prefers-color-scheme: dark)` styles. If your message doesn't include those styles, toggling to dark mode in the preview won't change how it looks.

  The toggle is available for HTML in-app messages only. Block-type in-app messages are not included in this release. Generally available for all customers using HTML in-app messages.

  See [Design your in-app message with HTML](/docs/en/design-your-in-app-message-with-html) for how to add dark mode support.
</Update>

<Update label="April 15 2026">
  **Standardized delivery metrics across all channels**

  Delivery metric terminology is now consistent across every messaging channel in OneSignal. All channels now share a unified delivery hierarchy: Audience → Sent → Delivered, with the same definitions everywhere. Labels have been aligned across delivery reports, journey reports, engagement trends, and CSV exports. The [Metrics Glossary](/docs/en/analytics-metrics-glossary) has been fully rewritten as the canonical reference for every metric definition.
</Update>

<Update label="April 10 2026">
  **Audience counts now show subscribed and unsubscribed breakdowns**

  The segment editor now shows both subscribed and unsubscribed counts for every subscription-based segment, with a per-channel breakdown across push, email, and SMS. Previously, only the opted-in (subscribed) count was visible.

  Additional improvements:

  * Counts always return within approximately 15 seconds. Exact counts are shown when possible; estimates are used when an exact count can't be calculated in time.
  * Estimates are clearly labeled: above 10,000 with a +/- margin of error (e.g. 140,000 +/- 5,000), and below 10,000 as a less-than value (e.g. \<4,800).
  * Estimates will never show 0 for a segment. Previously for segments with very small but non-zero membership, estimates could incorrectly show as 0.

  This release covers subscription-based segments. User-based segment improvements are coming later in Q2 2026.
</Update>

<Update label="April 7 2026">
  **Updated User Profile page**

  The User Profile page has been redesigned with a tabbed layout and several new management actions directly on the page:

  * Add and remove Subscriptions from a User
  * Search across a User's data tags
  * Perform more direct edits and admin actions without leaving the profile

  The previous profile view is still accessible from the **Actions** menu if you need it.
</Update>

<Update label="March 25 2026">
  **test users now apply at the User level**
  Marking a Subscription as a test user now automatically marks all Subscriptions for that User as test users, effectively creating a Test User.

  * Any new Subscriptions added to a Test User will automatically be marked as test users.
  * Test User is now a User-level property rather than a Subscription-level one.

  **OneSignal Server SDKs just got their first v5 stable release!**

  After a period of testing and iteration, v5 is now the default version users will get when installing any of our server SDKs. Here are the current versions included in this release:

  | Language | Version |
  | -------- | ------- |
  | Node.js  | 5.4.0   |
  | Go       | 5.3.0   |
  | Java     | 5.3.0   |
  | .NET     | 5.4.0   |
  | Rust     | 5.3.0   |
  | Ruby     | 5.3.0   |
  | Python   | 5.3.0   |
  | PHP      | 5.3.0   |

  This release pairs well with our recently refreshed Server SDK Reference, giving developers a solid starting point for integrating with the OneSignal API.
</Update>

<Update label="March 20 2026">
  **Audit Log Export is now in GA**

  * Customers can now export audit logs. Customers can export 2 days for free tier and up to 90 days with security and legal entitlement (either as individual SKU or enterprise plan).
  * Provides customers additional metadata details and allows them to filter through data locally for their own audits and consumption with their own tools.

  **Failed Reasons in Audience Activity for everyone!**

  * Free plan users can now see exactly why individual audience members failed to receive a notification — directly in the Audience Activity view.
  * When a notification fails, especially common when troubleshooting set up, free users had no way to know whether the problem was a bad token, an unsubscribed user, or a device issue — leaving them guessing and unable to fix anything. Now they get the same failure visibility paid users have, so they can debug and get set up properly.
  * Same data retention as audience activity (30 days)
</Update>

<Update label="March 17 2026">
  **Data Model Updates and Field Deprecations**

  To improve platform performance, strengthen data integrity, and reduce the risk of configuration errors, we are introducing several updates to the OneSignal data model.

  These changes will take effect **April 15, 2026.**

  **Field Limits**

  We are introducing limits on two user fields to improve consistency and prevent unexpected behavior.

  Existing records exceeding these limits will not be modified to avoid disrupting current data and operations.

  **External ID**

  * `external_id` values can contain up to 128 characters.

  **Aliases**

  * Each user can have up to 10 aliases.
  * Each alias key and value can contain up to 128 characters.

  **Field Deprecations**

  We are deprecating several legacy Subscription fields that are no longer actively used:

  * `amount_spent`
  * `rooted`
  * `bought_sku`
  * `app_interests`
  * `purchased_items`

  After April 15, 2026, these fields will no longer be available in:

  * Segment Builder
  * API requests
  * Event streams
  * Webhooks

  **Impact for Customers Using These Fields**

  If your implementation currently references any of these fields:

  **Segments:** Segments using these fields will be paused and labeled for your review.

  **Journeys:** Journeys depending on those segments will be archived.

  **Event Streams and Webhooks:** These fields will return empty values.

  **What You Need to Do**

  Most customers do not need to take any action.

  If your implementation relies on any of the deprecated fields, we recommend reviewing your segments and integrations before **April 15, 2026.**
</Update>

<Update label="March 6 2026">
  Email Address Validation is now available!

  * When email addresses are added to OneSignal, they're now validated at three entry points:
    * API: syntax check
    * CSV import: full validation including typo detection, MX record lookup, disposable email flagging, and role-based address detection\*
    * Bulk validation: same full checks, runs against addresses already in your audience
  * Free plans have syntax and typo checks.
  * Paid plans will have syntax, typo, MX, disposable email, and role based email address checks.

  See [Email Address Validation](/docs/en/email-address-validation) for more details.
</Update>

<Update label="March 4 2026">
  **Dashboard layout redesign has shipped!**

  * Panel-based layout. The old floating card approach has been replaced with flat panels. The side nav sits in a clean gray panel, and the main content in a white panel. This simplifies the look and feel and gives us a more modern aesthetic.
  * New global top bar. Breadcrumbs, the new Create menu, Help/Support links, and Upgrade button all live in a new sticky top bar that follows you on scroll.

  **Richer date context across the dashboard**

  Dates show up everywhere in OneSignal — denoting message creation, notification send times, user sessions, etc. — but it wasn't always clear which timezone you were looking at, or how recent something actually was. This came up in a discussion last week among the dashboard engineers.

  Now, hovering over a date in the following areas of the Dashboard shows a tooltip with three pieces of context at once: the time in your local timezone, the time in UTC, and a relative timestamp (like "2 days ago").

  Where you'll see it:

  * Message lists and indexes
  * Message reports
  * Message review modals before sending
  * User and subscription profiles

  This is enabled for all apps — no action needed. Just hover a date and it's there!

  **In-App Message library with new quickstarts!**

  We've shipped a library of professionally designed, ready-to-use in-app message templates — available now to all plans in the dashboard.

  What's in it: 7 categories of quick starts covering the most common IAM use cases: push soft prompts, promotions, onboarding flows, feature announcements, location prompts, spin-to-win, and notification preference centers.

  How to access: Dashboard → Messages → In-App → New In-App → OneSignal Quick Starts. No feature flag or backend enablement required — available immediately. (See demo for the full experience in product)

  Go from zero to a production-ready in-app message in minutes, without writing HTML from scratch!
</Update>

<Update label="March 3 2026">
  **Enhanced Snowflake Integration Now Available!**

  Key improvements include:

  * 15-minute sync intervals (down from 24 hours)
  * Selective event syncing so customers only export what they need
  * Self-service setup directly in the OneSignal dashboard
  * New events like in-app impressions, email bounced/received, and separated Live Activity events.
  * We've also added richer properties including Template ID, last active timestamp, and subscription status.

  Customers get near real-time data in their Snowflake instance with full control over what gets synced meaning faster insights. Selective syncing alone can dramatically reduce event volume (and spend) by letting them export only the events that they need.

  This moves from the legacy flat annual fee to our Event Streams pricing model. Customers pre-purchase an event volume tier, and that tier covers all destinations (Snowflake, BigQuery, Databricks, etc.).

  Live now for all customers. All new customers will automatically have access to this new integration. Existing legacy Snowflake customers have until August 1st to migrate to the new integration before deprecation. Both integrations can run in parallel during the transition so they can ensure parity/consistency, and we will be doing outreach to those affected shortly.

  See [Snowflake](/docs/en/snowflake) for more details.
</Update>

<Update label="February 26 2026">
  **Audit Logs API is now available**

  Enterprise customers (with Legal & Security package) can now programmatically access the same audit log data surfaced in the OneSignal dashboard — pipe it directly into their SIEM, compliance tooling, or internal security workflows.

  * Returns a time-scoped record of actions taken in their org — who did what, when, and from where
  * Filter by app, action type, actor, target, or IP address
  * Supports cursor-based pagination for large result sets

  See [Audit Logs API](/reference/list-audit-logs) for more details.
</Update>

<Update label="February 9 2026">
  Huawei Badge Parameter Support

  We now support app icon badges on Huawei (HMS) devices via both the API and dashboard.

  * What's new: Three new parameters on `Notification#Create`
    * `huawei_badge_class` — the app's launcher activity class name (required for badge)
    * `huawei_badge_set_num` — set the badge to an exact number (0–99)
    * `huawei_badge_add_num` — increment the badge by a specific amount (1–99)

  On the dashboard, you'll see a new Badge option under Send to Huawei Android with "Don't set" / "Set to" / "Increase by" options.

  * Good to know:
    * Setting `huawei_badge_set_num` to 0 clears the badge
    * If neither set nor add is specified, the badge increments by 1 by default
    * Huawei does not auto-clear badges when the app opens
</Update>

<Update label="January 29 2026">
  API Documentation Improvements

  * New API endpoint: [View Segment](/reference/view-segment) - Retrieve details of a specific segment by ID, including optional segment filter details.
  * New API endpoint: [Update Segment](/reference/update-segment) - Update an existing segment's name and/or filters programmatically.
  * Fixed JSON example formatting across multiple API reference pages for improved readability:
    * Segments API: view-segments, create-segments, delete-segments
    * Users API: create-user, view-user, update-user, delete-user
    * Subscriptions API: create-subscription, delete-subscription, transfer-subscription, unsubscribe-with-token, create-alias-by-subscription
</Update>

<Update label="January 26 2026">
  **Audit Logs are now available!**

  * Customers now have the ability to determine exactly what's happening across their OneSignal account. Audit Logs gives them a complete timeline of every action taken in their organization—who did what, when, and from where.
  * Track 50+ action types including:
    * Authentication events (login, logout, API key operations)
    * Message activity (notifications sent, canceled, A/B tests, Journeys)
    * Team changes (member added, role changed, removed)
    * Configuration updates (webhooks, segments, templates, integrations)
    * Billing & subscription events
  * Powerful filtering:
    * Search by team member email
    * Filter by action type, app, IP address, or item type
    * Custom date ranges with presets
    * Shareable filtered URLs—customers can collaborate with their team instantly
  * Deep visibility:
    * Expandable rows reveal 30+ fields: IP address, browser, location, correlation ID, API version, and more
    * Available at both App and Organization levels
    * Quick-access links from Journeys, Segments, Templates, Notifications, and more
  * Retention:
    * Legal & Security package: 90-day lookback
    * All other plans: 2-day lookback
  * Perfect for security audits, debugging, and understanding team activity at a glance.
</Update>

<Update label="January 9 2026">
  * Standardized time series for charts are now available for:
    * Event Streams and webhooks
    * Email delivery reports
    * SMS/RCS delivery reports
</Update>

<Update label="December 22 2025">
  * confirmed receipt Now Available On Engagement Trends
    * Customers with access to confirmed receipt can now see confirmed receipt on the Engagement Trends Time Series Chart.
    * This missing data was a common point of confusion for customers. They could see confirmed receipt & click through rate, but had no access to the total confirmed deliveries metric.
    * This additional data point gives customers confidence in the rates we're showing and helps with confusion on the difference between "delivered" and "Confirmed receipt" for push notifications.
</Update>

<Update label="December 12 2025">
  * New integration - Self-serve Snowflake data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake without going through customer support
    * The legacy Snowflake documentation remains available for existing implementations
</Update>

<Update label="December 8 2025">
  Live Activities in Event Streams & Integrations

  Live Activities Analytics provides two key capabilities to optimize customers' live activity strategy:

  1. Better Troubleshooting with confirmed receipt
     Gain visibility into whether devices actually received live activity updates. confirmed receipt tracking identifies delivery issues quickly to understand the true reach of live activities.
     Available in:

  * Individual message reports with per-device confirmation
  * Data exports to BI tools (through event streams and integrations)

  2. Deeper Engagement Insights with data exports to integrations & event streams
     Answer critical questions about how users interact with your live activities:

  * How many users engaged with my live activity over its duration?
  * When did users drop off?
  * What was the peak engagement time?
  * When did users click? (coming soon)

  Export live activity data to BI tools to analyze engagement patterns, optimize timing, and improve future campaigns.
</Update>

<Update label="December 5 2025">
  We've launched a new [Metrics Glossary](/docs/en/analytics-metrics-glossary) in our documentation. This resource provides a single source of truth for delivery metric definitions, helping both our team and customers understand our metrics consistently across dashboards, APIs, and exports.
  While we continue working toward unified terminology across all touch points, this glossary establishes clear mappings and definitions as they exist today, making it easier for customers to navigate our current analytics landscape.

  Custom Events in User Activity Timeline
  Custom events are now visible per User on their profile page in a dedicated tab. You can:

  * Filter by event type and event source
  * Filter by date, to any time window in the past. Only limiting factor is customer's own events retention window setting!
  * Expand each event to see the full payload
  * Click through to the events index to see that event type's config and full cross-user activity log

  This is important because:

  * It helps paint the complete picture of user activity. At a basic level, customers ask the question, "what's going on with this user?" and this helps answer it.
  * Especially useful for zoomed-in troubleshooting, auditing, what-happened analysis.
  * Please note: this will only be visible to customers in Custom Events early access, but will be available to all as they gain access to Custom Events
</Update>

<Update label="November 26 2025">
  UX Improvements Now Live

  1. Row-Level Linking
     You can now click anywhere on a table row to navigate to its destination, instead of having to click a specific cell. This makes navigation faster and more intuitive.
  2. Row Highlighting on Hover
     All tables now highlight the entire row on hover, helping users track data more easily and reducing visual strain when scanning wide tables.
  3. Improved Responsiveness
     The actions column has been narrowed to preserve horizontal space and is now right-aligned at the end of every table.
     It also features sticky, floating behavior — especially useful on smaller screens where horizontal scrolling is required.
     Some tables better truncate long text (e.g., lengthy message names) more effectively to maintain a clean layout.
  4. Refined Sorting UX
     Updated sort icons make the sort direction easier to interpret. Clicking anywhere on a column header now toggles sorting, improving ease of use.
  5. Unified Column Visibility Menu (Applies to Journeys, Users, Subscriptions)
     Tables with customizable columns now use a consistent, cleaner UI. Column changes update live as you toggle them.
  6. Updated Search Bar UI
     The search bar now aligns with design standards, featuring a left-aligned search icon, and a button that shows after typing for easy input clearing.
  7. Improved Pagination Formatting
     Pagination controls now use comma formatting for large numbers, improving scannability and readability.

  Core Component Update
  Many of the enhancements above come from migrating these tables to our core design system’s DataTable component. Sorting and filtering improvements for tables are consistently among the most requested features we receive. While these updates don’t introduce new sorting or filtering behavior yet, this component upgrade provides a more consistent experience for the functionality we have today, and does lay the foundation for Product teams to build more advanced table capabilities once those initiatives are prioritized.

  Coming Soon

  * Most tables across the Dashboard already include these improvements. A few remaining areas still require component updates before they can adopt the full set of new enhancements:
    * In-app index
    * Templates index
    * Audience activity table
    * A/B tests stats table
</Update>

<Update label="November 12 2025">
  UX Enhancement: Duplicate Templates Directly from the Editor
  In usability tests and dogfooding sessions, we noticed users often duplicate Journey nodes and then edit their templates. Previously, you had to exit the template editor and duplicate the template from the index view, an extra step that interrupted the workflow.
  Now, you can duplicate templates directly from the actions dropdown in the template editor. This small but meaningful improvement streamlines your editing experience and makes iteration faster. While our long-term goal is to enable template/content editing directly within Journeys, this enhancement is a great step in that direction.

  New Platform Filters for Engagement Trends & Subscription Trends
  You can now filter push engagement trend data by platform (iOS, Google Android, Huawei, etc.) to get a more granular view of performance across specific devices.
  In the spirit of our Analytics Consistency project, we've also brought this same filtering experience to Subscription Trends.

  Analytics Consistency: Standardized Time Series Chart Filters
  We're standardizing filter options across our time series charts, giving customers a consistent experience and clear access based on their plan.
  Key Changes:

  * All charts will share the same set of granularity and look back filters
  * Consistent casing and terminology used on all filters
  * Consistent upgrade experience for customers on plans with limited access
    As an example, Subscription Trends now supports a 2 year look back after the change.

  Charts where we've already rolled out these changes:

  * Engagement Trends
  * Subscription Trends
  * Global Outcomes
  * Push Delivery
  * All Template Reports
  * Coming Soon:
  * Email Delivery
  * SMS Delivery
  * Journeys Reports

  Look back access based on plan type:

  * Free: 30 days
  * Growth: 90 days
  * Professional: 1 year
  * Enterprise: 2 years
  * Custom: Up to 90 days (based on plan types above)
</Update>

<Update label="October 6 2025">
  Nice UXE on Journey Settings. We’ve updated the Journeys Settings Side panel to be more user friendly by adding a side navigation to keep each section in focus. This is in tandem with the eventuality of having more settings available to the user as we look towards Journey Goals, and more.  We will accompany this release with an intercom slide letting the user know we have updated the settings area as to give them a heads up due to the abrupt pattern change.

  Every Setting, In Focus: Journey Settings are now grouped and spotlighted, helping you zero in on each choice without distraction.
</Update>

<Update label="October 2 2025">
  Custom Events are now available to all customers on paid plans! You can now send custom events via our API or SDK, and use them to trigger actions in Journeys with your own event data.
</Update>

<Update label="September 21 2025">
  Customers can now pause a segment that's counting towards their segments entitlement even though it's only being used in an archived journey or paused IAM. We also made it even easier to pause segments, if the user wants to pause a segment, we'll help the user pause or archive the active IAMs or journeys stopping the user from pausing a segment.
</Update>

<Update label="September 9 2025">
  Deactivate email senders

  Deactivate email domains that are no longer in use or were set up incorrectly. This includes fallback handling for your email templates and scheduled sends to make sure you don't break them by removing a domain, just in case it was being used more widely than you anticipated.
</Update>

<Update label="August 29 2025">
  Personalize emails with real-time Data Feeds

  You can now use Data Feeds to pull live content from your APIs directly into emails at send time. No more static CSVs or preloaded tags — every message can include the latest account details, product recommendations, or order updates.

  Available in the email template composer for emails sent via Journeys, Data Feeds includes preview tools and error handling to keep sends smooth.

  👉 See how to set up [Data Feeds](/docs/en/data-feeds)
</Update>

<Update label="August 04 2025">
  You can now hold users in a Journey step until specific conditions are met before they move forward with the *Wait Until* action. This new feature allows you to:

  * Hold users at a step until they enter a segment or trigger a message event (such as a specific message being delivered, opened, or clicked).
  * Add multiple conditions and branch users based on whichever condition they meet first.
  * Set an expiration path that moves users forward or removes them from the Journey if none of the conditions are met within your chosen timeframe. This gives you greater flexibility and control over how users progress through your Journeys. Learn more: [Journeys Actions](/docs/en/journeys-actions)

  AI Composer Push Notifications
  You can now generate or improve push notification message copy using the AI message composer. This update helps you craft high-performing content without leaving OneSignal. When creating a new push notification, select AI-generated push button to get started. To improve existing copy, select “Refine” in the Title, Subject, or Message fields.

  New [Integrations](/docs/en/integrations) index page contains the following enhancements:

  * Filtering by type of integration
  * Filtering by Inbound/Outbound directions of data flow
  * Includes our new inbound DWH/Data ingestion options for custom events
</Update>

<Update label="July 07 2025">
  * Quickly identify and manage segments tied to campaigns
    * We’ve made it easier to clean up outdated segments.
    * Previously, you couldn’t delete a segment if it was tied to an In-App Message (IAM) or Journey, even if that campaign was paused or archived. Now, when you try to delete a segment, you’ll see a modal listing all IAMs and Journeys that are preventing deletion.
    * This helps you quickly locate and update the associated campaigns, so you can keep your workspace clean and organized without having to hunt through every Journey or IAM.
</Update>

<Update label="June 30 2025">
  * Segment users based on real message engagement
    * You can now create user segments based on how they interacted with previous messages across push, email, SMS and in-app.
    * This update adds a new Message Event filter that allows you to segment users based on events like email opens, push clicks, SMS failures, and more - without relying on tags or external tools.
    * Available on all paid plans.
    * See [Segmentation](/docs/en/segmentation#message-event-filters) for more details.
</Update>

<Update label="June 27 2025">
  * New documentation with Mintlify!
    * We've updated our docs!
    * New AI features and easier readability.
    * Updated API reference and openapi spec.
    * New Tutorials page with common use cases and step-by-step details to get you setup quickly!
</Update>

<Update label="June 18 2025">
  * Track In-App engagement trends alongside push, email, and SMS
    * Customers can now see In-App Message impressions, clicks, and click-through rates directly in the Engagement Trends chart. This update gives marketers a unified view of how users are interacting with all message types over time—including In-App—making it easier to spot trends, report on performance, and optimize messaging across channels.
    * With this update, In-App engagement data is now included alongside push, email, and SMS across all views in the Engagement Trends chart. Stats are grouped by day and support up to two years of data (depending on plan). This data is exportable via CSV just like other channels, and can be filtered to look at specific date ranges or message types.
    * This feature is available to all customers.
</Update>

<Update label="June 12 2025">
  * Unlock deeper email engagement insights with multi-link tracking
    * Customers can now track engagement on every individual link within their emails. This update gives customers a much clearer view into what content or messaging is working so they can improve email performance over time.
    * Previously, when customers included multiple links within an email, they could only view total click counts across all links. Now, they can see which specific links get the most engagement and how links perform inside journeys. This helps them refine content and messaging strategies.
    * Multi-link tracking is automatically applied to most emails created in the Drag & Drop or HTML editor. Link-level performance metrics will also be available for emails sent using a template and emails in a Journey.
    * This feature is available to all customers with access to email.
</Update>

<Update label="May 23 2025">
  * View and optimize message performance with Template Analytics
    * OneSignal customers can quickly assess how individual templates are performing across all messages, without needing to download and stitch together separate reports.
    * When users click into a template, they now land on a detailed analytics view showing Delivered, Unique Opens, Unique Clicks, and Unsubscribes. They can track performance over time, filter by platform, explore delivery breakdowns like Failed or Capped, and review a list of messages that used the template.
    * Template analytics is especially useful for:
      * Marketers who test and iterate on message content
      * Developers who need visibility into transactional message delivery
      * High-volume senders seeking scalable insights
    * Transactional visibility is a key differentiator that sets us apart from Firebase and other open source solutions. Customers can now answer questions like “How many Account Confirmation emails did I send last week?” or “What was the click-through rate on my Password Reset messages?”
    * Important note: For templates created before April 17, 2025, enhanced metrics are only available for messages sent after that date. Customers can use the “Show historical data” toggle at the top of the page to see earlier performance data.
    * The feature is live and available by default. Reporting history varies by plan:
      * Free: 30 days
      * Growth: 90 days
      * Professional: 1 year
      * Enterprise: 2 years
</Update>

<Update label="May 16 2025">
  * Add users manually from the dashboard
    * You can now create new users directly from the *Users* tab in your OneSignal dashboard using a simple form. This update makes it easy to manually add a user with an email address, phone number, or both without needing an SDK, API call or CSV upload.
    * This is especially helpful for quickly testing campaigns or adding users who aren’t yet in your system.
</Update>

<Update label="May 14 2025">
  * Track SMS link performance directly in OneSignal
    * Customers can now track SMS link performance directly in OneSignal without needing third-party tools like Bit.ly or custom UTM parameters. This feature gives our customers a more streamlined, built-in way to measure engagement and optimize messages faster, removing friction and helping drive better results from their SMS efforts.
    * When composing an SMS message, customers simply click “Insert Trackable Link” and enter the full URL they want to send users to. OneSignal automatically shortens the link using the 1sgnl.co domain so it fits within SMS character limits and can be tracked.
    * All SMS users will have access to trackable links as part of their existing plan.
</Update>

<Update label="May 07 2025">
  * Simplify message organization with easier label management
    * Now you can add labels to your messages to help you organize and manage them.
    * See [Labels](/docs/en/labels) for more details.
</Update>

<Update label="May 01 2025">
  * Template analytics
    * You can now view and optimize template performance from a centralized reporting view. Click into any message template to view detailed performance data across every message a template is used in.
</Update>

<Update label="Apr 25 2025">
  * Improved CSV Importer
    * **Real-time validation:** Get instant feedback on formatting errors before upload.
    * **Smart column mapping:** Easily align your CSV headers with OneSignal fields.
    * **Email suppression support:** Add or manage your suppression list directly in the file.
    * **Upload history:** View the status of your past imports for up to 30 days.
    * **Helpful templates:** Start quickly with a pre-built CSV example.
</Update>

<Update label="Apr 21 2025">
  * Fine-tune your Live Activities with new API parameters
    * You can now add more control, reliability, and speed to your Live Activities with three new parameters in the OneSignal API: - ios\_relevance\_score: Helps determine which Live Activity displays most prominently on iOS. - include\_aliases: Allows you to target individual users directly rather than relying on segment-based delivery. - idempotency\_key: Prevents the creation of duplicate Live Activities when retrying start requests if not using the OneSignal SDK.
</Update>

<Update label="April 14 2025">
  * New integration - Databricks data export
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Databricks. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Databricks, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="April 08 2025">
  * View opt-out status by sender and support transactional messaging even with marketing opt-outs
    * You can now see SMS opt-out status by sender, giving you better visibility and control when managing marketing and transactional messages.
    * With this update, you can:
      * View subscription status by individual sender for any phone number
      * Continue sending transactional messages (like OTPs or alerts) even if a user has opted out of marketing
      * Maintain deliverability and avoid carrier filtering by respecting opt-out preferences
    * This is especially useful if you manage separate senders for promotional and transactional use cases.
    * To access this feature, go to **Consent Management > Advanced Opt-out Settings** and turn off the setting that globally unsubscribes a user when they reply with an opt-out keyword.
    * *Note: This option is only available to customers using advanced opt-out settings for SMS.*
</Update>

<Update label="March 19 2025">
  * Easily find and select the right templates with visual previews
    * Quickly identify and select your email and in-app message templates with the new updated card view.
    * Instead of relying on template names alone, you can now see clear visual previews, making it easier to choose the right template at a glance.
</Update>

<Update label="March 12 2025">
  * Create users in OneSignal via HubSpot workflows
    * Keep your users in sync across HubSpot and OneSignal! With this new workflow action, you can now create users in OneSignal whenever a HubSpot workflow trigger fires. This enables you to queue up personalization details (such as Tags) and plan engagement strategies before a user even interacts with your mobile platform. Additionally, you can trigger an SMS or email via HubSpot while simultaneously creating a user in OneSignal—ensuring seamless and immediate engagement.
    * [HubSpot Documentation](/docs/en/hubspot)
  * Push preview accuracy improvements
    * As operating systems update, they often introduce new changes in their push designs.
    * We've updated our previews so they match latest and greatest push notification designs across iOS (18), Android (15), Windows (11), macOS (Sequoia). This ensures you see what your users will see when testing in OneSignal.
  * PII Masking of Emails and Phone Numbers
    * Protect user privacy and reduce compliance risks by masking personally identifiable information (PII) such as emails and phone numbers. With PII masking, your team can work securely while still analyzing campaign performance and sharing insights across teams.
    * OneSignal automatically masks phone numbers and emails in the dashboard and any data exported directly from the platform. However, PII masking does not currently apply to data accessed via API requests, external IDs, or Tags.
</Update>

<Update label="March 07 2025">
  * Verify & Lookup Phone Numbers
    * Sends the user a one-time verification code to ensure the customer owns the phone #
    * Confirms the phone number entered by a user at onboarding is valid
</Update>

<Update label="February 28 2025">
  * Added New Integration - [BigQuery Data Export](/docs/en/bigquery)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to BigQuery. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in BigQuery, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
  * Channel subscriber counts have moved
    * The counts of subscribed counts for each channel have moved from the dashboard to the Subscriptions page in OneSignal. Now you will see the number of *Subscribed* subscriptions for each channel at the top of the Subscriptions page under Audience to get an overview of audience reach per channel in the context of your subscriptions.
    * If you still wish to view this information on the Dashboard, you can filter your Subscriptions trends chart by channel.
</Update>

<Update label="February 14 2025">
  * Improvements to Keywords
    * We've made a couple of improvements to our SMS keywords.
      * Segment by subscription status when sending a keyword to encourage converting your customers who are not yet subscribed into opting in to your SMS marketing messages
      * Setup an auto-responder for unrecognized keywords
</Update>

<Update label="February 12 2025">
  * New Engagement Analytics on the OneSignal Dashboard

    * Are you curious to learn more about how your end users engage with the messages you send from OneSignal? Head to your Dashboard to see the new Engagement Trends report.
    * With this report you will gain insight into how users engage with your messages across Push, Email, and SMS. Track click-through-rate, unsubscribes, and monitor trends over time to refine your messaging strategy and optimize communication frequency. This comprehensive report consolidates data from all message types (Dashboard, API, Journeys) for a clearer view of performance. Now available in your OneSignal dashboard!

    <Frame>
      <img alt="New Engagement Analytics on the OneSignal Dashboard" />
    </Frame>
</Update>

<Update label="January 29 2025">
  * Sort segments by Last edited, Created at and more
    * Finding and managing your segments just got easier!
    * You can now sort segments by Last edited, Created at and more.
      * This update is especially valuable for customers who:
        * Maintain numerous segments
        * Frequently update their segment configurations
        * Need to identify and clean up outdated segments
        * Want to quickly find recently modified segments
</Update>

<Update label="January 27 2025">
  * Email Senders (Multi-Domain Sending)
    * Create distinct senders for different types of communications:
      * Keep your marketing campaigns separate from crucial transactional emails
      * Maintain different brand voices for various product lines
      * Optimize sender reputation for each type of communication
      * [Email Senders](/docs/en/senders)
  * Improved In-app Message Analytics for Event Streams
    * We've added a new In-app Message Analytics for Event Streams.
</Update>

<Update label="January 21 2025">
  * Email Intelligent Delivery
    * We've added intelligent delivery to email.
    * Transform your email engagement with OneSignal's latest breakthrough: Intelligent Delivery. This powerful new feature automatically determines the optimal time to reach each individual user, maximizing your email campaign's impact.
    * Our algorithm continuously learns from:
      * User open patterns
      * Click-through behavior
      * Real human interactions (excluding bot activity)
</Update>

<Update label="January 16 2025">
  * Retirement of Automated Message for Free apps
    * Automated Messages are no longer supported and the feature has been retired in the free plan. Paid apps will continue to have access to this feature until further notice.
    * Active automated messages will remain live and continue functioning as expected. However, you can no longer create new automated messages, or reactivate paused automated messages. To build new automated sequences and enhance your campaigns, we recommend using [Journeys](/docs/en/journeys-overview).
</Update>

<Update label="January 15 2025">
  * Customize how your users re-enter split branches
    * Now you can customize how your users re-enter split branches. This feature is available for all Journeys.
    * [Journey Entry Triggers](/docs/en/journeys-actions)
  * Improving New Message Experience
    * We improved the new message experience by adding a library of templates (get inspiration for your next push, in-app, email, or SMS), or quickly start from a template you've made, or a previous message.
</Update>

<Update label="January 03 2025">
  * message.url - New Push Event Stream Property
    * `message.url` is now a supported property for push events. It enables the retrieval of the launch URL directly from your event stream payload.
</Update>

<Update label="December 24 2024">
  * Journeys Multi-split Branching
    * Now you can set up more personalized paths in your Journey. Create up to 20 branches to test channels, content, timing, ordering, and more. Assign different weights to each branch, or easily distribute audiences evenly across all branches. See how different paths perform against each other or against a control group.
</Update>

<Update label="December 20 2024">
  * WordPress Plugin v3
    * We've upgraded our Wordpress Web Push plugin to v3+. What's changed:
      * Upgrades the OneSignal Web SDK from version 15 to 16.
      * Setup more new prompts within the OneSignal dashboard, including the following. No custom code is required anymore to configure these.
        * Category Prompt
        * Email/Phone Slide Prompt
        * Custom Link Prompt.
      * When publishing a new post, check the "Send notification when post is published" box to send a push notification.
      * Choose which audience segment should receive notifications for each post.
      * Web Topics are included by default.
      * Send to mobile app subscribers, with an option to direct them to a different URL (Deep Link).
</Update>

<Update label="December 11 2024">
  * Improved Logs in Event Streams
    * We've improved the Event Streams feature to make troubleshooting simpler and faster. Now, you’ll find dedicated tabs for successful and failed events, making it easier to spot issues at a glance. Clear empty states show when there’s no data in either tab, and updated messaging ensures you know the logs display a sample of your data.
  * SMS Keywords
    * We've added keywords for SMS. Keyword engagement enables quick, two-way communication, enhancing personalization, accessibility, and user satisfaction. It drives conversions and higher engagement with your subscribers. Add a data tag to the keyword, and segment based on their preferences to send more targeted SMS.
  * Quickstart Segments

    * We are thrilled to launch three new segment templates designed to help you hit the ground running with proven strategies:
      * First-Time audience
      * Regional audience
      * Custom Audience based on tags
    * Our analysis of 6.3 billion message deliveries uncovered powerful insights. These templates are built to help you:
      * Create high-performing segments from day one.
      * Use proven filter combinations that drive higher engagement.

    <Frame>
      <img alt="Quickstart Segments" />
    </Frame>
</Update>

<Update label="December 02 2024">
  * Email Quickstart Templates
    * We've added a library of quickstart templates for email. Explore our library of professionally crafted email templates, designed to inspire your creativity and elevate your email campaigns. Use them as a starting point to create impactful messages that drive conversions and engage your audience effectively.
</Update>

<Update label="November 27 2024">
  * Scheduling Journeys
    * Now you can schedule Journeys to send at a specific time. This feature is available for all Journeys.
  * Settings Overview Page
    * Now you can access and manage all your settings in a centralized setting overview page. Platform-specific settings have been reorganized under their relevant channels for better clarity.
</Update>

<Update label="November 20 2024">
  * Bulk Archive and Delete Journeys

    * Now you can bulk archive or delete Journeys from the Journeys index. Select up to 20 Journeys, and then choose an action you'd like to take to clean up Journeys you're no longer using.

    <Frame>
      <img alt="Bulk Archive and Delete Journeys" />
    </Frame>
</Update>

<Update label="November 06 2024">
  * Improved Export for Global Outcomes
    * We've improved the export for Global Outcomes to include more data and make it easier to use in your reporting.
  * Preview allows you to preview the content of a message and can be very helpful when you have a message with personalization (i.e. Tags, dynamic content, custom data). With preview, you can preview content from a specific test user's perspective, or with example custom data.
  * Settings for Email & Side Navigation Updates
    * In the side navigation, you can now easily see your Push, SMS, and Email settings. What was once "Messaging" is now "Push" settings, and SMS and Email Settings will take you directly to your channel's settings.
    * For email, we've created a dedicated place to manage your email provider and senders. If you are a OneSignal mail user, you'll also be able to see your reputation and suppression lists here.
  * SMS Usage
    * We've added SMS Usage in the Usage page. We've also added a breakdown so you can see the message type, and a breakout by inbound and outbound. You may see an unknown country if a segment failed to send.
</Update>

<Update label="October 02 2024">
  * Add Notes on your Journeys
    * Now you can add notes to the steps of your Journeys to keep reminders and more effectively collaborate and share information with your team. This feature is available for all Journeys.
</Update>

<Update label="September 27 2024">
  * New Quickstart Journeys
    * We've added a new Quickstart Journeys to help you get started with Journeys. This feature is available for all Journeys.
  * SMS Text-to-Subscribe
    * It's now easier to set up double opt-in and text-to-subscribe phone number collection experiences for your customers!
</Update>

<Update label="September 12 2024">
  * Confirmed Click-Through-Rate (CCTR) metric

    * We have added a new metric to measure the CTR using confirmed receipt. Confirmed Click-Through-Rate (CCTR) is measured by (total clicks/confirmed delivered) \* 100%

    <Frame>
      <img alt="Confirmed Click-Through-Rate (CCTR) metric" />
    </Frame>
</Update>

<Update label="September 06 2024">
  * Export your Subscription Trends
    * Now you can export the data from your Subscription Trends report as a CSV. If you apply filters to the report, OneSignal will export based on the filters you've applied so that you can fine-tune the data that you use to evaluate your messaging audience.
</Update>

<Update label="August 05 2024">
  * Email Saved Rows
    * Saved Rows are reusable content blocks that help streamline email creation and management. Many companies, especially those that have a lot of templates, prefer to use saved rows in their emails for consistency and to save time. Saved Rows are easily attached to new emails so you don't have to create the same information from scratch each time. And when things change, you just have to update the saved row, and your updates will automatically sync across all campaigns that have that saved row attached.
    * Common use cases include:
      * headers (logo, slogan)
      * footers (company details, social media links, mailing addresses)
      * disclaimers
      * other elements that are used across multiple campaigns
    * You can now save Email Drag-and-Drop rows to use across many Campaigns or Templates. These re-suable **Saved Rows** make it easy to sync updates across many emails at once. Click on the **Rows** tab of a Drag-and-Drop email, to view your **Saved Rows**. To save your first row, click the save icon in the edit, in the top right corner of the row.
    * We recommend you set up all of your templates to use saved rows for your header and footer so that you need to update the branding or content; you only have to make those edits once.
</Update>

<Update label="July 30 2024">
  * Journeys now target anonymous users
    * Now, Journeys do not require External IDs to be set on subscriptions. Instead, Journeys will target your entire user base within OneSignal, including anonymous users. We recommend still configuring External IDs to identify individual users who have subscribed to multiple channels.
</Update>

<Update label="July 25 2024">
  * Have more visibility into SMS unsubscribes, resubscribes, and help keywords
    * We now make it easier to manage your Consent Keywords within Onesignal. Reach out to support if you'd like to update the default consent keywords and replies.
</Update>

<Update label="July 19 2024">
  * Email Reply-to field now supports custom properties
    * Now you can use [Message Personalization](/docs/en/message-personalization) within the `reply-to`field on an email. This allows you to direct message replies to the right inbox and can be helpful if you are sending from different brands or across different countries.
</Update>

<Update label="July 16 2024">
  * Push Failures and Unsubscribes in Audience Activity
    * Obtain a list of subscriptions that have faced errors - failures or unsubscribes, for a specific push notification in the push report page.
</Update>

<Update label="July 03 2024">
  * Integrations: OneSignal Message Events can be sent to Twilio Segment
    * Customers can now select and send message events from OneSignal to sync back to their Twilio Segment account, making the Segment integration bidirectional.
  * Use Audience Activity for Live Activities to get a list of recipients
    * Get a list of subscriptions that successfully or failed to receive a Live Activity on a Live Activity report page, which is accessible through the Delivery - Sent Index. This list can be exported as well.
</Update>

<Update label="June 06 2024">
  * In-app message audience activity
    * In the report page of an in-app message, you can now see which mobile subscriptions viewed (impression) or clicked on an in-app message. Audience activity is available for 30 days from the time the message is displayed
</Update>

<Update label="May 15 2024">
  * FCM Expired Tokens > Increased Android Unsubscribes
    * On May 15, 2024, Google's FCM service will start to expire stale push tokens for devices that have been inactive for more than 270 days. You may see a spike in Android unsubscribes when sending notifications due to this change. Don't panic! These are devices that have not been online in over 270 days and are part of Google's [Best practices for FCM registration token management](https://firebase.google.com/docs/cloud-messaging/manage-tokens). If the device does come back online and opens your app, OneSignal will automatically resubscribe them to push if they were previously subscribed already.
    * See [FCM Expired Token FAQ](/docs/en/fcm-expired-token-faq) for more details.
</Update>

<Update label="April 29 2024">
  * Configure more granular Frequency Capping rates for Push
    * Push notifications can now be capped at a rate of x notifications per any time frame (less than 1 week). Navigate to Settings > Messaging > Push Frequency Capping > Custom (in the time dropdown) to view these settings.
    * Read [Frequency Capping Documentation](/docs/en/frequency-capping) for more details.
</Update>

<Update label="April 11 2024">
  * Added Android Live Notifications
    * Android's Live Notifications deliver live, dynamic content in notifications to enhance user engagement and app interactivity. This is a feature similar to iOS's Live Activities feature (introduced with iOS 16), but uses its own set of tools and APIs that enable similar functionalities.
    * See [Android Live Notifications](/docs/en/android-live-notifications) for more details.
  * Major improvements to Android SDK
  * Push to start Live Activities
    * Live Activities can now be launched on a user's screen when the mobile app is in the background (app is not open). Live Activities can both be started and updated by a remote push notification.
    * [How to start a Live Activity with a remote push notification](/docs/en/live-activities)
</Update>

<Update label="April 01 2024">
  * Added Audience Activity reports for Journeys
    * We have added Audience Activity reports for Journeys so you can get a closer look at which subscriptions were sent messages during a Journey. To view this report, click into a message report on your Journey. [Learn more here](/docs/en/journeys-analytics#audience-activity).
</Update>

<Update label="March 18 2024">
  * Added a new Setup guide for Analytics
    * We have added a new Analytics Setup guide to our product documentation detailing how to track Confirmed Deliveries and set up Custom Outcomes with support from your development team.
</Update>

<Update label="March 12 2024">
  * Mobile SDK Updates
    * We recommend updating to the latest SDK versions listed below to benefit from critical bug fixes, stability improvements, and new features. These updates include key enhancements across all platforms, including iOS 5.1.3 and Android 5.1.6, which improve concurrency safety, crash resilience, and background thread handling. The updates also include important API adjustments like more accurate property handling in the `PushSubscriptionState`.
</Update>

<Update label="February 16 2024">
  * Journeys is now available on the Growth plan
    * Journeys is now available on the Growth plan. This means you can now create and manage Journeys with up to 100,000 users.
    * See [Journeys](/docs/en/journeys-overview) for more details.
</Update>

<Update label="February 12 2024">
  * Added Auto Warm Up
    * We have added a new feature that allows you to automatically warm up your app when a user opens it. This feature is available for all OneSignal customers.
    * See [Email Warm Up](/docs/en/email-warm-up) for more details.
</Update>

<Update label="February 02 2024">
  * Journeys has easier targeting based on user activity
    * We've added support for Segments with time-based rules (e.g., first session, last session, etc.) and also simplified targeting inactive users. Now you can target your inactive users by including a segment based on last session behavior.
  * Email: Schedule Sends Across Different Timezones
    * Email campaigns can now be scheduled to send across different timezones. This feature is available for all OneSignal customers.
</Update>

<Update label="January 30 2024">
  * Email now supports One Click Unsubscribe
    * Inbox Service Providers (ISP) like Gmail, Outlook, iOS Mail, and Yahoo! Mail, AOL, and Verison Mail require senders to provide a One Click Unsubscribe option. The unsubscribe button is rendered at the discretion of the ISP based on sending criteria, which may include a daily sending volume greater than 5,000 emails.
</Update>

<Update label="December 18 2023">
  * Filter your messages with labels
    * Now you can filter your messages with [labels](/docs/en/labels). This feature is available for all OneSignal customers.
  * CSV Importer can now update properties
    * CSV Importer for email now enables updates to user properties `language`, `country`, and `timezone_id`.
  * Send more personalized messages and multi-language emails
    * [Dynamic Content Documentation](/docs/en/dynamic-content)
</Update>

<Update label="December 14 2023">
  * All OneSignal apps now belong to an Organization
    * We have added a new feature that allows you to manage your OneSignal apps within an Organization. This feature is available for all OneSignal customers.
    * See [Apps, Orgs, and Accounts](/docs/en/apps-organizations)
  * Journeys now has better analytics
    * We've added a new Journeys Report. See [Journeys Analytics](/docs/en/journeys-analytics) for more details.
</Update>

<Update label="November 22 2023">
  * Removed Journey Notifications from Delivery Reports and the View Notifications endpoint
</Update>

<Update label="October 04 2023">
  * Added new integration - [Snowflake](/docs/en/snowflake)
    * OneSignal customers can now effortlessly sync their app’s message event data—including push, email, in-app, and SMS—directly to Snowflake. This integration enables secure, automatic data transfer, allowing teams to unify their OneSignal messaging data with broader funnel insights. By centralizing this data in Snowflake, customers can unlock deeper analytics, measure the impact of their messaging, and make more data-driven decisions with ease.
</Update>

<Update label="September 27 2023">
  * You can now save and continue
    * Changed the default option for saving a message to save work without exiting the message.
</Update>

<Update label="September 13 2023">
  * Added the ability to adjust the default padding for IAM blocks
    * Learn more about [IAM blocks](/docs/en/design-your-in-app-message)
  * Added the ability to edit entry triggers and re-entry rules for live Journeys
    * Learn more about [Journey entry triggers](/docs/en/journeys-overview)
</Update>

<Update label="September 05 2023">
  * Added ability to create multi-language push messages by pasting your CSV
    * Learn more about [Multi-language messages](/docs/en/multi-language-messaging)
  * Added new "Editor" role permissions
    * Learn more about [Managing team members](/docs/en/manage-team-members)
  * Added enhanced Journey message stats and reports.
    * Learn more about [Journey message stats and reports](/docs/en/journeys-analytics)
</Update>

<Update label="September 01 2023">
  * Added a new feature to forward email templates to an app
    * Learn more at [Email Template Forwarding](/docs/en/email-template-forwarding)
  * Added FCM v1 API support for Android Push Notifications
    * Learn more about [Android Firebase credentials](/docs/en/android-firebase-credentials)
</Update>

<Update label="August 15 2022">
  * Android 13 changes
    * Android 13 introduces a runtime notification permission, meaning users must opt in to receive push notifications. Apps targeting Android 13 must explicitly prompt for permission at a time of their choosing, or the system will display the permission prompt automatically on first launch—often resulting in lower opt-in rates.
    * See [Android 13 Push Notification Developer Update Guide](/release-notes/android-13-push-notification-developer-update-guide) or our [Prompt for Push Permissions](/docs/en/prompt-for-push-permissions) guide for details.
</Update>


# SDK Releases
Source: https://documentation.onesignal.com/release-notes/sdk-releases

View the latest OneSignal SDK releases and updates.

## Mobile

<SdkReleasesIframe />

## Web

<SdkReleasesIframe />

## Server

<SdkReleasesIframe />

## Plugins

<SdkReleasesIframe />