Quickstart

TT-Bot is a production-grade Telegram bot for downloading TikTok and Instagram content without watermarks. It features proxy rotation, queue management, and multilingual support.

Prerequisites

Before you begin, ensure you have:

Docker and Docker Compose installed
A Telegram Bot Token from @BotFather
Telegram API credentials (API ID and API Hash) from my.telegram.org
A RapidAPI key for Instagram downloads (optional)

Quick Start with Docker Compose

Clone the repository

git clone https://github.com/karilaa-dev/tt-bot.git
cd tt-bot

Configure environment variables

Create a .env file from the example:

cp .env.example .env

Edit .env and configure the required variables:

# Telegram Bot Token from @BotFather
BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

# Telegram API credentials from my.telegram.org
TELEGRAM_API_ID=1234567
TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890

# Local Telegram Bot API server (recommended for Docker)
TG_SERVER=http://telegram-bot-api:8081

# Database connection (uses Docker Compose PostgreSQL)
DB_URL=postgresql+asyncpg://postgres:postgres@db/ttbot-db

Start the services

Launch all services (bot, database, and local Telegram API server):

docker compose up -d

The Docker Compose stack includes:

tt-bot - The main Telegram bot
stats-bot - Statistics tracking bot
telegram-bot-api - Local Telegram Bot API server (faster, no rate limits)
db - PostgreSQL database

Verify the bot is running

Check the logs to ensure everything started correctly:

docker compose logs -f tt-bot

You should see output like:

INFO:root:No Watermark TikTok [@ttgrab_bot, id:1234567890]
INFO:root:Proxy manager initialized

Test your bot

Open Telegram and send /start to your bot. You should receive a welcome message:

You have launched No Watermark TikTok🤖 This bot supports download of: 📹Video, 🖼Images and 🔈Audio from TikTok and Instagram without watermark Send video link to get started

Using the Bot

Basic Commands

/start

Initialize the bot and see welcome message

/lang

Change bot language (supports English, Russian, Arabic, Hindi, and more)

/mode

Toggle between video and file mode for downloads

Downloading Content

Send a TikTok or Instagram link

Simply paste any TikTok or Instagram video URL:

https://www.tiktok.com/@username/video/1234567890
https://vm.tiktok.com/ABC123
https://www.instagram.com/reel/ABC123DEF456/

Wait for processing

The bot will react with 👀 while processing your request.

Receive your content

Downloads are sent without watermarks:

Videos - HD quality, no watermark
Images - Original quality slideshow
Audio - Original audio track

File Mode: Use /mode to toggle between sending videos as native Telegram videos or as files. File mode is useful for larger videos or when you want to preserve maximum quality.

Supported Content Types

Platform	Videos	Images/Slideshows	Audio
TikTok	✅	✅	✅
Instagram	✅	✅	❌

Alternative Deployment Options

Docker (Single Container)

Run only the bot without the full stack:

Build the image

docker build -t tt-bot .

Update .env for standalone mode

When not using Docker Compose, update your .env:

# Use public Telegram API instead of local server
TG_SERVER=https://api.telegram.org

# Remove database if not needed (optional features only)
# DB_URL=

Run the container

docker run --rm --env-file .env tt-bot

Local Development with uv

For development without Docker:

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Ensure ~/.local/bin is on your PATH.

Install dependencies

uv sync

Configure for local run

Update .env for local development:

# Use public API if not running local server
TG_SERVER=https://api.telegram.org

# Point to local database if needed
DB_URL=postgresql+asyncpg://postgres:postgres@localhost/ttbot-db

Run the bot

uv run python main.py

Troubleshooting

Bot doesn't respond to messages

Check bot token validity:

# Verify your bot token is correct
curl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getMe

Verify the bot is running:

docker compose logs tt-bot

Common issues:

Incorrect BOT_TOKEN in .env
Bot not started in Telegram (send /start first)
Firewall blocking outbound connections

TikTok downloads fail with network errors

