Saltar a contenido

Menú

Su menú es un árbol de nodos bajo la clave raíz menu. Hay dos tipos de nodo:

Si estos términos son nuevos para usted, lea primero Conceptos. Para consultar la lista exacta de todos los campos, consulte Configuración → Menú.

Un menú plano

El menú más sencillo es una lista de botones sin anidamiento:

Crear un menú con tres botones

Tres botones sin categorías
menu:
  - name: Uptime
    type: button
    function: command
    command: "uptime"

  - name: Free memory
    type: button
    function: command
    command: "free -h"

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

Envíe /start en Telegram para ver el menú.

Agrupar con categorías

A medida que crezca el menú, agrupe las acciones relacionadas en categorías. Al tocar una categoría se muestran sus items. Inicio siempre está visible y Atrás solo aparece dentro de una categoría.

Agrupar botones en categorías

Categorías System y Services
menu:
  - name: System
    type: category
    icon: "💻"
    items:
      - name: Uptime
        type: button
        function: command
        command: "uptime"

      - name: Free memory
        type: button
        function: command
        command: "free -h"

  - name: Services
    type: category
    icon: "🔧"
    items:
      - name: Restart nginx
        type: button
        function: command
        command: "systemctl restart nginx"
        confirm: true

Las categorías pueden anidarse sin límite y deben contener al menos un elemento.

Los nombres deben ser únicos entre hermanos

Dos nodos del mismo padre no pueden compartir nombre, sin distinguir mayúsculas. Sí pueden usar el mismo nombre en categorías distintas:

Reutilizar un nombre bajo padres distintos

El mismo nombre bajo dos elementos superiores
menu:
  - name: Web
    type: category
    items:
      - name: Restart          # válido
        type: button
        function: command
        command: "systemctl restart nginx"
  - name: Database
    type: category
    items:
      - name: Restart          # válido, padre diferente
        type: button
        function: command
        command: "systemctl restart postgresql"

Iconos

icon es un emoji opcional delante del nombre y solo tiene efecto visual.

Este botón reinicia la máquina

Un botón con un icono emoji
- name: Reboot
  type: button
  icon: "🔁"
  function: command
  command: "reboot"
  confirm: true

Elija un emoji sencillo y común

Algunos emoji hacen que ciertos teléfonos corten el texto. Si ocurre, pruebe otro emoji.

Aspecto del menú de Telegram

Todos los botones aparecen en el teclado bajo el cuadro de mensajes, el que se muestra y se oculta con el pequeño botón situado en el extremo derecho del cuadro. Este teclado ocupa siempre todo el ancho del chat, por lo que el texto de los botones no queda apretado ni cortado.

  • Inicio es siempre el primer botón de cada pantalla. Tóquelo para volver a la primera pantalla.
  • Atrás aparece dentro de una categoría.
  • $ >_ Run Command aparece si enable_run_command está activado (consulte más abajo).
  • Los elementos aparecen dos por fila de forma predeterminada. Una categoría puede cambiarlo con columns. Si una pantalla tiene muchos elementos, Prev y Next permiten recorrer sus páginas.
  • Los botones con confirm: true preguntan Sí / Cancelar antes de ejecutarse.

Los títulos se reutilizan y la salida permanece

Cada nuevo título del menú —Inicio, una categoría o una página— sustituye al anterior para no llenar el chat de pantallas vacías. La línea Running y la salida del comando permanecen, por lo que podrá seguir viendo qué se ejecutó después de volver a abrir el menú.

Los resultados se quedan como mensajes o llegan como archivo

La salida corta del comando se queda en el chat como bloque de código. Un resultado más largo puede llegar en varios mensajes de respuesta o como un único archivo .txt, según output. El último mensaje, o el archivo, conserva los botones de la página en la que se encontraba, por lo que Atrás sigue saliendo de esa categoría. Consulte Controlar la salida.

Confirmación

Añada confirm: true a cualquier botón para exigir un segundo toque («¿Está seguro?») antes de ejecutarlo. Úselo para cualquier acción destructiva. Consulte Confirmación.

Este botón detiene un servicio

Un botón que pregunta primero
- name: Stop nginx
  type: button
  function: command
  command: "systemctl stop nginx"
  confirm: true

La pregunta caduca tras 5 minutos de forma predeterminada. Cambie confirm_ttl en Configuración → Campos raíz.

Sustituciones por botón

Algunos ajustes globales se pueden sustituir en un botón:

Dar ajustes propios a un botón

Un botón con su propio tiempo, carpeta y variables
- name: Long backup
  type: button
  function: command
  command: "/usr/local/bin/backup.sh"
  timeout: "10m"          # puede tardar más que el tiempo límite global
  workdir: "/var/backups" # ejecutar aquí
  env:
    BACKUP_MODE: "full"   # variable de entorno adicional para este comando

Consulte Configuración → Menú.

Controlar la disposición

menu_columns define cuántos botones de elementos aparecen por fila (2 de forma predeterminada). Una categoría puede sustituirlo con columns. Si un menú tiene más elementos que page_size (8 de forma predeterminada), se divide en páginas y se muestran Prev y Next hasta llegar a los extremos. Consulte Configuración → Campos raíz.

Ejecutar comando

Con enable_run_command: true en la raíz de la configuración, el botón $ >_ Run Command permanece en el menú: aparece después de Atrás dentro de una categoría o después de Inicio en la primera pantalla. Tóquelo y envíe el comando de shell que quiera ejecutar. El bot usa el mismo shell, tiempo máximo, directorio de trabajo y ajustes de salida que los demás botones. Ejecutar comando no tiene un output propio, por lo que siempre sigue el de la raíz.

Inicio o Atrás cancelan la petición sin ejecutar nada. Esta opción está desactivada de forma predeterminada. Consulte Configuración → Campos raíz.

Esto entrega el control de toda la máquina

Cualquier usuario permitido podrá ejecutar cualquier comando, no solo los botones definidos. Actívelo únicamente si confía plenamente en todos.

Un comando cada vez

Sus comandos se ejecutan uno tras otro, no en paralelo.

Un segundo toque espera su turno

Si toca otro botón mientras el primero sigue en ejecución, el segundo espera y después se ejecuta por separado. Verá su línea Running cuando se inicie. Así se evita que dos acciones suyas interfieran sobre el mismo servicio o archivo. Los comandos de otras personas no quedan bloqueados: cada una tiene su propio turno.

Qué se ejecuta al tocar un botón

Cada botón señala una función mediante su campo function. Los ejemplos anteriores usan la función integrada command. Para conocer las funciones integradas y personalizadas y aprender a crear las suyas, consulte Funciones.

Páginas relacionadas