Sign in

v1

latestOpenAPI 3.1.02026-07-26497885.9 KB

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.

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

Path parameters

app_idstring required

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

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

Headers

Authorizationstring required

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

Request body

include_subscription_idsstring[]

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_segmentsstring[]

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_segmentsstring[]

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.

event'start' required

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

activity_idstring 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_attributesobject required

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

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

namestring required

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

stale_dateinteger

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.

priority5 | 10

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.

ios_soundstring

The name of a sound file in your app bundle to play when the Live Activity receives an update. If excluded, the system plays the default notification sound. Using the value "nil" will silence the sound.

ios_relevance_scorenumber 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_keystring

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_idstring

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