Notifications

TaskMate has a full notification system with built-in notification types, per-recipient routing, custom scheduled notifications, actionable mobile callbacks, and bus events for power users.

Overview

Event occurs (chore completed, streak at risk, bedtime, badge earned)
    │
    ├─ Check notification type is enabled (master toggle)
    ├─ Check recipient routing matrix
    ├─ Check time gate (if applicable)
    │
    ├─ Send persistent HA notification
    ├─ Send push notification (per recipient's notify service)
    ├─ Fire bus event (taskmate_* event)
    │
    └─ Actionable notifications include Approve/Reject buttons (mobile)

Built-in Notification Types

TaskMate ships with these built-in notification types:

Type	ID	Audience	Time-Gated	Actionable	Default
Bedtime Reminder	`bedtime_reminder`	Children	Yes (per-recipient time)	No	Off
Streak at Risk	`streak_at_risk`	Children	Yes (global cutoff)	No	Off
All Chores Done	`all_chores_done`	Both	No	No	Off
Badge Earned	`badge_earned`	Both	No	No	On
Pending Chore Approval	`pending_chore_approval`	Parents	No	Yes	On
Pending Reward Claim	`pending_reward_claim`	Parents	No	Yes	On
Streak Milestone	`streak_milestone`	Both	No	No	Off
Level Up	`level_up`	Both	No	No	Off
Celebration	`celebration`	Both	No	No	Off
Weekly Digest	`weekly_digest`	Parents	No	No	Off

Bedtime Reminder

Sends a reminder to children who still have incomplete chores. Each recipient can have their own bedtime — e.g. 19:30 for younger children, 20:30 for older ones.

Streak at Risk

Alerts children who haven't completed a chore today and are at risk of losing their streak. Uses a global cutoff time (configurable in the recipient matrix).

All Chores Done

Fires immediately when a child finishes every chore assigned to them for the day.

Badge Earned

Fires when a child earns a new achievement badge (auto or manual). See Achievement Badges.

Pending Chore Approval

Sent to parent recipients when a child completes a chore that requires approval. Includes Approve and Reject action buttons on mobile.

Pending Reward Claim

Sent to parent recipients when a child claims a reward. Includes Approve and Reject action buttons on mobile.

Streak Milestone

Fires when a child reaches a streak milestone (e.g. a 3-, 7-, 14-day streak) and is awarded the milestone bonus. The bonus itself has always been granted; this type announces it. Off by default — enable it on the Notifications tab. One notification fires per newly reached milestone. Milestone days/bonuses come from the Streak Milestones setting (see Bonus Points).

Level Up

Fires when a child gains an XP level. Off by default. See Levels and XP.

Celebration

A single, tier-scaled notification for notable moments (level-ups, completed quests/challenges, and similar). It is opt-in and only sent when the moment meets a minimum tier:

Enable the celebration_notify setting to turn it on.
celebration_notify_min_tier (default 2) sets the smallest tier that notifies (1 = small, 2 = medium, 3 = epic).

The matching taskmate_celebration bus event always fires regardless of this notification (see Celebrations).

Weekly Digest

A Sunday-evening recap sent to parents summarising each child's week. Off by default. See Weekly Digest for the schedule, contents and configuration.

Notification Messages

Each built-in type has a fixed message template:

Type	Message
Bedtime Reminder	`"{child_name}, you still have chores to do before bedtime."`
Streak at Risk	`"{child_name}, complete a chore today to keep your {streak}-day streak!"`
All Chores Done	`"{child_name} finished every chore today!"`
Badge Earned	`"{child_name} earned the {badge_name} badge!"`
Pending Chore Approval	`"{child_name} completed '{chore_name}' (+{points} {points_name}) — awaiting approval."`
Pending Reward Claim	`"{child_name} claimed '{reward_name}' ({cost} {points_name}) — awaiting approval."`
Streak Milestone	`"{child_name} hit a {days}-day streak — +{points} {points_name}!"`
Level Up	`"{child_name} reached level {level}! 🎉"`
Celebration	`"🎉 {message}"`
Weekly Digest	`"TaskMate weekly digest:\n{summary}"`

Testing a Notification

To confirm that a notification type is routed correctly without waiting for the real trigger, use the test notification feature. It sends a sample message to that type's enabled recipients ignoring the master on/off toggle, so you can verify routing before you switch the type on. The sample message is prefixed with [TEST] and filled with placeholder data (child "Alex", chore "Tidy room", and so on). A test send does not fire a bus event.

Each notification type row in the Admin Panel → Notifications tab has a Send test button. You can also call the service directly:

action: taskmate.test_notification
data:
  type_id: streak_milestone

Field	Required	Description
`type_id`	Yes	Notification type id, e.g. `pending_chore_approval`, `badge_earned`, `streak_milestone`

A persistent notification is also created for the test, the same as a real send.

Actionable Notifications (Mobile)

The pending_chore_approval and pending_reward_claim types send actionable notifications via the HA Companion app. The notification includes two tap actions:

Approve — approve the pending item directly from the notification
Reject — reject the pending item

Action identifiers follow the format TASKMATE_APPROVE_{entry_id} and TASKMATE_REJECT_{entry_id}.

Requirement: The HA Companion app must be installed on the parent's device and the notify service must be a mobile_app service.

Graceful Fallback for Non-mobile_app Backends

Tap actions only render in the HA Companion app. Other notify backends — Telegram, email, SMS, and so on — silently ignore them. Rather than send dead buttons to those recipients, TaskMate detects a non-mobile_app notify service and instead appends a hint to the message:

Open the TaskMate panel to approve or reject.

In addition, a persistent notification is always created in Home Assistant for every notification type (see Persistent Notifications below), so even a recipient with no usable push backend has a way to act from the HA sidebar.

The notify service must be in the notify.* domain; other domains are rejected and logged.

Recipients

TaskMate supports two types of notification recipients:

Child Recipients

Each child in TaskMate is automatically a recipient. Their notify service can be configured in the admin panel's Notifications tab (e.g. notify.mobile_app_noahs_tablet). Children only receive notifications from types with audience child or both.

Parent Recipients

Parents are added manually in the Notifications tab. Each parent recipient has:

Field	Description
Name	Display name (e.g. "Dad")
Notify Service	HA notify service (e.g. `notify.mobile_app_dads_phone`)
Enabled	Master on/off toggle

Parents only receive notifications from types with audience parent or both.

Recipient Routing Matrix

The routing matrix controls which recipients get which notification types. It is configured in the Admin Panel → Notifications → Recipient Matrix.

The matrix is a table with:

Rows = notification types (6 built-in)
Columns = recipients (all children + all parent recipients)
Cells = enable/disable checkbox per type per recipient

Additional per-type settings in the matrix:

Bedtime Reminder: per-recipient time input (each child can have a different bedtime)
Streak at Risk: global cutoff time input (one time for all recipients)

Cells that don't apply (e.g. a child column for a parent-audience type) show a dash and are not interactive.

Master Toggle

Each notification type has a master enable/disable toggle. When disabled, the notification does not fire for any recipient regardless of individual routing.

Custom Notifications

Parents can create their own scheduled notifications for anything not covered by the built-in types.

Custom Notification Fields

Field	Description
Name	Display name (e.g. "Homework Reminder")
Message Template	Text with `{child_name}` and `{time}` placeholders
Time	Scheduled dispatch time in `HH:MM` format
Day Mask	Which days of the week this notification fires (Mon–Sun toggles)
Recipients	Which children and/or parents receive it
Enabled	On/off toggle

Creating a Custom Notification

Open the Admin Panel → Notifications tab
Scroll to the Custom Notifications section
Click Add Custom Notification
Fill in the name, message template, time, days, and recipients
Save

Example Use Cases

"Pack your bag!" — 19:00 on school nights (Mon–Thu) to children
"Lunch boxes?" — 07:00 on weekdays to a parent
"Weekend chore time!" — 10:00 on Sat/Sun to all children

Bus Events

Every notification fires a Home Assistant bus event, even if the master toggle is off (in which case the recipients list will be empty). Power users can use these in their own automations.

Notification-Type Event Names

Each notification type fires a matching taskmate_<type_id> event:

Event	Fired When
`taskmate_bedtime_reminder`	Bedtime reminder dispatched
`taskmate_streak_at_risk`	Streak at risk alert dispatched
`taskmate_all_chores_done`	Child finished all chores
`taskmate_badge_earned`	Badge awarded to a child
`taskmate_pending_chore_approval`	Chore completion awaiting approval
`taskmate_pending_reward_claim`	Reward claim awaiting approval
`taskmate_streak_milestone`	Streak milestone reached
`taskmate_level_up`	Child gained an XP level
`taskmate_celebration`	A notable moment (level-up, quest/challenge complete, …)
`taskmate_weekly_digest`	Weekly digest dispatched
`taskmate_custom_notification`	Custom notification dispatched

Event Data

Notification-type events include all context keys for the notification type (e.g. child_name, chore_name, points) plus recipients — a list of recipient IDs that were actually sent to. A test_notification send does not fire a bus event.

Custom notification events include:

id — custom notification ID
name — custom notification name
recipients — list of recipient IDs

Other Automation Events (v4.0.0)

TaskMate also fires events for penalties, bonuses and reward/chore approvals so you can build your own automations even when no notification is configured. These are not routed through the notification system and carry no recipients field:

Event	Fired When
`taskmate_penalty_applied`	A penalty was applied to a child
`taskmate_bonus_applied`	A bonus was applied to a child
`taskmate_reward_approved`	A reward claim was approved
`taskmate_reward_rejected`	A reward claim was rejected
`taskmate_chore_rejected`	A chore completion was rejected

See Automations for the full event reference and example automations.

Automation Example

alias: Log chore approvals to Discord
triggers:
  - trigger: event
    event_type: taskmate_pending_chore_approval
actions:
  - action: notify.discord_webhook
    data:
      message: >
        {{ trigger.event.data.child_name }} completed
        '{{ trigger.event.data.chore_name }}'
        (+{{ trigger.event.data.points }} {{ trigger.event.data.points_name }})

Persistent Notifications

Regardless of routing configuration, TaskMate always creates a persistent notification in Home Assistant for pending chore approvals and pending reward claims. These appear in the notification bell in the HA sidebar and are automatically dismissed once you approve or reject the item.

Binary Sensor

binary_sensor.taskmate_has_pending_approvals turns on when there are unapproved chore completions or reward claims. Use it in your own automations for fully custom notification logic.

Attributes:

pending_chore_completions — count of pending chore approvals
pending_reward_claims — count of pending reward claims
total_pending — combined total

Migration from Pre-v3.9.0

If you previously used the single Notification Service setting in the config flow, that setting still works but is now supplemented by the full notification system. For the best experience:

Open the Admin Panel → Notifications tab
Add yourself as a Parent Recipient with your notify service
Configure the routing matrix to your preferences
The old Notification Service setting in the config flow continues to work as a fallback

Multiple Parents / Devices

Unlike the old single-service setting, the v3.9.0 notification system natively supports multiple parents:

Add each parent as a Parent Recipient in the Notifications tab
Set each parent's notify_service to their device (e.g. notify.mobile_app_dads_phone, notify.mobile_app_mums_phone)
Enable/disable specific notification types per parent in the routing matrix

Notifications

Overview

Built-in Notification Types

Bedtime Reminder

Streak at Risk

All Chores Done

Badge Earned

Pending Chore Approval

Pending Reward Claim

Streak Milestone

Level Up

Celebration

Weekly Digest

Notification Messages

Testing a Notification

Actionable Notifications (Mobile)

Graceful Fallback for Non-mobile_app Backends

Recipients

Child Recipients

Parent Recipients

Recipient Routing Matrix

Master Toggle

Custom Notifications

Custom Notification Fields

Creating a Custom Notification

Example Use Cases

Bus Events

Notification-Type Event Names

Event Data

Other Automation Events (v4.0.0)

Automation Example

Persistent Notifications

Binary Sensor

Migration from Pre-v3.9.0

Multiple Parents / Devices

Related

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!