Create or Update Helper
ha_config_set_helperCreate or update any of 30 Home Assistant helper types—inputs, timers, zones, templates, groups—and manage integration config subentries.
Instructions
Create or update Home Assistant helper entities and config subentries (30 types, unified interface).
MUST call ha_get_skill_guide OR refer to your locally installed skills first.
SIMPLE/FLOW helper create requires name; SIMPLE/FLOW helper update
requires helper_id. Config subentry create requires entry_id and
subentry_type; config subentry update also requires subentry_id.
SIMPLE types (structured params, WebSocket API): input_boolean, input_button, input_select, input_number, input_text, input_datetime, counter, timer, schedule, zone, person, tag.
FLOW types (pass config dict, Config Entry Flow API): template, group,
utility_meter, derivative, min_max, threshold, integration, statistics, trend,
random, filter, tod, generic_thermostat, switch_as_x, generic_hygrostat,
history_stats, mold_indicator.
Note: tod is the purpose-built "is-current-time-in-range" indicator
(supports cross-midnight ranges, unlike schedule).
Note: otp is a helper in the HA UI but is not offered here — its flow
requires a live TOTP code. Create it with ha_set_integration(domain="otp"),
as with any other helper-domain flow outside this list.
CONFIG_SUBENTRY type (Config Subentry Flow API): config_subentry.
Pass entry_id, subentry_type, and config. Pass subentry_id to
reconfigure an existing subentry; omit it to create a new subentry.
For flow-type updates, pass the existing entry_id as helper_id. Options flows
reject the name key on update — to rename a flow helper, delete and recreate.
Behavior notes:
UPDATE preserves type-specific fields not re-passed (rename never wipes initial/icon/etc. for any simple helper). Flow-helper and config subentry updates behave the same way: a field omitted from
configkeeps its current value, and a field set to null is cleared where the schema allows that field to be empty.Pass
action="create"oraction="update"to disambiguate intent. For SIMPLE/FLOW helpers, omitted action falls back to the implicithelper_id-presence discriminator. For config subentries, omitted action falls back to thesubentry_id-presence discriminator.For flow-based helpers, config keys not declared by any step's data_schema are silently ignored by HA; submit once and the validation error returns the
data_schemafor that helper so subsequent calls use the correct field names.Validation errors raised by this tool carry the helper's
data_schemain the response context (andmenu_optionsfor menu-rooted helpers liketemplate/groupwhen no sub-type is chosen yet) so a follow-up call can self-correct without a separate schema-discovery round-trip.Flows that present more than one menu (e.g. an MQTT device subentry reconfigure looping through its summary menu) take
next_step_idas a LIST of successive selections, consumed one per menu encounter.
EXAMPLES (menu-based types + tod, where first-call payload is non-obvious):
template sensor: ha_config_set_helper(helper_type="template", name="Room Temp", config={"next_step_id": "sensor", "state": "{{ states('sensor.x')|float }}", "unit_of_measurement": "°C"})
group (light): ha_config_set_helper(helper_type="group", name="Kitchen Lights", config={"group_type": "light", "entities": ["light.a", "light.b"]})
tod (time-of-day indicator, cross-midnight OK): ha_config_set_helper(helper_type="tod", name="Quiet Hours", config={"after_time": "22:00:00", "before_time": "07:00:00"})
config subentry (create under an existing integration): ha_config_set_helper(helper_type="config_subentry", entry_id="01HXYZ...", subentry_type="conversation", config={"name": "Local agent", "model": "gemma3:27b"})
helper-selection.md ships in this response under
skill_content by default — decision
matrix for picking the right helper type plus worked examples
and per-type field tables. For deeper helper-design guidance
beyond what ships here, call ha_get_skill_guide.
create update new add helper input_boolean input_button input_number input_text input_datetime input_select counter timer schedule zone person tag template group utility_meter derivative min_max threshold integration statistics trend random filter tod generic_thermostat switch_as_x generic_hygrostat history_stats mold_indicator
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | Material Design Icon (e.g., 'mdi:bell', 'mdi:toggle-switch') | |
| mode | No | Display mode: 'box'/'slider' for input_number, 'text'/'password' for input_text | |
| name | No | Display name for simple/flow helper creation. Required when creating a helper without helper_id. Optional on helper update. Ignored for helper_type='config_subentry', which uses entry_id/subentry_type/subentry_id instead. For flow-based helper updates (template, group, utility_meter, ...), this is typically ignored because options flows don't expose renaming. Rename a flow helper by deleting and recreating instead. | |
| step | No | Step/increment value for input_number or counter | |
| wait | No | Wait for helper entity to be queryable before returning. Default: True. Set to False for bulk operations. | |
| action | No | Explicit intent: 'create' a new helper or 'update' an existing one. When omitted, falls back to the implicit discriminator: presence of helper_id => update, absence => create. Pass 'create' or 'update' to disambiguate (e.g. so a typo in helper_id surfaces as a clear 'helper not found' error instead of being mistaken for a create call). | |
| config | No | Config dict for flow-based helper types and helper_type='config_subentry' (template, group, utility_meter, derivative, min_max, threshold, integration, statistics, trend, random, filter, tod, generic_thermostat, switch_as_x, generic_hygrostat, history_stats, mold_indicator). Ignored for simple helper types. On update it is a patch: a field you omit keeps its current value, and a field set to null is cleared where the schema allows that field to be empty. A field two steps declare gets your one value both times; pass step_values={'<step_id>': {'<field>': <value>}} to give a step its own value, or to leave it out of that step; a LIST of those objects supplies one per encounter when the flow presents a step more than once. Field set is delivered as data_schema on the first validation error. | |
| friday | No | Schedule time ranges for Friday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes. | |
| labels | No | Labels to categorize the helper | |
| monday | No | Schedule time ranges for Monday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes (e.g. {'from': '07:00', 'to': '22:00', 'data': {'mode': 'comfort'}}) | |
| radius | No | Radius in meters for zone (default: 100) | |
| sunday | No | Schedule time ranges for Sunday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes. | |
| tag_id | No | Tag ID for tag. On create, omit to auto-generate a unique uuid4 hex (HA's tag/create requires this field; the tool fills it in for you). On update, the tag's existing tag_id is required (passed via helper_id). | |
| area_id | No | Area/room ID to assign the helper to | |
| initial | No | Initial value for applicable helper types. For input_boolean, input_select, input_number, input_text, and input_datetime: setting `initial` — even to false/0 — disables last-state restore and forces that value on every HA restart; omit unless you want the helper to reset to that value on every restart instead of restoring its last state. For counter, `initial` is just the starting value — restore-on-restart is controlled separately by `restore` (default True). | |
| options | No | List of options for input_select (required for input_select) | |
| passive | No | Passive zone (won't trigger state changes for person entities) | |
| picture | No | Picture URL for person entity | |
| restore | No | Restore state after restart (counter, timer). Defaults to True for counter, False for timer | |
| tuesday | No | Schedule time ranges for Tuesday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes. | |
| user_id | No | User ID to link to person entity | |
| category | No | Category ID to assign to this helper. Use ha_config_get_category(scope='helpers') to list available categories, or ha_config_set_category() to create one. | |
| duration | No | Default duration for timer in format 'HH:MM:SS' or seconds (e.g., '0:05:00' for 5 minutes) | |
| entry_id | No | Parent config entry ID when helper_type='config_subentry'. Use ha_get_integration() to find entry IDs. | |
| has_date | No | Include date component for input_datetime | |
| has_time | No | Include time component for input_datetime | |
| latitude | No | Latitude for zone (required for zone) | |
| saturday | No | Schedule time ranges for Saturday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes. | |
| thursday | No | Schedule time ranges for Thursday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes. | |
| helper_id | No | REQUIRED when updating an existing helper. Bare ID ('my_button') or full entity ID ('input_button.my_button'). Omit to create a new helper. | |
| longitude | No | Longitude for zone (required for zone) | |
| max_value | No | Maximum value (input_number/counter) or maximum length (input_text). Also accepts shorthand 'max'. | |
| min_value | No | Minimum value (input_number/counter) or minimum length (input_text). Also accepts shorthand 'min'. | |
| wednesday | No | Schedule time ranges for Wednesday. List of {'from': 'HH:MM', 'to': 'HH:MM'} dicts. Optional 'data' dict for additional attributes. | |
| description | No | Description for tag | |
| helper_type | Yes | Type of helper entity to create or update | |
| subentry_id | No | Existing config subentry ID to reconfigure when helper_type='config_subentry'. Omit to create. | |
| MandatoryBPS | No | ||
| subentry_type | No | Integration-defined subentry type when helper_type='config_subentry'. | |
| BestPracticeKey | No | Read-receipt for the home-assistant-best-practices skill; required when strict best-practices mode is enabled. Not a secret or credential: the current value is an attestation phrase published openly at the top of the skill content served by ha_get_skill_guide. Read that content, then pass the value back verbatim — this round-trip is the server's designed protocol confirming the practices were read before writing. | |
| device_trackers | No | List of device_tracker entity IDs for person | |
| unit_of_measurement | No | Unit of measurement for input_number (e.g., '°C', '%', 'W'). Also accepts shorthand 'unit'. | |
| show_advanced_options | No | When helper_type='config_subentry', ask older Home Assistant versions to expose advanced flow options. No-op on HA 2026.6+; pending removal before HA 2027.6. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||