Synology API Telegram Bot

June 3, 2026 · View on GitHub

A Telegram bot to control your Synology NAS via the synology-api library.

Features

  • 24 Synology modules — 740+ API functions (FileStation, Docker, DownloadStation, Surveillance...)
  • File Browser — explore folders, search files, download files directly in Telegram
  • Argument collection — the bot asks for required parameters step by step
  • Access control — only whitelisted Telegram users can interact with the bot
  • Secure — NAS password via SYNOLOGY_PASSWORD env var or config file, config stored outside repo
  • aiogram 3.x — modern async Telegram Bot API with FSM per-chat state

Premises

  • Python 3.9+ is required.
  • You should know how Telegram bots work — create one via @BotFather first.
  • This bot is not a finished product. It works, but I can't guarantee it will handle every edge case. Use it at your own discretion.
  • You're expected to know some Python. Please do your research before opening issues — but feel free to reach out with real concerns.
  • The code still has room for polish. Contributions are welcome.

Quick Start

git clone https://github.com/N4S4/synology-api-telegram-bot.git
cd synology-api-telegram-bot
pip install -r requirements.txt

# Edit the hardcoded values in synology_api_telegram_bot/main_bot.py:
#   _HARDCODED_TOKEN = "YOUR_BOT_TOKEN_HERE"   → your real token
#   _HARDCODED_USERS = "159718277"             → your Telegram user ID
# Then run:
python -m synology_api_telegram_bot.main_bot

Configuration

Bot credentials: Edit the hardcoded values at the top of synology_api_telegram_bot/main_bot.py:

  • _HARDCODED_TOKEN — bot token from @BotFather
  • _HARDCODED_USERS — comma-separated Telegram user IDs (get yours from @userinfobot)

These values are baked into the source. Environment variables (TELEGRAM_TOKEN, ALLOWED_USERS) take priority if set, but the compose file does not inject them — the hardcoded values are authoritative.

NAS connection: Stored in ~/.config/synology-bot/config.json (outside the repo for security), configured interactively via /start.

Usage

General workflow

  1. Send /start to your bot on Telegram
  2. Configure your NAS: IP, port, username, password, etc.
  3. Click Finish Configuration
  4. Choose a module (e.g., core_sys_info, docker_api)
  5. Click login to authenticate
  6. Select a function — the bot will ask for arguments if needed
  7. Results are returned as formatted JSON

Commands

CommandDescription
/startShow configuration menu
/helpShow help and workflow
/statusShow connection status and config validation
/cancelCancel current operation (arg collection, search, config)

File Browser (filestation module)

Select filestation from the module list to access a visual file browser:

ActionDescription
📂 Browse FilesBrowse folders starting from /home. Tap 📁 folder to enter, ⬆ Back to go up, 🏠 Home to reset.
🔍 Search FilesSearch files by pattern (e.g., *.py, backup*). Choose /home or type a custom path. Results are clickable.
📥 DownloadDownload a selected file. The bot sends it as a Telegram document (max 50 MB).
ℹ️ File InfoShow file metadata: path, size, owner, modification date.
📋 All FunctionsAccess the raw 48 FileStation API functions with the standard keyboard.

Access Control

The bot uses ALLOWED_USERS to whitelist Telegram user IDs. Anyone not in the list gets:

⛔ User not recognized.
OUT OF MY STUFF!
Device auto-destruction ACTIVATED!
Your device CPU will burn in 1 minute. 🔥

Set it in main_bot.py to lock everyone else out:

_HARDCODED_USERS = "159718277"
# or multiple users:
_HARDCODED_USERS = "159718277,123456789"

Docker

Edit _HARDCODED_TOKEN and _HARDCODED_USERS in main_bot.py first, then:

docker compose build --no-cache
docker compose up -d

Or with plain docker run (env vars override hardcoded values if you prefer):

docker build -t synology-telegram-bot .
docker run \
  -e TELEGRAM_TOKEN="your_token" \
  -e ALLOWED_USERS="your_telegram_id" \
  -e SYNOLOGY_PASSWORD="your_pass" \
  synology-telegram-bot

Modules Available

CategoryModules
FileFileStation, Drive Admin, USB Copy
SystemSystem Info, LogCenter, Security Advisor, Universal Search
UsersUser management, Group management, Shared Folders
NetworkDHCP Server, Directory Server, OAuth, VPN
BackupActive Backup for Business, Backup & Restore, Snapshot
MediaAudioStation, DownloadStation, NoteStation, Photos
ContainersDocker / Container Manager, Virtual Machine Manager
SecuritySurveillance Station (329 functions)
CloudCloud Sync

Configuration

Configuration is stored in ~/.config/synology-bot/config.json (outside the repo for security).

Consider My Work

This project takes time and effort to maintain. If you find it useful or fun, please consider supporting it:

License

MIT