Update Live Activity
Update the content of a running iOS Live Activity or end it with the OneSignal REST API. Covers required body fields, update priority, and dismissal timing.
Overview
Update or terminate running iOS Live Activities using our REST API. This endpoint enables real-time content updates and activity termination, ensuring dynamic, context-aware user experiences. Before using this API, ensure your app is properly configured by following the Live Activities developer setup.How to use this API
Select the Live Activity
activity_id of the Live Activity you want to update in the URL. The activity_id is a topic key: this request fans out to every device registered under it, whether that is one user tracking their delivery or every user following the same live game. See Choose an activity ID.Devices register under an activity_id when you:- Start the activity with the Start Live Activity API
- Start the activity in-app while following the Live Activities developer setup
- Call the
LiveActivities.enterSDK method
Set the required body fields
event, event_updates, and name. Requests missing any of them return a 400 error.Choose whether to update or end the activity
event to update to change the content of a running Live Activity, or to end to terminate it. See Update a running Live Activity and End a Live Activity below.Update a running Live Activity
Setevent to update and set event_updates to a JSON object that matches the structure of the ActivityAttributes.ContentState struct defined in your Live Activity widget extension. Missing or mismatched fields can prevent the Live Activity from updating. Set name to an internal label for the message, up to 128 characters. Recipients never see the name.
Set priority to control urgency. 10 delivers immediately and counts against the budget Apple imposes per device for high-priority updates. 5 delivers opportunistically and does not count against the budget, so there is no limit on how many you send. When you omit priority, OneSignal sends 10 and spends budget, which is the most common reason apps hit throttling. Try 5 first and reserve 10 for updates that need the user’s immediate attention. See Update frequency and throttling.
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.End a Live Activity
Setevent to end to terminate the Live Activity. Include event_updates and name in this request as well, since both remain required.
- If you omit
dismissal_date, iOS keeps the Live Activity visible for up to 4 hours after the end event, then removes it. - Include a
dismissal_dateif you want the Live Activity dismissed in less than 4 hours. - Set
dismissal_dateto a Unix timestamp in the past to dismiss the Live Activity immediately. The user must have allowed the Live Activity for it to be removed programmatically.
FAQ
Why isn’t my Live Activity dismissing immediately?
Confirm thatdismissal_date is a Unix timestamp in seconds that is already in the past, such as 1663177260. If the timestamp is correct, the user may not have allowed the Live Activity, which iOS requires before an activity can be removed programmatically. A third possibility is that an earlier request already ended this activity_id, in which case the new request has no effect.
Does one request update every device?
Yes. Every device registered under thatactivity_id receives the update, so you do not target individual subscriptions when updating. That is why the activity_id should identify a topic, such as game-1234 for content everyone sees or order-98765 for content specific to one user. See Choose an activity ID.
Why did my request return a 400 error?
The most common cause is a missing required field.event, event_updates, and name are all required on every request, including requests that end the Live Activity.Path Parameters
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
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.
Body
The action to perform on the Live Activity. Options: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.
update, end 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.
An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.
The push message body with language-specific values.
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.
A Unix timestamp (in seconds) indicating when the Live Activity should be removed from user's device. Use with the end event. If not set, the Live Activity will be dismissed automatically after 4 hours. To dismiss the Live Activity immediately, the user must have allowed the Live Activity first. Then you can set a date that’s in the past — for example, 1663177260. Alternatively, provide a date within a four-hour window to set a custom dismissal date before the default 4 hour period. See Apple's documentation for more.
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.
5, 10 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.
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
The ID of the Live Activity update request.