Button

A tappable item in the Telegram menu. A button has a name and, when tapped, runs a function on your server and sends the result back to the chat.

Buttons and categories together form the menu tree under the top-level menu key in your config file. A button does the work; a category only opens a submenu.

What a button looks like

Buttons appear on the keyboard under the message box, two per row by default. The name you choose is the text on the key, so keep it short enough to read on a phone. See Menu → How the Telegram menu looks.

The parts of a button

Every line controls one part of the button

One button, fully labelled

- name: Restart nginx # (1)!
  type: button # (2)!
  icon: "🔄" # (3)!
  function: command # (4)!
  command: "systemctl restart nginx" # (5)!
  confirm: true # (6)!

1. The text on the key in Telegram. It must be unique among its neighbours in the same menu.
2. Always button here. Use category instead when you want a submenu.
3. Optional emoji shown before the name. It is decoration only and changes nothing about what runs.
4. Which function to use. command is the built-in one that runs a shell command.
5. What the command function runs. Anything you could type in a terminal works here.
6. Optional. Ask "Are you sure?" before running. Leave it out for anything that only reads.

What happens when you tap it

1. The bot posts a short Running line so you know it started.
2. The command runs on the machine where the bot is running.
3. The output comes back as a code block, with the exit code and how long it took. Short output stays in the chat as one or more messages; longer output can arrive as a .txt file (see Long results as a file).
4. You stay on the same menu you were on, so Back still leaves that category.

Common buttons

Check somethingManage a serviceRead a logRun a scriptSomething destructive

Uptime button

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

Restart nginx button

- name: Restart nginx
  type: button
  icon: "🔄"
  function: command
  command: "systemctl restart nginx"

Nginx log button

- name: Nginx log
  type: button
  function: command
  command: "journalctl -u nginx -n 50 --no-pager"

Nightly backup button

- name: Nightly backup
  type: button
  function: script
  path: "/usr/local/bin/backup.sh"

Stop nginx button

- name: Stop nginx
  type: button
  icon: "🛑"
  function: command
  command: "systemctl stop nginx"
  confirm: true

Icons

icon puts an emoji in front of the name. It is purely cosmetic, so you can change or remove it at any time without touching what the button runs.

An icon only changes the label

The same button, with and without an icon

- name: Disk usage
  type: button
  function: command
  command: "df -h"

- name: Disk usage
  type: button
  icon: "💾"
  function: command
  command: "df -h"

Ask before risky buttons

Add confirm: true and the bot asks Yes or Cancel first. Use it for anything that stops a service, deletes data, or reboots the machine. The prompt expires after a while (five minutes by default).

Read Confirmation for when it is worth asking and how to change the waiting time.

Settings for one button only

Most global settings can be overridden on a single button, which is handy when one job behaves differently from the rest:

Override settings for one slow job

A slow job that runs somewhere else

- name: Long backup
  type: button
  function: command
  command: "/usr/local/bin/backup.sh"
  timeout: "10m"
  workdir: "/var/backups"
  env:
    BACKUP_MODE: "full"

timeout gives this one command longer to finish, workdir chooses the directory it runs in, and env adds environment variables just for it.

Long results as a file

You do not need output on a button. If you omit it, the button uses the root setting (auto unless you changed it): a short result stays as chat messages, and a result that would need more than two messages arrives as one .txt file. Write output on a button only when that one button should always send a file or always stay as text. max_output_messages cannot be set on a button.

Set output: file on a button that always prints a lot (for example logs), or output: text to keep the old split-message behaviour for that button only.

The root keys output and max_output_messages are documented under Configuration → How much command output you see. Control output walks through every root and button combination with an example each.

Values for the function

Write function values directly on the button. command, path, and args are shortcut fields for parameters with those names. Custom names such as url, host, unit, and lines work in the same way.

Pass custom values

Recent Nginx logs

- name: Nginx logs
  type: button
  function: journal-unit
  unit: "nginx.service"
  lines: 100

Do not put these values inside params:. Every key must match a parameter declared by the selected function. validate reports unknown names, missing required values, and invalid int or bool values.

Configuration

For every field a button accepts, see Configuration → Menu.

Related

• Category

  ---

  Opens a submenu instead of running something.

  Category

• Function

  ---

  What actually runs when a button is tapped.

  Function

• Parameter

  ---

  Values a function needs from the button.

  Parameter

• Menu

  ---

  Build and organise the whole tree.

  Menu

• Control output

  ---

  Messages versus a .txt file, and how a button can override the root.

  Control output