Skip to main content
POST
/
apps
/
{app_id}
/
activities
/
activity
/
{activity_type}
Start Live Activity
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,
  "priority": 5,
  "ios_relevance_score": 123,
  "idempotency_key": "<string>"
}
'
{
  "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.

​
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.

​
headings
object
required

The push title with language-specific values.

​
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.

​
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.

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

​
notification_id
string

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