Uso con tu agente

Bot API de Telegram y MAX para tu agente de IA

Usa un bot de Telegram o MAX con tu agente de IA o la terminal mediante la Bot API: envía mensajes y archivos, gestiona eventos y ayuda con tareas de grupo.

Usa un bot a través de tu agente o la terminal para responder peticiones, publicar novedades o ayudar con un grupo. Conéctalo y comprueba su acceso antes de tu primera tarea. Un bot tiene su propia cuenta, nombre y permisos. No obtiene acceso a tus conversaciones privadas, y los comandos sin bot siguen usando tu cuenta personal.

Bot API es la forma oficial de controlar un bot de Telegram o MAX desde un programa: Telegram Bot API y MAX Bot API. Las herramientas de línea de comandos tg y max la cubren entera: los 185 métodos de Telegram y las 33 operaciones de MAX. Además añaden lo que la API oficial no tiene: una copia de los mensajes del bot en la que puedes buscar, moderación del grupo según tus reglas y límites sobre dónde puede escribir el bot. Pide a tu agente que use el bot o ejecuta los comandos tú.

En esta página:

  1. Qué puede hacer un bot
  2. Qué añade la CLI a la Bot API
  3. Diferencias entre Telegram y MAX
  4. Conecta el bot
  5. Da una tarea al agente
  6. Envía un mensaje tú mismo
  7. Antes de automatizar
  8. Cuándo usar la API completa

Qué puede hacer un bot

TareaTelegramMAX
Enviar, responder, editar, borrar y fijar mensajes, con Markdown o HTMLSíSí
Enviar archivos, fotos y mensajes de vozSíSí
Ver mensajes nuevos, ediciones, botones pulsados, entradas y salidasSíSí, y mensajes borrados
Responder a botones, definir el menú de comandos, configurar un webhookSíSí
Nombrar y quitar administradores con los permisos que elijas; expulsar o bloquear miembrosSíSí
Ver la lista de miembros de un grupoNo: la Telegram Bot API no lo permiteSí, 100 por página
Añadir miembros a un grupoNo: la Telegram Bot API no lo permiteSí, mientras el servidor de MAX lo acepte
Responder en los comentarios de las publicaciones de un canalNoSí
Revisar un grupo según tus reglas y quitar lo que las incumpleSíSí
Leer y buscar lo que el bot envió y recibióSíSí
Importar mensajes antiguosCanales y supergruposSí

Un bot solo ve lo que el servicio de mensajería le muestra, y para hacer cambios en un grupo necesita permisos de administrador. Las respuestas automáticas continuas necesitan un programa que siga en marcha y gestione los eventos; un comando aislado no lo inicia.

Qué añade la CLI a la Bot API

  • Un historial en el que buscar. La Telegram Bot API no permite leer mensajes antiguos. La CLI guarda en tu ordenador lo que el bot envía y recibe, así que tú y tu agente podéis listar, buscar y ver quién escribió qué. También puede importar mensajes antiguos.
  • Moderación del grupo según tus reglas. Guardas las reglas del grupo una vez. El bot revisa los mensajes nuevos con ellas, muestra lo que haría y solo actúa como las reglas permiten.
  • Límites de escritura. Cada bot tiene una lista de chats en los que puede escribir, un límite por hora opcional y un registro de cada escritura. El registro nunca guarda el texto del mensaje. Estos límites también se aplican a la API completa.
  • Un token protegido. El token se guarda en el llavero del sistema y nunca se muestra, ni siquiera en los mensajes de error.
  • Varios bots. Cada bot tiene su propio nombre de perfil, la primera palabra del comando: tg sales bot …, tg support bot ….
  • Resultados que un programa puede usar. --json da datos limpios y códigos de salida claros. Si la conexión se corta durante un envío, la CLI no vuelve a enviar: informa de que el resultado es desconocido, para que compruebes el chat antes.
  • Una conexión para tu agente. tg <bot> bot mcp serve y max <bot> bot mcp serve dan el bot a una aplicación de agente solo con los permisos que tú definas.

Diferencias entre Telegram y MAX

  • Telegram: una persona debe iniciar el bot antes de que este pueda escribirle. En un grupo, un bot que no es administrador solo ve los comandos y las respuestas dirigidas a él, salvo que se desactive el modo de privacidad en BotFather.
  • MAX: solo las organizaciones verificadas, los empresarios individuales y los autónomos registrados pueden crear un bot, y cada bot pasa una moderación. Un bot solo puede unirse a grupos después de que lo permitas en los ajustes de privacidad del bot en business.max.ru.

Todos los comandos y límites: bots de Telegram · bots de MAX.

Conecta el bot

Primero crea un bot: en Telegram con BotFather y en MAX en business.max.ru. Las guías de Telegram y MAX explican cada paso. Guarda después su token mediante la entrada oculta del terminal:

tg support bot auth set
max support bot auth set

support es el nombre que eliges para el perfil del bot. Ejecuta el comando de tu servicio de mensajería. Es preferible introducir el token tú mismo en la entrada oculta del terminal. Puedes elegir compartirlo con tu agente, pero quedará en el historial del chat con el agente. No lo incluyas en argumentos de comandos ni capturas. Comprueba qué bot está conectado:

tg support bot me
max support bot me

Deberías ver el nombre y el identificador de tu bot. Añádelo al grupo o canal elegido, o inicia una conversación privada con él. En Telegram, el usuario debe iniciar la conversación antes de que el bot pueda escribirle.

Da una tarea al agente

El ejemplo usa el perfil support del bot de Telegram. Para MAX, cambia «Usa tg CLI» por «Usa max CLI» e indica su perfil de bot. En un chat del navegador, nombra la herramienta de bot conectada.

Petición
Usa tg CLI con el bot support conectado: comprueba su identidad y los eventos a los que tiene acceso. Propón cómo preparar un informe para mi grupo. Muestra el chat elegido y redacta un borrador. No envíes nada todavía.

El agente debe mostrar el bot, el chat y el borrador. Revisa el texto y el destinatario y autoriza el envío por separado. Encontrar chats y enviar: Telegram o MAX.

Envía un mensaje tú mismo

tg support bot messages send "Equipo" "El informe está listo"
max support bot messages send "Equipo" "El informe está listo"

Sustituye chat y texto por el mensaje deseado. Es un envío real desde el bot. El bot también puede enviar archivos, responder mensajes y gestionar chats si tiene los derechos necesarios. No le concedas derechos de administrador para acciones que no los requieren.

Antes de automatizar

Da al perfil del bot solo los permisos necesarios y decide sus destinatarios. Revisa los mensajes importantes antes de enviarlos. Webhooks y consultas de actualizaciones alimentan otras aplicaciones; cambiarlos puede interrumpir una integración existente.

Cuándo usar la API completa

Las tareas habituales tienen comandos cómodos como bot messages send. Para operaciones menos comunes está la Bot API nativa completa de Telegram y de MAX.

tg support bot api --help
max support bot api --help
tg support bot api get-me --json
max support bot api get-my-info --json

La ayuda de cada método explica sus campos. Los nombres y entradas siguen la API del proveedor. La API completa está en la línea de comandos; MCP ofrece herramientas para tareas comunes. Un agente con terminal puede usar ambas interfaces.

Configuración y tareas del bot de Telegram · MAX. Métodos oficiales: Telegram y MAX.