General

name

Type string

Description

Serves as an internal identifier to help organize your notification campaigns. The name is not visible to the end-users and is used solely for your purposes within your campaign management workflow.

Guidance

Assign meaningful names that reflect your notification campaign's purpose, content, or target audience to facilitate easier tracking and management of multiple campaigns.

custom_data

Type object

Description

User-specific or context-specific information for Message Personalization.

Guidance

• The object must be in JSON format.
• The payload may include up to 2,048 bytes for Push and SMS notifications and up to 10 kilobytes for email messages.

Example

{
  "custom_data": {
    "cart_items": [
      {
        "item_name": "sweater",
        "img_url": "https://store.onesignal.com/assets/sweater.png"
      },
      {
        "item_name": "socks",
        "img_url": "https://store.onesignal.com/assets/socks.png"
      }
    ]
  }
}

💡

Leverage Custom Data to personalize your transactional messages.

external_id

Type string

Description

Acts as a correlation identifier and an idempotency key to prevent duplicate notification deliveries. This is not the User External ID. Idempotent Notification Requests enable you to send requests while ensuring users receive a message only once. Messages with the same external_id send only one notification, and subsequent responses return the same result.

Guidance

• Keys must be unique. We recommend using a universally unique identifier (UUID) for this.
• The key remains idempotent for 30 days, meaning any request with the same external_id will not result in additional messages sent within this period. After 30 days, a notification with the same external_id may be considered a new request and could result in a new message being sent.

Example

{
  "external_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

☝ Ensures users receive the message once, even if there are any retry attempts or duplicated requests within a 30-day window.

Targeting

included_segments

Type string[]

Description

The segments to target for sending the message to. Members of each segment will receive the notification unless they're also members of a segment specified in the optional excluded segments parameter.

Guidance

Provide an array of the Segment names.

Example

{
  "included_segments": [
    "Active Users",
    "Inactive Users"
  ]
}

excluded_segments

Type string[]

Description

Segments to exclude from receiving the message. Overrides membership in any segment specified in the included_segments parameter.

Guidance

Provide an array of the Segment names.

Example

Target a message for customers who've spent $5K or more while excluding those deemed inactive, even if they are included in the segment "CLTV 5K".

{
  "included_segments": [
    "CLTV 5K"
  ],
  "excluded_segments": [
    "Inactive Users"
  ]
}

filters

Type object[]

Description

Filters allow you to dynamically define your notification's recipients based on their attributes or behaviors. They can be combined for complex targeting logic, enabling precise audience segmentation without the need to pre-define a segment. To learn more about the types of Filters that exist, refer to our documentation on Segments

Guidance

Filter fields

The filters parameter targets notification recipients using an array of JSON objects containing field conditions to check. The following are filter field options:

Using Filters

• Filter entries use "AND" by default; insert {"operator": "OR"} between entries to "OR" the parameters together.
• "AND" has priority over "OR".
• For performance reasons, a maximum of 200 entries can be used at a time. The 200 entries limit includes the "field" entry and "OR" entries -- each would count towards the 200 limit. Below, "Formatting Example 1" would be 2 entries and "Formatting Example 2" would be 3 entries.
• Tag filters using an equality ("=") or "exists" operator are very fast.
• Negation (eg. "!=" and "not_exists") is inherently more expensive to compute. Our default database indices map tags to devices, and can’t track which devices don’t have specific tags -- there are infinite tag keys which each device does not have. Upon request, it is sometimes possible for us to create a specific index on your application to address problems with negation.
• Numeric ordering operators like "<" or ">" are slow by default. Note that upon special request, we can add a special index for specific tags to improve performance of these operators.
• Filters on the "last_session", "session_count", and "country" fields are fast on their own or together, but when used with other filters such as tags can make the segment take longer to compute.

Formatting Filters

The power of filters comes from combining several fields and operators to precisely target your users. The following are examples of filters and how to format them:

1. A user is level 10 and purchased an item

2. A user is level 10 or 20

3. A user is not VIP or is admin

4. User's tags include key username and the user is not banned.

"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "amount_spent", "relation": ">","value": "0"}
]

"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"}, 
  {"operator": "OR"}, {"field": "tag", "key": "level", "relation": "=", "value": "20"}
]

"filters": [
  {"field": "tag", "key": "is_vip", "relation": "!=", "value": "true"},
  {"operator": "OR"}, {"field": "tag","key": "is_admin", "relation": "=", "value": "true"}
]

