Telegram Integration

Overview

The script uses Telethon (Telegram’s official Python API client) for downloading files from Telegram. This works for both public and private channels you have access to.

Telegram integration is optional. You only need it if you want to download files from Telegram channels/groups.

Why Telethon?

Telegram doesn’t use traditional web cookies for authentication. Private channels require Telegram’s native API with session-based auth. Telethon vs yt-dlp:

Feature	Telethon	yt-dlp
Public channels	✓ Works	✓ Works (sometimes)
Private channels	✓ Works	✗ Fails
Authentication	✓ Session-based	✗ Cookie-based
Media downloads	✓ All types	✗ Metadata only

Telethon works reliably for all cases.

Prerequisites

Python 3.7+

Check version: python3 --version

Telethon Library

Install: pip install telethon

Telegram API Credentials

Get from: https://my.telegram.org

Telegram Account

Phone number for authentication

Installation

Step 1: Install Telethon

pip install telethon

Verify installation:

python3 -c "import telethon; print(telethon.__version__)"

Should output a version number like 1.24.0.

Step 2: Get Telegram API Credentials

Go to my.telegram.org

Open https://my.telegram.org in your browser

Enter your phone number and verification code

Create application

Click on “API development tools”Fill in the form:

App title: GDrive Ingest
Short name: gdrive_ingest
Platform: Other
Description: (optional)

Click “Create application”

Save credentials

You’ll see:

api_id: A number (e.g., 12345678)
api_hash: A string (e.g., abc123def456...)

Save these for the next step.

Step 3: Configure Environment Variables

Option 1: .env File (Recommended)
Option 2: Shell Profile
Option 3: Temporary

Add to your .env file:

.env

TELEGRAM_API_ID="12345678"
TELEGRAM_API_HASH="abc123def456..."

The script will automatically load these from .env.

Add to ~/.bashrc, ~/.zshrc, or ~/.profile:

export TELEGRAM_API_ID='12345678'
export TELEGRAM_API_HASH='abc123def456...'

Then reload:

source ~/.bashrc  # or ~/.zshrc

Set for current session only:

export TELEGRAM_API_ID='12345678'
export TELEGRAM_API_HASH='abc123def456...'
./gdrive_ingest.sh https://t.me/channel/123

First Run - Authentication

The first time you download from Telegram, you’ll be prompted to authenticate:

Run script with Telegram URL

./gdrive_ingest.sh https://t.me/channelname/123

Enter phone number

Please enter your phone (or bot token): +1234567890

Use international format with country code (e.g., +1 for US).

Enter verification code

Please enter the code you received: 12345

Check your Telegram app for the code.

Session saved

A session file is created at:

~/.config/gdrive-ingest/telegram/downloader.session

This only happens once! Future runs use this session automatically.

The authentication session is valid indefinitely. You won’t need to enter your phone/code again unless you delete the session file.

Usage

Once set up, Telegram links work just like any other URL:

Single File

./gdrive_ingest.sh https://t.me/channelname/123

Multiple Files

./gdrive_ingest.sh https://t.me/channel/123 https://t.me/channel/456

With Folder Selection

# Interactive mode
./gdrive_ingest.sh https://t.me/channelname/123

# Direct to folder
./gdrive_ingest.sh --folder "Music" https://t.me/channelname/123

Mixed URLs

# Mix Telegram and regular URLs
./gdrive_ingest.sh \
  https://t.me/channel/123 \
  https://example.com/song.mp3 \
  https://t.me/channel/456

Supported Formats

Public Channels
Private Channels
Media Types

https://t.me/channelname/123
https://telegram.me/channelname/123
https://telegram.dog/channelname/123

Works for any public channel or group.

https://t.me/c/1234567890/456

Works for private channels if you’re a member.

All media types are supported:

Audio files (.mp3, .flac, .m4a)
Video files (.mp4, .mkv)
Photos (.jpg, .png)
Documents (.pdf, .zip)
Any other file type

Download Progress

Telegram downloads show real-time progress:

📱 Telegram link detected
⬇  Downloading filename.mp3...
Downloading: 45.2% (3.8 MB / 8.4 MB)
✓ Download complete
🔐 MD5: 6d2300f6a025e07ad87991b31023da6a

Troubleshooting

TELEGRAM_API_ID and TELEGRAM_API_HASH required

Error:

✗ Telegram API credentials required
Set environment variables:
  export TELEGRAM_API_ID='your_api_id'
  export TELEGRAM_API_HASH='your_api_hash'
Get them from: https://my.telegram.org

Solution:

Get credentials from https://my.telegram.org
Add to .env file or export as environment variables
See Step 3: Configure Environment Variables

ERROR: Message not found

Possible causes:

The message doesn’t exist
Message was deleted
You don’t have access to the channel
The link is incorrect

Solution:

Verify the link is correct
Check if you’re a member of private channels
Try opening the link in Telegram app first

ERROR: No media in message

Cause: The Telegram message is text-only (no file attached).Solution: Make sure the message contains a file. Text-only posts can’t be downloaded.

database is locked

Cause: Session file is locked by another process or crashed session.Solution:

