telegram-easy 0.2.0

A very simple Python package to send and receive Telegram messages

telegram-easy

A minimal, lightweight Python package to send and receive Telegram Bot messages, with both synchronous and asynchronous APIs.

Designed for simple automation and monitoring use cases where only basic Telegram Bot interactions are required.

For more advanced features, see the official Telegram Bot Python examples.

Features

• Send text messages to Telegram bots.
• Receive update messages.
• Synchronous and asynchronous APIs.
• Environment variable support for credentials.
• Command Line Interface (CLI).
• No external Telegram frameworks required.

Installation

pip install telegram-easy

Python version

• Python 3.8+

Configuration

Create a Telegram bot using BotFather and save your Bot Token.

Avoid hardcoding credentials. You can configure the package using environment variables:

export TELEGRAM_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"

If token or chat_id parameters are not explicitly provided, the package will try to read them from these variables.

Receive messages

Synchronous using environment variables (Recommended)

from telegram_easy import get_updates

updates = get_updates() 

Synchronous with no environment variables (Not recommended)

from telegram_easy import get_updates

updates = get_updates(token="xxx")
print(updates)

Asynchronous using environment variables (Recommended)

import asyncio
from telegram_easy.aio import get_updates

updates = asyncio.run(get_updates())
print(updates)

Asynchronous with no environment variables (Not recommended)

import asyncio
from telegram_easy.aio import get_updates

updates = asyncio.run(get_updates(token="xxx"))
print(updates)

CLI using environment variables (Recommended)

telegram-easy get_updates

CLI with no environment variables (Not recommended)

telegram-easy get_updates --token XXX

Get the Chat ID

To get the chat_id id you have different methods.

The easiest method if you have access to the chat is to open the chat in Telegram Web and look in the URL:

https://web.telegram.org/a/#1234567890

In this case the chat_id is 1234567890.

If you don't have access to the chat or if the chat url does not have a number, you can use the following method. Send (or request the owner to send) manually a message to your bot from the Telegram App or Web, then run:

from telegram_easy import get_updates

updates = get_updates()
for update in updates.get("result", []):
    chat_id = update["message"]["chat"]["id"]
    user_name = update["message"]["from"].get("first_name", "Unknown")
    print(f"User: {user_name}, Chat ID: {chat_id}")

Save that CHAT_ID to use it when sending messages to the bot.

Send a text message

Synchronous using environment variables (Recommended)

from telegram_easy import send_text_message

send_text_message(message="Hello World!")

Synchronous with no environment variables (Not recommended)

from telegram_easy import send_text_message

send_text_message(message="Hello World!", token="123",chat_id="1234")

Asynchronous using environment variables (Recommended)

import asyncio
from telegram_easy.aio import send_text_message

asyncio.run(send_text_message(message="Hello World!"))

Asynchronous with no environment variables (Not recommended)

import asyncio
from telegram_easy.aio import send_text_message

asyncio.run(send_text_message(message="Hello World!", token="123",chat_id="1234"))

CLI using environment variables (Recommended)

telegram-easy send_message "hello world"

CLI with no environment variables (Not recommended)

telegram-easy send_message "hello world" --token XXX --client_id XXX

Next steps

• Add image send/receive support.
• Add more features to get_updates.
• Add more features to send_text_message.
• If you have any suggestions, please open an issue.

License

MIT