Metadata-Version: 2.4
Name: pypi-bot-telegram
Version: 0.1.2
Summary: Modulo reutilizable para enviar mensajes y archivos a Telegram mediante la Bot API.
Author: hec
License: GPL-3.0
Project-URL: Repository, https://gitlab.com/hecdelatorre/bot-telegram
Keywords: telegram,bot,notifications,files
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

# 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:

```bash
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:

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

- `token`: token del bot proporcionado por [@BotFather](https://t.me/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:

    ```bash
    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:

```bash
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:

```bash
python3 test_file_telegram.py
```

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

```python
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):

```python
from bot_telegram import send_telegram_message

send_telegram_message("Hola desde el bot")
```

**Capturando el booleano**:

```python
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**:

```python
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**:

```python
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**:

```python
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)
```

