Cap 1: Introducción a los Bots de Telegram

Qué es un bot de Telegram

Un bot de Telegram es una cuenta especial que un programa controla vía la Bot API de Telegram. Los usuarios interactúan con él como si fuera una persona: envían mensajes, usan comandos (/start, /help), y el bot responde.

Casos de uso con Claude

• Asistente personal: preguntas y respuestas con contexto persistente
• Code review: envías código, Claude lo analiza y responde
• Interfaz móvil a Claude Code: ejecutar tareas de desarrollo desde el teléfono
• Bot de equipo: integrar Claude en un grupo de Telegram del equipo

Crear un bot con BotFather

BotFather es el bot oficial de Telegram para crear y gestionar bots.

1. Abre Telegram y busca @BotFather
2. Envía /newbot
3. Elige un nombre visible (ej: “Mi Asistente Claude”)
4. Elige un username que termine en bot (ej: mi_claude_bot)
5. BotFather responde con tu token: 7123456789:AAH...

Guarda ese token — es tu clave de acceso a la Bot API.

Comandos útiles de BotFather:

Comando	Acción
/mybots	Ver tus bots
/setdescription	Descripción del bot
/setcommands	Definir lista de comandos
/setprivacy	Modo privacidad en grupos
/deletebot	Eliminar bot

Polling vs Webhook

Hay dos formas de recibir mensajes de Telegram:

flowchart TD
    subgraph Polling
        BOT_P[Tu bot] -->|GET /getUpdates cada N seg| TG_P[Telegram]
        TG_P -->|mensajes pendientes| BOT_P
    end

    subgraph Webhook
        TG_W[Telegram] -->|POST al recibir mensaje| BOT_W[Tu bot en URL pública]
    end

Polling:

• Tu bot pregunta a Telegram cada pocos segundos: “¿hay mensajes nuevos?”
• Funciona sin URL pública — ideal para desarrollo local
• Más simple de configurar
• Ligero delay y más requests

Webhook:

• Telegram envía el mensaje a tu servidor en tiempo real
• Requiere URL HTTPS pública
• Más eficiente en producción
• Requiere ngrok o similar en desarrollo

Recomendación para este tutorial: polling en desarrollo, webhook en producción.

La Bot API de Telegram

Toda la comunicación pasa por https://api.telegram.org/bot<TOKEN>/método.

Los métodos más usados:

Método	Descripción
getMe	Info del bot
getUpdates	Obtener mensajes (polling)
sendMessage	Enviar texto
sendPhoto	Enviar imagen
sendDocument	Enviar archivo
setWebhook	Configurar webhook
answerCallbackQuery	Responder botones inline

No usaremos la API directamente — python-telegram-bot la envuelve en Python.

Tipos de update

Cuando llega un mensaje, Telegram envía un Update con uno de estos tipos:

mindmap
  root[Update]
    message
      texto
      foto
      documento
      voz
      sticker
    callback_query
      botón inline presionado
    inline_query
      búsqueda inline
    edited_message
      mensaje editado
    channel_post
      mensaje en canal

Privacidad en grupos

Por defecto, los bots en grupos solo ven mensajes que empiezan con / o que los mencionan. Para ver todos los mensajes, desactiva el modo privacidad:

/mybots → Selecciona tu bot → Bot Settings → Group Privacy → Turn off

Considera las implicaciones de privacidad antes de desactivarlo.

Límites importantes de la API

• Mensajes por segundo: máximo 30 mensajes/segundo globales, 1 mensaje/segundo por chat
• Longitud de mensaje: máximo 4096 caracteres (Markdown)
• Tamaño de archivo: máximo 50MB para enviar, 20MB para recibir via bot
• Webhook timeout: Telegram espera respuesta en 60 segundos