The basic available Controls are:

Control	Description
Divider	Visual separator for grouping controls
Text Field	Single-line input for short text
Text Area	Multi-line input for longer text
Drop Down	Selection from predefined options
Toggle Switch	On/off control for boolean settings
Slider	Numeric value selector with range limits
Condition	Shows/hides controls based on parameter values

Other use-case-specific Controls are available:

Control	Description
Aspect ratio	Selection for image/video dimensions with visual previews

Divider

You can use dividers to visually group or separate controls in ways that are intuitive for users.

Fields

Field	Type	Description	Required
`control`	String	The type of control. For a divider, control is always "divider"	Yes

Example

{
  "control": "divider"
}

Text field

Text fields allow users to enter short text values. They are best suited for single-line inputs like names, keywords, or short commands.

Fields

Field	Type	Description	Required
`control`	String	The type of control. For a text field, control is always "text_field"	Yes
`label`	String	The label text shown above the input field	Yes
`description`	String	Optional description text shown below the label	No
`parameter_name`	String	Name of the parameter to store the input value	Yes
`default_value`	String	Optional default text for the input field	No
`placeholder`	String	Optional placeholder text shown when field is empty	No

Example

{
  "control": "text_field",
  "label": "Style prompt",
  "description": "Define the visual style for your generated media",
  "parameter_name": "style_prompt",
  "default_value": "",
  "placeholder": "Photorealistic, anime, oil painting, cyberpunk"
}

Text area

Text areas allow users to enter longer text content. They are best suited for multi-line inputs like descriptions, prompts, or detailed instructions.

Fields

Field	Type	Description	Required
`control`	String	The type of control. For a text area, control is always "text_area"	Yes
`label`	String	The label text shown above the text area	Yes
`description`	String	Optional description text shown below the label	No
`parameter_name`	String	Name of the parameter to store the input value	Yes
`default_value`	String	Optional default text for the text area	No
`placeholder`	String	Optional placeholder text shown when field is empty	No

Example

{
  "control": "text_area",
  "label": "Negative prompt",
  "description": "Enter content you want to exclude from generation",
  "parameter_name": "negative_prompt",
  "default_value": "",
  "placeholder": "Low quality, blurry, distorted"
}

Drop down

Dropdowns allow users to select from a predefined list of options. They are ideal for scenarios where users need to choose one option from a limited set of choices.

Fields

Field	Type	Description	Required
`control`	String	The type of control. For a dropdown, control is always "drop_down"	Yes
`label`	String	The label text shown above the dropdown	Yes
`description`	String	Optional description text shown below the label	No
`parameter_name`	String	Name of the parameter to store the selected value	Yes
`default_value`	String	Optional default selected value	No
`options`	Array	List of Options, which are value-name pairs representing the available options	Yes

Option fields

Field	Type	Description	Required
`value`	String	The internal value that will be stored in the parameter	Yes
`name`	String	The display text shown to users in the dropdown menu	Yes

Each option in the options array must be an object containing both a value and name. The value is what gets stored in the parameter and used by your bot's logic, while the name is what's displayed to users in the UI.

Example

{
  "control": "drop_down",
  "label": "Model",
  "description": "Select your preferred AI model",
  "parameter_name": "model",
  "default_value": "gpt4o",
  "options": [
    {"value": "gpt4o", "name": "GPT-4o"},
    {"value": "claude4", "name": "Claude 4"},
    {"value": "llama4", "name": "Llama 4"}
  ]
}

Toggle switch

Toggle switches allow users to turn options on or off. They are ideal for boolean settings or enabling/disabling features.

Fields

Field	Type	Description	Required
`control`	String	The type of control. For a toggle switch, control is always "toggle_switch"	Yes
`label`	String	The label text shown next to the toggle switch	Yes
`description`	String	Optional description text shown below the label	No
`parameter_name`	String	Name of the parameter to store the boolean value	Yes
`default_value`	Boolean	Optional default state of the toggle (true/false)	No

Example

