--- openapi: 3.0.3 info: title: Braze REST API – 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/). 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 operationId: post_messages_live_activity_update_update requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateLiveActivityRequest' 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 responses: "201": description: | The request was formatted correctly and accepted. No action needed. 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. content: application/json: schema: $ref: '#/components/schemas/MessagingLiveActivityUpdateResponse' examples: success: summary: Request accepted value: message: success "400": description: | Bad request. To resolve it: - **The request body isn't valid JSON:** Send valid JSON and set `Content-Type: application/json`. - **The `app_id` is missing, isn't a valid key for this workspace, or isn't an iOS app:** Pass a valid iOS `app_id` from the API Keys page. - **The `activity_id` is missing, isn't a string, or is 256 bytes or longer:** Pass `activity_id` as a string shorter than 256 bytes. - **The `content_state` isn't an object matching your app's Live Activity integration:** Pass `content_state` as an object matching the `ContentState` shape you defined. - **The `content_state` payload is too large:** Reduce the size of the `content_state` payload to under 4096 bytes. - **The `end_activity` value isn't a boolean:** Pass `end_activity` as `true` or `false`. - **The `stale_date` value can't be parsed:** Provide `stale_date` as an ISO-8601 datetime. - **The `dismissal_date` value can't be parsed:** Provide `dismissal_date` as an ISO-8601 datetime. - **The app doesn't have a valid push credential for Live Activities:** Add a valid APNs JWT (P8) credential for the app, then retry. 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_json: summary: The request body isn't valid JSON value: 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' " invalid_app_id: summary: Invalid app_id value: message: app_id must be a valid app api key for this app group invalid_activity_id: summary: Invalid activity_id value: message: "'activity_id' must be provided as a string and less than 256 bytes" invalid_content_state: summary: Invalid content_state value: message: "'content_state' must be a hash that matches your app's custom live activity integration" payload_too_large: summary: content_state payload too large value: message: Payload must be less than 4096 bytes invalid_end_activity: summary: end_activity isn't a boolean value: message: "'end_activity' must be a boolean" invalid_stale_date: summary: stale_date can't be parsed value: message: could not parse 'stale_date' invalid_dismissal_date: summary: dismissal_date can't be parsed value: message: could not parse 'dismissal_date' missing_credential: summary: Missing JWT/P8 credential value: message: The app must have valid JWT/P8 credential to use live activity "401": description: | Unauthorized. The REST API key is missing, malformed, or sent to the wrong REST endpoint. 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). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_api_key: summary: Invalid API key value: message: 'Invalid API key: YOUR_REST_API_KEY' "403": description: Access denied. The REST API key doesn't have the required permission. Use a REST API key that has the `messages.live_activity.update` permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: access_denied: summary: Missing permission value: message: Access Denied "429": description: | Rate limited. You exceeded the rate limit for this endpoint. Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: over_rate_limit: summary: Over rate limit value: message: You have exceeded your limit of 250000 requests per hour. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/. 5XX: description: | Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: REST API key description: | REST API keys are created in the Braze dashboard at **Settings → APIs and Identifiers → API Keys**. The key must include the `messages.live_activity.update` permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`. schemas: UpdateLiveActivityRequest: title: Update Live Activity request type: object required: - app_id - activity_id - content_state properties: app_id: type: string description: 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. example: "{YOUR-APP-API-IDENTIFIER}" activity_id: type: string description: | 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. example: live-activity-1 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. example: teamOneScore: 2 teamTwoScore: 4 end_activity: type: boolean description: If `true`, this request ends the Live Activity. example: false dismissal_date: type: string description: | 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. example: "2023-02-28T00:00:00+0000" stale_date: type: string description: | 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. example: "2023-02-27T16:55:49+0000" notification: type: object description: | 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. - If a `notification` is included and the user is active on their iPhone when the update is delivered, the updated Live Activity UI will slide down and display like a push notification. - If a `notification` is included and the user is not active on their iPhone, their screen will light up to display the updated Live Activity UI on their lock screen. - The `notification alert` will not display as a standard push notification. Additionally, if a user has a proxy device, like an Apple Watch, the `alert` will be displayed there. This push notification creates an alert for the user. example: alert: body: It's halftime! Let's look at the scores title: Halftime MessagingLiveActivityUpdateResponse: title: Update Live Activity response type: object properties: message: type: string example: success ErrorResponse: title: Error type: object properties: message: type: string description: Human-readable error message. error: type: string description: Error details, returned when the request body can't be parsed.