--- openapi: 3.0.3 info: title: Braze REST API – Start Live Activity description: 'Use this endpoint to remotely start [Live Activities]({{site.baseurl}}/developer_guide/live_notifications/?sdktab=swift) displayed in 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/start": post: summary: Start Live Activity description: | ## Prerequisites To use this endpoint, you'll need to complete the following: - Generate an API key with the `messages.live_activity.start` permission. - [Create a Live Activity]({{site.baseurl}}/developer_guide/live_notifications/live_activities/?tab=local&sdktab=swift#create-an-activity) 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 The following sample request shows an example of how to start Live Activity. ```json { "app_id": "(required, string) App API identifier retrieved from the Developer Console.", "activity_id": "(required, string) Define a custom string as your `activity_id`. Use this ID to send update or end events to your Live Activity.", "activity_attributes_type": "(required, string) The activity attributes type you define within `liveActivities.registerPushToStart` in your app", "activity_attributes": "(required, object) The static attribute values for the activity type (such as the sports team names, which don't change)", "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.", "stale_date": "(optional, datetime in ISO-8601 format) The time the Live Activity content is marked as outdated in the user’s UI.", "notification": "(required, object) Include an `apple_push` object to define a push notification that creates an alert for the user, displayed on paired watchOS devices. Include `notification.alert.title` and `notification.alert.body`.", // Include one targeting method: // 1. "external_user_ids", "user_aliases", or both (combined maximum 50) // 2. "custom_audience" // 3. "segment_id" "external_user_ids": "(optional, array of strings) see external user identifier", "user_aliases": "(optional, array of user alias objects) see user alias object", "custom_audience": "(optional, connected audience object) see connected audience", "segment_id": "(optional, string) see segment identifier" } ``` ## 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 | Define a custom string as your `activity_id`. Use this ID to send update or end events to your Live Activity. | | `activity_attributes_type` | Required | String | The activity attributes type you define within `liveActivities.registerPushToStart` in your app. | | `activity_attributes` | Required | Object | The static attribute values for the activity type (such as the sports team names, which don't change). | | `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. | | `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` | Required | 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. | | `external_user_ids` | Optional if `user_aliases`, `segment_id`, or `custom_audience` is provided | Array of strings | See [external user ID]({{site.baseurl}}/api/objects_filters/user_attributes_object/#braze-user-profile-fields). | | `user_aliases` | Optional if `external_user_ids`, `segment_id`, or `custom_audience` is provided | Array of user alias objects | See [user alias object]({{site.baseurl}}/api/objects_filters/user_alias_object/). | | `segment_id` | Optional if `external_user_ids`, `user_aliases`, or `custom_audience` is provided | String | See [segment identifier]({{site.baseurl}}/api/identifier_types/). | | `custom_audience` | Optional if `external_user_ids`, `user_aliases`, or `segment_id` is provided | Connected audience object | See [connected audience]({{site.baseurl}}/api/objects_filters/connected_audience/). | ### Audience targeting behavior You can include `external_user_ids` and `user_aliases` in the same request. Their combined array length can't exceed 50. Braze targets users who match either parameter and sends only once when multiple identifiers resolve to the same user. Don't combine `external_user_ids` or `user_aliases` with `segment_id` or `custom_audience`. On this endpoint, use `custom_audience` to pass connected audience filters. When you target specific users, Braze starts a Live Activity only for `external_user_ids` and `user_aliases` that resolve to existing users. ## Example request The following sample request shows an example of how to start Live Activity. ```bash curl --location --request POST 'https://rest.iad-01.braze.com/messages/live_activity/start' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {YOUR_REST_API_KEY}' \ --data-raw '{ "app_id": "{YOUR-APP-API-IDENTIFIER}", "activity_id": "football-chiefs-bills-2024-01-21", "content_state": { "teamOneScore": 0, "teamTwoScore": 0 }, "activity_attributes_type": "FootballActivity", "activity_attributes": { "team1Name": "Chiefs", "team2Name": "Bills" }, "stale_date": "2024-01-22T16:55:49+0000", "notification": { "alert": { "body": "The game is starting! Tune in soon!", "title": "Chiefs v. Bills" } }, "external_user_ids": ["user-id1", "user-id2"], "user_aliases": [ { "alias_name": "user-name", "alias_label": "user-label" } ] }' ``` ## Response There are two status code responses for this endpoint: `201` and `4XX`. ### Example success response A `201` status code returns if the request is formatted correctly and Braze receives it. The status code `201` can 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 `activity_attributes_type` is missing or isn't a string. | `'activity_attributes_type' must be a String` | Pass `activity_attributes_type` as a string. | | `400 Bad Request` | The `activity_attributes` is missing or isn't an object. | `'activity_attributes' must be a Hash` | Pass `activity_attributes` as an object. | | `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 `stale_date` value can't be parsed. | `could not parse 'stale_date'` | Provide `stale_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. | | `400 Bad Request` | No audience was specified. | `One of 'external_user_ids', 'user_aliases', 'segment_id' or 'custom_audience' must be specified` | Include recipients (`external_user_ids`, `user_aliases`, or both), a `segment_id`, or a `custom_audience`. | | `400 Bad Request` | More than one audience type was specified. | `Only direct recipients ('external_user_ids' and/or 'user_aliases'), 'segment_id', or 'custom_audience' may be specified` | Use one audience type per request. You can combine `external_user_ids` and `user_aliases`, but don't pair either with `segment_id` or `custom_audience`. | | `400 Bad Request` | The `segment_id` isn't valid. | `Invalid 'segment_id'` | Pass a valid `segment_id`, or use a different audience type. | | `400 Bad Request` | The `external_user_ids` isn't an array of strings. | `'external_user_ids' must be an Array of type String` | Pass external user IDs as an array of strings. | | `400 Bad Request` | The `user_aliases` isn't an array of valid user alias objects. | `'user_aliases' must be an Array of objects containing String 'alias_name' and 'alias_label' fields` | Pass each user alias as an object with string `alias_name` and `alias_label` fields. | | `400 Bad Request` | The combined number of `external_user_ids` and `user_aliases` exceeds 50. | `Combined length of 'external_user_ids' and 'user_aliases' exceeds the limit of 50` | Keep the combined total of `external_user_ids` and `user_aliases` at 50 or fewer. | | `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.start` 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_start_start tags: - Messaging responses: '201': description: The request was formatted correctly and accepted. content: application/json: schema: $ref: '#/components/schemas/MessagingLiveActivityStartResponse' '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. - `'activity_attributes_type' must be a String` — The `activity_attributes_type` is missing or isn't a string. - `'activity_attributes' must be a Hash` — The `activity_attributes` is missing or isn't an object. - `'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. - `could not parse 'stale_date'` — The `stale_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. - `One of 'external_user_ids', 'user_aliases', 'segment_id' or 'custom_audience' must be specified` — No audience was specified. - `Only direct recipients ('external_user_ids' and/or 'user_aliases'), 'segment_id', or 'custom_audience' may be specified` — More than one audience type was specified. - `Invalid 'segment_id'` — The `segment_id` isn't valid. - `'external_user_ids' must be an Array of type String` — The `external_user_ids` isn't an array of strings. - `'user_aliases' must be an Array of objects containing String 'alias_name' and 'alias_label' fields` — The `user_aliases` isn't an array of valid user alias objects. - `Combined length of 'external_user_ids' and 'user_aliases' exceeds the limit of 50` — The combined number of `external_user_ids` and `user_aliases` exceeds 50. 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: Define a custom string as your `activity_id`. Use this ID to send update or end events to your Live Activity. activity_attributes_type: type: string description: The activity attributes type you define within `liveActivities.registerPushToStart` in your app. activity_attributes: type: object description: The static attribute values for the activity type (such as the sports team names, which don't change). 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. 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. external_user_ids: type: array items: type: string description: See external user ID. Combined with `user_aliases`, a maximum of 50 identifiers per request. user_aliases: type: array items: type: object description: See user alias object. Combined with `external_user_ids`, a maximum of 50 identifiers per request. segment_id: type: string description: See segment identifier. custom_audience: type: object description: See connected audience. required: - app_id - activity_id - activity_attributes_type - activity_attributes - content_state - notification components: schemas: MessagingLiveActivityStartResponse: type: object properties: message: type: string ErrorResponse: type: object properties: error: type: string securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: REST API key