Create or Update Helper
ha_config_set_helperCreate or update Home Assistant helper entities and config subentries across 30 types with a single unified interface, covering simple helpers, flow-based helpers, and integration 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 | |||