Adding parameter controls

You can add parameter controls to your bot by setting the parameter_controls property inside the SettingsResponse object (PoeBot:get_settings method in the fastapi_poe API) to a JSON object that uses the API described in the previous sections.

The parameter controls system uses the following JSON structure to define its controls and settings:

Fields

Field	Type	Description	Required
`api_version`	String	Version of the Parameter Controls schema. This matches the Poe Protocol response version. Currently only "2" is supported	Yes
`sections`	Array	List of Section objects that define the UI structure	Yes

The schema shows that Sections are the fundamental building blocks - they act as containers that organize all other controls. Every interface must have at least one Section to function properly.

Here's a practical example showing how to create a server bot with parameter controls. This example creates a 'Generation' section containing two dropdown menus:

class ImageBot(PoeBot):
 		
 		async def get_settings(self, setting: SettingsRequest) -> SettingsResponse:
        return SettingsResponseWithCustomUI(
            enable_multi_bot_chat_prompting=True,
            allow_attachments=True,
            enable_image_comprehension=False,
            custom_ui_definition={
                "api_version": "0",
                "sections": [
                    {
                        "name": "Generation",
                        "controls": [
                            {
                                "control": "drop_down",
                                "label": "Style",
                                "parameter_name": "style",
                                "default_value": "GENERAL",
                                "options": [
                                    {"name": "General", "value": "GENERAL"},
                                    {"name": "Realistic", "value": "REALISTIC"},
                                    {"name": "Design", "value": "DESIGN"},
                                    {"name": "3D render", "value": "RENDER_3D"},
                                    {"name": "Anime", "value": "ANIME"},
                                ],
                            },
                            {
                                "control": "drop_down",
                                "label": "Aspect ratio",
                                "parameter_name": "aspect",
                                "default_value": "1:1",
                                "options": [
                                    {"name": "16:9 (Horizontal)", "value": "16:9"},
                                    {"name": "16:10", "value": "16:10"},
                                    {"name": "3:2", "value": "3:2"},
                                    {"name": "4:3", "value": "4:3"},
                                    {"name": "1:1 (Square)", "value": "1:1"},
                                    {"name": "9:16 (Vertical)", "value": "9:16"},
                                    {"name": "10:16", "value": "10:16"},
                                    {"name": "2:3", "value": "2:3"},
                                    {"name": "3:4", "value": "3:4"},
                                ],
                            },
                        ],
                    }
                ],
            },
        )

Getting parameter values from a user message

When a user submits a message, any configured parameter values will be included in the ProtocolMessage object within a dedicated parameters field. The parameters field is an object where the parameters will be sent as:

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

This field is sent alongside the standard content field, allowing your bot to access both the user's message content and their parameter configurations in a structured format.

See Parameters for more details about how parameters are sent to the bot.