Configuration Reference
SolsticeIO loads its configuration from environment variables defined in a .env file at the project root or from your system environment at startup through internal/config/config.go.
Required Variables
These environment variables must be defined for the bot to run:
| Variable | Type | Description |
|---|---|---|
BOT_TOKEN | string | Telegram Bot API token obtained from @BotFather |
API_ID | string | Telegram API ID from my.telegram.org |
API_HASH | string | Telegram API Hash from my.telegram.org |
SESSION_STRING | string | Assistant userbot session string (supports GoGram, Pyrogram, and Telethon session formats) used by the assistant to join group voice chats |
MONGO_URI | string | MongoDB connection URI (e.g., mongodb://localhost:27017/solsticeio or mongodb+srv://user:pass@cluster.mongodb.net/solsticeio). Also falls back to MONGO_URL or DATABASE_URL if defined |
OWNER_ID | int64 | Telegram user ID of the bot owner with unrestricted administrative access |
Optional Variables
Bot Identity & Branding
| Variable | Type | Default | Description |
|---|---|---|---|
BOT_NAME | string | SolsticeIO | Bot name displayed in start panels, help menus, and status messages |
UPSTREAM_REPO | string | https://github.com/SolsticeIO/SolsticeIO | Git repository link displayed in information menus |
SUPPORT_CHAT | string | https://t.me/SolsticeIO | Invite link to your community support group |
SUPPORT_CHANNEL | string | https://t.me/SolsticeIO | Link to your updates and announcements channel |
START_IMG_URL | string | (default catbox banner) | Space-separated list of image URLs randomly rotated as start panel and help menu artwork |
FALLBACK_THUMBNAIL | string | (default catbox art) | Fallback image URL when a track does not provide album artwork |
EMOJIS | string | ❤️ 😁 👀 ⚡️ 🕊 ❤️🔥 💅 👻 | Space-separated emojis used for dynamic reactions and cards |
Logging & Diagnostics
| Variable | Type | Default | Description |
|---|---|---|---|
LOGGER_ID | int64 | (none) | Telegram group or channel ID where the bot sends error alerts, crash diagnostics, join/leave logs, and admin actions |
DEVELOPER_MODE | bool | false | When set to true, enables verbose debug logs in stdout |
Embedded Web Server & Web Room
| Variable | Type | Default | Description |
|---|---|---|---|
PORT | string | 8080 | Local port for the embedded HTTP server and WebSocket hub |
WEB_APP_URL | string | (auto) | Public domain or URL for the Web Room interface (e.g. https://music.yourdomain.com). Automatically detects Railway domains (RAILWAY_PUBLIC_DOMAIN) |
WEB_APP_SHORT_NAME | string | (none) | Mini App short name configured in BotFather for direct Telegram web app attachment buttons |
BOT_USERNAME | string | (auto-detected) | Bot's Telegram username for deep links |
Local Bot API Daemon
| Variable | Type | Default | Description |
|---|---|---|---|
ENABLE_LOCAL_BOT_API | bool | true | When running via Docker or start.sh, automatically starts a local telegram-bot-api binary on port 8081 when API_ID and API_HASH are set |
BOT_API_URL | string | http://127.0.0.1:8081 | Telegram Bot API base URL. Defaults to the local server if running, or falls back to https://api.telegram.org |
Text-to-Speech (TTS)
| Variable | Type | Default | Description |
|---|---|---|---|
SMALLEST_API_KEY | string | (none) | API key for Smallest.ai Waves. Delivers ultra-low latency female Hinglish voice synthesis. If unset or quota exhausted, automatically falls back to Google Translate |
Streaming & Proxies
| Variable | Type | Default | Description |
|---|---|---|---|
YTDLP_PROXY | string | (none) | Optional HTTP or SOCKS5 proxy passed to yt-dlp stream extraction workers |
Dynamic YouTube Cookies
YouTube cookies are managed dynamically in MongoDB rather than static files on disk:
- To upload or rotate cookies, send your
cookies.txtfile to the bot in private messages and reply with/setcookies. - To verify cookie validity, send
/checkcookies. - The bot loads cookies into memory instantly without requiring server reboots or file replacements.
Example .env File
ini
# ─── Required Credentials ─────────────────────────
BOT_TOKEN=7123456789:AAH-your-bot-token-here
API_ID=12345678
API_HASH=abcdef1234567890abcdef1234567890
SESSION_STRING=1BVts...your-session-string...
MONGO_URI=mongodb+srv://user:pass@cluster.mongodb.net/solsticeio
OWNER_ID=123456789
# ─── Logging & Telemetry ──────────────────────────
LOGGER_ID=-1001234567890
BOT_NAME=SolsticeIO
SUPPORT_CHAT=https://t.me/SolsticeIO
SUPPORT_CHANNEL=https://t.me/SolsticeIO
# ─── Embedded Web Server ──────────────────────────
PORT=8080
# WEB_APP_URL=https://music.yourdomain.com
# WEB_APP_SHORT_NAME=room
# ─── Speech Synthesis ─────────────────────────────
# SMALLEST_API_KEY=your_smallest_ai_key_here
# ─── Advanced / Local Bot API ─────────────────────
# ENABLE_LOCAL_BOT_API=true
# BOT_API_URL=http://127.0.0.1:8081Per-Chat Settings (Database)
Group administrators can configure these settings dynamically per-chat via bot commands:
| Setting | Command | Options | Purpose |
|---|---|---|---|
| Language | /language | en, es, hi | Changes bot text and button translations for the group |
| Playback Permissions | /playmode | everyone, admin | Restricts queue commands to group admins and DJs |
| Autoplay | /autoplay | Toggle | Auto-queues related songs when the playlist runs dry (auto-expires after 6 hours) |
| Photo Cards | /card | on, off | Shows or hides Now Playing album artwork cards |
| Welcome Messages | /welcome | on, off | Toggles automatic greetings for newly joined members |
| Warn Penalties | /setwarnmode | ban, mute, kick | Sets the action taken when a member reaches the warning limit |