Quick start

Start, show, update, and end a Live Activity.

Three things are needed:

A way to make HTTP requests (curl, a backend, a serverless function).
An API key. Create an account, choose a plan in the dashboard (Free works), then copy the key from Developer > API Key.
A phone: an iPhone on iOS 18 or later, or an Android phone with the WebActivity app.

Every call needs the API key in the x-api-key header. The key is secret: send requests from a backend, never from browser code.

Start the activity

Send the first state. Its layout sets the design (progress, picture, versus, or countdown). The widgetContainerId is required: any text that names this widget. Send the same value on every later call. brand.title names the activity in the app.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "pizza-tracker",
  "group": "order-tracker",
  "brand": {
    "title": "Order #1234"
  },
  "state": {
    "layout": "progress",
    "primaryText": "Preparing your order",
    "progress": 0.25
  }
}'

The response (201) gives the activityId, which every later call uses, and links.iframe, the launch button:

{
  "ok": true,
  "activityId": "act-8f2cqa4mx7rd",
  "userId": "act-8f2cqa4mx7rd",
  "group": "order-tracker",
  "widgetContainerId": "pizza-tracker",
  "links": {
    "iframe": "<iframe src=\"https://api.webliveactivity.com/embed/button?type=track&userId=act-8f2cqa4mx7rd\" width=\"340\" height=\"95\" style=\"border:0;color-scheme:light\"></iframe>"
  }
}

Open it on a phone

Paste links.iframe into a web page. It shows a Track With Live Activity button.

iPhone: a tap opens the app, or its App Clip with no install.
Android: a tap opens the WebActivity app, or Google Play to install it.
Computer: a click shows a QR code to scan with the phone.

The card then appears on the Lock Screen and in the Dynamic Island. No web page yet? Open the iframe's src URL in a computer browser and click the button. To change its color or use it on a dark page, see the launch button.

An activity belongs to the first phone that opens it. To give one button to many people, start with reuse: true. See one button, many phones.

Send updates

Send the activityId, its widgetContainerId, and only the fields that change. They merge into the saved state.

curl -X POST https://api.webliveactivity.com/api/update \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "activityId": "act-8f2cqa4mx7rd",
  "widgetContainerId": "pizza-tracker",
  "state": {
    "primaryText": "Out for delivery",
    "stage": "On the way",
    "progress": 0.7,
    "estimatedMinutes": 8
  }
}'

The card updates in place. Every update alerts the phone unless it is sent with priority: 5. Updates can take up to 45 seconds to arrive. See delivery and billing.

End it

End the activity when the job is done. The card is removed from the phone immediately, with no sound. To leave a final design on screen, send it as an update and end the activity later.

curl -X POST https://api.webliveactivity.com/api/end \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "activityId": "act-8f2cqa4mx7rd",
  "widgetContainerId": "pizza-tracker"
}'

Ending does not delete the activity. An update with restart: true brings the card back on the same phone.

Target a group

A group set on start labels activities. Send the group and its widgetContainerId, with no activityId, to update or end all of them in one call:

curl -X POST https://api.webliveactivity.com/api/update \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "group": "order-tracker",
  "widgetContainerId": "pizza-tracker",
  "state": {
    "secondaryText": "Kitchen is busier than usual"
  }
}'

Long-running activities

iOS stops taking normal updates 8 hours after a card starts. Start the activity with keepAlive: true and the service restarts the card every 7 hours, so it stays on the phone. Each of those restarts alerts. A countdown longer than 8 hours needs it to reach its alert. Without it, the next update after 8 hours is sent as a restart, which creates the card again and always alerts. To bring back a card the user swiped away, send an update with restart: true.

Get lifecycle callbacks

Add a webhook endpoint in the dashboard. The service calls it when an activity first appears on a phone, and when the user switches it off or deletes it in the app. See webhooks.

Change the layout

Send a new layout, with that layout's fields, in any update. The card changes to the new layout. See layouts.