drumsergio/paperless-telegram-bot repository overview

Manage Paperless-NGX documents entirely through Telegram.

A full-featured Telegram bot that integrates with Paperless-NGX⁠, giving you complete document management from your phone or desktop -- no web UI required. Upload documents and photos, search your archive with full-text search, manage metadata, review your inbox, and download files, all within Telegram.

⁠Features

• Document Upload -- Send any file or photo to the bot and it gets uploaded to Paperless-NGX automatically. Duplicates are detected and linked.
• Full-Text Search -- Search across all your documents with /search. Results are paginated with inline keyboard navigation.
• Metadata Management -- After uploading (or on any document), assign tags, correspondents, and document types through interactive inline keyboards.
• Inbox Review -- /inbox lists all documents tagged with your inbox tag. Mark them as reviewed with a single tap.
• Document Download -- Download original files directly to Telegram (up to 50 MB).
• Recent Documents -- /recent shows the latest documents added to your archive.
• System Statistics -- /stats displays document counts, tag usage, and storage information.
• Health Endpoint -- Built-in /health HTTP endpoint for Docker health checks and monitoring.
• User Authorization -- Restrict bot access to specific Telegram user IDs via allowlist.
• Non-Root Docker -- Runs as an unprivileged user inside the container.

⁠Quick Start

⁠Docker (Recommended)

docker run -d \
  --name paperless-telegram-bot \
  --restart unless-stopped \
  -e TELEGRAM_BOT_TOKEN=your_bot_token \
  -e PAPERLESS_URL=http://your-paperless:8000 \
  -e PAPERLESS_TOKEN=your_api_token \
  -e TELEGRAM_ALLOWED_USERS=123456789 \
  drumsergio/paperless-telegram-bot:v0.7.0

⁠Docker Compose

services:
  paperless-telegram-bot:
    image: drumsergio/paperless-telegram-bot:v0.7.0
    container_name: paperless-telegram-bot
    restart: unless-stopped
    environment:
      TELEGRAM_BOT_TOKEN: "${TELEGRAM_BOT_TOKEN}"
      PAPERLESS_URL: "http://paperless:8000"
      PAPERLESS_TOKEN: "${PAPERLESS_TOKEN}"
      TELEGRAM_ALLOWED_USERS: "${TELEGRAM_ALLOWED_USERS}"
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')"]
      interval: 30s
      timeout: 5s
      retries: 3

⁠Manual Installation

git clone https://github.com/GeiserX/paperless-telegram-bot.git
cd paperless-telegram-bot
python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env   # Edit with your values
python -m paperless_bot run

⁠Configuration

All configuration is done through environment variables. Copy .env.example to .env for local development.

Compatible with Paperless-NGX 2.x and 3.x (both task-API response formats are handled).

⁠Commands

In addition to commands, you can send any file or photo directly to the bot to upload it to Paperless-NGX. After upload, an interactive keyboard lets you assign tags, a correspondent, and a document type.

⁠Architecture

paperless-telegram-bot
|-- src/paperless_bot/
|   |-- __main__.py         # Entry point, health server, CLI
|   |-- config.py           # Environment variable loading and validation
|   |-- api/
|   |   +-- client.py       # Async Paperless-NGX API client with caching
|   +-- bot/
|       |-- handlers.py     # Command handlers, callback routing, upload flow
|       +-- keyboards.py    # Inline keyboard builders for metadata selection
+-- tests/                  # pytest + respx test suite

Key design decisions:

• Async throughout -- Uses python-telegram-bot with httpx for fully asynchronous I/O.
• Metadata caching -- Tags, correspondents, and document types are cached in memory and refreshed on demand, minimizing API calls.
• Callback data encoding -- Telegram limits callback_data to 64 bytes. All prefixes are kept short (meta:tags:, dl:, sp:, etc.) and long search queries are stored server-side per chat.
• Inbox auto-detection -- The bot reads the is_inbox_tag field from the Paperless API rather than matching by name, so it works with any language or custom tag name.
• Duplicate handling -- Upload failures containing "duplicate" are parsed to extract and link to the existing document.

⁠Security

• User allowlist -- Set TELEGRAM_ALLOWED_USERS to restrict access. An empty allowlist refuses to start unless ALLOW_OPEN_ACCESS=true is set explicitly (running open is not recommended).
• Non-root container -- The Docker image runs as an unprivileged paperlessbot user (UID 1000).
• No secrets in code -- All credentials are loaded from environment variables. Never commit .env files.
• API token scoping -- The bot uses a single Paperless-NGX API token. Create a dedicated user/token with appropriate permissions.

⁠Development

# Install dev dependencies
pip install -e ".[dev]"

# Run linter and formatter
ruff check src/ && ruff format src/

# Run tests
python -m pytest tests/ -v

# Run tests with coverage
python -m pytest tests/ --cov=paperless_bot --cov-report=term-missing

⁠Contributing

Contributions are welcome. Please:

1. Fork the repository
2. Create a feature branch (feat/my-feature or fix/my-bug)
3. Follow the existing code style (enforced by ruff)
4. Add tests for new functionality
5. Submit a pull request

This project follows Conventional Commits⁠ and Semantic Versioning⁠.

⁠Related Projects

⁠License

This project is licensed under the GNU General Public License v3.0⁠.