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

1. Define a Live Activity in your app. See 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.

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

  {
    "activity_id": "217aae2b-42ee-4097-bc3f-b7a6e9d15b9b",
    ...
  }
  

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.

Example

{
  "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.

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

{
  "event_updates": {
    "quarter": 1,
    "homeScore": 70,
    "awayScore": 78,
    "inTimeout": false
  }
}

---

Headers

Authorization · string · default: Key YOUR_APP_API_KEY · required

Your App API key with prefix Key. See Keys & IDs.

Path Parameters

app_id · string · required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

activity_type · string · required

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

application/json

event · enum<string> · default: start · required

The action to perform on the Live Activity. This request only supports start.

Available options:

start

activity_id · string · required

An identifier you set when starting the Live Activity to uniquely identify it and associated devices with the event. Save this value because it is required for the Update Live Activity API. Consider using a UUID, CUID, or NanoID for this parameter.

event_attributes · object · required

The static data to initialize the Live Activity. See Live Activities developer setup.

event_updates · object · required

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.

name · string · required

An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.

contents · object · required

The push message body with language-specific values.

Show child attributes

headings · object · required

The push title with language-specific values.

Show child attributes

include_aliases · object

Target up to 20,000 users by their external_id, onesignal_id, or your own custom alias. Use with target_channel to control the delivery channel. Not compatible with any other targeting parameters like filters, include_subscription_ids, included_segments, or excluded_segments. See Sending messages with the OneSignal API.

Show child attributes

include_subscription_ids · string[]

Target users' specific subscriptions by ID. Include up to 20,000 subscription_id per API call. Not compatible with any other targeting parameters like filters, include_aliases, included_segments, or excluded_segments. See Sending messages with the OneSignal API.

included_segments · string[]

Target predefined Segments. Users that are in multiple segments will only be sent the message once. Can be combined with excluded_segments. Not compatible with any other targeting parameters like filters, include_aliases, or include_subscription_ids. See Sending messages with the OneSignal API.

excluded_segments · string[]

Exclude users in predefined Segments. Overrides membership in any segment specified in the included_segments. Not compatible with any other targeting parameters like filters, include_aliases, or include_subscription_ids. See Sending messages with the OneSignal API.

filters · object[]

Dynamically target users based on properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and OR operators. Not compatible with other targeting parameters like include_aliases, include_subscription_ids, included_segments, or excluded_segments. See Sending messages with the OneSignal API.

Show child attributes

stale_date · integer

A Unix timestamp (in seconds) that indicates the date the Live Activity is considered outdated. Once this time is reached, the system updates the Live Activity to ActivityState.stale at which point you can update the Live Activity to indicate that its content is out of date.

priority · enum<integer>

Set the priority based on the urgency of the message. 10 - High priority. 5 - Normal priority. Apple allows a certain budget of High priority updates per hour. Exceeding the budget may throttle your messages. Apple recommends choosing a mix of priority 5 and 10 to prevent throttling. If your app needs more frequent updates, use NSSupportsLiveActivitiesFrequentUpdates entry as directed in Apple's Developer Docs.

Available options:

5,

10

ios_relevance_score · number

A value between 0 and 1. If you start more than one Live Activity for your app, the Live Activity with the highest relevance score appears in the Dynamic Island. If Live Activities have the same relevance score, the system displays the Live Activity that started first. Additionally, the Relevance Score determines the order of your Live Activities on the Lock Screen.

idempotency_key · string

A unique identifier used to prevent duplicate messages from repeat API calls. See Idempotent notification requests. Must be a v3 or v4 UUID. Valid for 30 days. Previously called external_id.

Response

201

application/json

201

notification_id · string

The ID of the Live Activity that was created in UUID v4 format.