iOS Live Activities API

Apple documentation:

• About Live Activities
• Updating and ending Live Activities with ActivityKit push notifications

To let a Customer Journey Live Activity point build its content-state form from field names instead of a raw JSON editor, publish a schema for your attributes-type — see the Live Activity Schemas API.

startLiveActivity

POST https://api.pushwoosh.com/json/1.3/startLiveActivity

Allows creating iOS Live Activities.

Request body

Parameter	Type	Required/Optional	Description
application	String	Required	Pushwoosh application code
auth	String	Required	API access token from the Pushwoosh Control Panel.
notifications	Array	Required	JSON array of message parameters. See details in the Notifications table below.

Notifications

Parameters used in the notifications array:

Parameter	Type	Required/Optional	Description
content	String	Required*	Alert body for the push that starts the Live Activity, and the fallback text shown on devices running iOS versions below 16.1.
title	String	Required*	Alert title for the push that starts the Live Activity.
live_activity	Object	Required	Live Activity data to create Live Activity in iOS.
live_activity.content-state	Object	Required	Content for the Live Activity notification.
live_activity.attributes-type	String	Required	The type of attributes used in the Live Activity.
live_activity.attributes	Object	Required	Attributes for the Live Activity.
live_activity_id	String	Required	A unique identifier for the Live Activity. Used to target this activity when calling updateLiveActivity. Must be unique per activity session.
filter	String	Optional	The name of a Pushwoosh filter (segment). See Segment / Filter name. The Live Activity will be started on all devices matching this filter.
devices	Array of Strings	Optional	A list of device tokens. The Live Activity will be started only on the specified devices.
send_date	String	Optional	Schedules the push that starts the Live Activity for a specific date and time — works with either filter or devices targeting. Use format YYYY-MM-DD HH:mm, or now to start immediately (this is also the default when the parameter is omitted). Must be no more than 1 day in the past or 30 days in the future, otherwise the request is rejected with a validation error.
timezone	String	Optional	The timezone used to interpret send_date. If omitted, send_date is interpreted in UTC.
apns_priority	Integer	Optional	Controls the APNs delivery priority for this Live Activity push. Accepts 10 (high priority, delivered with the apns-priority: 10 header for instant rendering on a locked screen) or 5 (low priority, delivered with apns-priority: 5 to conserve device battery). Any other value is treated as 5, with no validation error. Every Live Activity push defaults to priority 5 regardless of whether it carries alert content (content/title) — set apns_priority: 10 explicitly to request high-priority delivery. See Time Sensitive Push and delivery priority below.

Note: * At least one of content or title must be non-empty. Pushwoosh rejects a start request where both are empty.

Caution

Remote start of a Live Activity via startLiveActivity requires iOS 17.2+ on the device — earlier versions do not support the pushToStartTokenUpdates API that this endpoint relies on. See Start Live Activity with a Remote push notification.

When targeting a filter (segment), the scheduled send time is when Pushwoosh starts dispatching the push, not a guaranteed delivery instant — for large audiences, delivery to individual devices can lag behind send_date by a few minutes, since the send rate for Live Activity pushes can’t be customized with send_rate.

Repeated push-to-start calls exhaust silently. After roughly ten starts in quick succession, Apple stops delivering the underlying push-to-start notification without any error, and startLiveActivity still returns 200. During campaign testing this looks like “the API works but nothing happens on the device.” Space out consecutive test starts.

Request example

With filter

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1"
      }
    ]
  }
}

With devices

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "SECOND_LIVE_ACTIVITY",
        "devices": ["first_third", "second_device"]
      }
    ]
  }
}

Scheduled start

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "THIRD_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1",
        "send_date": "2026-06-16 16:00"
      }
    ]
  }
}

Response example

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

Note:

Read this article to learn more about working with Live Activities using the Pushwoosh iOS SDK.

updateLiveActivity

POST https://api.pushwoosh.com/json/1.3/updateLiveActivity

Allows updating and ending iOS Live Activities

Request body

Parameter	Type	Required/Optional	Description
auth	String	Required	API access token from the Pushwoosh Control Panel.
application	String	Required	Pushwoosh application code
notifications	Array	Required	JSON array of message parameters. See details in the Notifications table below.

Notifications

Parameters used in the notifications array:

