# iOS Live Activities API
> Apple documentation:
>
> * [About Live Activities](https://developer.apple.com/design/human-interface-guidelines/live-activities)
> * [Updating and ending Live Activities with ActivityKit push notifications](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications)
## 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](/developer/api-reference/api-identifiers/#application-code) |
| auth | String | Required | [API access token](/developer/api-reference/api-identifiers/#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 | Fallback content for devices running iOS versions below 16.1 that do not support Live Activity. On iOS 16.1+ (with Live Activity support), content is sourced from the `live_activity` field. |
| title | String | Optional | The title of the notification message. |
| 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](/developer/api-reference/api-identifiers/#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](/developer/api-reference/api-identifiers/#push-token). 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. |
### Request example
```json
{
"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": "FIRST_LIVE_ACTIVITY",
"filter": "FILTER_NAME_1"
}
]
}
}
```
```json
{
"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": "SECOND_LIVE_ACTIVITY",
"devices": ["first_third", "second_device"]
}
]
}
}
```
```json
{
"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
```json
{
"status_code": 200,
"status_message": "OK",
"response": {
"Messages": [
"XXXXX-XXXXXXXX-XXXXXXXX"
]
}
}
```
> **Note:**
>
> Read [this article](/developer/pushwoosh-sdk/ios-sdk/ios-live-activities) 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](/developer/api-reference/api-identifiers/#api-access-token) from the Pushwoosh Control Panel. |
| application | String | Required | [Pushwoosh application code](/developer/api-reference/api-identifiers/#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. |
| 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.|
### Request example
```json
{
"request": {
"application": "XXXXX-XXXXX",
"auth": "SECRET_API_TOKEN",
"notifications": [
{
"live_activity": {
"event": "update",
"title": "Live Activity Update",
"content-state": {
"status": "second 66",
"estimatedTime": "66 min",
"emoji": "👨"
},
"relevance-score": 60
},
"live_activity_id": "FIRST_LIVE_ACTIVITY"
}
]
}
}
```
### Response example
```json
{
"status_code": 200,
"status_message": "OK",
"response": {
"Messages": [
"XXXXX-XXXXXXXX-XXXXXXXX"
]
}
}
```
> [Read this article](/developer/pushwoosh-sdk/ios-sdk/ios-live-activities/) to learn more about working with Live Activities using the Pushwoosh iOS SDK.
## 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.