# Bot API de Telegram y MAX para tu agente de IA (/es/docs/bot-api)

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](https://core.telegram.org/bots/api) y [MAX Bot API](https://dev.max.ru/docs-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](#qué-puede-hacer-un-bot)
2. [Qué añade la CLI a la Bot API](#qué-añade-la-cli-a-la-bot-api)
3. [Diferencias entre Telegram y MAX](#diferencias-entre-telegram-y-max)
4. [Conecta el bot](#conecta-el-bot)
5. [Da una tarea al agente](#da-una-tarea-al-agente)
6. [Envía un mensaje tú mismo](#envía-un-mensaje-tú-mismo)
7. [Antes de automatizar](#antes-de-automatizar)
8. [Cuándo usar la API completa](#cuándo-usar-la-api-completa)

## Qué puede hacer un bot [#qué-puede-hacer-un-bot]

| Tarea | Telegram | MAX |
| --- | --- | --- |
| Enviar, responder, editar, borrar y fijar mensajes, con Markdown o HTML | Sí | Sí |
| Enviar archivos, fotos y mensajes de voz | Sí | Sí |
| Ver mensajes nuevos, ediciones, botones pulsados, entradas y salidas | Sí | Sí, y mensajes borrados |
| Responder a botones, definir el menú de comandos, configurar un webhook | Sí | Sí |
| Nombrar y quitar administradores con los permisos que elijas; expulsar o bloquear miembros | Sí | Sí |
| Ver la lista de miembros de un grupo | No: la Telegram Bot API no lo permite | Sí, 100 por página |
| Añadir miembros a un grupo | No: la Telegram Bot API no lo permite | Sí, mientras el servidor de MAX lo acepte |
| Responder en los comentarios de las publicaciones de un canal | No | Sí |
| Revisar un grupo según tus reglas y quitar lo que las incumple | Sí | Sí |
| Leer y buscar lo que el bot envió y recibió | Sí | Sí |
| Importar mensajes antiguos | Canales y supergrupos | Sí |

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 [#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 [#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](/llms.mdx/docs/es/tg/bot/content.md) · [bots de MAX](/llms.mdx/docs/es/max/bot/content.md).

## Conecta el bot [#conecta-el-bot]

Primero crea un bot: en Telegram con [BotFather](https://t.me/BotFather) y en MAX en [business.max.ru](https://business.max.ru/self). Las guías de [Telegram](/llms.mdx/docs/es/tg/bot/content.md) y [MAX](/llms.mdx/docs/es/max/bot/content.md) explican cada paso. Guarda después su token mediante la entrada oculta del terminal:

```sh
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 (Una clave secreta que permite al programa actuar como tu bot. Es independiente del acceso a tu cuenta personal; guárdala con el comando de configuración del bot.) 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:

```sh
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 [#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.

```text prompt
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](/llms.mdx/docs/es/tg/bot/content.md) o [MAX](/llms.mdx/docs/es/max/bot/content.md).

## Envía un mensaje tú mismo [#envía-un-mensaje-tú-mismo]

```sh
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 [#antes-de-automatizar]

Da al perfil del bot solo los [permisos](/llms.mdx/docs/es/configuration/content.md#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 [#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.

```sh
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](/llms.mdx/docs/es/agents/content.md#mcp-y-skills) ofrece herramientas para tareas comunes. Un agente con terminal puede usar ambas interfaces.

[Configuración y tareas del bot de Telegram](/llms.mdx/docs/es/tg/bot/content.md) · [MAX](/llms.mdx/docs/es/max/bot/content.md). Métodos oficiales: [Telegram](https://core.telegram.org/bots/api) y [MAX](https://dev.max.ru/docs-api).
