Skip to content

Configuration: Notifications

Jump to bottom
ccpk1 edited this page Feb 16, 2026 · 6 revisions

Notifications Overview

The KidsChores integration sends mobile notifications through Home Assistant's companion app to keep kids and parents informed about chore activity, reward claims, and gamification milestones.

Notification Events & Recipients

The integration sends 21 different notification types across 4 categories:

Chore Notifications

Event Trigger Recipients Example Text (Kid/Parent) Actionable Auto-Clear
Chore Claimed Kid presses claim button Parents "Sarah: Chore Claimed" / "Claimed Make Bed for review. Worth 10 points" Yes - Approve/Disapprove/Remind Yes - On approve/disapprove/undo
Chore Approved Parent approves claimed chore Kid "🎉 Chore Approved!" / "Make Bed approved! You earned 10 points" No Yes - Clears parent claim notifications
Chore Disapproved Parent disapproves claimed chore Kid "↩️ Chore Returned" / "Make Bed needs more work." No Yes - Clears parent claim notifications
Chore Overdue Chore past due date Kid + Parents Kid: "⏰ Chore Overdue" / Parent: "Sarah: Chore Overdue" Kids: Claim Now / Parents: Complete/Skip/Remind Yes - On claimed/approved
Chore Now Due Chore due window open (1h) Kid "🎯 Chore Now Due" / "Make Bed is now due! Complete within 1 hour(s)..." Yes - Claim Now Yes - On claimed/approved/skip
Chore Reminder Chore due reminder (30m before) Kid "⏰ Chore Reminder" / "Make Bed is due in 30 minutes! Worth 10 points" Yes - Claim Now Yes - On claimed/approved/skip
Chore Missed Chore expires without completion Kid + Parents Kid: "😔 Chore Expired" / Parent: "Sarah: Chore Missed" / "expired..." No No

Note: Chore Claimed notifications use aggregation. When multiple chores are pending approval, parents see a consolidated notification showing the total count and most recent chore details.

Understanding Due Date Notifications

The integration provides two types of due-date notifications with distinct purposes:

Notification Type When It Fires Purpose Per-Chore Toggle Auto-Clear Behavior
Chore Now Due When chore's due window opens (configurable per chore, default 1h) Inform kid the chore window is now active "Notify When Due Window Starts" Cleared when claimed/approved
Chore Reminder Before chore due time (configurable per chore, default 30m) Remind kid deadline is approaching "Notify at Due Reminder Time" Cleared when claimed/approved
Chore Overdue After chore due time passes Alert kid AND parents that deadline was missed "Notify When Overdue" Cleared when claimed/approved

Example Timeline (Chore due at 5:00 PM with default settings):

  • 4:00 PM - "🎯 Chore Now Due" notification sent (due window opens, default 1h before)
  • 4:30 PM - "⏰ Chore Reminder" notification sent (default 30m before deadline)
  • 5:00 PM - If not claimed, "⏰ Chore Overdue" notification sent to kid AND parents

Note: The timing for "Chore Now Due" and "Chore Reminder" can be customized for each individual chore in the chore configuration. For example, you might set important chores to remind 1 hour before deadline, while routine chores only remind 15 minutes before.

Key Design Choice: These are separate notification types (not just different text) because they serve different user needs:

  • Chore Now Due: "The work is available" signal
  • Chore Reminder: "Time is running out" urgency signal
  • Chore Overdue: "Deadline missed" alert requiring intervention

Per-Chore Control: Each chore has independent toggles and timing controls in the config flow:

  • Enable/Disable: Toggle each notification type on or off
  • Timing: Configure when "Chore Now Due" window opens (default 1 hour before due time)
  • Timing: Configure when "Chore Reminder" is sent (default 30 minutes before due time)

This allows you to silence "Chore Now Due" for routine chores while keeping "Chore Reminder" enabled, or adjust reminder timing based on chore importance.

Reward Notifications

