Skip to main content
POST
cURL

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

1

Select the Live Activity

Specify the 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:
2

Set the required body fields

Every request must include event, event_updates, and name. Requests missing any of them return a 400 error.
3

Choose whether to update or end the activity

Set 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

Set event 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.
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

End a Live Activity

Set event 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_date if you want the Live Activity dismissed in less than 4 hours.
  • Set dismissal_date to 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.
Once you end a Live Activity, you cannot update that activity_id again. Later requests to the same activity_id, including changes to dismissal_date or event, do not take effect.
Example

FAQ

Why isn’t my Live Activity dismissing immediately?

Confirm that dismissal_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 that activity_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.

Headers

Content-Type
string
default:application/json
required
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_id
string
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.

Body

application/json
event
enum<string>
required

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.

Available options:
update,
end
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

The push message body with language-specific values.

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.

dismissal_date
integer<int32>

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.

priority
enum<integer>

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.

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.

Response

201

id
string

The ID of the Live Activity update request.