rm ~/.config/gdrive-ingest/telegram/*.session-journal

Or fully reset:

rm -rf ~/.config/gdrive-ingest/telegram/

Next run will prompt for authentication again.

Session authentication issues

Symptoms:

Keeps asking for phone number
“User is deactivated” error
Random authentication failures

Solution: Clear session and re-authenticate:

rm -rf ~/.config/gdrive-ingest/telegram/
./gdrive_ingest.sh https://t.me/channel/123

Enter phone number and verification code when prompted.

Telethon not installed

Error:

✗ Telethon library required for Telegram downloads
Install: pip install telethon

Solution:

pip3 install telethon

Verify:

python3 -c "import telethon"

You don't have access to this channel

Cause: Private channel requires membership.Solution:

Join the channel in your Telegram app
Make sure you’re logged in with the same phone number
Try downloading again

Security Notes

Keep private:

Your API credentials (TELEGRAM_API_ID, TELEGRAM_API_HASH)
Session file (~/.config/gdrive-ingest/telegram/)
Never share or commit to git

Session file location:

~/.config/gdrive-ingest/telegram/downloader.session

This file contains your login credentials. Keep it secure! Best practices:

Use .env file

Store credentials in .env (already in .gitignore)

Don't commit credentials

Verify .gitignore excludes:

.env
~/.config/gdrive-ingest/

Restrict file permissions

chmod 600 ~/.config/gdrive-ingest/telegram/downloader.session

Setup Helper Script

Use the interactive setup helper:

./setup_telegram.sh

This script will:

Check for Python and Telethon
Prompt for API credentials
Save to .env file
Test the configuration

Example Session

$ ./gdrive_ingest.sh https://t.me/musicchannel/456

✓ Using cached access token
📦 Processing 1 URL(s)
Fetching your GDrive folders...

[Interactive folder selection]

✓ Selected: Music (ID: 1hU4H0PO_ifwGP47UZHwbc2w89Y7V_YPn)

────────────────────────────────────────
[1/1] Processing: https://t.me/musicchannel/456
────────────────────────────────────────
📱 Telegram link detected
⬇  Downloading song.mp3...
Downloading: 100.0% (8.5 MB / 8.5 MB)
✓ Download complete
🔐 MD5: 6d2300f6a025e07ad87991b31023da6a
📄 Single file
Organizing and uploading files...
💿 Don Toliver - Tiramisu (2025) - Tiramisu
   ⬆  Uploading 8.52MB... ✓ Uploaded 8.52MB
   🖼  Cover art... ✓ Cover art uploaded

────────────────────────────────────────
✓ Done! Files uploaded to GDrive: Music
🔗 Check: https://drive.google.com/drive/folders/...
────────────────────────────────────────

Advanced Usage

Download Entire Channel

While the script doesn’t support bulk channel downloads, you can create a JSON file with message links:

urls.json

[
  "https://t.me/channel/123",
  "https://t.me/channel/124",
  "https://t.me/channel/125",
  "https://t.me/channel/126"
]

Then run:

./gdrive_ingest.sh --json urls.json

Rate Limiting

Telegram API has rate limits. If you’re downloading many files:

Recommended: Process 10-20 files at a time
Wait time: 1-2 seconds between files (automatic)
Daily limit: ~1000 files per day per account

Next Steps

Usage Examples

See real-world Telegram usage patterns

Interactive Features

Master the interactive UI

File Organization

Understand how files are organized

Troubleshooting

Fix common issues

Get Started

Scripts

GDrive Ingest

Development

Overview

Why Telethon?

Prerequisites

Python 3.7+

Telethon Library

Telegram API Credentials

Telegram Account

Installation

Step 1: Install Telethon

Step 2: Get Telegram API Credentials

Step 3: Configure Environment Variables

First Run - Authentication

Usage

Single File

Multiple Files

With Folder Selection

Mixed URLs

Supported Formats

Download Progress

Troubleshooting

Security Notes

Setup Helper Script

Example Session

Advanced Usage

Download Entire Channel

Rate Limiting

Next Steps

Usage Examples

Interactive Features

File Organization

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Scripts

GDrive Ingest

Development

​Overview

​Why Telethon?

​Prerequisites

Python 3.7+

Telethon Library

Telegram API Credentials

Telegram Account

​Installation

​Step 1: Install Telethon

​Step 2: Get Telegram API Credentials

​Step 3: Configure Environment Variables

​First Run - Authentication

​Usage

​Single File

​Multiple Files

​With Folder Selection

​Mixed URLs

​Supported Formats

​Download Progress

​Troubleshooting

​Security Notes

​Setup Helper Script

​Example Session

​Advanced Usage

​Download Entire Channel

​Rate Limiting

​Next Steps

Usage Examples

Interactive Features

File Organization

Troubleshooting

Build docs developers (and LLMs) love

Overview

Why Telethon?

Prerequisites

Installation

Step 1: Install Telethon

Step 2: Get Telegram API Credentials

Step 3: Configure Environment Variables

First Run - Authentication

Usage

Single File

Multiple Files

With Folder Selection

Mixed URLs

Supported Formats

Download Progress

Troubleshooting

Security Notes

Setup Helper Script

Example Session

Advanced Usage

Download Entire Channel

Rate Limiting

Next Steps