Parameter	Type	Required/Optional	Description
live_activity	Object	Required	Live Activity data to update Live Activity in iOS.
live_activity.event	String	Required	Specifies the event type. Use "update" to update the Live Activity or "end" to close it.
live_activity.content-state	Object	Required	Object with key-value pairs used to pass data to Live Activity for updating its content.
live_activity.dismissal-date	Integer	Optional	The time (in seconds) when the Live Activity should end. On an end, omit this to leave the card showing its final content-state until iOS retires it on its own — see the note below. Set a date in the past to remove the card as soon as this update arrives instead.
live_activity_id	String	Required	The unique identifier of the Live Activity to update. Must match the live_activity_id used in startLiveActivity. The update will be delivered to all devices on which this activity was started.
live_activity.relevance-score	Integer	Optional	Tells the iOS system which Live Activity has higher priority than others. Accepts values from 1 to infinity (values up to 100 are recommended).
live_activity.stale-date	Integer	Optional	The time (in seconds) that represents the date at which a Live Activity becomes stale, or out of date.
apns_priority	Integer	Optional	Controls the APNs delivery priority for this Live Activity push. Accepts 10 (high priority, delivered with the apns-priority: 10 header for instant rendering on a locked screen) or 5 (low priority, delivered with apns-priority: 5 to conserve device battery). Any other value is treated as 5, with no validation error. Every Live Activity push defaults to priority 5 regardless of whether it carries alert content (content/title) — set apns_priority: 10 explicitly to request high-priority delivery. See Time Sensitive Push and delivery priority below.
content	String	Optional	Alert body for this update. The common case is a content-state-only update, which sets none of content, title, or subtitle and carries no alert at all.
title	String	Optional	Alert title for this update. Setting content, title, or subtitle triggers an alert and lets ios_sound play. With none of the three set, the update stays silent, which is the default for content-state-only updates.
subtitle	String	Optional	Alert subtitle for this update. Same alert-triggering role as content/title above.
ios_sound	String	Optional	Sound file name in the app’s main bundle. It rides inside aps.alert alongside content/title/subtitle, not the top-level aps.sound, which ActivityKit ignores for Live Activities, so it only plays when this update also sets at least one of those three. iOS also rate-limits Live Activity alerts on its own. The same payload has been observed to arrive with sound on one delivery and without it on the next, on both device and Simulator.

Note: relevance-score only affects the display order among multiple active Live Activities on the same device — it does not affect delivery urgency. Use apns_priority to control how urgently an update is delivered.

Note

An end with no dismissal-date doesn’t remove the card. It stays on the Lock Screen showing whatever content-state this update sent, and Apple’s own Live Activity system retires it on its own within up to 4 hours.

Request example

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "apns_priority": 10,
        "title": "Live Activity Update",
        "live_activity": {
          "event": "update",
          "content-state": {
            "status": "second 66",
            "estimatedTime": "66 min",
            "emoji": "👨‍"
          },
          "relevance-score": 60
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY"
      }
    ]
  }
}

Response example

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

Read this article to learn more about working with Live Activities using the Pushwoosh iOS SDK.

Time Sensitive Push and delivery priority

By default, Apple delivers Live Activity updates at low priority (apns-priority: 5) to conserve battery. When a device is locked, a low-priority update is processed in the background and only becomes visible on the Lock Screen once the user unlocks the device. On an already-unlocked device it still renders instantly. Use the apns_priority parameter described above to request high-priority (apns-priority: 10) delivery so the update renders on the Lock Screen immediately, without unlocking.

Not related to the Time Sensitive Push toggle

The Time Sensitive Push toggle in the Pushwoosh Control Panel sets the interruption-level for standard push notifications only. It has no effect on Live Activity delivery priority sent through this API — Live Activities use a separate delivery path, controlled exclusively by the apns_priority request parameter.

Even with apns_priority: 10 available, Apple caps how often it can be used.

APNs high-priority budget

Apple limits how many high-priority (apns-priority: 10) pushes an app can send per hour. For frequently updated activities (e.g. live scores), reserve apns_priority: 10 for critical events and use apns_priority: 5 or fewer updates for routine changes. Enabling NSSupportsLiveActivitiesFrequentUpdates in your app’s Info.plist (see the iOS SDK guide) raises this budget for high-frequency use cases.

Multiple activities per device

You can start multiple Live Activities on the same device by calling startLiveActivity several times with different live_activity_id values.

For example, if you start two activities: FIRST_LIVE_ACTIVITY with filter: FILTER_NAME_1 and SECOND_LIVE_ACTIVITY with filter: FILTER_NAME_2, a device that matches both filters will have both activities running simultaneously.

To update one of them, pass its live_activity_id to updateLiveActivity. The update is delivered to all devices where that activity was created. The other activity is not affected.

The relevance-score parameter controls display priority when multiple Live Activities are active on the same device. If screen space is limited or activities are grouped, the activity with a higher value is shown with higher priority.