Braze Messaging > Live Activities API

openapi: 3.2.0
info:
  title: Braze Messaging > Live Activities API
  description: The Braze and Radar integration allows you to access sophisticated location-based campaign triggers and user profile enrichment with rich, first-party location data.
  version: 1.0.0
servers:
- url: https://rest.iad-01.braze.com
  description: REST endpoint for instance US-01
- url: https://rest.iad-01.braze.com
  description: REST endpoint for instance US-01
- url: https://rest.iad-02.braze.com
  description: REST endpoint for instance US-02
- url: https://rest.iad-03.braze.com
  description: REST endpoint for instance US-03
- url: https://rest.iad-04.braze.com
  description: REST endpoint for instance US-04
- url: https://rest.iad-05.braze.com
  description: REST endpoint for instance US-05
- url: https://rest.iad-06.braze.com
  description: REST endpoint for instance US-06
- url: https://rest.iad-08.braze.com
  description: REST endpoint for instance US-08
- url: https://rest.fra-01.braze.eu
  description: REST endpoint for instance EU-01
- url: https://rest.fra-02.braze.eu
  description: REST endpoint for instance EU-02
security:
- BearerAuth: []
tags:
- name: Messaging > Live Activities
paths:
  /messages/live_activity/update:
    post:
      tags:
      - Messaging > Live Activities
      summary: Update Live Activity
      description: '> Use this endpoint to update and end Live Activities displayed by your iOS app. This endpoint requires additional setup.


        To use this endpoint, youll need to generate an API key with the `messages.live_activity.update` permission.


        Before using this endpoint, you must register an activity with the Braze Swift SDK using the `launchActivity`) method. Required request parameters will be defined during this step. Refer to Live Activities for more information on registration.


        Once you have registered your activity, pass a JSON payload with updates to the Apple Push Notification service (APNs) through this endpoint. See Apples documentation on updating your Live Activity with push notification payloads for more information.


        > **Tip:** For help with CSV and API exports, visit Export troubleshooting.


        ## Rate limit


        We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.


        ## Request parameters


        | Parameter | Required | Data Type | Description |

        | --- | --- | --- | --- |

        | `app_id` | Required | String | App API identifier retrieved from **Settings > Setup and Testing > API Keys.** |

        | `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

        (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, the Live Activity will be removed immediately. |

        | `stale_date` | Optional | Datetime

        (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` object to define a push notification. This behavior of this push notification depends on if the user is active or if the user is using a proxy device. {::nomarkdown}


        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.


        |


        ## 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 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'' "

        }


        ```'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                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
              properties:
                app_id:
                  type: string
                activity_id:
                  type: string
                content_state:
                  type: object
                  properties:
                    teamOneScore:
                      type: integer
                    teamTwoScore:
                      type: integer
                end_activity:
                  type: boolean
                dismissal_date:
                  type: string
                  format: date-time
                stale_date:
                  type: string
                  format: date-time
                notification:
                  type: object
                  properties:
                    alert:
                      type: object
                      properties:
                        body:
                          type: string
                        title:
                          type: string
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer {{api_key}}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      operationId: postMessagesLiveActivityUpdate
      x-operation-id-source: derived
components:
  responses:
    Unauthorized:
      description: 401 Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: 400 Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: 404 Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: 403 Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: 500 Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: 429 Rate Limited
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
        errors:
          type: array
          items:
            type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer