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.

• 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.

pip install telegram-easy -U

• Python 3.8+

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.

from telegram_easy import get_updates

updates = get_updates() 

from telegram_easy import get_updates

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

import asyncio
from telegram_easy.aio import get_updates

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

import asyncio
from telegram_easy.aio import get_updates

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

telegram-easy get_updates

telegram-easy get_updates --token XXX

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.

from telegram_easy import send_text_message

send_text_message(message="Hello World!")

from telegram_easy import send_text_message

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

import asyncio
from telegram_easy.aio import send_text_message

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

import asyncio
from telegram_easy.aio import send_text_message

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

telegram-easy send_message "hello world"

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

• 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.

MIT