Skip to content

What is a function?

A function is a recipe that turns some named values (its parameters) into a shell command. Every button in your menu names exactly one function in its function field.

Think of a function as a fill-in-the-blanks command. A "disk usage" function has one blank — the path — and you fill it in on each button.

What happens when you tap a button

  1. The bot looks up the function named in the button's function field.
  2. It collects the values written on that button.
  3. It builds one shell command from those values.
  4. It runs the command in the shell and sends the output back to the chat as a code block.

If the function does not exist, or a value it needs is missing, the bot never starts: validate reports the problem first.

A worked example

The command function is built in and always available. It runs whatever you write in the button's command field.

Use the built-in command function

Uptime button
- name: Uptime
  type: button
  function: command
  command: "uptime"

Tap Uptime and the bot runs uptime on the server and sends the output back.

Passing values from a button

Write each value directly on the button. There are two ways to do this:

  1. Use the shortcut fields command, path, and args. Each fills the parameter with the same name.
  2. For any other parameter, use its name as a key on the button.

Pass a URL by its parameter name

Check API button
- name: Check API
  type: button
  function: curl-url
  url: "https://example.com/health"

Here url matches the url parameter declared by curl-url. The same rule works for names such as host, unit, and lines.

Do not put values inside params:

params: belongs in a custom function file, where it declares the values that function accepts. On a button, write each value directly:

Values belong directly on the button
- name: Nginx logs
  type: button
  function: journal-unit
  unit: "nginx.service"
  lines: 100

Numeric YAML values do not need quotes.

validate checks every key against the parameters declared by the selected function. A misspelling or undeclared name fails validation. It also checks values declared as int or bool. Optional values use their defaults when the button leaves them out.

Two kinds of function

Functions either ship inside the program or come from a YAML file you keep on the server. They behave the same way once a button uses them.

Built-in Custom
Where it comes from Ships inside the program A YAML file you write
Do you create a file? No Yes, one file per function
Names Reserved (command, script) Any name that is not reserved
Always available? Yes Only if you set function_directory
Editable? No Yes, they are your files

You can mix both kinds freely in the same menu. Most menus start with command buttons only; move to custom functions when you notice yourself repeating the same command with a small change.

Built-in functions

Two functions are always loaded, even when you do not set a function_directory. Their command, path, and args fields go straight on a button.

Function What it does Required Optional
command Runs one shell command as written command —
script Runs a script file with arguments path args

Both names are reserved. A custom function file may not reuse them: the loader stops with an error such as function name "command" is reserved, and the bot does not start.

Custom functions

A custom function is a single YAML file that describes one reusable command. Keep those files in a folder of your own and point function_directory at it.

Tell the bot where your function files live

config.yaml
function_directory: "./functions"

The bot reads that folder when it starts, including sub-folders, and picks up every .yaml and .yml file in it. Other files are ignored.

The release archive already contains a functions/ folder with five examples you can use as they are:

Function What it does Button values
Echo Script Runs a script through Bash path, optional args
Disk path Shows disk usage optional path
Curl URL Fetches a URL url
Ping Host Pings a host host, optional count
Journal Unit Shows recent service logs unit, optional lines

To write your own, start with File structure or follow the step by step guide.

Check what got loaded

List every function the bot can see
./telegram-commander list-functions --config config.yaml

Built-in functions show source=builtin; custom ones show the file they came from.

Safety notes

Buttons run with the bot's privileges

Commands run with the privileges of the account running the bot. If that is root (the default service setup), buttons can do anything on the host. Only add allowed users you trust.

Parameter values are inserted into the command as text. Treat them like shell input: prefer fixed values on buttons, and add confirm: true to anything destructive.

Long output is cut and split

Commands stop at their timeout, and the bot keeps at most max_output_bytes of their output. Anything longer than one Telegram message arrives as several messages. See Configuration → How much command output you see.