Metadata-Version: 2.4
Name: pypi-bot-telegram
Version: 0.1.0
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; send_telegram_message('Hola desde mi bot')"
```

Debes recibir el mensaje en el chat indicado.

## Uso

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

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

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

4. Prueba en TestPyPI (opcional):

   ```bash
   ./publish.sh test
   ```

5. Publica en PyPI real:

   ```bash
   ./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`.
