paperless-telegram-bot
Bot Telegram completo para gestionar Paperless-NGX: subir documentos, buscar con texto completo, administrar metadatos (tags, correspondientes, tipos), revisar bandeja de entrada y descargar archivos hasta 50 MB. Funciona sin interfaz web.
Ficha actualizada 29 sept 2026, 14:13 · upstream 29 sept 2026, 13:39 · release v0.7.0
Qué es paperless-telegram-bot
Descripción editorial construida a partir del repositorio, su documentación y sus señales de mantenimiento.
paperless-telegram-bot es un bot Telegram que integra Paperless-NGX permitiendo la gestión documental completa desde el móvil o escritorio. Permite subir documentos y fotos, buscar en todo el archivo con texto completo, administrar metadatos como tags, correspondientes y tipos de documento mediante teclados interactivos, revisar la bandeja de entrada y descargar archivos originales.
El bot utiliza python-telegram-bot con httpx para I/O asíncrono, implementa caché de metadatos en memoria para minimizar llamadas API, detecta automáticamente el tag de bandeja vía API Paperless (funciona con cualquier idioma o nombre personalizado), maneja duplicados extrayendo y vinculando documentos existentes, e incluye un endpoint /health HTTP para Docker health checks.
Compatible con Paperless-NGX 2.x y 3.x. El contenedor Docker corre como usuario no privilegiado (UID 1000). La configuración se realiza mediante variables de entorno: TELEGRAM_BOT_TOKEN, PAPERLESS_URL, PAPERLESS_TOKEN, TELEGRAM_ALLOWED_USERS para restricción por lista blanca, ALLOW_OPEN_ACCESS para acceso abierto explícito, y opciones para MAX_SEARCH_RESULTS, UPLOAD_TASK_TIMEOUT, REMOVE_INBOX_ON_DONE, INBOX_TAG, DROP_PENDING_UPDATES y LOG_LEVEL.
- Gestionar documentos desde Telegram sin acceder a la interfaz web de Paperless-NGX
- Subir documentos y fotos directamente al archivo con detección automática de duplicados
- Buscar documentos con texto completo paginado mediante teclados interactivos
- Administrar metadatos (tags, correspondientes, tipos) desde el móvil o escritorio
- Revisar bandeja de entrada y marcar documentos como procesados con un toque
- Monitorizar estadísticas del archivo: conteo de documentos, uso de tags y almacenamiento
- Detección automática del tag is_inbox_tag vía API Paperless (funciona con cualquier idioma o nombre)
- Manejo de duplicados extrayendo y vinculando documentos existentes en fallos de subida
- Endpoint /health HTTP para Docker health checks (devuelve 503 degraded si Paperless no responde)
- Contenedor Docker corre como usuario no privilegiado (UID 1000) sin secretos en código
- Caché de metadatos en memoria minimizando llamadas API a Paperless-NGX
- Compatible con Paperless-NGX 2.x y 3.x (ambos formatos de respuesta task-API)
- Requiere lista blanca TELEGRAM_ALLOWED_USERS explícita o ALLOW_OPEN_ACCESS=true para acceso abierto
- Límite de descarga de archivos a 50 MB por Telegram
- Dependencia de Paperless-NGX activo y accesible (el bot no funciona sin él)
- Callback data limitada a 64 bytes en Telegram (prefijos cortos, consultas largas almacenadas server-side)
Capturas del proyecto
Imágenes reales detectadas en la documentación del repositorio.
Perfil de infraestructura
Estimación inicial derivada del repositorio y de los servicios detectados.
Despliegue detectado
Qué señales reales de instalación hemos encontrado.
Usar Docker con imagen drumsergio/paperless-telegram-bot:v0.7.0 o manual con pip install -e .; configurar TELEGRAM_BOT_TOKEN, PAPERLESS_URL, PAPERLESS_TOKEN y TELEGRAM_ALLOWED_USERS (o ALLOW_OPEN_ACCESS=true); puerto 8080 para /health.
Stack y dependencias
Componentes inferidos a partir de manifests, configuración y documentación.
Puede sustituir a
Relaciones detectadas por el análisis del repositorio y su categoría.
Experiencia real de la comunidad
Ayuda a contrastar la estimación automática con instalaciones reales.
Todavía no hay datos comunitarios para este proyecto.