Intents

Intents

A unit's configuration is offered as intents: what a user wants ("one touch turns it on and off", "turn off after no motion"), never the unit's menus. Each intent (IntentDef) has an id, a meaning, when (not) to use it, prerequisites, side effects, the errors a change can get, examples, its value shape, and its access:

• read_write — changed with PUT /v1/devices/{id}/intents/{intent} { value } (PUT /v1/devices/{id}/intents/{intent}) when the integration has advanced_config: read_write. The gateway sends the frames, and the new value is reported only after the unit confirmed it.
• read_only — shown from the cache with guidance and an appAction naming the app screen that changes it.

GET /v1/devices/{id}/intents lists the intents of that unit's model (or of one gang) with each value as { value, source: "cache", asOf }; GET /v1/intents the whole table.

• advanced_config: off: every intent call is 403 config_not_allowed; read: every change is.
• A read-only intent, and resetting a unit, are 403 not_offered.
• A setting packed with others in one register needs a cached value to change: without one it is 409 not_cached with appAction: unit.menus (unit.menus): the user reads the unit's menu in the app once.
• Unit mode (Auto, Eco, Manual) is a control operation, set_mode (see POST /v1/devices/{id}/control), not an intent.

The intents, one by one, follow.

Single touch

single_touch · read and write · IGHH, IGHHX1, IGPH, IGTHX2

The whole face of the switch becomes one key: any touch turns the load on or off. On a shutter, a short touch on up or down opens or closes it all the way.

• When: Someone wants the switch to work with one tap anywhere, e.g. for children, guests or a hard-to-reach switch.
• Not when: The switch's separate areas (on, mode, off) are still needed, e.g. to change the mode by hand.
• Needs: On light, power and sense switches the setting shares a register with the LED mode: the unit's settings must have been read once (Unit page → Read menu).
• Side effects: The LED mode is kept as it is.
• Value: true or false
• Errors: config_not_allowed, not_cached, validation, unit_unreachable, ighc_unavailable, not_found

Examples:

• “Make the hallway switch work with a single touch.” → PUT /v1/devices/{id}/intents/single_touch {"value": true}
• “Turn single touch off on the kids' room light.” → PUT /v1/devices/{id}/intents/single_touch {"value": false}

LED mode

led_mode · read and write · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGSH (per gang)

When the switch's status LEDs light: always (on), only while the load is on (while_on), or never (off).

• When: The LEDs disturb at night, or someone wants to see the switch in the dark.
• Not when: The shutter's LEDs: their encoding isn't settled, so they are read-only (shutter_leds).
• Needs: On light and power switches and on modules the LED mode shares a register with another setting: the unit's settings must have been read once (Unit page → Read menu).
• Side effects: Single touch (light and power switches) and the side-button flag (modules) are kept as they are.
• Value: on, while_on, off
• Errors: config_not_allowed, not_cached, validation, unit_unreachable, ighc_unavailable, not_found

Examples:

• “Turn off the bedroom switch's lights at night.” → PUT /v1/devices/{id}/intents/led_mode {"value": "off"}
• “Light the switch only while the light is on.” → PUT /v1/devices/{id}/intents/led_mode {"value": "while_on"}

Turn-on brightness

turn_on_brightness · read and write · IGHH

The brightness (in percent) a dimmer comes on at when switched on at the wall or by an on command without a level.

• When: The light comes on too bright or too dim, e.g. a softer light in a bedroom at night.
• Not when: Setting the brightness right now: use control with set_brightness. On a light that only switches (not set up as dimmable) it has no effect.
• Needs: A dimmer (IGHH) whose settings say it is dimmable, and whose settings were read once (Unit page → Read menu): the level shares a register with instant reporting.
• Side effects: Instant reporting is kept as it is.
• Value: a whole number 0–100 percent
• Errors: config_not_allowed, not_cached, validation, unit_unreachable, ighc_unavailable, not_found

Examples:

• “Have the bedroom light come on at 30%.” → PUT /v1/devices/{id}/intents/turn_on_brightness {"value": 30}
• “Make the kitchen light come on at full brightness.” → PUT /v1/devices/{id}/intents/turn_on_brightness {"value": 100}

Off delay

