teleconnector 1.0.0

Advanced Telegram Bot API Connector

TeleConnector

A robust Python package for seamless Telegram bot interactions with advanced file handling capabilities.

Features

• Send messages and files to Telegram chats
• Listen for incoming messages and files in real-time
• Automatic file saving with custom paths via captions
• Comprehensive error handling and validation
• Configurable timeouts for all operations
• Supports both individual chats and groups

Installation

pip install teleconnector

Quick Start

1. Sending Messages

from teleconnector import send_message

bot_token = "YOUR_BOT_TOKEN"
chat_id = "TARGET_CHAT_ID"

try:
    result = send_message("Hello World!", bot_token, chat_id)
    if result:
        print("Message sent successfully!")
    else:
        print("Failed to send message!")
except Exception as e:
    print(f"Error while sending: {e}")

Listen For Messages

from teleconnector import listen_for_messages

bot_token = "YOUR_BOT_TOKEN"
chat_id = "YOUR_GROUP_CHAT_ID"

try:
    print("📡 Listening for new messages... (Press CTRL+C to stop)")
    for message in listen_for_messages(bot_token, chat_id):
        if "text" in message:
            print(f"💬 New message: {message['text']}")
        else:
            print("⚠️ Received a message without text content:", message)
except KeyboardInterrupt:
    print("\n🛑 Listener stopped by user.")
except Exception as e:
    print(f"❌ Error while listening: {e}")

3. Sending File

from teleconnector import send_file

bot_token = "YOUR_BOT_TOKEN"
chat_id = "TARGET_CHAT_ID"

file_path = "/path/to/file.txt"

try:
    result = send_file(file_path, bot_token, chat_id)
    if result:
        print(f"File sent successfully: {file_path}")
    else:
        print(f"Failed to send file: {file_path}")
except Exception as e:
    print(f"Error while sending file: {e}")

4. Receiving and Auto-Saving Files

from teleconnector import listen_for_files

bot_token = "YOUR_BOT_TOKEN"

try:
    print("📡 Listening for incoming files... (Press CTRL+C to stop)")

    for file_info in listen_for_files(bot_token, save_dir=True):
        if 'saved_path' in file_info:
            print(f"File automatically saved to: {file_info['saved_path']}")
        if 'file_name' in file_info:
            print(f"Received file: {file_info['file_name']}")
        else:
            print(f"Received file data without a name: {file_info}")

except KeyboardInterrupt:
    print("\nListener stopped by user.")
except Exception as e:
    print(f"Error while listening for files: {e}")

Error Handling

The package raises specific exceptions you can catch:

from teleconnector import TelegramAPIError

try:
    send_message("Test", bot_token, chat_id)
except TelegramAPIError as e:
    print(f"Telegram error: {e}")
except ValueError as e:
    print(f"Invalid parameters: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.