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_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 obtiene las credenciales exclusivamente de variables de entorno. No hay ningún archivo de configuración en el repositorio.

Exporta las variables antes de usar el paquete:

export TELEGRAM_TOKEN="TU_TOKEN_DE_TELEGRAM"
export TELEGRAM_CHAT_ID="TU_CHAT_ID"

También puedes cargarlas desde un archivo .env (no se sube al repo, está en el .gitignore):

source .env && export TELEGRAM_TOKEN TELEGRAM_CHAT_ID

con el .env en este formato:

TELEGRAM_TOKEN=TU_TOKEN_DE_TELEGRAM
TELEGRAM_CHAT_ID=TU_CHAT_ID

• TELEGRAM_TOKEN: token del bot proporcionado por @BotFather.
• TELEGRAM_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 úsalo como variable de entorno:

   export TELEGRAM_TOKEN="tu_token_aqui"
   

⚠️ 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.

Guarda ese número en la variable de entorno TELEGRAM_CHAT_ID.

3. Verificar

Con las variables de entorno exportadas, prueba enviar un mensaje:

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

Debes recibir True y el mensaje en Telegram.

Uso

Las tres funciones del paquete (send_telegram_message, send_telegram_file y enviar_archivo) solo retornan un booleano:

• True → el envío a Telegram fue correcto.
• False → no se pudo enviar (credenciales faltantes, archivo inexistente, sin permisos, timeout, fallo de conexión, respuesta no 200 de Telegram, etc.).

No imprimen nada en pantalla. Quien las use decide qué hacer con el resultado (log, reintento, alerta, etc.).

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")

Ejemplos de uso con cada salida

Ignorando el resultado (no se hace nada si falla):

from bot_telegram import send_telegram_message

send_telegram_message("Hola desde el bot")

Capturando el booleano:

from bot_telegram import send_telegram_message

ok = send_telegram_message("Hola desde el bot")
if ok:
    print("Mensaje enviado")
else:
    print("Fallo el envio")

Reaccionando a cada salida:

from bot_telegram import enviar_archivo

if enviar_archivo("/ruta/reporte.pdf", "Reporte diario"):
    print("Reporte entregado a Telegram")
else:
    raise RuntimeError("No se pudo entregar el reporte")

Reintentando ante fallo:

import time
from bot_telegram import send_telegram_file

for intento in range(3):
    if send_telegram_file("/ruta/datos.csv"):
        break
    time.sleep(5)

Registrando el resultado en un log:

import logging
from bot_telegram import send_telegram_message

logging.basicConfig(filename="envios.log", level=logging.INFO)

if send_telegram_message("Proceso finalizado"):
    logging.info("Telegram: envio OK")
else:
    logging.error("Telegram: envio fallido")

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 (lee TELEGRAM_TOKEN / TELEGRAM_CHAT_ID del entorno)
│   └── enviar_archivo.py    # función enviar_archivo(ruta, texto="")
├── test_file_telegram.py    # script interactivo que pide ruta y texto
└── .env                      # credenciales locales (ignorado, no se publica)