Skip to content
BadxdPublic

About

C++ library for Telegram bot API

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

17 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

CppGram

CppGram is an independent C++20 library for Telegram. It provides:

  • an MTProto client (cppgram::Client) that signs in as a bot or a user and talks to Telegram's data centres directly, with an optional MTProxy path;
  • a Bot API layer (cppgram::bot) for HTTP-based bots. This layer is derived from tgbot-cpp (MIT); see NOTICE.

Repository: https://github.com/Badmunda05/cppgram

Version 1.0.0 is a release candidate. It is not declared stable. The release status, the open owner decisions and the evidence behind them are in FINAL_REPORT.md and TEST_MATRIX.md.

Requirements

  • A C++20 compiler. Verified with GCC 13.3.0 and Clang 18.1.3 on Linux x86_64.
  • CMake 3.16 or later.
  • OpenSSL, zlib, SQLite 3, libcurl, Boost (headers only), nlohmann/json. GoogleTest only when building the tests.

Ubuntu 24.04:

sudo apt-get install -y build-essential cmake ninja-build libssl-dev zlib1g-dev libsqlite3-dev \
    libcurl4-openssl-dev libboost-dev nlohmann-json3-dev libgtest-dev

Supported platforms

Platform Compiler Status
Linux x86_64 GCC 13.3.0 Built and tested (offline suites)
Linux x86_64 Clang 18.1.3 Built and tested (offline suites)
Linux ARM64 any Owner-reported PASS for cross-compilation and native runtime. Not rerun here (see TEST_MATRIX.md, section F)
macOS any Not tested
Windows any Not supported

See docs/PORTABILITY.md.

Features

Supported

  • MTProto client with bot login (login_bot) and user login (sign_in_code, sign_in_password, QR login).
  • Transports: intermediate, abridged and full, with obfuscated framing.
  • Typed API in include/cppgram/client.h, with typed wrappers in types.h. Every Client member is listed in docs/API_INDEX.md.
  • Update handling with filters (filters.h) and handler groups.
  • Session files in the versioned CGS2 format with a CRC-32 check, and session strings (session_string.h).
  • DC migration (USER_MIGRATE_N, PHONE_MIGRATE_N), cancellable FLOOD_WAIT waits, and reconnect with the saved authorisation key.
  • MTProxy with plain secrets and dd-prefixed (padded-intermediate) secrets.
  • Media transfer (transfer.h, media-transfer example).
  • Asynchronous operations (async.h, task.h).
  • Bot API layer for HTTP-based bots (bot.h).
  • Web App initData verification (webapp.h). This is not a cryptographic audit.
  • Structured logging with secret redaction (log.h), metrics (metrics.h, metrics_prometheus.h) and typed errors (errors.h).

Not supported

  • Fake-TLS (ee) MTProxy secrets. They are refused by design.
  • Secret chats and calls.
  • Windows.

Behavioural parity with other libraries is not claimed. PARITY_MATRIX.md records only whether the schema has a method, whether source implements it, and which test names it.

Architecture

application
    |
    +-- cppgram::Client (MTProto)  ->  transport (intermediate / abridged / full, obfuscated)
    |        |                              |
    |        +-- session store (CGS2, SQLite update state)
    |        +-- proxy (plain / dd)            -> Telegram DC or MTProxy
    |
    +-- cppgram::bot (Bot API over HTTPS, derived from tgbot-cpp)

The TL schema is generated into src/mtproto/schema/ from the inputs in schema/. See guides/ARCHITECTURE.md.

Installation

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD/install
cmake --build build
cmake --install build

The Makefile wraps the same steps: make build, make install INSTALL_PREFIX=build/install.

CMake package usage

After installation:

find_package(CppGram 1.0.0 CONFIG REQUIRED)
target_link_libraries(your_app PRIVATE cppgram::cppgram)

Or add the repository with add_subdirectory and link the same target.

Quick start

The snippet below is compile-checked against the public headers. It has not been run against Telegram.

#include <iostream>

#include "cppgram/client.h"

int main() {
    cppgram::ClientOptions opt;
    opt.api_id = 12345;                 // from https://my.telegram.org
    opt.api_hash = "your_api_hash";
    opt.session_path = "bot.sqlite";

    cppgram::Client client(opt);
    client.connect();
    client.login_bot("PLACE YOUR BOT TOKEN HERE");
    std::cout << "logged in as " << client.get_me().username << "\n";

    client.on_message(cppgram::filters::text(), [](cppgram::Client& c, const cppgram::Message& m) {
        c.send_text(m.chat, "You said: " + m.text);
    });

    client.run();
    return 0;
}

Programs under examples/ show media transfer, proxies, webhooks, keyboards and MTProto login.

