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 pinned dependencies (like libmw, nlohmann/json, and spdlog) automatically.

mkdir build
cd build
cmake ..
cmake --build . -j24

Usage

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

./telegrammer --token "YOUR_TELEGRAM_BOT_TOKEN" --db telegrammer.db

Command Line Options

API Key Management

Before using the API, you must generate an API key:

./telegrammer --add-key my_service
# Output: YOUR_GENERATED_KEY

The generated 64-character key is printed only by --add-key. Store it securely; --list-keys prints names and creation times, not credentials. The daemon stores SHA-256 digests rather than bearer tokens. The current development schema is intentionally not migrated: remove an old plaintext development database before starting this build.

API Reference

Authentication: All API requests must include the Authorization header with a valid API key: Authorization: Bearer YOUR_GENERATED_KEY

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 in a private chat for username resolution to work. IDs are the stable destination form.

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

Subscriptions are durable, owned by the API key that created them, and idempotent for the same key, chat, and callback URL. Callback delivery is queued in SQLite, retried with bounded backoff, and dead-lettered after the retry budget is exhausted.

Payload:

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

3. Subscription management

GET /subscriptions lists only the authenticated key's subscriptions. DELETE /subscriptions/{id} removes an owned subscription and its queued deliveries, returning 204 No Content. Unknown or foreign IDs return 404.

GET /health returns polling state and queue size. It requires authentication and returns 503 when polling has a persistent failure or the queue is saturated.

All API errors are JSON objects with stable uppercase error codes. Requests use Content-Type: application/json, reject unknown fields, and are limited to 64 KiB. The service accepts loopback callbacks as well as remote HTTP/HTTPS URLs; it does not follow callback redirects.

The daemon is the only process that acquires <database>.lock while running. Management commands use short SQLite connections and can be run against the same database while the daemon is active.

For the packaged systemd unit, put TELEGRAM_BOT_TOKEN=... in /etc/telegrammer/telegrammer.env with mode 0600. Provision a key against the service database as the service user, for example:

sudo -u telegrammer /usr/bin/telegrammer \
  --db /var/lib/telegrammer/telegrammer.db --add-key my-service

Dependencies

• libmw - HTTP Server/Client & Utilities.
• nlohmann/json - JSON Parsing.
• spdlog - Logging.
• cxxopts - CLI Argument Parsing.