{
  "control": "toggle_switch",
  "label": "Enable creative mode",
  "description": "Generate more imaginative and diverse AI responses",
  "parameter_name": "creative_mode_enabled",
  "default_value": true
}

Slider

Sliders allow users to select a numeric value within a specified range. They are ideal for settings that require numerical input within defined boundaries.

Fields

Field	Type	Description	Required
`control`	String	The type of control. For a slider, control is always "slider"	Yes
`label`	String	The label text shown above the slider	Yes
`description`	String	Optional description text shown below the label	No
`parameter_name`	String	Name of the parameter to store the numeric value	Yes
`default_value`	Number	Optional default position of the slider	No
`min_value`	Number	Minimum value of the slider range	Yes
`max_value`	Number	Maximum value of the slider range	Yes
`step`	Number	Increment between values on the slider	Yes

Example

{
  "control": "slider",
  "label": "Thinking budget",
  "description": "Select the complexity level for your AI's reasoning",
  "parameter_name": "thinking_budget",
  "default_value": 50,
  "min_value": 10,
  "max_value": 100,
  "step": 5
}

Conditional

Conditionals are control wrappers that dynamically hide or show other Controls based on parameter values.

Fields

Field	Type	Description	Required
`control`	String	The type of control. For a conditional, control is always "condition"	Yes
`condition`	Object	Contains the comparison logic (ComparatorCondition)	Yes
`controls`	Array	List of controls to show/hide based on the condition	Yes

Condition

Field	Type	Description	Required
`comparator`	String	The type of comparison. Currently only "equals" is supported	Yes
`left`	Object	Left side of comparison (LiteralValue or ParameterValue)	Yes
`right`	Object	Right side of comparison (LiteralValue or ParameterValue)	Yes

Parameter Value

Field	Type	Description	Required
`parameter_name`	String	Name of the parameter whose value to use	Yes

Literal Value

Field	Type	Description	Required
`literal`	String, Number, or Boolean	The literal value to use in the comparison	Yes

Example

{
  "control": "condition",
  "condition": {
    "comparator": "equals",
    "left": {
      "parameter_name": "output_type"
    },
    "right": {
      "literal": "image"
    }
  },
  "controls": [
    {
      "control": "slider",
      "label": "Image Width",
      "parameter_name": "width",
      "min_value": 256,
      "max_value": 1024,
      "step": 64,
      "default_value": 512
    }
  ]
}

In this example, the slider control for image width is only shown when the output_type parameter equals "image". The condition can compare either literal values or parameter values on both sides of the comparison.

Aspect ratio

The aspect ratio control lets users choose from predefined aspect ratios with visual previews for easy comparison—especially useful for image and video generation bots.

Fields

Field	Type	Description	Required
`control`	String	The type of control. For aspect ratio, control is always "aspect_ratio"	Yes
`label`	String	The label text shown above the aspect ratio selector	Yes
`description`	String	Optional description text shown below the label	No
`parameter_name`	String	Name of the parameter to store the selected aspect ratio	Yes
`default_value`	String	Optional default selected aspect ratio	No
`options`	Array	List of AspectRatioOptionDefinition objects representing the available options	Yes

AspectRatioOptionDefinition

Field	Type	Description	Required
`width`	Number	The width value for the aspect ratio	Yes
`height`	Number	The height value for the aspect ratio	Yes
`value`	String	The value to be passed when the option is selected. If not defined, a string with the following format will be passed as the value: `[width]:[height]` (e.g. “16:9”)	No

Example

{
  "control": "aspect_ratio",
  "label": "Aspect ratio",
  "description": "Select the aspect ratio for your generated image",
  "parameter_name": "aspect_ratio", 
  "default_value": "square",
  "options": [
    {"value": "square", "width": 1, "height": 1},
    {"value": "landscape", "width": 16, "height": 9},
    {"value": "portrait", "width": 9, "height": 16}
  ]
}

The aspect ratio control will display a visual preview of each ratio option to help users understand the proportions they're selecting.