@bcoders.gr/telegram-client

Advanced Node.js Telegram client with EventEmitter support, message parsing, and real-time event handling.

Features

• 🚀 EventEmitter-based: Listen for new messages with event listeners
• 📱 Message Parsing: Automatic extraction of URLs, cashtags, and metadata
• 🔗 Reply & Forward Detection: Identifies related messages and relationships
• 📂 Folder Support: Organizes chats by Telegram folders
• 🧹 Clean Output: Removes empty fields and emoticons from chat titles
• ⚡ Real-time: Instant message processing and event emission

Installation

npm install @bcoders.gr/telegram-client

Quick Start

const MyTelegramClient = require('@bcoders.gr/telegram-client');

const apiId = 'your_api_id';
const apiHash = 'your_api_hash';
const session = 'your_session_string';

const client = new MyTelegramClient(apiId, apiHash, session);

// Listen for new messages
client.on('msg', (message) => {
    console.log('New message:', message);
});

// Connect to Telegram
async function start() {
    try {
        await client.connect();
        console.log('Connected successfully!');
    } catch (error) {
        console.error('Failed to connect:', error);
    }
}

start();

Message Structure

The client emits cleaned message objects with the following structure:

{
    id: 12345,
    timestamp: 1749401385,
    text: "Message content",
    urls: ["https://example.com"],
    cashtags: ["$BTC", "$ETH"],
    isForwarded: true,
    forwardedFrom: "Channel Name",
    relatedId: 12344,  // ID of replied-to or related message
    chatId: 1234567890,
    chatTitle: "Chat Name",
    chatFolder: "Crypto"
}

API Reference

Constructor

new MyTelegramClient(apiId, apiHash, session)

• apiId: Your Telegram API ID
• apiHash: Your Telegram API hash
• session: Your session string

Methods

connect()

Connects to Telegram and starts listening for messages.

disconnect()

Disconnects from Telegram.

sendMessage(chatId, message)

Sends a message to a chat.

getMessages(chatId, limit = 10)

Retrieves messages from a chat.

getDialogs()

Gets all dialogs (chats) and organizes them by folders.

Events

msg

Emitted when a new message is received.

client.on('msg', (message) => {
    // Handle the message
});

Features in Detail

URL Extraction

Automatically extracts all URLs from messages, including:

• HTTP/HTTPS links
• Domain names
• Shortened URLs

Cashtag Detection

Finds cryptocurrency symbols like $BTC, $ETH, $DOGE in messages.

Reply Detection

Identifies when a message is a reply to another message and includes the original message ID.

Forward Detection

Detects forwarded messages and extracts information about the original source.

Folder Organization

Organizes chats by Telegram folders for better categorization.

Clean Titles

Removes emoticons and extra whitespace from chat titles for cleaner output.

Getting Telegram Credentials

1. Go to my.telegram.org
2. Log in with your phone number
3. Create a new application to get apiId and apiHash
4. For the session string, you can use the telegram package's session generation

License

ISC

Contributing

Issues and pull requests are welcome on GitHub.

Author

pagovitsa

• GitHub: @pagovitsa