off_delay · read and write · IGHH, IGHHX1

How long the load stays on after it is switched off at the switch, in seconds (0 turns the delay off; at most 3 min 59 s).

• When: Someone wants light for a moment after switching off, e.g. to leave a room or a stairway.
• Not when: Turning off after no motion: that is off_after_no_motion.
• Side effects: None.
• Value: a whole number 0–239 seconds
• Errors: config_not_allowed, not_cached, validation, unit_unreachable, ighc_unavailable, not_found

Examples:

• “Keep the stairway light on for 30 seconds after I switch it off.” → PUT /v1/devices/{id}/intents/off_delay {"value": 30}
• “Switch the hall light off at once.” → PUT /v1/devices/{id}/intents/off_delay {"value": 0}

Off after no motion

off_after_no_motion · read and write · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGSH (per gang)

How long after the last motion the unit turns its load off, in minutes (at most 3 h 59 min). Modules allow 0 (never); other units at least 1.

• When: Lights stay on too long in an empty room, or go off while people are still there.
• Not when: Turning off a moment after a switch press: that is off_delay.
• Needs: A motion sensor in the same room, and the unit in Auto or Eco mode.
• Side effects: None.
• Value: a whole number 0–239 minutes
• Errors: config_not_allowed, not_cached, validation, unit_unreachable, ighc_unavailable, not_found

Examples:

• “Turn the office light off 10 minutes after the last motion.” → PUT /v1/devices/{id}/intents/off_after_no_motion {"value": 10}
• “Keep the living room on for an hour without motion.” → PUT /v1/devices/{id}/intents/off_after_no_motion {"value": 60}

Quick off when someone only passes through

quick_off · read and write · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4 (per gang)

A shorter off timer, in minutes, that starts at the first motion: if no second motion follows, the load goes off after it (someone only walked through). 0 turns it off.

• When: Corridors and passages where a light should not stay on for the full motion timer after one pass.
• Not when: Rooms where people sit still: a second detection may come late, and the light would go off.
• Needs: A motion sensor in the same room, and the unit in Auto or Eco mode.
• Side effects: None.
• Value: a whole number 0–239 minutes
• Errors: config_not_allowed, not_cached, validation, unit_unreachable, ighc_unavailable, not_found

Examples:

• “In the corridor, switch off after 2 minutes if someone just walks by.” → PUT /v1/devices/{id}/intents/quick_off {"value": 2}
• “Stop the quick off in the study.” → PUT /v1/devices/{id}/intents/quick_off {"value": 0}

Only when dark

only_when_dark · read and write · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH (per gang)

Motion turns the load on only while the room's light level is below this many lux. The app's presets: dark 20, dimmed 60, bright 150, always 254 (whatever the light).

• When: Lights come on from motion in daylight, or don't come on at dusk.
• Not when: Units without a sensor in the room: the threshold is never checked.
• Needs: A motion sensor with a light reading in the same room.
• Side effects: None.
• Value: a whole number 0–254 lux
• Errors: config_not_allowed, not_cached, validation, unit_unreachable, ighc_unavailable, not_found

Examples:

• “Only turn the porch light on by motion when it is dark.” → PUT /v1/devices/{id}/intents/only_when_dark {"value": 20}
• “Let motion turn the hall light on whatever the light.” → PUT /v1/devices/{id}/intents/only_when_dark {"value": 254}
• “Turn on by motion when it is dim too.” → PUT /v1/devices/{id}/intents/only_when_dark {"value": 60}

Climate by room temperature

climate · read and write · IGPH, IGSH

What the switch feeds and its room-temperature rules in Auto and Eco mode: cool (an AC: on above on °C, off below off °C), heat (a heater: on below on, off above off), or none (no temperature rule). Any of the three parts may be sent alone.

• When: An AC or heater on a power or sense switch should follow the room temperature, e.g. cool from 26 °C and stop at 23 °C.
• Not when: Setting an AC's temperature now: use control with set_temp on the AC.
• Needs: A power (IGPH) or sense (IGSH) switch feeding the appliance, a sensor with a temperature reading in the room, and the unit in Auto or Eco mode.
• Side effects: Changing the type to none stops every temperature rule of the unit.
• Value: { mode: cool | heat | none, on: °C, off: °C }
• Errors: config_not_allowed, not_cached, validation, unit_unreachable, ighc_unavailable, not_found

