Start Live Activity

Remotely start an iOS Live Activity with the OneSignal REST API, also known as push-to-start. Covers required body fields, choosing an activity_id, and audience targeting.

POST /apps/{app_id}/activities/activity/{activity_type}

cURL

cURL

curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/activities/activity/{activity_type} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event": "start",
  "activity_id": "<string>",
  "event_attributes": {},
  "event_updates": {},
  "name": "<string>",
  "contents": {
    "en": "<string>"
  },
  "headings": {
    "en": "<string>"
  },
  "include_aliases": {
    "external_id": [
      "<string>"
    ]
  },
  "include_subscription_ids": [
    "<string>"
  ],
  "included_segments": [
    "<string>"
  ],
  "excluded_segments": [
    "<string>"
  ],
  "filters": [
    {
      "field": "first_session",
      "relation": ">",
      "value": "1",
      "key": "<string>"
    }
  ],
  "stale_date": 123,
  "ios_sound": "<string>",
  "ios_relevance_score": 123,
  "idempotency_key": "<string>"
}
'

201

{
  "notification_id": "<string>"
}

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.

Before using this API, ensure your app is properly configured by following the Live Activities developer setup. Starting a Live Activity remotely requires iOS 17.2 or newer and OneSignal iOS SDK 5.2.0 or newer. On iOS 16.1 through 17.1, start Live Activities in-app instead.

---

How to use this API

1. Set the activity type in the URL

   Set activity_type to the name of the Live Activity attributes struct in your widget extension, such as OneSignalWidgetAttributes. The value is case-sensitive and must match your struct name exactly, or the request finds no recipients.

2. Set the required body fields

   This endpoint requires seven fields. Requests missing any of them return a 400 error.

   • event: The action to perform. This endpoint only supports start.
   • activity_id: The identifier you use later to update or end the activity. See Choose an activity ID.
   • event_attributes: The static data that initializes the activity. See Set event attributes.
   • event_updates: The dynamic data the activity displays. See Set event updates.
   • name: An internal label for the message, up to 128 characters. Recipients never see it.
   • contents: The push message body, with en at minimum.
   • headings: The push title, with en at minimum.

   This endpoint requires both contents and headings. On the Update Live Activity API, contents is optional and headings is not available.

3. Choose your target audience

   Include one targeting parameter, such as included_segments. Without one, the request has no recipients. See Choose your target audience.

4. Set optional delivery parameters

   Set stale_date to the Unix timestamp when the content becomes outdated, which lets your widget show a fallback message. Set ios_relevance_score to order multiple activities in the Dynamic Island.

   Set priority to 5 to deliver opportunistically without spending Apple’s high-priority budget, or 10 to deliver immediately at the cost of budget. When you omit priority, OneSignal sends 10. See Update frequency and throttling.

   This endpoint has no dismissal_date parameter. You set the dismissal time when you end the activity with the Update Live Activity API.

Choose an activity ID

The activity_id is a topic key, not a per-message identifier. Every device registered under the same activity_id receives the same updates, so one Update Live Activity request fans out to all of them. Save the value you choose, because you need it to update or end the activity later.

Pick the pattern that matches your use case:

• Shared topic: many users follow the same real-world event, such as a live game, election results, a flight status, or a service incident. Use one stable business identifier for all of them, such as game-1234. A single update request then reaches every subscriber. Avoid random IDs here, since they would force you to update each device’s activity separately.
• Per entity: each user follows their own activity, such as a food delivery, a ride, or an order. Give every activity its own identifier. A UUID, CUID, or NanoID works well, as does a namespaced business ID like order-98765.

Never reuse a per-entity activity_id across users. Because the activity_id is the fan-out key, every device registered under it receives the same content. Reusing a generic value like order-tracking for all orders would show one user’s delivery ETA on another user’s Lock Screen.

Example

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

Choose 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 Choose your target audience for more information.

Set event attributes to initialize the Live Activity

Set default/static data to display in the Live Activity upon start. The object must match the Attributes struct defined in your widget extension, excluding the ContentState and onesignal properties.

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 match the ContentState struct defined within your app’s Live Activity. See Live Activities developer setup.

Ensure that the event_updates object matches the ContentState struct exactly as defined in your Live Activity implementation. Inconsistencies can cause Live Activities to fail to display.

Send any Date-typed field in your custom Attributes or ContentState struct as a Unix timestamp in seconds, not as an ISO 8601 string and not in milliseconds. ActivityKit decodes date values in the push payload as seconds since 1970, and your app cannot change that strategy. To avoid the ambiguity, declare the field as a Double of Unix seconds and convert it in your widget. OneSignal’s stale_date and dismissal_date parameters are also Unix timestamps in seconds.

Example

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

---

FAQ

What is the difference between event_attributes and event_updates?

event_attributes is static data set once when the activity starts, matching your Attributes struct. event_updates is dynamic data matching your ContentState struct, and it is the only part you can change later with the Update Live Activity API.

Can one request start the same Live Activity for many users?

Yes. Target a segment or a list of aliases, and give every recipient the same activity_id when they should all see identical content, such as a live sports score. Each recipient gets their own activity on device, but a single update request then reaches all of them. Use distinct IDs when the content is specific to each user, such as an order status.

Why did my request return no recipients?

The activity_type in the URL must exactly match the name of your attributes struct, including casing, and your targeting must resolve to at least one subscribed device running iOS 17.2 or newer with OneSignal iOS SDK 5.2.0 or newer. See Troubleshooting: No recipients for the full checklist.

Can I set a dismissal time when starting the activity?

No. This endpoint has no dismissal_date parameter. Set dismissal_date when you end the activity with the Update Live Activity API. If you end an activity without one, iOS keeps it on the Lock Screen for up to 4 hours.

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

The topic key for this Live Activity. Every device that starts an activity with this value receives the same updates, so one Update Live Activity request fans out to all of them. Use one shared value when many users follow the same event, such as game-1234 for a live match. Use a distinct value per user when the content is specific to that user, such as order-98765 for one delivery. Never reuse a per-user value across users, or one user's content appears on every other user's device. Save the value, because updating or ending the activity requires it. See Choose an activity ID.

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<int32>

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 urgency of this start request. 10 delivers immediately and counts against the budget Apple imposes per device for high-priority Live Activity updates. 5 delivers opportunistically and does not count against the budget. When you omit this parameter, OneSignal sends 10. Apple recommends you try 5 first and reserve 10 for updates that need the user's immediate attention. If your app needs frequent high-priority updates, add the NSSupportsLiveActivitiesFrequentUpdates key to your Info.plist. See Update frequency and throttling.

Available options: 5, 10

ios_sound · string

The name of a sound file in your app bundle, including its extension (for example, explode_sound.wav), to play when this message is delivered. Omit this field to deliver it silently. See Notification sounds.

ios_relevance_score · number<double>

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. Any RFC 9562 UUID supported. 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.