Server REST API Reference
Log InSign Up

Update Live Activity

post https://api.onesignal.com/apps//live_activities//notifications

Make updates and terminate running Live Activities.

How to Use this API

To use this API, ensure your iOS application is configured correctly to support Live Activities by following the Live Activities Setup guide. Once you've successfully launched your Live Activity on the device using our SDK, you may begin updating Live Activities started from the device or remotely using a pushToStartToken token.

Pick a Live Activity to update

Select which Live Activity to update by specifying its Activity ID in the URL. This is simple if your application only has one Live Activity or when the Live Activity is started remotely using Start Live Activity, It's either the identifier you passed to the LiveActivities.enter SDK method or the activity_id specified in your request. Otherwise, determine which Live Activity to update via its associated Activity ID.

For example, given the following code to launch an Activity:

OneSignal.LiveActivities.enter("bos_vs_dal_2024_09_05", withToken: token)

The Activity ID is bos_vs_dal_2024_09_05.

Provide new state

Use the event_updates parameter to specify a JSON object that matches the structure of the ActivityAttributes.ContentState struct defined in your Live Activity widget extension.

For example, given the following ActivityAttributes.ContentState struct:

public struct ContentState: Codable, Hashable {
  var homeScore: Int
  var awayScore: Int
  var quarter: Int
}

Update the state of a Live Activity by setting the event_updates to:

{
  "homeScore": 0,
  "homeScore": 3,
  "quarter": 1
}

The event_updates and ActivityAttributes.ContentState must match, or the Live Activity will silently fail to launch.

Path Parameters

activity_id

Description

A self-generated identifier is used to uniquely identify your Live Activity.

Guidance

  • Generate a unique activity_id to track and manage your 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.
  • Provide this activity_id when calling the iOS SDK method enterLiveActivity. This linkage is necessary for the iOS SDK to correctly handle and update the Live Activity.
  • Ensure that the activity_id is unique and consistently used for each Live Activity to avoid conflicts and ensure accurate tracking.

💡

Refer to this guide to learn more about starting and updating Live Activities.

Body Parameters

event

Required

Type: string

Description

The action to perform on the Live Activity.

Guidance

Set to one of the following values:

  • "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.

Example

Update an existing Live Activity:

{
  "event": "update"
}

💡

Refer to Apple's official documentation on Live Activities for comprehensive guidance on managing Live Activities.


event_updates

Type: object

Description

The content to update a running Live Activity with. The object must conform to the ContentState interface defined within your app's Live Activity.

Guidance

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

In this example, the object includes fields such as quarter, homeScore, and awayScore, which should correspond to the fields defined in the iOS app's ContentState interface. 

{
  "event_updates": {
    "quarter": 1,
    "homeScore": 70,
    "awayScore": 78,
    "inTimeout": false
  }
}

name

Required

Type: string

Description

An internal identifier used to assist with your campaign's organization and management. This value is not displayed to the end user and serves solely for tracking purposes within your campaign tracking and analytics.

Guidance

The name should be meaningful and indicate the campaign's purpose or target audience.

Example


{
  "name": "Spring Sale Campaign"
}

contents

Required

Type object

Description

The notification content is displayed in the main body of the notification.

Guidance

Equivalent to the contents parameter for Push Notifcations.

headings

Type object

Description

The notification's title.

Guidance

Equivalent to the headings parameter for Push Notifcations.

sound

Type string

Specify a custom sound file to play when the notification is received instead of the default sound.

Guidance

Equivalent to the ios_sound for Push Notifications.

stale_date

Type: number

Description

A Unix timestamp (in seconds) that indicates when the Live Activity is considered outdated. Once this time is reached, the system updates the Live Activity to ActivityState.stale.

Guidance
Use this parameter to set an expiration time for the Live Activity, ensuring users do not see outdated information.
The Unix timestamp should be provided in seconds, representing the exact time the Live Activity should transition to a stale state.

Example

To set a stale date for January 1, 2025, at 00:00:00 UTC.

{
  "stale_date": 1735689600
}

💡

Refer to Apple's documentation to learn more about this paramater.

dismissal_date

Type: number

Description

The Unix timestamp (in seconds) at which the Live Activity will be terminated and removed from users' lock screens.

Guidance

This parameter lets you control when the Live Activity should be automatically removed from the lock screen, ensuring timely updates and removing irrelevant information.

  • By default, the Live Activity is dismissed after 4 hours.
  • Provide the Unix timestamp in seconds.
  • This parameter is only effective when event is set to "end".

Example:

To set a dismissal date for January 1, 2025, at 12:00:00 UTC.

{
  "dismissal_date": 1735723200
}

💡

Refer to Apple's documentation to learn more about this paramater.

priority

Type: number

Description

The priority level affects how quickly a notification is delivered and processed, particularly in power-saving modes.

Guidance

The priority parameter determines the urgency and delivery behavior of the notification.

  • 10—Send the notification immediately. We recommend using this option while under development.
  • 5—Send the notification based on the device's current power considerations, balancing timely delivery with power efficiency. We recommend using this option for the majority of your notifications, reserving 10 for only the most critical messages.
  • 1—Prioritize the device's power savings over immediate delivery. Notifications will not wake the device and get delivered when it is more power-efficient.
  • If the priority is omitted, APNS defaults to a priority of 10.

Example:

Send a notification with a balanced priority.

{
  "priority": 5
}

💡

For more detailed information, refer to Apple's official documentation on APNs Priority Levels.

Language