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.
- 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| 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.
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 intypes.h. EveryClientmember is listed indocs/API_INDEX.md. - Update handling with filters (
filters.h) and handler groups. - Session files in the versioned
CGS2format with a CRC-32 check, and session strings (session_string.h). - DC migration (
USER_MIGRATE_N,PHONE_MIGRATE_N), cancellableFLOOD_WAITwaits, and reconnect with the saved authorisation key. - MTProxy with plain secrets and
dd-prefixed (padded-intermediate) secrets. - Media transfer (
transfer.h,media-transferexample). - Asynchronous operations (
async.h,task.h). - Bot API layer for HTTP-based bots (
bot.h). - Web App
initDataverification (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.
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.
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD/install
cmake --build build
cmake --install buildThe Makefile wraps the same steps: make build, make install INSTALL_PREFIX=build/install.
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.
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.
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.
login_bot(token)signs in with a bot token.- User login requests a code, then calls
sign_in_code(), andsign_in_password()when two-factor authentication is on. - QR login is in
qr_login.h. - Guides:
guides/AUTHENTICATION.md.
ClientOptions::session_pathnames the session file. Files use theCGS2format with a CRC-32 check. A corrupt file raisesSessionCorruptError.- 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.
- DC selection, transport choice, key exchange and reconnect are handled by
Client. FLOOD_WAITsleeps can be cancelled. A wait past the request deadline is returned to the caller, not resent.- Guides:
guides/RECONNECT_AND_FLOOD_WAIT.md.
- Plain MTProxy secrets and
dd-prefixed secrets are supported. Addsecret isddfollowed by 32 hex characters. - Fake-TLS (
ee) secrets are refused. - Proxy framing and its evidence:
MTProxy_AUDIT.mdandguides/PROXIES.md. - Live proxy status: see "Live testing" below.
Failures are reported as typed exceptions derived from errors::Error (include/cppgram/errors.h). A corrupt session
raises SessionCorruptError.
async.h and task.h provide the asynchronous operation types. Concurrency and cancellation are covered by the offline
test suites (see TEST_MATRIX.md).
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.
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.
cppgram/log.h: levels, components, request ids and redaction of secrets. The default level is WARN.cppgram/metrics.hrecords counters and timings.cppgram/metrics_prometheus.hrenders them in Prometheus text format. Metrics are off unlessClientOptions::metricsis set.
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-failureOr 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 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 livebuildscppgram_live_checkandcppgram_live_tests. It does not run them.LIVE_TESTING.mdlists 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.
- Report security issues privately to the maintainer. Do not open a public issue.
- Review and open items:
security-review.md,SECURITY.md,guides/THREAT_MODEL.md.
docs/API.md: public APIdocs/API_INDEX.md: everyClientmember and its definitionguides/API_SUPPORT.md: API support notes
Programs under examples/ are compile-checked against the public headers. They are not run in the release
checks.
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.
FINAL_REPORT.md,TEST_RESULTS.md,TEST_MATRIX.mdMTProxy_AUDIT.md,KNOWN_ISSUES.md,KNOWN_LIMITATIONS.mdCHANGELOG.md,RELEASE_NOTES.mdguides/: installation, authentication, sessions, proxies, troubleshooting, threat model
include/cppgram/: public headerssrc/: implementation, including generated TL code insrc/mtproto/schema/schema/: TL input files and provenancetests/: offline test suites.tests/consumer/is an independent consumer project for the installed packageexamples/: example programsfuzz/,bench/: fuzz harnesses and benchmarkstools/: checks, generators, packaging and verification scriptsreference/: third-party upstream material. It is not built and is not part of the CppGram API
- Email: mumda.bad1322@gmail.com
- Telegram group: https://t.me/PBXCHATS
- Updates channel: https://t.me/PBX_UPDATE
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).