Use this endpoint to start a Live Activity on one or more customers' devices. The activity appears on the Lock Screen and in the Dynamic Island, and updates in real time until you end it.

API at a glance

Description: Live Activities show a card that follows an event as it happens, such as an order on its way, an offer counting down, or a match in progress. This endpoint starts the activity. Use the Update a Live Activity endpoint to change its content or end it.

The activity is identified by bsftActivityId, which you set inside activity_attributes. Reuse that same identifier to update or end the activity.

Authentication & testing - Live Activities

Authorization: Basic encoded\_value

Postman collection

Try it with Postman: Explore the API using Blueshift's Postman collection.

Things to know before you start

• Set a unique bsftActivityId for each activity. It goes inside activity_attributes, and you reuse it to update or end the activity. Starting a second activity with an ID that is already running creates a duplicate card on the device.
• content_state property names must match your app. They must exactly match the ContentState your app defines. A mismatch is not reported as an error: the API returns a success response and the device discards the content.
• activity_attributes_type must match the name your app registers. This is the name passed to registerPushToStart in your app.
• A 200 response means the push was dispatched, not displayed. Check dispatched_to and the errors array in the response. A dispatched_to of 0 means no device received the message.
• You can include up to 50 customer identifiers per call. More than 50 returns a 413 Payload Too Large error.
• Apple limits apply. A device shows a maximum of 5 Live Activities per app, and the total push payload must stay under 4 KB. Activities and payloads beyond these limits are not delivered.

Request parameters

Example requests & responses

  curl --request POST \
       --url https://api.getblueshift.com/api/v1/live_activity/start \
       --header 'accept: application/json' \
       --header 'authorization: Basic YWNlZDZlNGYxMWExYWVhOTZmNTJkNDg4M2ZmMjI4Mjg6' \
       --header 'content-type: application/json' \
       --data '
  {
    "customer_identifier_type": "email",
    "customer_identifiers": ["[email protected]"],
    "activity_attributes_type": "DeliveryActivityAttribute",
    "activity_attributes": {
      "bsftActivityId": "order_4482",
      "activityName": "Order #4482"
    },
    "content_state": {
      "title": "Order confirmed",
      "subtitle": "Preparing your order",
      "progress": 0.2
    },
    "notification": {
      "title": "Order #4482",
      "body": "Your order is confirmed"
    }
  }
  '

{
  "status": "ok",
  "dispatched_to": 1,
  "errors": []
}

{
  "status": "ok",
  "dispatched_to": 0,
  "errors": [
    {
      "customer_identifier_type": "email",
      "customer_identifier_value": "[email protected]",
      "error_message": "No user found for given identifier"
    }
  ]
}

Field reference