Bot Inputs - lil'bots Docs

At the basis of each bots operation are the inputs it receives from the user to perform its task on. There are generally two types of inputs for a bot:

Parameters: these are configuations that the user can provide for the bot. The user is prompted to configure these when first installing the bot and can also edit them later via settings. Parameters are meant to be static and are not expected to change often. Think of them like bot settings.
Inputs: these are inputs that the user provides to the bot when running it. Inputs are meant to be dynamic and can change each time the bot is run. Think of them like arguments to a function.

The table below summarizes the differences between parameters and inputs:

	Parameters	Inputs
When Configured?	When the user installs the bot, and in the settings page.	Every time the user runs the bot.
Purpose	General settings and configurations for the bot.	Task definition for the bot.

Each bot configures the fields and data types it accepts for both parmaters and inputs in it’s botspec.json file under the params and inputs fields respectively. As the structure for defining parameters and inputs is the same, the rest of this document will refer to both simulanously.

Defining Input fields

The schema for your bots inputs and outputs is defined in the bostpect.json using a JSON Schema object (with several custom extensions we will discuss below). The general structure for fields will look as following:

{
	"runtime": "deno",
	"main": "script.mjs",
	"inputs": {
		"name": {
			"name": "Your Name",
			"description": "The name of the name to greet",
			"type": "string"
		}
	},
	"params": {
		"greeting": {
			"name": "Greeting",
			"type": "string",
			"enum": [
				"Hello",
				"Hi",
				"Hey",
				"Hola",
				"Yo"
			],
			"description": "Your Greeting",
			"errorMessage": {
				"minLength": "greeting is required"
			}
		}
	},
	"accounts": []
}

The key for each input inside it’s object must be unique - and corrosponds to the key that value will have when your bot is called. Each field defined in the in the JSON schema will be rendered into a form element. Regadless of type, each input can have the following properties:

General Field properties

type (required):

Each inpout must specify a type - please refer to the types settings below for a full list of all supported types and the additional configurations they support.

name (optional):

This is the user presentable name of the field, and will appear as the field’s label. If not specified, the key of the field will be used instead.

description (optional):

Description of the field. Will be presented as an explanation text after the field.

required (optional):

Marks a field as required, and disables the ability to run the bot without providing a value for this field. Defaults to false.

default (optional):

The default value for the field. If not specified, the field will be empty by default.

errorMessage (optional):

A map of error messages to display to the user if the input does not match the above criteria. The key of the map should be the name of the error, and the value should be the message to display. If not specified, a default error message will be displayed to the user. These may some times be cryptic, so it’s recommended to always specify a custom error message. See example below:

"inputs": {
	"email": {
		"name": "Your Email",
		"placeholder": "[email protected]",
		"description": "Your email address",
		"type": "string",
		"format": "email",
		"errorMessage": {
			"format": "Input must be an email"
		}
	}
}

Without the custom error message, the user would see the following error message when entering an invalid email address: must match format "email", which is not very helpful.

Data Types

The following list outlines the different types of inputs and parameters that are supported. Please note this list is a subset of all types supported by JSON Schema - so please check here to ensure a type is supported before using it.

string

Use the string type to accept a string value from the user. The following additional optional configurations are supported:

Property	Type	Description
`placeholder`	`string`	The placeholder text to show in the field when it’s empty.
`minLength`	`number`	The minimum length of the string.
`maxLength`	`number`	The maximum length of the string.
`pattern`	`string`	A regular expression that the string must match. See more here.
`format`	`string`	A format that the string must match. See here for a list of supported formats.
`enum`	`string[]`	A list of possible values the string can take on.
`textarea`	`boolean`	If true, the field will be rendered as a larger text area optimized for longer text inputs.

boolean

Use the boolean type to accept a boolean value from the user. The field will be rendered as a toggle. Boolean types have no additional configurations.

number

Use the number type to accept a numeric value from the user. The following additional optional configurations are supported:

Property	Type	Description
`placeholder`	`string`	The placeholder text to show in the field when it’s empty.
`multipleOf`	`number`	Numbers can be restricted to a multiple of a given number. It may be set to any positive number.
`minimum`	`number`	The minimum value of the number. `x ≥ minimum`
`exclusiveMinimum`	`number`	The minimum value of the number. `x > exclusiveMinimum`
`maximum`	`number`	The maximum value of the number. `x ≤ maximum`
`exclusiveMaximum`	`number`	The maximum value of the number. `x < exclusiveMaximum`
`enum`	`number[]`	A list of possible values the number can take on.

integer

Use the integer type to accept an integer value from the user. The following additional optional configurations are supported:

Property	Type	Description
`placeholder`	`string`	The placeholder text to show in the field when it’s empty.
`multipleOf`	`number`	Numbers can be restricted to a multiple of a given number. It may be set to any positive number.
`minimum`	`number`	The minimum value of the number. `x ≥ minimum`
`exclusiveMinimum`	`number`	The minimum value of the number. `x > exclusiveMinimum`
`maximum`	`number`	The maximum value of the number. `x ≤ maximum`
`exclusiveMaximum`	`number`	The maximum value of the number. `x < exclusiveMaximum`
`enum`	`number[]`	A list of possible values the number can take on.

file

Use the file type to accept a file as an input. The user will be able to choose a local file to be uploaded to the bot. The bot runtime will recieve a signed URL where the file can be downloaded from. Note that the files are kept on the server for a limited time (currently 24 hours) and will be deleted after that time. Farthermore, the signedUrl for the file will only be valid for a limited time (roughly 30 minutes) for security reasons. File inputs are thus not suitable for longer term storage of items, but only as a mechanism to transfer a file into the bot ephermally. The following additional optional configurations are supported:

Property	Type	Description
`accept`	`string`	The type of files accepted as a comma seperated list of suffixes (`.svg,.png,.mp3`) or as a comma seperated list of MIME types (`image/png,image/jpeg`). Wildcard MIME types are supported (`image/*`), as well as mixing file suffixes and mime types.

date

Use the date type to accept a date value from the user. The date will be passed to the bot as a string representing the date in ISO 8601 format.

array

Use the array type to accept an array of values from the user. The items property defines the shape of each item - which can be a string, number or any of the other types of inputs mentioned above. The following additional optional configurations are supported:

Property	Type	Description
`items`	`object`	The schema for each item in the array.
`minItems`	`number`	The minimum number of items in the array.
`maxItems`	`number`	The maximum number of items in the array.
`uniqueItems`	`boolean`	If true, all items in the array must be unique.

object

Array types are currently not supported.

Building Bots

​Defining Input fields

​General Field properties

​type (required):

​name (optional):

​description (optional):

​required (optional):

​default (optional):

​errorMessage (optional):

​Data Types

​string

​boolean

​number

​integer

​file

​date

​array

​object