bot_telegram

Bot de Telegram para envío de mensajes y archivos, además de notificaciones (ej. resultados de MLB).

Propósito del proyecto

La idea de este proyecto es ser un módulo reutilizable que cualquier otro proyecto pueda incorporar para enviar información a Telegram, ya sea en forma de texto o de archivos. No es un bot con lógica de conversación propia, sino una capa de envío lista para usarse: se importa telegram_sender.py (o enviar_archivo.py) y se llama a la función correspondiente. Así, otros proyectos (scripts de datos, notificaciones, reportes, automatizaciones, etc.) pueden notificar resultados sin reimplementar la integración con la Bot API.

Límites y tipos de archivo

Telegram impone ciertos límites al enviar archivos por la Bot API:

• Tamaño máximo: hasta 50 MB por archivo cuando se sube directamente por la API (método sendDocument). Archivos mayores no se pueden enviar por este medio.
• Tipos permitidos: sendDocument acepta cualquier tipo de archivo (PDF, TXT, CSV, imágenes, comprimidos, etc.). Si se usa un método específico (no implementado aquí), Telegram distingue:
  • sendPhoto: imágenes (JPG, PNG, GIF, etc.), hasta 10 MB.
  • sendAudio / sendVideo: audio y vídeo, con sus propios límites.
• No hay restricción de extensión al enviar como documento, pero el cliente de Telegram mostrará el archivo según su tipo MIME.

Este proyecto utiliza sendDocument, por lo que puede enviar cualquier archivo de hasta 50 MB sin importar su extensión.

Características

• Envío de mensajes de texto a un chat o usuario mediante la Bot API (sendMessage).
• Envío de archivos (documentos) a Telegram (sendDocument), con un texto opcional de acompañamiento (caption).
• Módulo reutilizable (telegram_sender.py) que cualquier script puede importar para enviar texto o archivos sin repetir la lógica de la API.
• Script interactivo de prueba (test_file_telegram.py) que pide la ruta del archivo y un texto opcional por teclado.
• Manejo de errores ante credenciales faltantes, archivo inexistente, sin permisos, timeout o fallos de conexión.

Dependencias

• Python 3.7+
• requests (para las llamadas HTTP a la Bot API de Telegram)

Instalación:

python3 -m venv env
source env/bin/activate
pip install requests

Estructura

bot_telegram/
├── telegram_config.json   # token + chat_id (NO se sube al repo)
├── telegram_sender.py     # lógica: send_telegram_message() + send_telegram_file()
├── enviar_archivo.py      # función enviar_archivo(ruta, texto="")
├── test_file_telegram.py  # script interactivo que pide ruta y texto
└── README.md

Configuración

El bot requiere un archivo telegram_config.json en la raíz del proyecto con las credenciales de acceso. Este archivo no se sube al repositorio (está en el .gitignore) porque contiene información sensible.

Créalo manualmente con el siguiente contenido:

{
    "token": "TU_TOKEN_DE_TELEGRAM",
    "chat_id": "TU_CHAT_ID"
}

• token: token del bot proporcionado por @BotFather.
• chat_id: identificador del chat o usuario destinatario de los mensajes.

Cómo crear un bot y obtener las credenciales

1. Crear el bot y obtener el token

1. Abre Telegram y busca a @BotFather (el bot oficial de Telegram para crear bots).

2. Envíale el comando /newbot.

3. Responde con el nombre del bot (p. ej. "Mi Bot de Notificaciones").

4. Responde con un username que termine en bot (p. ej. mi_bot_notificaciones_bot).

5. BotFather te devolverá un mensaje con el token de acceso, algo como:

   123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890
   

6. Copia ese token y ponlo en telegram_config.json como "token".

⚠️ El token es la contraseña de tu bot. No lo compartas ni lo subas al repo.

2. Obtener el chat_id (a dónde llegan los mensajes)

El chat_id identifica el chat o usuario que recibirá los mensajes.

• Para enviarte a ti mismo: habla con @userinfobot y te dirá tu chat_id (un número, p. ej. 5299658167).
• Para un grupo: añade el bot al grupo y usa uno de estos métodos:

  • Con curl, tras escribir un mensaje en el grupo:

    curl -s "https://api.telegram.org/bot<TU_TOKEN>/getUpdates" | grep -o '"chat":{"id":[0-9-]*'
    

  • O usa @getidsbot dentro del grupo, que muestra el chat_id.

Pon ese número en telegram_config.json como "chat_id".

3. Verificar

Con el archivo telegram_config.json completo, prueba enviar un mensaje:

python3 -c "from bot_telegram import send_telegram_message; send_telegram_message('Hola desde mi bot')"

Debes recibir el mensaje en el chat indicado.

Uso

Enviar un archivo de forma interactiva:

python3 test_file_telegram.py

Desde otro script (o tras instalar el paquete con pip install pypi-bot-telegram):

from bot_telegram import send_telegram_message, send_telegram_file, enviar_archivo

send_telegram_message("Hola desde el bot")
send_telegram_file("/ruta/al/archivo.pdf", caption="mi archivo")
enviar_archivo("/ruta/al/archivo.pdf", "texto opcional")

Estructura del paquete

bot_telegram/                 # repo
├── pyproject.toml            # metadatos y dependencia requests
├── publish.sh                # script para build + subir a PyPI
├── README.md
├── bot_telegram/             # paquete importable
│   ├── __init__.py           # expone send_telegram_message, send_telegram_file, enviar_archivo
│   ├── telegram_sender.py   # lógica de la Bot API
│   └── enviar_archivo.py    # función enviar_archivo(ruta, texto="")
├── test_file_telegram.py    # script interactivo que pide ruta y texto
└── telegram_config.json      # credenciales locales (ignorado, no se publica)

Publicar en PyPI

El paquete ya tiene pyproject.toml y el script publish.sh. Resumen:

1. Verifica que el nombre pypi-bot-telegram esté libre en https://pypi.org (cámbialo en pyproject.toml si no).

2. Crea un token en https://pypi.org/manage/account/token/ (usuario: __token__).

3. Prepara el entorno:

   python3 -m venv env
   source env/bin/activate
   pip install build twine
   

4. Prueba en TestPyPI (opcional):

   ./publish.sh test
   

5. Publica en PyPI real:

   ./publish.sh
   

⚠️ Antes de publicar, rota el token de Telegram si llegó a estar expuesto en el historial del repo. telegram_config.json no se incluye en el paquete porque está en el .gitignore.