Examples:

• “Cool the bedroom when it passes 26 degrees and stop at 23.” → PUT /v1/devices/{id}/intents/climate {"value": {"mode": "cool", "on": 26, "off": 23}}
• “Heat the bathroom below 20 degrees until 23.” → PUT /v1/devices/{id}/intents/climate {"value": {"mode": "heat", "on": 20, "off": 23}}
• “Raise the office AC's start to 27 degrees.” → PUT /v1/devices/{id}/intents/climate {"value": {"on": 27}}

Shutter eco light level

shutter_eco_light · read and write · IGTHX2

The light level (lux) a shutter keeps in Eco mode, moving a step at a time as the daylight changes.

• When: A room is too bright or too dark while its shutter is in Eco mode.
• Not when: Opening or closing the shutter now: use control.
• Needs: A light sensor in the room, and the shutter in Eco mode.
• Side effects: None.
• Value: a whole number 0–254 lux
• Errors: config_not_allowed, not_cached, validation, unit_unreachable, ighc_unavailable, not_found

Examples:

• “In Eco mode, let the living room shutter keep it bright.” → PUT /v1/devices/{id}/intents/shutter_eco_light {"value": 200}
• “Let the shutter keep the study dimmer.” → PUT /v1/devices/{id}/intents/shutter_eco_light {"value": 80}

Key Sense

key_sense · read only, from the cache · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGSH, IGTHX2 (per gang)

How sensitive the touch areas are (up, mode and down; higher means less sensitive). On a module, whether each gang's touch area responds at all (active or blocked).

• When: Explaining why a switch reacts to light brushes, or doesn't react.
• Not when: Changing it: it is set in the app.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: To lock a switch's touch (a child lock, or while tracking down phantom presses), open the unit's page in the app → Advanced settings and set Key Immunity to 90: the keys stop responding. Set it back to the value shown here to unlock. On a multi-gang module, set the gang's Sensitivity to Blocked instead. Raising Key Sense makes keys less sensitive without locking them. (appAction unit)
• Errors: config_not_allowed, not_found

Key Immunity

key_immunity · read only, from the cache · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGSH, IGTHX2

How strongly the keys ignore electrical noise (0–99; 90 locks them, which is how touch lock works). On light, power, sense and shutter switches +100 marks 60 Hz mains.

• When: Explaining phantom presses, or whether a switch's touch is locked (90).
• Not when: Changing it: it is set in the app.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: To lock a switch's touch (a child lock, or while tracking down phantom presses), open the unit's page in the app → Advanced settings and set Key Immunity to 90: the keys stop responding. Set it back to the value shown here to unlock. On a multi-gang module, set the gang's Sensitivity to Blocked instead. Raising Key Sense makes keys less sensitive without locking them. (appAction unit)
• Errors: config_not_allowed, not_found

Fade speed

fade_speed · read only, from the cache · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4

How long a light ramps up and down when switched (in units of 25 ms; 0 = no fade).

• When: Explaining why a light fades in slowly.
• Not when: Changing it: it is set in the app.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: The fade speed is set on the unit's page in the app → Advanced settings. (appAction unit)
• Errors: config_not_allowed, not_found

Presence sensing

presence_sensing · read only, from the cache · IGPH, IGSH

How many detections (Sensitivity, 0–20) within the detection window (Detection Timer, h:min) it takes before the appliance turns on in automatic mode.

• When: Explaining why an AC starts late or not at all when someone enters.
• Not when: Changing it: it is set in the app.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Sensitivity and Detection Timer are set on the unit's page in the app → Advanced settings. The detection window should match the room sensor's wake-up time. (appAction unit)
• Errors: config_not_allowed, not_found

Shutter travel

shutter_travel · read only, from the cache · IGTHX2

Up Time and Down Time (min:sec of full travel), Activating Time (0.1 s before it moves) and Flip Time (0.1 s, tilting the slats).

