PaperValet

PaperValet

English | 中文

A production-grade Telegram userbot built with gotd/td — pure Go MTProto, no CGO.

Clean modular architecture, 15 built-in plugins, and a hot-loadable external plugin ecosystem.

Quick Start

curl -fsSL https://raw.githubusercontent.com/PaperValet/PaperValet/master/scripts/install.sh | bash

The installer asks for your api_id, api_hash (from my.telegram.org) and phone number, installs to ~/.papervalet, then:

~/.papervalet/run.sh    # enter the Telegram code, done

Send .ping to yourself in any chat — the bot answers 🏓 Pong!.

Full walkthrough including systemd and Docker: Installation Guide.

Built-in Plugins

External Plugins

Third-party plugins live in the separate PaperValet-Plugins repo (21 available) and install with one command:

.apt install weather

Writing your own: Plugin SDK / 中文版.

Configuration

config.json (generated by the installer, see config.example.json):

{
  "telegram": {
    "api_id": 12345,
    "api_hash": "your_api_hash",
    "session_file": "session.json",
    "database_file": "sessions.db"
  },
  "bot": {
    "command_prefix": ".",
    "plugins_dir": "plugins",
    "owner_id": 0
  },
  "logger": {
    "level": "INFO",
    "format": "console"
  }
}

• command_prefix — command trigger (default .)
• owner_id — Telegram user ID for owner-only commands (0 = first logged-in user)
• logger.level — DEBUG, INFO, WARN, ERROR

Headless / Container Login

Architecture

cmd/papervalet/       entry point
internal/
  app/                orchestrator + auth + update handler
  command/            parser, registry, middleware
  config/             JSON config with defaults
  eventbus/           priority pub/sub
  media/              download/upload helpers
  peer/               access hash cache + resolver
  plugin/             manager + .so loader
  session/            SQLite session store
  i18n/               zh-CN / en-US catalogs
plugins/builtin/      compiled-in plugins
pkg/plugin/           PUBLIC SDK for external plugins
pkg/logger/           zap wrapper

Development

go build -o papervalet ./cmd/papervalet   # build
go test ./...                             # test
go vet ./... && golangci-lint run         # lint

Requires Go 1.25+.

License

MIT — see LICENSE.