Name	Latest commit	Last update
📂 packages
📂 src
📄 .gitignore	Initial commit	3 weeks ago
📄 CMakeLists.txt	Initial commit	3 weeks ago
📄 README.md	Add README with documentation and persistence note	3 weeks ago
📄 design.md	Add username support to /send API	3 weeks ago
📄 prd.md	Initial commit	3 weeks ago
📄 test_api.sh	Add username support to /send API	3 weeks ago

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.

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

Usage

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

./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:

{
  "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.

{
  "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.