Telegram Terminal Client

A fast, elegant Telegram client for the terminal. Browse chats, read messages, and send replies—all without leaving your keyboard.

Features

• Real-time Messaging - Auto-refreshing chat feed every 3 seconds
• Colored Output - Each sender gets a unique color for easy identification
• Conversation Insights - View statistics: top senders, busiest hours, activity trends (Press I)
• Full Keyboard Control - Navigate entirely with keyboard
• Session Persistence - Saves login automatically, no re-authentication needed
• Clean Message Display - Formatted bubbles with timestamps
• Toast Notifications - Real-time alerts for connection and messages
• Animated UI - Pulsing header animation
• Activity Logging - All events logged to app.log

Requirements

• Node.js 14+ (Download)
• npm (comes with Node.js)
• A Telegram account
• Linux/Mac terminal (Ubuntu, Debian, Fedora, macOS tested)
• Internet connection

Quick Start

1. Clone & Install

git clone https://github.com/Gomorph675/telegram-terminal-client.git
cd telegram-terminal-client
npm install

2. Get Telegram API Keys

1. Visit my.telegram.org
2. Log in with your Telegram account
3. Click "API development tools"
4. Create a new application
5. Copy your API ID and API Hash

3. Configure with .env File (Recommended)

Step 1: Copy the example file

cp .env.example .env

Step 2: Edit .env with your credentials

nano .env
# or use your favorite editor

Replace the placeholder values:

TELEGRAM_API_ID=YOUR_API_ID_HERE
TELEGRAM_API_HASH=YOUR_API_HASH_HERE
SESSION_FILE=session.json
CHAT_LIMIT=10

Important Security Notes:

• .env is listed in .gitignore - it will never be committed to git
• .env.example is a safe template you can commit (no real credentials)
• Always keep your .env file on your local machine only
• Never share or commit your real API credentials

Alternative: Configure with Environment Variables

Linux/Mac:

export TELEGRAM_API_ID=your_api_id
export TELEGRAM_API_HASH=your_api_hash

Windows (Command Prompt):

set TELEGRAM_API_ID=your_api_id
set TELEGRAM_API_HASH=your_api_hash

Windows (PowerShell):

$env:TELEGRAM_API_ID="your_api_id"
$env:TELEGRAM_API_HASH="your_api_hash"

4. Run

npm start

Or directly:

node index.js

First time? You'll be prompted to:

• Enter your phone number (e.g., +1234567890)
• Enter any 2FA codes
• The app saves your session automatically

Keyboard Shortcuts

| Key | Action | |-----|---------| | Arrow Keys / Mouse | Browse chats | | Tab | Focus message input | | Enter | Send message | | I | View conversation insights | | R | Refresh chats and messages | | Esc / Ctrl+C | Exit |

Layout

┌─────────────────────────────────────────────┐
│     ▶ TELEGRAM ◀  (pulsing animation)       │
├──────────────┬──────────────────────────────┤
│              │ [HH:MM] Alice: Hey!          │
│   CHATS      │ ═════════════════════════    │
│              │                              │
│ • Chat 1     │ [HH:MM] Bob: How are you?   │
│ • Chat 2     │ ═════════════════════════    │
│ • Chat 3     │                              │
│              │ [HH:MM] me: Good!           │
├──────────────┼──────────────────────────────┤
│ Chat: Chat 1 │ Type message here...         │
└──────────────┴──────────────────────────────┘

UI Components

• Header - Connection status and animated title
• Chat List (Left) - Your Telegram conversations
• Messages (Right) - Message history with colored senders and timestamps
• Chat Info (Bottom Left) - Currently selected chat
• Input (Bottom Right) - Type and send messages

Features Explained

Conversation Insights

Press I to view:

• Total Messages - Count of all messages in chat
• Top Senders - Who talks the most (with percentages)
• Busiest Hours - When the chat is most active
• Activity by Day - Message frequency by weekday

Auto-Refresh

Messages update automatically every 3 seconds. You'll see new messages appear without doing anything.

Color System

Each sender gets a unique color (cyan, magenta, yellow, green, white) that stays consistent throughout the conversation.

Timestamps

All messages show [HH:MM] timestamps in dark gray for reference.

Configuration

Edit .env to customize:

# Required: Your Telegram API credentials
TELEGRAM_API_ID=123456
TELEGRAM_API_HASH=your_hash_here

# Optional: Where to save your session (default: session.json)
SESSION_FILE=session.json

# Optional: How many chats to load (default: 10)
CHAT_LIMIT=10

Project Structure

telegram-terminal-client/
├── index.js              # Main application (organized & commented)
├── package.json          # Dependencies
├── .env                  # Your credentials (gitignored)
├── session.json          # Your session (auto-generated, gitignored)
├── app.log               # Activity logs (gitignored)
└── README.md             # This file

Configuration Guide

Method Priority

The app checks for credentials in this order:

1. System Environment Variables (highest priority)
   • TELEGRAM_API_ID and TELEGRAM_API_HASH
2. .env File (recommended)
   • Create .env with your credentials
3. Default (lowest priority, will fail)

Per-User Configuration

Each user can set their own credentials by creating their own .env file:

# User A
cp .env.example .env
nano .env  # Add User A's credentials

# User B (same system, in their own directory)
cp .env.example .env
nano .env  # Add User B's credentials

Each user will authenticate with their own Telegram account using their own .env file.

Setting Chat Limit

Limit the number of chats loaded (saves memory):

export CHAT_LIMIT=20
npm start

Or in .env:

CHAT_LIMIT=20

Troubleshooting

"Missing TELEGRAM_API_ID"

Check if your .env file exists and has the correct values:

cat .env  # View your .env file

Or check with environment variables:

echo $TELEGRAM_API_ID  # Linux/Mac
echo %TELEGRAM_API_ID% # Windows

"Cannot read properties of null"

• Phone number format: Use +1234567890 or just 1234567890
• The app auto-formats it, but try different formats if stuck

"No messages appearing"

• Check internet connection
• Wait 2 seconds (auto-refresh interval)
• Try scrolling in the messages box
• Check app.log for errors

Terminal looks broken

• Resize your terminal window to at least 120×30
• Make sure ANSI colors are enabled
• Try restarting the app

App crashes immediately

• Check app.log for error details
• Verify Node.js version: node --version (must be 14+)
• Delete session.json and re-authenticate

Performance

• Message Refresh: Every 2 seconds
• Messages Loaded: Last 50 per chat
• Chats Shown: Limited by CHAT_LIMIT (default 10)
• Logs: Auto-appended to app.log (no rotation)

Security

• Session stored locally in session.json (not committed)
• API credentials in .env (not committed)
• Uses Telegram's official encrypted protocol
• Logs contain message metadata (stored plaintext)

Protect your .env file! Add to .gitignore:

.env
session.json
app.log
node_modules/

Limitations

• Text only - No photos, files, or videos yet
• No editing - Can't edit or delete sent messages
• 50 messages - Only loads last 50 messages per chat
• No groups - Group management features not supported
• No calls - Voice/video not available

Roadmap

• [ ] Search messages and chats
• [ ] Edit/delete messages
• [ ] Media support (photos, files)
• [ ] Keyboard shortcuts customization
• [ ] Theme selector (dark/light)
• [ ] Message export/backup

License

ISC

Contributing

Found a bug? Have an idea?

• Open an issue
• Start a discussion

Support

• 📖 Check app.log for technical details
• 🐛 Report issues on GitHub
• ❓ Ask questions

Made for terminal enthusiasts

Star us on GitHub if you find this useful!