Skip to content

Services

Jump to bottom
tempus2016 edited this page Jun 22, 2026 · 11 revisions

TaskMate exposes a set of Home Assistant services for automations, scripts, and custom frontend integrations.

Every service is in the taskmate.* namespace and accepts parameters via the standard service_data / data key.

Dynamic Selectors (v3.7.0+)

All entity ID fields (child_id, chore_id, reward_id, penalty_id, bonus_id, group_id) show as dropdown selectors in the HA automation editor and Developer Tools → Services. The dropdown lists entity names as labels with the hex IDs as values, so you can pick "Noah" instead of typing ef19c56175c14bd9.

  • Dropdowns refresh automatically every 30 seconds as entities are added or removed
  • custom_value mode is enabled — you can still type a raw hex ID if you prefer
  • Services without entity ID fields (e.g. preview_sound, add_chore) are unaffected
  • Uses Home Assistant's native select widget — no custom styling

Tip: If you need to find an ID outside the automation editor, enable the Show IDs toggle in the admin panel.

Chore services

taskmate.complete_chore

Mark a chore as completed by a child.

Field Required Default Description
chore_id ✅ — ID of the chore
child_id ✅ — ID of the child
as_parent false Complete on behalf of the child and award points immediately, bypassing approval (v4.0.0, #402). See Photo Proof for how this interacts with photo-required chores.
photo_url — Optional evidence photo URL/path attached to the completion. Required in spirit when the chore has photo proof enabled. 
service: taskmate.complete_chore
data:
  chore_id: 8a3b2c1d4e5f6789
  child_id: ef19c56175c14bd9
  as_parent: false
  photo_url: "/local/proof/dishes.jpg"

Note: as_parent: true records the completion under the parent (__parent__) and skips the approval queue. A chore with require_photo enabled always routes to approval so the photo can be reviewed.

taskmate.approve_chore

Approve a completed chore and award points.

Field Required Description
completion_id ✅ ID of the pending chore completion

taskmate.reject_chore

Reject a completed chore. No points awarded.

Field Required Description
completion_id ✅ ID of the pending chore completion

taskmate.add_chore

Create a chore dynamically (for automations).

Field Required Description
name ✅ Chore title
description Optional details
points Point value (default 10)
assigned_to List of child IDs (empty = all)
time_category morning / afternoon / evening / night / anytime (default anytime)
difficulty Difficulty tier — easy / medium / hard (default medium). Scales awarded points by the tier multiplier; medium = ×1.0 baseline. See Difficulty Tiers.
one_shot Single-day auto-expiring chore (boolean, default false)
requires_approval Parent approval required (boolean, default true) 
service: taskmate.add_chore
data:
  name: "Take out recycling"
  points: 15
  difficulty: hard
  time_category: evening
  assigned_to:
    - ef19c56175c14bd9

Note: Advanced chore fields — expires_on, photo proof (require_photo), time incentives (due_time / early_bonus / late_penalty), and first_come assignment mode — are not exposed on the add_chore service. Configure them in the Admin Panel chore editor. See Difficulty Tiers, Photo Proof, and Chores.

taskmate.skip_chore

Skip today's assigned child in a rotation-mode chore and reassign to the next child in the pool.

Field Required Description
chore_id ✅ ID of the chore

Only works for non-everyone assignment modes with a pool of 2+ children. The skip is ephemeral — applies only today and resets at midnight. Maximum skips per day = pool size − 1. Sticky group followers cannot be skipped individually.

taskmate.set_chore_manual_start

Override the rotation to start with a specific child.

Field Required Description
chore_id ✅ ID of the chore
child_id ✅ ID of the child to assign

For alternating mode: reorders the rotation so the chosen child is first and resets the anchor to today. For random/balanced modes: overrides today's cached assignment only — the deterministic algorithm resumes tomorrow. Clears any active skip state.

taskmate.complete_bonus_subtask

Complete a bonus subtask within a parent chore.

Field Required Description
chore_id ✅ ID of the parent chore
bonus_subtask_id ✅ ID of the bonus subtask
child_id ✅ ID of the child

The parent chore must already be completed by the same child today. The subtask cannot already be completed by that child today. See Bonus Subtasks.

taskmate.request_swap (v4.0.0)

A child requests to take over today's rotation assignment of a chore. Creates a pending swap request for a parent to approve. See Chore Swaps.

Field Required Description
chore_id ✅ ID of the chore (must be a rotation mode: alternating / random / balanced / first_come)
requester_id ✅ ID of the child requesting to take the chore over 
service: taskmate.request_swap
data:
  chore_id: 8a3b2c1d4e5f6789
  requester_id: ef19c56175c14bd9

The requester must be a different child from today's current assignee and must be in the chore's pool. Approve/reject the request from the Admin Panel; on approval the chore's assignment_current_child_id is set to the requester. See Chore Swaps.

Timed task services

taskmate.start_timed_task

Start or resume a timed task timer.

Field Required Description
chore_id ✅ ID of the timed chore
child_id ✅ ID of the child

Starts a new session or resumes a paused one. Checks the daily cap before starting.

taskmate.pause_timed_task

Pause a running timed task timer.

Field Required Description
chore_id ✅ ID of the timed chore
child_id ✅ ID of the child

Closes the current time segment and marks the session as paused. Resume with start_timed_task.

taskmate.stop_timed_task

Stop a timed task and submit for approval.

Field Required Description
chore_id ✅ ID of the timed chore
child_id ✅ ID of the child

Creates a completion record. Points are calculated as floor(total_seconds / (rate_minutes × 60)) × rate_points, clamped to the daily cap if set. See Timed Tasks.

Task group services

taskmate.add_task_group

Create a task group to coordinate rotation-mode chore assignments.

Field Required Default Description
name ✅ — Group display name
policy ✅ sticky sticky (same child) or spread (different children)
chore_ids [] Ordered list of chore IDs 
service: taskmate.add_task_group
data:
  name: "Dinner Duties"
  policy: sticky
  chore_ids:
    - abc12345
    - def67890

taskmate.update_task_group

Update an existing task group. Only supplied fields are changed.

Field Required Description
group_id ✅ ID of the group to update
name New name
policy New policy
chore_ids New ordered chore list

taskmate.remove_task_group

Delete a task group. Chores revert to independent rotation.

Field Required Description
group_id ✅ ID of the group to remove

See Task Groups for full details on sticky and spread policies.

Reward services

taskmate.claim_reward

A child claims a reward. Creates a pending claim awaiting parent approval.

For wallet-mode rewards: child's balance must cover the cost. For pool-mode rewards: the child's pool allocation must equal or exceed the cost (i.e. the pool is full).

Field Required Description
reward_id ✅ ID of the reward
child_id ✅ ID of the claiming child

taskmate.approve_reward

Approve a pending reward claim. For wallet rewards, deducts cost from the child's balance. For pool rewards, clears the allocation (points were already deducted at deposit time).

Field Required Description
claim_id ✅ ID of the pending reward claim

taskmate.reject_reward

Reject a pending reward claim. For wallet rewards, no action (points were never deducted). For pool rewards, allocation stays in place — child can Redeem again.

Field Required Description
claim_id ✅ ID of the pending reward claim

taskmate.allocate_points_to_pool (v3.0+)

Move points from a child's spendable balance into a specific reward's pool.

Allocations are locked — there is no matching withdraw service. The requested amount is silently capped at whichever is lowest:

  • The requested points
  • The child's current spendable balance
  • The pool's remaining capacity (reward.cost − already_allocated)

Logs a negative PointsTransaction for audit.

Field Required Description
child_id ✅ ID of the child making the deposit
reward_id ✅ ID of the reward pool
points ✅ Points to allocate (integer ≥ 1)

Example:

service: taskmate.allocate_points_to_pool
data:
  child_id: 8a3b2c1d4e5f6789
  reward_id: 1f2e3d4c5b6a7890
  points: 5

Errors:

  • ValueError: No spendable points available — child has no uncommitted points
  • ValueError: Pool for reward 'X' is already full
  • ValueError: Points to allocate must be at least 1

Points services

taskmate.add_points

Add bonus points to a child.

Field Required Description
child_id ✅ ID of the child
points ✅ Points to add
reason Optional reason logged to activity

taskmate.remove_points

Remove points from a child.

Field Required Description
child_id ✅ ID of the child
points ✅ Points to remove
reason Optional reason

taskmate.gift_points (v4.0.0)

Transfer spendable points from one child to another (parent-controlled). See Gifting Points.

Field Required Description
from_child_id ✅ ID of the sending child
to_child_id ✅ ID of the receiving child
points ✅ Points to transfer (integer ≥ 1) 
service: taskmate.gift_points
data:
  from_child_id: ef19c56175c14bd9
  to_child_id: 8a3b2c1d4e5f6789
  points: 10

Deducts from the sender's spendable balance and credits the recipient. Logs a PointsTransaction on both children (Gift to <name> / Gift from <name>). The gift does not count toward the recipient's total_points_earned or career score, and the spending cap does not apply. Sender and recipient must differ, and the sender must hold at least points. See Gifting Points.

taskmate.undo_transaction (v4.0.0)

Reverse a reversible points transaction by its ID — penalties, bonuses, manual add/remove adjustments, and gifts (both legs). Automatic transactions (weekend/streak/perfect-week bonuses, pool moves, decay, interest) cannot be undone. See Points Economy.

Field Required Description
transaction_id ✅ ID of the points transaction to reverse (from the activity feed / recent_transactions) 
service: taskmate.undo_transaction
data:
  transaction_id: 3f2e1d0c9b8a7654

Re-credits (for a penalty) or re-debits (for a bonus) the original amount and removes the transaction record. Undoing a gift reverses both legs (sender re-credited, recipient re-debited). See Points Economy.

taskmate.undo_chore_approval (v4.1.0)

Reverse an accidental chore approval — removes the awarded points and returns the completion to pending so it can be approved (or rejected) again. See Points Economy.

Field Required Description
completion_id ✅ ID of the approved chore completion to revert to pending 
service: taskmate.undo_chore_approval
data:
  completion_id: 9c8b7a6d5e4f3210

Removes the points credited at approval, reverses the associated PointsTransaction, and moves the completion back into the pending-approvals queue. See Points Economy.

Penalty services

taskmate.add_penalty

Create a reusable penalty definition.

Field Required Default Description
name ✅ — Penalty name
points ✅ — Points to deduct when applied (1–10000)
description "" Optional description
icon mdi:alert-circle-outline MDI icon
assigned_to all children List of child IDs this penalty applies to

taskmate.update_penalty

Update an existing penalty. Only supplied fields are changed.

Field Required Description
penalty_id ✅ ID of the penalty to update
name New name
points New points value (1–10000)
description New description
icon New MDI icon
assigned_to New child ID list

taskmate.remove_penalty

Delete a penalty definition.

Field Required Description
penalty_id ✅ ID of the penalty to remove

taskmate.apply_penalty

Apply a penalty to a child — deducts points and logs a PointsTransaction to the activity feed.

Field Required Description
penalty_id ✅ ID of the penalty to apply
child_id ✅ ID of the child

Note: A child's balance can go negative when a penalty is applied.

Mandatory chore review services (v4.2.0)

When a mandatory chore is left incomplete and its time-period window closes, TaskMate records a mandatory-miss review item (one per chore/child/day). These services resolve a pending miss; each clears the review item. Find the miss_id in the mandatory_misses list on sensor.pending_approvals. See Mandatory Chores.

taskmate.apply_mandatory_penalty

Deduct the configured penalty points for a missed mandatory chore and clear the review item.

Field Required Description
miss_id ✅ ID of the mandatory-miss review item 
service: taskmate.apply_mandatory_penalty
data:
  miss_id: 4d3c2b1a0f9e8d7c

Deducts the miss's snapshotted penalty_points from the child (logging a PointsTransaction) when greater than 0, then removes the review item. See Mandatory Chores.

taskmate.postpone_mandatory_chore

Give a missed mandatory chore another period (or tomorrow) without a penalty, and clear the review item.

Field Required Description
miss_id ✅ ID of the mandatory-miss review item 
service: taskmate.postpone_mandatory_chore
data:
  miss_id: 4d3c2b1a0f9e8d7c

Re-opens the chore in the next remaining time period today; if no window is left today, normal scheduling resurfaces it tomorrow. No points are deducted. See Mandatory Chores.

taskmate.dismiss_mandatory_chore

Clear a missed mandatory chore review item with no penalty.

Field Required Description
miss_id ✅ ID of the mandatory-miss review item 
service: taskmate.dismiss_mandatory_chore
data:
  miss_id: 4d3c2b1a0f9e8d7c

Removes the review item outright — no points change, no rescheduling. See Mandatory Chores.

Bonus services

taskmate.add_bonus

Create a reusable bonus definition.

Field Required Default Description
name ✅ — Bonus name
points ✅ — Points to award when applied (1–10000)
description "" Optional description
icon mdi:star-circle-outline MDI icon
assigned_to all children List of child IDs this bonus applies to

taskmate.update_bonus

Update an existing bonus. Only supplied fields are changed.

Field Required Description
bonus_id ✅ ID of the bonus to update
name New name
points New points value (1–10000)
description New description
icon New MDI icon
assigned_to New child ID list

taskmate.remove_bonus

Delete a bonus definition.

Field Required Description
bonus_id ✅ ID of the bonus to remove

taskmate.apply_bonus

Apply a bonus to a child — awards points and logs a PointsTransaction to the activity feed.

Field Required Description
bonus_id ✅ ID of the bonus to apply
child_id ✅ ID of the child

Badge services

taskmate.add_badge

Create a custom badge with optional criteria and point bonus.

Field Required Default Description
name ✅ — Badge display name
description "" Description text
icon mdi:medal MDI icon
tier bronze bronze, silver, gold, or platinum
point_bonus 0 Bonus points awarded when earned
criteria [] List of {metric, operator, value} objects — AND-evaluated
assigned_to all children List of child IDs (empty = all)
notify_on_earn true Fire notifications when earned 
service: taskmate.add_badge
data:
  name: "Super Reader"
  description: "Complete 50 chores and maintain a 7-day streak"
  icon: mdi:book-open-variant
  tier: gold
  point_bonus: 25
  criteria:
    - { metric: total_chores, operator: ">=", value: 50 }
    - { metric: current_streak, operator: ">=", value: 7 }

taskmate.update_badge

Update an existing badge. Only supplied fields are changed. Built-in badges allow editing point_bonus, tier, assigned_to, notify_on_earn, and enabled — criteria, name, description, and icon are frozen.

Field Required Description
badge_id ✅ ID of the badge to update
name New name (custom only)
description New description (custom only)
icon New icon (custom only)
tier New tier
point_bonus New point bonus
criteria New criteria list (custom only)
assigned_to New child ID list
notify_on_earn New notification setting

taskmate.remove_badge

Delete a custom badge. Built-in badges cannot be removed — disable them via update_badge instead.

Field Required Description
badge_id ✅ ID of the badge to remove

taskmate.award_badge_manually

Manually award a badge to a child, bypassing criteria evaluation. Credits point bonus and fires notification if notify_on_earn is true.

Field Required Description
badge_id ✅ ID of the badge to award
child_id ✅ ID of the child

taskmate.revoke_badge

Revoke a previously awarded badge. Automatically reverses any point bonus that was credited.

Field Required Description
awarded_badge_id ✅ ID of the awarded badge record (from the admin panel's Award History tab or the badge sensor's earned array)

taskmate.rebuild_badges

Re-evaluate all badges across all children silently. Awards any newly-qualifying badges without notifications or point bonuses. No parameters.

See Achievement Badges for full details.

Miscellaneous

taskmate.set_chore_order

Set the per-child display order of chores.

Field Required Description
child_id ✅ ID of the child
chore_order ✅ Ordered list of chore IDs

taskmate.preview_sound

Preview a completion sound in the browser.

Field Required Description
sound ✅ Sound identifier — none, coin, levelup, fanfare, chime, powerup, undo, fart1–fart10, fart_random

taskmate.choose_avatar (v4.0.0)

A child switches to an avatar they have unlocked. See Avatars.

Field Required Description
child_id ✅ ID of the child
icon ✅ The MDI icon of an unlocked catalogue avatar (e.g. mdi:rocket-launch) 
service: taskmate.choose_avatar
data:
  child_id: ef19c56175c14bd9
  icon: mdi:rocket-launch

When invoked as a service (child self-service) the avatar must already be unlocked for that child. Parents can assign any catalogue avatar from the Admin Panel regardless of unlock state. See Avatars.

taskmate.test_notification (v4.0.0)

Send a sample notification of the given type to its enabled recipients. Ignores the master on/off toggle so routing can be verified.

Field Required Description
type_id ✅ Notification type ID, e.g. pending_chore_approval, badge_earned, streak_milestone, level_up, weekly_digest, celebration 
service: taskmate.test_notification
data:
  type_id: streak_milestone

See Notifications for the full list of notification type IDs.

Service Side Effects

Several services trigger additional actions beyond their primary purpose:

approve_chore

  • Applies the difficulty multiplier to the base points (easy ×0.5, medium ×1.0, hard ×2.0 by default — see Difficulty Tiers)
  • Applies the weekend multiplier if the current day is Saturday or Sunday (see Bonus Points)
  • Applies time incentives when the chore sets due_time — +early_bonus if completed at/before it, −late_penalty if after
  • Checks and awards streak milestone bonuses if the child hits a configured milestone
  • Records the child as a perfect week candidate (checked Monday at midnight)
  • Updates the child's current streak and best streak
  • Advances levels/XP (total_points_earned is the XP pool) and fires a level-up celebration when a threshold is crossed — see Levels and XP and Celebrations
  • Advances any matching quests and challenges — see Quests and Challenges
  • May fire a celebration (e.g. all chores done) — see Celebrations
  • Creates a PointsTransaction audit record
  • Sends a notification (persistent + optional push) if a notify service is configured

reject_chore

  • Decrements the child's current streak by 1 (does not reset to 0)
  • Does not award any points

approve_reward

  • For wallet rewards: deducts cost from the child's balance
  • For pool rewards: clears the child's allocation (points were already deducted at deposit time)
  • For jackpot pool rewards: each contributing child loses only their own deposited share
  • Decrements the reward's quantity by 1 (if limited stock)

claim_reward

  • Sends a notification (persistent + optional push) for pending reward claims
  • For wallet rewards: child's balance must cover the cost
  • For pool rewards: child's allocation must equal or exceed the cost
  • Blocked if the reward is sold out or expired

apply_penalty / apply_bonus

  • Creates a PointsTransaction record logged to the activity feed
  • Penalty applications show with a red shield icon in the Activity Card
  • Updates the child's career_score (total_points_earned − total_penalties_received)

allocate_points_to_pool

  • Immediately deducts points from the child's spendable balance
  • Creates a negative PointsTransaction for audit
  • Amount is silently capped at the lowest of: requested points, spendable balance, pool remaining capacity

Complete Service List

The full set of taskmate.* services registered by the integration:

complete_chore, complete_bonus_subtask, approve_chore, reject_chore, apply_mandatory_penalty, postpone_mandatory_chore, dismiss_mandatory_chore, undo_transaction, undo_chore_approval, test_notification, gift_points, request_swap, choose_avatar, claim_reward, approve_reward, reject_reward, allocate_points_to_pool, add_points, remove_points, preview_sound, set_chore_order, add_penalty, update_penalty, remove_penalty, apply_penalty, add_bonus, update_bonus, remove_bonus, apply_bonus, add_chore, skip_chore, set_chore_manual_start, add_task_group, update_task_group, remove_task_group, start_timed_task, pause_timed_task, stop_timed_task, add_badge, update_badge, remove_badge, award_badge_manually, revoke_badge, rebuild_badges.

Related

Clone this wiki locally