Metadata-Version: 2.4
Name: telegram-easy
Version: 0.1.0
Summary: A very simple Python package to send and receive Telegram messages
Author-email: Ferran Busquets <ferranb@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ferranb/telegram-easy
Keywords: telegram,bot,automation
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Dynamic: license-file

# telegram-easy

[![PyPI version](https://badge.fury.io/py/telegram-easy.svg)](https://badge.fury.io/py/telegram-easy)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

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](https://core.telegram.org/bots/samples#python).

## Features

- Send text messages to Telegram bots.
- Receive update messages.
- Synchronous and asynchronous APIs.
- Environment variable support for credentials.
- No external Telegram frameworks required.

## Installation

```bash
pip install telegram-easy
```

## Python version

- Python 3.8+

## Configuration

Create a Telegram bot using [BotFather](https://t.me/BotFather) and save your Bot Token.

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

```bash
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.

## Usage

### Receive messages

#### Synchronous using environment variables (Recommended)

```python
from telegram_easy import get_updates

updates = get_updates() 
```

#### Synchronous with no environment variables (Not recommended)

```python
from telegram_easy import get_updates

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

#### Asynchronous using environment variables (Recommended)
```python
import asyncio
from telegram_easy.aio import get_updates

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

#### Asynchronous with no environment variables (Not recommended)

```python
import asyncio
from telegram_easy.aio import get_updates

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


### 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:

```python
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)

```python
from telegram_easy import send_text_message

send_text_message(message="Hello World!")
```

#### Synchronous with no environment variables (Not recommended)

```python
from telegram_easy import send_text_message

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


#### Asynchronous using environment variables (Recommended)

```python
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)

```python
import asyncio
from telegram_easy.aio import send_text_message

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

## Next steps

- Add more features to [get_updates](https://core.telegram.org/bots/api#getupdates).
- Add more features to [send_text_message](https://core.telegram.org/bots/api#sendmessage).
- Add CLI support.
- Add image send/receive support.
- If you have any suggestions, please open an [issue](https://github.com/ferranb/telegram-easy/issues).

## License

MIT
