To define your parameter controls, you will create a JSON object that describes the desired UI and the corresponding parameters that the bot can accept as user input.

The are four basic building blocks:

• Controls
• Parameters
• Sections
• Tabs

Controls

The base building block is the Control. Controls describe individual UI elements that accept user input; like everything in the Parameter Controls API, they are described by JSON objects.

The basic available Controls are:

Other use-case-specific Controls are available:

Parameters

Parameters store the user input captured by Controls. Every Control has an associated Parameter, and the name of this Parameter is specified using the parameter_name property on the JSON description of the Control.

Controls may optionally specify a default value to store in their associated Parameter. If a default value is not provided, a default value will be inferred. Multiple controls are allowed to share the same parameter_name, but if they do they must all use the same default value.

When a user submits a message, their configured parameters are included in the ProtocolMessage object like this:

{
	"some_text_parameter": "some value", 
	"some_number_paramter": 123, //some value
}

This lets your bot easily access both the message content and parameter values in a structured way.

Some things to consider:

• Parameters included in the parameter dictionary on ProtocolMessages do not have to come from the Poe UI.
• Bots calling other Bots through the Bot Query API can include arbitrary parameters in the parameter dictionary.
• The parameter dictionary might include parameters not defined in your parameter_controls setting.
• Parameters included in the parameter dictionary can have any type and might have unexpected values.

Parameter naming

• Only alphanumeric characters and underscores (_) are allowed
• Parameters cannot contain hyphens (-)
• Parameters cannot start with "poe_" as this prefix is reserved
• Style suggestions:
  • Parameter names should be descriptive and indicate their purpose
  • Use lowercase letters and underscores for readability (e.g., image_size, output_format)
    
    

Examples of valid parameter names:

user_preference
imageSize
quality_level
output_format_1

Examples of invalid parameter names:

poe_setting      // Starts with reserved prefix
image-size      // Contains hyphen
$special        // Contains special character

Sections

Sections group Tabs and Controls into collapsible accordion cards for visual organization. This grouping helps users by clustering controls that are related or manage specific aspects of your bot.

Fields

Example

{
  "name": "Image Generation",
  "controls": [
    {
      "control": "slider",
      "label": "Image Width",
      "parameter_name": "width",
      "min_value": 256,
      "max_value": 1024,
      "step": 64
    }
  ],
  "collapsed_by_default": false
}

Note: A section must contain either controls or tabs, but cannot contain both. At least one of these fields must be present.

Tabs

Tabs group Controls together and live under Sections. They provide a convenient way to organize a long list of controls when you don't want to display them all simultaneously.

Fields

Example

{
  "name": "Advanced Settings",
  "controls": [
    {
      "control": "slider",
      "label": "Quality",
      "parameter_name": "quality",
      "min_value": 1,
      "max_value": 10,
      "step": 1,
      "default_value": 5
    },
    {
      "control": "toggle_switch",
      "label": "High Resolution Mode",
      "parameter_name": "high_res",
      "default_value": false
    }
  ]
}

Tabs must contain at least one control. They provide a way to organize related controls into separate views that users can switch between.