Start Live Activity

Use this endpoint to remotely start Live Activities displayed in your iOS app. This endpoint requires additional setup.

After you create a Live Activity, you can make a POST request to remotely start your activity for a segment, a connected audience, or specific external user IDs. For more information about Apple’s Live Activities, see Starting and updating Live Activities with ActivityKit push notifications.

If content-available isn’t set, the default Apple Push Notification service (APNs) priority is 10. If content-available is set, this priority is 5. Refer to Apple push object for more details.

tip

To end a Live Activity, use the /messages/live_activity/update endpoint with end_activity set to true.

Arranging automatic dismissal

To arrange automatic dismissal after a Live Activity starts, schedule a follow-up request to the update endpoint from your backend.

1. Send a /messages/live_activity/start request with an activity_id you can reuse later.
2. Store that activity_id and your target end time in your backend scheduler.
3. At the target end time, send a /messages/live_activity/update request with end_activity set to true.
4. Configure dismissal behavior in the same update request. For details, see the /messages/live_activity/update endpoint.
5. Verify send and outcome events in the Message Activity Log.

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 using the Braze Swift SDK.

important

If the final rendered payload is larger than the corresponding service’s maximum allowed size, the send won’t be successful.

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 body

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "app_id": "(required, string) App API identifier retrieved from the Developer Console.",
  "activity_id": "(required, string) Define a custom string as your `activity_id`. You will use this ID when you wish 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. Should include `notification.alert.title` and `notification.alert.body`",
  // One of the following:
  "external_user_ids": "(optional, array of strings) see external user identifier, maximum 50",
  "custom_audience": "(optional, connected audience object) see connected audience",
  "segment_id": "(optional, string) see segment identifier"
}

Request parameters

On this endpoint, pass connected audience filters in custom_audience.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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"
        }
    },
    // One of the following required:
    "segment_id": "{YOUR-SEGMENT-API-IDENTIFIER}", // Optional
    "custom_audience": {...}, // Optional
    "external_user_ids": ["user-id1", "user-id2"], // Optional
}'

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.

1
2
3
{
  "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.

1
2
3
{
    "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' "
}