• When: Explaining a shutter that stops short or overshoots.
• Not when: Changing them: set in the app or by Learn.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Shutter settings are set on the unit's page in the app → Advanced settings; travel times also by Learn on the shutter's page. (appAction unit)
• Errors: config_not_allowed, not_found

Shutter automatic movement

shutter_automatic · read only, from the cache · IGTHX2

Move Time Frame (h:min between automatic light-keeping moves), Auto Movement (seconds per step) and Alignment (0–14 % added to each movement).

• When: Explaining why a shutter moves by itself in Auto or Eco mode.
• Not when: Changing them: set in the app.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Shutter settings are set on the unit's page in the app → Advanced settings; travel times also by Learn on the shutter's page. (appAction unit)
• Errors: config_not_allowed, not_found

Shutter edges and passage

shutter_edges · read only, from the cache · IGTHX2

Ignore Edge (whether the keys keep working at the end of travel) and Passage/Remote (0 window; 1 passage, no remote or automatic down; 2 passage, down only from schedules).

• When: Explaining why a door shutter refuses to close from the app or an automation.
• Not when: Changing them: set in the app.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Shutter settings are set on the unit's page in the app → Advanced settings; travel times also by Learn on the shutter's page. (appAction unit)
• Errors: config_not_allowed, not_found

Shutter LEDs

shutter_leds · read only, from the cache · IGTHX2

Whether the shutter's LEDs are on. The apps disagree on how the register is coded (1 / 2 or 2 / 3), so it is shown as the unit holds it.

• When: Explaining a shutter's LEDs.
• Not when: Changing them: set in the app.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Shutter settings are set on the unit's page in the app → Advanced settings; travel times also by Learn on the shutter's page. (appAction unit)
• Errors: config_not_allowed, not_found

Automatic modes

automatic_modes · read only, from the cache · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGSH, IGTHX2 (per gang)

Whether Auto and Eco mode are allowed on the unit (1 allowed, 4 not; on dimmers and single switches the tens are the power factor).

• When: Explaining why a unit never goes to Auto or Eco.
• Not when: Changing the mode now: use control with set_mode.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Set on the unit's page in the app → Advanced settings. (appAction unit)
• Errors: config_not_allowed, not_found

Safety auto-off in Manual

safety_off_in_manual · read only, from the cache · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGSH (per gang)

