Show / Hide Table of Contents

    Your First Bot

    Note

    This article assumes the following:

    • You have created a bot account and have a bot token.
    • You have Visual Studio 2019 installed on your computer.

    Create a Project

    Open up Visual Studio and click on Create a new project towards the bottom right.

    Visual Studio Start Screen

    Select Console App (.NET Core) then click on the Next button.

    New Project Screen

    Next, you'll give your project a name. For this example, we'll name it MyFirstBot. If you'd like, you can also change the directory that your project will be created in.

    Enter your desired project name, then click on the Create button.

    Name Project Screen

    Voilà! Your project has been created!

    Visual Studio IDE

    Install Package

    Now that you have a project created, you'll want to get DSharpPlus installed. Locate the solution explorer on the right side, then right click on Dependencies and select Manage NuGet Packages from the context menu.

    Dependencies Context Menu

    You'll then be greeted by the NuGet package manager.

    Select the Browse tab towards the top left, then type DSharpPlus into the search text box.

    NuGet Package Search

    The first results should be the six DSharpPlus packages.

    Search Results

    Package Description
    DSharpPlus Main package; Discord API client.
    DSharpPlus.CommandsNext Add-on which provides a command framework.
    DSharpPlus.SlashCommands Add-on which provides an application command framework.
    DSharpPlus.Interactivity Add-on which allows for interactive commands.
    DSharpPlus.Lavalink Client implementation for Lavalink. Useful for music bots.
    DSharpPlus.VoiceNext Add-on which enables connectivity to Discord voice channels.
    DSharpPlus.Rest REST-only Discord client.

    We'll only need the DSharpPlus package for the basic bot we'll be writing in this article. Select it from the list then click the Install button to the right (after verifing that you will be installing the latest version).

    Install DSharpPlus

    You're now ready to write some code!

    First Lines of Code

    DSharpPlus implements Task-based Asynchronous Pattern. Because of this, the majority of DSharpPlus methods must be executed in a method marked as async so they can be properly awaited.

    Due to the way the compiler generates the underlying IL code, marking our Main method as async has the potential to cause problems. As a result, we must pass the program execution to an async method.

    Head back to your Program.cs tab and empty the Main method by deleting line 9.

    Code Editor

    Now, create a new static method named MainAsync beneath your Main method. Have it return type Task and mark it as async. After that, add MainAsync().GetAwaiter().GetResult(); to your Main method.

    static void Main(string[] args)
    {
        MainAsync().GetAwaiter().GetResult();
    }
    
    static async Task MainAsync()
    {
    
    }   
    

    If you typed this in by hand, Intellisense should have generated the required using directive for you. However, if you copy-pasted the snippet above, VS will complain about being unable to find the Task type.

    Hover over Task with your mouse and click on Show potential fixes from the tooltip.

    Error Tooltip

    Then apply the recommended solution.

    Solution Menu

    We'll now create a new DiscordClient instance in our brand new asynchronous method.

    Create a new variable in MainAsync and assign it a new DiscordClient instance, then pass an instance of DiscordConfiguration to its constructor. Create an object initializer for DiscordConfiguration and populate the Token property with your bot token then set the TokenType property to Bot. Next add the Intents property and populated it with the AllUnprivileged value. These Intents are required for certain Events to be fired. Please visit this article for more information.

    var discord = new DiscordClient(new DiscordConfiguration()
    {
        Token = "My First Token",
        TokenType = TokenType.Bot,
        Intents = DiscordIntents.AllUnprivileged     
    });
    
    Warning

    We hard-code the token in the above snippet to keep things simple and easy to understand.

    Hard-coding your token is not a smart idea, especially if you plan on distributing your source code. Instead you should store your token in an external medium, such as a configuration file or environment variable, and read that into your program to be used with DSharpPlus.

    Follow that up with ConnectAsync to connect and login to Discord, and await Task.Delay(-1); at the end of the method to prevent the console window from closing prematurely.

    var discord = new DiscordClient();
    
    await discord.ConnectAsync();
    await Task.Delay(-1);
    

    As before, Intellisense will have auto generated the needed using directive for you if you typed this in by hand. If you've copied the snippet, be sure to apply the recommended suggestion to insert the required directive.

    If you hit F5 on your keyboard to compile and run your program, you'll be greeted by a happy little console with a single log message from DSharpPlus. Woo hoo!

    Program Console

    Spicing Up Your Bot

    Right now our bot doesn't do a whole lot. Let's bring it to life by having it respond to a message!

    Hook the MessageCreated event fired by DiscordClient with a lambda. Mark it as async and give it two parameters: s and e.

    discord.MessageCreated += async (s, e) =>
    {
    
    };
    

    Then, add an if statement into the body of your event lambda that will check if Content starts with your desired trigger word and respond with a message using RespondAsync if it does. For this example, we'll have the bot to respond with pong! for each message that starts with ping.

    discord.MessageCreated += async (s, e) =>
    {
        if (e.Message.Content.ToLower().StartsWith("ping")) 
            await e.Message.RespondAsync("pong!");
    };
    

    The Finished Product

    Your entire program should now look like this:

    using System;
    using System.Threading.Tasks;
    using DSharpPlus;
    
    namespace MyFirstBot
    {
        class Program
        {
            static void Main(string[] args)
            {
                MainAsync().GetAwaiter().GetResult();
            }
    
            static async Task MainAsync()
            {
                var discord = new DiscordClient(new DiscordConfiguration()
                {
                    Token = "My First Token",
                    TokenType = TokenType.Bot
                });
    
                discord.MessageCreated += async (s, e) =>
                {
                    if (e.Message.Content.ToLower().StartsWith("ping")) 
                        await e.Message.RespondAsync("pong!");
    
                };
    
                await discord.ConnectAsync();
                await Task.Delay(-1);
            }
        }
    }
    

    Hit F5 to run your bot, then send ping in any channel your bot account has access to. Your bot should respond with pong! for each ping you send.

    Congrats, your bot now does something!

    Bot Response

    Further Reading

    Now that you have a basic bot up and running, you should take a look at the following:

    • Events
    • CommandsNext
    • Improve this Doc
    Back to top © 2016-2022 DSharpPlus Contributors