Event Trigger Recipients Example Text (Kid/Parent) Actionable Auto-Clear
Reward Claimed Kid spends points on reward Parents "Sarah: Reward Claimed" / "Claimed Ice Cream Trip for approval. Cost: 50..." Yes - Approve/Disapprove/Remind On any approve/disapprove/undo
Reward Approved Parent approves reward redemption Kid "🎉 Reward Approved!" / "Ice Cream Trip approved!" No Yes - Clears parent claim notifications
Reward Disapproved Parent disapproves reward claim Kid "💭 Reward Request Returned" / "Ice Cream Trip wasn't approved this time." No Yes - Clears parent claim notifications

Gamification Notifications

Event Trigger Recipients Example Text (Kid/Parent) Actionable Auto-Clear
Badge Earned Kid completes badge requirements Kid + Parents Kid: "🥇 Badge Earned!" / Parent: "Sarah: Badge Earned" / "Earned Morning Star" No No
Penalty Applied Parent deducts points via penalty button Kid "⚠️ Points Deducted" / "Lost 5 points. Parent note: {reason}" No No
Bonus Applied Parent awards points via bonus button Kid "⭐ Bonus Points!" / "Earned 10 points! Parent note: {reason}" No No
Achievement Earned Kid completes achievement milestones Kid + Parents Kid: "🏆 Achievement Earned!" / Parent: "Sarah: Achievement Earned" No No
Challenge Completed Kid finishes challenge goals Kid + Parents Kid: "🏁 Challenge Complete!" / Parent: "Sarah: Challenge Complete" No No

Reminder Notifications

Event Trigger Recipients Example Text Actionable Auto-Clear
Chore Reminder (30 min) Parent presses "Remind in 30 min" button Parents "⏰ Reminder" / "Sarah: Claimed Make Bed for review. Worth 10 points" Yes - Approve/Disapprove/Remind Yes - On any approve/disapprove
Reward Reminder (30 min) Parent presses "Remind in 30 min" button Parents "⏰ Reminder" / "Sarah: Claimed Ice Cream Trip for approval. Cost: 50..." Yes - Approve/Disapprove/Remind Yes - On any approve/disapprove

Actionable Notifications

Notifications marked as Actionable include buttons that parents (or kids) can press directly from the notification. The integration supports 6 action buttons:

Parent Action Buttons

  • ✅ Approve - Marks chore/reward as approved and awards/deducts points
  • ↩️ Needs Work - Rejects the claim and resets the chore or refunds points
  • ✅ Complete - Directly approves an overdue chore for a kid (no claim step needed)
  • ⏭️ Skip - Resets an overdue chore to pending and reschedules to next due date
  • ⏰ Remind in 30 min - Schedules a follow-up reminder notification

Kid Action Buttons

  • ✋ I Did It! - Allows kid to claim an overdue chore directly from notification

These action buttons allow parents to manage approvals and overdue chores without opening Home Assistant, and kids can quickly claim chores when reminded.

Overdue & Due Date Notifications

Overdue Notifications (Past Deadline)

Overdue notifications for kids include a "✋ I Did It!" action button, allowing kids to claim the chore directly from the notification.

Overdue notifications for parents include three action buttons:

  • ✅ Complete - Directly claims and approves the chore for that kid, awarding points.
    • For INDEPENDENT chores: Only approves for that kid
    • For SHARED chores: Only approves for that kid, remaining shared logic and requirements for others still in effect.
  • ⏭️ Skip - Reschedules the overdue chore to the next due date, no points or completions awarded
    • For INDEPENDENT chores: Only resets/reschedules for that specific kid
    • For SHARED chores: Resets state for all assigned kids and reschedules chore-level
  • ⏰ Remind in 30 min - Schedules a follow-up reminder notification

Why Complete instead of Approve? Parents can mark overdue chores complete directly from the notification, streamlining the workflow when kids forget to claim chores. The kid still receives approval notification and points.

Chore Now Due & Chore Reminder (Before Deadline)

Chore Now Due (when due window opens, typically 1 hour before deadline) and Chore Reminder (30 minutes before deadline) notifications for kids include a "✋ I Did It!" action button for quick claiming.

These notifications are automatically cleared when the kid claims the chore or when a parent approves it.

Chore Missed Notifications

Architectural Note: The current implementation sends "Chore Missed" notifications using the chore_missed_kid translation key to both kids and parents. This means parents receive kid-focused text ("😔 Chore Expired") instead of parent-appropriate text. A future update will:

  • Add chore_missed_parent translation key with parent-appropriate text
  • Add per-chore toggle "Notify on Missed" (currently no toggle exists)
  • Track in architectural decisions

