Navbar

A Warm Welcome

Hello there, if you are looking for some help on using the Sleepy Discord Library, then you came to the right place (I hope it is). If you have any questions you can ask me ( Sleepy Flower Girl ) on Discord; right now there is no official server for this library, but you can alway find me on the Sleepy Discord Server and the Discord API server. If you like to help, you can always make a pull request for the docs or the library itself on github. Thanks!

Topics

Getting Started How To Make a Basic Text Bot
Creating Applications with Voice Breaking Changes

DiscordClient

class DiscordClient {

The DiscordClient class is the base class for a client that can be used to send and read messages.

Declared in client.h

Functions

deleteChannel

ObjectResponse<Channel> deleteChannel(Snowflake<Channel> channelID);

Parameters

channelID The id of the channel that you delete

Return value

The channel was just deleted

sendMessage

ObjectResponse<Message> sendMessage(Snowflake<Channel> channelID, std::string message, bool tts = false);
#include <sleepy_discord.h>
#include <iostream>

class MyClientClass : public SleepyDiscord::DiscordClient {
    private:
    void onReady() {
        SleepyDiscord::Message message = client.sendMessage("channel id", "Hello");
        std::cout << message.content;
    }
}

int main() {
    MyClientClass client("token");
}

Output: Message sent

Hello

Post a message to a channel.

Parameters

channelID The id of the channel you want to post the message to
message The message you want to post
tts Short for Text to Speech. When this is true, anyone with text to speech messages on will have their computer read the message out load to the them

Return value

The Message you just sent as a Message object

Other Details

Declared in client.h and defined in endpoints.cpp

Uses Create Message

addReaction

bool SleepyDiscord::DiscordClient::addReaction(Snowflake<Channel> channelID, Snowflake<Message> messageID, std::string emoji);
#include <sleepy_discord>

class MyDiscordClient : public SleepyDiscord::DiscordClient {
public:
    void onReady(SleepyDiscord::Ready data) {
        client.addReaction("channel id", "message id", "%F0%9F%98%95");
    }
}

int main() {
    SleepyDiscord::DiscordClient client("token");
}

Output: added 😕 reaction

Adds reaction to a message.

Parameters

channelID The id of the channel with the message you want to add a reaction to
messageID The id of the message you want to add a reaction to
emoji The emoji you want to use for the reaction
  • Use Percent Encoding for Unicode Emoji
  • For custom emoji, use the id of the emoji (I haven’t tested this myself)

Return value

true on success, otherwise false

Other Details

Declared in client.h and defined in endpoints.cpp

Uses Create Reaction

editMessage

ObjectResponse<Message> editMessage(Snowflake<Channel> channelID, Snowflake<Message> messageID, std::string newMessage);
ObjectResponse<Message> editMessage(Message message, std::string newMessage);

Edits an existing Message

Parameters

channelID The id of the channel with the message that you want to edit
messageID The id of the message you want to edit
message The message with the id of the message that you want to edit
newMessage The new message that you want the message to be

Return value

Returns the message you just edited

pinMessage

bool pinMessage(Snowflake<Channel> channelID, Snowflake<Message> messageID);

Puts a message into the Pinned Messages of a channel

Parameters

channelID The id of the channel with the message that you want to pin
messageID The id of the message you want to pin

Return value

Returns true on success

unpinMessage

bool unpinMessage(Snowflake<Channel> channelID, Snowflake<Message> messageID);

Removes a message from the Pinned Messages in a channel

Parameters

channelID The id of the channel with the message that you want to unpin
messageID The id of the message you want to unpin

Return value

Returns true on success

deleteMessage

bool deleteMessage(Snowflake<Channel> channelID, Snowflake<Message> messageID);

Deletes a message

Parameters

channelID The id of the channel with the messages that you want to delete
messageID An array of ids of the messages you want to delete

Return value

Returns true on success

editNickname

bool editNickname(Snowflake<Server> serverID, std::string newNickname);

Changes the name that is displayed on a server

Parameters

serverID The id of the server where you want to this nickname
newNickname The Nickname that you want your bot to have

Return value

Returns true on success

addRole

bool addRole(Snowflake<Server> serverID, Snowflake<User> userID, Snowflake<Role> roleID);

Gives a member a role on a server

Parameters

serverID The id of the server with the user you want to give the role to
memberID The id of the user that you want to give the role to
roleID The id of role that you want to give

Return value

Returns true on success

removeRole

bool removeRole(Snowflake<Server> serverID, Snowflake<User> userID, Snowflake<Role> roleID);

Takes away a role from a member on a server

Parameters

serverID The id of the server with the user you want to remove the role from
memberID The id of the user that you want to remove the role from
roleID The id of role that you want to remove from the user

Return value

Returns true on success

kickMember

bool kickMember(Snowflake<Server> serverID, Snowflake<User> userID);

Removes a member from a server

Parameters

serverID The id of the server with the user you want to remove
userID The id of the user that you want to remove

Return value

Returns true on success

banMember

bool banMember(Snowflake<Server> serverID, Snowflake<User> userID);

Bans a member from a server

Parameters

serverID The id of the server with the user you want to ban
userID The id of the user that you want to ban

getServer

ObjectResponse<Server> getServer(Snowflake<Server> serverID);

Get a server object from a ServerID

Parameters

serverID The id of the server you want to get

Return value

Return a Server object

getChannel

ObjectResponse<Channel> getChannel(Snowflake<Channel> channelID);

Get a channel object from a channelID

Parameters

channelID The id of the channel you want to get

Return value

Return a Channel object

editChannel

ObjectResponse<Channel> editChannel(Snowflake<Channel> channelID, std::string name = "", std::string topic = "");

Edit the channel name and topic and return a Channel object of that channel

Parameters

channelID The id of the channel you want to edit
name The new name for the channel
topic The new topic for the channel

Return value

Return a Channel object

editChannelName

ObjectResponse<Channel> editChannelName(Snowflake<Channel> channelID, std::string name);

Edit the channel name and return a Channel object of that channel

Parameters

channelID The id of the channel you want to edit
name The new name of the channel

Return value

Return a Channel object

deleteChannel

ObjectResponse<Channel> deleteChannel(Snowflake<Channel> channelID);

Delete a channel and return a Channel object of that channel

Parameters

channelID The id of the channel you want to delete

Return value

Return a Channel object

updateStatus

void updateStatus(std::string gameName = "", uint64_t idleSince = 0);

Updates the bot’s status

Parameters

gameName The text right under the username, without the ``Playing”
idleSince unix time in milliseconds when the client when idle, or null if the client is not idle

isReady

const bool isReady();

Tell you if the Ready event has ocurred or not

Return value

true if the ready event ocurred

quit

void quit();

Lets you disconnect from discord and stops the client

run

virtual void run();

For more information, check out custom websockets

request

Response request(const RequestMethod method, const std::string url, const std::string jsonParameters = "", const std::initializer_list<Part>& multipartParameters = {});
Response request(const RequestMethod method, const std::string url, const std::initializer_list<Part>& multipartParameters);

Used to make a request to Discord. For more information, see Session.

path

const std::string path(const char* source, ...);

Usually used with the request function. This creates a path by putting together the url and the parameters.

Parameters

source The link with “{” and “}” to specify where to place the parameters
The parameters in std::string. Parameters should go in order from when they appear in source

Return value

The url with all {, }, and in between replaced with the parameters.

Events

Events are functions that can be overridden that are called when an event such as receiving a message occur. For example, the function onMessage is an event.

onReady

virtual void onReady(std::string* jsonMessage);

onServer

virtual void onServer(SleepyDiscord::Server server);
#include <sleepy_discord.h>

#include <iostream>
#include <vector>

class myClientClass : public SleepyDiscord::DiscordClient {
public:
  using SleepyDiscord::DiscordClient::DiscordClient;
  void onServer(SleepyDiscord::Server server) {
      serverList.push_back(server);
      std::cout << "New server, name: " << server.name << "\n";
  }

private:
  std::vector<SleepyDiscord::Server> serverList;
};

int main() {
  myClientClass client("token", 2);
  client.run();

  return 0;
}

Called when a guild is created/join the client

Parameters

server Server object with all the info from the GUILD_CREATE event

onBan

virtual void onBan(std::string *jsonMessage);
#include <sleepy_discord.h>

class myClientClass : public SleepyDiscord::DiscordClient {
public:
  using SleepyDiscord::DiscordClient::DiscordClient;
  void onBan(std::string \*jsonMessage) {
    std::cout << "New ban, json data: " << \*jsonMessage << "\n";
  }
};

int main() {
  myClientClass client("token", 2);
  client.run();

  return 0;
}

Called when a member is banned from a server

Parameters

jsonMessage This is the raw data for the event, this should be changed when a proper object is implemented

onUnban

virtual void onUnban(std::string \*jsonMessage);
#include <sleepy_discord.h>

class myClientClass : public SleepyDiscord::DiscordClient {
public:
  using SleepyDiscord::DiscordClient::DiscordClient;
  void onUnban(std::string \*jsonMessage) {
    std::cout << "New Unban, json data: " << \*jsonMessage << "\n";
  }
};

int main() {
  myClientClass client("token", 2);
  client.run();

  return 0;
}

Called when an user is unbaned from the server

Parameters

jsonMessage This is the raw data for the event, this should be changed when a proper object is implemented

onMessage

virtual void onMessage(SleepyDiscord::Message message);
#include <sleepy_discord>

class myClientClass : public SleepyDiscord::DiscordClient {
public:
    using DiscordClient::DiscordClient;
    void onMessage(SleepyDiscord::Message m) {
        if (m.startsWith("whcg hello")) {
            SleepyDiscord::Message message = sendMessage(message.channelID, "Hello " + message.author.username);
            std::cout << message.content;
        }
    }
};

int main() {
    myClientClass client("token", 2);
  client.run();
}

Input: Message received

whcg hello

Possible Output: Message sent

Hello Sleepy Flower Girl

Called when the Client receives a new message.

Parameters

message Message object with all the info from the MESSAGE_CREATE event

onEditMessage

virtual void onEditMessage(std::string \*jsonMessage);
#include <sleepy_discord.h>

class myClientClass : public SleepyDiscord::DiscordClient {
public:
  using SleepyDiscord::DiscordClient::DiscordClient;
  void onEditMessage(std::string \*jsonMessage) {
    std::cout << "New edit message, json data: " << \*jsonMessage << "\n";
  }
};

int main() {
  myClientClass client("token", 2);
  client.run();

  return 0;
}

Called when a user edit a message

Parameters

jsonMessage This is the raw data for the event, this should be changed when a proper object is implemented

onQuit

virtual void onQuit();

Happens when the client is quitting and after disconnecting from Discord

schedule

virtual Timer schedule(TimedTask                 code   , const time_t millisecondsTilDueTime);
inline  Timer schedule(TimedTask                 code   , const time_t milliseconds, AssignmentType mode);
inline  Timer schedule(void (BaseDiscordClient::*code)(), const time_t milliseconds, AssignmentType mode = TilDueTime);
Snowflake<Channel> channel = message.channelID;
sendMessage(channel, "Another message will be sent in 5 seconds from now.");
schedule([this, channel]() {
    this->sendMessage(channel, "5 seconds has pasted");
}, 5000);

Creates a timer that will execute a function after the timer expires. Based on JavaScript’s setTimeout()

Parameters

code Function that will be called when times up
millisecondsTilDueTime The amount of milliseconds before execute code
milliseconds Depends on mode
mode When this is EpochTime, code will execute at milliseconds since epoch. Else, code will execute at milliseconds since schedule was called

Return

See Timer below.

Timer

Stores needed timer function. However, this does not store the function will be called when times up.

TimedTask

Stores function that will be called when times up

AssignmentType

enum AssignmentType : bool {
    TilDueTime = 0,
    EpochTime  = 1,
};

Changes what milliseconds represents in milliseconds

sleep

virtual void sleep(const unsigned int milliseconds);

Parameters

milliseconds The amount of time to sleep for in milliseconds

Called when the client needs to wait a bit

onError

virtual void onError(ErrorCode errorCode, const std::string errorMessage);

Happens when an error is detected

Parameters

errorCode The number associated with the error
errorMessage The reason or message for the given error code

Discord Objects

Objects used to represent things from Discord, these include things like messages, users, server, etc.

Snowflake

template <typename DiscordObject>
struct Snowflake {

Most Discord Objects have ids, these ids have the type called Snowflake. Snowflakes are 64 bit unsigned ints, currently Sleepy Discord stores them as strings. This is because Discord sends and receives Snowflakes as strings, because unsigned 64 bit integer support is not something every language has. By passing snowflakes as a string, you can guarantee that the receiving language will not try to change it. For example, languages like PHP stores all numbers as doubles or 64 bit floats. In theory, the json standard supports 53 bit signed integers.

Structure


Timestamp 42 bits - milliseconds since the first second of 2015
Internal worker ID 5 bits - Internally Discord has servers that create snowflakes, this id unique to each generating sever
Internal process ID 5 bits - Same thing as the worker ID but unique to each generating process
Increment 10 bits - a number that is incremented for every generated ID on the process

But if C++ has support for unsigned 64 bit integer, then why does Sleepy Discord store them as strings?

That’s a good question. The fact that they are given to the client as strings and send to Discord as a string, is the main reason why. However, the disadvantages are that the strings take up more memory then 64 bits, and that you will need to convert them to an int if you want to so some math operations with them. However, you cannot send Snowflakes as integers to Discord, as that will give you an error.

operator==, !=

inline bool operator==(const Snowflake& right);
inline bool operator==(const char* right);

inline bool operator!=(const Snowflake& right);
inline bool operator!=(const char* right);

Return value

true when comparison is true, otherwise false

operator const std::string&

operator const std::string&();

Return value

Returns the snowflake as a string of numbers.

Message

struct Message : public DiscordObject {

An object that represents a message from Discord. Also very similar to the message object from the API

(constructor)

Message(const std::string * rawJson);
Message(BaseDiscordClient* client, std::string channelID, std::string message, bool tts = false);

Initializes the Message object. However the two constructors do different things. As the 2nd one also sends a message and initializes the message object, the first one just initializes the message object. In the 2nd constructor’s implementation, it uses the first constructor to initializes the message object.

startsWith

bool startsWith(char* test);

Parameters

test the string that to compare the beginning of the message to

Return value

true when the message starts with the given string

length

int length();

Return value

The content length of the message

isMentioned

bool isMentioned(const std::string id);
bool isMentioned(User& _user);

Parameters

id The id of the user that you want to check that they were mentioned or not
_user The user object of the user you want to check that they were mentioned or not

Return value

true if the user was mentioned

send

Message send(BaseDiscordClient * client);

Parameters

client The client that will be used to send the message

Return value

The Message you just sent as a Message object

reply

Message reply(BaseDiscordClient * client, std::string message, bool tts = false);

sends a message to same channel that the parent message is on

Parameters

client The client that will be used to send the reply
message The message to use to reply
tts Short for Text to Speech. When this is true, anyone with text to speech messages on will have their computer read the message out load to the them

Return value

The Message you just sent as a Message object

operator==

bool operator==(const std::string& message);

Compares the ids of two messages

Parameters

message The message that is being compared

Return value

true when the ids of the two messages are the same

User

struct User : public DiscordObject {
  ~User();
  User();
  User(const std::string * rawJSON);

Based on the object with the same name from the api

operator==

bool operator==(const User& rightUser);

Compares the id of two Users

Parameters

rightUser The User that is being compared

Return value

true when the two Users have the same id

Voice

For a step by step guild on using voice, go to here.

VoiceContext

SleepyDiscord::VoiceContext& context = myClient.createContext("channelID", "serverID");
myClient.connectToVoiceChannel(context);

Represents the information needed to connect to a voice channel, such as the channelID and serverID.

BaseVoiceEventHandler

class VoiceEventHandler : public SleepyDiscord::BaseVoiceEventHandler {
public:
    VoiceEventHandler() {}
    void onReady(SleepyDiscord::VoiceConnection& connection) {
        connection.getDiscordClient().sendMessage("Connected to a voice channel");
    }
}
VoiceEventHandler voiceEventHandler;

Class with virtual functions for handling events related to voice.

Events

All events will give you a reference to the VoiceConnection.

onReady

onEndSpeaking

onHeartbeat

onHeartbeatAck

VoiceConnection

Class that connects to the voice channel and used for sending and receiving audio from the voice channel. The Discord client will create this for you. You get one from your VoiceEventHandler.

AudioSources

Class representing the data that will be sent when speaking. When speaking, VoiceConnection will call AudioSource::read and use the audio data gotten from that call and send it to Discord’s voice server.

Session

class GenericSession {
typedef CPRSession Session;
typedef CustomSession Session;

Session is a class that wraps any http library, for now the library only supports cpr. However this can easily change in the future thanks to the Session class.

Declared in http.h

Member types

Response When you make a request, it sends back a response. This holds the response from the request.
Part Used for multipart requests, is stores the name and file or value

Response

struct Response {
    int32_t statusCode;
    std::string text;
    std::map<std::string, std::string> header;
};

When you make a request, a response is returned. The Response struct stores the response from a request.

There are a few class derived from Response as you can see below.

StandardResponse

struct StandardResponse : Response {

Used as a base for classes that are derived from Response.

BooleanResponse

template<class BooleanFunction = StandardBooleanResponseFunction>
struct BooleanResponse : public StandardResponse {
BooleanResponse<> response = deleteMessage("channelID", "messageID");
bool wasSuccessful = response;
//you may also do this
wasSuccessful = deleteMessage("channelID", "messageID");

Can implicitly convert from Response to bool.

Template Parameters

BooleanFunction Class that acts like a function using the function call operator overload to convert a ``const Response&” into a “bool”

Resps

BooleanResponse<EmptyResp>

Resps, short for Responses, BooleanFunctions for status codes that are used to signal success. This should allow you see the response that Discord returns with added features.

ObjectResponse

template<class Type>
struct ObjectResponse : public StandardResponse {
ObjectResponse<Message> response = sentMessage("channelID", "Hello");
Message message1 = response;
//you may also do this
Message message2 = sentMessage("channelID", "Hello again");

Can implicitly convert from Response into Type.

Template Parameters

Type Class with a constructor with the parameter list that can take in just a Response*

cast

Type cast();
std::string sentMessage = sendMessage.cast().content;

returns Type from Response.

ArrayResponse

template <class Type>
using ArrayResponse = 
ArrayResponse<Message> response = getMessages("channelID", na, "");
std::vector<Message> messages = response;

Can implicitly convert from Response into a Container of Type objects.

Functions

setUrl

virtual void setUrl(const std::string& url) = 0;

setBody

virtual void setBody(const std::string* jsonParameters) = 0;

Parameters

jsonParameters The body of the Session, usually a json

setHeader

virtual void setHeader(const std::vector<SleepyDiscord::HeaderPair>& header) = 0;

Parameters

header A vector of stuff in the header

HeaderPair

Represents one line of the header

name The name of the value, or the left of the header field
value The value, or the right of the header field

setMultipart

virtual void setMultipart(const std::initializer_list<Part>& parts) = 0;

Request Methods

Everything else in the Session class makes the request, and returns the response from the request. However each one uses a different request method. Here’s a useful wikipedia about them.

Return value

The response

Post

virtual Response Post() = 0;

Patch

virtual Response Patch() = 0;

Delete

virtual Response Delete() = 0;

Get

virtual Response Get() = 0;

Put

virtual Response Put() = 0;

Custom Session

class CustomSession : public GenericSession {

Sessions are used for http requests, it’s essentially a wrapper for any http library for Sleepy Discord. CustomSession is wrapper for a wrapper of http requests and responses. To learn more about Sessions, click here.

Member types

CustomInit A function pointer to a function that returns a new Session

(constructor)

static CustomInit init;
CustomSession() : session(init()) {}

This how the CustomSession constructor calls your custom Session.

class mySession : public SleepyDiscord::GenericSession{
    ...  //imagine a filled out Session class
}
SleepyDiscord::CustomInit SleepyDiscord::Session::init = []()->SleepyDiscord::GenericSession* { return new mySession; };    //init the custom session

The constructor of the CustomSession class calls init to get a pointer to a new Session.

Custom Websockets

Without websockets, Discord can’t get anything in real time, because http only does things after a request. Think of it as the difference between active and passive. Just like CustomSession, Sleepy Discord’s websockets are customizable. Right now, there isn’t a special class for websockets, it’s part of the BaseDiscordClient class.

Functions

run

virtual void run();

A function called by the user to run the websocket client when there’s 2 or less threads that can be used for Sleepy Discord

connect

virtual bool connect(const std::string & uri) { return false; }

Called when Sleepy Discord wants to connect.

Return value

True on a successful connection.

disconnect

virtual void disconnect(unsigned int code, const std::string reason) {}

The function that Sleepy Discord uses to disconnect

send

virtual void send(std::string message);

A function used for sending things like heartbeats and status updates

runAsync

virtual void runAsync();

Runs the websocket client on another thread. This is the function that Sleepy Discord calls when it’s told to run on 3 or more threads. Generally, this function should just make a new thread and call run on the new thread.

SLEEPY_LOCK_CLIENT_FUNCTIONS

class WebSocketDiscordClient : public BaseDiscordClient {
private:
    SLEEPY_LOCK_CLIENT_FUNCTIONS
};

A macro that is a must for any Discord Clients that will be used by others, that may include you. It specifies functions that a normal user should not touch as private.

Custom UDP

Preprocessor Directives

Sleepy Discord uses some preprocessor directives such as #define and #ifdef. This is so that Sleepy Discord can be compiled in many different situations. If you are having trouble compiling Sleepy Discord, these might help, but make sure you know what they do because they will disable or add features.

SLEEPY_ONE_THREAD

SLEEPY_ONE_THREAD
-DSLEEPY_ONE_THREAD

Disables anything that has to do with threads, because threads or std::threads don’t work on everything. Currently there’s no way to add in thread support of your own device yet.

SLEEPY_CUSTOM_SESSION

SLEEPY_CUSTOM_SESSION
-DSLEEPY_CUSTOM_SESSION

Makes Sleepy Discord use the CustomSession Class for sessions, This allows you to use any http library you like to use. Click here for info on the CustomSession Class

SLEEPY_USE_HARD_CODED_GATEWAY

SLEEPY_USE_HARD_CODED_GATEWAY
-DSLEEPY_USE_HARD_CODED_GATEWAY

This makes Sleepy Discord skip connecting to api/gateway to get the gateway and instead it uses the gateway that is hard coded into Sleepy Discord.