@@ -5,14 +5,15 @@ title: Start making a bot
# Making a Ping-Pong bot
One of the first steps to getting started with the Discord API is to
write a basic ping-pong bot. We will expand on this to create more
diverse commands later, but for now, it is a good starting point.
One of ways to get started with the Discord API is to write a basic
ping-pong bot. This bot will respond to a simple command "ping."
We will expand on this to create more diverse commands later, but for
now, it is a good starting point.
## Creating a Discord Bot
Before you can begin writing your bot, it is necessary to create a bot
account on Discord .
Before writing your bot, it is necessary to create a bot account via the
Discord Applications Portal first .
1. Visit the [Discord Applications Portal].
2. Create a New Application.
@@ -37,12 +38,14 @@ Bots **cannot** use invite links; they must be explicitly invited
through the OAuth2 flow.
1. Open your bot's application on the [Discord Applications Portal].
2. Retrieve the app's **Client ID**.
2. Retrieve the application 's **Client ID**.
3. Create an OAuth2 authorization URL
`https://discordapp.com/oauth2/authorize?client_id=<CLIENT ID>&scope=bot`
- `https://discordapp.com/oauth2/authorize?client_id=<CLIENT ID>&scope=bot`
4. Open the authorization URL in your browser.
5. Select a server.
6. Click on authorize.
@@ -56,36 +59,38 @@ through the OAuth2 flow.
## Connecting to Discord
If you have not already created a project and installed Discord.Net,
do that now. (see the [Installing](xref:Guides.GettingStarted.Installation) section)
do that now.
For more information, see @Guides.GettingStarted.Installation.
### Async
Discord.Net uses .NET's [Task-based Asynchronous Pattern (TAP)]
extensively - nearly every operation is asynchronous.
extensively - nearly every operation is asynchronous. It is highly
recommended that these operations are awaited in a
properly established async context whenever possible.
It is highly recommended that these operations are awaited in a
properly established async context whenever possible. Establishing an
async context can be problematic, but not hard .
To establish an async context, we will be creating an async main method
in your console application, and rewriting the static main method to
invoke the new async main .
To do so, we will be creating an async main in your console
application, and rewriting the static main method to invoke the new
async main.
[!code-csharp[Async Context](samples/intro/async-context.cs)]
[!code-csharp[Async Context](samples/first-bot/async-context.cs)]
As a result of this, your program will now start and immediately
jump into an async context. This will allow us to create a connection
to Discord later on without need ing to worry about setting up the
to Discord later on without having to worry about setting up the
correct async implementation.
> [!TIP ]
> [!WARNING ]
> If your application throws any exceptions within an async context,
> they will be thrown all the way back up to the first non-async method;
> since our first non-async method is the program's `Main` method, this
> means that **all** unhandled exceptions will be thrown up there, which
> will crash your application. Discord.Net will prevent exceptions in
> event handlers from crashing your program, but any exceptions in your
> async main **will** cause the application to crash.
> will crash your application.
>
> Discord.Net will prevent exceptions in event handlers from crashing
> your program, but any exceptions in your async main **will** cause
> the application to crash.
[Task-based Asynchronous Pattern (TAP)]: https://docs.microsoft.com/en-us/dotnet/articles/csharp/async
@@ -100,57 +105,61 @@ parameter. See the [API Documentation] for this event.
If you are using your own logging framework, this is where you would
invoke it. For the sake of simplicity, we will only be logging to
the Console.
the console.
You may learn more about this concept in @Guides.Concepts.Logging.
[!code-csharp[Async Context](samples/intro/logging.cs)]
[!code-csharp[Async Context](samples/f irst-b ot /logging.cs)]
[API Documentation]: xref:Discord.Rest.BaseDiscordClient.Log
### Creating a Discord Client
Finally, we can create a connection to Discord. Since we are writing
a bot, we will be using a [DiscordSocketClient] along with socket
entities. See the [terminology](xref:Guides.GettingStarted.Terminology) if you're unsure of
the differences.
Finally, we can create a new connection to Discord.
Since we are writing a bot, we will be using a [DiscordSocketClient]
along with socket entities. See @Guides.GettingStarted.Terminology
if you are unsure of the differences.
To do so, create an instance of [DiscordSocketClient] in your async
main, passing in a configuration object only if necessary. For most
To establish a new connection, we will create an instance of
[DiscordSocketClient] in the new async main. You may pass in an
optional @Discord.WebSocket.DiscordSocketConfig if necessary. For most
users, the default will work fine.
Before connecting, we should hook the client's `Log` event to the
log handler that was just created. Events in Discord.Net work
similarly to other events in C#, so hook this event the way that
you typically would.
log handler that we had just created. Events in Discord.Net work
similarly to any other events in C#.
Next, you will need to "login to Discord" with the `LoginAsync`
method.
Next, you will need to "login to Discord" with the [LoginAsync]
method with the application's "token ."
You may create a variable to hold your bot's token (this can be found
on your bot's application page on the [Discord Applications Portal]).
> [!NOTE]
> Pay attention to what you are copying from the developer portal!
> A token is not the same as the application's "client secret."
> [!IMPORTANT]
> Your bot's token can be used to gain total access to your bot, so
> **do __NOT__ share this token with anyone else!** It may behoove you
> to store this token in an external fil e if you plan on distributing
> to store this token in an external sourc e if you plan on distributing
> the source code for your bot.
We may now invoke the client's `StartAsync` method, which will
We may now invoke the client's [StartAsync] method, which will
start connection/reconnection logic. It is important to note that
**this method returns as soon as connection logic has been started!**
**this method will return as soon as connection logic has been started!**
Any methods that rely on the client's state should go in an event
handler.
handler. This means that you should **not** directly be interacting with
the client before it is fully ready.
Finally, we will want to block the async main method from returning
until after the application is exited. To do this, we can await an
infinite delay or any other blocking method, such as reading from
the console.
when running the application. To do this, we can await an infinite delay
or any other blocking method, such as reading from the console.
The following lines can now be added:
[!code-csharp[Create client](samples/int ro/client.cs)]
[!code-csharp[Create client](samples/f irst-b ot /client.cs)]
At this point, feel free to start your program and see your bot come
online in Discord.
@@ -162,6 +171,8 @@ online in Discord.
> for how to fix this.
[DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient
[LoginAsync]: xref:Discord.Rest.BaseDiscordClient.LoginAsync*
[StartAsync]: xref:Discord.WebSocket.DiscordSocketClient.StartAsync*
[installation guide]: xref:Guides.GettingStarted.Installation#installing-on-net-standard-11
### Handling a 'ping'
@@ -169,18 +180,18 @@ online in Discord.
> [!WARNING]
> Please note that this is *not* a proper way to create a command.
> Use the `CommandService` provided by the library instead, as explained
> in the [Command Guide] section.
> in the [Command Guide](xref:Guides.Commands.Intro) section.
Now that we have learned how to open a connection to Discord, we can
begin handling messages that users are sending. To start out, our bot
will listen for any message where th e content is equal to `!ping` and
respond back with "Pong!".
Now that we have learned to open a connection to Discord, we can
begin handling messages that the users are sending. To start out, our
bot will listen for any message whos e content is equal to `!ping` and
will respond back with "Pong!".
Since we want to listen for new messages, the event to hook into
is [MessageReceived].
In your program, add a method that matches the signature of the
`MessageReceived` event - it must be a method (`Func`) that returns
`MessageReceived` event - it must be a method (`Func`) that returns
the type `Task` and takes a single parameter, a [SocketMessage]. Also,
since we will be sending data to Discord in this method, we will flag
it as `async`.
@@ -189,45 +200,49 @@ In this method, we will add an `if` block to determine if the message
content fits the rules of our scenario - recall that it must be equal
to `!ping`.
Inside the branch of this condition, we will want to send a message
back to the channel from which the message comes from - "Pong!" . To
find the channel, look for the `Channel` property on the message
Inside the branch of this condition, we will want to send a message,
`Pong!`, back to the channel from which the message comes from. To
find the channel, look for the `Channel` property on the message
parameter.
Next, we will want to send a message to this channel. Since the
channel object is of type [SocketMessageChannel], we can invoke the
`SendMessageAsync` instance method. For the message content, send back
a string containing "Pong!".
channel object is of type [I SocketMessageChannel], we can invoke the
[SendMessageAsync] instance method. For the message content, send back
a string, "Pong!".
You should have now added the following lines,
[!code-csharp[Message](samples/int ro/message.cs)]
[!code-csharp[Message](samples/f irst-b ot /message.cs)]
Now your first bot is complete. You may continue to add on to this
Now that your first bot is complete. You may continue to add on to this
if you desire, but for any bots that will be carrying out multiple
commands, it is strongly recommended to use the command framework as
shown below.
For your reference, you may view the [completed program].
> [!NOTE]
> For your reference, you may view the [completed program].
[MessageReceived]: xref:Discord.WebSocket.BaseSocketClient.MessageReceived
[SocketMessage]: xref:Discord.WebSocket.SocketMessage
[SocketMessageChannel]: xref:Discord.WebSocket.ISocketMessageChannel
[completed program]: samples/intro/complete.cs
[Command Guide]: xref:Guides.Commands.Intro
[SendMessageAsync]: xref:Discord.WebSocket.ISocketMessageChannel.SendMessageAsync*
[completed program]: samples/first-bot/complete.cs
# Building a bot with commands
This section will show you how to write a program that is ready for
[Commands](xref:Guides.Commands.Intro). Note that we will not be
explaining _how_ to write Commands or Services, it will only be
covering the general structure.
@Guides.Commands.Intro will guide you through how to setup a program
that is ready for [CommandService], a service that is ready for
advanced command usage.
For reference, view an [annotated example] of this structure.
[annotated example]: samples/int ro/structure.cs
[annotated example]: samples/f irst-b ot /structure.cs
It is important to know that the recommended design pattern of bots
should be to separate the program (initialization and command handler),
the modules (handle commands), and the services (persistent storage,
pure functions, data manipulation).
should be to separate...
1. the program (initialization and command handler)
2. the modules (handle commands)
3. the services (persistent storage, pure functions, data manipulation)
[CommandService]: xref:Discord.Commands.CommandService
Hsu Still