Safety Timer (hours in Manual mode before the load turns off; 0 never) and Safety Mode (the mode it falls back to, whether the load stays on, and the timer's unit).

• When: Explaining why a load switched itself off after hours in Manual.
• Not when: Changing it: set in the app.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Set on the unit's page in the app → Advanced settings. (appAction unit)
• Errors: config_not_allowed, not_found

Sleep timer

sleep_timer · read only, from the cache · IGHH, IGHHX1, IGPH, IGSH, IGTHX2

How long after Sleep mode starts the unit turns its load off (a shutter: closes) and goes to Manual (h:min).

• When: Explaining why a light went off a while after Sleep mode.
• Not when: Changing it: set in the app.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Set on the unit's page in the app → Advanced settings. (appAction unit)
• Errors: config_not_allowed, not_found

After a power cut

after_power_cut · read only, from the cache · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGSH, IGTHX2 (per gang)

What the unit does when mains power returns: off, on or as before, in which mode, and whether its own schedules stay on.

• When: Explaining why lights came on (or stayed off) after a power cut.
• Not when: Changing it: set in the app.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Set on the unit's page in the app → Advanced settings. (appAction unit)
• Errors: config_not_allowed, not_found

House-wide "all off"

all_off_group · read only, from the cache · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGTHX2 (per gang)

The unit's house group: whether it follows the house-wide all-off (e.g. 250 all lights, 251 all shutters, 252 all power units; 170 outside the global group).

• When: Explaining why a unit didn't follow (or followed) a house-wide all off.
• Not when: Changing it: set in the app. A sense switch's register is disputed and isn't shown.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Set on the unit's page in the app → Advanced settings. (appAction unit)
• Errors: config_not_allowed, not_found

Load calibration

load_calibration · read only, from the cache · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGSH (per gang)

How the unit measures and drives its load: Low Current (+ Scale), Power Factor, Dimmable, Min Dim Level, Gate Time, Min and Max Switch; a sense switch's On Level and Load Type.

• When: Explaining a power reading or a dimming range.
• Not when: Changing them: installer settings.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: An installer setting, on the unit's page in the app → Advanced settings. Wrong values can damage the load or the unit. (appAction unit)
• Errors: config_not_allowed, not_found

Protection

protection · read only, from the cache · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGSH, IGTHX2

The unit's own protection: Max Temp (°C cutoff), Max Load and Min Load (raw), and the load check.

• When: Explaining why a unit turned off by itself and alerted.
• Not when: Changing them: installer settings.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: An installer setting, on the unit's page in the app → Advanced settings. Wrong values can damage the load or the unit. (appAction unit)
• Errors: config_not_allowed, not_found

IR binding

ir_binding · read only, from the cache · IGPH, IGSH

The IR emitter a power or sense switch drives and its channels.

• When: Explaining how an appliance is driven by IR.
• Not when: Changing it: set in the app.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: IR remotes are set up in the app (Add device → IR). (appAction unit)
• Errors: config_not_allowed, not_found

Side buttons

side_buttons · read only, from the cache · IGHHX2, IGHHX3, IGHHX4

A module's side scene buttons: whether they are off, and whether each responds (left, right).

• When: Explaining a module's side buttons.
• Not when: Configuring them: never through the API.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Side buttons are set up in the app, on the module's Side buttons screen. (appAction unit.buttons)
• Errors: config_not_allowed, not_found

Groups and sensor bindings

groups_and_sensors · read only, from the cache · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGSH

The unit's group code (set when it was added; it ties the unit to a group and a sensor), and a module's sensor.

• When: Explaining which sensor drives a unit.
• Not when: Changing it: set when the unit is programmed.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: Groups and sensors are bound when units are added in the app. (appAction unit)
• Errors: config_not_allowed, not_found

Protocol

protocol · read only, from the cache · IGHH, IGHHX1, IGHHX2, IGHHX3, IGHHX4, IGPH, IGSH, IGTHX2

How the unit talks to the gateway: Acknowledge Control, instant reporting, a module's number of switches and switch-on speed.

• When: Explaining slow or missing state reports.
• Not when: Changing them: installer settings.
• Side effects: None.
• Value: the values as the unit holds them
• Instead: An installer setting, on the unit's page in the app → Advanced settings. Wrong values can damage the load or the unit. (appAction unit)
• Errors: config_not_allowed, not_found

Examples

How is the kitchen light set up?

GET /v1/devices/8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light/intents

Answer 200:

{
  "house": "Cohen Home",
  "device": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light",
  "model": "IGHH",
  "access": "read_write",
  "intents": [
    {
      "intent": "single_touch",
      "title": "Single touch",
      "access": "read_write",
      "value": true,
      "source": "cache",
      "asOf": 1760780000000
    },
    {
      "intent": "key_immunity",
      "title": "Key Immunity",
      "access": "read_only",
      "value": null,
      "source": "cache",
      "asOf": null,
      "guidance": "Change it on the unit's page in the IGH app.",
      "appAction": "unit.menus"
    }
  ],
  "note": "Values are what the unit last confirmed (source: cache, asOf)."
}

Turn the kitchen light off ten minutes after the room is empty.

PUT /v1/devices/8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light/intents/off_after_no_motion

{
  "value": 10
}

Answer 200:

{
  "house": "Cohen Home",
  "device": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light",
  "intent": {
    "intent": "off_after_no_motion",
    "title": "Off after no motion",
    "access": "read_write",
    "value": 10,
    "source": "cache",
    "asOf": 1760781000000
  }
}

Turn on Key Immunity on the kitchen light.

PUT /v1/devices/8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light/intents/key_immunity

{
  "value": 1
}

Answer 403:

{
  "error": {
    "code": "not_offered",
    "message": "Key Immunity is read-only through the API.",
    "appAction": "unit.menus"
  }
}

What are the unit settings? (the integration has unit settings off)

GET /v1/devices/8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light/intents

Answer 403:

{
  "error": {
    "code": "config_not_allowed",
    "message": "Unit settings are off for this API integration.",
    "appAction": "integrations.record"
  }
}

IGH home API 1.1.0. Generated from the doc source; do not edit.