Beruflich Dokumente
Kultur Dokumente
Net Documentation
Release 0.7.1b1
RogueException
Documentation
Getting Started
1.1 Requirements
1.2 Installation .
1.3 Async . . . .
1.4 Example . .
.
.
.
.
3
3
3
3
3
Logging
2.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Logging Your Own Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
5
5
5
Server Management
Permissions
4.1 Channel Permissions . . . .
4.2 Dual Channel Permissions .
4.3 Setting Channel Permissions
4.4 Server Permissions . . . . .
4.5 Roles . . . . . . . . . . . .
4.6 Example . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
9
9
9
10
10
10
10
Commands
5.1 Example (Simple) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 Example (Groups) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
11
11
Voice
6.1 Broadcasting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 Multi-Server Broadcasting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3 Receiving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
13
13
13
Events
7.1 Usage . . . . . .
7.2 Connection State
7.3 Messages . . . .
7.4 Users . . . . . .
15
15
15
15
16
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
ii
Discord.Net is an unofficial C# wrapper around the Discord Chat Service. It offers several methods to create automated
operations, bots, or even custom clients.
Feel free to join us in the Discord API chat.
This is a beta!
This library has been built thanks to a community effort reverse engineering the Discord client. As the API is still
unofficial, it may change at any time without notice, breaking this library as well. Discord.Net itself is still in development (and is currently undergoing a rewrite) and you may encounter breaking changes throughout development until
the official Discord API is released.
It is highly recommended that you always use the latest version and please report any bugs you find to our Discord
chat.
This Documentation is currently undergoing a rewrite. Some pages (marked with a wrench) are not updated, or are
not completed yet.
Documentation
Documentation
CHAPTER 1
Getting Started
1.1 Requirements
Discord.Net currently requires logging in with a claimed account - anonymous logins are not supported. You can
register for a Discord account here.
New accounts are also useless when not connected to a server, so you should create an invite code for whatever server
you intend to test on using the official Discord client.
1.2 Installation
You can get Discord.Net from NuGet:
Discord.Net
Discord.Net.Commands
Discord.Net.Modules_
Discord.Net.Audio_
If you have trouble installing from NuGet, try installing dependencies manually.
You can also pull the latest source from GitHub
1.3 Async
Discord.Net uses C# tasks extensively - nearly all operations return one. It is highly recommended that these tasks be
awaited whenever possible. To do so requires the calling method be marked as async, which can be problematic in a
console application. An example of how to get around this is provided below.
For more information, go to MSDNs Await-Async section.
1.4 Example
class Program
{
static void Main(string[] args)
{
var client = new DiscordClient();
//Display all log messages in the console
client.LogMessage += (s, e) => Console.WriteLine($"[{e.Severity}] {e.Source}: {e.Message}");
//Echo back any message received, provided it didn't come from the bot itself
client.MessageReceived += async (s, e) =>
{
if (!e.Message.IsAuthor)
await e.Channel.SendMessage(e.Message.Text);
};
//Convert our sync method to an async one and block the Main function until the bot disconnects
client.ExecuteAndWait(async () =>
{
//Connect to the Discord server using our email and password
await client.Connect("discordtest@email.com", "Password123");
//If we are not a member of any server, use our invite code (made beforehand in the official Di
if (!client.Servers.Any())
await client.AcceptInvite(client.GetInvite("aaabbbcccdddeee"));
});
}
}
CHAPTER 2
Logging
Discord.Net will log all of its events/exceptions using a built-in LogManager. This LogManager can be accessed
through DiscordClient.Log
2.1 Usage
To
handle
Log
Messages
through
Log.Message<LogMessageEventArgs> Event.
Discord.Nets
Logger,
you
must
hook
into
the
The LogManager does not provide a string-based result for the message, you must put your own message format
together using the data provided through LogMessageEventArgs See the Example for a snippet of logging.
2.3 Example
class Program
{
private static DiscordBotClient _client;
static void Main(string[] args)
{
var client = new DiscordClient(x =>
{
LogLevel = LogSeverity.Info
});
Chapter 2. Logging
CHAPTER 3
Server Management
This page is a placeholder and has not been written yet. It should be coming soon!
CHAPTER 4
Permissions
There are two types of permissions: Channel Permissions and Server Permissions.
Type
Text
Voice
General
Voice
Text
General
Text
General
Text
Voice
Voice
Text
Description
Send files to a channel.
Connect to a voice channel.
Create an invite to the channel.
Text
Text
Text
Voice
Voice
Read any messages in a text channel; exposes the text channel to users.
Send messages in a text channel.
Send TTS messages in a text channel.
Speak in a voice channel.
Use Voice Activation in a text channel (for large channels where PTT is
preferred)
If a user has a permission, the value is true. If a user is denied a permission, it will be false. If the permission is not
set, the value will return null.
and
updated
with
A users server permissions also contain the default values for its channel permissions, so the channel permissions
listed above are also valid flags for Server Permissions. There are also a few extra Server Permissions:
BanMembers Server Ban users from the server. KickMembers Server Kick users from the server. They can still rejoin.
ManageRoles Server Manage roles on the server, and their permissions. ManageChannels Server Manage channels
that exist on the server (add, remove them) ManageServer Server Manage the server settings.
4.5 Roles
Managing permissions for roles is much easier than for users in channels. For roles, just access the flag under
Role.Permissions.
4.6 Example
// Find a User's Channel Permissions
var userChannelPermissions = user.GetPermissions(channel);
// Find a User's Server Permissions
var userServerPermissions = user.ServerPermissions();
var userServerPermissions = server.GetPermissions(user);
// Set a User's Channel Permissions (using DualChannelPermissions)
var userPerms = user.GetPermissions(channel);
userPerms.ReadMessageHistory = false;
userPerms.AttachFiles = null;
channel.AddPermissionsRule(user, userPerms);
}
10
Chapter 4. Permissions
CHAPTER 5
Commands
The Discord.Net.Commands package DiscordBotClient extends DiscordClient with support for commands.
//Since we have setup our CommandChar to be '~', we will run this command by typing ~greet
commands.CreateCommand("greet") //create command greet
.Alias(new string[] { "gr", "hi" }) //add 2 aliases, so it can be run with ~gr and ~hi
.Description("Greets a person.") //add description, it will be shown when ~help is used
.Parameter("GreetedPerson", ParameterType.Required) //as an argument, we have a person we wan
.Do(async e =>
{
await client.SendMessage(e.Channel, e.User.Name + " greets " + e.GetArg("GreetedPerson"))
//sends a message to channel with the given text
});
//we would run our commands with ~do greet X and ~do bye X
commands.CreateGroup("do", cgb =>
{
cgb.CreateCommand("greet")
.Alias(new string[] { "gr", "hi" })
.Description("Greets a person.")
.Parameter("GreetedPerson", ParameterType.Required)
.Do(async e =>
{
await client.SendMessage(e.Channel, e.User.Name + " greets " + e.GetArg("Gree
});
cgb.CreateCommand("bye")
.Alias(new string[] { "bb", "gb" })
.Description("Greets a person.")
.Parameter("GreetedPerson", ParameterType.Required)
.Do(async e =>
{
await client.SendMessage(e.Channel, e.User.Name + " says goodbye to " + e.Get
});
});
11
12
Chapter 5. Commands
CHAPTER 6
Voice
This page is a placeholder and has not been written yet. It should be coming soon!
6.1 Broadcasting
6.2 Multi-Server Broadcasting
6.3 Receiving
13
14
Chapter 6. Voice
CHAPTER 7
Events
7.1 Usage
Messages from the Discord server are exposed via events on the DiscordClient class and follow the standard EventHandler<EventArgs> C# pattern.
Warning: Note that all synchronous code in an event handler will run on the gateway sockets thread and should
be handled as quickly as possible. Using the async-await pattern to let the thread continue immediately is recommended and is demonstrated in the examples below.
7.3 Messages
MessageReceived, MessageUpdated and MessageDeleted are raised when a new message arrives, an existing
one has been updated (by the user, or by Discord itself), or deleted.
MessageAcknowledged is only triggered in client mode, and occurs when a message is read on another device
logged-in with your account.
Example of MessageReceived:
// (Preface: Echo Bots are discouraged, make sure your bot is not running in a public server if you u
// Hook into the MessageReceived event using a Lambda
_client.MessageReceived += async (s, e) => {
// Check to make sure that the bot is not the author
if (!e.Message.IsAuthor)
// Echo the message back to the channel
await e.Channel.SendMessage(e.Message);
};
15
7.4 Users
There are several user events:
UserBanned: A user has been banned from a server.
UserUnbanned: A user was unbanned.
UserJoined: A user joins a server.
UserLeft: A user left (or was kicked from) a server.
UserIsTyping: A user in a channel starts typing.
UserUpdated: A user object was updated (presence update, role/permission change, or a voice state update).
Note: UserUpdated Events include a User object for Before and After the change. When accessing the User, you
should only use e.Before if comparing changes, otherwise use e.After
Examples:
16
Chapter 7. Events