Configuration Reference

All configuration is done via environment variables, loaded from a .env file at the project root or from the system environment. The bot reads these at startup through config.LoadConfig().

Required Variables

These variables must be set or the bot will not start correctly.

Variable	Type	Description
BOT_TOKEN	string	Telegram Bot API token 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	Pyrogram session string for the userbot account that joins voice chats. Also accepts PYRO_SESSION_STRING as an alias
MONGO_URI	string	MongoDB connection URI. Also accepts MONGO_URL or DATABASE_URL as aliases. Example: mongodb://localhost:27017/solstice or mongodb+srv://user:pass@cluster.mongodb.net/solstice
OWNER_ID	int64	Telegram user ID of the bot owner (has unrestricted access to all commands)

Optional Variables

Bot Identity

Variable	Type	Default	Description
BOT_NAME	string	Solstice	Display name used in start messages and logs
UPSTREAM_REPO	string	https://github.com/SolsticeIO/SolsticeIO	GitHub repository URL shown in bot info

Logging

Variable	Type	Default	Description
LOGGER_ID	int64	(none)	Chat ID of the logging group/channel. All error logs, play logs, admin actions, and join/leave events are sent here
PLAY_LOGS_THREAD_ID	int	(none)	Forum topic thread ID within the logger group for play logs specifically. If unset, play logs go to the main chat
OTHER_LOGS_THREAD_ID	int	(none)	Forum topic thread ID for error and admin logs. If unset, these go to the main chat

Links & UI

Variable	Type	Default	Description
SUPPORT_CHAT	string	https://t.me/	URL to the support group, shown in help menus and start messages
START_IMG_URL	string	(catbox default)	Space-separated list of image URLs used as random start/help banners. Multiple URLs are rotated randomly
START_STICKERS	string	(default sticker ID)	Space-separated list of Telegram sticker file IDs sent as greeting animations
EMOJIS	string	❤️ 😁 👀 ⚡️ 🕊 ❤️‍🔥 💅 👻	Space-separated emojis used for random reactions in start messages

Caching (Upstash Redis)

Variable	Type	Default	Description
UPSTASH_REDIS_REST_URL	string	(none)	Upstash Redis REST API URL (e.g., https://your-db.upstash.io). When set, extracted YouTube stream URLs are cached with smart TTLs based on the URL's expire parameter
UPSTASH_REDIS_REST_TOKEN	string	(none)	Upstash Redis REST API bearer token

YouTube Cookies

Variable	Type	Default	Description
YOUTUBE_COOKIES	string	(none)	Raw Netscape cookie file content for YouTube authentication. Filtered to keep only youtube.com and google.com domains. Saved to MongoDB on first load for persistence across restarts. Can also be set via /setcookies command

Developer

Variable	Type	Default	Description
DEVELOPER_MODE	bool	false	Enables verbose debug logging when set to true

---

Configuration Loading Order

1. .env file (via godotenv)         ← loaded first
2. System environment variables     ← override .env values
3. MongoDB (cookies, sessions)      ← runtime persistence

For YouTube cookies specifically, the loading priority is:

1. MongoDB (database.GetYoutubeCookies)    ← highest priority
2. YOUTUBE_COOKIES environment variable     ← fallback, saved to MongoDB on first use
3. cookies.txt file on disk                 ← legacy fallback

---

Example .env File

# ─── Required ────────────────────────────────────
BOT_TOKEN=7123456789:AAH-your-bot-token-here
API_ID=12345678
API_HASH=abcdef1234567890abcdef1234567890
SESSION_STRING=BQC7a...your-session-string...
MONGO_URI=mongodb+srv://user:password@cluster0.xxxxx.mongodb.net/solstice
OWNER_ID=123456789

# ─── Logging ─────────────────────────────────────
LOGGER_ID=-1001987654321
PLAY_LOGS_THREAD_ID=5
OTHER_LOGS_THREAD_ID=7

# ─── Links ───────────────────────────────────────
SUPPORT_CHAT=https://t.me/SolsticeIO
BOT_NAME=Solstice

# ─── Caching (Optional) ─────────────────────────
UPSTASH_REDIS_REST_URL=https://solstice-cache-12345.upstash.io
UPSTASH_REDIS_REST_TOKEN=AXxxAAIjcDE...

# ─── YouTube (Optional) ─────────────────────────
# YOUTUBE_COOKIES=<paste raw Netscape cookie content here>

---

Per-Chat Settings (Database)

In addition to environment variables, several settings are configurable per-chat via bot commands and stored in MongoDB:

Setting	Command	Values	Description
Language	/lang	en (extensible)	Chat display language
Admin command mode	/playmode	everyone / admin	Who can use music playback commands
Autoplay	/autoplay	toggle	Auto-queue related songs when queue empties
Vote skip threshold	/setvotes N	1-20	Number of votes needed to skip a song
Welcome message	/setwelcome	text	Custom greeting for new members
Welcome toggle	/welcome on/off	bool	Enable/disable welcome messages
Group rules	/setrules	text	Group rules displayed via /rules
Warn mode	/setwarnmode	ban / mute / kick	Action taken when warn limit reached
Chat locks	/lock / /unlock	url, media, bot, etc.	Restrict specific message types