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; 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
│   └── 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)