companion-actions

Define actions inside an UpdateActions function that calls self.setActionDefinitions with CompanionActionDefinition objects. Each action needs a name, an options array of input fields, and a callback that receives a CompanionActionEvent with user-configured option values.

The SomeCompanionActionInputField union covers textinput, number, dropdown, checkbox, colorpicker, multidropdown, bonjourdevice, static-text, and custom-variable. Every field requires id, type, and label, with type-specific extras like min/max for number and choices for dropdown.

Use subscribe and unsubscribe for stateful actions that need setup or teardown tied to button usage, such as starting polling when an action is added to a button and stopping it when removed. The plain callback still fires on each button press.

Actions are not re-registered automatically, so you must call UpdateActions(self) again after connection or capability changes. Forgetting this leaves stale option lists and outdated action definitions in the UI.

Mark callbacks as async, await device calls, and wrap them in try/catch blocks that log failures via self.log('error', ...). Avoid long synchronous operations, since blocking the callback degrades the module's responsiveness.