Countdown Template

A timer-based template with server-managed lifecycle. Set it and forget it -- the server handles warning and completion pushes automatically.

Fields

Field	Type	Description
`template`	string	Required. Must be `"countdown"`
`progress`	float	Required. Initial progress (usually `0.0`)
`duration`	string	Required (or `end_date`). Server-side convenience — converted to `end_date` before reaching the device. Accepts: `"30s"`, `"5m"`, `"1h30m"`, or plain seconds (`"1500"`)
`end_date`	integer	Required (or `duration`). Unix timestamp when the countdown expires
`start_date`	integer	Unix timestamp when the countdown began. Must be less than `end_date`. Used to compute progress on-device.
`warning_threshold`	integer	Seconds before `end_date` to send a warning push (accent turns orange)
`completion_message`	string	Text shown when countdown expires (default: "Completed")
`state`	string	Status text (e.g. "Baking", "Printing")
`icon`	string	SF Symbol name or MDI icon with `mdi:` prefix (e.g. `"mdi:timer-outline"`)
`subtitle`	string	Secondary text
`accent_color`	string	Named color or hex
`background_color`	string	Background color override
`text_color`	string	Text color override
`alarm`	boolean	Opt-in: schedule an iOS AlarmKit alarm at `end_date` that rings through silent mode and Focus. iOS 26+ only. See Ringing an Alarm on Completion.

Example Payload

Start a countdown

{
  "state": "ongoing",
  "content": {
    "template": "countdown",
    "progress": 0.0,
    "state": "Baking",
    "icon": "flame",
    "subtitle": "25 min timer",
    "duration": "25m",
    "warning_threshold": 60,
    "completion_message": "Done baking!",
    "accent_color": "orange",
    "alarm": true
  }
}

Auto-Managed Lifecycle

After starting a countdown, the server automatically manages the remaining lifecycle:

You send the start push -- sets ended -> ongoing with the countdown content
Server sends warning push -- when warning_threshold seconds remain, the server automatically sends an update with accent_color: "orange"
Server sends completion push -- when end_date is reached, the server sends an end push with completion_message and progress: 1.0

ℹ Info

The countdown timer display on the device is computed from start_date and end_date, so it counts down in real-time without needing additional pushes.

💡 Tip

Only the initial start push is required. You don't need to send any follow-up requests -- the server handles everything automatically.

Buttons & tap targets

Accepts url_action, secondary_url_action, and tap_action — tap_action is useful for deep-linking back into the timer's source app while it runs. See Tap actions for the action object shape.

Ringing an Alarm on Completion

Setting alarm: true (as shown above) schedules an iOS AlarmKit alarm at end_date. The alarm rings through silent mode and Focus -- like a native Clock alarm -- alongside the Live Activity countdown, with built-in Dismiss and Snooze (5 min) controls.

ℹ Info

Requires iOS 26+ and user authorization on first use. Once set, the alarm persists across partial updates until you clear it with {"content":{"alarm":null}} in a PATCH body, or a transition to ended. See Alarms for details.

Integrations Using This Template

Home Assistant — configurable via the template option in entity config