--- openapi: 3.0.3 info: title: Braze REST API – Update Live Activity description: 'Use this endpoint to update and end [Live Activities]({{site.baseurl}}/developer_guide/live_notifications/?sdktab=swift) displayed by your iOS app. This endpoint requires additional setup. ' version: 1.0.0 contact: name: Braze Support url: https://www.braze.com/docs/braze_support/ license: name: Braze Documentation url: https://www.braze.com/docs/api/home/ servers: - url: https://rest.iad-01.braze.com description: US-01 - url: https://rest.iad-02.braze.com description: US-02 - url: https://rest.iad-03.braze.com description: US-03 - url: https://rest.iad-04.braze.com description: US-04 - url: https://rest.iad-05.braze.com description: US-05 - url: https://rest.iad-06.braze.com description: US-06 - url: https://rest.iad-07.braze.com description: US-07 - url: https://rest.iad-08.braze.com description: US-08 - url: https://rest.us-10.braze.com description: US-10 - url: https://rest.fra-01.braze.eu description: EU-01 - url: https://rest.fra-02.braze.eu description: EU-02 - url: https://rest.au-01.braze.com description: AU-01 - url: https://rest.id-01.braze.com description: ID-01 - url: https://rest.jp-01.braze.com description: JP-01 - url: https://rest.kr-01.braze.com description: KR-01 security: - BearerAuth: [] paths: "/messages/live_activity/update": post: summary: Update Live Activity description: | ## Prerequisites To use this endpoint, you'll need to complete the following: - Generate an API key with the `messages.live_activity.update` permission. - Register a Live Activity [remotely]({{site.baseurl}}/developer_guide/live_notifications/?tab=remote&sdktab=swift) or [locally]({{site.baseurl}}/developer_guide/live_notifications/?tab=local&sdktab=swift) using the Braze Swift SDK. **Important:** The maximum request payload size is 4 MB. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/). ## Request body ```json { "app_id": "(required, string) App API identifier retrieved from the Developer Console.", "activity_id": "(required, string) When you register your Live Activity using launchActivity, you use the pushTokenTag parameter to name the Activity’s push token to a custom string. Set activity_id to this custom string to define which Live Activity you want to update.", "content_state": "(required, object) You define the ContentState parameters when you create your Live Activity. Pass the updated values for your ContentState using this object. The format of this request must match the shape you initially defined.", "end_activity": "(optional, boolean) If true, this request ends the Live Activity.", "dismissal_date": "(optional, datetime in ISO-8601 format) The time to remove the Live Activity from the user’s UI. If this time is in the past, the Live Activity will be removed immediately.", "stale_date": "(optional, datetime in ISO-8601 format) The time the Live Activity content is marked as outdated in the user’s UI.", "notification": "(optional, object ) Include an `apple_push` object to define a push notification that creates an alert for the user." } ``` ## Request parameters The following table lists the request parameters for this endpoint. | Parameter | Required | Data Type | Description | |---|---|---|---| | `app_id` | Required | String | App [API identifier]({{site.baseurl}}/api/identifier_types/#app-identifier) retrieved from the [API Keys]({{site.baseurl}}/user_guide/administer/global/workspace_settings/apis_and_identifiers/) page. | | `activity_id` | Required | String | When you register your Live Activity using [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class), you use the `pushTokenTag` parameter to name the Activity's push token to a custom string.

Set `activity_id` to this custom string to define which Live Activity you want to update. | | `content_state` | Required | Object | You define the `ContentState` parameters when you create your Live Activity. Pass the updated values for your `ContentState` using this object.

The format of this request must match the shape you initially defined. | | `end_activity` | Optional | Boolean | If `true`, this request ends the Live Activity. | | `dismissal_date` | Optional | Datetime
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter defines the time to remove the Live Activity from the user's UI. If this time is in the past and `end_activity` is `true`, the Live Activity will be removed immediately.

