A C++20 library for Discord user accounts, with a small API you can start using in a few lines. A personal project by Cavanshirpro.
Release v0.2.2 (package version 0.2.2) is an early release. Inspired by
discord.py-self, independently written
in C++, and deliberately different in API design. The goal is a complete
user-client communication layer; current coverage remains partial. See the
research inventory and roadmap.
Download: Source ZIP | Source TAR.GZ | GitHub Releases | Release notes
#include <discord/discord.hpp>
int main() {
discord::Client client;
client.on_message([&](const discord::Message& message) {
auto self = client.user();
if (self && message.author.id == self->id && message.content == "!ping") {
(void)message.reply("pong");
}
});
client.run(discord::token_from_env());
}- Send, reply, edit, delete, reactions, message history and DMs.
- Fetch users, profiles, guilds, channels, members and relationships.
- Multiple event listeners and own-message prefix commands with quoted arguments.
- Gateway heartbeats, reconnect/resume, fragmented frames and zlib-stream decompression.
- Route/shared-bucket/global HTTP rate limits, bounded retries and cancellation.
- A bounded message cache, partial update events and raw dispatch events.
- Static/shared builds and an installed CMake package named
discordSelf. - Optional camera, microphone, Go Live, receive/record and stream viewers via
MediaSession; see native media setup.
Release v0.2.2 includes an optional native C++ media backend. Prebuilt packages provide the REST/Gateway core; media is enabled in source builds. There is no custom embed sender, bot-token mode, file upload or coroutine interface. REST calls are synchronous; Gateway I/O runs on a separate thread. See the feature comparison.
Discord prohibits user-account automation. Its user API is unofficial and may change without notice; account restrictions and verification challenges are real limitations. This project does not bypass them. See the reference project's notice.
Use the MSYS2 MINGW64 terminal. Do not mix MINGW64 and UCRT64 dependencies.
pacman -S --needed mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-curl mingw-w64-x86_64-nlohmann-json mingw-w64-x86_64-zlib mingw-w64-x86_64-python
git clone https://github.com/Cavanshirpro/discord.cpp-self.git
cd discord.cpp-self
cmake --preset mingw64
cmake --build --preset mingw64
ctest --preset mingw64The preset expects MSYS2 at C:/msys64. From PowerShell, use scripts/build.ps1.
Requirements: a C++20 compiler, CMake 3.25+, Ninja, libcurl 7.86+ with ws/wss
support, nlohmann/json 3.11+, and zlib. Python 3.9+ is required for offline tests.
The matching MSYS2 bin directory must be on PATH when running executables.
On Linux, install the equivalent development packages, then use:
cmake --preset default
cmake --build --preset default
ctest --preset defaultCheck that curl --version lists ws and wss. Older distribution packages may
omit WebSockets. See the build guide for shared builds and installation.
The GitHub Release also provides native MINGW64 and UCRT64 MSYS2 packages.
Install the matching .pkg.tar.zst with pacman -U; see the
MSYS2 package guide. A central MSYS2 pacman -S
listing requires a separate reviewed submission.
The simplest way to start is to add the source to your project:
add_subdirectory(external/discord.cpp-self)
target_link_libraries(my_app PRIVATE discord::self)Examples and tests default to off in a parent project. For installed packages:
find_package(discordSelf 0.1 CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE discord::self)Install with cmake --install <build-directory> --prefix <install-prefix> and add
that prefix to CMAKE_PREFIX_PATH. Use compatible compiler and runtime ABIs.
You can also use CMake FetchContent, the Conan 2 recipe, or the vcpkg overlay
attached to v0.2.2.
The installation guide has complete examples. ConanCenter
and the central vcpkg registry are separate submissions; no central listing is
claimed by this release. Dependencies are not bundled in source archives.
Examples read DISCORD_TOKEN from the process environment; .env files are not
loaded automatically. In MINGW64, keep the credential out of shell history:
read -rs -p 'Discord token: ' DISCORD_TOKEN; echo
export DISCORD_TOKEN
./build/mingw64/discord_self_ping.exe
unset DISCORD_TOKENCTest uses only fake credentials and loopback servers. Manual account examples
are disabled unless DISCORD_SELF_BUILD_LIVE_EXAMPLES=ON is set explicitly.
For a responder that keeps listening to other users in one channel, run:
export DISCORD_REPLY_CHANNEL='123456789012345678'
./build/mingw64/discord_self_auto_reply.exeSet DISCORD_TOKEN first as shown above. The example answers hello, hi,
!ping, !help and !about. Your own !autoreply on/off/status/quit commands
control it; Ctrl+C stops it too. It filters its own/bot messages, limits reply
frequency and remembers recent message IDs. The commented examples guide
explains how to customize and run each example.
discord::Client client;
discord::Commands commands(client, "!");
commands.add("ping", [](const discord::Context& ctx) { (void)ctx.reply("pong"); });
commands.add("quit", [&](const discord::Context&) { client.close(); });
client.on_message([&](const discord::Message& message) { (void)commands.process(message); });
client.run(discord::token_from_env());Only the logged-in user's messages invoke commands. Names are case-sensitive.
ctx.arguments contains the argument text; ctx.args handles quotes and escapes.
Keep the command router alive while its callback can run.
Mentions and reply-author notifications are off by default. IDs use Snowflake,
stored as uint64_t and serialized as strings. Model values are snapshots;
edit() returns a new message. login() enables REST but validates credentials
only on the first request. user() is populated after Gateway READY; use
fetch_me() in REST-only applications.
- API reference, architecture and documentation index
- Testing and anonymized live findings
- Camera, microphone and Go Live
- User API scope and research, roadmap and changelog
- Comparison
- Contributing, security and release process
- Package installation and GitHub publishing setup
- Editor hover help and MSYS2 packages
Copyright (C) 2026 Cavanshirpro. LGPL-3.0-or-later. See LICENSE, the incorporated GPL v3 text in COPYING, the completed project copyright notice, distribution guidance and third-party notices. Discord is a trademark of Discord Inc. This project is unofficial and unaffiliated.