Notification Management

The integration includes advanced notification management features:

  • Smart Tagging: Prevents notification spam by replacing old notifications with updates
  • Auto-Clearing: Automatically removes stale notifications when actions are taken
  • Aggregation: Consolidates multiple pending chores into single parent notifications
  • Multi-Parent Support: Clears notifications from all parent devices when any parent takes action

For detailed information about notification tagging, auto-clearing behavior, and aggregation logic, see Technical: Notifications.

Enabling & Disabling Notifications

Per-Kid Notification Services

Each kid and parent can have their own notification service configured:

  1. Go to Integration → Configure → Manage Kid/Parent
  2. Edit kid or parent profile
  3. Set Notification Service field to the HA Companion service (e.g., notify.mobile_app_phone)
  4. Leave blank to disable notifications for that person

Note: A parent with no notification service configured will not receive chore approval requests or aggregated notifications.

Per-Chore Reminder Control

Each chore has an individual notification setting:

  1. Go to Integration → Configure → Manage Chore
  2. Edit chore
  3. Toggle Send Reminders setting:
    • ON (default) - Kid receives due-soon reminders
    • OFF - Kid does not receive reminders for this chore

This allows you to silence reminders for routine chores while keeping them for important ones.

Language Selection

Notifications are sent in each recipient's preferred language, not the system language.

Setting Language Preferences

  1. Go to Integration → Configure → Manage Kid/Parent
  2. Edit kid or parent profile
  3. Set Language preference
  4. Save changes

Key Features:

  • Per-kid language - Each kid can have their own language preference
  • Per-parent language - Each parent can have their own language preference
  • Mixed households - Parents and kids can use different languages (e.g., Spanish-speaking parent, English-speaking kid)
  • 14 languages supported - Including English, Spanish, Dutch, French, German, Italian, and more
  • Automatic fallback - If a translation is missing, English is used
  • Everything translated - Notification titles, messages, and action button labels are all localized

For technical details about the translation architecture, see Technical: Notifications.

Mobile App Setup

To receive notifications, you must have the Home Assistant Companion App installed:

iOS Setup

  1. Install Home Assistant Companion from App Store
  2. Log in to your Home Assistant instance
  3. Enable notifications when prompted
  4. Note your device's notification service name (e.g., notify.mobile_app_iphone)

Android Setup

  1. Install Home Assistant Companion from Google Play
  2. Log in to your Home Assistant instance
  3. Enable notifications when prompted
  4. Note your device's notification service name (e.g., notify.mobile_app_phone)

Finding Your Service Name

  1. Go to Developer Tools → Services
  2. Search for services starting with notify.mobile_app_
  3. Use this service name in kid/parent profiles

Troubleshooting

Not Receiving Notifications

Check these settings:

  1. Profile Level: Kid/Parent has valid notification service configured?
  2. Mobile App: Companion app installed and logged in?
  3. App Permissions: Notification permissions granted to HA Companion app?
  4. Chore Level: (For reminders) Chore has "Send Reminders" enabled?

Notifications in Wrong Language

  • Check kid/parent profile language setting
  • Verify translation file exists for selected language
  • Missing translations automatically fall back to English

Action Buttons Not Working

  • Ensure you're using Home Assistant Companion app (not browser notifications)
  • Action buttons require HA Companion app v2021.6.0 or later
  • Check Home Assistant logs for errors when pressing buttons

Testing Notifications

Test notifications by:

  1. Having a kid claim a chore (parents should receive approval request)
  2. Having a parent apply a bonus (kid should receive points notification)
  3. Checking Home Assistant logs: custom_components.kidschores.managers.notification_manager

Technical Reference

For developers and advanced users, see:

  • Technical: Notifications - Notification system architecture, smart tagging, auto-clearing, aggregation, translation system, and implementation details

Last Updated: January 2026 (v0.5.0)

📖 KidsChores Wiki

🚀 Getting Started

⚙️ Configuration

🔧 Services & Examples

📖 Advanced Topics

📚 Technical Reference

👩‍🔧 Troubleshooting

Clone this wiki locally