# 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
```bash
pip install teleconnector
```
## Quick Start
### 1. Sending Messages
```python
from teleconnector import send_message
bot_token = "YOUR_BOT_TOKEN"
chat_id = "TARGET_CHAT_ID"
message = "Hello World"
try:
result = send_message(message, bot_token, chat_id)
print("ā
Message sent successfully!")
print("š Message ID:", result['result']['message_id'])
except Exception as e:
print(f"ā Error while sending message: {e}")
```
### Listen For Messages
```python
from teleconnector import listen_for_messages
bot_token = "YOUR_BOT_TOKEN"
chat_id = "TARGET_CHAT_ID"
try:
print("š” Listening for new messages... (Press CTRL+C to stop)")
for message in listen_for_messages(bot_token, chat_id):
from_user = message.get('from', {})
name = from_user.get('first_name', 'Unknown')
text = message.get('text', '')
print(f"š¬ New message from {name}: {text}")
except KeyboardInterrupt:
print("\nš Listener stopped by user.")
except Exception as e:
print(f"ā Error while listening for messages: {e}")
```
### 3. Sending File
```python
from teleconnector import send_file
bot_token = "YOUR_BOT_TOKEN"
chat_id = "TARGET_CHAT_ID"
file_path = "/path/to/your/file.pdf"
caption = "Here's the document"
try:
result = send_file(file_path, bot_token, chat_id, caption=caption)
print("ā
File sent successfully!")
print("š File ID:", result['result']['document']['file_id'])
except Exception as e:
print(f"ā Error while sending file: {e}")
```
### 4. Receiving and Auto-Saving Files
```python
from teleconnector import listen_for_files
bot_token = "YOUR_BOT_TOKEN"
chat_id = "TARGET_CHAT_ID"
save_directory = "./downloads"
try:
print("š” Listening for incoming files... (Press CTRL+C to stop)")
for file_info in listen_for_files(bot_token, chat_id, save_dir=save_directory):
file_name = file_info.get('file_name', 'Unknown')
file_size = file_info.get('file_size', 0)
saved_path = file_info.get('saved_path', 'Not saved')
print(f"š„ Received file: {file_name} ({file_size} bytes)")
print(f"š¾ Saved to: {saved_path}")
except KeyboardInterrupt:
print("\nš Listener 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:
```python
from teleconnector import send_message, TelegramAPIError
bot_token = "YOUR_BOT_TOKEN"
chat_id = "TARGET_CHAT_ID"
try:
response = send_message("Test message", bot_token, chat_id)
print("Success:", response)
except TelegramAPIError as e:
print("Telegram API Error:", e)
except ValueError as e:
print("Invalid parameters:", e)
except Exception as e:
print("Unexpected error:", e)
```
## Contributing
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
<a href="https://mrfidal.in">GitHub</a>
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/bytebreach/teleconnector",
"name": "teleconnector",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "telegram, bot, api, messaging, chat, telegram-bot, telegram-api, file-transfer",
"author": "MrFidal",
"author_email": "mrfidal@proton.me",
"download_url": "https://files.pythonhosted.org/packages/9d/ce/d838162e3691d33b33d563abb1e142da80ce37a935633066f5e87d4735a7/teleconnector-1.1.2.tar.gz",
"platform": null,
"description": "# TeleConnector\r\n\r\n\r\n\r\n\r\n\r\nA robust Python package for seamless Telegram bot interactions with advanced file handling capabilities.\r\n\r\n## Features\r\n\r\n- Send messages and files to Telegram chats\r\n- Listen for incoming messages and files in real-time\r\n- Automatic file saving with custom paths via captions\r\n- Comprehensive error handling and validation\r\n- Configurable timeouts for all operations\r\n- Supports both individual chats and groups\r\n\r\n## Installation\r\n\r\n```bash\r\npip install teleconnector\r\n```\r\n\r\n## Quick Start\r\n\r\n### 1. Sending Messages\r\n\r\n```python\r\nfrom teleconnector import send_message\r\n\r\nbot_token = \"YOUR_BOT_TOKEN\"\r\nchat_id = \"TARGET_CHAT_ID\"\r\n\r\nmessage = \"Hello World\" \r\n\r\ntry:\r\n result = send_message(message, bot_token, chat_id)\r\n print(\"\u2705 Message sent successfully!\")\r\n print(\"\ud83c\udd94 Message ID:\", result['result']['message_id'])\r\nexcept Exception as e:\r\n print(f\"\u274c Error while sending message: {e}\")\r\n\r\n\r\n```\r\n\r\n### Listen For Messages\r\n\r\n```python\r\nfrom teleconnector import listen_for_messages\r\n\r\nbot_token = \"YOUR_BOT_TOKEN\"\r\nchat_id = \"TARGET_CHAT_ID\"\r\n\r\ntry:\r\n print(\"\ud83d\udce1 Listening for new messages... (Press CTRL+C to stop)\")\r\n for message in listen_for_messages(bot_token, chat_id):\r\n from_user = message.get('from', {})\r\n name = from_user.get('first_name', 'Unknown')\r\n text = message.get('text', '')\r\n print(f\"\ud83d\udcac New message from {name}: {text}\")\r\nexcept KeyboardInterrupt:\r\n print(\"\\n\ud83d\uded1 Listener stopped by user.\")\r\nexcept Exception as e:\r\n print(f\"\u274c Error while listening for messages: {e}\")\r\n\r\n```\r\n\r\n### 3. Sending File\r\n\r\n```python\r\nfrom teleconnector import send_file\r\n\r\nbot_token = \"YOUR_BOT_TOKEN\"\r\nchat_id = \"TARGET_CHAT_ID\"\r\nfile_path = \"/path/to/your/file.pdf\"\r\ncaption = \"Here's the document\" \r\n\r\ntry:\r\n result = send_file(file_path, bot_token, chat_id, caption=caption)\r\n print(\"\u2705 File sent successfully!\")\r\n print(\"\ud83c\udd94 File ID:\", result['result']['document']['file_id'])\r\nexcept Exception as e:\r\n print(f\"\u274c Error while sending file: {e}\")\r\n\r\n\r\n```\r\n\r\n\r\n\r\n### 4. Receiving and Auto-Saving Files\r\n\r\n```python\r\nfrom teleconnector import listen_for_files\r\n\r\nbot_token = \"YOUR_BOT_TOKEN\"\r\nchat_id = \"TARGET_CHAT_ID\"\r\nsave_directory = \"./downloads\" \r\n\r\ntry:\r\n print(\"\ud83d\udce1 Listening for incoming files... (Press CTRL+C to stop)\")\r\n for file_info in listen_for_files(bot_token, chat_id, save_dir=save_directory):\r\n file_name = file_info.get('file_name', 'Unknown')\r\n file_size = file_info.get('file_size', 0)\r\n saved_path = file_info.get('saved_path', 'Not saved')\r\n print(f\"\ud83d\udce5 Received file: {file_name} ({file_size} bytes)\")\r\n print(f\"\ud83d\udcbe Saved to: {saved_path}\")\r\nexcept KeyboardInterrupt:\r\n print(\"\\n\ud83d\uded1 Listener stopped by user.\")\r\nexcept Exception as e:\r\n print(f\"\u274c Error while listening for files: {e}\")\r\n\r\n\r\n```\r\n\r\n## Error Handling\r\n\r\nThe package raises specific exceptions you can catch:\r\n\r\n```python\r\nfrom teleconnector import send_message, TelegramAPIError\r\n\r\nbot_token = \"YOUR_BOT_TOKEN\"\r\nchat_id = \"TARGET_CHAT_ID\"\r\n\r\ntry:\r\n response = send_message(\"Test message\", bot_token, chat_id)\r\n print(\"Success:\", response)\r\nexcept TelegramAPIError as e:\r\n print(\"Telegram API Error:\", e)\r\nexcept ValueError as e:\r\n print(\"Invalid parameters:\", e)\r\nexcept Exception as e:\r\n print(\"Unexpected error:\", e)\r\n```\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please open an issue or submit a pull request on GitHub.\r\n<a href=\"https://mrfidal.in\">GitHub</a>\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Advanced Telegram Bot API Connector",
"version": "1.1.2",
"project_urls": {
"Bug Reports": "https://github.com/bytebreach/teleconnector/issues",
"Homepage": "https://github.com/bytebreach/teleconnector",
"Source": "https://github.com/bytebreach/teleconnector"
},
"split_keywords": [
"telegram",
" bot",
" api",
" messaging",
" chat",
" telegram-bot",
" telegram-api",
" file-transfer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6d1d5384d2423c4584d55aa62cf5cb30b51ba043e38b047c05847041902c28ab",
"md5": "b3e1efcc7a051f1d255e6d18f1b3cc35",
"sha256": "9243173c7ec589947625838ba8ed7e7c194e9e29d07b341851dd88e406d0af9f"
},
"downloads": -1,
"filename": "teleconnector-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b3e1efcc7a051f1d255e6d18f1b3cc35",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6033,
"upload_time": "2025-08-18T16:38:03",
"upload_time_iso_8601": "2025-08-18T16:38:03.544318Z",
"url": "https://files.pythonhosted.org/packages/6d/1d/5384d2423c4584d55aa62cf5cb30b51ba043e38b047c05847041902c28ab/teleconnector-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9dced838162e3691d33b33d563abb1e142da80ce37a935633066f5e87d4735a7",
"md5": "4a883c370e17d94f73ad1fb61ce8b3d6",
"sha256": "d77ee61689a63efb69b148df65ee139e69164ffac0925cefc18087e62099afcc"
},
"downloads": -1,
"filename": "teleconnector-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "4a883c370e17d94f73ad1fb61ce8b3d6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 4861,
"upload_time": "2025-08-18T16:38:04",
"upload_time_iso_8601": "2025-08-18T16:38:04.948908Z",
"url": "https://files.pythonhosted.org/packages/9d/ce/d838162e3691d33b33d563abb1e142da80ce37a935633066f5e87d4735a7/teleconnector-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 16:38:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bytebreach",
"github_project": "teleconnector",
"github_not_found": true,
"lcname": "teleconnector"
}
JSON
