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

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"
  }
}

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.

Integrations Using This Template

Home Assistant — configurable via the template option in entity config