Getting Started

This guide walks you through setting up Solstice from scratch - from obtaining API credentials to running the bot in your first Telegram group.

Prerequisites

Requirement	Version	Purpose
Go	1.20+	Compile and run the bot engine
Python	3.9+	Run the voice chat daemon (PyTgCalls)
Node.js	18+	Required by yt-dlp for JavaScript extraction
FFmpeg	5.0+	Audio/video stream transcoding
MongoDB	6.0+	Persistent storage (local or Atlas)
yt-dlp	Latest	YouTube audio/video extraction

Optional

Requirement	Purpose
Upstash Redis	Stream URL caching (reduces yt-dlp calls)
YouTube cookies.txt	Bypass YouTube rate limiting / bot detection
A VPS or cloud server	For 24/7 operation

---

Step 1: Obtain Telegram Credentials

You need three sets of credentials:

1.1 Bot Token (from @BotFather)

1. Open @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token (format: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
4. Important: Disable privacy mode - send /setprivacy → select your bot → Disable

1.2 API ID & API Hash (from my.telegram.org)

1. Go to my.telegram.org
2. Log in with your phone number
3. Click "API Development Tools"
4. Create a new application (any name/description)
5. Copy the api_id (number) and api_hash (hex string)

1.3 Pyrogram Session String

The bot needs a userbot session (your personal account or a dedicated account) to join voice chats, because bots cannot join voice chats through the Bot API alone.

pip install pyrogram tgcrypto

python3 -c "
from pyrogram import Client
app = Client('session', api_id=YOUR_API_ID, api_hash='YOUR_API_HASH')
with app:
    print(app.export_session_string())
"

Security: The session string grants full access to the Telegram account. Use a dedicated account, not your personal one.

---

Step 2: Download or Clone

You can either download the pre-compiled binary (easiest) or clone the source code.

Option A: Download Pre-compiled Binary (Easiest)

# Download the release zip from Telegram
# Extract it into a folder
unzip solstice-release.zip -d solstice
cd solstice

# Copy the example environment file
cp .env.example .env

Option B: Clone & Configure from Source

git clone https://github.com/SolsticeIO/SolsticeIO.git
cd SolsticeIO

# Copy the example environment file
cp .env.example .env

Edit .env with your credentials:

# Required
BOT_TOKEN=your_bot_token_here
API_ID=your_api_id
API_HASH=your_api_hash
SESSION_STRING=your_session_string
MONGO_URI=mongodb://localhost:27017/solstice
OWNER_ID=your_telegram_user_id

# Optional
LOGGER_ID=-1001234567890
SUPPORT_CHAT=https://t.me/SolsticeIO

See Configuration Reference for all available variables.

---

Step 3: Install Dependencies

Python Dependencies

pip install -r requirements.txt

This installs:

• pyrogram - MTProto client for voice chat management
• tgcrypto - Cryptographic acceleration for Pyrogram
• py-tgcalls - Voice chat streaming library
• aiohttp - Async HTTP server for the daemon API
• yt-dlp - YouTube extraction (also used as a Python module)

Go Dependencies

go mod download

This fetches:

• gopkg.in/telebot.v3 - Telegram Bot API framework
• go.mongodb.org/mongo-driver - MongoDB driver
• github.com/joho/godotenv - .env file loader
• github.com/tidwall/gjson - Fast JSON parser for YouTube data
• gopkg.in/yaml.v3 - YAML parser for i18n strings

---

Step 4: Build & Run

If using Option A (Pre-compiled Binary)

Because Solstice is bundled with both the Go engine and the Python PyTgCalls daemon, you do not need to install Python, pip, or Go.

Simply run the executable:

./solstice

If using Option B (Build from Source)

Development (direct run)

go run cmd/bot/main.go

Production (compiled binary)

# Build
go build -o solstice cmd/bot/main.go

# Run
./solstice

You should see output like:

Starting Music Bot...
Loaded 85 strings from strings/langs/en.yml
Successfully loaded YouTube cookies from MongoDB
Connected to MongoDB!
Dropping pending Telegram updates...
Initializing Voice Chat Manager...
Starting vc_daemon.py...
Initializing Bot API (Commands)...
Bot is now polling for updates...

---

Step 5: Set Up Your Group

1. Add the bot to your Telegram group
2. Promote the bot to admin with these permissions:
   • Delete messages
   • Ban users
   • Pin messages
   • Manage voice chats
   • Invite users via link
3. Add the userbot account (the one whose session string you generated) to the same group
4. Send /start in the group - you should see the welcome card
5. Try /play Bohemian Rhapsody to test music playback

---

Troubleshooting

Bot doesn't respond to commands

• Ensure BOT_TOKEN is correct
• Check that privacy mode is disabled in BotFather
• Verify the bot is added to the group and promoted as admin

Voice chat doesn't start

• Ensure SESSION_STRING is valid and the associated account is in the group
• Check that API_ID and API_HASH match the session
• Verify FFmpeg is installed: ffmpeg -version
• Check Python daemon logs for PyTgCalls errors

YouTube extraction fails

• Update yt-dlp: pip install -U yt-dlp
• Check if cookies are needed: /checkcookies (bot owner only)
• Upload fresh cookies via /setcookies (reply to a cookies.txt file)
• Verify Node.js is installed: node --version

MongoDB connection fails

• Verify MONGO_URI is correct
• For MongoDB Atlas, ensure your IP is whitelisted
• Check that the database user has read/write permissions

---

Next Steps

• Configuration Reference - Fine-tune every aspect of the bot
• Command Reference - Learn all available commands
• Deployment Guide - Run the bot 24/7 on a server