indigo_2025.1_documentation:substitutions []

This is an old revision of the document!

One of Indigo's powerful features is substitutions. Substitutions are special codes that are used to reference other Indigo objects – like devices, variables, and events – to get values related to them. For example, you might used a variable substitution to get the current value of the variable you're referencing. All substitution expressions have a similar format:

Object	Substition String	Example	Target
Devices	%%d:DEVICEID:STATEID%%	%%d:12345678:onOffState%%	the current onOffState of device 12345678
Variables	%%v:VARIABLEID%%	%%v:234566789%%	the current value of variable 234566789
Timestamps	%%t:"FORMATSTRING"%%	%%t:"%Y-%M-%D %H:%M"%%	the current time based on the provided `datetime` format specifier `“%Y-%M-%D %H:%M”`
Events	%%e:"PATH"%%	%%e:"a-list.[2].dict-in-list"%%	replaces the specified path string `“a-list.[2].dict-in-list”`with the corresponding value from the related `event_data`

Substitutions are used extensively throughout Indigo and Indigo Plugins. For example, you can use a device or variable substitution as a part of a Control Page Refreshing URL input like this: http://www.example.com/images/%%v:2345678%%.jpg which will substitute the current value of variable 2345678 as the image filename. While available in a wide array of instances, substitutions are not universally supported. You should confirm that substitutions are supported in each instance before attempting to use them.

Device Substitutions

Device substitutions allow you to reference a particular state's current value of the target device. Device states can have different value types – like strings, numbers, booleans, etc. – so it's important to ensure that the substitution will return a value type appropriate to your use case.

Substition String	Example	Target
%%d:DEVICEID:STATEID%%	%%d:12345678:onOffState%%	the current onOffState of device 12345678
Example	Result
%%d:12345678:brightnessLevel%%	100 (integer)
%%d:12345678:onOffState%%	on (on/off boolean)
%%d:12345678:hvacFanModeIsAuto%%	true (boolean)

Variable Substitutions

Variable substitutions allow you to reference the current value of the target variable. Since variables values are always strings, a variable substitution will always return a string.

Substition String	Example	Target
%%v:VARIABLEID%%	%%v:234566789%%	the current value of variable 234566789
Example	Result
%%v:12345678%%	“My variable value”
%%v:2345678%%	“Another value”

Timestamp Substitutions

Timestamp substitutions allow you to reference the current date/time based on the provided format specifier. There is a considerable number of online resources that explain the various datetime format specifiers. Do a search for “python datetime format specifiers” (there are some differences between programming languages, so be sure to search for *python* specifiers.

Substition String	Example	Target
%%t:"FORMATSTRING"%%	%%t:"%Y-%M-%D %H:%M"%%	the current time based on the provided `datetime` format specifier `“%Y-%M-%D %H:%M”`
Example	Result
%%t:"%Y-%m-%d %H:%M"%%	“2025-10-22 13:03”
%%t:"%Y-%m-%d"%%	“2025-10-22”
%%t:"%H:%M:%S"%%	“13:03:49”

Event Substitutions

Event substitutions allow you to reference a particular data element of an event-data payload. Event substitutions are somewhat of a special case and have a separate page dedicated to them.

Substition String	Example	Target
%%e:"PATH"%%	%%e:"a-list.[2].dict-in-list"%%	replaces the specified path string `“a-list.[2].dict-in-list”`with the corresponding value from the related `event_data`

Plugin Substitutions

Many Indigo plugins support substitutions– plugin developers are encouraged to make it clear where substitutions are permitted and to explain how they're used in the plugin's documentation.