Client configuration

cppgram::ClientOptions holds the API id and hash, the session path, the proxy, the logger, the metrics registry and the timeouts. Defaults and field meanings are in include/cppgram/client.h and docs/API.md.

Authentication

  • login_bot(token) signs in with a bot token.
  • User login requests a code, then calls sign_in_code(), and sign_in_password() when two-factor authentication is on.
  • QR login is in qr_login.h.
  • Guides: guides/AUTHENTICATION.md.

Session persistence

  • ClientOptions::session_path names the session file. Files use the CGS2 format with a CRC-32 check. A corrupt file raises SessionCorruptError.
  • Update state is kept in SQLite (SqliteStorage).
  • Session files and session strings are secrets. Do not commit them, log them or paste them into an issue.
  • Guides: guides/SESSIONS.md, guides/SESSION_ENCRYPTION.md.

MTProto connection

  • DC selection, transport choice, key exchange and reconnect are handled by Client.
  • FLOOD_WAIT sleeps can be cancelled. A wait past the request deadline is returned to the caller, not resent.
  • Guides: guides/RECONNECT_AND_FLOOD_WAIT.md.

Proxy support

  • Plain MTProxy secrets and dd-prefixed secrets are supported. A dd secret is dd followed by 32 hex characters.
  • Fake-TLS (ee) secrets are refused.
  • Proxy framing and its evidence: MTProxy_AUDIT.md and guides/PROXIES.md.
  • Live proxy status: see "Live testing" below.

Error handling

Failures are reported as typed exceptions derived from errors::Error (include/cppgram/errors.h). A corrupt session raises SessionCorruptError.

Async operations

async.h and task.h provide the asynchronous operation types. Concurrency and cancellation are covered by the offline test suites (see TEST_MATRIX.md).

Media

transfer.h provides upload and download with progress and cancellation. The upload path is exercised by the offline fake-DC tests. The media-transfer and receive-file examples show typical use.

Web App initData

cppgram/webapp.h verifies Telegram Web App initData and returns parsed data only when the signature and time checks pass. The checks are covered by tests/security/webapp_test.cpp. This is not a cryptographic audit.

Logging and metrics

  • cppgram/log.h: levels, components, request ids and redaction of secrets. The default level is WARN.
  • cppgram/metrics.h records counters and timings. cppgram/metrics_prometheus.h renders them in Prometheus text format. Metrics are off unless ClientOptions::metrics is set.

Testing

Offline suites (no network, no credentials):

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DENABLE_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure

Or make test. Other checks: make checks, make schema-check, make api-check, make format-check.

Results with exact commands, exit codes and counts are in TEST_RESULTS.md. Test areas and their status are in TEST_MATRIX.md.

Live testing

Live checks contact real Telegram servers or a proxy you configure. They need your own credentials, and some need an unrestricted network. Owner-reported live results (direct login, session restore, reconnect, plain and DD MTProxy, and the message loop) are recorded in TEST_MATRIX.md, section C.1. They were not reproduced in the release workspace. SOCKS5 through a live proxy is owner-reported PASS (TEST_MATRIX.md, C10). Live proxy failure injection has no recorded result; see FINAL_REPORT.md.

  • make live builds cppgram_live_check and cppgram_live_tests. It does not run them.
  • LIVE_TESTING.md lists the environment variables and how to read results.
  • The separate CppGramLiveTest project is delivered as its own archive and is hosted at https://github.com/Badxd/Cpplivetest.

Security

API documentation

Examples

Programs under examples/ are compile-checked against the public headers. They are not run in the release checks.

Contributing

Run make checks and make test before sending a change. Do not include credentials, session files or proxy secrets in a report or a test. Changes to the TL schema follow HOW_TO_UPDATE_TELEGRAM_API.md.

Documentation index

Repository layout

  • include/cppgram/: public headers
  • src/: implementation, including generated TL code in src/mtproto/schema/
  • schema/: TL input files and provenance
  • tests/: offline test suites. tests/consumer/ is an independent consumer project for the installed package
  • examples/: example programs
  • fuzz/, bench/: fuzz harnesses and benchmarks
  • tools/: checks, generators, packaging and verification scripts
  • reference/: third-party upstream material. It is not built and is not part of the CppGram API

Contact

Licence

CppGram is released under the MIT licence. See LICENSE. The Bot API layer is derived from tgbot-cpp (MIT), whose copyright notice is kept in LICENSE and NOTICE. The TL schema provenance and its LGPL-3.0 reference are described in NOTICE and schema/README.md. Review of that provenance is an open owner item (see KNOWN_ISSUES.md).

About

C++ library for Telegram bot API

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages