POST /api/update

Change what one or more activities show.

Send only the fields that change. They merge into the saved state, so a call with just primaryText leaves everything else alone. See the state object.

Targets

Every call includes the widgetContainerId and one of:

activityId: one activity.
activityIds: a list of activities.
group: every activity in the group.

If none of the named ids exist in the container, the call answers 404. A group with no activities answers 200 with targeted: 0.

By activity id

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": "acme-orders",
  "state": {
    "primaryText": "Out for delivery",
    "stage": "On the way",
    "progress": 0.7,
    "estimatedMinutes": 8
  }
}'

By multiple activity ids

curl -X POST https://api.webliveactivity.com/api/update \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "activityIds": [
    "act-8f2cqa4mx7rd",
    "act-9k4d2bwh6tne"
  ],
  "widgetContainerId": "acme-orders",
  "state": {
    "secondaryText": "Running behind schedule"
  }
}'

By group

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": "acme-orders",
  "state": {
    "secondaryText": "Kitchen is busy tonight"
  }
}'

Response

targeted is how many activities the update was sent to. unknown lists ids that were not found in this container.

{
  "ok": true,
  "targeted": 3,
  "unknown": []
}

Examples

Quiet update

Every update alerts the phone, with primaryText as the title and secondaryText as the body. priority takes 10 (the default) or 5. Send priority: 5 for a quiet update: no alert on iPhone, no sound on Android. Any other value counts as 10. For timing and billing, see delivery and billing.

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": "acme-orders",
  "priority": 5,
  "state": {
    "progress": 0.8,
    "estimatedMinutes": 4
  }
}'

Advance segmented steps

Send the full segments list with new complete values. The list is replaced, not merged.

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": "On the way",
    "segments": [
      {
        "label": "Cooking",
        "complete": true
      },
      {
        "label": "On the way",
        "complete": false
      },
      {
        "label": "Delivered",
        "complete": false
      }
    ]
  }
}'

Update a versus score

The versus object merges one level down, so only send what changed.

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": "csgo-scores",
  "state": {
    "versus": {
      "leftScore": "16",
      "rightScore": "14",
      "activeSide": "left",
      "leftStatus": "Winner"
    }
  }
}'

Change the layout

Send a new layout with that layout's fields. The card changes type.

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": "acme-orders",
  "state": {
    "layout": "countdown",
    "primaryText": "Ready for pickup",
    "secondaryText": "Pickup closes in",
    "countdownTo": 1795046400,
    "completionText": "Pickup closed"
  }
}'

Restart a card

A restart creates the card again instead of changing it in place. A restart always alerts and ignores priority. An update is sent as a restart when:

it has restart: true,
it adds a new image URL (the iPhone must download the image first), or
the card started more than 8 hours ago (iOS stops taking normal updates after 8 hours).

Use restart: true to bring back a card the user swiped away, or one that was ended. A normal update cannot. With no state, the card restarts with its 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": "acme-orders",
  "restart": true
}'

Keep image URLs the same between calls. A URL with a changing query string counts as a new image and restarts the card on every update.