Bot Outputs - lil'bots Docs

Outputs are the bots way to communicate information back to the user. They are the main method for displaying the results of the bots work back to the user. In designing bots, we strive to provide user with helpful formatting and a rich expirience. To that end, little bots support a wide variety of output types that are rendered into different UIs. This document will cover how to return outputs, as well as the different types of supported bot outputs.

Returning Outputs

Outputs are returned from the bot’s main function, by a simple return statement at the end of the function. The return value can be either a single output, or an array of outputs. The following example shows a bot that returns a single output:

export async function main(inputs, params, accouunts) {
    //... your bot's logic here
    return {
        "type": "text",
        "message": "Hello, World!"
    }
}

Returning a single object will return one output from the bot. Alternatively, you can return an array of objects to retuen multiple outputs, which may have different types:

export async function main(inputs, params, accouunts) {
    //... your bot's logic here
    return [{
        "type": "text",
        "message": "Hello, World!"
    },{
        "type": "table",
        "rows": [
            {"name": "John", "age": 42},
            {"name": "Jane", "age": 35}
        ]
    }]
}

Each output is an object with standard properties, as well as type-specific properties. We will cover the standard properties first, and then the type-specific properties.

Standard Output Properties

type (string, optional)

The type of output. See the next section for a list of supported types. If not supplied, type will be infered based on type specific keys.

title (string, optional)

The title of the output. This is used in the UI to display the output. It is recomended to give your outputs meaningful titles.

description (string, optional)

A description of the output. This is used in the UI to display the output. It is recomended to give your outputs meaningful descriptions.

Output Types

Text Output

Type: text

{
    "type": "text",
    "message": "Hello, World!"
}

The text output is used to present a simple string to the user. It’ll be rendered as a simple text message in the UI.

Markdown Output

Type: markdown

{
    "type": "markdown",
    "markdown": "#Hello, World!"
}

The markdown output is used to present rich text to rhe user. Your string will be parsed as markdown and rendered in the UI, including titles, lists, links and other markdown features. The markdown output is rendered using react-markdown and is 100% compliant with the CommonMark standard.

Table Output

Type: table

{
    "type": "table",
    "rows": [
        {"name": "John", "age": 42},
        {"name": "Jane", "age": 35}
    ]
}

The table output is used to present tabular data to the user. It’ll be rendered as a table in the UI. The rows array should contain objects. Each key in the object will be a column in the table, and the value will be the value of that column in the row. You can control which columns are showed and in what order using the optional columns parameter.

If you don’t specify the columns parameter, all keys in the first row will be used as columns.
If you pass an array of strings, these will be the keys used as columns.
Optionally, you can pass an array of objects, each containing key and title - to give a nicer title to the columns. This will map the keys in the rows to the titles in the columns.

{
    "type": "table",
    "columns": ["name", "age"],
    "rows": [
        {"name": "John", "age": 42},
        {"name": "Jane", "age": 35}
    ]
}

{
    "type": "table",
    "columns": [
        {"key": "name", "title": "User Name"},
        {"key": "age", "title": "User Age"}
    ],
    "rows": [
        {"name": "John", "age": 42},
        {"name": "Jane", "age": 35}
    ]
}

File Output

Type: file

{
    "type": "file",
    "file": "path/to/file"
}

The file output is used to present a file to the user. The file will be downloaded by the user when they view the output. The file path should be relative to the bot’s root directory. When the bot finished executing, the bot runtime will identify the file output and uplaod the file to a temporary location. The file will be available for download for the user for several days. Note that the file will be deleted after a few days, so you should not rely on the file being available for a long time. All file types are supported, and a file icon will be presented to the bot user based on the file mime type.

Image Output

Type: image

{
    "type": "image",
    "file": "path/to/image", //OR
    "url": "https://example.com/image.png"
}

For image outputs, you must explicitly specify "type": "image", otherwise they will be treated as a file output.

JSON Output

Type: json

{
    "type": "json",
    "json": {"name": "John", "age": 42}
}

The JSON output is used to present a JSON object to the user. It’ll be printed in the UI as a JSON string with proper indentation. The JSON output is particularly useful for debugging, as it allows you to print the value of a variable to the UI.

Logs

Your bot can also print logs while it’s running. Just use the standard log function in your bots runtime. Anything printed to stdout or stderr will be streamed to the UI live while the bot is running. Logs are useful when building and debugging bots, and they are also a great way to communicate progress to the user while the bot is running as they are streamed live.

Creating Good Outputs

When designing your bot, you should strive to create outputs that are easy to read and understand. The following are some tips for creating good outputs:

Use Meaningful Titles and Descriptions

When creating outputs, you should always give them meaningful titles and descriptions. This will help the user understand what the output is about, and will make it easier for them to find the output later.

Ordering Outputs

Outputs are presented in an accordion, with the first output expanded by default and all other outputs collapsed by default. Thus, the first output should be the “main” output of your bot, and the rest should be supporting outputs. For instance, if your bot generates and executes a SQL query, the first output should be the results of the query, and the second output should be the query itself (which isn’t the main output of the bot, but may sometimes be useful).

Use The Right Data Type

We offer multiple output types to help create the right user experience for any data. Try to use the right output type for your data. Some examples:

If you are returning a list of items, use the table output, don’t just print them as a comma separated list.
If you are generating an image, use the image output - don’t just return the link to the image as text.
If you are returning a JSON object, use the JSON output - don’t just print it as a string.
If you are returning longer text, format it with markdown instead of just returning plain text.

Don’t Use Logs for Output

Logs are great for debugging and for communicating process, but they should not be used to pass outputs. They are not a convinient way for users to see outputs, and logs are not always available after the bot finishes running. For instance, when triggering a bot from a webhook, the logs are not sent back to the user, so any log output cannot be used by the user calling the webhook.

​Returning Outputs

​Standard Output Properties

​type (string, optional)

​title (string, optional)

​description (string, optional)

​Output Types

​Text Output

​Markdown Output

​Table Output

​File Output

​Image Output

​JSON Output

​Logs

​Creating Good Outputs

​Use Meaningful Titles and Descriptions

​Ordering Outputs

​Use The Right Data Type

​Don’t Use Logs for Output

Returning Outputs

Standard Output Properties

type (string, optional)

title (string, optional)

description (string, optional)

Output Types

Text Output

Markdown Output

Table Output

File Output

Image Output

JSON Output

Logs

Creating Good Outputs

Use Meaningful Titles and Descriptions

Ordering Outputs

Use The Right Data Type

Don’t Use Logs for Output