Start Live Activity
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
- Define a Live Activity in your app. See Live Activities developer setup to get started.
- Use the
activity_type
parameter to specify the type of the Live Activity UI to use. - Select your target audience to receive the Live Activity. Target all or individual users.
- Generate a unique
activity_id
to track and manage your Live Activity. - Use the
event_attributes
parameter to initialize the Live Activity with static data. - 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:
- Aliases & Subscription IDs: Send messages to specific users using unique identifiers such as External ID (recommended), OneSignal ID, custom alias, or subscription ID.
- Segments: Target predefined user groups based on attributes and behavior.
- Filters: Create custom targeting rules using user properties, such as tags, location, or activity.
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 for more information.
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.Example
See Live Activities developer setup guide for more information.
Set event_attributes
to initialize the Live Activity
Set default/static data to display in the Live Activity upon start.
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.
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.
Headers
Your App API key with prefix Key
. See Keys & IDs.
Path Parameters
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
The name of the Live Activity defined in your app. This should match the your-nameAttributes
struct used in your app code. See Live Activities developer setup. Example: If your app defines a Live Activity as OneSignalWidgetAttributes
, then activity_type
should be OneSignalWidgetAttributes
.
Body
Response
201
The response is of type object
.