"filters": [
  {"field": "tag", "key": "username", "relation": "exists"},
  {"field": "tag", "key": "banned", "relation": "!=", "value": "true"}
]

include_aliases

Type object

Description

Targets specific users based on their Aliases & External ID.

Guidance

• Provide an object of aliases to include.
  • User's External ID – external_id
  • OneSignal ID – onesignal_id
  • Custom alias name – some_custom_alias
• You may include up to 2,000 Alias IDs per API call.

Example

Send a message to the users identified by the EUIDs "one", "two", and "three" using the push channel.

{
  "include_aliases": {
    "external_id": [
      "one",
      "two",
      "three"
    ]
  }
}

💡

Use with the target_channel parameter to control the delivery channel.

include_subscription_ids

Type string[]

Description

Allows targeting users based on their Subscription ID.

Guidance

You may include up to 2,000 IDs per API call.

Example

{
  "include_subscription_ids": [
    "1dd608f2-c6a1-11e3-851d-000c2940e62c"
  ]
}

target_channel

Type string

Description

The channel in which to deliver a message. Use in conjunction with include_aliases.

Guidance

Choose from the following options:

• "push" – send the message as a push notification
• "email" - send the message as an email
• "sms" - send the message as a text message

Example

{
  "target_channel": "push"
}

Delivery

send_after

Type string

Description

Schedule notifications for future delivery; defaults to Coordinated Universal Time (UTC). Align delivery with your target users' time zones so they're more likely to see it.

Guidance

Specify the string according to the ISO 8601 calendar format. A heuristic you can use to determine whether we can parse your date-time string is whether Javascript's Date constructor can parse the string.

Example

All of the following are valid and equivalent formats for the same date and time:

• { "send_after": "Thu Sep 24 2015 14:00:00 GMT-0700 (PDT)" }
• { "send_after": "2015-09-24 14:00:00 GMT-0700" }
• { "send_after": "Sept 24 2015 14:00:00 GMT-0700" }

delayed_option

Type string

Description

Choose how deliveries should be scheduled.

Guidance

• timezone – simultaneous across time zones at the same local time.
• last-active – enable Intelligent Delivery, which schedules notifications based on the user's Last Active Session.

Example

Deliver the notification worldwide at 9 AM in each user's local time zone.

{
  "delayed_option": "timezone",
  "send_after": "2024-03-05T15:00:00.600Z"
}

🚧

Incompatible with Message Throttling

Set throttle_rate_per_minute to 0 to disable throttling.

delivery_time_of_day

Type string

Description

Specify when the message should be delivered when the delayed_option parameter is "timezone". It's ideal for time-sensitive daily digests, reminders, or promotions.

Guidance

• Format the time as a string, which can be in various formats such as:
  • 12-hour e.g., "9:00AM"
  • 24-hour e.g., "21:45"
  • HH:mm:ss format - e.g., "9:45:30"

Example

Schedule a notification for all users in the morning at 9:00 AM local time.

{
  "delayed_option": "timezone",
  "delivery_time_of_day": "9:00AM"
}

Path

notification_id

The identifier of the message of interest. Locating this value depends on how the message was created.

• Create Notification API - the response's id property.
• View Notifications API
• The URL of the Message Report page

Outcomes

Parameters for View Outcomes can be used with this View Notification API.

Search

app_id

Type string

Description

Identifies your application within our system.

Guidance

• The value must be a universally unique identifier (UUID).
• Refer to Keys & IDs to learn more.

limit

Type number

Description

Specifies the maximum number of notifications to return in a single query.

Guidance

This parameter helps control the volume of data retrieved during one operation, especially when navigating many notifications.

• The default value is 50.
• The maximum value that can be used is 50.

offset

Type number

Description

Controls the starting point for the notifications being returned.

Guidance

Results are returned and sorted in descending order by queued_at.

• The default value is 0 (Starts at the beginning of your notification list).

kind

Type number

Description

Specifies the type of notifications to return.

Guidance

Use this to segment notifications by their creation method, allowing for targeted analysis or management of notification types.

• All notification types are returned by default.
• 0 — Notifications created through the dashboard.
• 1 — Notifications sent via API calls.
• 3 — Notifications triggered through automated systems.

template_id

Type string

Description

Specifies the identifier of a pre-defined template used to configure a message.

Guidance

To obtain the template_id, navigate to the relevant template in your dashboard. It's typically found in the URL or designated section within the template settings.