TikTok uses aggressive anti-bot measures. Solutions:1. Use proxies:Create proxies.txt with one proxy per line:

http://proxy1.example.com:8080
socks5://proxy2.example.com:1080

Update .env:

PROXY_FILE=proxies.txt
PROXY_INCLUDE_HOST=false

2. Add cookies:Export TikTok cookies using a browser extension and save to cookies.txt, then:

YTDLP_COOKIES=cookies.txt

3. Adjust retry settings:

URL_RESOLVE_MAX_RETRIES=5
VIDEO_INFO_MAX_RETRIES=5
DOWNLOAD_MAX_RETRIES=5

Database connection errors

With Docker Compose:Ensure the database service is running:

docker compose ps db

The DB_URL should match Docker Compose service names:

DB_URL=postgresql+asyncpg://postgres:postgres@db/ttbot-db

With external database:Update connection string with your database credentials:

DB_URL=postgresql+asyncpg://user:password@host:5432/database

Instagram downloads not working

Instagram downloads require a RapidAPI key:

Sign up at RapidAPI
Subscribe to an Instagram API (search for “Instagram” in the API marketplace)
Copy your API key and add to .env:

RAPIDAPI_KEY=your_rapidapi_key_here

Without a valid RAPIDAPI_KEY, Instagram downloads will fail. TikTok downloads work without any API keys.

Queue full errors

Users see “Please wait! You already have X videos processing” when:

MAX_USER_QUEUE_SIZE limit is reached (default: 0 = unlimited)
Multiple large downloads are processing simultaneously

Solutions:Increase the queue limit:

MAX_USER_QUEUE_SIZE=10  # Allow 10 concurrent downloads per user

Or remove the limit entirely:

MAX_USER_QUEUE_SIZE=0  # Unlimited

Out of memory errors

For large videos or high traffic:1. Enable streaming mode:

# Stream videos longer than 5 minutes (300 seconds)
STREAMING_DURATION_THRESHOLD=300

2. Set maximum duration:

# Reject videos longer than 30 minutes
MAX_VIDEO_DURATION=1800

3. Increase Docker memory limits:Edit docker-compose.yml:

services:
  tt-bot:
    deploy:
      resources:
        limits:
          memory: 2G

Local Telegram Bot API server issues

The local API server (telegram-bot-api service) provides:

Faster uploads/downloads
No rate limits
Support for larger files (up to 2GB)

If it’s not working:

Check it’s running:

docker compose logs telegram-bot-api

Verify TELEGRAM_API_ID and TELEGRAM_API_HASH are correct
Fall back to public API:

TG_SERVER=https://api.telegram.org

When using public API, you don’t need TELEGRAM_API_ID or TELEGRAM_API_HASH, but you’ll have stricter rate limits.

Next Steps

Configuration

Learn about all configuration options and environment variables

Architecture

Understand the bot’s internal architecture and design patterns

Development

Set up your development environment and contribute

Deployment

Production deployment guides and best practices

Get Started

Deployment

Configuration

Features

Architecture

Prerequisites

Quick Start with Docker Compose

Using the Bot

Basic Commands

/start

/lang

/mode

Downloading Content

Supported Content Types

Alternative Deployment Options

Docker (Single Container)

Local Development with uv

Troubleshooting

Next Steps

Configuration

Architecture

Development

Deployment

Get Started

Deployment

Configuration

Features

Architecture

​Prerequisites

​Quick Start with Docker Compose

​Using the Bot

​Basic Commands

/start

/lang

/mode

​Downloading Content

​Supported Content Types

​Alternative Deployment Options

​Docker (Single Container)

​Local Development with uv

​Troubleshooting

​Next Steps

Configuration

Architecture

Development

Deployment

Prerequisites

Quick Start with Docker Compose

Using the Bot

Basic Commands

Downloading Content

Supported Content Types

Alternative Deployment Options

Docker (Single Container)

Local Development with uv

Troubleshooting

Next Steps