paperless-telegram-bot 0.6.2

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

Docker Compose

services:
  paperless-telegram-bot:
    image: drumsergio/paperless-telegram-bot:latest
    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 -r requirements.txt
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.

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. When empty, the bot accepts messages from anyone (not recommended for production).
• 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.