telegram-easy 0.2.0
A very simple Python package to send and receive Telegram messages
Requires Python: >=3.8
Keywords: telegram, bot, automation

# 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.
- Command Line Interface (CLI).
- 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.


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

#### CLI using environment variables (Recommended)

```bash
telegram-easy get_updates
```

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

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

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

#### CLI using environment variables (Recommended)

```bash
telegram-easy send_message "hello world"
```

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

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

## Next steps

- Add image send/receive support.
- 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).
- If you have any suggestions, please open an [issue](https://github.com/ferranb/telegram-easy/issues).

## License

MIT