Braze Messaging > Live Activities API

openapi: 3.0.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. When Radar geofence or trip tracking events are generated, custom events and user attributes are sent to Braze in real-time. These events and attributes can then be used to trigger location-based campaigns, power last-mile pickup and delivery operations, monitor fleet and shipping logistics, or build user segments based on location patterns. '
  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](https://www.braze.com/docs/developer_guide/platform_integration_guides/swift/live_activities/live_activities/) displayed by your iOS app. This endpoint requires additional setup. \n  \n\nTo use this endpoint, youll need to generate an API key with the `messages.live_activity.update` permission.\n\nBefore using this endpoint, you must register an activity with the Braze Swift SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method. Required request parameters will be defined during this step. Refer to [Live Activities](https://www.braze.com/docs/developer_guide/platform_integration_guides/swift/live_activities/live_activities/) for more information on registration.\n\nOnce 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](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications) for more information.\n\n> **Tip:** For help with CSV and API exports, visit [Export troubleshooting](https://www.braze.com/docs/user_guide/data_and_analytics/export_braze_data/export_troubleshooting/). \n  \n\n## Rate limit\n\nWe apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.\n\n## Request parameters\n\n| Parameter | Required | Data Type | Description |\n| --- | --- | --- | --- |\n| `app_id` | Required | String | App [API identifier]({{site.baseurl}}/api/identifier_types/#the-app-identifier) retrieved from **Settings > Setup and Testing > API Keys.** |\n| `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.  <br>  <br>Set `activity_id` to this custom string to define which Live Activity you want to update. |\n| `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.  <br>  <br>The format of this request must match the shape you initially defined. |\n| `end_activity` | Optional | Boolean | If `true`, this request ends the Live Activity. |\n| `dismissal_date` | Optional | Datetime  <br>([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, the Live Activity will be removed immediately. |\n| `stale_date` | Optional | Datetime  <br>([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. |\n| `notification` | Optional | Object | <br><br>  <br>  <br>  <br>  <br>  <br>  <br>Include an [`apple_push`]({{site.baseurl}}/api/objects_filters/messaging/apple_object/) 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}  <br>  <br>  <br>  <br><br><ul><li><p>If a <code>notification</code> 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.</p></li><li><p>If a <code>notification</code> 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.</p></li><li><p>The <code>notification alert</code> will not display as a standard push notification. Additionally, if a user has a proxy device, like an Apple Watch, the <code>alert</code> will be displayed there.</p></li></ul><br><br> |\n\n## Response\n\nThere are two status code responses for this endpoint: `201` and `4XX`.\n\n### Example success response\n\nA `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.\n\n``` json\n{\n  \"message\": \"success\"\n}\n\n```\n\n### Example error response\n\nThe `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.\n\nThe status code `400` could return the following response body.\n\n``` json\n{\n    \"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' \"\n}\n\n```"
      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'
components:
  responses:
    Forbidden:
      description: 403 Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 401 Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: 429 Rate Limited
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: 404 Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: 400 Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: 500 Internal Server Error
      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