Collect one closed field at the moment it matters

Seven presentations, two result shapes

text, textarea, password, phone

Return one string inside the declared length bounds.

select, choice

Return one declared option value. Select is a dropdown; choice is a radio group.

choices

Returns a list of unique declared option values inside min_selections/max_selections.

Import InputRequest, text, and, for option controls, InputOption from shimpz. Every title, description, label, placeholder, and option label or description is shimpz.text request copy; option values stay canonical and are never translated. Declare each exact kind, such as input:text, in the Action's human_requests list.

text

Use for one short identifier, hostname, label, or other bounded value.

resource = ctx.request_input(
    InputRequest(
        kind="text",
        title=text("Identify the resource"),
        description=text("Enter the exact resource name to inspect."),
        label=text("Resource name"),
        placeholder=text("api.example.com"),
        min_length=3,
        max_length=253,
    )
)

textarea

Use for a bounded explanation or note where line breaks help the human communicate clearly.

note = ctx.request_input(
    InputRequest(
        kind="textarea",
        title=text("Describe the incident"),
        description=text("Add the context needed to prepare the response."),
        label=text("Incident context"),
        min_length=20,
        max_length=2000,
    )
)

password

Use only for a third-party credential intentionally delegated to this Assistant. The value is masked and is never a Shimpz Account password or Local Supervisor password. Every password request names a declared Stored Input with stored_input="<id>": Team keeps the value encrypted under that Team as soon as the person enters it, never asks for it again, and never gives it to the Action. Instead, Team places it where the Stored Input's placement says in every ctx.fetch call to that host that its reviewed routes admit. An Action may declare several Stored Inputs, such as an access token and an app secret; request them together with ctx.request_stored_inputs(...), which asks for each missing one in turn and returns once Team holds all of them. Call ctx.reject_stored_input(id) for exactly the value the provider rejected; Team deletes only that one and the next run asks for it again. Uninstalling the Assistant or deleting the Team removes them. Every Stored Input declares a help-text description and a help_url: wherever Admin asks for the value, and on the Assistant's page, the person reads in their own language what the secret is and how to get it, followed by one link to the page where it is made.

ctx.request_input(
    InputRequest(
        kind="password",
        title=text("Connect the provider"),
        description=text("Provide the third-party API secret for this connection."),
        label=text("Provider API secret"),
        min_length=1,
        max_length=256,
        stored_input="provider-api-key",
    )
)

# Team holds the key now and places it in every call to its declared host.
response = await ctx.fetch("GET", "https://api.example.com/v1/status")

phone

Use for one phone number. The specialized control helps entry; your Action still owns domain-specific parsing.

phone = ctx.request_input(
    InputRequest(
        kind="phone",
        title=text("Choose an escalation contact"),
        description=text("Enter the phone number that should receive this escalation."),
        label=text("Escalation phone"),
        placeholder=text("+1 415 555 0100"),
        min_length=7,
        max_length=32,
    )
)

select

Use when several compact options fit naturally in a dropdown.

environment = ctx.request_input(
    InputRequest(
        kind="select",
        title=text("Choose the environment"),
        description=text("Select the one environment this read should inspect."),
        label=text("Environment"),
        options=(
            InputOption("production", text("Production")),
            InputOption("staging", text("Staging")),
        ),
    )
)

choice

Use when the human should compare all mutually exclusive options and their descriptions at once.

mode = ctx.request_input(
    InputRequest(
        kind="choice",
        title=text("Choose the DNS mode"),
        description=text("Select exactly one routing behavior."),
        label=text("Mode"),
        options=(
            InputOption("proxied", text("Proxied"), text("Route traffic through Cloudflare.")),
            InputOption("dns-only", text("DNS only"), text("Publish only the DNS answer.")),
        ),
    )
)

choices

Use for a bounded set of independent selections. Declare both minimum and maximum intentionally.

channels = ctx.request_input(
    InputRequest(
        kind="choices",
        title=text("Choose notification channels"),
        description=text("Select one or two channels for this incident."),
        label=text("Channels"),
        options=(
            InputOption("email", text("Email")),
            InputOption("sms", text("SMS")),
            InputOption("voice", text("Voice call")),
        ),
        min_selections=1,
        max_selections=2,
    )
)

Reference limits for humans and code generators

• Title 80, description 500, label 80, and placeholder 120 characters, counting each parameter at its declared maximum.
• Maximum value lengths: text 4096, textarea 16000, password 1024, phone 64.
• Option controls require 2–32 unique options.
• Option value 128, label 80, and optional description 160 characters.
• required=False permits an empty string for select/choice and zero selections when allowed.