Remotely start a Live Activity.
Overview
This API lets you start a Live Activity by sending a Push Notification.
Path Parameters
activity_type
activity_type
Required
Type: string
Description
Indicates which Live Activity to start.
Guidance
Use the structure's name in your app's Live Activity file that defines the attributes and state of the Live Activity.
Select your target audience
Before sending a message, you need to determine who should receive it. OneSignal offers three targeting options:
- Aliases & Subscription IDs: Send messages to specific users using unique identifiers such as external ids, OneSignal IDs, custom aliases, or subscription IDs
- Segments: Target predefined user groups based on attributes and behavior.
- Filters: Create custom targeting rules using user properties, such as tags, location, or activity.
Only one targeting method per message
You can only use one targeting method per message. For example, you cannot combine alias-based targeting with filters in the same request.
Additionally, when sending push notifications using any of these methods, you can choose to Target specific platforms, limiting your message to one or more platforms (Android, iOS, Web).
Body Parameters
include_aliases
include_aliases
Type object
Description
Targets specific users based on their External ID or custom Aliases. You may include up to 20,000 Alias IDs per API call.
Provide one object of aliases to include.
- User's External ID –
external_id
- OneSignal ID –
onesignal_id
- Custom alias name –
some_custom_alias
Example
Send a message to the users identified by the External IDs "user1", "user2", and "user3" using the push channel.
{
"include_aliases": {
"external_id": [
"user1",
"user2",
"user3"
]
},
}
include_subscription_ids
include_subscription_ids
Type string[]
Description
Targets users based on their Subscription ID. Include up to 20,000 IDs per API call.
Example
{
"include_subscription_ids": [
"1dd608f2-c6a1-11e3-851d-000c2940e62c"
]
}
included_segments
included_segments
Type string[]
Description
The segments to target. Members of each segment will receive the notification unless they're also members of a segment specified in the optional excluded segments
parameter. Users that are in multiple segments will only be sent the message once.
Example
{
"included_segments": [
"Active Users",
"Inactive Users"
]
}
excluded_segments
excluded_segments
Type string[]
Description
Segments to exclude from targeting. Overrides membership in any segment specified in the included_segments
parameter.
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
filters
Type object[]
Description
Filters allow you to dynamically define your message's audience based on their properties. They can be combined with "AND"
and "OR"
operators for complex targeting logic, enabling precise audience segmentation.
For performance reasons, a maximum of 200 entries can be used. The 200 entries limit includes the "field"
entry and "OR"
entries - each would count towards the 200 limit.
Filter performance:
- Tag filters using an equality (
"="
) or"exists"
operator are very fast. - Negation (eg.
"!="
and"not_exists"
) is inherently more expensive to compute because it depends on how many tags per user are set. 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.
Available filters:
- operator
- tag
- last_session
- first_session
- session_count
- session_time
- language
- app_version
- location
- amount_spent
- bought_sku
activity_id
activity_id
Required
Description
A self-generated identifier uniquely identifies your Live Activity and associates devices with the event.
Guidance
- Generate a unique
activity_id
to track and manage your 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. - Provide this
activity_id
when calling the iOS SDK methodenterLiveActivity
. This linkage is necessary for the iOS SDK to correctly handle and update the Live Activity. - Ensure that the
activity_id
is unique and consistently used for each Live Activity to avoid conflicts and ensure accurate tracking.
Example
{
"activity_id": "217aae2b-42ee-4097-bc3f-b7a6e9d15b9b",
...
}
Refer to this guide to learn more about starting and updating Live Activities.
event_attributes
event_attributes
Type: object
Description
The static data to initialize the Live Activity with.
Example
{
"event_attributes": {
"awayTeam": "Celtics",
"homeTeam": "Lakers"
}
}
event_updates
event_updates
Type: object
Description
The content to update a running Live Activity with. The object must conform to the ContentState
interface defined within your app's Live Activity.
Guidance
Ensure that the event_updates
object matches the ContentState
interface exactly as defined in your Live Activity implementation. Inconsistencies can cause Live Activities to fail to display.
Example
In this example, the object includes fields such as quarter
, homeScore
, and awayScore
, which should correspond to the fields defined in the iOS app's ContentState
interface.
{
"event_updates": {
"quarter": 1,
"homeScore": 70,
"awayScore": 78,
"inTimeout": false
}
}
name
name
Required
Type: string
Description
An internal identifier used to assist with your campaign's organization and management. This value is not displayed to the end user and serves solely for tracking purposes within your campaign tracking and analytics.
Guidance
The name should be meaningful and indicate the campaign's purpose or target audience.
Example
{
"name": "Spring Sale Campaign"
}
contents
contents
Required
Type object
Description
The notification content that is displayed in the main body of the notification.
Guidance
Equivalent to the contents
parameter for Push Notifcations.
headings
headings
Type object
Description
The notification's title.
Guidance
Equivalent to the headings
parameter for Push Notifcations.
sound
sound
Type string
Specify a custom sound file to play when the notification is received instead of the default sound.
Guidance
Equivalent to the ios_sound
for Push Notifications.
stale_date
stale_date
Type: number
Description
A Unix timestamp (in seconds) indicates when the Live Activity is considered outdated. Once this time is reached, the system updates the Live Activity to ActivityState.stale
.
Guidance
Use this parameter to set an expiration time for the Live Activity, ensuring users do not see outdated information.
The Unix timestamp should be provided in seconds, representing the exact time the Live Activity should transition to a stale state.
Example
To set a stale date for January 1, 2025, at 00:00:00 UTC.
{
"stale_date": 1735689600
}
Refer to Apple's documentation to learn more about this paramater.
priority
priority
Type: number
Description
The priority level affects how quickly a notification is delivered and processed, particularly in power-saving modes.
Guidance
The priority
parameter determines the urgency and delivery behavior of the notification.
10
—Send the notification immediately. We recommend using this option while under development.5
—Send the notification based on the device's current power considerations, balancing timely delivery with power efficiency. We recommend using this option for the majority of your notifications, reserving10
for only the most critical messages.1
—Prioritize the device's power savings over immediate delivery. Notifications will not wake the device and get delivered when it is more power-efficient.- If the
priority
is omitted, APNS defaults to a priority of 10.
Example:
Send a notification with a balanced priority.
{
"priority": 5
}
For more detailed information, refer to Apple's official documentation on APNs Priority Levels.
ios_relevance_score
ios_relevance_score
Type: double
Description
A score you assign that determines the order in which your Live Activities appear when you start several Live Activities for your app.
Guidance
Higher scores make it more likely to be displayed when multiple activities are present.
Refer to Apple's documentation to learn more about this paramater.
idempotency_key
Type: string
Description
A unique identifier used to prevent duplicate Live Activities if the same request is retried. Recommended for apps not using the OneSignal SDK.
Guidance
Idempotency_key
is automatically handled when using the OneSignal SDK. Developers using the REST API directly should implement their own logic to generate and reuse this key on retries.