--- openapi: 3.0.3 info: title: Braze REST API – 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/). 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: | ## 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. operationId: post_messages_live_activity_start_start requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartLiveActivityRequest' examples: specific_users: summary: Start a Live Activity for specific users value: 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 responses: "201": description: | The request was formatted correctly and accepted. No action needed. 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. content: application/json: schema: $ref: '#/components/schemas/MessagingLiveActivityStartResponse' 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 `activity_attributes_type` is missing or isn't a string:** Pass `activity_attributes_type` as a string. - **The `activity_attributes` is missing or isn't an object:** Pass `activity_attributes` as an object. - **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 `stale_date` value can't be parsed:** Provide `stale_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. - **No audience was specified:** Include recipients (`external_user_ids`, `user_aliases`, or both), a `segment_id`, or a `custom_audience`. - **More than one audience type was 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`. - **The `segment_id` isn't valid:** Pass a valid `segment_id`, or use a different audience type. - **The `external_user_ids` isn't an array of strings:** Pass external user IDs as an array of strings. - **The `user_aliases` isn't an array of valid user alias objects:** Pass each user alias as an object with string `alias_name` and `alias_label` fields. - **The combined number of `external_user_ids` and `user_aliases` exceeds 50:** Keep the combined total of `external_user_ids` and `user_aliases` at 50 or fewer. 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_activity_attributes_type: summary: Invalid activity_attributes_type value: message: "'activity_attributes_type' must be a String" invalid_activity_attributes: summary: Invalid activity_attributes value: message: "'activity_attributes' must be a Hash" 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_stale_date: summary: stale_date can't be parsed value: message: could not parse 'stale_date' missing_credential: summary: Missing JWT/P8 credential value: message: The app must have valid JWT/P8 credential to use live activity missing_audience: summary: No audience specified value: message: One of 'external_user_ids', 'user_aliases', 'segment_id' or 'custom_audience' must be specified multiple_audience_types: summary: More than one audience type value: message: Only direct recipients ('external_user_ids' and/or 'user_aliases'), 'segment_id', or 'custom_audience' may be specified invalid_segment_id: summary: Invalid segment_id value: message: Invalid 'segment_id' invalid_external_user_ids: summary: Invalid external_user_ids value: message: "'external_user_ids' must be an Array of type String" invalid_user_aliases: summary: Invalid user_aliases value: message: "'user_aliases' must be an Array of objects containing String 'alias_name' and 'alias_label' fields" too_many_recipients: summary: More than 50 direct recipients value: message: Combined length of 'external_user_ids' and 'user_aliases' exceeds the limit of 50 "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.start` 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.start` permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`. schemas: UserAlias: title: User alias type: object required: [alias_name, alias_label] properties: alias_name: type: string example: user-name alias_label: type: string example: user-label StartLiveActivityRequest: title: Start Live Activity request type: object description: | Include one targeting method: 1. `external_user_ids`, `user_aliases`, or both (combined maximum 50) 2. `custom_audience` 3. `segment_id` required: - app_id - activity_id - activity_attributes_type - activity_attributes - content_state - notification 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: Define a custom string as your `activity_id`. Use this ID to send update or end events to your Live Activity. example: football-chiefs-bills-2024-01-21 activity_attributes_type: type: string description: The activity attributes type you define within `liveActivities.registerPushToStart` in your app. example: FootballActivity activity_attributes: type: object description: The static attribute values for the activity type (such as the sports team names, which don't change). example: team1Name: Chiefs team2Name: Bills 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: 0 teamTwoScore: 0 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: "2024-01-22T16: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, displayed on paired watchOS devices. Include `notification.alert.title` and `notification.alert.body`. example: alert: body: The game is starting! Tune in soon! title: Chiefs v. Bills external_user_ids: type: array items: type: string description: | Optional if `user_aliases`, `segment_id`, or `custom_audience` is provided. See [external user ID]({{site.baseurl}}/api/objects_filters/user_attributes_object/#braze-user-profile-fields). Combined with `user_aliases`, a maximum of 50 identifiers per request. example: - user-id1 - user-id2 user_aliases: type: array items: $ref: '#/components/schemas/UserAlias' description: | Optional if `external_user_ids`, `segment_id`, or `custom_audience` is provided. See [user alias object]({{site.baseurl}}/api/objects_filters/user_alias_object/). Combined with `external_user_ids`, a maximum of 50 identifiers per request. segment_id: type: string description: Optional if `external_user_ids`, `user_aliases`, or `custom_audience` is provided. See [segment identifier]({{site.baseurl}}/api/identifier_types/). custom_audience: title: Connected audience object type: object description: Optional if `external_user_ids`, `user_aliases`, or `segment_id` is provided. See [connected audience]({{site.baseurl}}/api/objects_filters/connected_audience/). MessagingLiveActivityStartResponse: title: Start 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.