If `end_activity` is `false` or omitted, this parameter only updates the Live Activity.| | `stale_date` | Optional | Datetime
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter tells the system when the Live Activity content is marked as outdated in the user's UI. | | `notification` | Optional | Object | Include an [`apple_push`]({{site.baseurl}}/api/objects_filters/messaging/apple_object/) object to define a push notification. The behavior of this push notification depends on if the user is active or if the user is using a proxy device. | ## Example request ``` curl --location --request POST 'https://rest.iad-01.braze.com/messages/live_activity/update' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {YOUR-REST-API-KEY}' \ --data-raw '{ "app_id": "{YOUR-APP-API-IDENTIFIER}", "activity_id": "live-activity-1", "content_state": { "teamOneScore": 2, "teamTwoScore": 4 }, "end_activity": false, "dismissal_date": "2023-02-28T00:00:00+0000", "stale_date": "2023-02-27T16:55:49+0000", "notification": { "alert": { "body": "It's halftime! Let's look at the scores", "title": "Halftime" } } }' ``` ## Response There are two status code responses for this endpoint: `201` and `4XX`. ### Example success response A `201` status code is returned if the request was formatted correctly and we received the request. The status code `201` could return the following response body. ```json { "message": "success" } ``` ### Example error response The `4XX` class of status code indicates a client error. Refer to the [API errors and responses article]({{site.baseurl}}/api/errors/) for more information about errors you may encounter. The status code `400` could return the following response body. ```json { "error": "\nProblem:\n message body does not match declared format\nResolution:\n when specifying application/json as content-type, you must pass valid application/json in the request's 'body' " } ``` ## Response status codes The following table lists the responses for this endpoint, the error message you may receive, and how to resolve it. | Status code | Meaning | Error message | How to resolve | | --- | --- | --- | --- | | `201 Created` | The request was formatted correctly and accepted. | `success` | No action needed. | | `400 Bad Request` | The request body isn't valid JSON. | `message body does not match declared format` | Send valid JSON and set `Content-Type: application/json`. | | `400 Bad Request` | The `app_id` is missing, isn't a valid key for this workspace, or isn't an iOS app. | `app_id must be a valid app api key for this app group` | Pass a valid iOS `app_id` from the API Keys page. | | `400 Bad Request` | The `activity_id` is missing, isn't a string, or is 256 bytes or longer. | `'activity_id' must be provided as a string and less than 256 bytes` | Pass `activity_id` as a string shorter than 256 bytes. | | `400 Bad Request` | The `content_state` isn't an object matching your app's Live Activity integration. | `'content_state' must be a hash that matches your app's custom live activity integration` | Pass `content_state` as an object matching the `ContentState` shape you defined. | | `400 Bad Request` | The `content_state` payload is too large. | `Payload must be less than 4096 bytes` | Reduce the size of the `content_state` payload to under 4096 bytes. | | `400 Bad Request` | The `end_activity` value isn't a boolean. | `'end_activity' must be a boolean` | Pass `end_activity` as `true` or `false`. | | `400 Bad Request` | The `stale_date` value can't be parsed. | `could not parse 'stale_date'` | Provide `stale_date` as an ISO-8601 datetime. | | `400 Bad Request` | The `dismissal_date` value can't be parsed. | `could not parse 'dismissal_date'` | Provide `dismissal_date` as an ISO-8601 datetime. | | `400 Bad Request` | The app doesn't have a valid push credential for Live Activities. | `The app must have valid JWT/P8 credential to use live activity` | Add a valid APNs JWT (P8) credential for the app, then retry. | | `401 Unauthorized` | The REST API key is missing, malformed, or sent to the wrong REST endpoint. | `Invalid API key` | Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors). | | `403 Access Denied` | The REST API key doesn't have the required permission. | `Access Denied` | Use a REST API key that has the `messages.live_activity.update` permission. | | `429 Rate Limited` | You exceeded the rate limit for this endpoint. | `Over rate limit` | Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). | | `5XX Internal Server Error` | An unexpected error occurred on the Braze server. | `Internal Server Error` | Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). | operationId: post_messages_live_activity_update_update tags: - Messaging responses: '201': description: The request was formatted correctly and accepted. content: application/json: schema: $ref: '#/components/schemas/MessagingLiveActivityUpdateResponse' '400': description: |- Bad Request. Causes include: - `message body does not match declared format` — The request body isn't valid JSON. - `app_id must be a valid app api key for this app group` — The `app_id` is missing, isn't a valid key for this workspace, or isn't an iOS app. - `'activity_id' must be provided as a string and less than 256 bytes` — The `activity_id` is missing, isn't a string, or is 256 bytes or longer. - `'content_state' must be a hash that matches your app's custom live activity integration` — The `content_state` isn't an object matching your app's Live Activity integration. - `Payload must be less than 4096 bytes` — The `content_state` payload is too large. - `'end_activity' must be a boolean` — The `end_activity` value isn't a boolean. - `could not parse 'stale_date'` — The `stale_date` value can't be parsed. - `could not parse 'dismissal_date'` — The `dismissal_date` value can't be parsed. - `The app must have valid JWT/P8 credential to use live activity` — The app doesn't have a valid push credential for Live Activities. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: The REST API key is missing, malformed, or sent to the wrong REST endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: The REST API key doesn't have the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: You exceeded the rate limit for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '5XX': description: An unexpected error occurred on the Braze server. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: required: true content: application/json: schema: type: object properties: app_id: type: string description: App API identifier retrieved from the API Keys page. activity_id: type: string description: When you register your Live Activity using `launchActivity`, you use the `pushTokenTag` parameter to name the Activity's push token to a custom string. Set `activity_id` to this custom string to define which Live Activity you want to update. content_state: type: object description: You define the `ContentState` parameters when you create your Live Activity. Pass the updated values for your `ContentState` using this object. The format of this request must match the shape you initially defined. end_activity: type: boolean description: If `true`, this request ends the Live Activity. dismissal_date: type: string description: This parameter defines the time to remove the Live Activity from the user's UI. If this time is in the past and `end_activity` is `true`, the Live Activity will be removed immediately. If `end_activity` is `false` or omitted, this parameter only updates the Live Activity. stale_date: type: string description: This parameter tells the system when the Live Activity content is marked as outdated in the user's UI. notification: type: object description: Include an `apple_push` object to define a push notification. The behavior of this push notification depends on if the user is active or if the user is using a proxy device. required: - app_id - activity_id - content_state examples: example_request: summary: Example request value: app_id: "{YOUR-APP-API-IDENTIFIER}" activity_id: live-activity-1 content_state: teamOneScore: 2 teamTwoScore: 4 end_activity: false dismissal_date: '2023-02-28T00:00:00+0000' stale_date: '2023-02-27T16:55:49+0000' notification: alert: body: It's halftime! Let's look at the scores title: Halftime components: schemas: MessagingLiveActivityUpdateResponse: type: object properties: message: type: string ErrorResponse: type: object properties: error: type: string securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: REST API key