Path
app_id
app_id
Description
Identifies your application within our system.
Guidance
- The value must be a universally unique identifier (UUID).
- Refer to Keys & IDs to learn more.
activity_id
activity_id
Description
A self-generated identifier used to uniquely identify your Live Activity and associate devices with the event.
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 methodenterLiveActivity
. This linkage is necessary for the iOS SDK to handle and update the Live Activity correctly. - 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.
activity_type
activity_type
Required
Type: string
Description
Indicates which Live Activity to start.
Guidance
Use the name of the structure in the Live Activity file of your app that defines and manages the attributes and state of the Live Activity.
Body
event
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_attributes
event_attributes
Type: object
Description
The static data to initialize the Live Activity with.
Example
{
"event_attributes": {
"awayTeam": "Celtics",
"homeTeam": "Lakers"
}
}
event_updates
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
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
contents
Required
Type object
Description
The notification content that is displayed in the main body of the notification.
Guidance
Equivalent to the contents
parameter for Push Notifcations.
headings
headings
Type object
Description
The notification's title.
Guidance
Equivalent to the headings
parameter for Push Notifcations.
sound
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
stale_date
Type: number
Description
A Unix timestamp (in seconds) that indicates when the Live Activity is considered out of date. 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
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
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, reserving10
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.