Skip to content

About

A C++20 library for Discord user accounts. Simple API, CMake, Conan and vcpkg support. LGPL-3.0-or-later.

Topics

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

discord.cpp-self

Build Packages Release C++20 License: LGPL v3 or later

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());
}

What works

  • 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.

Build on Windows with MSYS2

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 mingw64

The 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 default

Check 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.

Add it to your project

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.

Run an example

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_TOKEN

CTest 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.exe

Set 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.

Commands

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.

Documentation

License

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.

About

A C++20 library for Discord user accounts. Simple API, CMake, Conan and vcpkg support. LGPL-3.0-or-later.

Topics

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages