ONonesignal

Update Live Activity

Update or terminate running iOS Live Activities using OneSignal's Live Activities API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences.

post/apps/{app_id}/live_activities/{activity_id}/notifications

Request

  • Base URL
    https://api.onesignal.com
  • URL
    https://api.onesignal.com/apps/{app_id}/live_activities/{activity_id}/notifications
  • Auth
    none required

Path parameters

app_idstring required

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

activity_idstring required

The topic key of the Live Activity to update, set when the activity started. This request fans out to every device registered under this value. See Choose an activity ID.

Headers

Content-Typestring required
Authorizationstring required

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

Request body

event'update' | 'end' required

The action to perform on the Live Activity. update updates the content of an existing Live Activity without ending it. end ends the Live Activity and removes it from the user's view. See Apple's developer docs on Starting and updating Live Activities.

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.

dismissal_dateinteger

A Unix timestamp (in seconds) indicating when the Live Activity should be removed from the user's device. Use with the end event. If not set, the Live Activity is dismissed automatically after 4 hours. To dismiss immediately, the user must have already allowed the Live Activity, then set a timestamp in the past (for example 1663177260). Alternatively, provide a date within a four-hour window to dismiss before the default 4-hour period. See Apple's documentation for more.

priority5 | 10

Set the urgency of this update. 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.

ios_soundstring

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

Response

201

idstring

The ID of the Live Activity update request.

Changes

No recorded changes to this operation across all 2 revisions of this API.