简体中文 | English

NapGram

A modern QQ-Telegram message bridge powered by NapCat and mtcute

✨ Features

• 🚀 Modern architecture: NapCat (QQ) + mtcute (Telegram), Fastify-based backend
• 💬 Full message support: text, images, videos, audio, files, stickers, replies/forwards
• 🛡️ Stability & monitoring: reconnect, recall sync, stats & latency metrics
• 🐳 Docker ready: built-in Web Dashboard served from the container
• Web Dashboard:
• ✅ Built-in in the Docker image (default 8080, visit http://<host>:8080/)
• 📊 Monitoring & statistics (overview, trends, latency)
• ⚙️ Admin operations (instances/pairs/settings, logs & message queries)

🏗️ Tech Stack

🚀 Quick Start

Prerequisites

• Node.js 25+
• PostgreSQL 14+
• NapCat (required): deploy NapCatQQ and enable WebSocket
• Network access from NapGram to NapCat

Docker (Recommended)

Note: NapGram requires connection to a deployed NapCat instance. Please ensure NapCat is running first.

# Clone the repository
git clone https://github.com/NapLink/NapGram.git
cd NapGram

# Copy and edit Docker Compose
cp compose.example.yaml docker-compose.yml
## Edit docker-compose.yml -> services.napgram.environment (required: TG_API_ID / TG_API_HASH / TG_BOT_TOKEN)

docker-compose pull
docker-compose up -d

NapCat Configuration: - Ensure NapCat has WebSocket or HTTP interface enabled - Configure NAPCAT_WS_URL in docker-compose.yml - NapCat and NapGram must be in the same network or accessible to each other

Manual Installation

# Install dependencies
pnpm install

# Build
pnpm --filter=@napgram/app run build

# Start
pnpm --filter=@napgram/app start

📖 Documentation

• GitHub Wiki: https://github.com/NapLink/NapGram/wiki
• Changelog: https://github.com/NapLink/NapGram/wiki/Changelog
• Plugins: https://github.com/NapLink/NapGram/wiki/Operations-Plugins
• Upgrade & Migration (FAQ): https://github.com/NapLink/NapGram/wiki/Operations-Upgrade
• Commands: https://github.com/NapLink/NapGram/wiki/Guide-Commands

📅 Changelog

📝 View Changelog

🎯 Enabled Features

Enabled plugins

• ForwardFeature: forwarding core with dedup & advanced strategies
• RecallFeature: bidirectional recall sync
• MediaFeature: unified media download/transcoding
• CommandsFeature: admin & management commands (send /help for full list)

Commands

See Wiki: https://github.com/NapLink/NapGram/wiki/Guide-Commands

🛠️ Development

# Install dependencies
pnpm install

# Development mode
pnpm --filter=@napgram/app run dev

# Type checking
pnpm --filter=@napgram/app run type-check

# Build
pnpm --filter=@napgram/app run build

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

• Powered by NapCat and mtcute
• Inspired by q2tg
• NapCat TypeScript SDK reference: node-napcat-ts

⚠️ Disclaimer

This project is for educational and personal use only. Please comply with the Terms of Service of QQ and Telegram.

⭐ Star History

📧 Contact

• GitHub Issues: Report a bug
• Telegram: Join discussion (if available)

Made with ❤️ by magisk317