Introducing LiveActivityRead more

Guides / Live ActivitiesMenu

Live Activities

How starting, updating and ending Live Activities works, from your backend to the phone.

Updated · Markdown · Ask Claude · Ask ChatGPT

This is how the pieces work together. Setup is in the Quickstart, the exact requests are in the API reference.

The flow

  1. The app registers. The SDK (or Expo) reports the device’s push-to-start token and your user ID. The attributes struct has an optional lacId, which we fill in when we start the activity by push.
  2. Your backend starts it. POST /api/v1/activities with the user, the attributes type and the content state. Leave out startAt to start now. It is in milliseconds. We send push-to-start at that time to every device of the user (iOS 17.2+). On iOS 26, LiveActivity.schedule(…) in the app also schedules it on the device, and we push only if the device hasn’t reported it 60 seconds after startAt.
  3. Your backend updates and ends it. PATCH /api/v1/activities/act_… with a new content state, POST …/end to end it, DELETE … to cancel it before it starts.
  4. The phone reports back. The SDK tells us when the activity is on the phone, gets a new token, ends or is dismissed. We pass that to your backend as webhooks.
curl https://liveactivity.dev/api/v1/activities \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "appId": "<app id>",
    "userId": "user_42",
    "attributesType": "DeliveryAttributes",
    "attributes": { "orderId": "1234" },
    "contentState": { "eta": 15, "status": "cooking" },
    "startAt": 1795180000000,
    "alert": { "title": "Your order", "body": "Cooking now" }
  }'

What we take care of

  • Tokens. Every activity has its own update token, and the push-to-start token rotates. The SDK reports each new one, and devices that got their token late catch up on the latest state.
  • Payloads. Content state is checked against what your app’s ContentState sends (same keys, same JSON types) and against APNs’ 4 KB limit. A mismatch returns 422, where iOS would otherwise drop the update silently. Dates: Swift’s default Codable encodes Date as seconds since 2001, so send numbers your struct expects.
  • Budget. Updates go at priority 5. Only updates with an alert use priority 10, which counts against Apple’s hourly budget. Rapid updates collapse into the newest one.
  • Timeline. Activities shows every push, APNs answer and SDK report for each activity. See Troubleshooting.

Something not arriving? Start with Troubleshooting.