# Telegrammer

Telegrammer is a high-performance C++ API Gateway for Telegram Bots. It acts as a bridge between the Telegram Bot API and your local applications or microservices.

Instead of embedding Telegram logic into every service, you run **Telegrammer** as a standalone daemon. Your applications can then simply:
1.  **POST** JSON to Telegrammer to send messages.
2.  **Subscribe** via webhooks to receive incoming messages from specific chats.

## Features

*   **Simple HTTP API**: Send messages using a clean JSON REST interface.
*   **Webhook Dispatcher**: Converts Telegram Long Polling into local HTTP callbacks (webhooks), allowing your internal services to be event-driven.
*   **Username Resolution**: Automatically resolves Telegram usernames to `chat_id` based on recent activity, allowing you to address users by name.
*   **High Performance**: Built with C++23 and `libmw`, utilizing asynchronous I/O where appropriate.

## Prerequisites

*   C++23 compatible compiler (GCC 14+, Clang 18+)
*   CMake 3.24+
*   OpenSSL Development Libraries
*   Git

## Build

This project uses CMake and fetches dependencies (like `libmw`, `nlohmann/json`, `spdlog`) automatically.

```bash
mkdir build
cd build
cmake ..
make -j$(nproc)
```

## Usage

Run the executable from the build directory. You must provide your Telegram Bot Token.

```bash
./telegrammer --token "YOUR_TELEGRAM_BOT_TOKEN"
```

### Command Line Options

| Option | Description | Default |
| :--- | :--- | :--- |
| `-t, --token` | **Required.** Your Telegram Bot Token. | |
| `-p, --port` | Port to listen on. | `8080` |
| `-h, --host` | Interface to bind to. | `0.0.0.0` |
| `--help` | Show help message. | |

## API Reference

### 1. Send Message (`POST /send`)

Send a text message to a chat. You can target a user by `chat_id` OR `username`.

**Payload:**

```json
{
  "chat_id": 123456789,
  "text": "Hello form the API!"
}
```

**Using Username:**
*Note: The user must have previously messaged the bot for the username resolution to work.*

```json
{
  "username": "some_user",
  "text": "Hello user!"
}
```

### 2. Subscribe (`POST /subscribe`)

Register a callback URL for a specific chat. When the bot receives a message in that chat, it will POST the full Telegram Message JSON to your URL.

> **Note:** Subscriptions are currently stored in memory and do not persist across application restarts.

**Payload:**

```json
{
  "chat_id": 123456789,
  "callback_url": "http://localhost:9090/my-webhook"
}
```

**Callback Payload:**
Your server will receive a POST request containing the standard [Telegram Message Object](https://core.telegram.org/bots/api#message).

## Dependencies

*   [libmw](https://github.com/MetroWind/libmw) - HTTP Server/Client & Utilities.
*   [nlohmann/json](https://github.com/nlohmann/json) - JSON Parsing.
*   [spdlog](https://github.com/gabime/spdlog) - Logging.
*   [cxxopts](https://github.com/jarro2783/cxxopts) - CLI Argument Parsing.