Bot Lifecycle
It's important to know the life-cycle of a discord bot to properly handle disconnects. The following state diagram shows the 4 states a bot can have:
\u{1F4A1} The four states
Connected
The bot is connected to the websocket and receives all events.
Disconnected
The bot is not connected to the websocket and receives no events. It's not uncommon for a bot to occasionally lose connection. This can have various reasons, for example:
- Your bot lost its internet connection
- Discord restarted the gateway server you are currently connected to
- A plane crashed into Discord's data center
The bot will periodically try to resume/reconnect to the websocket. It will start with a small frequency and increase it with every failed reconnect attempt. You can modify the reconnect delay with the DiscordApi#setReconnectDelay(...) method. The following example code would increase the delay linearly. The 1st attempt would be delayed for 2 seconds, the 2nd attempt for 4 seconds, the 3rd attempts for 6 seconds, ...
api.setReconnectDelay(attempt -> attempt * 2);
+Important: Bots can only reconnect 1000 times in a 24-hour period (every ~90 seconds). This limit is global and across all shards. Upon hitting this limit, all active sessions for the bot will be terminated, the bot's token will be reset, and you will receive an email notification. This is the reason Javacord increases the reconnect delay with every attempt.
By default, the $default_delay$ formula below is used to calculate the reconnect delay
$$ default_delay(a) = \\lfloor a^{1.5} - \\frac{a^{1.5}}{\\frac{1}{(0.1 \\cdot a)} + 1} \\rceil $$
with $a$ being the attempt.
The formula will generate the following reconnect delay:
| Attempt | Delay |
|---|---|
| 1 | 1 |
| 2 | 2 |
| 3 | 4 |
| 4 | 6 |
| 5 | 7 |
| ... | ... |
| 10 | 16 |
| 15 | 23 |
| 20 | 30 |
| ... | ... |
| 50 | 59 |
| 100 | 91 |
| 150 | 115 |
| ... | ... |
Resuming
Resuming is only possible for a short time after being disconnected. If the bot can successfully resume the connection, you will not miss any events. Your bot will receive all events you missed while being disconnected. The cache gets updated accordingly.
Reconnecting
If your bot reconnects (not resumes!), the whole cache gets wiped, and you will not receive any missed events.
What does this mean?
`,22),h=t("References to entities (e.g. a "),m=e("code",null,"Server",-1),f=t(", "),b=e("code",null,"User",-1),v=t(", "),g=e("code",null,"Channel",-1),y=t(", ...) will be outdated. This is why you should never store entities, but the id instead. See "),k=t("Entity Cache"),w=t("."),_=e("li",null,"You will miss events. There's no way to receive the missed events.",-1),x=e("li",null,[t("Listeners attached to entities will "),e("strong",null,"not"),t(" be affected, because they are bound to the entity's id, not the object itself.")],-1),T=n(`\u{1F48A} How to handle disconnects
For most bots, there's nothing you have to do. All registered listeners are reconnect-resistant, which means if your bot is only reacting to events, it will work fine after a restart. For example, the following code will not be affected by a reconnect (besides maybe some missed !ping messages):
api.addMessageCreateListener(event -> {
+ if (event.getMessage().getContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+});
+In case you want to handle reconnects (e.g. fetch the message history to detect missed messages), there are special connection-related listeners which can be used to track the state of the bot:
LostConnectionListenerReconnectListenerResumeListener
Interaction Commands aka. Slash Commands
INFO
There are a lot of convenient methods which aim to make your life easier with i.e., not being able to have an invalid configuration of your builder. Therefore, the following examples will only show the usage with the convenient methods.
\u{1F4A1} Creating a Command
INFO
There are 2 different types of Commands:
- Global | Available for every Server once your Bot gets invited: Created with
createGlobal(DiscordApi). - Server | Only available on the specific Server: Created with
createForServer(Server).
Let's get started with the most basic command, a ping command.
SlashCommand command = SlashCommand.with("ping", "Checks the functionality of this command")
+ .createGlobal(api)
+ .join();
+That's all you have to do!
Let's have a look at a more complex command which involves nearly all possibilities:
SlashCommand command =
+ SlashCommand.with("channel", "A command dedicated to channels",
+ Arrays.asList(
+ SlashCommandOption.createWithOptions(SlashCommandOptionType.SUB_COMMAND_GROUP, "edit", "Edits a channel",
+ Arrays.asList(
+ SlashCommandOption.createWithOptions(SlashCommandOptionType.SUB_COMMAND, "allow", "Allows a permission to a user for a channel",
+ Arrays.asList(
+ SlashCommandOption.create(SlashCommandOptionType.CHANNEL, "channel", "The channel to modify", true),
+ SlashCommandOption.create(SlashCommandOptionType.USER, "user", "The user which permissions should be changed", true),
+ SlashCommandOption.createWithChoices(SlashCommandOptionType.DECIMAL, "permission", "The permission to allow", true,
+ Arrays.asList(
+ SlashCommandOptionChoice.create("manage", 0),
+ SlashCommandOptionChoice.create("show", 1)))
+ ))))))
+ .createGlobal(api)
+ .join();
+Let that sink in first!
What are we doing here?
- We create a base command called
channel. - It has a SUB_COMMAND_GROUP called
editwhich basically is just a folder where you can put your commands in. - There's a SUB_COMMAND called
allowwhich is our actual command. Therefore, our complete argument looks likechannel edit allow. - The SUB_COMMAND has 3 arguments:
- The channel which should be edited.
- The user which permissions should be changed.
- A predefined list of available permissions the command executor can choose of.
\u{1F4D4} Notes on creating commands:
The REQUIRED attribute
You can only mark the last argument as being not required. This means it can be optionally set by the command executor. In the above example you could i.e. set the PERMISSIONS argument to false.
Command structure
Your command has to follow these structures in order to be successfully created:
Command structure
VALID
+
+command
+|
+|__ subcommand
+|
+|__ subcommand
+
+----
+
+command
+|
+|__ subcommand-group
+ |
+ |__ subcommand
+|
+|__ subcommand-group
+ |
+ |__ subcommand
+
+----
+
+VALID
+
+command
+|
+|__ subcommand-group
+ |
+ |__ subcommand
+|
+|__ subcommand
+
+-------
+
+INVALID
+
+
+command
+|
+|__ subcommand-group
+ |
+ |__ subcommand-group
+|
+|__ subcommand-group
+ |
+ |__ subcommand-group
+
+----
+
+INVALID
+
+command
+|
+|__ subcommand
+ |
+ |__ subcommand-group
+|
+|__ subcommand
+ |
+ |__ subcommand-group
+\u2935\uFE0F Get your commands
All global commands:
Set<SlashCommand> commands = api.getGlobalSlashCommands().join();
+All commands only available on a single server:
Server server = ...;
+Set<SlashCommand> commands = api.getServerSlashCommands(server).join();
+WARNING
Getting all commands from a server only contains the commands you have created on this specific server. Therefore, the returned list does not include any global command!
\u{1F528} Updating Commands
When updating your commands you only have to include what you actually want to change. The following updater will change the previous created command and change its base name from channel to channels.
SlashCommand updatedCommand =
+ new SlashCommandUpdater(commandId)
+ .setName("channels")
+ .updateGlobal(api)
+ .join();
+\u270D\uFE0F Bulk overwriting commands
If you have to update / create multiple commands at once it advised to use the batch updater to only have to do 1 request.
DiscordApi api = ...;
+
+Set<SlashCommandBuilder> builders = new HashSet<>();
+builders.add(new SlashCommandBuilder().setName("server").setDescription("A command for the server"));
+builders.add(new SlashCommandBuilder().setName("permission").setDescription("A command for permissions"));
+
+api.bulkOverwriteGlobalApplicationCommands(builders).join();
+\u{1F46E}\u200D\u2642\uFE0F Permissions
Permissions exist to enable / disable the usage of your commands for certain things. These things may be:
- Permissions
- DMs
When you create a command you can specify which permissions are required to use it. In addition to the required permissions, you can also specify whether the command should be available in DMs.
SlashCommand.with("ping","Ping!")
+ .setDefaultEnabledForPermissions(PermissionType.ADMINISTRATOR, PermissionType.BAN_MEMBERS)
+ //.setDefaultDisabled() Effectively the same as setDefaultEnabledForPermissions(PermissionType.ADMINISTRATOR) but this will lead to the default type by Discord.
+ .setEnabledInDms(false)
+ .createGlobal(api)
+ .join();
+INFO
Once your bot has been invited to a server, you can not change the permissions afterwards on this server. Then it's up to the server administrators / owner to correctly set up the commands for users / roles / channels.
\u2757 Limits
Registering a command
- Server commands are specific to the server you specify when making them. Server commands are not available in DMs. Command names are unique per application within each scope (global and server). That means:
- Your app cannot have two global commands with the same name
- Your app cannot have two server commands within the same name on the same guild
- Your app can have a global and guild command with the same name
- Multiple apps can have commands with the same names
General
- An app can have up to 100 top-level global commands with unique names
- An app can have up to an additional 100 server commands per server
- An app can have up to 25 subcommand groups on a top-level command
- An app can have up to 25 subcommands within a subcommand group
- Commands can have up to 25 options
- Options can have up to 25 choices
- Maximum of 4000 characters for combined name, description, and value properties for each command and its subcommands and groups
- Limitations on nesting subcommands and groups
- Global rate limit of 200 slash command creates per day per server
\u{1F914} What the heck is a future?
A future is basically a wrapper, that will contain a value in the future but might not contain it right now. This is useful, if a method call requires some time and should not block the execution of your current code. You can easily see the difference with a primitive speed comparison:
long currentTime = System.currentTimeMillis();
+channel.sendMessage("Test 1");
+channel.sendMessage("Test 2");
+channel.sendMessage("Test 3");
+channel.sendMessage("Test 4");
+channel.sendMessage("Test 5");
+// Prints "4 ms"
+System.out.println((System.currentTimeMillis() - currentTime) + " ms");
+long currentTime = System.currentTimeMillis();
+channel.sendMessage("Test 1").join();
+channel.sendMessage("Test 2").join();
+channel.sendMessage("Test 3").join();
+channel.sendMessage("Test 4").join();
+channel.sendMessage("Test 5").join();
+// Prints "894 ms"
+System.out.println((System.currentTimeMillis() - currentTime) + " ms");
+TIP
join() blocks the current thread until the method finished. This will be explained later.
\u{1F4D6} Methods
join()
The join method blocks the current thread until the method finished. It returns the method's result or throws a CompletionException if anything failed.
The following example would create a new text channel in a given server and sends a message directly afterwards.
// Create the channel
+ServerTextChannel channel = new ServerTextChannelBuilder(server)
+ .setName("new-channel")
+ .create()
+ .join();
+// Send a message in the new channel
+Message message = channel.sendMessage("First!").join();
+// Adds an reaction to the message. Even though this method doesn't return anything,
+// join() ensures, that an exception is thrown in case something went wrong
+message.addReaction("\u{1F44D}").join();
+DANGER
You should avoid join() for methods which will be called frequently.
TIP
While join() can become a performance issue when you call it very frequently, it is very convenient to use and easy to understand. If you are new to programming and just want to get your first bot working, this is a good method to start with.
Once you gathered more experience, we highly advise against using join as it negatively impacts your bot's performance!
thenAccept(...)
The thenAccept method accepts a Consumer, that consumes the result of the method and is executed asynchronously. It is the method you usually want to use most of the time.
The following example would create a new text channel in a given server and send a message directly afterwards.
new ServerTextChannelBuilder(server)
+ .setName("new-channel")
+ .create()
+ .thenAccept(channel -> {
+ channel.sendMessage("First!").thenAccept(message -> {
+ message.addReaction("\u{1F44D}");
+ });
+ });
+DANGER
The example code above has a major problem: Any exception that might occur will be completely ignored. This makes it very hard to find bugs.
For example, if your bot doesn't have the permissions to create a new channel, it will just fail silently.
exceptionally(...)
The exceptionally method accepts a Function as parameter, which consumes possible exceptions and returns a fallback value.
The following example would create a new text channel in a given server and send a message directly afterwards. If something fails (e.g., if the bot isn't allowed to create a text channel in the server), it will log an exception.
new ServerTextChannelBuilder(server)
+ .setName("new-channel")
+ .create()
+ .thenAccept(channel -> {
+ channel.sendMessage("First!").thenAccept(message -> {
+ message.addReaction("\u{1F44D}").exceptionally(e -> {
+ e.printStackTrace(); // Adding the reaction failed
+ return null;
+ });
+ }).exceptionally(e -> {
+ e.printStackTrace(); // Message sending failed
+ return null;
+ });
+ }).exceptionally(e -> {
+ e.printStackTrace(); // Channel creation failed
+ return null;
+ });
+Wow! This looks ugly \u{1F92E}. But worry not! There are many options to improve this code!
To make things simpler for you, Javacord has the ExceptionLogger class, which can be used here. It logs every exception you didn't catch manually.
new ServerTextChannelBuilder(server)
+ .setName("new-channel")
+ .create()
+ .thenAccept(channel -> {
+ channel.sendMessage("First!").thenAccept(message -> {
+ message.addReaction("\u{1F44D}").exceptionally(ExceptionLogger.get());
+ }).exceptionally(ExceptionLogger.get());
+ }).exceptionally(ExceptionLogger.get());
+Okay! This is at least a little better, but still not really perfect \u{1F914}.
thenCompose()
`,26),j=n("The "),C=s("code",null,"thenCompose",-1),F=n(" methods allows you to chain futures. It takes a "),M={href:"https://docs.oracle.com/javase/8/docs/api/java/util/function/Function.html",target:"_blank",rel:"noopener noreferrer"},S=n("Function"),A=n(" as parameter, that consumes the future's value and expects a new future to be returned."),N=o(`The example to create a text channel can now be written like this:
new ServerTextChannelBuilder(server)
+ .setName("new-channel")
+ .create()
+ .thenCompose(channel -> channel.sendMessage("First!"))
+ .thenCompose(message -> message.addReaction("\u{1F44D}"))
+ .exceptionally(ExceptionLogger.get());
+Finally \u{1F389}! Now we only need a single exceptionally(...) call at the end. We also got rid of the nested callbacks (usually referred to as "callback hell").
For better understanding, here's the example with comments that tell you the type at each line:
new ServerTextChannelBuilder(server) // ServerTextChannelBuilder
+ .setName("new-channel") // ServerTextChannelBuilder
+ .create() // CompletableFuture<ServerTextChannel>
+ .thenCompose(channel -> channel.sendMessage("First!")) // CompletableFuture<Message>
+ .thenCompose(message -> message.addReaction("\u{1F44D}")) // CompletableFuture<Void>
+ .exceptionally(ExceptionLogger.get()); // CompletableFuture<Void>
+\u{1F4DA} Further Read
`,6),E=n("This tutorial only focuses on the absolute basics. For a more detailed introduction to CompletableFutures, you can take a look at "),B={href:"https://www.callicoder.com/java-8-completablefuture-tutorial/",target:"_blank",rel:"noopener noreferrer"},R=n("this tutorial"),I=n("."),L=n("You should also take a look at the JavaDoc for a complete list of methods: "),V={href:"https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html",target:"_blank",rel:"noopener noreferrer"},W=n("CompletableFuture JavaDoc"),D=n(".");function J(P,G){const p=e("RouterLink"),t=e("ExternalLinkIcon");return i(),u("div",null,[k,s("div",d,[m,s("p",null,[h,a(p,{to:"/wiki/essential-knowledge/lambdas/"},{default:l(()=>[v]),_:1}),g])]),s("p",null,[f,s("a",b,[w,a(t)]),y,s("a",_,[x,a(t)]),q]),T,s("p",null,[j,C,F,s("a",M,[S,a(t)]),A]),N,s("p",null,[E,s("a",B,[R,a(t)]),I]),s("p",null,[L,s("a",V,[W,a(t)]),D])])}var O=c(r,[["render",J],["__file","completable-futures.html.vue"]]);export{O as default}; diff --git a/assets/components.html.604ea486.js b/assets/components.html.604ea486.js new file mode 100644 index 0000000..14b111c --- /dev/null +++ b/assets/components.html.604ea486.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-35e5cc98","path":"/wiki/basic-tutorials/interactions/components.html","title":"Message Components","lang":"en-US","frontmatter":{"keywords":["interaction","component","button","actionrow","selectmenus"]},"excerpt":"","headers":[{"level":2,"title":"\u2754 What are components?","slug":"what-are-components","children":[]},{"level":2,"title":"\u{1F4A1} Sending a message with a component","slug":"sending-a-message-with-a-component","children":[]}],"git":{"updatedTime":1692105785000,"contributors":[{"name":"Dominic Fellbaum","email":"d.fellbaum@hotmail.de","commits":1}]},"filePathRelative":"wiki/basic-tutorials/interactions/components.md"}');export{e as data}; diff --git a/assets/components.html.e89a60b6.js b/assets/components.html.e89a60b6.js new file mode 100644 index 0000000..7b128f6 --- /dev/null +++ b/assets/components.html.e89a60b6.js @@ -0,0 +1,20 @@ +import{_ as n,o as s,c as a,e as t}from"./app.151ccb98.js";const e={},p=t(`Message Components
\u2754 What are components?
Components are interactive elements like buttons or hidden elements like the ActionRow which use is for displaying the visible components. You can add them to a message and interact with users in a very convenient way. Currently, the only interactive components available at the moment are buttons. They differ in style and behaviour(link redirect) seen in the picture below: 
\u{1F4A1} Sending a message with a component
Sending a component with your message is a simple as that:
TextChannel channel = ...;
+
+new MessageBuilder()
+ .setContent("Click on one of these Buttons!")
+ .addComponents(
+ ActionRow.of(Button.success("success", "Send a message"),
+ Button.danger("danger", "Delete this message"),
+ Button.secondary("secondary", "Remind me after 5 minutes")))
+ .send(channel);
+
You simply add a High Level component like an ActionRow which is a container for displaying your components. In turn the ActionRow consist of the components you can interact with like Buttons.
This works for Select Menus as well:
TextChannel channel = ...;
+
+new MessageBuilder()
+ .setContent("Select an option of this list!")
+ .addComponents(
+ ActionRow.of(SelectMenu.create("options", "Click here to show the options", 1, 1,
+ Arrays.asList(SelectMenuOption.create("Option One", "You selected Option One!", "Click here to select Option One"),
+ SelectMenuOption.create("Option Two", "You selected Option Two!", "Click here to select Option Two"),
+ SelectMenuOption.create("Option Three", "You selected Option Three!", "Click here to select Option Three")))))
+ .send(channel);
+
2. Switch to Bot
TIP
If you want to, you can rename your application first
3. Click on Add bot and confirm the popup
4. Copy the bot's token. In this case the token would be NDc[...]pCs. You can just click on Copy.
DANGER
This token is used to login your bot. Keep it secret!
5. If you want to, you can change the bot's name and avatar on this page, too.
\u2795 How to add a bot to your server
Bots cannot join a server on their own like normal Discord users can. Instead, the owner of a server has to invite the bot using a so called Invite Link. There are multiple ways to create the invite link:
Use Javacord to create the invite link
The easiest way to obtain an invite link for your bot is by letting Javacord do it for you. Simply execute the following code, and it will print the invite link to your console:
DiscordApi api = new DiscordApiBuilder().setToken("your token").login().join();
+System.out.println(api.createBotInvite());
+If you don't have Javacord setup yet, you can also create the invite link manually.
Create the invite link manually
Get the client id
In order to add a bot to your server you need its client id.
`,19),D=t("You can get your client id from the "),N={href:"https://discord.com/developers/applications/me",target:"_blank",rel:"noopener noreferrer"},J=t("same page"),E=t(" where you created it."),S=o('With this id you can create an invite link for your bot.
If you are the owner or admin of the server, you can use this link to add your bot to your server. Otherwise, you have to give the link to the server owner/admins and ask them to add your bot.
TIP
Unlike the token, you don't have to keep your client id secret
Create the url
Just use the following link and replace 123456789 with your own client id.
https://discord.com/api/oauth2/authorize?client_id=123456789&scope=applications.commands%20bot&permissions=0
You can calculate the permissions (in the link above it's the 0) on the page where you created the bot:
\u{1F64B}\u200D\u2642\uFE0F Use the invite link
You can now open the link and add the bot to your server:
TIP
Only the owner and admins of a server can invite bots. If you do not own a server yet, it is recommended to create one for testing.
Creating Channels, Invites, etc.
Javacord provides XyzBuilder classes to create new Discord entities like channels, webhooks, servers, and many more.
\u{1F4D5} Create Channels
You can get the channel builders for a specific server using the Server#createXyzChannelBuilder or by directly calling the constructor. Creating a ServerVoiceChannel would look like this:
Server server = ...;
+ServerVoiceChannel channel = new ServerVoiceChannelBuilder(server)
+ .setName("example-channel")
+ .setUserlimit(10)
+ .create().join();
+\u{1F4D7} Create Webhooks
You can get the WebhookBuilder for a specific text channel:
ServerTextChannel channel = ...;
+Webhook webhook = new WebhookBuilder(channel)
+ .setName("Captain Hook")
+ .setAvatar(new File("C:/Users/Bastian/Pictures/puppy.jpg"))
+ .create().join();
+\u{1F4D8} Create Invites
You can get the InviteBuilder for a specific server channel:
ServerTextChannel channel = ...;
+Invite invite = new InviteBuilder(channel)
+ .setMaxAgeInSeconds(60*60*24)
+ .setMaxUses(42)
+ .create().join();
+\u{1F4D9} Create Servers
You can get the ServerBuilder from the current api instance:
DiscordApi api = ...;
+long serverId = new ServerBuilder(api)
+ .setName("My Awesome Server")
+ .setIcon(api.getYourself().getAvatar())
+ .setVerificationLevel(VerificationLevel.HIGH)
+ .setDefaultMessageNotificationLevel(DefaultMessageNotificationLevel.ONLY_MENTIONS)
+ .setRegion(Region.EU_CENTRAL)
+ .create().join();
+WARNING
By default, bots can only create servers if they are in less than 10 servers. You can contact the Discord support to request a higher limit.
\u{1F527} Setup
1. Start Eclipse
2. Create a new project (File -> New -> Project)
3. Select Maven Project
4. Click Next
5. Check Create a simple project
6. Click Next
7. Enter a group id (e.g. com.github.yourname)
8. Enter an artifact id (e.g. myfirstbot)
9. Click Finish
10. Double click on the pom.xml file
11. Select pom.xml
12. Now you have to add Javacord as a dependency by editing the pom.xml file. Your file should now look like this:
<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>your.package.name</groupId>
+ <artifactId>myfirstbot</artifactId>
+ <version>1.0-SNAPSHOT</version>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.javacord</groupId>
+ <artifactId>javacord</artifactId>
+ <version>$latest-version</version>
+ <type>pom</type>
+ </dependency>
+ </dependencies>
+
+</project>
+ 13. Create a new package inside the src/main/java folder
14. Create a new class inside this package
15. Save the project (you should do this from time to time)
16. Now you can start coding! Example code:
package com.github.yourname.myfirstbot;
+
+import org.javacord.api.DiscordApi;
+import org.javacord.api.DiscordApiBuilder;
+
+public class Main {
+
+ public static void main(String[] args) {
+ // Insert your bot's token here
+ String token = "your token";
+
+ DiscordApi api = new DiscordApiBuilder().setToken(token).login().join();
+
+ // Add a listener which answers with "Pong!" if someone writes "!ping"
+ api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ });
+
+ // Print the invite url of your bot
+ System.out.println("You can invite the bot by using the following url: " + api.createBotInvite());
+ }
+
+}
+\u{1F3C3}\u200D\u2640\uFE0F Run the code
You can run your code by clicking on the small green arrow 
Embeds
Embeds are attached to messages and have a special design. The usually look like this:
\u{1F528} Creating an Embed
Javacord provides an EmbedBuilder which can be used to create embeds:
// Create the embed
+EmbedBuilder embed = new EmbedBuilder()
+ .setTitle("Title")
+ .setDescription("Description")
+ .setAuthor("Author Name", "http://google.com/", "https://cdn.discordapp.com/embed/avatars/0.png")
+ .addField("A field", "Some text inside the field")
+ .addInlineField("An inline field", "More text")
+ .addInlineField("Another inline field", "Even more text")
+ .setColor(Color.BLUE)
+ .setFooter("Footer", "https://cdn.discordapp.com/embed/avatars/1.png")
+ .setImage(new File("C:/Users/Bastian/Pictures/puppy.jpg"))
+ .setThumbnail(new File("C:/Users/Bastian/Pictures/kitten2.png"));
+// Send the embed
+channel.sendMessage(embed);
+\u{1F4F7} Supported Image Sources
By default, Discord expects embed images to be a link (e.g., the image link used in setFooter(...)), but you can also use attachments for images. If you provide a non-url image source (e.g. the puppy.jpg file used in setImage(...)), Javacord automatically uploads them as an attachment to the message and uses this attachment for the embed.
\u{1F512} Embed Limits
| Type | Limit |
|---|---|
| Title | 256 characters |
| Description | 4096 characters |
| Field Amount | Up to 25 fields |
| Field Name | 256 characters |
| Field Value | 1024 characters |
| Footer Text | 2048 characters |
| Author Name | 256 characters |
In addition to the limits above, the sum of all characters in an embed structure must not exceed 6000 characters.
\u2753 FAQ
What is the second parameter of setAuthor(...)?
.setAuthor("Author Name", "http://google.com/", "https://cdn.discordapp.com/embed/avatars/0.png")
+- First parameter: The name of the author
- Second parameter: A link for the author (e.g. their homepage). Can be
null. - Third parameter: The avatar of the author
What's the difference between an inline field and a normal one?
Normal fields always start in a new line, whereas several inline fields can be in the same line.
Can I change the placement of inline fields?
No, Discord does not allow different embed layouts.
How can I format text in an embed?
`,21),r=n("Discord allows for a subset of markdown to be used. See "),u={href:"https://support.discord.com/hc/en-us/articles/210298617-Markdown-Text-101-Chat-Formatting-Bold-Italic-Underline-",target:"_blank",rel:"noopener noreferrer"},h=n("their docs"),m=n(" for the specifics.");function k(b,f){const s=t("ExternalLinkIcon");return o(),i("div",null,[d,a("p",null,[r,a("a",u,[h,c(s)]),m])])}var v=e(l,[["render",k],["__file","embeds.html.vue"]]);export{v as default}; diff --git a/assets/emojis-and-reactions.html.7f613dfc.js b/assets/emojis-and-reactions.html.7f613dfc.js new file mode 100644 index 0000000..768f462 --- /dev/null +++ b/assets/emojis-and-reactions.html.7f613dfc.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-13e99c06","path":"/wiki/basic-tutorials/emojis-and-reactions.html","title":"Emojis and Reactions","lang":"en-US","frontmatter":{"keywords":["create emoji","emoji creation","unicode emoji","custom emojis","delete emojis","emoji deletion","send emoji","use emoji","KnownCustomEmoji"]},"excerpt":"","headers":[{"level":2,"title":"\u{1F6B4}\u200D\u2642\uFE0F Unicode Emojis","slug":"unicode-emojis","children":[{"level":3,"title":"What are Unicode emojis?","slug":"what-are-unicode-emojis","children":[]},{"level":3,"title":"How to use them in messages","slug":"how-to-use-them-in-messages","children":[]},{"level":3,"title":"How to use them for reactions","slug":"how-to-use-them-for-reactions","children":[]}]},{"level":2,"title":"\u{1F938}\u200D\u2640\uFE0F Custom Emojis","slug":"custom-emojis","children":[{"level":3,"title":"What are custom emojis?","slug":"what-are-custom-emojis","children":[]},{"level":3,"title":"How to use them in messages","slug":"how-to-use-them-in-messages-1","children":[]},{"level":3,"title":"How to use them for reactions","slug":"how-to-use-them-for-reactions-1","children":[]},{"level":3,"title":"How to get the tag","slug":"how-to-get-the-tag","children":[]}]},{"level":2,"title":"\u{1F451} Javacord Emoji \\"Hierarchy\\"","slug":"javacord-emoji-hierarchy","children":[{"level":3,"title":"What is a KnownCustomEmoji?","slug":"what-is-a-knowncustomemoji","children":[]}]},{"level":2,"title":"\u{1F44C} Recommended libraries","slug":"recommended-libraries","children":[]}],"git":{"updatedTime":1692105785000,"contributors":[{"name":"Dominic Fellbaum","email":"d.fellbaum@hotmail.de","commits":1}]},"filePathRelative":"wiki/basic-tutorials/emojis-and-reactions.md"}');export{e as data}; diff --git a/assets/emojis-and-reactions.html.ce8f0b41.js b/assets/emojis-and-reactions.html.ce8f0b41.js new file mode 100644 index 0000000..22093b0 --- /dev/null +++ b/assets/emojis-and-reactions.html.ce8f0b41.js @@ -0,0 +1,12 @@ +import{_ as o,r as i,o as c,c as p,a as n,b as t,e as s,d as a}from"./app.151ccb98.js";const u={},r=s('Emojis and Reactions
There are two different kinds of emojis in Discord: Unicode emojis and custom emojis.
\u{1F6B4}\u200D\u2642\uFE0F Unicode Emojis
What are Unicode emojis?
',4),d=a('Unicode emojis are "normal" text emojis which are supported by (nearly) all chat clients, including Discord. You can find a list with all Unicode emojis here: '),l={href:"https://unicode.org/emoji/charts/full-emoji-list.html",target:"_blank",rel:"noopener noreferrer"},m=a("Full Emoji List"),h=a("."),g=s(`How to use them in messages
You can either directly add them in your code, e.g.
channel.sendMessage("Hi! \u{1F603}");
+or use the normal "tag" like you would in the Client:
channel.sendMessage("Hi! :smiley:");
+
How to use them for reactions
Adding unicode reactions is only possible by using the "real" reaction. It doesn't support tags like :smiley:.
message.addReaction("\u{1F603}"); // works
+message.addReaction(":smiley:"); // doesn't work
+
\u{1F938}\u200D\u2640\uFE0F Custom Emojis
What are custom emojis?
Custom emojis are emojis that are created in a server. You can get all custom emojis the bot knows by using DiscordApi#getCustomEmojis().
How to use them in messages
To use custom emojis, you have to know its "tag", which has the format <:name:id>. You can get it by calling CustomEmoji#getMentionTag():
channel.sendMessage("Hi! <:javacord:415465982715494402>");
+CustomEmoji emoji = ...;
+channel.sendMessage("Hi! " + emoji.getMentionTag());
+How to use them for reactions
You can either directly use the custom emoji object or use the tag without the <: > if you don't have access a custom emoji object (e.g., because it's from a different shard):
CustomEmoji emoji = ...;
+message.addReaction(emoji);
+message.addReaction("javacord:415465982715494402");
+How to get the tag
Just add a \\ in front of the emoji and press Enter
\u{1F451} Javacord Emoji "Hierarchy"
In Javacord, all Emojis are a child of the Emoji interface:
What is a KnownCustomEmoji?
Known custom emojis are emojis that the bot knows because it's a member of the server with this emoji. A custom emoji can be unknown if someone adds a reaction with an unknown emoji for example. A KnownCustomEmoji has additional methods like getServer() or updateName(String).
\u{1F44C} Recommended libraries
`,32),k=a("If you are working a lot with Unicode emojis, it's recommended to use a library like "),v={href:"https://github.com/felldo/JEmoji",target:"_blank",rel:"noopener noreferrer"},j=a("JEmoji"),b=a(". It enables you to do things like the following:"),f=s(`message.addReaction(EmojiManager.getByAlias(":thumbsup:"));
+Entity Cache
Javacord keeps an internal cache for entities (e.g. Servers, Channels, Users, ...). It is important to know how the cache behaves to properly use it.
\u{1F52E} What is in the cache?
Nearly every entity known by the bot is guaranteed to be in the cache. There are a few exceptions though:
Users
',5),k=s("Users are only cached when you have the "),h=n("code",null,"GUILD_MEMBERS",-1),m=s(" intent enabled. See "),v=s("Gateway Intents"),g=s(" for more information."),b=n("h4",{id:"messages",tabindex:"-1"},[n("a",{class:"header-anchor",href:"#messages","aria-hidden":"true"},"#"),s(" Messages")],-1),f=s("Not every single message is in the cache, which means you can encounter messages which exist but are not in the cache. This can happen for most message events, e.g. the "),_={href:"https://ci.javacord.org/javadoc/org/javacord/api/event/message/reaction/ReactionAddEvent.html",target:"_blank",rel:"noopener noreferrer"},w=n("code",null,"ReactionAddEvent",-1),y=s(". You can, however, interact with these messages without having them in the cache. Every message event has methods like "),j=n("code",null,"event.deleteMessage()",-1),q=s(", "),E=n("code",null,'event.editMessage("New Content")',-1),x=s(". If you need the message (e.g. to get its content), you can request it using "),M=n("code",null,"event.requestMessage()",-1),S=s("."),I=s("Additionally, you can use the static methods in the "),B={href:"https://ci.javacord.org/javadoc/org/javacord/api/entity/message/Message.html",target:"_blank",rel:"noopener noreferrer"},C=n("code",null,"Message",-1),L=s(" class which only require the channel and message id, e.g. "),R=n("code",null,'Message.edit(api, channelId, messageId, "New content");',-1),N=s(". This is very useful if you want to store them in a database."),W=o(`Webhooks and Invites
Webhooks and Invites are not kept in the cache at all and won't receive any updates.
Embeds
Embeds from message.getEmbed() won't receive updates. If a message's embed gets edited, getEmbed() will return a completely new embed object.
\u2753 When are cached entities updated?
Javacord's cache exclusively uses websocket events to keep the cache up to date. This means that the content of your objects might be outdated, even though you modified it yourself:
Messages message = ...;
+System.out.println(message.getContent()); // Prints the old content, e.g. "old content"
+message.edit("new content").join(); // Edits the message and waits for success
+System.out.println(message.getContent()); // Still prints "old content"
+Thread.sleep(1000);
+System.out.println(message.getContent()); // Most likely prints "new content" now
+\u231A How long are cached entities valid?
Even though entities are usually kept in the cache for a very long time, you should not keep references to these objects for a longer period of time, but store the id / use event methods:
// Bad
+Message message = ...;
+message.addReactionAddListener(event -> {
+ if (event.getEmoji().equalsEmoji("\u{1F44E}")) {
+ message.delete(); // Prevents "message" from being garbage collected
+ }
+});
+
+// Good
+Message message = ...;
+message.addReactionAddListener(event -> {
+ if (event.getEmoji().equalsEmoji("\u{1F44E}")) {
+ event.deleteMessage(); // Does not use the message object
+ }
+});
+// Bad
+Set<User> usersWithBadMood = new HashSet<>();
+api.addReactionAddListener(event -> {
+ if (event.getEmoji().equalsEmoji("\u{1F626}")) {
+ usersWithBadMood.add(event.getUser());
+ }
+});
+
+// Good
+Set<Long> usersWithBadMood = new HashSet<>();
+api.addReactionAddListener(event -> {
+ if (event.getEmoji().equalsEmoji("\u{1F626}")) {
+ usersWithBadMood.add(event.getUser().getId());
+ }
+});
+Some examples of when cached entities are invalidated:
- The bot lost its connection to Discord and had to reconnect (not resume)
- You weren't able to receive updates for an entity, e.g. for
Channel, because you left and rejoined a server
Q: What is ... in the code examples?
You have to replace the ... with an instance that can be assigned to the datatype seen left.
For example, if you see TextChannel channel = ..., you have to replace ... with an instance that is a TextChannel which you can get from the API api.getTextChannelById(CHANNEL_ID) (note this returns an Optional<TextChannel>) or from an event like messageCreateEvent.getChannel().
Q: Why is my code not working?
There are multiple reasons why your code might not work. The most common ones are:
',5),x=e("li",null,"Your code is not being reached. So make sure your code actually gets executed with a print statement or a debugger.",-1),v=t("Add at least "),q=e("code",null,".exceptionally(ExceptionLogger.get())",-1),b=t(" to every "),C=e("a",{href:"../essential-knowledge/completable-futures"},"CompletableFuture",-1),E=t(" (like when sending a message) to show any exceptions that might come from Discord."),A=a('User#getRoles(Server) do not return the roles of the user. To fix this make sure to add the GUILD_MEMBERS intent.NoSuchElementException. Congratulations, you have killed a kitten! You are most likely getting this Exception because you handle Optionals wrong. Read the article on Optionals to learn how to use them correctly.How to properly ask a question to get fast support?
Don't ask:
Why is my code not working?
+//Code
+Why am I getting Exception X?
+To ensure all information is provided that is needed to solve your issue, you should ask your question in a format like:
I have an issue with: YOUR_ISSUE
+I want to do: WHAT_YOU_WANT_TO_DO
+Currently this happens: WHAT_HAPPENS_NOW
+
+//Code
+
+//Exception
+The exception is thrown in the following line(not the number): CODE_LINE
+Q: What differs Javacord from JDA and D4J?
While all 3 libraries are Wrappers for the programming language Java, they use different techniques and concepts for their API.
- Javacord: Uses Java classes for its API like CompletableFuture for async requests and Optional for return types which may be
null.- Sending a Message:
channel.sendMessage("Javacord") - Checking if the Author of a message is a user:
message.getMessageAuthor().asUser().isPresent()
- Sending a Message:
- JDA: Has its own wrapper to execute requests and returns
nullif values are not present.- Sending a Message:
channel.sendMessage("JDA").queue() - Checking if the Author of a message is a user:
message.getMember() != null
- Sending a Message:
- Discord4J: Takes on the
reactiveapproach.- Sending a Message:
channel.createMessage("Pong!").block();
- Sending a Message:
Gateway Intents
Discord allows you to "subscribe" to specific groups of events. These "subscriptions" are called intent. Disabling intents that are not required for your bot can significantly increase your bot's performance.
\u{1F4CB} List of Intents
Below you can find a table with all intents supported by Discord.
| Intent | Safe to Disable | Privileged |
|---|---|---|
GUILDS | \u274C | \u274C |
GUILD_MEMBERS | \u2714\uFE0F | \u2714\uFE0F |
GUILD_BANS | \u26A0\uFE0F* | \u274C |
GUILD_EMOJIS | \u26A0\uFE0F* | \u274C |
GUILD_INTEGRATIONS | \u2714\uFE0F | \u274C |
GUILD_WEBHOOKS | \u2714\uFE0F | \u274C |
GUILD_INVITES | \u2714\uFE0F | \u274C |
GUILD_VOICE_STATES | \u26A0\uFE0F* | \u274C |
GUILD_PRESENCES | \u2714\uFE0F | \u2714\uFE0F |
GUILD_MESSAGES | \u2714\uFE0F | \u274C |
GUILD_MESSAGE_REACTIONS | \u2714\uFE0F | \u274C |
GUILD_MESSAGE_TYPING | \u2714\uFE0F | \u274C |
DIRECT_MESSAGES | \u2714\uFE0F | \u274C |
DIRECT_MESSAGE_REACTIONS | \u2714\uFE0F | \u274C |
DIRECT_MESSAGE_TYPING | \u2714\uFE0F | \u274C |
MESSAGE_CONTENT | \u2714\uFE0F | \u2714\uFE0F |
AUTO_MODERATION_CONFIGURATION | \u2714\uFE0F | \u274C |
AUTO_MODERATION_EXECUTION | \u2714\uFE0F | \u274C |
* Will most likely work, but needs further testing
',6),k={class:"custom-container tip"},v=n("p",{class:"custom-container-title"},"Good to know!",-1),m=n("em",null,"Guild",-1),b=s(" is a synonym for servers, commonly used in Discord's API. See "),g=s("Glossary"),_=s("."),f=n("h2",{id:"what-happens-when-i-disable-some-intents",tabindex:"-1"},[n("a",{class:"header-anchor",href:"#what-happens-when-i-disable-some-intents","aria-hidden":"true"},"#"),s(" \u{1F4A1} What Happens When I Disable Some Intents?")],-1),E=n("p",null,"When you disable some of the listed intents, Javacord will not fire events that belong to the intents and will not update these specific parts of the cache.",-1),I=n("p",null,[s("At the moment, we don't have a list which events are affected by which intents (but it will come soon\u2122\uFE0F). However, most intents should be self-explanatory. E.g. when you disable the "),n("code",null,"DIRECT_MESSAGES"),s(" intent, your bot will not receive any private messages.")],-1),S=n("h2",{id:"privileged-intents",tabindex:"-1"},[n("a",{class:"header-anchor",href:"#privileged-intents","aria-hidden":"true"},"#"),s(" \u{1F451} Privileged Intents")],-1),y=s('Some intents are defined as "privileged" due to the sensitive nature of the data. To use these intents, you have to go to your bot in the '),w={href:"https://discord.com/developers/applications",target:"_blank",rel:"noopener noreferrer"},T=s("Developer Portal"),D=s(" (where you created bot) and manually enable the intents:"),A=n("p",null,[n("img",{src:r,alt:""})],-1),x=n("p",null,"There are some additionally restrictions for bots that are in over 100 servers:",-1),G=n("ul",null,[n("li",null,"Your bot must be verified"),n("li",null,"Your bot must be whitelisted to use this intents")],-1),N=s("Take a look at the official article from Discord about this topic and how to verify your bot: "),U={href:"https://support.discord.com/hc/en-us/articles/360040720412",target:"_blank",rel:"noopener noreferrer"},j=s("Bot Verification and Data Whitelisting"),O=s("."),L=o(`\u2757 Notable Intents
The following two intents are especially noteworthy: GUILD_MEMBERS and GUILD_PRESENCES. Besides being privileged, they have some special implications for Javacord:
GUILD_PRESENCES
This intent is required to get updates about a user's status (i.e., if they are online, what game they are playing, ...). Additionally, without this intent it might take considerably longer to cache all users because of ratelimits (up to 10 minutes for shards with 1000 servers). It is advised against setting DiscordApiBuilder#setWaitForAllUsersOnStartup(true) without this intent, unless absolutely necessary.
GUILD_MEMBERS
This intent is required to keep all users in Javacord's cache. Without this intent, methods like Server#getMembers() or DiscordApi#getCachedUsers() will return empty collections. However, you will still be able to access users from objects like messages, e.g. Message#getUserAuthor() will still work.
MESSAGE_CONTENT
This intent is a bit different to the other as it does not act as a toggle to receive any events. It's sole purpose is to receive the message content, attachments, components, and embeds. Otherwise, these fields will be empty when you receive a Message object.
\u2699\uFE0F Setting Intents
Javacord allows you to specify intents in the DiscordApiBuilder prior to login. There are many options to set intents. The following example code shows the most common ones:
Set All Non-Privileged Intents (Default)
This method enables all non-privileged intents. This is the default setting in Javacord.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .setAllNonPrivilegedIntents()
+ .login()
+ .join();
+Set All Non-Privileged Intents Except
This method enabled all non-privileged intents, except the given ones.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .setAllNonPrivilegedIntentsExcept(Intent.GUILD_WEBHOOKS)
+ .login()
+ .join();
+Set All Intents
This method enabled all intents.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .setAllIntents()
+ .login()
+ .join();
+Set All Intents Except
This method enabled all intents, except the given ones.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .setAllIntentsExcept(Intent.GUILD_PRESENCES, Intent.GUILD_WEBHOOKS)
+ .login()
+ .join();
+Set Intents
This method only enables the given intents.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .setIntents(Intent.GUILDS, Intent.DIRECT_MESSAGES)
+ .login()
+ .join();
+Add Intents
This method adds the intents to the currently enabled ones(by default all non-privileged). This is useful i.e. if you only want to enable 1 privileged intent like the MESSAGE_CONTENT
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .addIntents(Intent.MESSAGE_CONTENT)
+ .login()
+ .join();
+Introduction
Welcome to the Javacord wiki! \u{1F44B}
This wiki will help you to get started with your first Discord bot as fast as possible.
\u{1F4DA} Structure of the wiki
The wiki is divided into four groups:
- Getting Started focuses on teaching you how to setup up everything to get the most basic bot working.
- Basic tutorials contains articles about various concepts and classes of Javacord. Take a look at the headlines of each article and decide yourself, if it is relevant for you.
- Advanced Topics focuses on some more advanced topics that are not strictly necessary to start working with Javacord, but might become handy later on.
- Essential Knowledge teaches you the most important Java features/classes that you should know to comfortably work with Javacord. If you already have decent Java knowledge, you can skip this completely.
\u{1F91D} Support
While the wiki is great and covers many aspects of Javacord, we highly recommended you to join our Discord server if you have any questions:
',8),h=t("Join the "),u={href:"https://discord.gg/javacord",target:"_blank",rel:"noopener noreferrer"},p=t("Javacord server");function f(g,v){const o=r("ExternalLinkIcon");return s(),i("div",null,[l,e("ul",null,[e("li",null,[h,e("strong",null,[e("a",u,[p,n(o)])])])])])}var m=a(d,[["render",f],["__file","index.html.vue"]]);export{m as default}; diff --git a/assets/intellij-gradle.html.4d5164dd.js b/assets/intellij-gradle.html.4d5164dd.js new file mode 100644 index 0000000..49f275b --- /dev/null +++ b/assets/intellij-gradle.html.4d5164dd.js @@ -0,0 +1,42 @@ +import{_ as r,r as a,o as p,c as l,b as s,w as t,a as e,d as n,e as d}from"./app.151ccb98.js";var u="/assets/create-project.f0c107a4.png",k="/assets/select-gradle.959beb91.png",g="/assets/new-project.7658c402.png",h="/assets/new-project-2.3dadb90c.png",v="/assets/new-project-3.bd7a7df1.png",A="/assets/after-finished.b35ece7e.png",b="/assets/new-package.fc4668da.png",m="/assets/new-package-2.9c890d4d.png",f="/assets/new-class.388b2e2e.png",y="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVsAAACXCAYAAAC7kviWAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAA8zSURBVHhe7Z3LkxRFHseJMDbYgxf34p68eNAwXIONxV1tmHF4uQwg8hBQdGcwgIlAcGVZBBGXGXksAkoMzsDIuu7jwMxghKFeOPRc/AO8e+BmePLgaQ/ecuuX1VmVXZ1VU/3Kru76fCM+MV2ZWdVTSfRnfpU1Q6349YXvFAAAdBctW0IIId0LsiWEEA9BtoQQ4iHIlhBCPATZEkKIhyBbQgjxkNyy/dWZ/7UFIYSUOU3JdmhoqCWQLSGk7GlKtmvWrGkJZEsIKXuaku0zzzyj+fnnnzXffPNN1Ca89957ut1uE5AtIaTfsmLFCvXtt9/WthojfTImb5qS7erVqzUzMzNaqjt27IjahDNnzuh2u01YXrb31XRlhf7GNZXpoKVXuacm5HuYuFfbNpH2ipruyjeWdv7dfE9CSFZEpr9Y+UuncLP60tKUbFetWqU5ffq0lqrZXq49U7b3p1UlEEyd24K26aTrWkorsgr3qQTyq/dtl8SXef7IlpBexiXVVkQraUq2Tz75pObkyZNaqmbbcOrUKWd7umzDiq6hiOxYWpft9L1AgnUVdjfEt9z5I1tCeh1brq2KVtKUbB977DHNzZs3tVS3b9+uHn/8cfXxxx+rw4cPq6+//lr98MMP0ThDqmx1VTcRKCUtoWwmJirB5XVtXK0SDC+5433vTViX4dpesm+yLUjK/nFiwckxK5HpEuJzHEfGx+J0jE9aNef5m2M0nqOkfgkibHa1EUJajZFsq6KVNCXbRx99VPPjjz9qvvzyS/XEE0+oxcVF9dNPP6nvv/9eHTlyJBpnyJRt5vpsKMxU4d2bsPpM7DGJ8W3tn3Fcc5zgayRBaatUouPfn45fR8l1/tb7RLHa7fc0cbURQlqOd9k+8sgjLdFuZRvJRo+PKzaNJbe4PUWKWftHaRRpOMZqTzuOJc97QTUeL0VIpWkd06TZ83edY+17qRO5q40Q0lKMaOWr/brZNCXbhx9+uCVSZasl1MSaZZqc6tptseXcvy6JfaLvMSlb13HMewdjI8kG42S8s4Jt4vxTzzHM/aByFgnbx3K1EULyxyVXV1ueNCXbhx56qCXSZRukVq3VCSEQi/tuvGw7KjY5hpGZlpLZJ+f+dUnuE0Qf06omM44jgksuH0xMuJYrasl7/qnnGEe/d6LR1UYIWT4i0zSpZvWlpSnZPvjggxq5OebC9CfJlK0kklmNqArMEl8NbamwQgz3nQiqynif6KaSsZlzfzuO9wwi0oplqxvcx0mKMLntSvJYzvNPOce6pYVa5etqI4Q0Ffn8ZMlU+mRM3jQl25UrV7bEsrIlhJABT1OyfeCBB1oC2RJCyp6mZNsOhBBS5uSWLSGEkNaDbAkhxEOQLSGEeAiyJYQQD0G2hBDiIciWEEI8BNkSQoiHIFtCCPGQSLZrn1sHAABdAtkCAHgA2QIAeADZAgB4ANkCAHgA2QIAeADZAgB4ANkCAHgA2QIAeKB0sh164U9qaPx9NfT6JQAYFOQzHXy2XZ/5olA+2SJagMEk+Gy7PvNFoXyyrf3DPP/mLAAMCOZz7frMF4VSy3bT6BYA6HOQbUFBtgCDBbItKMgWYLBAtgUF2QIMFsi2oCBbgMEC2RYUZAswWLQr2/Wb/qiuXL2mNm3e4uw3fPHFF872vCBbAOhr2pHt0Mh69dH161qk09M31HPrNzjHCT2TbWX4mJqpVlV19pijfV6d2zNS114UsmS7cfNxdUvOae54Q5+w/+KiqlYX1fmxUWe/sHHsolpYZgwAdI52ZPu3c5NaoobJqfQ/jOixbOfVnfmqmjkai7X/ZbuoFhYaZRmJGJECFIp2ZGtYWFhwttv0XLbnjk4Fwp1Su4dDuQ6CbG/NBcK9OFbfd3wuqHjndD+yBSgO5ZFtINUjs1V1Z3JfQ7tsS9/S0pLGLDnUiTqoFqVPquPdk/PRWHM8PX5PPK5anVVHArFXjs6qqiX5vOSR7fkx+Tqn3tocSnXj5jF1Xle7pj9sf2vOOrfa0kN8jNH49cW5aFxS4gDQHqWSbdrr7PHBJXlNliJOEVEkbBGpkWrieNIn47or21Et0lvHa7KVddiFi2q/1Z+2X+PreA1YV8eWxAGgfUolW70t8gsqV1d7VP3VydYak7FtV7XRcRI35Zohr2xjwcbitfv1+ECe8bmlydYan9gGgPYpn2yH96lz+mZZUpSmQpX+WnvTsg2PYd67HXLL1iwdHI+lW9evf+sgrFLjZYbEGGQL0HVKJ1vdVqtCowrWutQP+2rtzchWv47XhKP36vIygt6uVa5mnbVOpLIkYCRs/boXsgXwSzdlK793K79/K6I1XPvwo8zfx02jo7IV5CZXvFwQVrv6Mnt+Vs20UNnq7cRSgl6u8CFbXbHaN8pskUpf7dyCMbeobAF6QrcrW/kLs9u3b2vR3rx1S63buMk5bjlalm2/kiVbAOg/ui1bYfPWF9SHH11f9k96s2hZtqbKzMK1X69BtgCDRSdk6wMqWwDoa5BtQUG2AIMFsi0oyBZgsEC2BQXZAgwWyLag2LIFgMEA2RaQofH3o38YABgggs+26zNfFMon2xf+hHABBg35TAefbddnviiUTrYAAL0A2QIAeADZAgB4ANkCAHgA2QIAeADZAgB4ANkCAHgA2QIAeADZAgB4oLSylUdb7H/1VXXw4CF16BAAgBtxhLii1cfhGEor21f271cvv7JfrdvQ3gQCwKCzXm3bvkM7w92fj9LK9uDBg2oE0QJATsQZrva8lFa2cnngagcAcNGuM5AtAEAOkG2L5J64jaNq+NAJNXzmunruwj818lrapM+5DwAMHMi2RfJM3NDeA2r4/Kdq+O//cRP0yRjXvgAwWCDbFllu4rRoLzkEmyQYg3ABBp+eybYyfEzNVOfVuT0jte196tx8VVVnj6nKnil1x+rLS/KY3SRz4jaNZle0SYKxso/zWDXM/CwtLWmq81Nq9/CI13MGgNYpjGyPzFbVncl9DeOaoSiy1Wu0dUL9t1r9+gn11Ja9atW2/WrVzvFEf4Cs4TqOJYQ/fKpq5mh8XtJ2LthGtgD9QSFku3tyXle0rnHNUBjZyg0wS6SrX/+r+u2ucTV0IaPaDfZxHctUtLZo6/uRLYAvjp94W/3js/+mIv2u/YTey3ZyNrokbugLBGKPM5fQdgVsqr6wfSre72jjcTtJpmwTSwi/2bRTPXvqal1bA7KU4DhWeH6z6kjKeSRlK1cI0VJD7QdYcglCxO1qs48LAI0MjaxX75yddIpW2qXftZ/QY9mGH/bkB71RtuFaru4TidbkY/rM/rpCLqRsd6hn375S19ZAlmwzziMpW1e7novElYOrDQCWZ3jdBjV14XKdaGVb2l3jDb2vbI823gyrE0VCJnV9CRElx3aTTNkmlhF+d+AttWrnWGvLCE1WtiJRU61GP3hq1b/riqDddXKAMjKy4Xl1+dp1LVr5KtuucTa9l63IQKosSyh1fUmZ2H1FlW3DDbJ/qdUH/qKeGt2tntq6V63afSDRH5Byg6yZNVtbzOF+9XMhlX/ySsLVBgDLs3HzqK5o5aurP0khZCvbegmgJs46gSTGNfYVbxmh07/6ZapVW4gi1uRvI9jnHIo3njeDzFGymnW1AUBnKYxsBbm5I7LYNXQ0IdR4XMO2ddlclBtkQqf/qMFc9ptzdf9gim96Vedn1UytsrXnKFrvdrS53hcAOkPPZNvv5Jk4LdysCjfo46/HAMpBz2RrqioXrvFFI/fE8R/RAEAAlW2LtDtxAFAukG2LIFsAaAZk2yI8FgcAmoHH4rQID3wEgHzwwMe24FHmAJAHHmUOANBHIFsAAA8gWwAADyBbAAAPIFsAAA8gWwAADyBbAAAPIFsAAA8gWwAADyBbAAAPIFsAAA8gWwAADyBbAAAPIFsAAA8gW+hrhtZtUBvGz6gtb15V245/CAEyFzInMjeuOctieGSd2rVnr3ptfFyNHTgAATIXMicyN645ywuyhb5mYyCV0TevqbVjF9QfXplSv3+53MgcyFzInMjcuOYsCy3asXG146W9atuOXRAgcyFzInPjmrO8IFvoa7b8+apaO37BKZ4yI3Oi58YxZ1m8NjamdgZScUmnzMicyNy45iwvyBb6GrlspqJtROZE5sY1Z1nIZbNLNrBLz41rzvKCbKGvEaG4ZAPIttMgWyg1yDYdZNtZkC2UGmSbDrLtLMgWSg2yTQfZdhZkC6WmV7LdfvUrtbS0FHHn6pWo7+l9M+pGtaqq1QV1eN+kbjv8aVWPq37+mdpea+s2RZDt1hcPq0t3w3PX53/3A3XgxZ3OsZ1m64un1Fz1rrp0sDPvh2yh1PRCtkacN94Npfn0uwuhSD6dCbcTso36PYpW6LVstx78QC0G8zB3MpadtF2ytrsJsgXoIL5l+/Qbn6k7ItKaWA0i4Gr1K3X2jUCudbI1r8M+e59u00vZmorWFq1vkC1AB/EtW7N8YKraZLssJ9iyvVGrgu1lBl/0VLa6qr2tTmQsGZz4xFpe+OSUbosEefl21Ld4+XC0T3JZwsjcVNH6WLX3RbYAHaQosjVLBbZsjRDstVuf9Fy2OddnbSmGr4MfVEa+J29b8gxFa8s3ub/ZR8YgW4AOUrTKVtrtyvZsrd33eq1Q9MpWpBj/QLJla4nTFnHKMe2qNjpeIGtkC9BBfMs2eTPMkL5me0Wd/TwUge+lhJ7Kdpk1W1uc4dh2ZetoR7YAncO3bAVbrLJtLyHo7TrZBvI1N9U83yTrpWwFU7m6fhtBLw/UlhlCWeaQbeYywvLLC+2CbKHU9EK2glk2MNhVa1K20hb9nq3H9dtey1YIRWqtXxvBWje6qndvq7kclW28HR/PdYNMH5NlBIDO0ivZ9gNFkO0ggWyh1CDbdJBtZ0G2UGqQbTrItrMgWyg1IhT+8/BG+M/DOw+yhVLDY3Hc8FiczsJjcaD0bBh/hwc+WsgcmAc+yty45iyLXS/t0Q835IGPMdEDH4O5cc1ZXpAt9DWV4RG1fuw0jzK3kLmQOZG5cc1ZFmuGhtWu3S/xKHML/SjzYE5kblxzlhdkC31NZe2werayBhzI3LjmLAvmM51W5tMG2ULfowWxZq3zA1JKgrloRwzMZ4I259OAbAEAPIBsAQA8gGwBADyAbAEAPIBsAQA8gGwBADyAbAEAPIBsAQA8gGwBADwQyRYAALrJd+r/zHVjD33sbMEAAAAASUVORK5CYII=",w="/assets/run-the-bot.f048bed2.png";const j={},V=e("h1",{id:"intellij-gradle",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#intellij-gradle","aria-hidden":"true"},"#"),n(" IntelliJ + Gradle")],-1),q=n("This tutorial provides a beginner-friendly click by click guide to set up Javacord with Intellij and Gradle. If you are already familiar with IntelliJ and Gradle, you can just see the artifact locations at "),Z=n("Download / Installation"),B=n("."),C=d('\u{1F527} Setup
1. Start IntelliJ
2. Create a new project (File -> New -> Project)
3. Select Gradle
4. Make sure to select an SDK which is 1.8 (or greater)
5. Click Next
6. Enter a group id (e.g. com.github.yourname)
You can choose whatever you want
7. Enter an artifact id (e.g. myfirstbot)
You can choose whatever you want
8. Click Next
9. Check Use auto-import
10. Click Next
11. Click Finish
12. Locate the build.gradle file and open it
12. Add the Javacord dependency. Your build.gradle file should now look like this
plugins {
+ id 'java'
+}
+
+group 'com.github.yourname'
+version '1.0-SNAPSHOT'
+
+sourceCompatibility = 1.8
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ implementation 'org.javacord:javacord:$latest-version'
+}
+ 13. Create a new package in the src/main/java folder
14. Create a new class inside this package
15. You can now start coding!
Example code:
package com.github.yourname;
+
+import org.javacord.api.DiscordApi;
+import org.javacord.api.DiscordApiBuilder;
+
+public class Main {
+
+ public static void main(String[] args) {
+ // Insert your bot's token here
+ String token = "your token";
+
+ DiscordApi api = new DiscordApiBuilder().setToken(token).login().join();
+
+ // Add a listener which answers with "Pong!" if someone writes "!ping"
+ api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ });
+
+ // Print the invite url of your bot
+ System.out.println("You can invite the bot by using the following url: " + api.createBotInvite());
+ }
+
+}
+\u{1F3C3}\u200D\u2640\uFE0F Run the code
You can run your code by clicking on the small green arrow
\u{1F527} Setup
1. Start IntelliJ
2. Create a new project (File -> New -> Project)
3. Select Maven
4. Make sure to select an SDK which is 1.8 (or greater)
5.* Click Next
6. Enter a group id (e.g. com.github.yourname)
7. Enter an artifact id (e.g. myfirstbot)
8. Click Next
9. Click on Finish
10. Your project should now look like this. First click on Enable Auto-Import
11. Now you have to add Javacord as a dependency by editing the pom.xml file. Your file should now look like this:
<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>your.package.name</groupId>
+ <artifactId>myfirstbot</artifactId>
+ <version>1.0-SNAPSHOT</version>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.javacord</groupId>
+ <artifactId>javacord</artifactId>
+ <version>$latest-version</version>
+ <type>pom</type>
+ </dependency>
+ </dependencies>
+
+</project>
+12. Create a new package
13. Create a new class inside this package
14. You can now start coding! Example code:
package com.github.yourname;
+
+import org.javacord.api.DiscordApi;
+import org.javacord.api.DiscordApiBuilder;
+
+public class Main {
+
+ public static void main(String[] args) {
+ // Insert your bot's token here
+ String token = "your token";
+
+ DiscordApi api = new DiscordApiBuilder().setToken(token).login().join();
+
+ // Add a listener which answers with "Pong!" if someone writes "!ping"
+ api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ });
+
+ // Print the invite url of your bot
+ System.out.println("You can invite the bot by using the following url: " + api.createBotInvite());
+ }
+
+}
+\u{1F3C3}\u200D\u2640\uFE0F Run the code
You can run your code by clicking on the small green arrow 
\u{1F6A7} Possible problems
Note: If you get the following error: 
you have to change your language level to 1.8
@FunctionalInterface
+public interface MessageCreateListener {
+ void onMessageCreate(MessageCreateEvent event);
+}
+api.addMessageCreateListener(new MessageCreateListener() {
+ @Override
+ public void onMessageCreate(MessageCreateEvent event) {
+ // Do stuff
+ event.pinMessage();
+ }
+});
+In Java 8, this can be replaced with a lambda expression, which does exactly the same thing, but in a more readable fashion. The method parameter (in this case event) is written in front of the -> arrow, and the method body is written after it.
api.addMessageCreateListener(event -> {
+ // Do stuff
+ event.pinMessage();
+});
+TIP
If the method has more than one parameter, it would look like this:
(param1, param2) -> { ... }
+There's even a shorter version: If you are only executing one statement, you can get rid of the { } brackets as well:
api.addMessageCreateListener(event -> event.pinMessage());
+api.addMessageCreateListener(MessageEvent::pinMessage);
+Listeners
\u{1F468}\u200D\u{1F527} Creating listeners
Creating listeners is extremely easy in Javacord. You can either use Java 8's lambda expressions to register listeners inline or just create a new class for them, if an inline listener would get too messy.
Inline Listeners
api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+});
+In their own class
api.addListener(new MyListener());
+and
public class MyListener implements MessageCreateListener {
+
+ @Override
+ public void onMessageCreate(MessageCreateEvent event) {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ }
+
+}
+Before logging in
Sometimes it might be useful to add listeners before calling the DiscordApiBuilder#login() method.
DiscordApi api = new DiscordApiBuilder()
+ // An inline listener
+ .addMessageCreateListener(event -> {
+ Message message = event.getMessage();
+ if (message.getContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ })
+ .addServerBecomesAvailableListener(event -> {
+ System.out.println("Loaded " + event.getServer().getName());
+ })
+ // A listener in their own class
+ .addListener(new MyListener())
+ // Alternative syntax that can be used for classes that require a DiscordApi parameter in their constructor
+ .addListener(MyListener::new)
+ .setToken("top secret")
+ .setWaitForServersOnStartup(false)
+ .login()
+ .join();
+Note: In most cases, it's enough to add listeners after logging in
Object listeners
Another cool feature is the ability to attach listeners directly to objects. An example where this can be useful is, for example, reacting to reactions. The following code would delete the message if someone adds a \u{1F44E} reaction.
message.addReactionAddListener(event -> {
+ if (event.getEmoji().equalsEmoji("\u{1F44E}")) {
+ event.deleteMessage();
+ }
+}).removeAfter(30, TimeUnit.MINUTES);
+Seems like the bot is very sensitive to criticism.
\u{1F4A3} Removing listeners
There are two ways to remove a listener:
Using the returned ListenerManager
Every time you register a listener, a ListenerManager is returned which can be used to unregister the listener:
ListenerManager<MessageCreateListener> listenerManager = api.addMessageCreateListener(event -> {
+ // Do stuff
+});
+
+listenerManager.remove();
+This manager also has some utility methods. You can, for example, remove a listener after a given time, which can be useful for object listeners:
message.addReactionAddListener(event -> {
+ // Do stuff
+}).removeAfter(30, TimeUnit.MINUTES);
+ Using the removeListener(...) method
You can remove any listener using the removeListener(...) method:
MyListener listener = new MyListener();
+api.addListener(listener);
+// ...
+api.removeListener(listener);
+\u{1F948} Fallback Logger
Javacord's fallback logger is a simple Log4j logger which always logs INFO level and higher. It allows you to enable DEBUG and TRACE logging manually. As log levels are hierarchical, enabling TRACE will also implicitly enable DEBUG, and disabling DEBUG will also implicitly disable TRACE.
// Enable debug logging
+FallbackLoggerConfiguration.setDebug(true);
+
+// Enable trace logging
+FallbackLoggerConfiguration.setTrace(true);
+Changing the log level of the fallback logger only affects newly created loggers. Pre-existing loggers will not have their log level changed. So if you want to configure the fallback logger, you should do this as one of the first actions in your bot code. If you want to change log levels during runtime, you should use a proper logging framework like Log4j 2 Core or another library that supports this.
All fallback logger messages are printed to the standard output stream (System.out) and thus usually to your console. If you want to log to a file, database, or anything else, you should consider using a proper logging framework which allows you to configure this behavior.
This is how a log line from the fallback logger will look like:
<time with date ><level><logger name, usually the logging class > <message > <the thread context, here the shard number>
+2018-08-03 20:00:06.080+0200 DEBUG org.javacord.core.util.gateway.DiscordWebSocketAdapter Received HELLO packet {shard=0}
+\u{1F947} Using a Proper Logging Framework
Adding a Logging Framework
Adding a logging framework of your choice is very straightforward. You can just add it as a dependency, and it will be detected by Log4j automatically. The following example adds Log4j 2 using Gradle:
dependencies { runtimeOnly 'org.apache.logging.log4j:log4j-core:2.17.0' }
+You can also use an SLF4J compatible logging framework using log4j-to-slf4j. The following example adds Logback Classic using Gradle:
dependencies {
+ runtimeOnly 'org.apache.logging.log4j:log4j-to-slf4j:2.17.0'
+ runtimeOnly 'ch.qos.logback:logback-classic:1.2.3'
+}
+Configure Your Logging Framework
`,14),b=a("strong",null,"Log4j 2",-1),v=e(": "),y={href:"https://logging.apache.org/log4j/2.x/manual/configuration.html",target:"_blank",rel:"noopener noreferrer"},_=e("Log4j configuration"),w=a("strong",null,"Logback Classic",-1),L=e(": "),x={href:"https://logback.qos.ch/manual/configuration.html",target:"_blank",rel:"noopener noreferrer"},j=e("Logback configuration"),C=a("h3",{id:"logging-the-relevant-shard",tabindex:"-1"},[a("a",{class:"header-anchor",href:"#logging-the-relevant-shard","aria-hidden":"true"},"#"),e(" Logging the Relevant Shard")],-1),E=a("p",null,[e("Javacord adds the relevant shard to each log message. The facility that stores this information has a different name depending on which logging framework you use. For Log4j 2, this is called Thread Context Map and can be added in a pattern layout with "),a("code",null,"%X{shard}"),e(", or you can add the whole thread context map by using "),a("code",null,"%X"),e(". For Logback Classic, it is called MDC and can be added with the same pattern expressions as for Log4j.")],-1);function F(T,A){const n=l("ExternalLinkIcon");return t(),r("div",null,[g,a("p",null,[d,a("a",p,[u,o(n)]),h,m,k]),f,a("ul",null,[a("li",null,[b,v,a("a",y,[_,o(n)])]),a("li",null,[w,L,a("a",x,[j,o(n)])])]),C,E])}var B=s(c,[["render",F],["__file","logger-config.html.vue"]]);export{B as default}; diff --git a/assets/message-builder.html.02c7cb1d.js b/assets/message-builder.html.02c7cb1d.js new file mode 100644 index 0000000..51402f7 --- /dev/null +++ b/assets/message-builder.html.02c7cb1d.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-29bd20c3","path":"/wiki/basic-tutorials/message-builder.html","title":"Using the MessageBuilder","lang":"en-US","frontmatter":{"keywords":["create messages","message creation","sendMessage"]},"excerpt":"","headers":[{"level":2,"title":"\u{1F575}\uFE0F\u200D\u2640\uFE0F Example","slug":"example","children":[]},{"level":2,"title":"\u{1F4CD} Allowed Mentions","slug":"allowed-mentions","children":[]}],"git":{"updatedTime":1692105785000,"contributors":[{"name":"Dominic Fellbaum","email":"d.fellbaum@hotmail.de","commits":1}]},"filePathRelative":"wiki/basic-tutorials/message-builder.md"}');export{e as data}; diff --git a/assets/message-builder.html.2ab31ad9.js b/assets/message-builder.html.2ab31ad9.js new file mode 100644 index 0000000..44061a5 --- /dev/null +++ b/assets/message-builder.html.2ab31ad9.js @@ -0,0 +1,27 @@ +import{_ as n,o as s,c as a,e as t}from"./app.151ccb98.js";const e={},p=t(`Using the MessageBuilder
The MessageBuilder class is a more powerful alternative to the TextChannel#sendMessage(...) method.
It can be used to construct more complex messages and supports some additional features that are not possible with a simple TextChannel#sendMessage(...) call.
\u{1F575}\uFE0F\u200D\u2640\uFE0F Example
The following code
new MessageBuilder()
+ .append("Look at these ")
+ .append("awesome", MessageDecoration.BOLD, MessageDecoration.UNDERLINE)
+ .append(" animal pictures! \u{1F603}")
+ .appendCode("java", "System.out.println(\\"Sweet!\\");")
+ .addAttachment(new File("C:/Users/Bastian/Pictures/kitten.jpg"))
+ .addAttachment(new File("C:/Users/Bastian/Pictures/puppy.jpg"))
+ .setEmbed(new EmbedBuilder()
+ .setTitle("WOW")
+ .setDescription("Really cool pictures!")
+ .setColor(Color.ORANGE))
+ .send(channel);
+will be displayed like this:
\u{1F4CD} Allowed Mentions
The allowed mentions object lets you control what should be mentioned (pinged) in a message if it contains mentions.
The following code will ping:
- The user0
- All mentioned roles in the message
And will not ping:
- @everyone and @here
- The user1
AllowedMentions allowedMentions = new AllowedMentionsBuilder()
+ .addUser(user0.getId())
+ .setMentionRoles(true)
+ .setMentionEveryoneAndHere(false)
+ .build();
+
+ new MessageBuilder()
+ .setAllowedMentions(allowedMentions)
+ .append(user0.getMentionTag())
+ .append(user1.getMentionTag())
+ .append(role.getMentionTag())
+ .append(role2.getMentionTag())
+ .append("@everyone")
+ .send(channel);
+If you add a user to the mentions object and set setMentionUsers(true) it will ping every mentioned user. The same applies for setMentionRoles(true)
\u{1F4AA} Motivation
The Optional class is widely used in Javacord. Basically, every method that might return a null value will return an Optional in Javacord instead. Optionals help you to avoid NullPointerExceptions and make it very clear if a method may not have a result. Here's a small example:
The old way of doing it
User user = api.getCachedUserById(123L);
+if (user != null) {
+ user.sendMessage("Hi!");
+}
+The new way of doing it
api.getCachedUserById(123L).ifPresent(user ->
+ user.sendMessage("Hi!")
+);
+You can imagine an Optional like a box \u{1F4E6} that may or may not contain a value. Before accessing this value, you have to "unpack" this box first.
\u{1F4D6} Methods
`,8),b=n("The Optional class has many useful methods which can all be found in the "),y={href:"https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html",target:"_blank",rel:"noopener noreferrer"},_=n("JavaDocs"),x=n(". This tutorial gives a short introduction to the most common ones."),j=e(`get()
The get method returns the value of the Optional or throws a NoSuchElementException if it does not contain a value.
TextChannel channel = api.getTextChannelById(123L).get();
+channel.sendMessage("Hi");
+DANGER
You should never use this method blindly but only if you are 100% sure the optional contains a value.
Every time you use this method carelessly, a kitten dies \u{1F640}! True story.
isPresent()
The isPresent methods checks, if the Optional contains a value.
Optional<TextChannel> channel = api.getTextChannelById(123L);
+if (channel.isPresent()) {
+ // A text channel with the id 123 exists. It's safe to call #get() now
+ channel.get().sendMessage("Hi");
+}
+orElse(...)
The orElse methods returns the value of the Optional if it is present. Otherwise, it returns the given default value.
// The user may not have a nickname on the given server.
+// In this case, we use the user's "regular" name.
+String displayName = user.getNickname(server).orElse(user.getName());
+The example above is (mostly) equivalent to the example below but much more concise.
String displayName = "";
+Optional<String> nickname = user.getNickname(server);
+if (nickname.isPresent()) {
+ displayName = nickname.get();
+} else {
+ displayName = user.getName();
+}
+TIP
In this case you can just use user.getDisplayName(server) instead.
ifPresent(...)
`,14),w=n("The "),O=s("code",null,"ifPresent",-1),q=n(" method is very similar to an "),T=s("code",null,"if (value != null) { ... }",-1),N=n(" check. It takes a "),U={href:"https://docs.oracle.com/javase/8/docs/api/java/util/function/Consumer.html",target:"_blank",rel:"noopener noreferrer"},I=n("Consumer"),B=n(" as it's argument. This consumer is called if the Optional contains a value. Together with lambda expressions this can be a very handy method."),C=e(`api.getTextChannelById(123L).ifPresent(channel -> {
+ channel.sendMessage("Hi!");
+});
+The example above is (mostly) equivalent to the example below but more concise.
Optional<TextChannel> channel = api.getTextChannelById(123L);
+if (channel.isPresent()) {
+ channel.get().sendMessage("Hi!");
+}
+filter(...)
The filter method filters the Optional for a given criteria.
Optional<User> botUser = api.getCachedUserById(123L).filter(User::isBot);
+The example above is equivalent to the example below but more concise.
Optional<User> user = api.getCachedUserById(123L);
+Optional<User> botUser;
+if (user.isPresent() && user.get().isBot()) {
+ botUser = user;
+} else {
+ botUser = Optional.empty();
+}
+map(...)
The map method "converts" the type of an Optional. This is useful, if the type of an Optional does not contain the final value you need.
The following example gets the name of the bots current activity (the "Playing xyz" status) or "None" if the bot has no current activity.
String activityName = api.getYourself().getActivity().map(Activity::getName).orElse("None");
+For better understanding, here's the exact same code but with the types as comments:
String activityName = api.getYourself() // User
+ .getActivity() // Optional<Activity>
+ .map(Activity::getName) // Optional<String>
+ .orElse("None"); // String
+flatMap(...)
The flatMap method if very similar to the map methods. It is used to map values that itself are Optionals to prevent Optional nesting (a "box in a box").
String activityName = api.getCachedUserById(123L) // Optional<User>
+ .flatMap(User::getActivity) // Optional<Activity>
+ .map(Activity::getName) // Optional<String>
+ .orElse("None"); // String
+Without flatMap, the code would look like this:
String activityName = api.getCachedUserById(123L) // Optional<User>
+ .map(User::getActivity) // Optional<Optional<Activity>>
+ .filter(Optional::isPresent) // Optional<Optional<Activity>>
+ .map(Optional::get) // Optional<Activity>
+ .map(Activity::getName) // Optional<String>
+ .orElse("None"); // String
+\u{1F4DA} Further Read
`,20),A=n("This tutorial only focuses on the absolute basics. For an in-depth introduction to Optionals, you can take a look at "),E={href:"https://www.oracle.com/technical-resources/articles/java/java8-optional.html",target:"_blank",rel:"noopener noreferrer"},S=n("Oracle's article about optionals"),L=n(".");function P(M,H){const p=o("RouterLink"),t=o("ExternalLinkIcon");return i(),l("div",null,[d,s("div",k,[m,s("p",null,[v,a(p,{to:"/wiki/essential-knowledge/lambdas/"},{default:u(()=>[h]),_:1}),g])]),f,s("p",null,[b,s("a",y,[_,a(t)]),x]),j,s("p",null,[w,O,q,T,N,s("a",U,[I,a(t)]),B]),C,s("p",null,[A,s("a",E,[S,a(t)]),L])])}var V=c(r,[["render",P],["__file","optionals.html.vue"]]);export{V as default}; diff --git a/assets/optionals.html.b4abca2e.js b/assets/optionals.html.b4abca2e.js new file mode 100644 index 0000000..1b9637a --- /dev/null +++ b/assets/optionals.html.b4abca2e.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-56bee89c","path":"/wiki/essential-knowledge/optionals.html","title":"Optionals","lang":"en-US","frontmatter":{"keywords":[null,"ifPresent","isPresent","orElse"]},"excerpt":"","headers":[{"level":2,"title":"\u{1F4AA} Motivation","slug":"motivation","children":[{"level":3,"title":"The old way of doing it","slug":"the-old-way-of-doing-it","children":[]},{"level":3,"title":"The new way of doing it","slug":"the-new-way-of-doing-it","children":[]}]},{"level":2,"title":"\u{1F4D6} Methods","slug":"methods","children":[{"level":3,"title":"get()","slug":"get","children":[]},{"level":3,"title":"isPresent()","slug":"ispresent","children":[]},{"level":3,"title":"orElse(...)","slug":"orelse","children":[]},{"level":3,"title":"ifPresent(...)","slug":"ifpresent","children":[]},{"level":3,"title":"filter(...)","slug":"filter","children":[]},{"level":3,"title":"map(...)","slug":"map","children":[]},{"level":3,"title":"flatMap(...)","slug":"flatmap","children":[]}]},{"level":2,"title":"\u{1F4DA} Further Read","slug":"further-read","children":[]}],"git":{"updatedTime":1692105785000,"contributors":[{"name":"Dominic Fellbaum","email":"d.fellbaum@hotmail.de","commits":1}]},"filePathRelative":"wiki/essential-knowledge/optionals.md"}');export{e as data}; diff --git a/assets/overview.html.53b5f728.js b/assets/overview.html.53b5f728.js new file mode 100644 index 0000000..2d937fd --- /dev/null +++ b/assets/overview.html.53b5f728.js @@ -0,0 +1 @@ +import{_ as c,r as i,o as d,c as l,a as e,b as o,w as s,e as r,d as t}from"./app.151ccb98.js";var h="/assets/lifecycle_command.b2e278fd.png",m="/assets/lifecycle_interaction.38162b05.png";const p={},u=r('Interactions
Interactions are a means of accepting user input through Discord. They have been introduced to provide a more standardized, controlled way for commands than parsing messages. They can even be used with applications that do not provide a bot user.
\u{1F4AC} Message Commands
The "old" way of doing commands was done through parsed text messages, like !ping, !userinfo James or !mute James 100s. While such commands are easy in theory, they come with several problems, such as:
- Conflicts between Bots using the same command format / prefix.
- Bots have to be able to read all messages and find those that are directed at them
- Information about command structure can only be provided in info texts and error messages
\u2709\uFE0F Interaction Types
',7),_=t("Interactions come in a variety of shapes. The most complex and versatile is the "),f=t("command interaction"),b=t(", which allows for commands directed at a particular bot with information and assistance on subcommands and parameters being integrated into the discord client."),g={href:"https://javadoc.io/doc/org.javacord/javacord-api/latest/org/javacord/api/interaction/ContextMenu.html",target:"_blank",rel:"noopener noreferrer"},v=t("Context Menu commands"),y=t(" are available from the context menu in the client either on a message or a server member."),w=t("Message components"),x=t(" come in the flavor of buttons, select menus and other form elements and can be attached directly to a message."),I=r('\u267B\uFE0F Lifecycle
INFO
Creation of interactions is detailed on the pages linked in the previous section.
Unlike chat message commands, interactions and interaction commands need to be registered with Discord. In order for a bot's interactions to be available in a server, the bot must be added to the server with the applications.commands OAUTH scope. The scope is included in links created by DiscordApi#createInviteLink. If your bot is older, it may need to be invited with the new link to add the scope. It is not necessary to remove the bot from the server to do this.
\u{1F4C8} Advantages
While being more complicated to utilize, interactions have many benefits over pure text commands.
',6),k=e("li",null,"Better Validation: Commands can not be sent with parameters of the wrong type or missing required parameters",-1),C=e("li",null,"No conflicts: Interactions are separated by bot and only sent to the proper bot",-1),N=e("li",null,'"Privacy": If no public response is sent by the bot, the exchange is invisible to other chat participants',-1),D=e("li",null,"Integration: Interactions are integrated into the client's user interface",-1),T=t("Conversations: "),L=t("Message components"),A=t(" can be used in replies to interactions, allowing for nested dialogues."),B=e("div",{class:"custom-container warning"},[e("p",{class:"custom-container-title"},"WARNING"),e("p",null,"If a bot replies to a slash command with a public message, the command used, including all parameters, is visible to other users.")],-1),M=e("h2",{id:"applications-vs-bots",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#applications-vs-bots","aria-hidden":"true"},"#"),t(" \u{1F916} Applications vs. Bots")],-1),V=t("Interactions can used by any application, not only bots. While interactions can also be handled through webhooks, Javacord only offers support for dealing with them through the gateway. See the "),W={href:"https://discord.com/developers/docs/interactions/receiving-and-responding",target:"_blank",rel:"noopener noreferrer"},j=t("Discord Documentation"),R=t(" for more information."),q=e("div",{class:"custom-container warning"},[e("p",{class:"custom-container-title"},"WARNING"),e("p",null,"The methods of handling interactions can not be mixed. If you register a webhook for your interaction commands, the bot will no longer receive any interaction events.")],-1),E=e("h2",{id:"see-also",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#see-also","aria-hidden":"true"},"#"),t(" \u{1F50D} See also")],-1),J={href:"https://discord.com/developers/docs/interactions/application-commands",target:"_blank",rel:"noopener noreferrer"},S=t("Application Commands (Discord Documentation)"),z={href:"https://discord.com/developers/docs/interactions/message-components",target:"_blank",rel:"noopener noreferrer"},G=t("Message Components (Discord Documentation)");function O(U,F){const a=i("RouterLink"),n=i("ExternalLinkIcon");return d(),l("div",null,[u,e("p",null,[_,o(a,{to:"/wiki/basic-tutorials/interactions/commands.html"},{default:s(()=>[f]),_:1}),b]),e("p",null,[e("a",g,[v,o(n)]),y]),e("p",null,[o(a,{to:"/wiki/basic-tutorials/interactions/components.html"},{default:s(()=>[w]),_:1}),x]),I,e("ul",null,[k,C,N,D,e("li",null,[T,o(a,{to:"/wiki/basic-tutorials/interactions/components.html"},{default:s(()=>[L]),_:1}),A])]),B,M,e("p",null,[V,e("a",W,[j,o(n)]),R]),q,E,e("ul",null,[e("li",null,[e("a",J,[S,o(n)])]),e("li",null,[e("a",z,[G,o(n)])])])])}var P=c(p,[["render",O],["__file","overview.html.vue"]]);export{P as default}; diff --git a/assets/overview.html.d664223d.js b/assets/overview.html.d664223d.js new file mode 100644 index 0000000..9e7fc05 --- /dev/null +++ b/assets/overview.html.d664223d.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-16fe8d71","path":"/wiki/basic-tutorials/interactions/overview.html","title":"Interactions","lang":"en-US","frontmatter":{"keywords":["interaction","slash command","command","context menu","autocomplete"]},"excerpt":"","headers":[{"level":2,"title":"\u{1F4AC} Message Commands","slug":"message-commands","children":[]},{"level":2,"title":"\u2709\uFE0F Interaction Types","slug":"interaction-types","children":[]},{"level":2,"title":"\u267B\uFE0F Lifecycle","slug":"lifecycle","children":[]},{"level":2,"title":"\u{1F4C8} Advantages","slug":"advantages","children":[]},{"level":2,"title":"\u{1F916} Applications vs. Bots","slug":"applications-vs-bots","children":[]},{"level":2,"title":"\u{1F50D} See also","slug":"see-also","children":[]}],"git":{"updatedTime":1692105785000,"contributors":[{"name":"Dominic Fellbaum","email":"d.fellbaum@hotmail.de","commits":1}]},"filePathRelative":"wiki/basic-tutorials/interactions/overview.md"}');export{e as data}; diff --git a/assets/performance-tweaks.html.1ed90e55.js b/assets/performance-tweaks.html.1ed90e55.js new file mode 100644 index 0000000..1ffb8ea --- /dev/null +++ b/assets/performance-tweaks.html.1ed90e55.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-2037d84f","path":"/wiki/advanced-topics/performance-tweaks.html","title":"Performance Tweaks","lang":"en-US","frontmatter":{"keywords":["performance","tweaks","startup wait","message cache","tuning"]},"excerpt":"","headers":[{"level":2,"title":"\u2702\uFE0F Disabling Startup Wait","slug":"disabling-startup-wait","children":[]},{"level":2,"title":"\u2699\uFE0F Fine Tuning the Message Cache","slug":"fine-tuning-the-message-cache","children":[]},{"level":2,"title":"\u{1F48E} Using the Updater classes","slug":"using-the-updater-classes","children":[{"level":3,"title":"Example","slug":"example","children":[]}]}],"git":{"updatedTime":1692105785000,"contributors":[{"name":"Dominic Fellbaum","email":"d.fellbaum@hotmail.de","commits":1}]},"filePathRelative":"wiki/advanced-topics/performance-tweaks.md"}');export{e as data}; diff --git a/assets/performance-tweaks.html.909e9a4b.js b/assets/performance-tweaks.html.909e9a4b.js new file mode 100644 index 0000000..254dd35 --- /dev/null +++ b/assets/performance-tweaks.html.909e9a4b.js @@ -0,0 +1,25 @@ +import{_ as n,o as a,c as s,e}from"./app.151ccb98.js";const t={},p=e(`Performance Tweaks
\u2702\uFE0F Disabling Startup Wait
By default, Javacord waits for all servers and members to be loaded on startup. You can disable this behavior in the DiscordApiBuilder before logging in:
new DiscordApiBuilder()
+ .setToken("abc")
+ .setWaitForServersOnStartup(false)
+ .login()
+ .thenAccept(api -> {
+ // Do something
+ }).exceptionally(ExceptionLogger.get());
+Depending on the size of your bot, this can significantly speed up the login process. This comes with one downside however: The api.getServers() collection is empty directly after logging in. You will receive ServerBecomesAvailableEvents for every server which finished loading.
\u2699\uFE0F Fine Tuning the Message Cache
In order to reduce memory usage, you can completely disable the message cache or reduce the number of cached messages. By default, Javacord caches up to 50 messages per channel and removes messages from the cache which are older than 12 hours. You can lower this limit by using DiscordApi#setMessageCacheSize(Capacity, StorageTimeInSeconds).
// Cache a maximum of 10 messages per channel for and remove messages older than 1 hour
+api.setMessageCacheSize(10, 60*60);
+You can even set this limit on a per-channel basis:
TextChannel channel = ...;
+channel.getMessageCache().setCapacity(10);
+channel.getMessageCache().setStorageTimeInSeconds(60*60);
+\u{1F48E} Using the Updater classes
If you update several settings of an entity (server, channel, ...) at once, you should use the updater for this entity instead of the updateXyz(...) methods.
Example
// Sends 1 request to Discord
+ServerTextChannel channel = ...;
+new ServerTextChannelUpdater(channel)
+ .setName("example-channel")
+ .setTopic("This is an example channel")
+ .setNsfwFlag(true)
+ .update();
+instead of
// Sends 3 requests to Discord
+ServerTextChannel channel = ...;
+channel.updateName("example-channel");
+channel.updateTopic("This is an example channel");
+channel.updateNsfwFlag(true);
+Example
The following example will connect the bot to the voice channel of the user that typed !music in the chat:
ServerVoiceChannel channel = ...;
+channel.connect().thenAccept(audioConnection -> {
+ // Do stuff
+}).exceptionally(e -> {
+ // Failed to connect to voice channel (no permissions?)
+ e.printStackTrace();
+ return null;
+});
+\u{1F442} Playing music
`,4),O=n("There are plenty of sources for audio (e.g., YouTube, local files, etc.). The current de facto standard library for extracting audio from these sources with Java is the "),V={href:"https://github.com/lavalink-devs/lavaplayer",target:"_blank",rel:"noopener noreferrer"},J=n("LavaPlayer"),E=n(" library."),I=o(`To use it with Javacord, you have to add it as a dependency to your project (e.g., with Gradle or Maven) and create a Javacord audio source like this:
public class LavaplayerAudioSource extends AudioSourceBase {
+
+ private final AudioPlayer audioPlayer;
+ private AudioFrame lastFrame;
+
+ /**
+ * Creates a new lavaplayer audio source.
+ *
+ * @param api A discord api instance.
+ * @param audioPlayer An audio player from Lavaplayer.
+ */
+ public LavaplayerAudioSource(DiscordApi api, AudioPlayer audioPlayer) {
+ super(api);
+ this.audioPlayer = audioPlayer;
+ }
+
+ @Override
+ public byte[] getNextFrame() {
+ if (lastFrame == null) {
+ return null;
+ }
+ return applyTransformers(lastFrame.getData());
+ }
+
+ @Override
+ public boolean hasFinished() {
+ return false;
+ }
+
+ @Override
+ public boolean hasNextFrame() {
+ lastFrame = audioPlayer.provide();
+ return lastFrame != null;
+ }
+
+ @Override
+ public AudioSource copy() {
+ return new LavaplayerAudioSource(getApi(), audioPlayer);
+ }
+}
+With this audio source, you can now start using Lavaplayer, e.g. to play a YouTube video:
// Create a player manager
+AudioPlayerManager playerManager = new DefaultAudioPlayerManager();
+playerManager.registerSourceManager(new YoutubeAudioSourceManager());
+AudioPlayer player = playerManager.createPlayer();
+
+// Create an audio source and add it to the audio connection's queue
+AudioSource source = new LavaplayerAudioSource(api, player);
+audioConnection.setAudioSource(source);
+
+// You can now use the AudioPlayer like you would normally do with Lavaplayer, e.g.,
+playerManager.loadItem("https://www.youtube.com/watch?v=NvS351QKFV4", new AudioLoadResultHandler() {
+ @Override
+ public void trackLoaded(AudioTrack track) {
+ player.playTrack(track);
+ }
+
+ @Override
+ public void playlistLoaded(AudioPlaylist playlist) {
+ for (AudioTrack track : playlist.getTracks()) {
+ player.playTrack(track);
+ }
+ }
+
+ @Override
+ public void noMatches() {
+ // Notify the user that we've got nothing
+ }
+
+ @Override
+ public void loadFailed(FriendlyException throwable) {
+ // Notify the user that everything exploded
+ }
+});
+Proxies
There are basically two kinds of proxies: HTTP proxies and SOCKS proxies. Both may or may not support or require authentication depending on version, capabilities, and configuration. Due to the underlying libraries used, currently, Javacord fully supports HTTP proxies and partially supports SOCKS proxies.
Javacord uses HTTPS connections to communicate with the Discord REST API and a WSS connection to communicate with the Discord WebSocket endpoint. Both these protocols are secure protocols and thus do not honor settings for HTTP connections, only settings for HTTPS connections.
\u{1F468}\u200D\u{1F4BB} Configuring a Proxy ...
... using System Properties
If you did not explicitly set a proxy in the DiscordApiBuilder and did not set a system default ProxySelector, the default proxy selector of the JRE is used. This proxy selector honors, amongst others, the relevant standard system properties https.proxyHost, https.proxyPort, socksProxyHost, socksProxyPort, and socksProxyVersion. Use the former two to configure an HTTP proxy, or the latter three to configure a SOCKS proxy, although you will not need socksProxyVersion, as SOCKS4 is currently not supported.
... using a System Default Proxy Selector
You can use java.net.ProxySelector.setDefault(ProxySelector) to set a system default proxy selector that replaces the default one. In its implementation, you can dynamically determine which proxy to use for each connection.
... using an Explicitly Set Proxy
Using the method DiscordApiBuilder.setProxy(Proxy) you can set a proxy instance directly in the DiscordApiBuilder that is solely used for Javacord connections and does not affect the unrelated code running in the JVM.
... using an Explicitly Set Proxy Selector
Using the method DiscordApiBuilder.setProxySelector(ProxySelector) you can set a proxy selector instance directly in the DiscordApiBuilder that is solely used for Javacord connections and does not affect the remaining code running in the JVM. In its implementation, you can dynamically determine which proxy to use for each connection.
Precedence of the Configuration Options
- if an explicit proxy is set, it is used
- if an explicit proxy selector is set, it is used
- if both an explicit proxy and an explicit proxy selector are set, this is a configuration error and will cause an exception to be thrown
- if neither explicit option is set, the system default proxy selector is used
- if no system default proxy selector was explicitly set, the JRE default that honors the system properties is used
\u{1F511} Configuring Proxy Authentication ...
... using a System Default Authenticator
You can use java.net.Authenticator.setDefault(Authenticator) to set a system default authenticator that is used to provide username and password pairs for connections. This authenticator is only used if the proxy supports the Basic authentication scheme. If you need to support any other authentication scheme, use an explicitly configured authenticator. The java.net.Authenticator interface is too inflexible to support this.
... using an Explicitly Set Authenticator
Using the method DiscordApiBuilder.setProxyAuthenticator(Authenticator), you can set a custom authenticator that is much more powerful than the java.net.Authenticator. You get much more information about the connection to be established, and you can return any HTTP header that is necessary for a successful authentication. This should cover all sorts of available authentication mechanisms.
\u{1F4A1} Proxy Types
HTTP
HTTP proxies are fully supported.
SOCKS 4
SOCKS 4 is currently not supported.
The WebSocket library we use does not support SOCKS proxies at all, and the HTTP library we use has a bug that prevents SOCKS 4 to be used. Additionally, you would need to use at least Java 9 or a separate socket factory supporting SOCKS 4, as the JRE implementation is not working in Java 8 and got fixed only in Java 9+.
SOCKS 4a
SOCKS 4a is currently only partially supported.
The WebSocket library we use does not support SOCKS proxies at all, so it could be used for the REST connections only. Additionally, you would need to use a separate socket factory supporting SOCKS 4a, as the JRE implementation is not capable of doing SOCKS 4a, only SOCKS 4 and SOCKS 5 are supported at the time of creation of this wiki article.
SOCKS 5
SOCKS 5 is currently only partially supported.
The WebSocket library we use does not support SOCKS proxies at all, so it could be used for the REST connections only.
',31),s=[r];function n(c,d){return t(),o("div",null,s)}var l=e(i,[["render",n],["__file","proxies.html.vue"]]);export{l as default}; diff --git a/assets/ratelimits.html.4f60547f.js b/assets/ratelimits.html.4f60547f.js new file mode 100644 index 0000000..1438762 --- /dev/null +++ b/assets/ratelimits.html.4f60547f.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-fc3b23ca","path":"/wiki/advanced-topics/ratelimits.html","title":"Ratelimits","lang":"en-US","frontmatter":{"keywords":["ratelimits"]},"excerpt":"","headers":[{"level":2,"title":"\u2757 The Most Important Ratelimits","slug":"the-most-important-ratelimits","children":[]},{"level":2,"title":"\u{1F4AA} Dealing with Ratelimits","slug":"dealing-with-ratelimits","children":[{"level":3,"title":"Example","slug":"example","children":[]}]},{"level":2,"title":"\u274C Can I disable ratelimits?","slug":"can-i-disable-ratelimits","children":[]}],"git":{"updatedTime":1692105785000,"contributors":[{"name":"Dominic Fellbaum","email":"d.fellbaum@hotmail.de","commits":1}]},"filePathRelative":"wiki/advanced-topics/ratelimits.md"}');export{e as data}; diff --git a/assets/ratelimits.html.a990bfd1.js b/assets/ratelimits.html.a990bfd1.js new file mode 100644 index 0000000..ba83d7c --- /dev/null +++ b/assets/ratelimits.html.a990bfd1.js @@ -0,0 +1,14 @@ +import{_ as n,o as a,c as s,e as t}from"./app.151ccb98.js";const e={},i=t(`Ratelimits
Ratelimits is a Discord restriction which prevents you from performing actions in a very fast rate. Most ratelimits are on a per-channel or a per-server basis.
\u2757 The Most Important Ratelimits
| Action | Ratelimit | Type |
|---|---|---|
| Send Messages | 5 / 5s | per channel |
| Delete Messages | 5 / 1s | per channel |
| Add/Remove Reactions | 1 / 0.25s | per channel |
| Edit Server Members | 10 / 10s | per server |
| Edit Member Nickname | 1 / 1s | per server |
| Edit Bot Username | 2 / 1h | per account |
| Update Channels | 2 / 10m | per account |
| All Actions Combined | 50 / 1s | per account |
\u{1F4AA} Dealing with Ratelimits
Usually Javacord takes care about these limitations for you. As a user, there's nothing you have to do, but you should at least know that ratelimits exist.
Example
The following code
// Who even needs loops?
+channel.sendMessage("Ratelimit Example #1");
+channel.sendMessage("Ratelimit Example #2");
+channel.sendMessage("Ratelimit Example #3");
+channel.sendMessage("Ratelimit Example #4");
+channel.sendMessage("Ratelimit Example #5");
+channel.sendMessage("Ratelimit Example #6");
+channel.sendMessage("Ratelimit Example #7");
+channel.sendMessage("Ratelimit Example #8");
+channel.sendMessage("Ratelimit Example #9");
+channel.sendMessage("Ratelimit Example #10");
+channel.sendMessage("Ratelimit Example #11");
+channel.sendMessage("Ratelimit Example #12");
+would look like this in the client:
You can clearly see the delay between every 5 sent messages.
\u274C Can I disable ratelimits?
No. Ratelimits are a limitation from Discord itself, which you cannot circumvent.
`,14),p=[i];function o(c,l){return a(),s("div",null,p)}var d=n(e,[["render",o],["__file","ratelimits.html.vue"]]);export{d as default}; diff --git a/assets/respond_with_modal.9601f2a7.png b/assets/respond_with_modal.9601f2a7.png new file mode 100644 index 0000000..e1ce916 Binary files /dev/null and b/assets/respond_with_modal.9601f2a7.png differ diff --git a/assets/responding.html.3c5c7e21.js b/assets/responding.html.3c5c7e21.js new file mode 100644 index 0000000..c7aa19f --- /dev/null +++ b/assets/responding.html.3c5c7e21.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-00728006","path":"/wiki/basic-tutorials/interactions/responding.html","title":"Responding to interactions","lang":"en-US","frontmatter":{"keywords":["interaction responding","modal","autocomplete"]},"excerpt":"","headers":[{"level":2,"title":"\u{1F4AC} Responding immediately after receiving an interaction.","slug":"responding-immediately-after-receiving-an-interaction","children":[]},{"level":2,"title":"\u{1F4AC} Responding after some time when receiving an interaction.","slug":"responding-after-some-time-when-receiving-an-interaction","children":[{"level":3,"title":"Sending followup messages","slug":"sending-followup-messages","children":[]}]},{"level":2,"title":"Responding with a Modal","slug":"responding-with-a-modal","children":[]},{"level":2,"title":"\u{1F4AC} SlashCommand interaction only response methods","slug":"slashcommand-interaction-only-response-methods","children":[{"level":3,"title":"How to know what slash command was invoked?","slug":"how-to-know-what-slash-command-was-invoked","children":[]},{"level":3,"title":"Respond to an AutoComplete interaction triggered from a SlashCommand","slug":"respond-to-an-autocomplete-interaction-triggered-from-a-slashcommand","children":[]}]},{"level":2,"title":"\u{1F4AC} Message Component interaction only response methods","slug":"message-component-interaction-only-response-methods","children":[{"level":3,"title":"A more complete example of how to respond to Component interactions","slug":"a-more-complete-example-of-how-to-respond-to-component-interactions","children":[]}]}],"git":{"updatedTime":1692105785000,"contributors":[{"name":"Dominic Fellbaum","email":"d.fellbaum@hotmail.de","commits":1}]},"filePathRelative":"wiki/basic-tutorials/interactions/responding.md"}');export{e as data}; diff --git a/assets/responding.html.a1a19125.js b/assets/responding.html.a1a19125.js new file mode 100644 index 0000000..482f52d --- /dev/null +++ b/assets/responding.html.a1a19125.js @@ -0,0 +1,77 @@ +import{_ as t,r as e,o,c as p,a as c,b as i,w as u,e as s,d as n}from"./app.151ccb98.js";var l="/assets/respond_with_modal.9601f2a7.png";const r={},d=s(`Responding to interactions
There are many ways to respond to interactions and some are only available for certain interactions. The following will be usable for every interaction.
\u{1F4AC} Responding immediately after receiving an interaction.
event.getInteraction()
+ .createImmediateResponder()
+ .setContent("YOUR_RESPONSE")
+ .respond();
+INFO
Note that you have to respond withing 3 seconds, or the command will fail. If you need longer than 3 seconds you have to respond with respondLater() which allows you to respond within 15 minutes.
Because of this time limitation, sending any files when creating an immediate response is not possible. If you want a file to be embedded either use respondLater or include a web link in the message content. Depending on the media type of the link and the server configuration, Discord will then display an appropriate embed for the file.
When you want to respond ephemerally, you can use the setFlags method. Your new responder would look like the following:
event.getInteraction()
+ .createImmediateResponder()
+ .setContent("YOUR_RESPONSE")
+ .setFlags(MessageFlag.EPHEMERAL)
+ .respond();
+\u{1F4AC} Responding after some time when receiving an interaction.
If your computations takes longer than the 3 seconds limit, you can respond later and the Discord Client will show that your bot is thinking until you respond.
event.getInteraction()
+ .respondLater()
+ .thenAccept(interactionOriginalResponseUpdater -> {
+ interactionOriginalResponseUpdater.setContent("Update message after some time").update();
+ });
+You can respond ephemerally when responding later too. For that you have pass a true boolean to the respondLater method.
event.getInteraction()
+ .respondLater(true)
+ .thenAccept(interactionOriginalResponseUpdater -> {
+ interactionOriginalResponseUpdater.setContent("Update message after some time").update();
+ });
+Sending followup messages
Followup messages can be sent within 15 minutes after the command has been invoked. You can send as many followup messages as you want.
api.addSlashCommandCreateListener(event -> {
+ SlashCommandInteraction slashCommandInteraction = event.getSlashCommandInteraction();
+ slashCommandInteraction.respondLater().thenAccept(interactionOriginalResponseUpdater -> {
+ interactionOriginalResponseUpdater.setContent("You will receive the answer in a few minutes!").update();
+
+ // time < 15 minutes
+
+ slashCommandInteraction.createFollowupMessageBuilder()
+ .setContent("Thank you for your patience, it took a while but the answer to the universe is 42")
+ .send();
+ });
+});
+Responding with a Modal
A modal is a popup dialog which can be shown when responding to an interaction. It focuses the users to explicitly fill out this form to continue with the workflow. Currently, only the TextInput (SelectMenu has been seen working too, but is not yet officially supported) is supported.
api.addMessageComponentCreateListener(event -> {
+ event.getInteraction().respondWithModal("modalId","Modal Title",
+ ActionRow.of(TextInput.create(TextInputStyle.SHORT, "text_input_id", "This is a Text Input Field")));
+});
+Which results in
\u{1F4AC} SlashCommand interaction only response methods
How to know what slash command was invoked?
For example, you have created a slash command with the name "settings" and a subcommand "color". If you want to check if exactly this command has been used, you can check it as follows:
api.addSlashCommandCreateListener(event -> {
+ SlashCommandInteraction interaction = event.getSlashCommandInteraction();
+ if (interaction.getFullCommandName().equals("settings color")) {
+ //Code if command matches the full name
+ }
+});
+Respond to an AutoComplete interaction triggered from a SlashCommand
api.addAutocompleteCreateListener(event -> {
+ event.getAutocompleteInteraction()
+ .respondWithChoices(Arrays.asList(
+ SlashCommandOptionChoice.create("one", 1),
+ SlashCommandOptionChoice.create("two", 2))
+ );
+});
+\u{1F4AC} Message Component interaction only response methods
When dealing with message components, you don't necessarily have to respond or update a message. You can simply acknowledge the interaction and let the user know that the task is done.
api.addMessageComponentCreateListener(event -> {
+ event.getMessageComponentInteraction().acknowledge();
+});
+A more complete example of how to respond to Component interactions
`,30),k=n("The following code snipped shows how you can respond to the example created in "),m=n("Components"),v=n("."),h=s(`api.addMessageComponentCreateListener(event -> {
+ MessageComponentInteraction messageComponentInteraction = event.getMessageComponentInteraction();
+ String customId = messageComponentInteraction.getCustomId();
+
+ switch (customId) {
+ case "success":
+ messageComponentInteraction.createImmediateResponder()
+ .setContent("You clicked a button!")
+ .respond();
+ break;
+ case "danger":
+ messageComponentInteraction.getMessage().ifPresent(Message::delete);
+ break;
+ case "secondary":
+ messageComponentInteraction.respondLater().thenAccept(interactionOriginalResponseUpdater -> {
+ //Code to respond after 5 minutes
+ });
+ break;
+ case "options":
+ messageComponentInteraction.createImmediateResponder()
+ .setContent("You selected an option in a select menu!")
+ .respond();
+ break;
+ }
+});
+Running and Deploying your Bot
If you took the time to write a bot, at some point you'll also want to run it, either for use in production or for debugging from the IDE.
\u{1F477} Running from your IDE
While developing your bot, you will want to run your bot directly from the IDE in order to quickly test changes and new features. For this, create a Run/Debug Configuration in your IDE of choice with your bot's main class. Remember to also add any necessary parameters and environment variables.
A working Run/Debug configuration will also enable you to run your bot with a debugger. A debugger is often considered a developer's most important tool, so make sure to familiarize yourself with the debugging integration for your IDE of choice.
IntelliJ IDEA
This assumes your project is set up correctly, preferably with Gradle, can be built without errors, and does not yet have any run/debug configurations.
1. Locate and click the Add Configuration... button in the top bar next to the start button.
2. In the newly opened window, click the + button in the top left and select Application
3. Give a name for your configuration and select the module to use the classpath of (usually yourproject.main).
4. Select your Main class. Use the ... button to search for it or provide the fully qualified name. If it can not be found, you most likely selected the wrong module in step 3.
5. Optional: Set command line arguments and environment variables. For the environment variables, use the button to the right of the input field for a more convenient input window.
6. Click Apply to finalize the configuration, then OK to close the window.
7. Select your configuration in the drop-down menu and run or debug it with the buttons to the right.
Eclipse
This assumes your project is set up correctly, can be built without errors, and does not yet have any run/debug configurations.
1. In the menu bar, click "Run" then "Run Configurations...".
2. In the newly opened window, select "Java Application" on the left side, then click the leftmost button in the row above the tree view. A new configuration will appear.
3. Give a name to your configuration.
4. Set the project and the main class. To easily select it, use the "Browse..." and "Search..." buttons.
5. Optional: Set command line (and VM) arguments as well as environment variables in their respective tabs.
6. Click Apply to save your configuration, then Close to close the window.
7. Run or debug your bot via the Buttons in the top row, the Run menu, or the shortcuts Ctrl+F11 for running and F11 for debugging.
\u{1F4E6} Deploying and Running as a Standalone Application
Running from the IDE is only recommended during development and strongly discouraged for production use. Generally, you'll want your build tool to create a convenient distribution format for you to use.
Building a Distribution with Gradle
',32),w=s("For Gradle, only two further steps are necessary for a basic application. On top of the steps described in the "),x=n("a",{href:"/wiki/getting-started/intellij-gradle"},"Getting Started Section",-1),C=s(", also add the "),I={href:"https://docs.gradle.org/current/userguide/application_plugin.html",target:"_blank",rel:"noopener noreferrer"},j=s("Application Plugin"),_=s(" and define your "),S=n("code",null,"mainClass",-1),M=s(" as the fully qualified name of your main class. If you're using an older version of Gradle (earlier than 6.4), the attribute is instead called "),T=n("code",null,"mainClassName",-1),P=s("."),G=n("div",{class:"custom-container tip"},[n("p",{class:"custom-container-title"},"INFO"),n("p",null,[s("As with many Gradle solutions, there is actually a whole lot going on under the hood. The "),n("code",null,"application"),s(" plugin implicitly also applies the "),n("code",null,"java"),s(" and "),n("code",null,"distribution"),s(" plugins. Refer to the documentations of the involved plugins for more ways to fine-tune the process.")])],-1),q=n("p",null,"Your modified build file should now look similar to this:",-1),L=n("div",{class:"language-kts ext-kts line-numbers-mode"},[n("pre",{class:"language-kts"},[n("code",null,[s("plugins "),n("span",{class:"token punctuation"},"{"),s(` + application +`),n("span",{class:"token punctuation"},"}"),s(` + +version `),n("span",{class:"token operator"},"="),s(),n("span",{class:"token string-literal singleline"},[n("span",{class:"token string"},'"1.0.0"')]),s(` + +java `),n("span",{class:"token punctuation"},"{"),s(` + sourceCompatibility `),n("span",{class:"token operator"},"="),s(" JavaVersion"),n("span",{class:"token punctuation"},"."),s(`VERSION_1_8 +`),n("span",{class:"token punctuation"},"}"),s(` + +application `),n("span",{class:"token punctuation"},"{"),s(` + mainClass`),n("span",{class:"token punctuation"},"."),n("span",{class:"token function"},"set"),n("span",{class:"token punctuation"},"("),n("span",{class:"token string-literal singleline"},[n("span",{class:"token string"},'"com.github.yourname.BotMain"')]),n("span",{class:"token punctuation"},")"),s(` + `),n("span",{class:"token comment"},'// mainClassName.set("com.github.yourname.BotMain") // Gradle < 6.4'),s(` +`),n("span",{class:"token punctuation"},"}"),s(` + +repositories `),n("span",{class:"token punctuation"},"{"),s(` + `),n("span",{class:"token function"},"mavenCentral"),n("span",{class:"token punctuation"},"("),n("span",{class:"token punctuation"},")"),s(` +`),n("span",{class:"token punctuation"},"}"),s(` + +dependencies `),n("span",{class:"token punctuation"},"{"),s(` + `),n("span",{class:"token function"},"implementation"),n("span",{class:"token punctuation"},"("),n("span",{class:"token string-literal singleline"},[n("span",{class:"token string"},'"org.javacord:javacord:{{latestVersion}}"')]),n("span",{class:"token punctuation"},")"),s(` +`),n("span",{class:"token punctuation"},"}"),s(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),V=n("div",{class:"language-groovy ext-groovy line-numbers-mode"},[n("pre",{class:"language-groovy"},[n("code",null,[s("plugins "),n("span",{class:"token punctuation"},"{"),s(` + id `),n("span",{class:"token string"},"'application'"),s(` +`),n("span",{class:"token punctuation"},"}"),s(` + +version `),n("span",{class:"token string"},"'1.0.0'"),s(` + +java `),n("span",{class:"token punctuation"},"{"),s(` + sourceCompatibility `),n("span",{class:"token operator"},"="),s(" JavaVersion"),n("span",{class:"token punctuation"},"."),s(`VERSION_1_8 +`),n("span",{class:"token punctuation"},"}"),s(` + +application `),n("span",{class:"token punctuation"},"{"),s(` + mainClass `),n("span",{class:"token operator"},"="),s(),n("span",{class:"token string"},"'com.github.yourname.BotMain'"),s(` + `),n("span",{class:"token comment"},"// mainClassName = 'com.github.yourname.BotMain' // for Gradle versions < 6.4"),s(` +`),n("span",{class:"token punctuation"},"}"),s(` + +repositories `),n("span",{class:"token punctuation"},"{"),s(` + `),n("span",{class:"token function"},"mavenCentral"),n("span",{class:"token punctuation"},"("),n("span",{class:"token punctuation"},")"),s(` +`),n("span",{class:"token punctuation"},"}"),s(` + +dependencies `),n("span",{class:"token punctuation"},"{"),s(` + implementation `),n("span",{class:"token string"},"'org.javacord:javacord:{{latestVersion}}'"),s(` +`),n("span",{class:"token punctuation"},"}"),s(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),E=e('Now you can execute the distZip or distTar task with Gradle. The task will create a distribution and package it in an archive file that will be placed in the build/distributions directory. Extract the content of those files on your server or whichever machine you want to run your bot on.
The distribution usually only contains the directories bin and lib. From the distribution directory, run either bin/yourbot or bin/yourbot.bat, depending on whether you're running the bot on Linux / macOS or windows.
Building a Distribution with Maven
',3),Y=s("For Maven, add the "),F={href:"https://www.mojohaus.org/appassembler/appassembler-maven-plugin/usage-program.html",target:"_blank",rel:"noopener noreferrer"},N=s("Appassembler"),J=s(" plugin to your "),K=n("code",null,"pom.xml",-1),R=s(". The plugin will create a distribution, but not bundle it in a neat archive file, so we'll also add the assembly plugin. We'll bind both to the "),B=n("code",null,"package",-1),D=s(" lifecycle phase."),Z=e(`<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>appassembler-maven-plugin</artifactId>
+ <version>1.10</version>
+ <configuration>
+ <programs>
+ <program>
+ <mainClass>org.javacord.examplebot.Main</mainClass>
+ <id>examplebot</id>
+ </program>
+ </programs>
+ </configuration>
+ <executions>
+ <execution>
+ <id>create-distribution</id>
+ <phase>package</phase>
+ <goals>
+ <goal>assemble</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <version>3.3.0</version>
+ <configuration>
+ <descriptors>
+ <!-- This must match the location of the descriptor -->
+ <descriptor>src/assembly/distribution.xml</descriptor>
+ </descriptors>
+ </configuration>
+ <executions>
+ <execution>
+ <id>create-archive</id>
+ <phase>package</phase>
+ <goals>
+ <goal>single</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
+Sadly, none of the built-in assembly descriptors match our use case, so we'll put our custom one into src/assembly/distribution.xml:
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
+ <id>distribution</id>
+ <formats>
+ <!-- See https://maven.apache.org/plugins/maven-assembly-plugin/assembly.html for supported formats -->
+ <format>tar.gz</format>
+ <format>tar.bz2</format>
+ <format>zip</format>
+ </formats>
+ <fileSets>
+ <fileSet>
+ <!-- This will also include your project readme, license and similar files-->
+ <directory>\${project.basedir}</directory>
+ <outputDirectory>/</outputDirectory>
+ <includes>
+ <include>README*</include>
+ <include>LICENSE*</include>
+ <include>NOTICE*</include>
+ </includes>
+ </fileSet>
+ <fileSet>
+ <!-- Change this if you reconfigured the appassembler output directory -->
+ <directory>\${project.build.directory}/appassembler</directory>
+ <outputDirectory>/</outputDirectory>
+ </fileSet>
+ </fileSets>
+</assembly>
+Now when you execute mvn package, a distribution with start scripts for Windows and Linux/macOS will be generated which is then packaged into archive files for every format you specified in the assembly descriptor. You can find the raw distribution (without readme and license files) in target/appassembler and the archive files directly in target.
Running
After creating your distribution via Gradle or Maven and extracting/copying it to the machine you want to run it from, you should have a directory containing both a bin and a lib (or repo) directory. Depending on your platform, you can now run the bin/yourbot or bin/yourbot.bat script.
These automatically generated scripts will then invoke java with your dependencies on the classpath and run your main class. Your working directory will be the directory you ran the script from.
\u{1F4A9} Building a Fat Jar
Although it is an abuse of the way java works, sometimes you will be forced to create a fat jar, or an uber jar. This is a jar file that contains your application and all its dependencies. This is sometimes used as a lazy way of building a convenient distribution, but should be foregone in favor of the above mentioned distributions.
However, in some cases (more often than not Bukkit/Spigot addons) it is necessary to provide a fat jar, since the host application's loading mechanism can only handle singular jar files. If you are subject to such a case of bad design, please complain to the maintainer of whatever host application you are using, then use the following instructions to forsake all that is good and just and create a fat jar. Remember to grit your teeth the whole time.
With Gradle
`,11),z=s("For Gradle, use the "),X={href:"https://github.com/johnrengelman/shadow",target:"_blank",rel:"noopener noreferrer"},H=s("shadow"),Q=s(" plugin. If you want the fat jar to be executable, you will need to specify a main class via the application plugin."),W=e(`plugins {
+ id 'java'
+ # ...
+ id 'com.github.johnrengelman.shadow' version '7.1.2'
+}
+With gradlew shadowJar you can now create a shaded (fat) jar. It will be named build/libs/yourbot-1.0.0-all.jar or similar, according to your project settings.
With Maven
`,3),O=s("For Maven, add the "),U={href:"https://maven.apache.org/plugins/maven-shade-plugin/usage.html",target:"_blank",rel:"noopener noreferrer"},$=s("maven-shade-plugin"),nn=s(" to your build. As with the other solutions, configure your main class."),sn=e(`Some of your dependencies might be signed .jar files. Unfortunately, this will likely break your fat jar. Remove the signatures by defining an exclusion filter as demonstrated below. Let the thought that you had to disable a security feature just to make this work serve as a reminder that creating a fat jar is not how jars are meant to be used.
<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-shade-plugin</artifactId>
+ <version>3.2.3</version>
+ <configuration>
+ <shadedArtifactAttached>true</shadedArtifactAttached>
+ <shadedClassifierName>fat</shadedClassifierName>
+ <transformers>
+ <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+ <manifestEntries>
+ <Main-Class>com.github.yourname.BotMain</Main-Class>
+ </manifestEntries>
+ </transformer>
+ </transformers>
+ <filters>
+ <filter>
+ <artifact>*:*</artifact>
+ <excludes>
+ <exclude>META-INF/*.SF</exclude>
+ <exclude>META-INF/*.DSA</exclude>
+ <exclude>META-INF/*.RSA</exclude>
+ </excludes>
+ </filter>
+ </filters>
+ </configuration>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <goals>
+ <goal>shade</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
+Running mvn package will now additionally create the yourbot-1.0.0-fat.jar.
Sharding
Discord allows (and forces) you to "split" larger bots into several independent parts. This behavior is called "sharding", and the independent parts are called "shards". You can think of shards as completely independent bots. Every shard is responsible for a disjoint set of servers.
\u{1F469}\u200D\u{1F3ED} Sharding in Javacord
Logging in with a single shard
Logging in with a single shard is pretty much the same as logging in without sharding:
DiscordApi api = new DiscordApiBuilder()
+ .setToken("top secret")
+ .setCurrentShard(0)
+ .setTotalShards(2)
+ .login().join();
+System.out.println("Shard " + api.getCurrentShard() + " logged in!");
+Note:
current shardstarts counting at0! This means in the example above you would have current shard0and shard1with atotal amountof2shards.
Important: There must be a > 5-second delay between each shard-login
Logging in with a fixed amount of shards
You can manually set a fixed amount of total shards and log in all of them:
public class Main {
+
+ public static void main(String[] args) {
+ new DiscordApiBuilder()
+ .setToken("top secret")
+ .setTotalShards(10)
+ .loginAllShards()
+ .forEach(shardFuture -> shardFuture
+ .thenAcceptAsync(Main::onShardLogin)
+ .exceptionally(ExceptionLogger.get())
+ );
+ }
+
+ private static void onShardLogin(DiscordApi api) {
+ System.out.println("Shard " + api.getCurrentShard() + " logged in!");
+ // You can treat the shard like a normal bot account, e.g. registering listeners
+ api.addMessageCreateListener(event -> {
+ // ...
+ });
+ }
+
+}
+loginAllShards() returns a collection with completable futures (Collection<CompletableFuture<DiscordApi>>). This method automatically obeys the > 5-second delay rule.
Using the recommended shard amount
You can "ask" Discord to recommend you a total amount of shards. This is done by using the DiscordApiBuilder#setRecommendedTotalShards() method, which returns a CompletableFuture<DiscordApiBuilder> after getting the required information.
public class Main {
+
+ public static void main(String[] args) {
+ new DiscordApiBuilder()
+ .setToken("top secret")
+ .setRecommendedTotalShards().join()
+ .loginAllShards()
+ .forEach(shardFuture -> shardFuture
+ .thenAccept(Main::onShardLogin)
+ .exceptionally(ExceptionLogger.get())
+ );
+ }
+
+ private static void onShardLogin(DiscordApi api) {
+ // ...
+ }
+
+}
+\u{1F4A1} Behavior of Shards
Managed servers
You can calculate for which servers a shard is responsible using the server id:
boolean isResponsible = (serverId >> 22) % totalShards == currentShard;
+Private messages
Private messages are always sent to the first shard (currentShard == 0).
When do I need sharding?
Sharding is forced for bots which are in more than 2500 servers.
\u{1F304} Sharding for Very Large Bots
`,24),r=n('Sharding for very large bots (> 150,000 servers) is a bit different from "normal" sharding. Discord will contact you once your bot reaches this state. Additional information can be found in the '),d={href:"https://discordapp.com/developers/docs/topics/gateway#sharding-for-large-bots",target:"_blank",rel:"noopener noreferrer"},k=n("official Discord api documentation"),h=n(".");function v(m,g){const a=t("ExternalLinkIcon");return o(),p("div",null,[u,s("p",null,[r,s("a",d,[k,c(a)]),h])])}var f=e(l,[["render",v],["__file","sharding.html.vue"]]);export{f as default}; diff --git a/assets/sharding.html.d6f88b19.js b/assets/sharding.html.d6f88b19.js new file mode 100644 index 0000000..bf10a1b --- /dev/null +++ b/assets/sharding.html.d6f88b19.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-595301cf","path":"/wiki/advanced-topics/sharding.html","title":"Sharding","lang":"en-US","frontmatter":{"keywords":["sharding","large"]},"excerpt":"","headers":[{"level":2,"title":"\u{1F469}\u200D\u{1F3ED} Sharding in Javacord","slug":"sharding-in-javacord","children":[{"level":3,"title":"Logging in with a single shard","slug":"logging-in-with-a-single-shard","children":[]},{"level":3,"title":"Logging in with a fixed amount of shards","slug":"logging-in-with-a-fixed-amount-of-shards","children":[]},{"level":3,"title":"Using the recommended shard amount","slug":"using-the-recommended-shard-amount","children":[]}]},{"level":2,"title":"\u{1F4A1} Behavior of Shards","slug":"behavior-of-shards","children":[{"level":3,"title":"Managed servers","slug":"managed-servers","children":[]},{"level":3,"title":"Private messages","slug":"private-messages","children":[]},{"level":3,"title":"When do I need sharding?","slug":"when-do-i-need-sharding","children":[]}]},{"level":2,"title":"\u{1F304} Sharding for Very Large Bots","slug":"sharding-for-very-large-bots","children":[]}],"git":{"updatedTime":1692105785000,"contributors":[{"name":"Dominic Fellbaum","email":"d.fellbaum@hotmail.de","commits":1}]},"filePathRelative":"wiki/advanced-topics/sharding.md"}');export{e as data}; diff --git a/assets/style.18d74fae.css b/assets/style.18d74fae.css new file mode 100644 index 0000000..0aa0c0a --- /dev/null +++ b/assets/style.18d74fae.css @@ -0,0 +1 @@ +:root{--back-to-top-z-index: 5;--back-to-top-color: #3eaf7c;--back-to-top-color-hover: #71cda3}.back-to-top{cursor:pointer;position:fixed;bottom:2rem;right:2.5rem;width:2rem;height:1.2rem;background-color:var(--back-to-top-color);-webkit-mask:url(/assets/back-to-top.8efcbe56.svg) no-repeat;mask:url(/assets/back-to-top.8efcbe56.svg) no-repeat;z-index:var(--back-to-top-z-index)}.back-to-top:hover{background-color:var(--back-to-top-color-hover)}@media (max-width: 959px){.back-to-top{display:none}}.back-to-top-enter-active,.back-to-top-leave-active{transition:opacity .3s}.back-to-top-enter-from,.back-to-top-leave-to{opacity:0}:root{--external-link-icon-color: #aaa}.external-link-icon{position:relative;display:inline-block;color:var(--external-link-icon-color);vertical-align:middle;top:-1px}.external-link-icon-sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border-width:0;-webkit-user-select:none;-moz-user-select:none;user-select:none}:root{--medium-zoom-z-index: 100;--medium-zoom-bg-color: #ffffff;--medium-zoom-opacity: 1}.medium-zoom-overlay{background-color:var(--medium-zoom-bg-color)!important;z-index:var(--medium-zoom-z-index)}.medium-zoom-overlay~img{z-index:calc(var(--medium-zoom-z-index) + 1)}.medium-zoom--opened .medium-zoom-overlay{opacity:var(--medium-zoom-opacity)}:root{--nprogress-color: #29d;--nprogress-z-index: 1031}#nprogress{pointer-events:none}#nprogress .bar{background:var(--nprogress-color);position:fixed;z-index:var(--nprogress-z-index);top:0;left:0;width:100%;height:2px}:root{--c-brand: #3eaf7c;--c-brand-light: #4abf8a;--c-bg: #ffffff;--c-bg-light: #f3f4f5;--c-bg-lighter: #eeeeee;--c-bg-navbar: var(--c-bg);--c-bg-sidebar: var(--c-bg);--c-bg-arrow: #cccccc;--c-text: #2c3e50;--c-text-accent: var(--c-brand);--c-text-light: #3a5169;--c-text-lighter: #4e6e8e;--c-text-lightest: #6a8bad;--c-text-quote: #999999;--c-border: #eaecef;--c-border-dark: #dfe2e5;--c-tip: #42b983;--c-tip-bg: var(--c-bg-light);--c-tip-title: var(--c-text);--c-tip-text: var(--c-text);--c-tip-text-accent: var(--c-text-accent);--c-warning: #e7c000;--c-warning-bg: #fffae3;--c-warning-title: #ad9000;--c-warning-text: #746000;--c-warning-text-accent: var(--c-text);--c-danger: #cc0000;--c-danger-bg: #ffe0e0;--c-danger-title: #990000;--c-danger-text: #660000;--c-danger-text-accent: var(--c-text);--c-details-bg: #eeeeee;--c-badge-tip: var(--c-tip);--c-badge-warning: var(--c-warning);--c-badge-danger: var(--c-danger);--t-color: .3s ease;--t-transform: .3s ease;--code-bg-color: #282c34;--code-hl-bg-color: rgba(0, 0, 0, .66);--code-ln-color: #9e9e9e;--code-ln-wrapper-width: 3.5rem;--font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;--font-family-code: Consolas, Monaco, "Andale Mono", "Ubuntu Mono", monospace;--navbar-height: 3.6rem;--navbar-padding-v: .7rem;--navbar-padding-h: 1.5rem;--sidebar-width: 20rem;--sidebar-width-mobile: calc(var(--sidebar-width) * .82);--content-width: 740px;--homepage-width: 960px}html.dark{--c-brand: #3aa675;--c-brand-light: #349469;--c-bg: #22272e;--c-bg-light: #2b313a;--c-bg-lighter: #262c34;--c-text: #adbac7;--c-text-light: #96a7b7;--c-text-lighter: #8b9eb0;--c-text-lightest: #8094a8;--c-border: #3e4c5a;--c-border-dark: #34404c;--c-tip: #318a62;--c-warning: #ceab00;--c-warning-bg: #7e755b;--c-warning-title: #ceac03;--c-warning-text: #362e00;--c-danger: #940000;--c-danger-bg: #806161;--c-danger-title: #610000;--c-danger-text: #3a0000;--c-details-bg: #323843;--code-hl-bg-color: #363b46}html,body{padding:0;margin:0;background-color:var(--c-bg);transition:background-color var(--t-color)}html.dark{color-scheme:dark}html{font-size:16px}body{font-family:var(--font-family);-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;font-size:1rem;color:var(--c-text)}a{font-weight:500;color:var(--c-text-accent);text-decoration:none;overflow-wrap:break-word}p a code{font-weight:400;color:var(--c-text-accent)}kbd{font-family:var(--font-family-code);color:var(--c-text);background:var(--c-bg-lighter);border:solid .15rem var(--c-border-dark);border-bottom:solid .25rem var(--c-border-dark);border-radius:.15rem;padding:0 .15em}code{font-family:var(--font-family-code);color:var(--c-text-lighter);padding:.25rem .5rem;margin:0;font-size:.85em;background-color:var(--c-bg-lighter);border-radius:3px;overflow-wrap:break-word;transition:background-color var(--t-color)}blockquote{font-size:1rem;color:var(--c-text-quote);border-left:.2rem solid var(--c-border-dark);margin:1rem 0;padding:.25rem 0 .25rem 1rem}blockquote>p{margin:0}ul,ol{padding-left:1.2em}strong{font-weight:600}h1,h2,h3,h4,h5,h6{font-weight:600;line-height:1.25}h1:focus-visible,h2:focus-visible,h3:focus-visible,h4:focus-visible,h5:focus-visible,h6:focus-visible{outline:none}h1:hover .header-anchor,h2:hover .header-anchor,h3:hover .header-anchor,h4:hover .header-anchor,h5:hover .header-anchor,h6:hover .header-anchor{opacity:1}h1{font-size:2.2rem}h2{font-size:1.65rem;padding-bottom:.3rem;border-bottom:1px solid var(--c-border);transition:border-color var(--t-color)}h3{font-size:1.35rem}h4{font-size:1.15rem}h5{font-size:1.05rem}h6{font-size:1rem}a.header-anchor{font-size:.85em;float:left;margin-left:-.87em;padding-right:.23em;margin-top:.125em;opacity:0;-webkit-user-select:none;-moz-user-select:none;user-select:none}a.header-anchor:hover{text-decoration:none}a.header-anchor:focus-visible{opacity:1}p,ul,ol{line-height:1.7}hr{border:0;border-top:1px solid var(--c-border)}table{border-collapse:collapse;margin:1rem 0;display:block;overflow-x:auto;transition:border-color var(--t-color)}tr{border-top:1px solid var(--c-border-dark);transition:border-color var(--t-color)}tr:nth-child(2n){background-color:var(--c-bg-light);transition:background-color var(--t-color)}th,td{padding:.6em 1em;border:1px solid var(--c-border-dark);transition:border-color var(--t-color)}.arrow{display:inline-block;width:0;height:0}.arrow.up{border-left:4px solid transparent;border-right:4px solid transparent;border-bottom:6px solid var(--c-bg-arrow)}.arrow.down{border-left:4px solid transparent;border-right:4px solid transparent;border-top:6px solid var(--c-bg-arrow)}.arrow.right{border-top:4px solid transparent;border-bottom:4px solid transparent;border-left:6px solid var(--c-bg-arrow)}.arrow.left{border-top:4px solid transparent;border-bottom:4px solid transparent;border-right:6px solid var(--c-bg-arrow)}.badge{display:inline-block;font-size:14px;height:18px;line-height:18px;border-radius:3px;padding:0 6px;color:var(--c-bg);vertical-align:top;transition:color var(--t-color),background-color var(--t-color)}.badge.tip{background-color:var(--c-badge-tip)}.badge.warning{background-color:var(--c-badge-warning)}.badge.danger{background-color:var(--c-badge-danger)}.badge+.badge{margin-left:5px}code[class*=language-],pre[class*=language-]{color:#ccc;background:none;font-family:var(--font-family-code);font-size:1em;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;word-wrap:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;hyphens:none}pre[class*=language-]{padding:1em;margin:.5em 0;overflow:auto}:not(pre)>code[class*=language-],pre[class*=language-]{background:#2d2d2d}:not(pre)>code[class*=language-]{padding:.1em;border-radius:.3em;white-space:normal}.token.comment,.token.block-comment,.token.prolog,.token.doctype,.token.cdata{color:#999}.token.punctuation{color:#ccc}.token.tag,.token.attr-name,.token.namespace,.token.deleted{color:#ec5975}.token.function-name{color:#6196cc}.token.boolean,.token.number,.token.function{color:#f08d49}.token.property,.token.class-name,.token.constant,.token.symbol{color:#f8c555}.token.selector,.token.important,.token.atrule,.token.keyword,.token.builtin{color:#cc99cd}.token.string,.token.char,.token.attr-value,.token.regex,.token.variable{color:#7ec699}.token.operator,.token.entity,.token.url{color:#67cdcc}.token.important,.token.bold{font-weight:700}.token.italic{font-style:italic}.token.entity{cursor:help}.token.inserted{color:#3eaf7c}.theme-default-content pre,.theme-default-content pre[class*=language-]{line-height:1.4;padding:1.3rem 1.5rem;margin:.85rem 0;border-radius:6px;overflow:auto}.theme-default-content pre code,.theme-default-content pre[class*=language-] code{color:#fff;padding:0;background-color:transparent;border-radius:0;overflow-wrap:unset;-webkit-font-smoothing:auto;-moz-osx-font-smoothing:auto}.theme-default-content .line-number{font-family:var(--font-family-code)}div[class*=language-]{position:relative;background-color:var(--code-bg-color);border-radius:6px}div[class*=language-]:before{position:absolute;z-index:3;top:.8em;right:1em;font-size:.75rem;color:var(--code-ln-color)}div[class*=language-] pre,div[class*=language-] pre[class*=language-]{background:transparent!important;position:relative;z-index:1}div[class*=language-] .highlight-lines{-webkit-user-select:none;-moz-user-select:none;user-select:none;padding-top:1.3rem;position:absolute;top:0;left:0;width:100%;line-height:1.4}div[class*=language-] .highlight-lines .highlight-line{background-color:var(--code-hl-bg-color)}div[class*=language-]:not(.line-numbers-mode) .line-numbers{display:none}div[class*=language-].line-numbers-mode .highlight-lines .highlight-line{position:relative}div[class*=language-].line-numbers-mode .highlight-lines .highlight-line:before{content:" ";position:absolute;z-index:2;left:0;top:0;display:block;width:var(--code-ln-wrapper-width);height:100%}div[class*=language-].line-numbers-mode pre{margin-left:var(--code-ln-wrapper-width);padding-left:1rem;vertical-align:middle}div[class*=language-].line-numbers-mode .line-numbers{position:absolute;top:0;width:var(--code-ln-wrapper-width);text-align:center;color:var(--code-ln-color);padding-top:1.25rem;line-height:1.4;counter-reset:line-number}div[class*=language-].line-numbers-mode .line-numbers .line-number{position:relative;z-index:3;-webkit-user-select:none;-moz-user-select:none;user-select:none;height:1.4em}div[class*=language-].line-numbers-mode .line-numbers .line-number:before{counter-increment:line-number;content:counter(line-number);font-size:.85em}div[class*=language-].line-numbers-mode:after{content:"";position:absolute;top:0;left:0;width:var(--code-ln-wrapper-width);height:100%;border-radius:6px 0 0 6px;border-right:1px solid var(--code-hl-bg-color)}div[class*=language-].ext-c:before{content:"c"}div[class*=language-].ext-cpp:before{content:"cpp"}div[class*=language-].ext-cs:before{content:"cs"}div[class*=language-].ext-css:before{content:"css"}div[class*=language-].ext-dart:before{content:"dart"}div[class*=language-].ext-docker:before{content:"docker"}div[class*=language-].ext-fs:before{content:"fs"}div[class*=language-].ext-go:before{content:"go"}div[class*=language-].ext-html:before{content:"html"}div[class*=language-].ext-java:before{content:"java"}div[class*=language-].ext-js:before{content:"js"}div[class*=language-].ext-json:before{content:"json"}div[class*=language-].ext-kt:before{content:"kt"}div[class*=language-].ext-less:before{content:"less"}div[class*=language-].ext-makefile:before{content:"makefile"}div[class*=language-].ext-md:before{content:"md"}div[class*=language-].ext-php:before{content:"php"}div[class*=language-].ext-py:before{content:"py"}div[class*=language-].ext-rb:before{content:"rb"}div[class*=language-].ext-rs:before{content:"rs"}div[class*=language-].ext-sass:before{content:"sass"}div[class*=language-].ext-scss:before{content:"scss"}div[class*=language-].ext-sh:before{content:"sh"}div[class*=language-].ext-styl:before{content:"styl"}div[class*=language-].ext-ts:before{content:"ts"}div[class*=language-].ext-toml:before{content:"toml"}div[class*=language-].ext-vue:before{content:"vue"}div[class*=language-].ext-yml:before{content:"yml"}@media (max-width: 419px){.theme-default-content div[class*=language-]{margin:.85rem -1.5rem;border-radius:0}}.code-group__nav{margin-top:.85rem;margin-bottom:calc(-1.7rem - 6px);padding-bottom:calc(1.7rem - 6px);padding-left:10px;padding-top:10px;border-top-left-radius:6px;border-top-right-radius:6px;background-color:var(--code-bg-color)}.code-group__ul{margin:auto 0;padding-left:0;display:inline-flex;list-style:none}.code-group__nav-tab{border:0;padding:5px;cursor:pointer;background-color:transparent;font-size:.85em;line-height:1.4;color:#ffffffe6;font-weight:600}.code-group__nav-tab:focus{outline:none}.code-group__nav-tab:focus-visible{outline:1px solid rgba(255,255,255,.9)}.code-group__nav-tab-active{border-bottom:var(--c-brand) 1px solid}@media (max-width: 419px){.code-group__nav{margin-left:-1.5rem;margin-right:-1.5rem;border-radius:0}}.code-group-item{display:none}.code-group-item__active{display:block}.code-group-item>pre{background-color:orange}.custom-container{transition:color var(--t-color),border-color var(--t-color),background-color var(--t-color)}.custom-container .custom-container-title{font-weight:600}.custom-container .custom-container-title:not(:only-child){margin-bottom:-.4rem}.custom-container.tip,.custom-container.warning,.custom-container.danger{padding:.1rem 1.5rem;border-left-width:.5rem;border-left-style:solid;margin:1rem 0}.custom-container.tip{border-color:var(--c-tip);background-color:var(--c-tip-bg);color:var(--c-tip-text)}.custom-container.tip .custom-container-title{color:var(--c-tip-title)}.custom-container.tip a{color:var(--c-tip-text-accent)}.custom-container.warning{border-color:var(--c-warning);background-color:var(--c-warning-bg);color:var(--c-warning-text)}.custom-container.warning .custom-container-title{color:var(--c-warning-title)}.custom-container.warning a{color:var(--c-warning-text-accent)}.custom-container.danger{border-color:var(--c-danger);background-color:var(--c-danger-bg);color:var(--c-danger-text)}.custom-container.danger .custom-container-title{color:var(--c-danger-title)}.custom-container.danger a{color:var(--c-danger-text-accent)}.custom-container.details{display:block;position:relative;border-radius:2px;margin:1.6em 0;padding:1.6em;background-color:var(--c-details-bg)}.custom-container.details h4{margin-top:0}.custom-container.details figure:last-child,.custom-container.details p:last-child{margin-bottom:0;padding-bottom:0}.custom-container.details summary{outline:none;cursor:pointer}.home{padding:var(--navbar-height) 2rem 0;max-width:var(--homepage-width);margin:0 auto;display:block}.home .hero{text-align:center}.home .hero img{max-width:100%;max-height:280px;display:block;margin:3rem auto 1.5rem}.home .hero h1{font-size:3rem}.home .hero h1,.home .hero .description,.home .hero .actions{margin:1.8rem auto}.home .hero .actions{display:flex;flex-wrap:wrap;gap:1rem;justify-content:center}.home .hero .description{max-width:35rem;font-size:1.6rem;line-height:1.3;color:var(--c-text-lightest)}.home .hero .action-button{display:inline-block;font-size:1.2rem;padding:.8rem 1.6rem;border-width:2px;border-style:solid;border-radius:4px;transition:background-color var(--t-color);box-sizing:border-box}.home .hero .action-button.primary{color:var(--c-bg);background-color:var(--c-brand);border-color:var(--c-brand)}.home .hero .action-button.primary:hover{background-color:var(--c-brand-light)}.home .hero .action-button.secondary{color:var(--c-brand);background-color:var(--c-bg);border-color:var(--c-brand)}.home .hero .action-button.secondary:hover{color:var(--c-bg);background-color:var(--c-brand-light)}.home .features{border-top:1px solid var(--c-border);transition:border-color var(--t-color);padding:1.2rem 0;margin-top:2.5rem;display:flex;flex-wrap:wrap;align-items:flex-start;align-content:stretch;justify-content:space-between}.home .feature{flex-grow:1;flex-basis:30%;max-width:30%}.home .feature h2{font-size:1.4rem;font-weight:500;border-bottom:none;padding-bottom:0;color:var(--c-text-light)}.home .feature p{color:var(--c-text-lighter)}.home .theme-default-content{padding:0;margin:0}.home .footer{padding:2.5rem;border-top:1px solid var(--c-border);text-align:center;color:var(--c-text-lighter);transition:border-color var(--t-color)}@media (max-width: 719px){.home .features{flex-direction:column}.home .feature{max-width:100%;padding:0 2.5rem}}@media (max-width: 419px){.home{padding-left:1.5rem;padding-right:1.5rem}.home .hero img{max-height:210px;margin:2rem auto 1.2rem}.home .hero h1{font-size:2rem}.home .hero h1,.home .hero .description,.home .hero .actions{margin:1.2rem auto}.home .hero .description{font-size:1.2rem}.home .hero .action-button{font-size:1rem;padding:.6rem 1.2rem}.home .feature h2{font-size:1.25rem}}.page{padding-top:var(--navbar-height);padding-left:var(--sidebar-width)}.navbar{position:fixed;z-index:20;top:0;left:0;right:0;height:var(--navbar-height);box-sizing:border-box;border-bottom:1px solid var(--c-border);background-color:var(--c-bg-navbar);transition:background-color var(--t-color),border-color var(--t-color)}.sidebar{font-size:16px;width:var(--sidebar-width);position:fixed;z-index:10;margin:0;top:var(--navbar-height);left:0;bottom:0;box-sizing:border-box;border-right:1px solid var(--c-border);overflow-y:auto;scrollbar-width:thin;scrollbar-color:var(--c-brand) var(--c-border);background-color:var(--c-bg-sidebar);transition:transform var(--t-transform),background-color var(--t-color),border-color var(--t-color)}.sidebar::-webkit-scrollbar{width:7px}.sidebar::-webkit-scrollbar-track{background-color:var(--c-border)}.sidebar::-webkit-scrollbar-thumb{background-color:var(--c-brand)}.sidebar-mask{position:fixed;z-index:9;top:0;left:0;width:100vw;height:100vh;display:none}.theme-container.sidebar-open .sidebar-mask{display:block}.theme-container.sidebar-open .navbar>.toggle-sidebar-button .icon span:nth-child(1){transform:rotate(45deg) translate3d(5.5px,5.5px,0)}.theme-container.sidebar-open .navbar>.toggle-sidebar-button .icon span:nth-child(2){transform:scale3d(0,1,1)}.theme-container.sidebar-open .navbar>.toggle-sidebar-button .icon span:nth-child(3){transform:rotate(-45deg) translate3d(6px,-6px,0)}.theme-container.sidebar-open .navbar>.toggle-sidebar-button .icon span:nth-child(1),.theme-container.sidebar-open .navbar>.toggle-sidebar-button .icon span:nth-child(3){transform-origin:center}.theme-container.no-navbar .theme-default-content h1,.theme-container.no-navbar .theme-default-content h2,.theme-container.no-navbar .theme-default-content h3,.theme-container.no-navbar .theme-default-content h4,.theme-container.no-navbar .theme-default-content h5,.theme-container.no-navbar .theme-default-content h6{margin-top:1.5rem;padding-top:0}.theme-container.no-navbar .page{padding-top:0}.theme-container.no-navbar .sidebar{top:0}@media (min-width: 720px){.theme-container.no-sidebar .sidebar{display:none}.theme-container.no-sidebar .page{padding-left:0}}.theme-default-content a:hover{text-decoration:underline}.theme-default-content img{max-width:100%}.theme-default-content h1,.theme-default-content h2,.theme-default-content h3,.theme-default-content h4,.theme-default-content h5,.theme-default-content h6{margin-top:calc(.5rem - var(--navbar-height));padding-top:calc(1rem + var(--navbar-height));margin-bottom:0}.theme-default-content h1:first-child,.theme-default-content h2:first-child,.theme-default-content h3:first-child,.theme-default-content h4:first-child,.theme-default-content h5:first-child,.theme-default-content h6:first-child{margin-bottom:1rem}.theme-default-content h1:first-child+p,.theme-default-content h1:first-child+pre,.theme-default-content h1:first-child+.custom-container,.theme-default-content h2:first-child+p,.theme-default-content h2:first-child+pre,.theme-default-content h2:first-child+.custom-container,.theme-default-content h3:first-child+p,.theme-default-content h3:first-child+pre,.theme-default-content h3:first-child+.custom-container,.theme-default-content h4:first-child+p,.theme-default-content h4:first-child+pre,.theme-default-content h4:first-child+.custom-container,.theme-default-content h5:first-child+p,.theme-default-content h5:first-child+pre,.theme-default-content h5:first-child+.custom-container,.theme-default-content h6:first-child+p,.theme-default-content h6:first-child+pre,.theme-default-content h6:first-child+.custom-container{margin-top:2rem}@media (max-width: 959px){.sidebar{font-size:15px;width:var(--sidebar-width-mobile)}.page{padding-left:var(--sidebar-width-mobile)}}@media (max-width: 719px){.sidebar{top:0;padding-top:var(--navbar-height);transform:translate(-100%)}.page{padding-left:0}.theme-container.sidebar-open .sidebar{transform:translate(0)}.theme-container.no-navbar .sidebar{padding-top:0}}@media (max-width: 419px){h1{font-size:1.9rem}}.navbar{--navbar-line-height: calc( var(--navbar-height) - 2 * var(--navbar-padding-v) );padding:var(--navbar-padding-v) var(--navbar-padding-h);line-height:var(--navbar-line-height)}.navbar .logo{height:var(--navbar-line-height);margin-right:var(--navbar-padding-v);vertical-align:top}.navbar .site-name{font-size:1.3rem;font-weight:600;color:var(--c-text);position:relative}.navbar .navbar-items-wrapper{display:flex;position:absolute;box-sizing:border-box;top:var(--navbar-padding-v);right:var(--navbar-padding-h);height:var(--navbar-line-height);padding-left:var(--navbar-padding-h);white-space:nowrap;font-size:.9rem}.navbar .navbar-items-wrapper .search-box{flex:0 0 auto;vertical-align:top}@media (max-width: 719px){.navbar{padding-left:4rem}.navbar .can-hide{display:none}.navbar .site-name{width:calc(100vw - 9.4rem);overflow:hidden;white-space:nowrap;text-overflow:ellipsis}}.navbar-items{display:inline-block}.navbar-items a{display:inline-block;line-height:1.4rem;color:inherit}.navbar-items a:hover,.navbar-items a.router-link-active{color:var(--c-text-accent)}.navbar-items .navbar-item{position:relative;display:inline-block;margin-left:1.5rem;line-height:var(--navbar-line-height)}.navbar-items .navbar-item:first-child{margin-left:0}@media (max-width: 719px){.navbar-items .navbar-item{margin-left:0}}@media (min-width: 719px){.navbar-items a:hover,.navbar-items a.router-link-active{color:var(--c-text)}.navbar-item>a:hover,.navbar-item>a.router-link-active{margin-bottom:-2px;border-bottom:2px solid var(--c-text-accent)}}.toggle-sidebar-button{position:absolute;top:.6rem;left:1rem;display:none;padding:.6rem;cursor:pointer}.toggle-sidebar-button .icon{display:flex;flex-direction:column;justify-content:center;align-items:center;width:1.25rem;height:1.25rem;cursor:inherit}.toggle-sidebar-button .icon span{display:inline-block;width:100%;height:2px;border-radius:2px;background-color:var(--c-text);transition:transform var(--t-transform)}.toggle-sidebar-button .icon span:nth-child(2){margin:6px 0}@media screen and (max-width: 719px){.toggle-sidebar-button{display:block}}.toggle-color-mode-button{display:flex;margin:auto;margin-left:1rem;border:0;background:none;color:var(--c-text);opacity:.8;cursor:pointer}.toggle-color-mode-button:hover{opacity:1}.toggle-color-mode-button .icon{width:1.25rem;height:1.25rem}.DocSearch{transition:background-color var(--t-color)}.navbar-dropdown-wrapper{cursor:pointer}.navbar-dropdown-wrapper .navbar-dropdown-title,.navbar-dropdown-wrapper .navbar-dropdown-title-mobile{display:block;font-size:.9rem;font-family:inherit;cursor:inherit;padding:inherit;line-height:1.4rem;background:transparent;border:none;font-weight:500;color:var(--c-text)}.navbar-dropdown-wrapper .navbar-dropdown-title:hover,.navbar-dropdown-wrapper .navbar-dropdown-title-mobile:hover{border-color:transparent}.navbar-dropdown-wrapper .navbar-dropdown-title .arrow,.navbar-dropdown-wrapper .navbar-dropdown-title-mobile .arrow{vertical-align:middle;margin-top:-1px;margin-left:.4rem}.navbar-dropdown-wrapper .navbar-dropdown-title-mobile{display:none;font-weight:600;font-size:inherit}.navbar-dropdown-wrapper .navbar-dropdown-title-mobile:hover{color:var(--c-text-accent)}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item{color:inherit;line-height:1.7rem}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle{margin:.45rem 0 0;border-top:1px solid var(--c-border);padding:1rem 0 .45rem;font-size:.9rem}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle>span{padding:0 1.5rem 0 1.25rem}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle>a{font-weight:inherit}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle>a.router-link-active:after{display:none}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subitem-wrapper{padding:0;list-style:none}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subitem-wrapper .navbar-dropdown-subitem{font-size:.9em}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item a{display:block;line-height:1.7rem;position:relative;border-bottom:none;font-weight:400;margin-bottom:0;padding:0 1.5rem 0 1.25rem}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item a:hover,.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item a.router-link-active{color:var(--c-text-accent)}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item a.router-link-active:after{content:"";width:0;height:0;border-left:5px solid var(--c-text-accent);border-top:3px solid transparent;border-bottom:3px solid transparent;position:absolute;top:calc(50% - 2px);left:9px}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item:first-child .navbar-dropdown-subtitle{margin-top:0;padding-top:0;border-top:0}@media (max-width: 719px){.navbar-dropdown-wrapper.open .navbar-dropdown-title,.navbar-dropdown-wrapper.open .navbar-dropdown-title-mobile{margin-bottom:.5rem}.navbar-dropdown-wrapper .navbar-dropdown-title,.navbar-dropdown-wrapper .navbar-dropdown-title-mobile{display:none}.navbar-dropdown-wrapper .navbar-dropdown-title-mobile{display:block}.navbar-dropdown-wrapper .navbar-dropdown{transition:height .1s ease-out;overflow:hidden}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle{border-top:0;margin-top:0;padding-top:0;padding-bottom:0}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle,.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item>a{font-size:15px;line-height:2rem}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subitem{font-size:14px;padding-left:1rem}}@media (min-width: 720px){.navbar-dropdown-wrapper{height:1.8rem}.navbar-dropdown-wrapper:hover .navbar-dropdown,.navbar-dropdown-wrapper.open .navbar-dropdown{display:block!important}.navbar-dropdown-wrapper.open:blur{display:none}.navbar-dropdown-wrapper .navbar-dropdown{display:none;height:auto!important;box-sizing:border-box;max-height:calc(100vh - 2.7rem);overflow-y:auto;position:absolute;top:100%;right:0;background-color:var(--c-bg-navbar);padding:.6rem 0;border:1px solid var(--c-border);border-bottom-color:var(--c-border-dark);text-align:left;border-radius:.25rem;white-space:nowrap;margin:0}}.page{padding-bottom:2rem;display:block}.page .theme-default-content{max-width:var(--content-width);margin:0 auto;padding:2rem 2.5rem;padding-top:0}@media (max-width: 959px){.page .theme-default-content{padding:2rem}}@media (max-width: 419px){.page .theme-default-content{padding:1.5rem}}.page-meta{max-width:var(--content-width);margin:0 auto;padding:1rem 2.5rem;overflow:auto}@media (max-width: 959px){.page-meta{padding:2rem}}@media (max-width: 419px){.page-meta{padding:1.5rem}}.page-meta .meta-item{cursor:default;margin-top:.8rem}.page-meta .meta-item .meta-item-label{font-weight:500;color:var(--c-text-lighter)}.page-meta .meta-item .meta-item-info{font-weight:400;color:var(--c-text-quote)}.page-meta .edit-link{display:inline-block;margin-right:.25rem}.page-meta .last-updated{float:right}@media (max-width: 719px){.page-meta .last-updated{font-size:.8em;float:none}.page-meta .contributors{font-size:.8em}}.page-nav{max-width:var(--content-width);margin:0 auto;padding:1rem 2.5rem 2rem;padding-bottom:0}@media (max-width: 959px){.page-nav{padding:2rem}}@media (max-width: 419px){.page-nav{padding:1.5rem}}.page-nav .inner{min-height:2rem;margin-top:0;border-top:1px solid var(--c-border);transition:border-color var(--t-color);padding-top:1rem;overflow:auto}.page-nav .prev a:before{content:"\2190"}.page-nav .next{float:right}.page-nav .next a:after{content:"\2192"}.sidebar ul{padding:0;margin:0;list-style-type:none}.sidebar a{display:inline-block}.sidebar .navbar-items{display:none;border-bottom:1px solid var(--c-border);transition:border-color var(--t-color);padding:.5rem 0 .75rem}.sidebar .navbar-items a{font-weight:600}.sidebar .navbar-items .navbar-item{display:block;line-height:1.25rem;font-size:1.1em;padding:.5rem 0 .5rem 1.5rem}.sidebar .sidebar-items{padding:1.5rem 0}@media (max-width: 719px){.sidebar .navbar-items{display:block}.sidebar .navbar-items .navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item a.router-link-active:after{top:calc(1rem - 2px)}.sidebar .sidebar-items{padding:1rem 0}}.sidebar-item{cursor:default;border-left:.25rem solid transparent;color:var(--c-text)}.sidebar-item:focus-visible{outline-width:1px;outline-offset:-1px}.sidebar-item.active:not(p.sidebar-heading){font-weight:600;color:var(--c-text-accent);border-left-color:var(--c-text-accent)}.sidebar-item.sidebar-heading{transition:color .15s ease;font-size:1.1em;font-weight:700;padding:.35rem 1.5rem .35rem 1.25rem;width:100%;box-sizing:border-box;margin:0}.sidebar-item.sidebar-heading+.sidebar-item-children{transition:height .1s ease-out;overflow:hidden;margin-bottom:.75rem}.sidebar-item.sidebar-heading.collapsible{cursor:pointer}.sidebar-item.sidebar-heading.collapsible .arrow{position:relative;top:-.12em;left:.5em}.sidebar-item:not(.sidebar-heading){font-size:1em;font-weight:400;display:inline-block;margin:0;padding:.35rem 1rem .35rem 2rem;line-height:1.4;width:100%;box-sizing:border-box}.sidebar-item:not(.sidebar-heading)+.sidebar-item-children{padding-left:1rem;font-size:.95em}.sidebar-item-children .sidebar-item-children .sidebar-item:not(.sidebar-heading){padding:.25rem 1rem .25rem 1.75rem}.sidebar-item-children .sidebar-item-children .sidebar-item:not(.sidebar-heading).active{font-weight:500;border-left-color:transparent}a.sidebar-heading+.sidebar-item-children .sidebar-item:not(.sidebar-heading).active{border-left-color:transparent}a.sidebar-item{cursor:pointer}a.sidebar-item:hover{color:var(--c-text-accent)}.table-of-contents .badge{vertical-align:middle}.dropdown-enter-from,.dropdown-leave-to{height:0!important}.fade-slide-y-enter-active{transition:all .2s ease}.fade-slide-y-leave-active{transition:all .2s cubic-bezier(1,.5,.8,1)}.fade-slide-y-enter-from,.fade-slide-y-leave-to{transform:translateY(10px);opacity:0}:root{--c-brand: #6c83e0;--c-brand-light: #7b8fe3;--c-bg: #ffffff;--c-bg-light: #f3f4f5;--c-bg-lighter: #eeeeee;--c-bg-navbar: var(--c-bg);--c-bg-sidebar: var(--c-bg);--c-bg-arrow: #ccc;--c-text: #2c3e50;--c-text-accent: var(--c-brand);--c-text-light: #3a5169;--c-text-lighter: #4e6e8e;--c-text-lightest: #6a8bad;--c-text-quote: #999999;--c-border: #eaecef;--c-border-dark: #dfe2e5;--c-tip: #42b983;--c-tip-bg: var(--c-bg-light);--c-tip-title: var(--c-text);--c-tip-text: var(--c-text);--c-tip-text-accent: var(--c-text-accent);--c-warning: #e7c000;--c-warning-bg: #fffae3;--c-warning-title: #ad9000;--c-warning-text: #746000;--c-warning-text-accent: var(--c-text);--c-danger: #cc0000;--c-danger-bg: #ffe0e0;--c-danger-title: #990000;--c-danger-text: #660000;--c-danger-text-accent: var(--c-text);--c-details-bg: #eeeeee;--c-badge-tip: var(--c-tip);--c-badge-warning: var(--c-warning);--c-badge-danger: var(--c-danger);--t-color: .3s ease;--t-transform: .3s ease;--code-bg-color: #282c34;--code-hl-bg-color: rgba(0, 0, 0, .66);--code-ln-color: #9e9e9e;--code-ln-wrapper-width: 3.5rem;--font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;--font-family-code: Consolas, Monaco, "Andale Mono", "Ubuntu Mono", monospace;--navbar-height: 3.6rem;--navbar-padding-v: .7rem;--navbar-padding-h: 1.5rem;--sidebar-width: 20rem;--sidebar-width-mobile: calc(var(--sidebar-width) * .82);--content-width: 740px;--homepage-width: 960px}.back-to-top{--back-to-top-color: var(--c-brand);--back-to-top-color-hover: var(--c-brand-light)}.DocSearch{--docsearch-primary-color: var(--c-brand);--docsearch-text-color: var(--c-text);--docsearch-highlight-color: var(--c-brand);--docsearch-muted-color: var(--c-text-quote);--docsearch-container-background: rgba(9, 10, 17, .8);--docsearch-modal-background: var(--c-bg-light);--docsearch-searchbox-background: var(--c-bg-lighter);--docsearch-searchbox-focus-background: var(--c-bg);--docsearch-searchbox-shadow: inset 0 0 0 2px var(--c-brand);--docsearch-hit-color: var(--c-text-light);--docsearch-hit-active-color: var(--c-bg);--docsearch-hit-background: var(--c-bg);--docsearch-hit-shadow: 0 1px 3px 0 var(--c-border-dark);--docsearch-footer-background: var(--c-bg)}.external-link-icon{--external-link-icon-color: var(--c-text-quote)}.medium-zoom-overlay{--medium-zoom-bg-color: var(--c-bg)}#nprogress{--nprogress-color: var(--c-brand)}.pwa-popup{--pwa-popup-text-color: var(--c-text);--pwa-popup-bg-color: var(--c-bg);--pwa-popup-border-color: var(--c-brand);--pwa-popup-shadow: 0 4px 16px var(--c-brand);--pwa-popup-btn-text-color: var(--c-bg);--pwa-popup-btn-bg-color: var(--c-brand);--pwa-popup-btn-hover-bg-color: var(--c-brand-light)}.search-box{--search-bg-color: var(--c-bg);--search-accent-color: var(--c-brand);--search-text-color: var(--c-text);--search-border-color: var(--c-border);--search-item-text-color: var(--c-text-lighter);--search-item-focus-bg-color: var(--c-bg-light)}html.dark{--c-brand: #6c83e0;--c-brand-light: #7b8fe3;--c-bg: #22272e;--c-bg-light: #2b313a;--c-bg-lighter: #262c34;--c-text: #adbac7;--c-text-light: #96a7b7;--c-text-lighter: #8b9eb0;--c-text-lightest: #8094a8;--c-border: #3e4c5a;--c-border-dark: #34404c;--c-tip: #318a62;--c-warning: #ceab00;--c-warning-bg: #7e755b;--c-warning-title: #ceac03;--c-warning-text: #362e00;--c-danger: #940000;--c-danger-bg: #806161;--c-danger-title: #610000;--c-danger-text: #3a0000;--c-details-bg: #323843;--code-hl-bg-color: #363b46}html.dark .DocSearch{--docsearch-logo-color: var(--c-text);--docsearch-modal-shadow: inset 1px 1px 0 0 #2c2e40, 0 3px 8px 0 #000309;--docsearch-key-shadow: inset 0 -2px 0 0 #282d55, inset 0 0 1px 1px #51577d, 0 2px 2px 0 rgba(3, 4, 9, .3);--docsearch-key-gradient: linear-gradient(-225deg, #444950, #1c1e21);--docsearch-footer-shadow: inset 0 1px 0 0 rgba(73, 76, 106, .5), 0 -4px 8px 0 rgba(0, 0, 0, .2)}:root{--search-bg-color: #ffffff;--search-accent-color: #3eaf7c;--search-text-color: #2c3e50;--search-border-color: #eaecef;--search-item-text-color: #5d81a5;--search-item-focus-bg-color: #f3f4f5;--search-input-width: 8rem;--search-result-width: 20rem}.search-box{display:inline-block;position:relative;margin-left:1rem}.search-box input{cursor:text;width:var(--search-input-width);height:2rem;color:var(--search-text-color);display:inline-block;border:1px solid var(--search-border-color);border-radius:2rem;font-size:.9rem;line-height:2rem;padding:0 .5rem 0 2rem;outline:none;transition:all ease .3s;background:var(--search-bg-color) url(/assets/search.0782d0d1.svg) .6rem .5rem no-repeat;background-size:1rem}.search-box input:focus{cursor:auto;border-color:var(--search-accent-color)}.search-box .suggestions{background:var(--search-bg-color);width:var(--search-result-width);position:absolute;top:2rem;right:0;border:1px solid var(--search-border-color);border-radius:6px;padding:.4rem;list-style-type:none}.search-box .suggestion{line-height:1.4;padding:.4rem .6rem;border-radius:4px;cursor:pointer}.search-box .suggestion.focus{background-color:var(--search-item-focus-bg-color)}.search-box .suggestion.focus a{color:var(--search-accent-color)}.search-box .suggestion a{white-space:normal;color:var(--search-item-text-color)}.search-box .suggestion .page-title{font-weight:600}.search-box .suggestion .page-header{font-size:.9em;margin-left:.25em}@media (max-width: 720px){.search-box input{cursor:pointer;width:0;border-color:transparent;position:relative}.search-box input:focus{cursor:text;left:0;width:10rem}}@media (max-width: 420px){.search-box input:focus{width:8rem}.search-box .suggestions{width:calc(100vw - 4rem);right:-.5rem}} diff --git a/assets/use-invite-link.6050cdc9.png b/assets/use-invite-link.6050cdc9.png new file mode 100644 index 0000000..ba52a59 Binary files /dev/null and b/assets/use-invite-link.6050cdc9.png differ diff --git a/assets/writing-your-first-bot.html.3edd185d.js b/assets/writing-your-first-bot.html.3edd185d.js new file mode 100644 index 0000000..637b3b7 --- /dev/null +++ b/assets/writing-your-first-bot.html.3edd185d.js @@ -0,0 +1,28 @@ +import{_ as o,r as i,o as p,c,a as n,b as t,w as e,d as s,e as u}from"./app.151ccb98.js";var l="/assets/ping-pong-white.53343497.gif";const r={},d=n("h1",{id:"writing-your-first-bot",tabindex:"-1"},[n("a",{class:"header-anchor",href:"#writing-your-first-bot","aria-hidden":"true"},"#"),s(" Writing your first bot")],-1),k=n("p",null,"After you have successfully added Javacord as a dependency, created a bot user, and got its token, you are now ready to create your first simple bot! \u{1F389}",-1),v=n("h2",{id:"enabling-required-intents",tabindex:"-1"},[n("a",{class:"header-anchor",href:"#enabling-required-intents","aria-hidden":"true"},"#"),s(" \u2757 Enabling required intents")],-1),m=s("By default, all non-privileged intents are enabled. To receive the message content, attachments, components, and embeds you need a special privileged intent "),g=n("code",null,"MESSAGE_CONTENT",-1),h=s(". To enable this privileged intent please see the "),b=s("Gateway Intents"),f=s(" wiki article."),y={class:"custom-container tip"},_=n("p",{class:"custom-container-title"},"Slash Commands",-1),w=s("Generally it is recommended to use "),q=s("Slash Commands"),x=s(" instead of text commands because they offer many advantages like auto-completion, fixed and optional arguments, different kind of arguments with built-in types: numbers(with ranges), text, channel and a lot more."),C=u(`\u{1F511} Log the bot in
Everything starts with the DiscordApiBuilder class. It is used to create a DiscordApi object which is the most important class of your bot.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("<your super secret token>")
+ .addIntents(Intent.MESSAGE_CONTENT)
+ .login().join();
+After executing this code, you should already see your bot online in Discord. Of course, just being online is not enough, so let's add some more code!
\u{1F442} Adding a listener
After you got your api instance, let's continue by adding a listener that answers every !ping message with a simple Pong!.
api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+});
+\u{1F469}\u200D\u{1F527} Putting it all together
A good place for your code is the main(...) method that every executable Java program must have. Your complete class may look like this:
public class MyFirstBot {
+
+ public static void main(String[] args) {
+ // Log the bot in
+ DiscordApi api = new DiscordApiBuilder()
+ .setToken("<your super secret token>")
+ .addIntents(Intent.MESSAGE_CONTENT)
+ .login().join();
+
+ // Add a listener which answers with "Pong!" if someone writes "!ping"
+ api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ });
+ }
+
+}
+Congratulations, that's already everything you have to know for the beginning. Now, you can play around a little bit by exploring other listeners and methods. Or you just continue reading articles in the Basic Tutorials category.
`,12);function A(j,E){const a=i("RouterLink");return p(),c("div",null,[d,k,v,n("p",null,[m,g,h,t(a,{to:"/wiki/basic-tutorials/gateway-intents.html#privileged-intents"},{default:e(()=>[b]),_:1}),f]),n("div",y,[_,n("p",null,[w,t(a,{to:"/wiki/basic-tutorials/interactions/commands.html"},{default:e(()=>[q]),_:1}),x])]),C])}var N=o(r,[["render",A],["__file","writing-your-first-bot.html.vue"]]);export{N as default}; diff --git a/assets/writing-your-first-bot.html.ab95f1ba.js b/assets/writing-your-first-bot.html.ab95f1ba.js new file mode 100644 index 0000000..42eb611 --- /dev/null +++ b/assets/writing-your-first-bot.html.ab95f1ba.js @@ -0,0 +1 @@ +const t=JSON.parse('{"key":"v-7bf86adb","path":"/wiki/getting-started/writing-your-first-bot.html","title":"Writing your first bot","lang":"en-US","frontmatter":{},"excerpt":"","headers":[{"level":2,"title":"\u2757 Enabling required intents","slug":"enabling-required-intents","children":[]},{"level":2,"title":"\u{1F511} Log the bot in","slug":"log-the-bot-in","children":[]},{"level":2,"title":"\u{1F442} Adding a listener","slug":"adding-a-listener","children":[]},{"level":2,"title":"\u{1F469}\u200D\u{1F527} Putting it all together","slug":"putting-it-all-together","children":[]}],"git":{"updatedTime":1692105785000,"contributors":[{"name":"Dominic Fellbaum","email":"d.fellbaum@hotmail.de","commits":1}]},"filePathRelative":"wiki/getting-started/writing-your-first-bot.md"}');export{t as data}; diff --git a/bot-search-index.json b/bot-search-index.json new file mode 100644 index 0000000..e456634 --- /dev/null +++ b/bot-search-index.json @@ -0,0 +1 @@ +[{"title":"Imprint","headers":[],"content":"# Imprint
\n","path":"/imprint.html","keywords":[]},{"title":"Privacy Policy","headers":[],"content":"# Privacy Policy
\n","path":"/privacy-policy.html","keywords":[]},{"title":"Bot Lifecycle","headers":[{"level":2,"title":"💡 The four states","slug":"the-four-states","children":[{"level":3,"title":"Connected","slug":"connected","children":[]},{"level":3,"title":"Disconnected","slug":"disconnected","children":[]},{"level":3,"title":"Resuming","slug":"resuming","children":[]},{"level":3,"title":"Reconnecting","slug":"reconnecting","children":[]}]},{"level":2,"title":"💊 How to handle disconnects","slug":"how-to-handle-disconnects","children":[]}],"content":"# Bot Lifecycle
\nIt's important to know the life-cycle of a discord bot to properly handle disconnects.\nThe following state diagram shows the 4 states a bot can have:
\n![\"\"](\"@source/wiki/advanced-topics/lifecycle-state-diagram.svg\")
# 💡 The four states
\n# Connected
\nThe bot is connected to the websocket and receives all events.
\n# Disconnected
\nThe bot is not connected to the websocket and receives no events. It's not uncommon for a bot to occasionally lose connection.\nThis can have various reasons, for example:
\n- \n
- Your bot lost its internet connection \n
- Discord restarted the gateway server you are currently connected to \n
- A plane crashed into Discord's data center \n
The bot will periodically try to resume/reconnect to the websocket. It will start with a small frequency and increase it\nwith every failed reconnect attempt. You can modify the reconnect delay with the DiscordApi#setReconnectDelay(...) method.\nThe following example code would increase the delay linearly.\nThe 1st attempt would be delayed for 2 seconds, the 2nd attempt for 4 seconds, the 3rd attempts for 6 seconds, ...
api.setReconnectDelay(attempt -> attempt * 2);\n\n\nImportant: Bots can only reconnect 1000 times in a 24-hour period (every ~90 seconds). This limit is global and across all shards.\nUpon hitting this limit, all active sessions for the bot will be terminated, the bot's token will be reset, and\nyou will receive an email notification. This is the reason Javacord increases the reconnect delay with every attempt.
\n
By default, the $default_delay$ formula below is used to calculate the reconnect delay
\n$$\ndefault_delay(a) = \\lfloor a^{1.5} - \\frac{a^{1.5}}{\\frac{1}{(0.1 \\cdot a)} + 1} \\rceil\n$$
\nwith $a$ being the attempt.
\nThe formula will generate the following reconnect delay:
\n| Attempt | \nDelay | \n
|---|---|
| 1 | \n1 | \n
| 2 | \n2 | \n
| 3 | \n4 | \n
| 4 | \n6 | \n
| 5 | \n7 | \n
| ... | \n... | \n
| 10 | \n16 | \n
| 15 | \n23 | \n
| 20 | \n30 | \n
| ... | \n... | \n
| 50 | \n59 | \n
| 100 | \n91 | \n
| 150 | \n115 | \n
| ... | \n... | \n
# Resuming
\nResuming is only possible for a short time after being disconnected. If the bot can successfully resume the connection,\nyou will not miss any events. Your bot will receive all events you missed while being disconnected. The cache gets updated\naccordingly.
\n# Reconnecting
\nIf your bot reconnects (not resumes!), the whole cache gets wiped, and you will not receive any missed events.
\nWhat does this mean?
\n- \n
- References to entities (e.g. a
Server,User,Channel, ...) will be outdated. This is why you should never store\nentities, but the id instead. SeeEntity Cache . \n - You will miss events. There's no way to receive the missed events. \n
- Listeners attached to entities will not be affected, because they are bound to the entity's id, not the object itself. \n
# 💊 How to handle disconnects
\nFor most bots, there's nothing you have to do. All registered listeners are reconnect-resistant, which means if your bot\nis only reacting to events, it will work fine after a restart. For example, the following code will not be affected by a\nreconnect (besides maybe some missed !ping messages):
api.addMessageCreateListener(event -> {\n if (event.getMessage().getContent().equalsIgnoreCase(\"!ping\")) {\n event.getChannel().sendMessage(\"Pong!\");\n }\n});\nIn case you want to handle reconnects (e.g. fetch the message history to detect missed messages), there are\nspecial connection-related listeners which can be used to track the state of the bot:
\n- \n
LostConnectionListener\nReconnectListener\nResumeListener\n
# Entity Cache
\nJavacord keeps an internal cache for entities (e.g. Servers, Channels, Users, ...). It is important to know how the cache behaves to properly use it.
\n# 🔮 What is in the cache?
\nNearly every entity known by the bot is guaranteed to be in the cache. There are a few exceptions though:
\n# Users
\nUsers are only cached when you have the GUILD_MEMBERS intent enabled.\nSee
# Messages
\nNot every single message is in the cache, which means you can encounter messages which exist but are not in the cache. This can happen for most message events, e.g. the ReactionAddEventevent.deleteMessage(), event.editMessage("New Content"). If you need the message (e.g. to get its content), you can request it using event.requestMessage().
Additionally, you can use the static methods in the MessageMessage.edit(api, channelId, messageId, "New content");. This is very useful if you want to store them in a database.
# Webhooks and Invites
\nWebhooks and Invites are not kept in the cache at all and won't receive any updates.
\n# Embeds
\nEmbeds from message.getEmbed() won't receive updates. If a message's embed gets edited, getEmbed() will return a completely new embed object.
# ❓ When are cached entities updated?
\nJavacord's cache exclusively uses websocket events to keep the cache up to date. This means that the content of your objects might be outdated, even though you modified it yourself:
\nMessages message = ...;\nSystem.out.println(message.getContent()); // Prints the old content, e.g. \"old content\"\nmessage.edit(\"new content\").join(); // Edits the message and waits for success\nSystem.out.println(message.getContent()); // Still prints \"old content\"\nThread.sleep(1000);\nSystem.out.println(message.getContent()); // Most likely prints \"new content\" now\n# ⌚ How long are cached entities valid?
\nEven though entities are usually kept in the cache for a very long time, you should not keep references to these objects for a longer period of time, but store the id / use event methods:
\n// Bad\nMessage message = ...;\nmessage.addReactionAddListener(event -> {\n if (event.getEmoji().equalsEmoji(\"👎\")) {\n message.delete(); // Prevents \"message\" from being garbage collected\n }\n});\n\n// Good\nMessage message = ...;\nmessage.addReactionAddListener(event -> {\n if (event.getEmoji().equalsEmoji(\"👎\")) {\n event.deleteMessage(); // Does not use the message object\n }\n});\n// Bad\nSet<User> usersWithBadMood = new HashSet<>();\napi.addReactionAddListener(event -> {\n if (event.getEmoji().equalsEmoji(\"😦\")) {\n usersWithBadMood.add(event.getUser());\n }\n});\n\n// Good\nSet<Long> usersWithBadMood = new HashSet<>();\napi.addReactionAddListener(event -> {\n if (event.getEmoji().equalsEmoji(\"😦\")) {\n usersWithBadMood.add(event.getUser().getId());\n }\n});\nSome examples of when cached entities are invalidated:
\n- \n
- The bot lost its connection to Discord and had to reconnect (not resume) \n
- You weren't able to receive updates for an entity, e.g. for
Channel, because you left and rejoined a server \n
# Performance Tweaks
\n# ✂️ Disabling Startup Wait
\nBy default, Javacord waits for all servers and members to be loaded on startup. You can disable this behavior in the DiscordApiBuilder before logging in:
new DiscordApiBuilder()\n .setToken(\"abc\")\n .setWaitForServersOnStartup(false)\n .login()\n .thenAccept(api -> {\n // Do something\n }).exceptionally(ExceptionLogger.get());\nDepending on the size of your bot, this can significantly speed up the login process. This comes with one downside however: The api.getServers() collection is empty directly after logging in. You will receive ServerBecomesAvailableEvents for every server which finished loading.
# ⚙️ Fine Tuning the Message Cache
\nIn order to reduce memory usage, you can completely disable the message cache or reduce the number of cached messages. By default, Javacord caches up to 50 messages per channel and removes messages from the cache which are older than 12 hours. You can lower this limit by using DiscordApi#setMessageCacheSize(Capacity, StorageTimeInSeconds).
// Cache a maximum of 10 messages per channel for and remove messages older than 1 hour\napi.setMessageCacheSize(10, 60*60);\nYou can even set this limit on a per-channel basis:
\nTextChannel channel = ...;\nchannel.getMessageCache().setCapacity(10);\nchannel.getMessageCache().setStorageTimeInSeconds(60*60);\n# 💎 Using the Updater classes
\nIf you update several settings of an entity (server, channel, ...) at once, you should use the updater for this entity instead of the updateXyz(...) methods.
# Example
\n// Sends 1 request to Discord\nServerTextChannel channel = ...;\nnew ServerTextChannelUpdater(channel)\n .setName(\"example-channel\")\n .setTopic(\"This is an example channel\")\n .setNsfwFlag(true)\n .update();\ninstead of
\n// Sends 3 requests to Discord\nServerTextChannel channel = ...;\nchannel.updateName(\"example-channel\");\nchannel.updateTopic(\"This is an example channel\");\nchannel.updateNsfwFlag(true);\n# Playing Audio
\nWARNING
\nSupport for audio was added to Javacord very recently.\nIf you encounter any bugs, please create an issue on GitHub
Javacord allows your bot to connect to voice channels and play audio (e.g., music).\nThis short tutorial gives you an introduction on how to connect to a voice channel and play your\nfavorite music
# 🔌 Connect to a voice channel
\nConnecting to a voice channel is very straight forward:\nCalling #connect() on an instance of ServerVoiceChannel will connect your bot to this voice channel and\nreturn a AudioConnection object.
# Example
\nThe following example will connect the bot to the voice channel of the user that typed !music in the chat:
ServerVoiceChannel channel = ...;\nchannel.connect().thenAccept(audioConnection -> {\n // Do stuff\n}).exceptionally(e -> {\n // Failed to connect to voice channel (no permissions?)\n e.printStackTrace();\n return null;\n});\n# 👂 Playing music
\nThere are plenty of sources for audio (e.g., YouTube, local files, etc.).\nThe current de facto standard library for extracting audio from these sources with Java is the\nLavaPlayer
To use it with Javacord, you have to add it as a dependency to your project (e.g., with Gradle or Maven) and\ncreate a Javacord audio source like this:
\npublic class LavaplayerAudioSource extends AudioSourceBase {\n\n private final AudioPlayer audioPlayer;\n private AudioFrame lastFrame;\n\n /**\n * Creates a new lavaplayer audio source.\n *\n * @param api A discord api instance.\n * @param audioPlayer An audio player from Lavaplayer.\n */\n public LavaplayerAudioSource(DiscordApi api, AudioPlayer audioPlayer) {\n super(api);\n this.audioPlayer = audioPlayer;\n }\n\n @Override\n public byte[] getNextFrame() {\n if (lastFrame == null) {\n return null;\n }\n return applyTransformers(lastFrame.getData());\n }\n\n @Override\n public boolean hasFinished() {\n return false;\n }\n\n @Override\n public boolean hasNextFrame() {\n lastFrame = audioPlayer.provide();\n return lastFrame != null;\n }\n\n @Override\n public AudioSource copy() {\n return new LavaplayerAudioSource(getApi(), audioPlayer);\n }\n}\nWith this audio source, you can now start using Lavaplayer, e.g. to play a YouTube video:
\n// Create a player manager\nAudioPlayerManager playerManager = new DefaultAudioPlayerManager();\nplayerManager.registerSourceManager(new YoutubeAudioSourceManager());\nAudioPlayer player = playerManager.createPlayer();\n\n// Create an audio source and add it to the audio connection's queue\nAudioSource source = new LavaplayerAudioSource(api, player);\naudioConnection.setAudioSource(source);\n\n// You can now use the AudioPlayer like you would normally do with Lavaplayer, e.g.,\nplayerManager.loadItem(\"https://www.youtube.com/watch?v=NvS351QKFV4\", new AudioLoadResultHandler() {\n @Override\n public void trackLoaded(AudioTrack track) {\n player.playTrack(track);\n }\n\n @Override\n public void playlistLoaded(AudioPlaylist playlist) {\n for (AudioTrack track : playlist.getTracks()) {\n player.playTrack(track);\n }\n }\n\n @Override\n public void noMatches() {\n // Notify the user that we've got nothing\n }\n\n @Override\n public void loadFailed(FriendlyException throwable) {\n // Notify the user that everything exploded\n }\n});\n# Proxies
\nThere are basically two kinds of proxies: HTTP proxies and SOCKS proxies. Both may or may not support or require authentication depending on version, capabilities, and configuration. Due to the underlying libraries used, currently, Javacord fully supports HTTP proxies and partially supports SOCKS proxies.
\nJavacord uses HTTPS connections to communicate with the Discord REST API and a WSS connection to communicate with the Discord WebSocket endpoint. Both these protocols are secure protocols and thus do not honor settings for HTTP connections, only settings for HTTPS connections.
\n# 👨💻 Configuring a Proxy ...
\n# ... using System Properties
\nIf you did not explicitly set a proxy in the DiscordApiBuilder and did not set a system default ProxySelector, the default proxy selector of the JRE is used. This proxy selector honors, amongst others, the relevant standard system properties https.proxyHost, https.proxyPort, socksProxyHost, socksProxyPort, and socksProxyVersion. Use the former two to configure an HTTP proxy, or the latter three to configure a SOCKS proxy, although you will not need socksProxyVersion, as SOCKS4 is currently not supported.
# ... using a System Default Proxy Selector
\nYou can use java.net.ProxySelector.setDefault(ProxySelector) to set a system default proxy selector that replaces the default one. In its implementation, you can dynamically determine which proxy to use for each connection.
# ... using an Explicitly Set Proxy
\nUsing the method DiscordApiBuilder.setProxy(Proxy) you can set a proxy instance directly in the DiscordApiBuilder that is solely used for Javacord connections and does not affect the unrelated code running in the JVM.
# ... using an Explicitly Set Proxy Selector
\nUsing the method DiscordApiBuilder.setProxySelector(ProxySelector) you can set a proxy selector instance directly in the DiscordApiBuilder that is solely used for Javacord connections and does not affect the remaining code running in the JVM. In its implementation, you can dynamically determine which proxy to use for each connection.
# Precedence of the Configuration Options
\n- \n
- if an explicit proxy is set, it is used \n
- if an explicit proxy selector is set, it is used \n
- if both an explicit proxy and an explicit proxy selector are set, this is a configuration error and will cause an exception to be thrown \n
- if neither explicit option is set, the system default proxy selector is used \n
- if no system default proxy selector was explicitly set, the JRE default that honors the system properties is used \n
# 🔑 Configuring Proxy Authentication ...
\n# ... using a System Default Authenticator
\nYou can use java.net.Authenticator.setDefault(Authenticator) to set a system default authenticator that is used to provide username and password pairs for connections. This authenticator is only used if the proxy supports the Basic authentication scheme. If you need to support any other authentication scheme, use an explicitly configured authenticator. The java.net.Authenticator interface is too inflexible to support this.
# ... using an Explicitly Set Authenticator
\nUsing the method DiscordApiBuilder.setProxyAuthenticator(Authenticator), you can set a custom authenticator that is much more powerful than the java.net.Authenticator. You get much more information about the connection to be established, and you can return any HTTP header that is necessary for a successful authentication. This should cover all sorts of available authentication mechanisms.
# 💡 Proxy Types
\n# HTTP
\nHTTP proxies are fully supported.
\n# SOCKS 4
\nSOCKS 4 is currently not supported.
\nThe WebSocket library we use does not support SOCKS proxies at all, and the HTTP library we use has a bug that prevents SOCKS 4 to be used. Additionally, you would need to use at least Java 9 or a separate socket factory supporting SOCKS 4, as the JRE implementation is not working in Java 8 and got fixed only in Java 9+.
\n# SOCKS 4a
\nSOCKS 4a is currently only partially supported.
\nThe WebSocket library we use does not support SOCKS proxies at all, so it could be used for the REST connections only. Additionally, you would need to use a separate socket factory supporting SOCKS 4a, as the JRE implementation is not capable of doing SOCKS 4a, only SOCKS 4 and SOCKS 5 are supported at the time of creation of this wiki article.
\n# SOCKS 5
\nSOCKS 5 is currently only partially supported.
\nThe WebSocket library we use does not support SOCKS proxies at all, so it could be used for the REST connections only.
\n","path":"/wiki/advanced-topics/proxies.html","keywords":["proxy","connection","socks","socks4","socks5"]},{"title":"Ratelimits","headers":[{"level":2,"title":"❗ The Most Important Ratelimits","slug":"the-most-important-ratelimits","children":[]},{"level":2,"title":"💪 Dealing with Ratelimits","slug":"dealing-with-ratelimits","children":[{"level":3,"title":"Example","slug":"example","children":[]}]},{"level":2,"title":"❌ Can I disable ratelimits?","slug":"can-i-disable-ratelimits","children":[]}],"content":"# Ratelimits
\nRatelimits is a Discord restriction which prevents you from performing actions in a very fast rate.\nMost ratelimits are on a per-channel or a per-server basis.
\n# ❗ The Most Important Ratelimits
\n| Action | \nRatelimit | \nType | \n
|---|---|---|
| Send Messages | \n5 / 5s | \nper channel | \n
| Delete Messages | \n5 / 1s | \nper channel | \n
| Add/Remove Reactions | \n1 / 0.25s | \nper channel | \n
| Edit Server Members | \n10 / 10s | \nper server | \n
| Edit Member Nickname | \n1 / 1s | \nper server | \n
| Edit Bot Username | \n2 / 1h | \nper account | \n
| Update Channels | \n2 / 10m | \nper account | \n
| All Actions Combined | \n50 / 1s | \nper account | \n
# 💪 Dealing with Ratelimits
\nUsually Javacord takes care about these limitations for you.\nAs a user, there's nothing you have to do, but you should at least know that ratelimits exist.
\n# Example
\nThe following code
\n// Who even needs loops?\nchannel.sendMessage(\"Ratelimit Example #1\");\nchannel.sendMessage(\"Ratelimit Example #2\");\nchannel.sendMessage(\"Ratelimit Example #3\");\nchannel.sendMessage(\"Ratelimit Example #4\");\nchannel.sendMessage(\"Ratelimit Example #5\");\nchannel.sendMessage(\"Ratelimit Example #6\");\nchannel.sendMessage(\"Ratelimit Example #7\");\nchannel.sendMessage(\"Ratelimit Example #8\");\nchannel.sendMessage(\"Ratelimit Example #9\");\nchannel.sendMessage(\"Ratelimit Example #10\");\nchannel.sendMessage(\"Ratelimit Example #11\");\nchannel.sendMessage(\"Ratelimit Example #12\");\nwould look like this in the client:
\n\n\n\n
![\"\"](\"https://i.imgur.com/ailPCdH.gif\")
You can clearly see the delay between every 5 sent messages.
\n# ❌ Can I disable ratelimits?
\nNo. Ratelimits are a limitation from Discord itself, which you cannot circumvent.
\n","path":"/wiki/advanced-topics/ratelimits.html","keywords":["ratelimits"]},{"title":"Sharding","headers":[{"level":2,"title":"👩🏭 Sharding in Javacord","slug":"sharding-in-javacord","children":[{"level":3,"title":"Logging in with a single shard","slug":"logging-in-with-a-single-shard","children":[]},{"level":3,"title":"Logging in with a fixed amount of shards","slug":"logging-in-with-a-fixed-amount-of-shards","children":[]},{"level":3,"title":"Using the recommended shard amount","slug":"using-the-recommended-shard-amount","children":[]}]},{"level":2,"title":"💡 Behavior of Shards","slug":"behavior-of-shards","children":[{"level":3,"title":"Managed servers","slug":"managed-servers","children":[]},{"level":3,"title":"Private messages","slug":"private-messages","children":[]},{"level":3,"title":"When do I need sharding?","slug":"when-do-i-need-sharding","children":[]}]},{"level":2,"title":"🌄 Sharding for Very Large Bots","slug":"sharding-for-very-large-bots","children":[]}],"content":"# Sharding
\nDiscord allows (and forces) you to "split" larger bots into several independent parts. This behavior is called "sharding", and the independent parts are called "shards". You can think of shards as completely independent bots. Every shard is responsible for a disjoint set of servers.
\n# 👩🏭 Sharding in Javacord
\n# Logging in with a single shard
\nLogging in with a single shard is pretty much the same as logging in without sharding:
\nDiscordApi api = new DiscordApiBuilder()\n .setToken(\"top secret\")\n .setCurrentShard(0)\n .setTotalShards(2)\n .login().join();\nSystem.out.println(\"Shard \" + api.getCurrentShard() + \" logged in!\");\n\n\nNote:
\ncurrent shardstarts counting at0! This means in the example above you would have current shard0and shard1with atotal amountof2shards.
\n\nImportant: There must be a > 5-second delay between each shard-login
\n
# Logging in with a fixed amount of shards
\nYou can manually set a fixed amount of total shards and log in all of them:
\npublic class Main {\n\n public static void main(String[] args) {\n new DiscordApiBuilder()\n .setToken(\"top secret\")\n .setTotalShards(10)\n .loginAllShards()\n .forEach(shardFuture -> shardFuture\n .thenAcceptAsync(Main::onShardLogin)\n .exceptionally(ExceptionLogger.get())\n );\n }\n\n private static void onShardLogin(DiscordApi api) {\n System.out.println(\"Shard \" + api.getCurrentShard() + \" logged in!\");\n // You can treat the shard like a normal bot account, e.g. registering listeners\n api.addMessageCreateListener(event -> {\n // ...\n });\n }\n\n}\nloginAllShards() returns a collection with completable futures (Collection<CompletableFuture<DiscordApi>>). This method automatically obeys the > 5-second delay rule.
# Using the recommended shard amount
\nYou can "ask" Discord to recommend you a total amount of shards. This is done by using the DiscordApiBuilder#setRecommendedTotalShards() method, which returns a CompletableFuture<DiscordApiBuilder> after getting the required information.
public class Main {\n\n public static void main(String[] args) {\n new DiscordApiBuilder()\n .setToken(\"top secret\")\n .setRecommendedTotalShards().join()\n .loginAllShards()\n .forEach(shardFuture -> shardFuture\n .thenAccept(Main::onShardLogin)\n .exceptionally(ExceptionLogger.get())\n );\n }\n\n private static void onShardLogin(DiscordApi api) {\n // ...\n }\n\n}\n# 💡 Behavior of Shards
\n# Managed servers
\nYou can calculate for which servers a shard is responsible using the server id:
\nboolean isResponsible = (serverId >> 22) % totalShards == currentShard;\n# Private messages
\nPrivate messages are always sent to the first shard (currentShard == 0).
# When do I need sharding?
\nSharding is forced for bots which are in more than 2500 servers.
\n# 🌄 Sharding for Very Large Bots
\nSharding for very large bots (> 150,000 servers) is a bit different from "normal" sharding. Discord will contact you once your bot reaches this state. Additional information can be found in the official Discord api documentation
# Creating Channels, Invites, etc.
\nJavacord provides XyzBuilder classes to create new Discord entities like channels, webhooks, servers, and many more.
# 📕 Create Channels
\nYou can get the channel builders for a specific server using the Server#createXyzChannelBuilder or by directly calling the constructor.\nCreating a ServerVoiceChannel would look like this:
Server server = ...;\nServerVoiceChannel channel = new ServerVoiceChannelBuilder(server)\n .setName(\"example-channel\")\n .setUserlimit(10)\n .create().join();\n# 📗 Create Webhooks
\nYou can get the WebhookBuilder for a specific text channel:
ServerTextChannel channel = ...;\nWebhook webhook = new WebhookBuilder(channel)\n .setName(\"Captain Hook\")\n .setAvatar(new File(\"C:/Users/Bastian/Pictures/puppy.jpg\"))\n .create().join();\n# 📘 Create Invites
\nYou can get the InviteBuilder for a specific server channel:
ServerTextChannel channel = ...;\nInvite invite = new InviteBuilder(channel)\n .setMaxAgeInSeconds(60*60*24)\n .setMaxUses(42)\n .create().join();\n# 📙 Create Servers
\nYou can get the ServerBuilder from the current api instance:
DiscordApi api = ...;\nlong serverId = new ServerBuilder(api)\n .setName(\"My Awesome Server\")\n .setIcon(api.getYourself().getAvatar())\n .setVerificationLevel(VerificationLevel.HIGH)\n .setDefaultMessageNotificationLevel(DefaultMessageNotificationLevel.ONLY_MENTIONS)\n .setRegion(Region.EU_CENTRAL)\n .create().join();\nWARNING
\nBy default, bots can only create servers if they are in less than 10 servers. You can contact the Discord support to request a higher limit.
\n# Embeds
\nEmbeds are attached to messages and have a special design.\nThe usually look like this:
\n![\"Embed\"](\"https://i.imgur.com/QYbXmQU.png\")
# 🔨 Creating an Embed
\nJavacord provides an EmbedBuilder which can be used to create embeds:
// Create the embed\nEmbedBuilder embed = new EmbedBuilder()\n .setTitle(\"Title\")\n .setDescription(\"Description\")\n .setAuthor(\"Author Name\", \"http://google.com/\", \"https://cdn.discordapp.com/embed/avatars/0.png\")\n .addField(\"A field\", \"Some text inside the field\")\n .addInlineField(\"An inline field\", \"More text\")\n .addInlineField(\"Another inline field\", \"Even more text\")\n .setColor(Color.BLUE)\n .setFooter(\"Footer\", \"https://cdn.discordapp.com/embed/avatars/1.png\")\n .setImage(new File(\"C:/Users/Bastian/Pictures/puppy.jpg\"))\n .setThumbnail(new File(\"C:/Users/Bastian/Pictures/kitten2.png\"));\n// Send the embed\nchannel.sendMessage(embed);\n# 📷 Supported Image Sources
\nBy default, Discord expects embed images to be a link (e.g., the image link used in setFooter(...)), but you can also use attachments for images.\nIf you provide a non-url image source (e.g. the puppy.jpg file used in setImage(...)), Javacord automatically uploads them as an attachment to the message and uses this attachment for the embed.
# 🔒 Embed Limits
\n| Type | \nLimit | \n
|---|---|
| Title | \n256 characters | \n
| Description | \n4096 characters | \n
| Field Amount | \nUp to 25 fields | \n
| Field Name | \n256 characters | \n
| Field Value | \n1024 characters | \n
| Footer Text | \n2048 characters | \n
| Author Name | \n256 characters | \n
In addition to the limits above, the sum of all characters in an embed structure must not exceed 6000 characters.
\n# ❓ FAQ
\n# What is the second parameter of setAuthor(...)?
\n.setAuthor(\"Author Name\", \"http://google.com/\", \"https://cdn.discordapp.com/embed/avatars/0.png\")\n- \n
- First parameter: The name of the author \n
- Second parameter: A link for the author (e.g. their homepage). Can be
null. \n - Third parameter: The avatar of the author \n
\n\n\n
![\"\"](\"https://i.imgur.com/SyE0e88.png\")
# What's the difference between an inline field and a normal one?
\nNormal fields always start in a new line, whereas several inline fields can be in the same line.
\n# Can I change the placement of inline fields?
\nNo, Discord does not allow different embed layouts.
\n# How can I format text in an embed?
\nDiscord allows for a subset of markdown to be used. See their docs
# Emojis and Reactions
\nThere are two different kinds of emojis in Discord: Unicode emojis and custom emojis.
\n# 🚴♂️ Unicode Emojis
\n# What are Unicode emojis?
\nUnicode emojis are "normal" text emojis which are supported by (nearly) all chat clients, including Discord. You can find a list with all Unicode emojis here: Full Emoji List
# How to use them in messages
\nYou can either directly add them in your code, e.g.
\nchannel.sendMessage(\"Hi! 😃\");\nor use the normal "tag" like you would in the Client:
\nchannel.sendMessage(\"Hi! :smiley:\");\n![\"\"](\"https://i.imgur.com/VBiTPq5.png\")
# How to use them for reactions
\nAdding unicode reactions is only possible by using the "real" reaction. It doesn't support tags like :smiley:.
message.addReaction(\"😃\"); // works\nmessage.addReaction(\":smiley:\"); // doesn't work\n![\"\"](\"https://i.imgur.com/Wpp8PNz.png\")
# 🤸♀️ Custom Emojis
\n# What are custom emojis?
\nCustom emojis are emojis that are created in a server. You can get all custom emojis the bot knows by using DiscordApi#getCustomEmojis().
![\"\"](\"https://i.imgur.com/5tb3Kxu.png\")
# How to use them in messages
\nTo use custom emojis, you have to know its "tag", which has the format <:name:id>. You can get it by calling CustomEmoji#getMentionTag():
channel.sendMessage(\"Hi! <:javacord:415465982715494402>\");\nCustomEmoji emoji = ...;\nchannel.sendMessage(\"Hi! \" + emoji.getMentionTag());\n# How to use them for reactions
\nYou can either directly use the custom emoji object or use the tag without the <: > if you don't have access a custom emoji object (e.g., because it's from a different shard):
CustomEmoji emoji = ...;\nmessage.addReaction(emoji);\nmessage.addReaction(\"javacord:415465982715494402\");\n# How to get the tag
\nJust add a \\ in front of the emoji and press Enter
![\"\"](\"https://i.imgur.com/9L1WyFm.gif\")
![\"\"](\"https://i.imgur.com/4WTGo7F.png\")
# 👑 Javacord Emoji "Hierarchy"
\nIn Javacord, all Emojis are a child of the Emoji interface:
![\"\"](\"https://i.imgur.com/YtMKqXe.png\")
# What is a KnownCustomEmoji?
\nKnown custom emojis are emojis that the bot knows because it's a member of the server with this emoji. A custom emoji can be unknown if someone adds a reaction with an unknown emoji for example. A KnownCustomEmoji has additional methods like getServer() or updateName(String).
# 👌 Recommended libraries
\nIf you are working a lot with Unicode emojis, it's recommended to use a library like JEmoji
message.addReaction(EmojiManager.getByAlias(\":thumbsup:\"));\n# Gateway Intents
\nDiscord allows you to "subscribe" to specific groups of events.\nThese "subscriptions" are called intent.\nDisabling intents that are not required for your bot can significantly increase your bot's performance.
\n# 📋 List of Intents
\nBelow you can find a table with all intents supported by Discord.
\n| Intent | \nSafe to Disable | \nPrivileged | \n
|---|---|---|
GUILDS | \n❌ | \n❌ | \n
GUILD_MEMBERS | \n✔️ | \n✔️ | \n
GUILD_BANS | \n⚠️* | \n❌ | \n
GUILD_EMOJIS | \n⚠️* | \n❌ | \n
GUILD_INTEGRATIONS | \n✔️ | \n❌ | \n
GUILD_WEBHOOKS | \n✔️ | \n❌ | \n
GUILD_INVITES | \n✔️ | \n❌ | \n
GUILD_VOICE_STATES | \n⚠️* | \n❌ | \n
GUILD_PRESENCES | \n✔️ | \n✔️ | \n
GUILD_MESSAGES | \n✔️ | \n❌ | \n
GUILD_MESSAGE_REACTIONS | \n✔️ | \n❌ | \n
GUILD_MESSAGE_TYPING | \n✔️ | \n❌ | \n
DIRECT_MESSAGES | \n✔️ | \n❌ | \n
DIRECT_MESSAGE_REACTIONS | \n✔️ | \n❌ | \n
DIRECT_MESSAGE_TYPING | \n✔️ | \n❌ | \n
MESSAGE_CONTENT | \n✔️ | \n✔️ | \n
AUTO_MODERATION_CONFIGURATION | \n✔️ | \n❌ | \n
AUTO_MODERATION_EXECUTION | \n✔️ | \n❌ | \n
* Will most likely work, but needs further testing
\nGood to know!
\nGuild is a synonym for servers, commonly used in Discord's API.\nSee
# 💡 What Happens When I Disable Some Intents?
\nWhen you disable some of the listed intents, Javacord will not fire events that belong to the intents and\nwill not update these specific parts of the cache.
\nAt the moment, we don't have a list which events are affected by which intents (but it will come soon™️).\nHowever, most intents should be self-explanatory.\nE.g. when you disable the DIRECT_MESSAGES intent, your bot will not receive any private messages.
# 👑 Privileged Intents
\nSome intents are defined as "privileged" due to the sensitive nature of the data.\nTo use these intents, you have to go to your bot in the Developer Portal
![\"\"](\"@source/wiki/basic-tutorials/enable_privileged_intents.png\")
There are some additionally restrictions for bots that are in over 100 servers:
\n- \n
- Your bot must be verified \n
- Your bot must be whitelisted to use this intents \n
Take a look at the official article from Discord about this topic and how to verify your bot:\nBot Verification and Data Whitelisting
# ❗ Notable Intents
\nThe following two intents are especially noteworthy: GUILD_MEMBERS and GUILD_PRESENCES.\nBesides being privileged, they have some special implications for Javacord:
# GUILD_PRESENCES
\nThis intent is required to get updates about a user's status (i.e., if they are online, what game they are playing, ...).\nAdditionally, without this intent it might take considerably longer to cache all users because of ratelimits\n(up to 10 minutes for shards with 1000 servers).\nIt is advised against setting DiscordApiBuilder#setWaitForAllUsersOnStartup(true) without this intent, unless absolutely necessary.
# GUILD_MEMBERS
\nThis intent is required to keep all users in Javacord's cache.\nWithout this intent, methods like Server#getMembers() or DiscordApi#getCachedUsers() will return empty collections.\nHowever, you will still be able to access users from objects like messages, e.g. Message#getUserAuthor() will still work.
# MESSAGE_CONTENT
\nThis intent is a bit different to the other as it does not act as a toggle to receive any events.\nIt's sole purpose is to receive the message content, attachments, components, and embeds.\nOtherwise, these fields will be empty when you receive a Message object.
# ⚙️ Setting Intents
\nJavacord allows you to specify intents in the DiscordApiBuilder prior to login.\nThere are many options to set intents.\nThe following example code shows the most common ones:
# Set All Non-Privileged Intents (Default)
\nThis method enables all non-privileged intents.\nThis is the default setting in Javacord.
\nDiscordApi api = new DiscordApiBuilder()\n .setToken(\"topc secret\")\n .setAllNonPrivilegedIntents()\n .login()\n .join();\n# Set All Non-Privileged Intents Except
\nThis method enabled all non-privileged intents, except the given ones.
\nDiscordApi api = new DiscordApiBuilder()\n .setToken(\"topc secret\")\n .setAllNonPrivilegedIntentsExcept(Intent.GUILD_WEBHOOKS)\n .login()\n .join();\n# Set All Intents
\nThis method enabled all intents.
\nDiscordApi api = new DiscordApiBuilder()\n .setToken(\"topc secret\")\n .setAllIntents()\n .login()\n .join();\n# Set All Intents Except
\nThis method enabled all intents, except the given ones.
\nDiscordApi api = new DiscordApiBuilder()\n .setToken(\"topc secret\")\n .setAllIntentsExcept(Intent.GUILD_PRESENCES, Intent.GUILD_WEBHOOKS)\n .login()\n .join();\n# Set Intents
\nThis method only enables the given intents.
\nDiscordApi api = new DiscordApiBuilder()\n .setToken(\"topc secret\")\n .setIntents(Intent.GUILDS, Intent.DIRECT_MESSAGES)\n .login()\n .join();\n# Add Intents
\nThis method adds the intents to the currently enabled ones(by default all non-privileged).\nThis is useful i.e. if you only want to enable 1 privileged intent like the MESSAGE_CONTENT
DiscordApi api = new DiscordApiBuilder()\n .setToken(\"topc secret\")\n .addIntents(Intent.MESSAGE_CONTENT)\n .login()\n .join();\n# Glossary
\nThis is a list with the most common Discord-related terms:
\n- \n
Guild- A synonym forserver\nSelfbot- A client account bot, usually logged in to a user's own account \nSharding- Splitting a bot into several independentshards, seeSharding \nToken- Used to login instead of requiring a username + password \nEmbed- A "fancy" message, seeEmbed FAQ \nRatelimit- Prevents you from spamming actions, seeRatelimit FAQ \nWebsocket- A TCP"connection" to Discord that receives events, see Wikipedia \nGateway- The address for thewebsocket\nRest/Rest Request- RESTis used to perform actions like sending messages. Rest Requests do not require an active websocket connection. \nActivity- The text underneath the username, usuallyPlaying Xyz\nRich Presence- A more detailed activity, see Discord Docs \n
# Listeners
\n# 👨🔧 Creating listeners
\nCreating listeners is extremely easy in Javacord.\nYou can either use Java 8's lambda expressions to register listeners inline or just create a new class for them, if an inline listener would get too messy.
\n# Inline Listeners
\napi.addMessageCreateListener(event -> {\n if (event.getMessageContent().equalsIgnoreCase(\"!ping\")) {\n event.getChannel().sendMessage(\"Pong!\");\n }\n});\n# In their own class
\napi.addListener(new MyListener());\nand
\npublic class MyListener implements MessageCreateListener {\n\n @Override\n public void onMessageCreate(MessageCreateEvent event) {\n if (event.getMessageContent().equalsIgnoreCase(\"!ping\")) {\n event.getChannel().sendMessage(\"Pong!\");\n }\n }\n\n}\n# Before logging in
\nSometimes it might be useful to add listeners before calling the DiscordApiBuilder#login() method.
DiscordApi api = new DiscordApiBuilder()\n // An inline listener\n .addMessageCreateListener(event -> {\n Message message = event.getMessage();\n if (message.getContent().equalsIgnoreCase(\"!ping\")) {\n event.getChannel().sendMessage(\"Pong!\");\n }\n })\n .addServerBecomesAvailableListener(event -> {\n System.out.println(\"Loaded \" + event.getServer().getName());\n })\n // A listener in their own class\n .addListener(new MyListener())\n // Alternative syntax that can be used for classes that require a DiscordApi parameter in their constructor\n .addListener(MyListener::new)\n .setToken(\"top secret\")\n .setWaitForServersOnStartup(false)\n .login()\n .join();\n\n\nNote: In most cases, it's enough to add listeners after logging in
\n
# Object listeners
\nAnother cool feature is the ability to attach listeners directly to objects. An example where this can be useful is, for example, reacting to reactions. The following code would delete the message if someone adds a 👎 reaction.
\nmessage.addReactionAddListener(event -> {\n if (event.getEmoji().equalsEmoji(\"👎\")) {\n event.deleteMessage();\n }\n}).removeAfter(30, TimeUnit.MINUTES);\n\n\nSeems like the bot is very sensitive to criticism.
\n
# 💣 Removing listeners
\nThere are two ways to remove a listener:
\n# Using the returned ListenerManager
\nEvery time you register a listener, a ListenerManager is returned which can be used to unregister the listener:
ListenerManager<MessageCreateListener> listenerManager = api.addMessageCreateListener(event -> {\n // Do stuff\n});\n\nlistenerManager.remove();\nThis manager also has some utility methods. You can, for example, remove a listener after a given time, which can be useful for object listeners:
\nmessage.addReactionAddListener(event -> {\n // Do stuff\n}).removeAfter(30, TimeUnit.MINUTES);\n# Using the removeListener(...) method
\nYou can remove any listener using the removeListener(...) method:
MyListener listener = new MyListener();\napi.addListener(listener);\n// ...\napi.removeListener(listener);\n# Logger Configuration
\nLogging is an important tool to keep track of what is going on in your application. Javacord uses the Log4j 2 API
\nIf you want more control, add a proper logging framework that supports your needs and configure it accordingly. You can for example configure log messages on a per-class level, change log levels during runtime, or log to a file or database.
# 🥈 Fallback Logger
\nJavacord's fallback logger is a simple Log4j logger which always logs INFO level and higher. It allows you to enable DEBUG and TRACE logging manually. As log levels are hierarchical, enabling TRACE will also implicitly enable DEBUG, and disabling DEBUG will also implicitly disable TRACE.
// Enable debug logging\nFallbackLoggerConfiguration.setDebug(true);\n\n// Enable trace logging\nFallbackLoggerConfiguration.setTrace(true);\nChanging the log level of the fallback logger only affects newly created loggers. Pre-existing loggers will not have their log level changed. So if you want to configure the fallback logger, you should do this as one of the first actions in your bot code. If you want to change log levels during runtime, you should use a proper logging framework like Log4j 2 Core or another library that supports this.
\nAll fallback logger messages are printed to the standard output stream (System.out) and thus usually to your console. If you want to log to a file, database, or anything else, you should consider using a proper logging framework which allows you to configure this behavior.
This is how a log line from the fallback logger will look like:
\n<time with date ><level><logger name, usually the logging class > <message > <the thread context, here the shard number>\n2018-08-03 20:00:06.080+0200 DEBUG org.javacord.core.util.gateway.DiscordWebSocketAdapter Received HELLO packet {shard=0}\n# 🥇 Using a Proper Logging Framework
\n# Adding a Logging Framework
\nAdding a logging framework of your choice is very straightforward. You can just add it as a dependency, and it will be detected by Log4j automatically. The following example adds Log4j 2 using Gradle:
\ndependencies { runtimeOnly 'org.apache.logging.log4j:log4j-core:2.17.0' }\nYou can also use an SLF4J compatible logging framework using log4j-to-slf4j. The following example adds Logback Classic using Gradle:
dependencies {\n runtimeOnly 'org.apache.logging.log4j:log4j-to-slf4j:2.17.0'\n runtimeOnly 'ch.qos.logback:logback-classic:1.2.3'\n}\n# Configure Your Logging Framework
\n- \n
- Log4j 2: Log4j configuration
- Logback Classic: Logback configuration
# Logging the Relevant Shard
\nJavacord adds the relevant shard to each log message. The facility that stores this information has a different name depending on which logging framework you use. For Log4j 2, this is called Thread Context Map and can be added in a pattern layout with %X{shard}, or you can add the whole thread context map by using %X. For Logback Classic, it is called MDC and can be added with the same pattern expressions as for Log4j.
# Using the MessageBuilder
\nThe MessageBuilder class is a more powerful alternative to the TextChannel#sendMessage(...) method.
It can be used to construct more complex messages and supports some additional features that are not possible\nwith a simple TextChannel#sendMessage(...) call.
# 🕵️♀️ Example
\nThe following code
\nnew MessageBuilder()\n .append(\"Look at these \")\n .append(\"awesome\", MessageDecoration.BOLD, MessageDecoration.UNDERLINE)\n .append(\" animal pictures! 😃\")\n .appendCode(\"java\", \"System.out.println(\\\"Sweet!\\\");\")\n .addAttachment(new File(\"C:/Users/Bastian/Pictures/kitten.jpg\"))\n .addAttachment(new File(\"C:/Users/Bastian/Pictures/puppy.jpg\"))\n .setEmbed(new EmbedBuilder()\n .setTitle(\"WOW\")\n .setDescription(\"Really cool pictures!\")\n .setColor(Color.ORANGE))\n .send(channel);\nwill be displayed like this:
\n![\"\"](\"https://i.imgur.com/AP1cjDf.png\")
# 📍 Allowed Mentions
\nThe allowed mentions object lets you control what should be mentioned (pinged) in a message if it contains mentions.
\nThe following code will ping:
\n- \n
- The user0 \n
- All mentioned roles in the message \n
And will not ping:
\n- \n
- @everyone and @here \n
- The user1 \n
AllowedMentions allowedMentions = new AllowedMentionsBuilder()\n .addUser(user0.getId())\n .setMentionRoles(true)\n .setMentionEveryoneAndHere(false)\n .build();\n\n new MessageBuilder()\n .setAllowedMentions(allowedMentions)\n .append(user0.getMentionTag())\n .append(user1.getMentionTag())\n .append(role.getMentionTag())\n .append(role2.getMentionTag())\n .append(\"@everyone\")\n .send(channel);\nIf you add a user to the mentions object and set setMentionUsers(true) it will ping every mentioned user. The same applies for setMentionRoles(true)
# Running and Deploying your Bot
\nIf you took the time to write a bot, at some point you'll also want to run it, either for use in production or for debugging from the IDE.
\n# 👷 Running from your IDE
\nWhile developing your bot, you will want to run your bot directly from the IDE in order to quickly test changes and new features. For this, create a Run/Debug Configuration in your IDE of choice with your bot's main class. Remember to also add any necessary parameters and environment variables.
\nA working Run/Debug configuration will also enable you to run your bot with a debugger. A debugger is often considered a developer's most important tool, so make sure to familiarize yourself with the debugging integration for your IDE of choice.
\n# IntelliJ IDEA
\nThis assumes your project is set up correctly, preferably with Gradle, can be built without errors, and does not yet have any run/debug configurations.
\n1. Locate and click the Add Configuration... button in the top bar next to the start button.
![\"\"](\"@source/wiki/basic-tutorials/running-idea-configurations-empty.png\"){kind=spacer}
2. In the newly opened window, click the + button in the top left and select Application
3. Give a name for your configuration and select the module to use the classpath of (usually yourproject.main).
4. Select your Main class. Use the ... button to search for it or provide the fully qualified name. If it can not be found, you most likely selected the wrong module in step 3.
5. Optional: Set command line arguments and environment variables. For the environment variables, use the button to the right of the input field for a more convenient input window.
\n6. Click Apply to finalize the configuration, then OK to close the window.
![\"\"](\"@source/wiki/basic-tutorials/running-idea-configurations-create.png\")
7. Select your configuration in the drop-down menu and run or debug it with the buttons to the right.
\n![\"\"](\"@source/wiki/basic-tutorials/running-idea-configurations-bar.png\")
# Eclipse
\nThis assumes your project is set up correctly, can be built without errors, and does not yet have any run/debug configurations.
\n1. In the menu bar, click "Run" then "Run Configurations...".
\n2. In the newly opened window, select "Java Application" on the left side, then click the leftmost button in the row above the tree view. A new configuration will appear.
\n![\"\"](\"@source/wiki/basic-tutorials/running-eclipse-configurations-empty.png\"){kind=spacer}
3. Give a name to your configuration.
\n4. Set the project and the main class. To easily select it, use the "Browse..." and "Search..." buttons.
\n5. Optional: Set command line (and VM) arguments as well as environment variables in their respective tabs.
\n6. Click Apply to save your configuration, then Close to close the window.
![\"\"](\"@source/wiki/basic-tutorials/running-eclipse-configurations-create.png\")
7. Run or debug your bot via the Buttons in the top row, the Run menu, or the shortcuts Ctrl+F11 for running and F11 for debugging.
![\"\"](\"@source/wiki/basic-tutorials/running-eclipse-configurations-bar.png\")
# 📦 Deploying and Running as a Standalone Application
\nRunning from the IDE is only recommended during development and strongly discouraged for production use. Generally, you'll want your build tool to create a convenient distribution format for you to use.
\n# Building a Distribution with Gradle
\nFor Gradle, only two further steps are necessary for a basic application. On top of the steps described in the Getting Started Section, also add the Application PluginmainClass as the fully qualified name of your main class. If you're using an older version of Gradle (earlier than 6.4), the attribute is instead called mainClassName.
INFO
\nAs with many Gradle solutions, there is actually a whole lot going on under the hood. The application plugin implicitly also applies the java and distribution plugins. Refer to the documentations of the involved plugins for more ways to fine-tune the process.
Your modified build file should now look similar to this:
\nplugins {\n application\n}\n \nversion = \"1.0.0\"\n \njava {\n sourceCompatibility = JavaVersion.VERSION_1_8\n}\n \napplication {\n mainClass.set(\"com.github.yourname.BotMain\")\n // mainClassName.set(\"com.github.yourname.BotMain\") // Gradle < 6.4\n}\n \nrepositories {\n mavenCentral()\n}\n \ndependencies {\n implementation(\"org.javacord:javacord:{{latestVersion}}\")\n}\nplugins {\n id 'application'\n}\n \nversion '1.0.0'\n \njava {\n sourceCompatibility = JavaVersion.VERSION_1_8\n}\n \napplication {\n mainClass = 'com.github.yourname.BotMain'\n // mainClassName = 'com.github.yourname.BotMain' // for Gradle versions < 6.4\n}\n \nrepositories {\n mavenCentral()\n}\n \ndependencies {\n implementation 'org.javacord:javacord:{{latestVersion}}'\n}\nNow you can execute the distZip or distTar task with Gradle. The task will create a distribution and package it in an archive file that will be placed in the build/distributions directory. Extract the content of those files on your server or whichever machine you want to run your bot on.
The distribution usually only contains the directories bin and lib. From the distribution directory, run either bin/yourbot or bin/yourbot.bat, depending on whether you're running the bot on Linux / macOS or windows.
# Building a Distribution with Maven
\nFor Maven, add the Appassemblerpom.xml. The plugin will create a distribution, but not bundle it in a neat archive file, so we'll also add the assembly plugin. We'll bind both to the package lifecycle phase.
<project>\n ...\n <build>\n <plugins>\n <plugin>\n <groupId>org.codehaus.mojo</groupId>\n <artifactId>appassembler-maven-plugin</artifactId>\n <version>1.10</version>\n <configuration>\n <programs>\n <program>\n <mainClass>org.javacord.examplebot.Main</mainClass>\n <id>examplebot</id>\n </program>\n </programs>\n </configuration>\n <executions>\n <execution>\n <id>create-distribution</id>\n <phase>package</phase>\n <goals>\n <goal>assemble</goal>\n </goals>\n </execution>\n </executions>\n </plugin>\n <plugin>\n <artifactId>maven-assembly-plugin</artifactId>\n <version>3.3.0</version>\n <configuration>\n <descriptors>\n <!-- This must match the location of the descriptor -->\n <descriptor>src/assembly/distribution.xml</descriptor>\n </descriptors>\n </configuration>\n <executions>\n <execution>\n <id>create-archive</id>\n <phase>package</phase>\n <goals>\n <goal>single</goal>\n </goals>\n </execution>\n </executions>\n </plugin>\n </plugins>\n </build>\n</project>\nSadly, none of the built-in assembly descriptors match our use case, so we'll put our custom one into src/assembly/distribution.xml:
<assembly xmlns=\"http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n xsi:schemaLocation=\"http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd\">\n <id>distribution</id>\n <formats>\n <!-- See https://maven.apache.org/plugins/maven-assembly-plugin/assembly.html for supported formats -->\n <format>tar.gz</format>\n <format>tar.bz2</format>\n <format>zip</format>\n </formats>\n <fileSets>\n <fileSet>\n <!-- This will also include your project readme, license and similar files-->\n <directory>${project.basedir}</directory>\n <outputDirectory>/</outputDirectory>\n <includes>\n <include>README*</include>\n <include>LICENSE*</include>\n <include>NOTICE*</include>\n </includes>\n </fileSet>\n <fileSet>\n <!-- Change this if you reconfigured the appassembler output directory -->\n <directory>${project.build.directory}/appassembler</directory>\n <outputDirectory>/</outputDirectory>\n </fileSet>\n </fileSets>\n</assembly>\nNow when you execute mvn package, a distribution with start scripts for Windows and Linux/macOS will be generated which is then packaged into archive files for every format you specified in the assembly descriptor. You can find the raw distribution (without readme and license files) in target/appassembler and the archive files directly in target.
# Running
\nAfter creating your distribution via Gradle or Maven and extracting/copying it to the machine you want to run it from, you should have a directory containing both a bin and a lib (or repo) directory. Depending on your platform, you can now run the bin/yourbot or bin/yourbot.bat script.
These automatically generated scripts will then invoke java with your dependencies on the classpath and run your main class. Your working directory will be the directory you ran the script from.
\n# 💩 Building a Fat Jar
\nAlthough it is an abuse of the way java works, sometimes you will be forced to create a fat jar, or an uber jar. This is a jar file that contains your application and all its dependencies. This is sometimes used as a lazy way of building a convenient distribution, but should be foregone in favor of the above mentioned distributions.
\nHowever, in some cases (more often than not Bukkit/Spigot addons) it is necessary to provide a fat jar, since the host application's loading mechanism can only handle singular jar files. If you are subject to such a case of bad design, please complain to the maintainer of whatever host application you are using, then use the following instructions to forsake all that is good and just and create a fat jar. Remember to grit your teeth the whole time.
\n# With Gradle
\nFor Gradle, use the shadow
plugins {\n id 'java'\n # ...\n id 'com.github.johnrengelman.shadow' version '7.1.2'\n}\nWith gradlew shadowJar you can now create a shaded (fat) jar. It will be named build/libs/yourbot-1.0.0-all.jar or similar, according to your project settings.
# With Maven
\nFor Maven, add the maven-shade-plugin
Some of your dependencies might be signed .jar files. Unfortunately, this will likely break your fat jar. Remove the signatures by defining an exclusion filter as demonstrated below. Let the thought that you had to disable a security feature just to make this work serve as a reminder that creating a fat jar is not how jars are meant to be used.
\n<project>\n ...\n <build>\n <plugins>\n <plugin>\n <groupId>org.apache.maven.plugins</groupId>\n <artifactId>maven-shade-plugin</artifactId>\n <version>3.2.3</version>\n <configuration>\n <shadedArtifactAttached>true</shadedArtifactAttached>\n <shadedClassifierName>fat</shadedClassifierName>\n <transformers>\n <transformer implementation=\"org.apache.maven.plugins.shade.resource.ManifestResourceTransformer\">\n <manifestEntries>\n <Main-Class>com.github.yourname.BotMain</Main-Class>\n </manifestEntries>\n </transformer>\n </transformers>\n <filters>\n <filter>\n <artifact>*:*</artifact>\n <excludes>\n <exclude>META-INF/*.SF</exclude>\n <exclude>META-INF/*.DSA</exclude>\n <exclude>META-INF/*.RSA</exclude>\n </excludes>\n </filter>\n </filters>\n </configuration>\n <executions>\n <execution>\n <phase>package</phase>\n <goals>\n <goal>shade</goal>\n </goals>\n </execution>\n </executions>\n </plugin>\n </plugins>\n </build>\n</project>\nRunning mvn package will now additionally create the yourbot-1.0.0-fat.jar.
# Completable Futures
\nWARNING
\nThis tutorial assumes that you are familiar with lambda expressions.\nTake a look at the
As Javacord is heavily multithreaded, you must understand the concept of\nFutures
# 🤔 What the heck is a future?
\nA future is basically a wrapper, that will contain a value in the future but might not contain it right now.\nThis is useful, if a method call requires some time and should not block the execution of your current code.\nYou can easily see the difference with a primitive speed comparison:
\nlong currentTime = System.currentTimeMillis();\nchannel.sendMessage(\"Test 1\");\nchannel.sendMessage(\"Test 2\");\nchannel.sendMessage(\"Test 3\");\nchannel.sendMessage(\"Test 4\");\nchannel.sendMessage(\"Test 5\");\n// Prints \"4 ms\"\nSystem.out.println((System.currentTimeMillis() - currentTime) + \" ms\");\nlong currentTime = System.currentTimeMillis();\nchannel.sendMessage(\"Test 1\").join();\nchannel.sendMessage(\"Test 2\").join();\nchannel.sendMessage(\"Test 3\").join();\nchannel.sendMessage(\"Test 4\").join();\nchannel.sendMessage(\"Test 5\").join();\n// Prints \"894 ms\"\nSystem.out.println((System.currentTimeMillis() - currentTime) + \" ms\");\nTIP
\njoin() blocks the current thread until the method finished. This will be explained later.
# 📖 Methods
\n# join()
\nThe join method blocks the current thread until the method finished.\nIt returns the method's result or throws a CompletionException if anything failed.
The following example would create a new text channel in a given server and sends a message directly afterwards.
// Create the channel\nServerTextChannel channel = new ServerTextChannelBuilder(server)\n .setName(\"new-channel\")\n .create()\n .join();\n// Send a message in the new channel\nMessage message = channel.sendMessage(\"First!\").join();\n// Adds an reaction to the message. Even though this method doesn't return anything,\n// join() ensures, that an exception is thrown in case something went wrong\nmessage.addReaction(\"👍\").join();\nDANGER
\nYou should avoid join() for methods which will be called frequently.
TIP
\nWhile join() can become a performance issue when you call it very frequently, it is very convenient to use and easy to understand.\nIf you are new to programming and just want to get your first bot working, this is a good method to start with.
Once you gathered more experience, we highly advise against using join as it negatively impacts your bot's performance!
# thenAccept(...)
\nThe thenAccept method accepts a Consumer, that consumes the result of the method and is executed asynchronously.\nIt is the method you usually want to use most of the time.
The following example would create a new text channel in a given server and send a message directly afterwards.
new ServerTextChannelBuilder(server)\n .setName(\"new-channel\")\n .create()\n .thenAccept(channel -> {\n channel.sendMessage(\"First!\").thenAccept(message -> {\n message.addReaction(\"👍\");\n });\n });\nDANGER
\nThe example code above has a major problem: Any exception that might occur will be completely ignored.\nThis makes it very hard to find bugs.
\nFor example, if your bot doesn't have the permissions to create a new channel, it will just fail silently.
\n# exceptionally(...)
\nThe exceptionally method accepts a Function as parameter, which consumes possible exceptions and returns a fallback value.
The following example would create a new text channel in a given server and send a message directly afterwards.\nIf something fails (e.g., if the bot isn't allowed to create a text channel in the server), it will log an exception.
new ServerTextChannelBuilder(server)\n .setName(\"new-channel\")\n .create()\n .thenAccept(channel -> {\n channel.sendMessage(\"First!\").thenAccept(message -> {\n message.addReaction(\"👍\").exceptionally(e -> {\n e.printStackTrace(); // Adding the reaction failed\n return null;\n });\n }).exceptionally(e -> {\n e.printStackTrace(); // Message sending failed\n return null;\n });\n }).exceptionally(e -> {\n e.printStackTrace(); // Channel creation failed \n return null;\n });\nWow! This looks ugly 🤮.\nBut worry not! There are many options to improve this code!
\nTo make things simpler for you, Javacord has the ExceptionLogger class, which can be used here.\nIt logs every exception you didn't catch manually.
new ServerTextChannelBuilder(server)\n .setName(\"new-channel\")\n .create()\n .thenAccept(channel -> {\n channel.sendMessage(\"First!\").thenAccept(message -> {\n message.addReaction(\"👍\").exceptionally(ExceptionLogger.get());\n }).exceptionally(ExceptionLogger.get());\n }).exceptionally(ExceptionLogger.get());\nOkay! This is at least a little better, but still not really perfect 🤔.
\n# thenCompose()
\nThe thenCompose methods allows you to chain futures.\nIt takes a Function
The example to create a text channel can now be written like this:
\nnew ServerTextChannelBuilder(server)\n .setName(\"new-channel\")\n .create() \n .thenCompose(channel -> channel.sendMessage(\"First!\"))\n .thenCompose(message -> message.addReaction(\"👍\"))\n .exceptionally(ExceptionLogger.get());\nFinally 🎉! Now we only need a single exceptionally(...) call at the end.\nWe also got rid of the nested callbacks (usually referred to as "callback hell").
For better understanding, here's the example with comments that tell you the type at each line:
\nnew ServerTextChannelBuilder(server) // ServerTextChannelBuilder\n .setName(\"new-channel\") // ServerTextChannelBuilder\n .create() // CompletableFuture<ServerTextChannel>\n .thenCompose(channel -> channel.sendMessage(\"First!\")) // CompletableFuture<Message>\n .thenCompose(message -> message.addReaction(\"👍\")) // CompletableFuture<Void>\n .exceptionally(ExceptionLogger.get()); // CompletableFuture<Void>\n# 📚 Further Read
\nThis tutorial only focuses on the absolute basics.\nFor a more detailed introduction to CompletableFutures, you can take a look at\nthis tutorial
You should also take a look at the JavaDoc for a complete list of methods: CompletableFuture JavaDoc
# Lambdas
\nLambdas are used to implement functional interfaces
@FunctionalInterface\npublic interface MessageCreateListener {\n void onMessageCreate(MessageCreateEvent event);\n}\nBefore Java 8, you would have implemented this kind of listener as an anonymous class
api.addMessageCreateListener(new MessageCreateListener() {\n @Override\n public void onMessageCreate(MessageCreateEvent event) {\n // Do stuff\n event.pinMessage();\n }\n});\nIn Java 8, this can be replaced with a lambda expression, which does exactly the same thing, but in a more readable fashion.\nThe method parameter (in this case event) is written in front of the -> arrow, and the method body is written after it.
api.addMessageCreateListener(event -> {\n // Do stuff\n event.pinMessage();\n});\nTIP
\nIf the method has more than one parameter, it would look like this:
\n(param1, param2) -> { ... }\nThere's even a shorter version: If you are only executing one statement, you can get rid of the { } brackets as well:
api.addMessageCreateListener(event -> event.pinMessage());\nHowever, the above method can be shortened even more, by replacing the lambda expression with a so called "method reference
api.addMessageCreateListener(MessageEvent::pinMessage);\nThere are also plenty classes in Java 8, that make use of lambda expressions.\nOne example would be the Optional class, which is explained
# 📚 Further Read
\nThis tutorial only focuses on the absolute basics.\nFor an in-depth introduction to lambda expressions, you can take a look at\nOracle's article about lambda expressions
# Optionals
\nWARNING
\nThis tutorial assumes that you are familiar with lambda expressions.\nTake a look at the
# 💪 Motivation
\nThe Optional class is widely used in Javacord.\nBasically, every method that might return a null value will return an Optional in Javacord instead.\nOptionals help you to avoid NullPointerExceptions and make it very clear if a method may not have a result.\nHere's a small example:
# The old way of doing it
\nUser user = api.getCachedUserById(123L);\nif (user != null) {\n user.sendMessage(\"Hi!\");\n}\n# The new way of doing it
\napi.getCachedUserById(123L).ifPresent(user -> \n user.sendMessage(\"Hi!\")\n);\nYou can imagine an Optional like a box 📦 that may or may not contain a value.\nBefore accessing this value, you have to "unpack" this box first.
# 📖 Methods
\nThe Optional class has many useful methods which can all be found in the JavaDocs
# get()
\nThe get method returns the value of the Optional or throws a NoSuchElementException if it does not contain a value.
TextChannel channel = api.getTextChannelById(123L).get();\nchannel.sendMessage(\"Hi\");\nDANGER
\nYou should never use this method blindly but only if you are 100% sure the optional contains a value.
\nEvery time you use this method carelessly, a kitten dies 🙀!\nTrue story.
\n# isPresent()
\nThe isPresent methods checks, if the Optional contains a value.
Optional<TextChannel> channel = api.getTextChannelById(123L);\nif (channel.isPresent()) {\n // A text channel with the id 123 exists. It's safe to call #get() now\n channel.get().sendMessage(\"Hi\");\n}\n# orElse(...)
\nThe orElse methods returns the value of the Optional if it is present. Otherwise, it returns the given default value.
// The user may not have a nickname on the given server. \n// In this case, we use the user's \"regular\" name.\nString displayName = user.getNickname(server).orElse(user.getName());\nThe example above is (mostly) equivalent to the example below but much more concise.
\nString displayName = \"\";\nOptional<String> nickname = user.getNickname(server);\nif (nickname.isPresent()) {\n displayName = nickname.get();\n} else {\n displayName = user.getName();\n}\nTIP
\nIn this case you can just use user.getDisplayName(server) instead.
# ifPresent(...)
\nThe ifPresent method is very similar to an if (value != null) { ... } check.\nIt takes a Consumer
api.getTextChannelById(123L).ifPresent(channel -> {\n channel.sendMessage(\"Hi!\");\n});\nThe example above is (mostly) equivalent to the example below but more concise.
\nOptional<TextChannel> channel = api.getTextChannelById(123L);\nif (channel.isPresent()) {\n channel.get().sendMessage(\"Hi!\");\n}\n# filter(...)
\nThe filter method filters the Optional for a given criteria.
Optional<User> botUser = api.getCachedUserById(123L).filter(User::isBot);\nThe example above is equivalent to the example below but more concise.
\nOptional<User> user = api.getCachedUserById(123L);\nOptional<User> botUser;\nif (user.isPresent() && user.get().isBot()) {\n botUser = user;\n} else {\n botUser = Optional.empty();\n}\n# map(...)
\nThe map method "converts" the type of an Optional.\nThis is useful, if the type of an Optional does not contain the final value you need.
The following example gets the name of the bots current activity (the "Playing xyz" status) or "None" if the bot has no current activity.
\nString activityName = api.getYourself().getActivity().map(Activity::getName).orElse(\"None\");\nFor better understanding, here's the exact same code but with the types as comments:
\nString activityName = api.getYourself() // User\n .getActivity() // Optional<Activity>\n .map(Activity::getName) // Optional<String>\n .orElse(\"None\"); // String\n# flatMap(...)
\nThe flatMap method if very similar to the map methods.\nIt is used to map values that itself are Optionals to prevent Optional nesting (a "box in a box").
String activityName = api.getCachedUserById(123L) // Optional<User>\n .flatMap(User::getActivity) // Optional<Activity>\n .map(Activity::getName) // Optional<String>\n .orElse(\"None\"); // String\nWithout flatMap, the code would look like this:
String activityName = api.getCachedUserById(123L) // Optional<User>\n .map(User::getActivity) // Optional<Optional<Activity>>\n .filter(Optional::isPresent) // Optional<Optional<Activity>>\n .map(Optional::get) // Optional<Activity>\n .map(Activity::getName) // Optional<String>\n .orElse(\"None\"); // String\n# 📚 Further Read
\nThis tutorial only focuses on the absolute basics.\nFor an in-depth introduction to Optionals, you can take a look at\nOracle's article about optionals
# Introduction
\nWelcome to the Javacord wiki! 👋
\nThis wiki will help you to get started with your first Discord bot as fast as possible.
\n# 📚 Structure of the wiki
\nThe wiki is divided into four groups:
\n- \n
- Getting Started focuses on teaching you how to setup up everything to get the most basic bot working. \n
- Basic tutorials contains articles about various concepts and classes of Javacord. Take a look at the headlines of each article and decide yourself, if it is relevant for you. \n
- Advanced Topics focuses on some more advanced topics that are not strictly necessary to start working with Javacord, but might become handy later on. \n
- Essential Knowledge teaches you the most important Java features/classes that you should know to comfortably work with Javacord. If you already have decent Java knowledge, you can skip this completely. \n
# 🤝 Support
\nWhile the wiki is great and covers many aspects of Javacord, we highly recommended you to join our Discord server if you have any questions:
\n- \n
- Join the Javacord server
# Creating a Bot Account
\nAfter you added Javacord as a dependency with your favorite build manager, you should now create a bot account on the Discord website.\nThis article will guide you through the process.
\n# 💡 Create a bot and get its token
\n# 1. Open https://discord.com/developers/applications/me
\n![\"\"](\"@source/wiki/getting-started/create-application.png\")
# 2. Switch to Bot
\nTIP
\nIf you want to, you can rename your application first
\n![\"\"](\"@source/wiki/getting-started/click-bot.png\")
# 3. Click on Add bot and confirm the popup
\n![\"\"](\"@source/wiki/getting-started/add-bot.png\")
\n![\"\"](\"@source/wiki/getting-started/confirm.png\")
# 4. Copy the bot's token. In this case the token would be NDc[...]pCs. You can just click on Copy.
\nDANGER
\nThis token is used to login your bot. Keep it secret!
\n![\"\"](\"@source/wiki/getting-started/copy-token.png\")
# 5. If you want to, you can change the bot's name and avatar on this page, too.
\n# ➕ How to add a bot to your server
\nBots cannot join a server on their own like normal Discord users can.\nInstead, the owner of a server has to invite the bot using a so called Invite Link.\nThere are multiple ways to create the invite link:
# Use Javacord to create the invite link
\nThe easiest way to obtain an invite link for your bot is by letting Javacord do it for you.\nSimply execute the following code, and it will print the invite link to your console:
\nDiscordApi api = new DiscordApiBuilder().setToken(\"your token\").login().join();\nSystem.out.println(api.createBotInvite());\nIf you don't have Javacord setup yet, you can also create the invite link manually.
\n# Create the invite link manually
\n# Get the client id
\nIn order to add a bot to your server you need its client id.
\nYou can get your client id from the same page
![\"\"](\"@source/wiki/getting-started/get-client-id.png\")
With this id you can create an invite link for your bot.
\nIf you are the owner or admin of the server, you can use this link to add your bot to your server. Otherwise, you have to give the link to the server owner/admins and ask them to add your bot.
\nTIP
\nUnlike the token, you don't have to keep your client id secret
\n# Create the url
\nJust use the following link and replace 123456789 with your own client id.
https://discord.com/api/oauth2/authorize?client_id=123456789&scope=applications.commands%20bot&permissions=0
\nYou can calculate the permissions (in the link above it's the 0) on the page where you created the bot:
![\"\"](\"@source/wiki/getting-started/calculate-permissions.png\")
# 🙋♂️ Use the invite link
\nYou can now open the link and add the bot to your server:
\n![\"\"](\"@source/wiki/getting-started/use-invite-link.png\")
TIP
\nOnly the owner and admins of a server can invite bots. If you do not own a server yet, it is recommended to create one for testing.
\n# Download / Installation
\nThe recommended way to get Javacord is to use a build manager, like Gradle or Maven.
\nIf you are not familiar with build managers, you can follow one of the beginner ide setup guides (see navigation) or\ndownload Javacord directly from GitHub
# 📦 Javacord Dependency
\nrepositories { mavenCentral() }\ndependencies { implementation 'org.javacord:javacord:$latest-version' }\n<dependency>\n <groupId>org.javacord</groupId>\n <artifactId>javacord</artifactId>\n <version>$latest-version</version>\n <type>pom</type>\n</dependency>\nlibraryDependencies ++= Seq(\"org.javacord\" % \"javacord\" % \"$latest-version\")\nClick to view snapshot repositories
\nSnapshots are automatically deployed from the development
repositories {\n maven {\n url \"https://oss.sonatype.org/content/repositories/snapshots/\"\n }\n}\ndependencies {\n implementation 'org.javacord:javacord:$latest-snapshot-version'\n}\n<repository>\n <id>snapshots-repo</id>\n <url>https://oss.sonatype.org/content/repositories/snapshots/</url>\n</repository>\n<dependency>\n <groupId>org.javacord</groupId>\n <artifactId>javacord</artifactId>\n <version>$latest-snapshot-version</version>\n <type>pom</type>\n</dependency>\nresolvers += \"snapshots-repo\" at \"https://oss.sonatype.org/content/repositories/snapshots/\"\nlibraryDependencies ++= Seq(\"org.javacord\" % \"javacord\" % \"$latest-snapshot-version\")\n# 📝 Optional Logger Dependency
\nIn addition to Javacord, it is also recommended to install a Log4j-2-compatible logging framework.\nA logging framework can be used to provide a more sophisticated logging experience with being able to configure log\nformat, log targets (console, file, database, Discord direct message, ...), log levels per class, and much more.
\nFor example, Log4j Core:
\ndependencies { runtimeOnly 'org.apache.logging.log4j:log4j-core:2.17.0' }\n<dependency>\n <groupId>org.apache.logging.log4j</groupId>\n <artifactId>log4j-core</artifactId>\n <version>2.17.0</version>\n</dependency>\nlibraryDependencies ++= Seq(\"org.apache.logging.log4j\" % \"log4j-core\" % \"2.17.0\")\nTake a look at the
# Frequently Asked Questions
\nHere you will find answers to some of the most asked questions.
\n# Q: Why do I receive empty (no content) messages in i.e. the MessageCreateListener?
\nYou are missing the privileged MESSAGE_CONTENT intent. For more information of how to enable privileged intents and enable them in your code see
# Q: What is ... in the code examples?
\nYou have to replace the ... with an instance that can be assigned to the datatype seen left.
For example, if you see TextChannel channel = ..., you have to replace ... with an instance that is a TextChannel which you can get from the API api.getTextChannelById(CHANNEL_ID) (note this returns an Optional<TextChannel>) or from an event like messageCreateEvent.getChannel().
# Q: Why is my code not working?
\nThere are multiple reasons why your code might not work. The most common ones are:
\n- \n
- Your code is not being reached. So make sure your code actually gets executed with a print statement or a debugger. \n
- Add at least
.exceptionally(ExceptionLogger.get())\n - Methods like
User#getRoles(Server)do not return the roles of the user. To fix this make sure to add theGUILD_MEMBERSintent. \n - You are getting a
NoSuchElementException. Congratulations, you have killed a kitten! You are most likely getting this Exception because you handle Optionals wrong. Read the article on Optionals to learn how to use them correctly. \n
If none of these tips will help you, you can ask your question in our Discord Server
# How to properly ask a question to get fast support?
\nDon't ask:
\nWhy is my code not working?\n//Code\nWhy am I getting Exception X?\nTo ensure all information is provided that is needed to solve your issue, you should ask your question in a format like:
\nI have an issue with: YOUR_ISSUE\nI want to do: WHAT_YOU_WANT_TO_DO\nCurrently this happens: WHAT_HAPPENS_NOW\n\n//Code\n\n//Exception\nThe exception is thrown in the following line(not the number): CODE_LINE\n# Q: What differs Javacord from JDA and D4J?
\nWhile all 3 libraries are Wrappers for the programming language Java, they use different techniques and concepts for their API.
\n- \n
- Javacord: Uses Java classes for its API like CompletableFuture for async requests and Optional for return types which may be
null.\n- \n
- Sending a Message:
channel.sendMessage("Javacord")\n - Checking if the Author of a message is a user:
message.getMessageAuthor().asUser().isPresent()\n
\n - Sending a Message:
- JDA: Has its own wrapper to execute requests and returns
nullif values are not present.\n- \n
- Sending a Message:
channel.sendMessage("JDA").queue()\n - Checking if the Author of a message is a user:
message.getMember() != null\n
\n - Sending a Message:
- Discord4J: Takes on the
reactiveapproach.\n- \n
- Sending a Message:
channel.createMessage("Pong!").block();\n
\n - Sending a Message:
# Writing your first bot
\nAfter you have successfully added Javacord as a dependency, created a bot user, and got its token, you are now ready to create your first simple bot! 🎉
\n# ❗ Enabling required intents
\nBy default, all non-privileged intents are enabled. To receive the message content, attachments, components, and embeds you need a special privileged intent MESSAGE_CONTENT.\nTo enable this privileged intent please see the
Slash Commands
\nGenerally it is recommended to use
# 🔑 Log the bot in
\nEverything starts with the DiscordApiBuilder class.\nIt is used to create a DiscordApi object which is the most important class of your bot.
DiscordApi api = new DiscordApiBuilder()\n .setToken(\"<your super secret token>\")\n .addIntents(Intent.MESSAGE_CONTENT)\n .login().join();\nAfter executing this code, you should already see your bot online in Discord.\nOf course, just being online is not enough, so let's add some more code!
\n# 👂 Adding a listener
\nAfter you got your api instance, let's continue by adding a listener that answers every !ping message with a simple Pong!.
api.addMessageCreateListener(event -> {\n if (event.getMessageContent().equalsIgnoreCase(\"!ping\")) {\n event.getChannel().sendMessage(\"Pong!\");\n }\n});\n![\"\"](\"@source/wiki/getting-started/ping-pong-white.gif\")
# 👩🔧 Putting it all together
\nA good place for your code is the main(...) method that every executable Java program must have.\nYour complete class may look like this:
public class MyFirstBot {\n\n public static void main(String[] args) {\n // Log the bot in\n DiscordApi api = new DiscordApiBuilder()\n .setToken(\"<your super secret token>\")\n .addIntents(Intent.MESSAGE_CONTENT)\n .login().join();\n\n // Add a listener which answers with \"Pong!\" if someone writes \"!ping\"\n api.addMessageCreateListener(event -> {\n if (event.getMessageContent().equalsIgnoreCase(\"!ping\")) {\n event.getChannel().sendMessage(\"Pong!\");\n }\n });\n }\n\n}\nCongratulations, that's already everything you have to know for the beginning.\nNow, you can play around a little bit by exploring other listeners and methods.\nOr you just continue reading articles in the Basic Tutorials category.
\n","path":"/wiki/getting-started/writing-your-first-bot.html","keywords":[]},{"title":"Interaction Commands aka. Slash Commands","headers":[{"level":2,"title":"💡 Creating a Command","slug":"creating-a-command","children":[{"level":3,"title":"📔 Notes on creating commands:","slug":"notes-on-creating-commands","children":[]}]},{"level":2,"title":"⤵️ Get your commands","slug":"get-your-commands","children":[]},{"level":2,"title":"🔨 Updating Commands","slug":"updating-commands","children":[]},{"level":2,"title":"✍️ Bulk overwriting commands","slug":"bulk-overwriting-commands","children":[]},{"level":2,"title":"👮♂️ Permissions","slug":"permissions","children":[]},{"level":2,"title":"❗ Limits","slug":"limits","children":[{"level":3,"title":"Registering a command","slug":"registering-a-command","children":[]},{"level":3,"title":"General","slug":"general","children":[]}]}],"content":"# Interaction Commands aka. Slash Commands
\nINFO
\nThere are a lot of convenient methods which aim to make your life easier with i.e., not\nbeing able to have an invalid configuration of your builder.\nTherefore, the following examples will only show the usage with the convenient methods.
\n# 💡 Creating a Command
\nINFO
\nThere are 2 different types of Commands:
\n- \n
- Global | Available for every Server once your Bot gets invited: Created with
createGlobal(DiscordApi). \n - Server | Only available on the specific Server: Created with
createForServer(Server). \n
Let's get started with the most basic command, a ping command.
\nSlashCommand command = SlashCommand.with(\"ping\", \"Checks the functionality of this command\")\n .createGlobal(api)\n .join();\nThat's all you have to do!
\nLet's have a look at a more complex command which involves nearly all possibilities:
\nSlashCommand command =\n SlashCommand.with(\"channel\", \"A command dedicated to channels\",\n Arrays.asList(\n SlashCommandOption.createWithOptions(SlashCommandOptionType.SUB_COMMAND_GROUP, \"edit\", \"Edits a channel\",\n Arrays.asList(\n SlashCommandOption.createWithOptions(SlashCommandOptionType.SUB_COMMAND, \"allow\", \"Allows a permission to a user for a channel\",\n Arrays.asList(\n SlashCommandOption.create(SlashCommandOptionType.CHANNEL, \"channel\", \"The channel to modify\", true),\n SlashCommandOption.create(SlashCommandOptionType.USER, \"user\", \"The user which permissions should be changed\", true),\n SlashCommandOption.createWithChoices(SlashCommandOptionType.DECIMAL, \"permission\", \"The permission to allow\", true,\n Arrays.asList(\n SlashCommandOptionChoice.create(\"manage\", 0),\n SlashCommandOptionChoice.create(\"show\", 1)))\n ))))))\n .createGlobal(api)\n .join();\nLet that sink in first!
\nWhat are we doing here?
\n- \n
- We create a base command called
channel. \n - It has a SUB_COMMAND_GROUP called
editwhich basically is just a folder where you can put your commands in. \n - There's a SUB_COMMAND called
allowwhich is our actual command. Therefore, our complete argument looks likechannel edit allow. \n - The SUB_COMMAND has 3 arguments:\n
- \n
- The channel which should be edited. \n
- The user which permissions should be changed. \n
- A predefined list of available permissions the command executor can choose of. \n
\n
![\"\"](\"https://i.imgur.com/Qb9lgqb.png\")
# 📔 Notes on creating commands:
\n# The REQUIRED attribute
\nYou can only mark the last argument as being not required. This means it can be optionally set by the command executor.\nIn the above example you could i.e. set the PERMISSIONS argument to false.
# Command structure
\nYour command has to follow these structures in order to be successfully created:
\nCommand structure
\nVALID\n\ncommand\n|\n|__ subcommand\n|\n|__ subcommand\n\n----\n\ncommand\n|\n|__ subcommand-group\n |\n |__ subcommand\n|\n|__ subcommand-group\n |\n |__ subcommand\n\n----\n\nVALID\n\ncommand\n|\n|__ subcommand-group\n |\n |__ subcommand\n|\n|__ subcommand\n\n-------\n\nINVALID\n\n\ncommand\n|\n|__ subcommand-group\n |\n |__ subcommand-group\n|\n|__ subcommand-group\n |\n |__ subcommand-group\n\n----\n\nINVALID\n\ncommand\n|\n|__ subcommand\n |\n |__ subcommand-group\n|\n|__ subcommand\n |\n |__ subcommand-group\n# ⤵️ Get your commands
\nAll global commands:
\nSet<SlashCommand> commands = api.getGlobalSlashCommands().join();\nAll commands only available on a single server:
\nServer server = ...;\nSet<SlashCommand> commands = api.getServerSlashCommands(server).join();\nWARNING
\nGetting all commands from a server only contains the commands you have created on this specific server.\nTherefore, the returned list does not include any global command!
\n# 🔨 Updating Commands
\nWhen updating your commands you only have to include what you actually want to change.\nThe following updater will change the previous created command and change its base name from channel to channels.
SlashCommand updatedCommand =\n new SlashCommandUpdater(commandId)\n .setName(\"channels\")\n .updateGlobal(api)\n .join();\n# ✍️ Bulk overwriting commands
\nIf you have to update / create multiple commands at once it advised to use the batch updater to only have to do 1 request.
\nDiscordApi api = ...;\n\nSet<SlashCommandBuilder> builders = new HashSet<>();\nbuilders.add(new SlashCommandBuilder().setName(\"server\").setDescription(\"A command for the server\"));\nbuilders.add(new SlashCommandBuilder().setName(\"permission\").setDescription(\"A command for permissions\"));\n \napi.bulkOverwriteGlobalApplicationCommands(builders).join();\n# 👮♂️ Permissions
\nPermissions exist to enable / disable the usage of your commands for certain things. These things may be:
\n- \n
- Permissions \n
- DMs \n
When you create a command you can specify which permissions are required to use it.\nIn addition to the required permissions, you can also specify whether the command should be available in DMs.
\nSlashCommand.with(\"ping\",\"Ping!\")\n .setDefaultEnabledForPermissions(PermissionType.ADMINISTRATOR, PermissionType.BAN_MEMBERS)\n //.setDefaultDisabled() Effectively the same as setDefaultEnabledForPermissions(PermissionType.ADMINISTRATOR) but this will lead to the default type by Discord.\n .setEnabledInDms(false)\n .createGlobal(api)\n .join();\nINFO
\nOnce your bot has been invited to a server, you can not change the permissions afterwards on this server.\nThen it's up to the server administrators / owner to correctly set up the commands for users / roles / channels.
\n# ❗ Limits
\n# Registering a command
\n- \n
- Server commands are specific to the server you specify when making them. Server commands are not available in DMs. Command names are unique per application within each scope (global and server). That means: \n
- Your app cannot have two global commands with the same name \n
- Your app cannot have two server commands within the same name on the same guild \n
- Your app can have a global and guild command with the same name \n
- Multiple apps can have commands with the same names \n
# General
\n- \n
- An app can have up to 100 top-level global commands with unique names \n
- An app can have up to an additional 100 server commands per server \n
- An app can have up to 25 subcommand groups on a top-level command \n
- An app can have up to 25 subcommands within a subcommand group \n
- Commands can have up to 25 options \n
- Options can have up to 25 choices \n
- Maximum of 4000 characters for combined name, description, and value properties for each command and its subcommands and groups \n
- Limitations on nesting subcommands and groups \n
- Global rate limit of 200 slash command creates per day per server \n
# Message Components
\n# ❔ What are components?
\nComponents are interactive elements like buttons or hidden elements like the ActionRow which use is for displaying the visible components. You can add them to a message and interact with users in a very convenient way.\nCurrently, the only interactive components available at the moment are buttons. They differ in style and behaviour(link redirect) seen in the picture below:\n![\"\"](\"https://support.discord.com/hc/article_attachments/1500019725621/buttons.png\")
# 💡 Sending a message with a component
\nSending a component with your message is a simple as that:
\nTextChannel channel = ...;\n\nnew MessageBuilder()\n .setContent(\"Click on one of these Buttons!\")\n .addComponents(\n ActionRow.of(Button.success(\"success\", \"Send a message\"),\n Button.danger(\"danger\", \"Delete this message\"),\n Button.secondary(\"secondary\", \"Remind me after 5 minutes\")))\n .send(channel);\n![\"\"](\"https://i.imgur.com/5tMCePH.png\")
You simply add a High Level component like an ActionRow which is a container for displaying your components.\nIn turn the ActionRow consist of the components you can interact with like Buttons.
\nThis works for Select Menus as well:
\nTextChannel channel = ...;\n\nnew MessageBuilder()\n .setContent(\"Select an option of this list!\")\n .addComponents(\n ActionRow.of(SelectMenu.create(\"options\", \"Click here to show the options\", 1, 1,\n Arrays.asList(SelectMenuOption.create(\"Option One\", \"You selected Option One!\", \"Click here to select Option One\"),\n SelectMenuOption.create(\"Option Two\", \"You selected Option Two!\", \"Click here to select Option Two\"),\n SelectMenuOption.create(\"Option Three\", \"You selected Option Three!\", \"Click here to select Option Three\")))))\n .send(channel);\n![\"\"](\"https://i.imgur.com/bhcGjCN.png\")
![\"\"](\"https://i.imgur.com/ZlviGPe.png\")
# Interactions
\nInteractions are a means of accepting user input through Discord. They have been introduced to provide a more standardized,\ncontrolled way for commands than parsing messages. They can even be used with applications that do not provide a bot user.
\n# 💬 Message Commands
\nThe "old" way of doing commands was done through parsed text messages, like !ping, !userinfo James or\n!mute James 100s. While such commands are easy in theory, they come with several problems, such as:
- \n
- Conflicts between Bots using the same command format / prefix. \n
- Bots have to be able to read all messages and find those that are directed at them \n
- Information about command structure can only be provided in info texts and error messages \n
![\"Message](\"@source/wiki/basic-tutorials/interactions/lifecycle_command.png\")
# ✉️ Interaction Types
\nInteractions come in a variety of shapes. The most complex and versatile is the
Context Menu commands
# ♻️ Lifecycle
\nINFO
\nCreation of interactions is detailed on the pages linked in the previous section.
\nUnlike chat message commands, interactions and interaction commands need to be registered with Discord. In order for\na bot's interactions to be available in a server, the bot must be added to the server with the applications.commands\nOAUTH scope. The scope is included in links created by DiscordApi#createInviteLink. If your bot is older, it may need to\nbe invited with the new link to add the scope. It is not necessary to remove the bot from the server to do this.
![\"Interaction](\"@source/wiki/basic-tutorials/interactions/lifecycle_interaction.png\")
# 📈 Advantages
\nWhile being more complicated to utilize, interactions have many benefits over pure text commands.
\n- \n
- Better Validation: Commands can not be sent with parameters of the wrong type or missing required parameters \n
- No conflicts: Interactions are separated by bot and only sent to the proper bot \n
- "Privacy": If no public response is sent by the bot, the exchange is invisible to other chat participants \n
- Integration: Interactions are integrated into the client's user interface \n
- Conversations:
Message components can be used in replies to interactions, allowing for nested dialogues. \n
WARNING
\nIf a bot replies to a slash command with a public message, the command used, including all parameters, is visible to\nother users.
\n# 🤖 Applications vs. Bots
\nInteractions can used by any application, not only bots. While interactions can also be handled through webhooks,\nJavacord only offers support for dealing with them through the gateway. See the\nDiscord Documentation
WARNING
\nThe methods of handling interactions can not be mixed. If you register a webhook for your interaction commands, the bot\nwill no longer receive any interaction events.
\n# 🔍 See also
\n\n","path":"/wiki/basic-tutorials/interactions/overview.html","keywords":["interaction","slash command","command","context menu","autocomplete"]},{"title":"Responding to interactions","headers":[{"level":2,"title":"💬 Responding immediately after receiving an interaction.","slug":"responding-immediately-after-receiving-an-interaction","children":[]},{"level":2,"title":"💬 Responding after some time when receiving an interaction.","slug":"responding-after-some-time-when-receiving-an-interaction","children":[{"level":3,"title":"Sending followup messages","slug":"sending-followup-messages","children":[]}]},{"level":2,"title":"Responding with a Modal","slug":"responding-with-a-modal","children":[]},{"level":2,"title":"💬 SlashCommand interaction only response methods","slug":"slashcommand-interaction-only-response-methods","children":[{"level":3,"title":"How to know what slash command was invoked?","slug":"how-to-know-what-slash-command-was-invoked","children":[]},{"level":3,"title":"Respond to an AutoComplete interaction triggered from a SlashCommand","slug":"respond-to-an-autocomplete-interaction-triggered-from-a-slashcommand","children":[]}]},{"level":2,"title":"💬 Message Component interaction only response methods","slug":"message-component-interaction-only-response-methods","children":[{"level":3,"title":"A more complete example of how to respond to Component interactions","slug":"a-more-complete-example-of-how-to-respond-to-component-interactions","children":[]}]}],"content":"# Responding to interactions
\nThere are many ways to respond to interactions and some are only available for certain interactions.\nThe following will be usable for every interaction.
\n# 💬 Responding immediately after receiving an interaction.
\nevent.getInteraction()\n .createImmediateResponder()\n .setContent(\"YOUR_RESPONSE\")\n .respond();\nINFO
\nNote that you have to respond withing 3 seconds, or the command will fail. If you need longer than 3 seconds you have to\nrespond with respondLater() which allows you to respond within 15 minutes.
Because of this time limitation, sending any files when creating an immediate response is not possible.\nIf you want a file to be embedded either use respondLater or include a web link in the message content.\nDepending on the media type of the link and the server configuration, Discord will then display an appropriate embed for the file.
When you want to respond ephemerally, you can use the setFlags method. Your new responder would look like the\nfollowing:
event.getInteraction()\n .createImmediateResponder()\n .setContent(\"YOUR_RESPONSE\")\n .setFlags(MessageFlag.EPHEMERAL)\n .respond();\n# 💬 Responding after some time when receiving an interaction.
\nIf your computations takes longer than the 3 seconds limit, you can respond later and the Discord Client will show that\nyour bot is thinking until you respond.
\nevent.getInteraction()\n .respondLater()\n .thenAccept(interactionOriginalResponseUpdater -> {\n interactionOriginalResponseUpdater.setContent(\"Update message after some time\").update();\n });\nYou can respond ephemerally when responding later too. For that you have pass a true boolean to the respondLater method.
event.getInteraction()\n .respondLater(true)\n .thenAccept(interactionOriginalResponseUpdater -> {\n interactionOriginalResponseUpdater.setContent(\"Update message after some time\").update();\n });\n# Sending followup messages
\nFollowup messages can be sent within 15 minutes after the command has been invoked. You can send as many followup\nmessages as you want.
\napi.addSlashCommandCreateListener(event -> {\n SlashCommandInteraction slashCommandInteraction = event.getSlashCommandInteraction();\n slashCommandInteraction.respondLater().thenAccept(interactionOriginalResponseUpdater -> {\n interactionOriginalResponseUpdater.setContent(\"You will receive the answer in a few minutes!\").update();\n\n // time < 15 minutes\n \n slashCommandInteraction.createFollowupMessageBuilder()\n .setContent(\"Thank you for your patience, it took a while but the answer to the universe is 42\")\n .send();\n });\n});\n# Responding with a Modal
\nA modal is a popup dialog which can be shown when responding to an interaction. It focuses the users to explicitly fill out this form to continue with the workflow.\nCurrently, only the TextInput (SelectMenu has been seen working too, but is not yet officially supported) is supported.
api.addMessageComponentCreateListener(event -> {\n event.getInteraction().respondWithModal(\"modalId\",\"Modal Title\",\n ActionRow.of(TextInput.create(TextInputStyle.SHORT, \"text_input_id\", \"This is a Text Input Field\")));\n});\nWhich results in
\n![\"Modal\"](\"@source/wiki/basic-tutorials/interactions/respond_with_modal.png\")
# 💬 SlashCommand interaction only response methods
\n# How to know what slash command was invoked?
\nFor example, you have created a slash command with the name "settings" and a subcommand "color". If you want to check if\nexactly this command has been used, you can check it as follows:
\napi.addSlashCommandCreateListener(event -> {\n SlashCommandInteraction interaction = event.getSlashCommandInteraction();\n if (interaction.getFullCommandName().equals(\"settings color\")) {\n //Code if command matches the full name\n }\n});\n# Respond to an AutoComplete interaction triggered from a SlashCommand
\napi.addAutocompleteCreateListener(event -> {\n event.getAutocompleteInteraction()\n .respondWithChoices(Arrays.asList(\n SlashCommandOptionChoice.create(\"one\", 1),\n SlashCommandOptionChoice.create(\"two\", 2))\n );\n});\n# 💬 Message Component interaction only response methods
\nWhen dealing with message components, you don't necessarily have to respond or update a message.\nYou can simply acknowledge the interaction and let the user know that the task is done.
\napi.addMessageComponentCreateListener(event -> {\n event.getMessageComponentInteraction().acknowledge();\n});\n# A more complete example of how to respond to Component interactions
\nThe following code snipped shows how you can respond to the example created in
api.addMessageComponentCreateListener(event -> {\n MessageComponentInteraction messageComponentInteraction = event.getMessageComponentInteraction();\n String customId = messageComponentInteraction.getCustomId();\n\n switch (customId) {\n case \"success\":\n messageComponentInteraction.createImmediateResponder()\n .setContent(\"You clicked a button!\")\n .respond();\n break;\n case \"danger\":\n messageComponentInteraction.getMessage().ifPresent(Message::delete);\n break;\n case \"secondary\":\n messageComponentInteraction.respondLater().thenAccept(interactionOriginalResponseUpdater -> {\n //Code to respond after 5 minutes\n });\n break;\n case \"options\":\n messageComponentInteraction.createImmediateResponder()\n\t\t\t\t\t.setContent(\"You selected an option in a select menu!\")\n\t\t\t\t\t.respond();\n break;\n }\n});\n# Eclipse + Maven
\nInfo
\nWe recommend to use
# 🔧 Setup
\n# 1. Start Eclipse
\n# 2. Create a new project (File -> New -> Project)
\n![\"\"](\"https://i.imgur.com/hYeYxen.png\")
# 3. Select Maven Project
\n# 4. Click Next
\n![\"\"](\"https://i.imgur.com/CeHy9HK.png\")
# 5. Check Create a simple project
\n# 6. Click Next
\n![\"\"](\"https://i.imgur.com/xxbGmr6.png\")
# 7. Enter a group id (e.g. com.github.yourname)
\n# 8. Enter an artifact id (e.g. myfirstbot)
\n# 9. Click Finish
\n![\"\"](\"https://i.imgur.com/JSV9yrl.png\")
# 10. Double click on the pom.xml file
\n![\"\"](\"https://i.imgur.com/NCAALIt.png\")
# 11. Select pom.xml
\n![\"\"](\"https://i.imgur.com/kbdtiLJ.png\")
# 12. Now you have to add Javacord as a dependency by editing the pom.xml file. Your file should now look like this:
\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<project xmlns=\"http://maven.apache.org/POM/4.0.0\"\n xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n xsi:schemaLocation=\"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd\">\n <modelVersion>4.0.0</modelVersion>\n\n <groupId>your.package.name</groupId>\n <artifactId>myfirstbot</artifactId>\n <version>1.0-SNAPSHOT</version>\n\n <dependencies>\n <dependency>\n <groupId>org.javacord</groupId>\n <artifactId>javacord</artifactId>\n <version>$latest-version</version>\n <type>pom</type>\n </dependency>\n </dependencies>\n\n</project>\n# 13. Create a new package inside the src/main/java folder
\n![\"\"](\"https://i.imgur.com/Z1QNuQf.png\")
\n![\"\"](\"https://i.imgur.com/RKJc0yU.png\")
# 14. Create a new class inside this package
\n![\"\"](\"https://i.imgur.com/eUmumlz.png\")
\n![\"\"](\"https://i.imgur.com/GsPFaag.png\")
# 15. Save the project (you should do this from time to time)
\n![\"\"](\"https://i.imgur.com/Ht5UT8S.png\")
# 16. Now you can start coding! Example code:
\npackage com.github.yourname.myfirstbot;\n\nimport org.javacord.api.DiscordApi;\nimport org.javacord.api.DiscordApiBuilder;\n\npublic class Main {\n\n public static void main(String[] args) {\n // Insert your bot's token here\n String token = \"your token\";\n\n DiscordApi api = new DiscordApiBuilder().setToken(token).login().join();\n\n // Add a listener which answers with \"Pong!\" if someone writes \"!ping\"\n api.addMessageCreateListener(event -> {\n if (event.getMessageContent().equalsIgnoreCase(\"!ping\")) {\n event.getChannel().sendMessage(\"Pong!\");\n }\n });\n\n // Print the invite url of your bot\n System.out.println(\"You can invite the bot by using the following url: \" + api.createBotInvite());\n }\n\n}\n# 🏃♀️ Run the code
\nYou can run your code by clicking on the small green arrow\n![\"\"](\"https://i.imgur.com/rsIHH9M.png\")
# IntelliJ + Gradle
\nThis tutorial provides a beginner-friendly click by click guide to set up Javacord with Intellij and Gradle.\nIf you are already familiar with IntelliJ and Gradle, you can just see the artifact locations at
# 🔧 Setup
\n# 1. Start IntelliJ
\n# 2. Create a new project (File -> New -> Project)
\n![\"\"](\"@source/wiki/getting-started/setup/img-intellij-gradle/create-project.png\")
# 3. Select Gradle
\n# 4. Make sure to select an SDK which is 1.8 (or greater)
\n# 5. Click Next
\n![\"\"](\"@source/wiki/getting-started/setup/img-intellij-gradle/select-gradle.png\")
# 6. Enter a group id (e.g. com.github.yourname)
\nYou can choose whatever you want
\n# 7. Enter an artifact id (e.g. myfirstbot)
\nYou can choose whatever you want
\n# 8. Click Next
\n![\"\"](\"@source/wiki/getting-started/setup/img-intellij-gradle/new-project.png\")
# 9. Check Use auto-import
\n# 10. Click Next
\n![\"\"](\"@source/wiki/getting-started/setup/img-intellij-gradle/new-project-2.png\")
# 11. Click Finish
\n![\"\"](\"@source/wiki/getting-started/setup/img-intellij-gradle/new-project-3.png\")
# 12. Locate the build.gradle file and open it
\n![\"\"](\"@source/wiki/getting-started/setup/img-intellij-gradle/after-finished.png\")
# 12. Add the Javacord dependency. Your build.gradle file should now look like this
\nplugins {\n id 'java'\n}\n\ngroup 'com.github.yourname'\nversion '1.0-SNAPSHOT'\n\nsourceCompatibility = 1.8\n\nrepositories {\n mavenCentral()\n}\n\ndependencies {\n implementation 'org.javacord:javacord:$latest-version'\n}\n# 13. Create a new package in the src/main/java folder
\n![\"\"](\"@source/wiki/getting-started/setup/img-intellij-gradle/new-package.png\")
\n![\"\"](\"@source/wiki/getting-started/setup/img-intellij-gradle/new-package-2.png\")
# 14. Create a new class inside this package
\n![\"\"](\"@source/wiki/getting-started/setup/img-intellij-gradle/new-class.png\")
\n![\"\"](\"@source/wiki/getting-started/setup/img-intellij-gradle/new-class-2.png\")
# 15. You can now start coding!
\nExample code:
\npackage com.github.yourname;\n\nimport org.javacord.api.DiscordApi;\nimport org.javacord.api.DiscordApiBuilder;\n\npublic class Main {\n\n public static void main(String[] args) {\n // Insert your bot's token here\n String token = \"your token\";\n\n DiscordApi api = new DiscordApiBuilder().setToken(token).login().join();\n\n // Add a listener which answers with \"Pong!\" if someone writes \"!ping\"\n api.addMessageCreateListener(event -> {\n if (event.getMessageContent().equalsIgnoreCase(\"!ping\")) {\n event.getChannel().sendMessage(\"Pong!\");\n }\n });\n\n // Print the invite url of your bot\n System.out.println(\"You can invite the bot by using the following url: \" + api.createBotInvite());\n }\n\n}\n# 🏃♀️ Run the code
\nYou can run your code by clicking on the small green arrow\n![\"\"](\"@source/wiki/getting-started/setup/img-intellij-gradle/run-the-bot.png\")
# IntelliJ + Maven
\nThis tutorial provides a beginner-friendly click by click guide to set up Javacord with Intellij and Maven.\nIf you are already familiar with IntelliJ and Maven, you can just see the artifact locations at
Info
\nWe recommend to use
# 🔧 Setup
\n# 1. Start IntelliJ
\n# 2. Create a new project (File -> New -> Project)
\n![\"\"](\"https://i.imgur.com/Twz9SlW.png\")
# 3. Select Maven
\n# 4. Make sure to select an SDK which is 1.8 (or greater)
\n# 5.* Click Next
\n![\"\"](\"https://i.imgur.com/OGDuITx.png\")
# 6. Enter a group id (e.g. com.github.yourname)
\n# 7. Enter an artifact id (e.g. myfirstbot)
\n# 8. Click Next
\n![\"\"](\"https://i.imgur.com/kWoutrk.png\")
# 9. Click on Finish
\n![\"\"](\"https://i.imgur.com/pXwWMbi.png\")
# 10. Your project should now look like this. First click on Enable Auto-Import
\n![\"\"](\"https://i.imgur.com/PXZ6aww.png\")
# 11. Now you have to add Javacord as a dependency by editing the pom.xml file. Your file should now look like this:
\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<project xmlns=\"http://maven.apache.org/POM/4.0.0\"\n xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n xsi:schemaLocation=\"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd\">\n <modelVersion>4.0.0</modelVersion>\n\n <groupId>your.package.name</groupId>\n <artifactId>myfirstbot</artifactId>\n <version>1.0-SNAPSHOT</version>\n\n <dependencies>\n <dependency>\n <groupId>org.javacord</groupId>\n <artifactId>javacord</artifactId>\n <version>$latest-version</version>\n <type>pom</type>\n </dependency>\n </dependencies>\n\n</project>\n# 12. Create a new package
\n![\"\"](\"https://i.imgur.com/EtgpIok.png\")
\n![\"\"](\"https://i.imgur.com/P4e3RwT.png\")
# 13. Create a new class inside this package
\n![\"\"](\"https://i.imgur.com/VVnLssf.png\")
\n![\"\"](\"https://i.imgur.com/nyl3Jit.png\")
# 14. You can now start coding! Example code:
\npackage com.github.yourname;\n\nimport org.javacord.api.DiscordApi;\nimport org.javacord.api.DiscordApiBuilder;\n\npublic class Main {\n\n public static void main(String[] args) {\n // Insert your bot's token here\n String token = \"your token\";\n\n DiscordApi api = new DiscordApiBuilder().setToken(token).login().join();\n\n // Add a listener which answers with \"Pong!\" if someone writes \"!ping\"\n api.addMessageCreateListener(event -> {\n if (event.getMessageContent().equalsIgnoreCase(\"!ping\")) {\n event.getChannel().sendMessage(\"Pong!\");\n }\n });\n\n // Print the invite url of your bot\n System.out.println(\"You can invite the bot by using the following url: \" + api.createBotInvite());\n }\n \n}\n# 🏃♀️ Run the code
\nYou can run your code by clicking on the small green arrow\n![\"\"](\"https://i.imgur.com/USGlewm.png\")
# 🚧 Possible problems
\nNote: If you get the following error:\n![\"\"](\"https://i.imgur.com/Q34zZpb.png\")
you have to change your language level to 1.8
![\"\"](\"https://i.imgur.com/IwQ5LN8.png\")
Legal Disclosure
+ Information in accordance with section 5 TMG+
+ nnamreppO naitsaB
+ 12 .rtS-hcasieR-noV
+ htoR 45119
+
+
Contact
+ Telephone: 3426112 8751 94++ E-Mail: gro [tod] drocavaj [ta] tcatnoc
+
+
Disclaimer
+Accountability for content
+ The contents of our pages have been created with the utmost care. However, we cannot guarantee the contents' accuracy, completeness or topicality. According to statutory provisions, we are furthermore responsible for our own content on these web pages. In this context, please note that we are accordingly not obliged to monitor merely the transmitted or saved information of third parties, or investigate circumstances pointing to illegal activity. Our obligations to remove or block the use of information under generally applicable laws remain unaffected by this as per §§ 8 to 10 of the Telemedia Act (TMG).+
+
Accountability for links
+ Responsibility for the content of external links (to web pages of third parties) lies solely with the operators of the linked pages. No violations were evident to us at the time of linking. Should any legal infringement become known to us, we will remove the respective link immediately.+
+
Copyright
+ Our web pages and their contents are subject to German copyright law. Unless expressly permitted by law (§ 44a et seq. of the copyright law), every form of utilizing, reproducing or processing works subject to copyright protection on our web pages requires the prior consent of the respective owner of the rights. Individual reproductions of a work are allowed only for private use, so must not serve either directly or indirectly for earnings. Unauthorized utilization of copyrighted works is punishable (§ 106 of the copyright law).+
+ Source: http://www.muster-vorlagen.net/
+ +
An easy to use multithreaded library for creating Discord bots in Java.
💡 About Javacord
Javacord is a modern library that focuses on simplicity and speed 🚀. By reducing itself to standard Java classes and features like Optionals and CompletableFutures, it is extremely easy to use for every Java developer, as it does not require you to learn any new frameworks or complex abstractions. It has rich documentation and an awesome community 💪 on Discord that loves to help with any specific problems and questions.
👩🏫 Learn more
This website is the home to our wiki for everyone who want to learn Javacord. If you haven't already, you should first take a look at our GitHub page before you continue with the wiki.
🤝 Discord Server
Did you know that Javacord has a Discord server? No? Well, now you do! 😉
Javacord's Discord community is an excellent resource if you have questions about the library. You can join it by clicking 👉 here 👈.
Effective date: October 27, 2018
+ + +Javacord ("us", "we", or "our") operates the https://javacord.org website (the "Service").
+ +This page informs you of our policies regarding the collection, use, and disclosure of personal data when you use our Service and the choices you have associated with that data. Our Privacy Policy for Javacord is managed through Free Privacy Policy.
+ +We use your data to provide and improve the Service. By using the Service, you agree to the collection and use of information in accordance with this policy. Unless otherwise defined in this Privacy Policy, terms used in this Privacy Policy have the same meanings as in our Terms and Conditions, accessible from https://javacord.org
+ + +Information Collection And Use
+ +We collect several different types of information for various purposes to provide and improve our Service to you.
+ +Types of Data Collected
+ +Personal Data
+ +While using our Service, we may ask you to provide us with certain personally identifiable information that can be used to contact or identify you ("Personal Data"). Personally identifiable information may include, but is not limited to:
+ +-
+
- Cookies and Usage Data +
Usage Data
+ +We may also collect information how the Service is accessed and used ("Usage Data"). This Usage Data may include information such as your computer's Internet Protocol address (e.g. IP address), browser type, browser version, the pages of our Service that you visit, the time and date of your visit, the time spent on those pages, unique device identifiers and other diagnostic data.
+ +Tracking & Cookies Data
+We use cookies and similar tracking technologies to track the activity on our Service and hold certain information.
+Cookies are files with small amount of data which may include an anonymous unique identifier. Cookies are sent to your browser from a website and stored on your device. Tracking technologies also used are beacons, tags, and scripts to collect and track information and to improve and analyze our Service.
+You can instruct your browser to refuse all cookies or to indicate when a cookie is being sent. However, if you do not accept cookies, you may not be able to use some portions of our Service.
+Examples of Cookies we use:
+-
+
- Session Cookies. We use Session Cookies to operate our Service. +
- Preference Cookies. We use Preference Cookies to remember your preferences and various settings. +
- Security Cookies. We use Security Cookies for security purposes. +
Use of Data
+ +We use the collected data for various purposes:
+-
+
- To provide and maintain the Service +
- To notify you about changes to our Service +
- To allow you to participate in interactive features of our Service when you choose to do so +
- To provide customer care and support +
- To provide analysis or valuable information so that we can improve the Service +
- To monitor the usage of the Service +
- To detect, prevent and address technical issues +
Transfer Of Data
+Your information, including Personal Data, may be transferred to — and maintained on — computers located outside of your state, province, country or other governmental jurisdiction where the data protection laws may differ than those from your jurisdiction.
+If you are located outside Germany and choose to provide information to us, please note that we transfer the data, including Personal Data, to Germany and process it there.
+Your consent to this Privacy Policy followed by your submission of such information represents your agreement to that transfer.
+We will take all steps reasonably necessary to ensure that your data is treated securely and in accordance with this Privacy Policy and no transfer of your Personal Data will take place to an organization or a country unless there are adequate controls in place including the security of your data and other personal information.
+ +Disclosure Of Data
+ +Legal Requirements
+We may disclose your Personal Data in the good faith belief that such action is necessary to:
+-
+
- To comply with a legal obligation +
- To protect and defend the rights or property of us +
- To prevent or investigate possible wrongdoing in connection with the Service +
- To protect the personal safety of users of the Service or the public +
- To protect against legal liability +
Security Of Data
+The security of your data is important to us, but remember that no method of transmission over the Internet, or method of electronic storage is 100% secure. While we strive to use commercially acceptable means to protect your Personal Data, we cannot guarantee its absolute security.
+ +Service Providers
+We may employ third party companies and individuals to facilitate our Service ("Service Providers"), to provide the Service on our behalf, to perform Service-related services or to assist us in analyzing how our Service is used.
+These third parties have access to your Personal Data only to perform these tasks on our behalf and are obligated not to disclose or use it for any other purpose.
+ +Analytics
+We may use third-party Service Providers to monitor and analyze the use of our Service.
+-
+
-
+
Google Analytics
+Google Analytics is a web analytics service offered by Google that tracks and reports website traffic. Google uses the data collected to track and monitor the use of our Service. This data is shared with other Google services. Google may use the collected data to contextualize and personalize the ads of its own advertising network.
+You can opt-out of having made your activity on the Service available to Google Analytics by installing the Google Analytics opt-out browser add-on. The add-on prevents the Google Analytics JavaScript (ga.js, analytics.js, and dc.js) from sharing information with Google Analytics about visits activity.
For more information on the privacy practices of Google, please visit the Google Privacy & Terms web page: https://policies.google.com/privacy?hl=en
+
+
Links To Other Sites
+Our Service may contain links to other sites that are not operated by us. If you click on a third party link, you will be directed to that third party's site. We strongly advise you to review the Privacy Policy of every site you visit.
+We have no control over and assume no responsibility for the content, privacy policies or practices of any third party sites or services.
+ + +Children's Privacy
+Our Service does not address anyone under the age of 18 ("Children").
+We do not knowingly collect personally identifiable information from anyone under the age of 18. If you are a parent or guardian and you are aware that your Children has provided us with Personal Data, please contact us. If we become aware that we have collected Personal Data from children without verification of parental consent, we take steps to remove that information from our servers.
+ + +Changes To This Privacy Policy
+We may update our Privacy Policy from time to time. We will notify you of any changes by posting the new Privacy Policy on this page.
+We will let you know via email and/or a prominent notice on our Service, prior to the change becoming effective and update the "effective date" at the top of this Privacy Policy.
+You are advised to review this Privacy Policy periodically for any changes. Changes to this Privacy Policy are effective when they are posted on this page.
+ + +Contact Us
+If you have any questions about this Privacy Policy, please contact us:
+-
+
- By email: gro [tod] drocavaj [ta] tcatnoc
+ +
Bot Lifecycle
It's important to know the life-cycle of a discord bot to properly handle disconnects. The following state diagram shows the 4 states a bot can have:
💡 The four states
Connected
The bot is connected to the websocket and receives all events.
Disconnected
The bot is not connected to the websocket and receives no events. It's not uncommon for a bot to occasionally lose connection. This can have various reasons, for example:
- Your bot lost its internet connection
- Discord restarted the gateway server you are currently connected to
- A plane crashed into Discord's data center
The bot will periodically try to resume/reconnect to the websocket. It will start with a small frequency and increase it with every failed reconnect attempt. You can modify the reconnect delay with the DiscordApi#setReconnectDelay(...) method. The following example code would increase the delay linearly. The 1st attempt would be delayed for 2 seconds, the 2nd attempt for 4 seconds, the 3rd attempts for 6 seconds, ...
api.setReconnectDelay(attempt -> attempt * 2);
+Important: Bots can only reconnect 1000 times in a 24-hour period (every ~90 seconds). This limit is global and across all shards. Upon hitting this limit, all active sessions for the bot will be terminated, the bot's token will be reset, and you will receive an email notification. This is the reason Javacord increases the reconnect delay with every attempt.
By default, the $default_delay$ formula below is used to calculate the reconnect delay
$$ default_delay(a) = \lfloor a^{1.5} - \frac{a^{1.5}}{\frac{1}{(0.1 \cdot a)} + 1} \rceil $$
with $a$ being the attempt.
The formula will generate the following reconnect delay:
| Attempt | Delay |
|---|---|
| 1 | 1 |
| 2 | 2 |
| 3 | 4 |
| 4 | 6 |
| 5 | 7 |
| ... | ... |
| 10 | 16 |
| 15 | 23 |
| 20 | 30 |
| ... | ... |
| 50 | 59 |
| 100 | 91 |
| 150 | 115 |
| ... | ... |
Resuming
Resuming is only possible for a short time after being disconnected. If the bot can successfully resume the connection, you will not miss any events. Your bot will receive all events you missed while being disconnected. The cache gets updated accordingly.
Reconnecting
If your bot reconnects (not resumes!), the whole cache gets wiped, and you will not receive any missed events.
What does this mean?
- References to entities (e.g. a
Server,User,Channel, ...) will be outdated. This is why you should never store entities, but the id instead. See Entity Cache. - You will miss events. There's no way to receive the missed events.
- Listeners attached to entities will not be affected, because they are bound to the entity's id, not the object itself.
💊 How to handle disconnects
For most bots, there's nothing you have to do. All registered listeners are reconnect-resistant, which means if your bot is only reacting to events, it will work fine after a restart. For example, the following code will not be affected by a reconnect (besides maybe some missed !ping messages):
api.addMessageCreateListener(event -> {
+ if (event.getMessage().getContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+});
+In case you want to handle reconnects (e.g. fetch the message history to detect missed messages), there are special connection-related listeners which can be used to track the state of the bot:
LostConnectionListenerReconnectListenerResumeListener
Entity Cache
Javacord keeps an internal cache for entities (e.g. Servers, Channels, Users, ...). It is important to know how the cache behaves to properly use it.
🔮 What is in the cache?
Nearly every entity known by the bot is guaranteed to be in the cache. There are a few exceptions though:
Users
Users are only cached when you have the GUILD_MEMBERS intent enabled. See Gateway Intents for more information.
Messages
Not every single message is in the cache, which means you can encounter messages which exist but are not in the cache. This can happen for most message events, e.g. the ReactionAddEvent. You can, however, interact with these messages without having them in the cache. Every message event has methods like event.deleteMessage(), event.editMessage("New Content"). If you need the message (e.g. to get its content), you can request it using event.requestMessage().
Additionally, you can use the static methods in the Message class which only require the channel and message id, e.g. Message.edit(api, channelId, messageId, "New content");. This is very useful if you want to store them in a database.
Webhooks and Invites
Webhooks and Invites are not kept in the cache at all and won't receive any updates.
Embeds
Embeds from message.getEmbed() won't receive updates. If a message's embed gets edited, getEmbed() will return a completely new embed object.
❓ When are cached entities updated?
Javacord's cache exclusively uses websocket events to keep the cache up to date. This means that the content of your objects might be outdated, even though you modified it yourself:
Messages message = ...;
+System.out.println(message.getContent()); // Prints the old content, e.g. "old content"
+message.edit("new content").join(); // Edits the message and waits for success
+System.out.println(message.getContent()); // Still prints "old content"
+Thread.sleep(1000);
+System.out.println(message.getContent()); // Most likely prints "new content" now
+⌚ How long are cached entities valid?
Even though entities are usually kept in the cache for a very long time, you should not keep references to these objects for a longer period of time, but store the id / use event methods:
// Bad
+Message message = ...;
+message.addReactionAddListener(event -> {
+ if (event.getEmoji().equalsEmoji("👎")) {
+ message.delete(); // Prevents "message" from being garbage collected
+ }
+});
+
+// Good
+Message message = ...;
+message.addReactionAddListener(event -> {
+ if (event.getEmoji().equalsEmoji("👎")) {
+ event.deleteMessage(); // Does not use the message object
+ }
+});
+// Bad
+Set<User> usersWithBadMood = new HashSet<>();
+api.addReactionAddListener(event -> {
+ if (event.getEmoji().equalsEmoji("😦")) {
+ usersWithBadMood.add(event.getUser());
+ }
+});
+
+// Good
+Set<Long> usersWithBadMood = new HashSet<>();
+api.addReactionAddListener(event -> {
+ if (event.getEmoji().equalsEmoji("😦")) {
+ usersWithBadMood.add(event.getUser().getId());
+ }
+});
+Some examples of when cached entities are invalidated:
- The bot lost its connection to Discord and had to reconnect (not resume)
- You weren't able to receive updates for an entity, e.g. for
Channel, because you left and rejoined a server
Performance Tweaks
✂️ Disabling Startup Wait
By default, Javacord waits for all servers and members to be loaded on startup. You can disable this behavior in the DiscordApiBuilder before logging in:
new DiscordApiBuilder()
+ .setToken("abc")
+ .setWaitForServersOnStartup(false)
+ .login()
+ .thenAccept(api -> {
+ // Do something
+ }).exceptionally(ExceptionLogger.get());
+Depending on the size of your bot, this can significantly speed up the login process. This comes with one downside however: The api.getServers() collection is empty directly after logging in. You will receive ServerBecomesAvailableEvents for every server which finished loading.
⚙️ Fine Tuning the Message Cache
In order to reduce memory usage, you can completely disable the message cache or reduce the number of cached messages. By default, Javacord caches up to 50 messages per channel and removes messages from the cache which are older than 12 hours. You can lower this limit by using DiscordApi#setMessageCacheSize(Capacity, StorageTimeInSeconds).
// Cache a maximum of 10 messages per channel for and remove messages older than 1 hour
+api.setMessageCacheSize(10, 60*60);
+You can even set this limit on a per-channel basis:
TextChannel channel = ...;
+channel.getMessageCache().setCapacity(10);
+channel.getMessageCache().setStorageTimeInSeconds(60*60);
+💎 Using the Updater classes
If you update several settings of an entity (server, channel, ...) at once, you should use the updater for this entity instead of the updateXyz(...) methods.
Example
// Sends 1 request to Discord
+ServerTextChannel channel = ...;
+new ServerTextChannelUpdater(channel)
+ .setName("example-channel")
+ .setTopic("This is an example channel")
+ .setNsfwFlag(true)
+ .update();
+instead of
// Sends 3 requests to Discord
+ServerTextChannel channel = ...;
+channel.updateName("example-channel");
+channel.updateTopic("This is an example channel");
+channel.updateNsfwFlag(true);
+Playing Audio
WARNING
Support for audio was added to Javacord very recently. If you encounter any bugs, please create an issue on GitHub!
Javacord allows your bot to connect to voice channels and play audio (e.g., music). This short tutorial gives you an introduction on how to connect to a voice channel and play your favorite music.
🔌 Connect to a voice channel
Connecting to a voice channel is very straight forward: Calling #connect() on an instance of ServerVoiceChannel will connect your bot to this voice channel and return a future with an AudioConnection object.
Example
The following example will connect the bot to the voice channel of the user that typed !music in the chat:
ServerVoiceChannel channel = ...;
+channel.connect().thenAccept(audioConnection -> {
+ // Do stuff
+}).exceptionally(e -> {
+ // Failed to connect to voice channel (no permissions?)
+ e.printStackTrace();
+ return null;
+});
+👂 Playing music
There are plenty of sources for audio (e.g., YouTube, local files, etc.). The current de facto standard library for extracting audio from these sources with Java is the LavaPlayer library.
To use it with Javacord, you have to add it as a dependency to your project (e.g., with Gradle or Maven) and create a Javacord audio source like this:
public class LavaplayerAudioSource extends AudioSourceBase {
+
+ private final AudioPlayer audioPlayer;
+ private AudioFrame lastFrame;
+
+ /**
+ * Creates a new lavaplayer audio source.
+ *
+ * @param api A discord api instance.
+ * @param audioPlayer An audio player from Lavaplayer.
+ */
+ public LavaplayerAudioSource(DiscordApi api, AudioPlayer audioPlayer) {
+ super(api);
+ this.audioPlayer = audioPlayer;
+ }
+
+ @Override
+ public byte[] getNextFrame() {
+ if (lastFrame == null) {
+ return null;
+ }
+ return applyTransformers(lastFrame.getData());
+ }
+
+ @Override
+ public boolean hasFinished() {
+ return false;
+ }
+
+ @Override
+ public boolean hasNextFrame() {
+ lastFrame = audioPlayer.provide();
+ return lastFrame != null;
+ }
+
+ @Override
+ public AudioSource copy() {
+ return new LavaplayerAudioSource(getApi(), audioPlayer);
+ }
+}
+With this audio source, you can now start using Lavaplayer, e.g. to play a YouTube video:
// Create a player manager
+AudioPlayerManager playerManager = new DefaultAudioPlayerManager();
+playerManager.registerSourceManager(new YoutubeAudioSourceManager());
+AudioPlayer player = playerManager.createPlayer();
+
+// Create an audio source and add it to the audio connection's queue
+AudioSource source = new LavaplayerAudioSource(api, player);
+audioConnection.setAudioSource(source);
+
+// You can now use the AudioPlayer like you would normally do with Lavaplayer, e.g.,
+playerManager.loadItem("https://www.youtube.com/watch?v=NvS351QKFV4", new AudioLoadResultHandler() {
+ @Override
+ public void trackLoaded(AudioTrack track) {
+ player.playTrack(track);
+ }
+
+ @Override
+ public void playlistLoaded(AudioPlaylist playlist) {
+ for (AudioTrack track : playlist.getTracks()) {
+ player.playTrack(track);
+ }
+ }
+
+ @Override
+ public void noMatches() {
+ // Notify the user that we've got nothing
+ }
+
+ @Override
+ public void loadFailed(FriendlyException throwable) {
+ // Notify the user that everything exploded
+ }
+});
+Proxies
There are basically two kinds of proxies: HTTP proxies and SOCKS proxies. Both may or may not support or require authentication depending on version, capabilities, and configuration. Due to the underlying libraries used, currently, Javacord fully supports HTTP proxies and partially supports SOCKS proxies.
Javacord uses HTTPS connections to communicate with the Discord REST API and a WSS connection to communicate with the Discord WebSocket endpoint. Both these protocols are secure protocols and thus do not honor settings for HTTP connections, only settings for HTTPS connections.
👨💻 Configuring a Proxy ...
... using System Properties
If you did not explicitly set a proxy in the DiscordApiBuilder and did not set a system default ProxySelector, the default proxy selector of the JRE is used. This proxy selector honors, amongst others, the relevant standard system properties https.proxyHost, https.proxyPort, socksProxyHost, socksProxyPort, and socksProxyVersion. Use the former two to configure an HTTP proxy, or the latter three to configure a SOCKS proxy, although you will not need socksProxyVersion, as SOCKS4 is currently not supported.
... using a System Default Proxy Selector
You can use java.net.ProxySelector.setDefault(ProxySelector) to set a system default proxy selector that replaces the default one. In its implementation, you can dynamically determine which proxy to use for each connection.
... using an Explicitly Set Proxy
Using the method DiscordApiBuilder.setProxy(Proxy) you can set a proxy instance directly in the DiscordApiBuilder that is solely used for Javacord connections and does not affect the unrelated code running in the JVM.
... using an Explicitly Set Proxy Selector
Using the method DiscordApiBuilder.setProxySelector(ProxySelector) you can set a proxy selector instance directly in the DiscordApiBuilder that is solely used for Javacord connections and does not affect the remaining code running in the JVM. In its implementation, you can dynamically determine which proxy to use for each connection.
Precedence of the Configuration Options
- if an explicit proxy is set, it is used
- if an explicit proxy selector is set, it is used
- if both an explicit proxy and an explicit proxy selector are set, this is a configuration error and will cause an exception to be thrown
- if neither explicit option is set, the system default proxy selector is used
- if no system default proxy selector was explicitly set, the JRE default that honors the system properties is used
🔑 Configuring Proxy Authentication ...
... using a System Default Authenticator
You can use java.net.Authenticator.setDefault(Authenticator) to set a system default authenticator that is used to provide username and password pairs for connections. This authenticator is only used if the proxy supports the Basic authentication scheme. If you need to support any other authentication scheme, use an explicitly configured authenticator. The java.net.Authenticator interface is too inflexible to support this.
... using an Explicitly Set Authenticator
Using the method DiscordApiBuilder.setProxyAuthenticator(Authenticator), you can set a custom authenticator that is much more powerful than the java.net.Authenticator. You get much more information about the connection to be established, and you can return any HTTP header that is necessary for a successful authentication. This should cover all sorts of available authentication mechanisms.
💡 Proxy Types
HTTP
HTTP proxies are fully supported.
SOCKS 4
SOCKS 4 is currently not supported.
The WebSocket library we use does not support SOCKS proxies at all, and the HTTP library we use has a bug that prevents SOCKS 4 to be used. Additionally, you would need to use at least Java 9 or a separate socket factory supporting SOCKS 4, as the JRE implementation is not working in Java 8 and got fixed only in Java 9+.
SOCKS 4a
SOCKS 4a is currently only partially supported.
The WebSocket library we use does not support SOCKS proxies at all, so it could be used for the REST connections only. Additionally, you would need to use a separate socket factory supporting SOCKS 4a, as the JRE implementation is not capable of doing SOCKS 4a, only SOCKS 4 and SOCKS 5 are supported at the time of creation of this wiki article.
SOCKS 5
SOCKS 5 is currently only partially supported.
The WebSocket library we use does not support SOCKS proxies at all, so it could be used for the REST connections only.
Ratelimits
Ratelimits is a Discord restriction which prevents you from performing actions in a very fast rate. Most ratelimits are on a per-channel or a per-server basis.
❗ The Most Important Ratelimits
| Action | Ratelimit | Type |
|---|---|---|
| Send Messages | 5 / 5s | per channel |
| Delete Messages | 5 / 1s | per channel |
| Add/Remove Reactions | 1 / 0.25s | per channel |
| Edit Server Members | 10 / 10s | per server |
| Edit Member Nickname | 1 / 1s | per server |
| Edit Bot Username | 2 / 1h | per account |
| Update Channels | 2 / 10m | per account |
| All Actions Combined | 50 / 1s | per account |
💪 Dealing with Ratelimits
Usually Javacord takes care about these limitations for you. As a user, there's nothing you have to do, but you should at least know that ratelimits exist.
Example
The following code
// Who even needs loops?
+channel.sendMessage("Ratelimit Example #1");
+channel.sendMessage("Ratelimit Example #2");
+channel.sendMessage("Ratelimit Example #3");
+channel.sendMessage("Ratelimit Example #4");
+channel.sendMessage("Ratelimit Example #5");
+channel.sendMessage("Ratelimit Example #6");
+channel.sendMessage("Ratelimit Example #7");
+channel.sendMessage("Ratelimit Example #8");
+channel.sendMessage("Ratelimit Example #9");
+channel.sendMessage("Ratelimit Example #10");
+channel.sendMessage("Ratelimit Example #11");
+channel.sendMessage("Ratelimit Example #12");
+would look like this in the client:
You can clearly see the delay between every 5 sent messages.
❌ Can I disable ratelimits?
No. Ratelimits are a limitation from Discord itself, which you cannot circumvent.
Sharding
Discord allows (and forces) you to "split" larger bots into several independent parts. This behavior is called "sharding", and the independent parts are called "shards". You can think of shards as completely independent bots. Every shard is responsible for a disjoint set of servers.
👩🏭 Sharding in Javacord
Logging in with a single shard
Logging in with a single shard is pretty much the same as logging in without sharding:
DiscordApi api = new DiscordApiBuilder()
+ .setToken("top secret")
+ .setCurrentShard(0)
+ .setTotalShards(2)
+ .login().join();
+System.out.println("Shard " + api.getCurrentShard() + " logged in!");
+Note:
current shardstarts counting at0! This means in the example above you would have current shard0and shard1with atotal amountof2shards.
Important: There must be a > 5-second delay between each shard-login
Logging in with a fixed amount of shards
You can manually set a fixed amount of total shards and log in all of them:
public class Main {
+
+ public static void main(String[] args) {
+ new DiscordApiBuilder()
+ .setToken("top secret")
+ .setTotalShards(10)
+ .loginAllShards()
+ .forEach(shardFuture -> shardFuture
+ .thenAcceptAsync(Main::onShardLogin)
+ .exceptionally(ExceptionLogger.get())
+ );
+ }
+
+ private static void onShardLogin(DiscordApi api) {
+ System.out.println("Shard " + api.getCurrentShard() + " logged in!");
+ // You can treat the shard like a normal bot account, e.g. registering listeners
+ api.addMessageCreateListener(event -> {
+ // ...
+ });
+ }
+
+}
+loginAllShards() returns a collection with completable futures (Collection<CompletableFuture<DiscordApi>>). This method automatically obeys the > 5-second delay rule.
Using the recommended shard amount
You can "ask" Discord to recommend you a total amount of shards. This is done by using the DiscordApiBuilder#setRecommendedTotalShards() method, which returns a CompletableFuture<DiscordApiBuilder> after getting the required information.
public class Main {
+
+ public static void main(String[] args) {
+ new DiscordApiBuilder()
+ .setToken("top secret")
+ .setRecommendedTotalShards().join()
+ .loginAllShards()
+ .forEach(shardFuture -> shardFuture
+ .thenAccept(Main::onShardLogin)
+ .exceptionally(ExceptionLogger.get())
+ );
+ }
+
+ private static void onShardLogin(DiscordApi api) {
+ // ...
+ }
+
+}
+💡 Behavior of Shards
Managed servers
You can calculate for which servers a shard is responsible using the server id:
boolean isResponsible = (serverId >> 22) % totalShards == currentShard;
+Private messages
Private messages are always sent to the first shard (currentShard == 0).
When do I need sharding?
Sharding is forced for bots which are in more than 2500 servers.
🌄 Sharding for Very Large Bots
Sharding for very large bots (> 150,000 servers) is a bit different from "normal" sharding. Discord will contact you once your bot reaches this state. Additional information can be found in the official Discord api documentation.
Creating Channels, Invites, etc.
Javacord provides XyzBuilder classes to create new Discord entities like channels, webhooks, servers, and many more.
📕 Create Channels
You can get the channel builders for a specific server using the Server#createXyzChannelBuilder or by directly calling the constructor. Creating a ServerVoiceChannel would look like this:
Server server = ...;
+ServerVoiceChannel channel = new ServerVoiceChannelBuilder(server)
+ .setName("example-channel")
+ .setUserlimit(10)
+ .create().join();
+📗 Create Webhooks
You can get the WebhookBuilder for a specific text channel:
ServerTextChannel channel = ...;
+Webhook webhook = new WebhookBuilder(channel)
+ .setName("Captain Hook")
+ .setAvatar(new File("C:/Users/Bastian/Pictures/puppy.jpg"))
+ .create().join();
+📘 Create Invites
You can get the InviteBuilder for a specific server channel:
ServerTextChannel channel = ...;
+Invite invite = new InviteBuilder(channel)
+ .setMaxAgeInSeconds(60*60*24)
+ .setMaxUses(42)
+ .create().join();
+📙 Create Servers
You can get the ServerBuilder from the current api instance:
DiscordApi api = ...;
+long serverId = new ServerBuilder(api)
+ .setName("My Awesome Server")
+ .setIcon(api.getYourself().getAvatar())
+ .setVerificationLevel(VerificationLevel.HIGH)
+ .setDefaultMessageNotificationLevel(DefaultMessageNotificationLevel.ONLY_MENTIONS)
+ .setRegion(Region.EU_CENTRAL)
+ .create().join();
+WARNING
By default, bots can only create servers if they are in less than 10 servers. You can contact the Discord support to request a higher limit.
Embeds
Embeds are attached to messages and have a special design. The usually look like this:
🔨 Creating an Embed
Javacord provides an EmbedBuilder which can be used to create embeds:
// Create the embed
+EmbedBuilder embed = new EmbedBuilder()
+ .setTitle("Title")
+ .setDescription("Description")
+ .setAuthor("Author Name", "http://google.com/", "https://cdn.discordapp.com/embed/avatars/0.png")
+ .addField("A field", "Some text inside the field")
+ .addInlineField("An inline field", "More text")
+ .addInlineField("Another inline field", "Even more text")
+ .setColor(Color.BLUE)
+ .setFooter("Footer", "https://cdn.discordapp.com/embed/avatars/1.png")
+ .setImage(new File("C:/Users/Bastian/Pictures/puppy.jpg"))
+ .setThumbnail(new File("C:/Users/Bastian/Pictures/kitten2.png"));
+// Send the embed
+channel.sendMessage(embed);
+📷 Supported Image Sources
By default, Discord expects embed images to be a link (e.g., the image link used in setFooter(...)), but you can also use attachments for images. If you provide a non-url image source (e.g. the puppy.jpg file used in setImage(...)), Javacord automatically uploads them as an attachment to the message and uses this attachment for the embed.
🔒 Embed Limits
| Type | Limit |
|---|---|
| Title | 256 characters |
| Description | 4096 characters |
| Field Amount | Up to 25 fields |
| Field Name | 256 characters |
| Field Value | 1024 characters |
| Footer Text | 2048 characters |
| Author Name | 256 characters |
In addition to the limits above, the sum of all characters in an embed structure must not exceed 6000 characters.
❓ FAQ
What is the second parameter of setAuthor(...)?
.setAuthor("Author Name", "http://google.com/", "https://cdn.discordapp.com/embed/avatars/0.png")
+- First parameter: The name of the author
- Second parameter: A link for the author (e.g. their homepage). Can be
null. - Third parameter: The avatar of the author
What's the difference between an inline field and a normal one?
Normal fields always start in a new line, whereas several inline fields can be in the same line.
Can I change the placement of inline fields?
No, Discord does not allow different embed layouts.
How can I format text in an embed?
Discord allows for a subset of markdown to be used. See their docs for the specifics.
Emojis and Reactions
There are two different kinds of emojis in Discord: Unicode emojis and custom emojis.
🚴♂️ Unicode Emojis
What are Unicode emojis?
Unicode emojis are "normal" text emojis which are supported by (nearly) all chat clients, including Discord. You can find a list with all Unicode emojis here: Full Emoji List.
How to use them in messages
You can either directly add them in your code, e.g.
channel.sendMessage("Hi! 😃");
+or use the normal "tag" like you would in the Client:
channel.sendMessage("Hi! :smiley:");
+
How to use them for reactions
Adding unicode reactions is only possible by using the "real" reaction. It doesn't support tags like :smiley:.
message.addReaction("😃"); // works
+message.addReaction(":smiley:"); // doesn't work
+
🤸♀️ Custom Emojis
What are custom emojis?
Custom emojis are emojis that are created in a server. You can get all custom emojis the bot knows by using DiscordApi#getCustomEmojis().
How to use them in messages
To use custom emojis, you have to know its "tag", which has the format <:name:id>. You can get it by calling CustomEmoji#getMentionTag():
channel.sendMessage("Hi! <:javacord:415465982715494402>");
+CustomEmoji emoji = ...;
+channel.sendMessage("Hi! " + emoji.getMentionTag());
+How to use them for reactions
You can either directly use the custom emoji object or use the tag without the <: > if you don't have access a custom emoji object (e.g., because it's from a different shard):
CustomEmoji emoji = ...;
+message.addReaction(emoji);
+message.addReaction("javacord:415465982715494402");
+How to get the tag
Just add a \ in front of the emoji and press Enter
👑 Javacord Emoji "Hierarchy"
In Javacord, all Emojis are a child of the Emoji interface:
What is a KnownCustomEmoji?
Known custom emojis are emojis that the bot knows because it's a member of the server with this emoji. A custom emoji can be unknown if someone adds a reaction with an unknown emoji for example. A KnownCustomEmoji has additional methods like getServer() or updateName(String).
👌 Recommended libraries
If you are working a lot with Unicode emojis, it's recommended to use a library like JEmoji. It enables you to do things like the following:
message.addReaction(EmojiManager.getByAlias(":thumbsup:"));
+Gateway Intents
Discord allows you to "subscribe" to specific groups of events. These "subscriptions" are called intent. Disabling intents that are not required for your bot can significantly increase your bot's performance.
📋 List of Intents
Below you can find a table with all intents supported by Discord.
| Intent | Safe to Disable | Privileged |
|---|---|---|
GUILDS | ❌ | ❌ |
GUILD_MEMBERS | ✔️ | ✔️ |
GUILD_BANS | ⚠️* | ❌ |
GUILD_EMOJIS | ⚠️* | ❌ |
GUILD_INTEGRATIONS | ✔️ | ❌ |
GUILD_WEBHOOKS | ✔️ | ❌ |
GUILD_INVITES | ✔️ | ❌ |
GUILD_VOICE_STATES | ⚠️* | ❌ |
GUILD_PRESENCES | ✔️ | ✔️ |
GUILD_MESSAGES | ✔️ | ❌ |
GUILD_MESSAGE_REACTIONS | ✔️ | ❌ |
GUILD_MESSAGE_TYPING | ✔️ | ❌ |
DIRECT_MESSAGES | ✔️ | ❌ |
DIRECT_MESSAGE_REACTIONS | ✔️ | ❌ |
DIRECT_MESSAGE_TYPING | ✔️ | ❌ |
MESSAGE_CONTENT | ✔️ | ✔️ |
AUTO_MODERATION_CONFIGURATION | ✔️ | ❌ |
AUTO_MODERATION_EXECUTION | ✔️ | ❌ |
* Will most likely work, but needs further testing
Good to know!
Guild is a synonym for servers, commonly used in Discord's API. See Glossary.
💡 What Happens When I Disable Some Intents?
When you disable some of the listed intents, Javacord will not fire events that belong to the intents and will not update these specific parts of the cache.
At the moment, we don't have a list which events are affected by which intents (but it will come soon™️). However, most intents should be self-explanatory. E.g. when you disable the DIRECT_MESSAGES intent, your bot will not receive any private messages.
👑 Privileged Intents
Some intents are defined as "privileged" due to the sensitive nature of the data. To use these intents, you have to go to your bot in the Developer Portal (where you created bot) and manually enable the intents:
There are some additionally restrictions for bots that are in over 100 servers:
- Your bot must be verified
- Your bot must be whitelisted to use this intents
Take a look at the official article from Discord about this topic and how to verify your bot: Bot Verification and Data Whitelisting.
❗ Notable Intents
The following two intents are especially noteworthy: GUILD_MEMBERS and GUILD_PRESENCES. Besides being privileged, they have some special implications for Javacord:
GUILD_PRESENCES
This intent is required to get updates about a user's status (i.e., if they are online, what game they are playing, ...). Additionally, without this intent it might take considerably longer to cache all users because of ratelimits (up to 10 minutes for shards with 1000 servers). It is advised against setting DiscordApiBuilder#setWaitForAllUsersOnStartup(true) without this intent, unless absolutely necessary.
GUILD_MEMBERS
This intent is required to keep all users in Javacord's cache. Without this intent, methods like Server#getMembers() or DiscordApi#getCachedUsers() will return empty collections. However, you will still be able to access users from objects like messages, e.g. Message#getUserAuthor() will still work.
MESSAGE_CONTENT
This intent is a bit different to the other as it does not act as a toggle to receive any events. It's sole purpose is to receive the message content, attachments, components, and embeds. Otherwise, these fields will be empty when you receive a Message object.
⚙️ Setting Intents
Javacord allows you to specify intents in the DiscordApiBuilder prior to login. There are many options to set intents. The following example code shows the most common ones:
Set All Non-Privileged Intents (Default)
This method enables all non-privileged intents. This is the default setting in Javacord.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .setAllNonPrivilegedIntents()
+ .login()
+ .join();
+Set All Non-Privileged Intents Except
This method enabled all non-privileged intents, except the given ones.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .setAllNonPrivilegedIntentsExcept(Intent.GUILD_WEBHOOKS)
+ .login()
+ .join();
+Set All Intents
This method enabled all intents.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .setAllIntents()
+ .login()
+ .join();
+Set All Intents Except
This method enabled all intents, except the given ones.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .setAllIntentsExcept(Intent.GUILD_PRESENCES, Intent.GUILD_WEBHOOKS)
+ .login()
+ .join();
+Set Intents
This method only enables the given intents.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .setIntents(Intent.GUILDS, Intent.DIRECT_MESSAGES)
+ .login()
+ .join();
+Add Intents
This method adds the intents to the currently enabled ones(by default all non-privileged). This is useful i.e. if you only want to enable 1 privileged intent like the MESSAGE_CONTENT
DiscordApi api = new DiscordApiBuilder()
+ .setToken("topc secret")
+ .addIntents(Intent.MESSAGE_CONTENT)
+ .login()
+ .join();
+Glossary
This is a list with the most common Discord-related terms:
Guild- A synonym forserverSelfbot- A client account bot, usually logged in to a user's own accountSharding- Splitting a bot into several independentshards, see ShardingToken- Used to login instead of requiring a username + passwordEmbed- A "fancy" message, see Embed FAQRatelimit- Prevents you from spamming actions, see Ratelimit FAQWebsocket- A TCP "connection" to Discord that receives events, see WikipediaGateway- The address for thewebsocketRest/Rest Request- REST is used to perform actions like sending messages. Rest Requests do not require an active websocket connection.Activity- The text underneath the username, usuallyPlaying XyzRich Presence- A more detailed activity, see Discord Docs
Interaction Commands aka. Slash Commands
INFO
There are a lot of convenient methods which aim to make your life easier with i.e., not being able to have an invalid configuration of your builder. Therefore, the following examples will only show the usage with the convenient methods.
💡 Creating a Command
INFO
There are 2 different types of Commands:
- Global | Available for every Server once your Bot gets invited: Created with
createGlobal(DiscordApi). - Server | Only available on the specific Server: Created with
createForServer(Server).
Let's get started with the most basic command, a ping command.
SlashCommand command = SlashCommand.with("ping", "Checks the functionality of this command")
+ .createGlobal(api)
+ .join();
+That's all you have to do!
Let's have a look at a more complex command which involves nearly all possibilities:
SlashCommand command =
+ SlashCommand.with("channel", "A command dedicated to channels",
+ Arrays.asList(
+ SlashCommandOption.createWithOptions(SlashCommandOptionType.SUB_COMMAND_GROUP, "edit", "Edits a channel",
+ Arrays.asList(
+ SlashCommandOption.createWithOptions(SlashCommandOptionType.SUB_COMMAND, "allow", "Allows a permission to a user for a channel",
+ Arrays.asList(
+ SlashCommandOption.create(SlashCommandOptionType.CHANNEL, "channel", "The channel to modify", true),
+ SlashCommandOption.create(SlashCommandOptionType.USER, "user", "The user which permissions should be changed", true),
+ SlashCommandOption.createWithChoices(SlashCommandOptionType.DECIMAL, "permission", "The permission to allow", true,
+ Arrays.asList(
+ SlashCommandOptionChoice.create("manage", 0),
+ SlashCommandOptionChoice.create("show", 1)))
+ ))))))
+ .createGlobal(api)
+ .join();
+Let that sink in first!
What are we doing here?
- We create a base command called
channel. - It has a SUB_COMMAND_GROUP called
editwhich basically is just a folder where you can put your commands in. - There's a SUB_COMMAND called
allowwhich is our actual command. Therefore, our complete argument looks likechannel edit allow. - The SUB_COMMAND has 3 arguments:
- The channel which should be edited.
- The user which permissions should be changed.
- A predefined list of available permissions the command executor can choose of.
📔 Notes on creating commands:
The REQUIRED attribute
You can only mark the last argument as being not required. This means it can be optionally set by the command executor. In the above example you could i.e. set the PERMISSIONS argument to false.
Command structure
Your command has to follow these structures in order to be successfully created:
Command structure
VALID
+
+command
+|
+|__ subcommand
+|
+|__ subcommand
+
+----
+
+command
+|
+|__ subcommand-group
+ |
+ |__ subcommand
+|
+|__ subcommand-group
+ |
+ |__ subcommand
+
+----
+
+VALID
+
+command
+|
+|__ subcommand-group
+ |
+ |__ subcommand
+|
+|__ subcommand
+
+-------
+
+INVALID
+
+
+command
+|
+|__ subcommand-group
+ |
+ |__ subcommand-group
+|
+|__ subcommand-group
+ |
+ |__ subcommand-group
+
+----
+
+INVALID
+
+command
+|
+|__ subcommand
+ |
+ |__ subcommand-group
+|
+|__ subcommand
+ |
+ |__ subcommand-group
+⤵️ Get your commands
All global commands:
Set<SlashCommand> commands = api.getGlobalSlashCommands().join();
+All commands only available on a single server:
Server server = ...;
+Set<SlashCommand> commands = api.getServerSlashCommands(server).join();
+WARNING
Getting all commands from a server only contains the commands you have created on this specific server. Therefore, the returned list does not include any global command!
🔨 Updating Commands
When updating your commands you only have to include what you actually want to change. The following updater will change the previous created command and change its base name from channel to channels.
SlashCommand updatedCommand =
+ new SlashCommandUpdater(commandId)
+ .setName("channels")
+ .updateGlobal(api)
+ .join();
+✍️ Bulk overwriting commands
If you have to update / create multiple commands at once it advised to use the batch updater to only have to do 1 request.
DiscordApi api = ...;
+
+Set<SlashCommandBuilder> builders = new HashSet<>();
+builders.add(new SlashCommandBuilder().setName("server").setDescription("A command for the server"));
+builders.add(new SlashCommandBuilder().setName("permission").setDescription("A command for permissions"));
+
+api.bulkOverwriteGlobalApplicationCommands(builders).join();
+👮♂️ Permissions
Permissions exist to enable / disable the usage of your commands for certain things. These things may be:
- Permissions
- DMs
When you create a command you can specify which permissions are required to use it. In addition to the required permissions, you can also specify whether the command should be available in DMs.
SlashCommand.with("ping","Ping!")
+ .setDefaultEnabledForPermissions(PermissionType.ADMINISTRATOR, PermissionType.BAN_MEMBERS)
+ //.setDefaultDisabled() Effectively the same as setDefaultEnabledForPermissions(PermissionType.ADMINISTRATOR) but this will lead to the default type by Discord.
+ .setEnabledInDms(false)
+ .createGlobal(api)
+ .join();
+INFO
Once your bot has been invited to a server, you can not change the permissions afterwards on this server. Then it's up to the server administrators / owner to correctly set up the commands for users / roles / channels.
❗ Limits
Registering a command
- Server commands are specific to the server you specify when making them. Server commands are not available in DMs. Command names are unique per application within each scope (global and server). That means:
- Your app cannot have two global commands with the same name
- Your app cannot have two server commands within the same name on the same guild
- Your app can have a global and guild command with the same name
- Multiple apps can have commands with the same names
General
- An app can have up to 100 top-level global commands with unique names
- An app can have up to an additional 100 server commands per server
- An app can have up to 25 subcommand groups on a top-level command
- An app can have up to 25 subcommands within a subcommand group
- Commands can have up to 25 options
- Options can have up to 25 choices
- Maximum of 4000 characters for combined name, description, and value properties for each command and its subcommands and groups
- Limitations on nesting subcommands and groups
- Global rate limit of 200 slash command creates per day per server
Message Components
❔ What are components?
Components are interactive elements like buttons or hidden elements like the ActionRow which use is for displaying the visible components. You can add them to a message and interact with users in a very convenient way. Currently, the only interactive components available at the moment are buttons. They differ in style and behaviour(link redirect) seen in the picture below:
💡 Sending a message with a component
Sending a component with your message is a simple as that:
TextChannel channel = ...;
+
+new MessageBuilder()
+ .setContent("Click on one of these Buttons!")
+ .addComponents(
+ ActionRow.of(Button.success("success", "Send a message"),
+ Button.danger("danger", "Delete this message"),
+ Button.secondary("secondary", "Remind me after 5 minutes")))
+ .send(channel);
+
You simply add a High Level component like an ActionRow which is a container for displaying your components. In turn the ActionRow consist of the components you can interact with like Buttons.
This works for Select Menus as well:
TextChannel channel = ...;
+
+new MessageBuilder()
+ .setContent("Select an option of this list!")
+ .addComponents(
+ ActionRow.of(SelectMenu.create("options", "Click here to show the options", 1, 1,
+ Arrays.asList(SelectMenuOption.create("Option One", "You selected Option One!", "Click here to select Option One"),
+ SelectMenuOption.create("Option Two", "You selected Option Two!", "Click here to select Option Two"),
+ SelectMenuOption.create("Option Three", "You selected Option Three!", "Click here to select Option Three")))))
+ .send(channel);
+
Interactions
Interactions are a means of accepting user input through Discord. They have been introduced to provide a more standardized, controlled way for commands than parsing messages. They can even be used with applications that do not provide a bot user.
💬 Message Commands
The "old" way of doing commands was done through parsed text messages, like !ping, !userinfo James or !mute James 100s. While such commands are easy in theory, they come with several problems, such as:
- Conflicts between Bots using the same command format / prefix.
- Bots have to be able to read all messages and find those that are directed at them
- Information about command structure can only be provided in info texts and error messages
✉️ Interaction Types
Interactions come in a variety of shapes. The most complex and versatile is the command interaction, which allows for commands directed at a particular bot with information and assistance on subcommands and parameters being integrated into the discord client.
Context Menu commands are available from the context menu in the client either on a message or a server member.
Message components come in the flavor of buttons, select menus and other form elements and can be attached directly to a message.
♻️ Lifecycle
INFO
Creation of interactions is detailed on the pages linked in the previous section.
Unlike chat message commands, interactions and interaction commands need to be registered with Discord. In order for a bot's interactions to be available in a server, the bot must be added to the server with the applications.commands OAUTH scope. The scope is included in links created by DiscordApi#createInviteLink. If your bot is older, it may need to be invited with the new link to add the scope. It is not necessary to remove the bot from the server to do this.
📈 Advantages
While being more complicated to utilize, interactions have many benefits over pure text commands.
- Better Validation: Commands can not be sent with parameters of the wrong type or missing required parameters
- No conflicts: Interactions are separated by bot and only sent to the proper bot
- "Privacy": If no public response is sent by the bot, the exchange is invisible to other chat participants
- Integration: Interactions are integrated into the client's user interface
- Conversations: Message components can be used in replies to interactions, allowing for nested dialogues.
WARNING
If a bot replies to a slash command with a public message, the command used, including all parameters, is visible to other users.
🤖 Applications vs. Bots
Interactions can used by any application, not only bots. While interactions can also be handled through webhooks, Javacord only offers support for dealing with them through the gateway. See the Discord Documentation for more information.
WARNING
The methods of handling interactions can not be mixed. If you register a webhook for your interaction commands, the bot will no longer receive any interaction events.
🔍 See also
Responding to interactions
There are many ways to respond to interactions and some are only available for certain interactions. The following will be usable for every interaction.
💬 Responding immediately after receiving an interaction.
event.getInteraction()
+ .createImmediateResponder()
+ .setContent("YOUR_RESPONSE")
+ .respond();
+INFO
Note that you have to respond withing 3 seconds, or the command will fail. If you need longer than 3 seconds you have to respond with respondLater() which allows you to respond within 15 minutes.
Because of this time limitation, sending any files when creating an immediate response is not possible. If you want a file to be embedded either use respondLater or include a web link in the message content. Depending on the media type of the link and the server configuration, Discord will then display an appropriate embed for the file.
When you want to respond ephemerally, you can use the setFlags method. Your new responder would look like the following:
event.getInteraction()
+ .createImmediateResponder()
+ .setContent("YOUR_RESPONSE")
+ .setFlags(MessageFlag.EPHEMERAL)
+ .respond();
+💬 Responding after some time when receiving an interaction.
If your computations takes longer than the 3 seconds limit, you can respond later and the Discord Client will show that your bot is thinking until you respond.
event.getInteraction()
+ .respondLater()
+ .thenAccept(interactionOriginalResponseUpdater -> {
+ interactionOriginalResponseUpdater.setContent("Update message after some time").update();
+ });
+You can respond ephemerally when responding later too. For that you have pass a true boolean to the respondLater method.
event.getInteraction()
+ .respondLater(true)
+ .thenAccept(interactionOriginalResponseUpdater -> {
+ interactionOriginalResponseUpdater.setContent("Update message after some time").update();
+ });
+Sending followup messages
Followup messages can be sent within 15 minutes after the command has been invoked. You can send as many followup messages as you want.
api.addSlashCommandCreateListener(event -> {
+ SlashCommandInteraction slashCommandInteraction = event.getSlashCommandInteraction();
+ slashCommandInteraction.respondLater().thenAccept(interactionOriginalResponseUpdater -> {
+ interactionOriginalResponseUpdater.setContent("You will receive the answer in a few minutes!").update();
+
+ // time < 15 minutes
+
+ slashCommandInteraction.createFollowupMessageBuilder()
+ .setContent("Thank you for your patience, it took a while but the answer to the universe is 42")
+ .send();
+ });
+});
+Responding with a Modal
A modal is a popup dialog which can be shown when responding to an interaction. It focuses the users to explicitly fill out this form to continue with the workflow. Currently, only the TextInput (SelectMenu has been seen working too, but is not yet officially supported) is supported.
api.addMessageComponentCreateListener(event -> {
+ event.getInteraction().respondWithModal("modalId","Modal Title",
+ ActionRow.of(TextInput.create(TextInputStyle.SHORT, "text_input_id", "This is a Text Input Field")));
+});
+Which results in
💬 SlashCommand interaction only response methods
How to know what slash command was invoked?
For example, you have created a slash command with the name "settings" and a subcommand "color". If you want to check if exactly this command has been used, you can check it as follows:
api.addSlashCommandCreateListener(event -> {
+ SlashCommandInteraction interaction = event.getSlashCommandInteraction();
+ if (interaction.getFullCommandName().equals("settings color")) {
+ //Code if command matches the full name
+ }
+});
+Respond to an AutoComplete interaction triggered from a SlashCommand
api.addAutocompleteCreateListener(event -> {
+ event.getAutocompleteInteraction()
+ .respondWithChoices(Arrays.asList(
+ SlashCommandOptionChoice.create("one", 1),
+ SlashCommandOptionChoice.create("two", 2))
+ );
+});
+💬 Message Component interaction only response methods
When dealing with message components, you don't necessarily have to respond or update a message. You can simply acknowledge the interaction and let the user know that the task is done.
api.addMessageComponentCreateListener(event -> {
+ event.getMessageComponentInteraction().acknowledge();
+});
+A more complete example of how to respond to Component interactions
The following code snipped shows how you can respond to the example created in Components.
api.addMessageComponentCreateListener(event -> {
+ MessageComponentInteraction messageComponentInteraction = event.getMessageComponentInteraction();
+ String customId = messageComponentInteraction.getCustomId();
+
+ switch (customId) {
+ case "success":
+ messageComponentInteraction.createImmediateResponder()
+ .setContent("You clicked a button!")
+ .respond();
+ break;
+ case "danger":
+ messageComponentInteraction.getMessage().ifPresent(Message::delete);
+ break;
+ case "secondary":
+ messageComponentInteraction.respondLater().thenAccept(interactionOriginalResponseUpdater -> {
+ //Code to respond after 5 minutes
+ });
+ break;
+ case "options":
+ messageComponentInteraction.createImmediateResponder()
+ .setContent("You selected an option in a select menu!")
+ .respond();
+ break;
+ }
+});
+Listeners
👨🔧 Creating listeners
Creating listeners is extremely easy in Javacord. You can either use Java 8's lambda expressions to register listeners inline or just create a new class for them, if an inline listener would get too messy.
Inline Listeners
api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+});
+In their own class
api.addListener(new MyListener());
+and
public class MyListener implements MessageCreateListener {
+
+ @Override
+ public void onMessageCreate(MessageCreateEvent event) {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ }
+
+}
+Before logging in
Sometimes it might be useful to add listeners before calling the DiscordApiBuilder#login() method.
DiscordApi api = new DiscordApiBuilder()
+ // An inline listener
+ .addMessageCreateListener(event -> {
+ Message message = event.getMessage();
+ if (message.getContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ })
+ .addServerBecomesAvailableListener(event -> {
+ System.out.println("Loaded " + event.getServer().getName());
+ })
+ // A listener in their own class
+ .addListener(new MyListener())
+ // Alternative syntax that can be used for classes that require a DiscordApi parameter in their constructor
+ .addListener(MyListener::new)
+ .setToken("top secret")
+ .setWaitForServersOnStartup(false)
+ .login()
+ .join();
+Note: In most cases, it's enough to add listeners after logging in
Object listeners
Another cool feature is the ability to attach listeners directly to objects. An example where this can be useful is, for example, reacting to reactions. The following code would delete the message if someone adds a 👎 reaction.
message.addReactionAddListener(event -> {
+ if (event.getEmoji().equalsEmoji("👎")) {
+ event.deleteMessage();
+ }
+}).removeAfter(30, TimeUnit.MINUTES);
+Seems like the bot is very sensitive to criticism.
💣 Removing listeners
There are two ways to remove a listener:
Using the returned ListenerManager
Every time you register a listener, a ListenerManager is returned which can be used to unregister the listener:
ListenerManager<MessageCreateListener> listenerManager = api.addMessageCreateListener(event -> {
+ // Do stuff
+});
+
+listenerManager.remove();
+This manager also has some utility methods. You can, for example, remove a listener after a given time, which can be useful for object listeners:
message.addReactionAddListener(event -> {
+ // Do stuff
+}).removeAfter(30, TimeUnit.MINUTES);
+ Using the removeListener(...) method
You can remove any listener using the removeListener(...) method:
MyListener listener = new MyListener();
+api.addListener(listener);
+// ...
+api.removeListener(listener);
+Logger Configuration
Logging is an important tool to keep track of what is going on in your application. Javacord uses the Log4j 2 API, which allows you to use your favorite logging framework to log messages in your own code and have all logging messages end up in the same destination. In case you do not add your own logging framework, a fallback logger is used that logs to the console.
If you want more control, add a proper logging framework that supports your needs and configure it accordingly. You can for example configure log messages on a per-class level, change log levels during runtime, or log to a file or database.
🥈 Fallback Logger
Javacord's fallback logger is a simple Log4j logger which always logs INFO level and higher. It allows you to enable DEBUG and TRACE logging manually. As log levels are hierarchical, enabling TRACE will also implicitly enable DEBUG, and disabling DEBUG will also implicitly disable TRACE.
// Enable debug logging
+FallbackLoggerConfiguration.setDebug(true);
+
+// Enable trace logging
+FallbackLoggerConfiguration.setTrace(true);
+Changing the log level of the fallback logger only affects newly created loggers. Pre-existing loggers will not have their log level changed. So if you want to configure the fallback logger, you should do this as one of the first actions in your bot code. If you want to change log levels during runtime, you should use a proper logging framework like Log4j 2 Core or another library that supports this.
All fallback logger messages are printed to the standard output stream (System.out) and thus usually to your console. If you want to log to a file, database, or anything else, you should consider using a proper logging framework which allows you to configure this behavior.
This is how a log line from the fallback logger will look like:
<time with date ><level><logger name, usually the logging class > <message > <the thread context, here the shard number>
+2018-08-03 20:00:06.080+0200 DEBUG org.javacord.core.util.gateway.DiscordWebSocketAdapter Received HELLO packet {shard=0}
+🥇 Using a Proper Logging Framework
Adding a Logging Framework
Adding a logging framework of your choice is very straightforward. You can just add it as a dependency, and it will be detected by Log4j automatically. The following example adds Log4j 2 using Gradle:
dependencies { runtimeOnly 'org.apache.logging.log4j:log4j-core:2.17.0' }
+You can also use an SLF4J compatible logging framework using log4j-to-slf4j. The following example adds Logback Classic using Gradle:
dependencies {
+ runtimeOnly 'org.apache.logging.log4j:log4j-to-slf4j:2.17.0'
+ runtimeOnly 'ch.qos.logback:logback-classic:1.2.3'
+}
+Configure Your Logging Framework
- Log4j 2: Log4j configuration
- Logback Classic: Logback configuration
Logging the Relevant Shard
Javacord adds the relevant shard to each log message. The facility that stores this information has a different name depending on which logging framework you use. For Log4j 2, this is called Thread Context Map and can be added in a pattern layout with %X{shard}, or you can add the whole thread context map by using %X. For Logback Classic, it is called MDC and can be added with the same pattern expressions as for Log4j.
Using the MessageBuilder
The MessageBuilder class is a more powerful alternative to the TextChannel#sendMessage(...) method.
It can be used to construct more complex messages and supports some additional features that are not possible with a simple TextChannel#sendMessage(...) call.
🕵️♀️ Example
The following code
new MessageBuilder()
+ .append("Look at these ")
+ .append("awesome", MessageDecoration.BOLD, MessageDecoration.UNDERLINE)
+ .append(" animal pictures! 😃")
+ .appendCode("java", "System.out.println(\"Sweet!\");")
+ .addAttachment(new File("C:/Users/Bastian/Pictures/kitten.jpg"))
+ .addAttachment(new File("C:/Users/Bastian/Pictures/puppy.jpg"))
+ .setEmbed(new EmbedBuilder()
+ .setTitle("WOW")
+ .setDescription("Really cool pictures!")
+ .setColor(Color.ORANGE))
+ .send(channel);
+will be displayed like this:
📍 Allowed Mentions
The allowed mentions object lets you control what should be mentioned (pinged) in a message if it contains mentions.
The following code will ping:
- The user0
- All mentioned roles in the message
And will not ping:
- @everyone and @here
- The user1
AllowedMentions allowedMentions = new AllowedMentionsBuilder()
+ .addUser(user0.getId())
+ .setMentionRoles(true)
+ .setMentionEveryoneAndHere(false)
+ .build();
+
+ new MessageBuilder()
+ .setAllowedMentions(allowedMentions)
+ .append(user0.getMentionTag())
+ .append(user1.getMentionTag())
+ .append(role.getMentionTag())
+ .append(role2.getMentionTag())
+ .append("@everyone")
+ .send(channel);
+If you add a user to the mentions object and set setMentionUsers(true) it will ping every mentioned user. The same applies for setMentionRoles(true)
Running and Deploying your Bot
If you took the time to write a bot, at some point you'll also want to run it, either for use in production or for debugging from the IDE.
👷 Running from your IDE
While developing your bot, you will want to run your bot directly from the IDE in order to quickly test changes and new features. For this, create a Run/Debug Configuration in your IDE of choice with your bot's main class. Remember to also add any necessary parameters and environment variables.
A working Run/Debug configuration will also enable you to run your bot with a debugger. A debugger is often considered a developer's most important tool, so make sure to familiarize yourself with the debugging integration for your IDE of choice.
IntelliJ IDEA
This assumes your project is set up correctly, preferably with Gradle, can be built without errors, and does not yet have any run/debug configurations.
1. Locate and click the Add Configuration... button in the top bar next to the start button.
2. In the newly opened window, click the + button in the top left and select Application
3. Give a name for your configuration and select the module to use the classpath of (usually yourproject.main).
4. Select your Main class. Use the ... button to search for it or provide the fully qualified name. If it can not be found, you most likely selected the wrong module in step 3.
5. Optional: Set command line arguments and environment variables. For the environment variables, use the button to the right of the input field for a more convenient input window.
6. Click Apply to finalize the configuration, then OK to close the window.
7. Select your configuration in the drop-down menu and run or debug it with the buttons to the right.
Eclipse
This assumes your project is set up correctly, can be built without errors, and does not yet have any run/debug configurations.
1. In the menu bar, click "Run" then "Run Configurations...".
2. In the newly opened window, select "Java Application" on the left side, then click the leftmost button in the row above the tree view. A new configuration will appear.
3. Give a name to your configuration.
4. Set the project and the main class. To easily select it, use the "Browse..." and "Search..." buttons.
5. Optional: Set command line (and VM) arguments as well as environment variables in their respective tabs.
6. Click Apply to save your configuration, then Close to close the window.
7. Run or debug your bot via the Buttons in the top row, the Run menu, or the shortcuts Ctrl+F11 for running and F11 for debugging.
📦 Deploying and Running as a Standalone Application
Running from the IDE is only recommended during development and strongly discouraged for production use. Generally, you'll want your build tool to create a convenient distribution format for you to use.
Building a Distribution with Gradle
For Gradle, only two further steps are necessary for a basic application. On top of the steps described in the Getting Started Section, also add the Application Plugin and define your mainClass as the fully qualified name of your main class. If you're using an older version of Gradle (earlier than 6.4), the attribute is instead called mainClassName.
INFO
As with many Gradle solutions, there is actually a whole lot going on under the hood. The application plugin implicitly also applies the java and distribution plugins. Refer to the documentations of the involved plugins for more ways to fine-tune the process.
Your modified build file should now look similar to this:
plugins {
+ application
+}
+
+version = "1.0.0"
+
+java {
+ sourceCompatibility = JavaVersion.VERSION_1_8
+}
+
+application {
+ mainClass.set("com.github.yourname.BotMain")
+ // mainClassName.set("com.github.yourname.BotMain") // Gradle < 6.4
+}
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ implementation("org.javacord:javacord:{{latestVersion}}")
+}
+plugins {
+ id 'application'
+}
+
+version '1.0.0'
+
+java {
+ sourceCompatibility = JavaVersion.VERSION_1_8
+}
+
+application {
+ mainClass = 'com.github.yourname.BotMain'
+ // mainClassName = 'com.github.yourname.BotMain' // for Gradle versions < 6.4
+}
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ implementation 'org.javacord:javacord:{{latestVersion}}'
+}
+Now you can execute the distZip or distTar task with Gradle. The task will create a distribution and package it in an archive file that will be placed in the build/distributions directory. Extract the content of those files on your server or whichever machine you want to run your bot on.
The distribution usually only contains the directories bin and lib. From the distribution directory, run either bin/yourbot or bin/yourbot.bat, depending on whether you're running the bot on Linux / macOS or windows.
Building a Distribution with Maven
For Maven, add the Appassembler plugin to your pom.xml. The plugin will create a distribution, but not bundle it in a neat archive file, so we'll also add the assembly plugin. We'll bind both to the package lifecycle phase.
<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>appassembler-maven-plugin</artifactId>
+ <version>1.10</version>
+ <configuration>
+ <programs>
+ <program>
+ <mainClass>org.javacord.examplebot.Main</mainClass>
+ <id>examplebot</id>
+ </program>
+ </programs>
+ </configuration>
+ <executions>
+ <execution>
+ <id>create-distribution</id>
+ <phase>package</phase>
+ <goals>
+ <goal>assemble</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <version>3.3.0</version>
+ <configuration>
+ <descriptors>
+ <!-- This must match the location of the descriptor -->
+ <descriptor>src/assembly/distribution.xml</descriptor>
+ </descriptors>
+ </configuration>
+ <executions>
+ <execution>
+ <id>create-archive</id>
+ <phase>package</phase>
+ <goals>
+ <goal>single</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
+Sadly, none of the built-in assembly descriptors match our use case, so we'll put our custom one into src/assembly/distribution.xml:
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
+ <id>distribution</id>
+ <formats>
+ <!-- See https://maven.apache.org/plugins/maven-assembly-plugin/assembly.html for supported formats -->
+ <format>tar.gz</format>
+ <format>tar.bz2</format>
+ <format>zip</format>
+ </formats>
+ <fileSets>
+ <fileSet>
+ <!-- This will also include your project readme, license and similar files-->
+ <directory>${project.basedir}</directory>
+ <outputDirectory>/</outputDirectory>
+ <includes>
+ <include>README*</include>
+ <include>LICENSE*</include>
+ <include>NOTICE*</include>
+ </includes>
+ </fileSet>
+ <fileSet>
+ <!-- Change this if you reconfigured the appassembler output directory -->
+ <directory>${project.build.directory}/appassembler</directory>
+ <outputDirectory>/</outputDirectory>
+ </fileSet>
+ </fileSets>
+</assembly>
+Now when you execute mvn package, a distribution with start scripts for Windows and Linux/macOS will be generated which is then packaged into archive files for every format you specified in the assembly descriptor. You can find the raw distribution (without readme and license files) in target/appassembler and the archive files directly in target.
Running
After creating your distribution via Gradle or Maven and extracting/copying it to the machine you want to run it from, you should have a directory containing both a bin and a lib (or repo) directory. Depending on your platform, you can now run the bin/yourbot or bin/yourbot.bat script.
These automatically generated scripts will then invoke java with your dependencies on the classpath and run your main class. Your working directory will be the directory you ran the script from.
💩 Building a Fat Jar
Although it is an abuse of the way java works, sometimes you will be forced to create a fat jar, or an uber jar. This is a jar file that contains your application and all its dependencies. This is sometimes used as a lazy way of building a convenient distribution, but should be foregone in favor of the above mentioned distributions.
However, in some cases (more often than not Bukkit/Spigot addons) it is necessary to provide a fat jar, since the host application's loading mechanism can only handle singular jar files. If you are subject to such a case of bad design, please complain to the maintainer of whatever host application you are using, then use the following instructions to forsake all that is good and just and create a fat jar. Remember to grit your teeth the whole time.
With Gradle
For Gradle, use the shadow plugin. If you want the fat jar to be executable, you will need to specify a main class via the application plugin.
plugins {
+ id 'java'
+ # ...
+ id 'com.github.johnrengelman.shadow' version '7.1.2'
+}
+With gradlew shadowJar you can now create a shaded (fat) jar. It will be named build/libs/yourbot-1.0.0-all.jar or similar, according to your project settings.
With Maven
For Maven, add the maven-shade-plugin to your build. As with the other solutions, configure your main class.
Some of your dependencies might be signed .jar files. Unfortunately, this will likely break your fat jar. Remove the signatures by defining an exclusion filter as demonstrated below. Let the thought that you had to disable a security feature just to make this work serve as a reminder that creating a fat jar is not how jars are meant to be used.
<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-shade-plugin</artifactId>
+ <version>3.2.3</version>
+ <configuration>
+ <shadedArtifactAttached>true</shadedArtifactAttached>
+ <shadedClassifierName>fat</shadedClassifierName>
+ <transformers>
+ <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+ <manifestEntries>
+ <Main-Class>com.github.yourname.BotMain</Main-Class>
+ </manifestEntries>
+ </transformer>
+ </transformers>
+ <filters>
+ <filter>
+ <artifact>*:*</artifact>
+ <excludes>
+ <exclude>META-INF/*.SF</exclude>
+ <exclude>META-INF/*.DSA</exclude>
+ <exclude>META-INF/*.RSA</exclude>
+ </excludes>
+ </filter>
+ </filters>
+ </configuration>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <goals>
+ <goal>shade</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
+Running mvn package will now additionally create the yourbot-1.0.0-fat.jar.
Completable Futures
WARNING
This tutorial assumes that you are familiar with lambda expressions. Take a look at the lambda introduction first, if you are not!
As Javacord is heavily multithreaded, you must understand the concept of Futures in general, as well as their most common implementation, the CompletableFuture. This little introduction gives you a quick overview of the basics you need to know in order to work with Futures.
🤔 What the heck is a future?
A future is basically a wrapper, that will contain a value in the future but might not contain it right now. This is useful, if a method call requires some time and should not block the execution of your current code. You can easily see the difference with a primitive speed comparison:
long currentTime = System.currentTimeMillis();
+channel.sendMessage("Test 1");
+channel.sendMessage("Test 2");
+channel.sendMessage("Test 3");
+channel.sendMessage("Test 4");
+channel.sendMessage("Test 5");
+// Prints "4 ms"
+System.out.println((System.currentTimeMillis() - currentTime) + " ms");
+long currentTime = System.currentTimeMillis();
+channel.sendMessage("Test 1").join();
+channel.sendMessage("Test 2").join();
+channel.sendMessage("Test 3").join();
+channel.sendMessage("Test 4").join();
+channel.sendMessage("Test 5").join();
+// Prints "894 ms"
+System.out.println((System.currentTimeMillis() - currentTime) + " ms");
+TIP
join() blocks the current thread until the method finished. This will be explained later.
📖 Methods
join()
The join method blocks the current thread until the method finished. It returns the method's result or throws a CompletionException if anything failed.
The following example would create a new text channel in a given server and sends a message directly afterwards.
// Create the channel
+ServerTextChannel channel = new ServerTextChannelBuilder(server)
+ .setName("new-channel")
+ .create()
+ .join();
+// Send a message in the new channel
+Message message = channel.sendMessage("First!").join();
+// Adds an reaction to the message. Even though this method doesn't return anything,
+// join() ensures, that an exception is thrown in case something went wrong
+message.addReaction("👍").join();
+DANGER
You should avoid join() for methods which will be called frequently.
TIP
While join() can become a performance issue when you call it very frequently, it is very convenient to use and easy to understand. If you are new to programming and just want to get your first bot working, this is a good method to start with.
Once you gathered more experience, we highly advise against using join as it negatively impacts your bot's performance!
thenAccept(...)
The thenAccept method accepts a Consumer, that consumes the result of the method and is executed asynchronously. It is the method you usually want to use most of the time.
The following example would create a new text channel in a given server and send a message directly afterwards.
new ServerTextChannelBuilder(server)
+ .setName("new-channel")
+ .create()
+ .thenAccept(channel -> {
+ channel.sendMessage("First!").thenAccept(message -> {
+ message.addReaction("👍");
+ });
+ });
+DANGER
The example code above has a major problem: Any exception that might occur will be completely ignored. This makes it very hard to find bugs.
For example, if your bot doesn't have the permissions to create a new channel, it will just fail silently.
exceptionally(...)
The exceptionally method accepts a Function as parameter, which consumes possible exceptions and returns a fallback value.
The following example would create a new text channel in a given server and send a message directly afterwards. If something fails (e.g., if the bot isn't allowed to create a text channel in the server), it will log an exception.
new ServerTextChannelBuilder(server)
+ .setName("new-channel")
+ .create()
+ .thenAccept(channel -> {
+ channel.sendMessage("First!").thenAccept(message -> {
+ message.addReaction("👍").exceptionally(e -> {
+ e.printStackTrace(); // Adding the reaction failed
+ return null;
+ });
+ }).exceptionally(e -> {
+ e.printStackTrace(); // Message sending failed
+ return null;
+ });
+ }).exceptionally(e -> {
+ e.printStackTrace(); // Channel creation failed
+ return null;
+ });
+Wow! This looks ugly 🤮. But worry not! There are many options to improve this code!
To make things simpler for you, Javacord has the ExceptionLogger class, which can be used here. It logs every exception you didn't catch manually.
new ServerTextChannelBuilder(server)
+ .setName("new-channel")
+ .create()
+ .thenAccept(channel -> {
+ channel.sendMessage("First!").thenAccept(message -> {
+ message.addReaction("👍").exceptionally(ExceptionLogger.get());
+ }).exceptionally(ExceptionLogger.get());
+ }).exceptionally(ExceptionLogger.get());
+Okay! This is at least a little better, but still not really perfect 🤔.
thenCompose()
The thenCompose methods allows you to chain futures. It takes a Function as parameter, that consumes the future's value and expects a new future to be returned.
The example to create a text channel can now be written like this:
new ServerTextChannelBuilder(server)
+ .setName("new-channel")
+ .create()
+ .thenCompose(channel -> channel.sendMessage("First!"))
+ .thenCompose(message -> message.addReaction("👍"))
+ .exceptionally(ExceptionLogger.get());
+Finally 🎉! Now we only need a single exceptionally(...) call at the end. We also got rid of the nested callbacks (usually referred to as "callback hell").
For better understanding, here's the example with comments that tell you the type at each line:
new ServerTextChannelBuilder(server) // ServerTextChannelBuilder
+ .setName("new-channel") // ServerTextChannelBuilder
+ .create() // CompletableFuture<ServerTextChannel>
+ .thenCompose(channel -> channel.sendMessage("First!")) // CompletableFuture<Message>
+ .thenCompose(message -> message.addReaction("👍")) // CompletableFuture<Void>
+ .exceptionally(ExceptionLogger.get()); // CompletableFuture<Void>
+📚 Further Read
This tutorial only focuses on the absolute basics. For a more detailed introduction to CompletableFutures, you can take a look at this tutorial.
You should also take a look at the JavaDoc for a complete list of methods: CompletableFuture JavaDoc.
Lambdas
Lambdas are used to implement functional interfaces. Simply said, functional interfaces are interfaces with a single method definition. All listeners in Javacord are functional interfaces and look like this internally (simplified):
@FunctionalInterface
+public interface MessageCreateListener {
+ void onMessageCreate(MessageCreateEvent event);
+}
+Before Java 8, you would have implemented this kind of listener as an anonymous class, which would look like this:
api.addMessageCreateListener(new MessageCreateListener() {
+ @Override
+ public void onMessageCreate(MessageCreateEvent event) {
+ // Do stuff
+ event.pinMessage();
+ }
+});
+In Java 8, this can be replaced with a lambda expression, which does exactly the same thing, but in a more readable fashion. The method parameter (in this case event) is written in front of the -> arrow, and the method body is written after it.
api.addMessageCreateListener(event -> {
+ // Do stuff
+ event.pinMessage();
+});
+TIP
If the method has more than one parameter, it would look like this:
(param1, param2) -> { ... }
+There's even a shorter version: If you are only executing one statement, you can get rid of the { } brackets as well:
api.addMessageCreateListener(event -> event.pinMessage());
+However, the above method can be shortened even more, by replacing the lambda expression with a so called "method reference".
api.addMessageCreateListener(MessageEvent::pinMessage);
+There are also plenty classes in Java 8, that make use of lambda expressions. One example would be the Optional class, which is explained here.
📚 Further Read
This tutorial only focuses on the absolute basics. For an in-depth introduction to lambda expressions, you can take a look at Oracle's article about lambda expressions.
Optionals
WARNING
This tutorial assumes that you are familiar with lambda expressions. Take a look at the lambda introduction first, if you are not!
💪 Motivation
The Optional class is widely used in Javacord. Basically, every method that might return a null value will return an Optional in Javacord instead. Optionals help you to avoid NullPointerExceptions and make it very clear if a method may not have a result. Here's a small example:
The old way of doing it
User user = api.getCachedUserById(123L);
+if (user != null) {
+ user.sendMessage("Hi!");
+}
+The new way of doing it
api.getCachedUserById(123L).ifPresent(user ->
+ user.sendMessage("Hi!")
+);
+You can imagine an Optional like a box 📦 that may or may not contain a value. Before accessing this value, you have to "unpack" this box first.
📖 Methods
The Optional class has many useful methods which can all be found in the JavaDocs. This tutorial gives a short introduction to the most common ones.
get()
The get method returns the value of the Optional or throws a NoSuchElementException if it does not contain a value.
TextChannel channel = api.getTextChannelById(123L).get();
+channel.sendMessage("Hi");
+DANGER
You should never use this method blindly but only if you are 100% sure the optional contains a value.
Every time you use this method carelessly, a kitten dies 🙀! True story.
isPresent()
The isPresent methods checks, if the Optional contains a value.
Optional<TextChannel> channel = api.getTextChannelById(123L);
+if (channel.isPresent()) {
+ // A text channel with the id 123 exists. It's safe to call #get() now
+ channel.get().sendMessage("Hi");
+}
+orElse(...)
The orElse methods returns the value of the Optional if it is present. Otherwise, it returns the given default value.
// The user may not have a nickname on the given server.
+// In this case, we use the user's "regular" name.
+String displayName = user.getNickname(server).orElse(user.getName());
+The example above is (mostly) equivalent to the example below but much more concise.
String displayName = "";
+Optional<String> nickname = user.getNickname(server);
+if (nickname.isPresent()) {
+ displayName = nickname.get();
+} else {
+ displayName = user.getName();
+}
+TIP
In this case you can just use user.getDisplayName(server) instead.
ifPresent(...)
The ifPresent method is very similar to an if (value != null) { ... } check. It takes a Consumer as it's argument. This consumer is called if the Optional contains a value. Together with lambda expressions this can be a very handy method.
api.getTextChannelById(123L).ifPresent(channel -> {
+ channel.sendMessage("Hi!");
+});
+The example above is (mostly) equivalent to the example below but more concise.
Optional<TextChannel> channel = api.getTextChannelById(123L);
+if (channel.isPresent()) {
+ channel.get().sendMessage("Hi!");
+}
+filter(...)
The filter method filters the Optional for a given criteria.
Optional<User> botUser = api.getCachedUserById(123L).filter(User::isBot);
+The example above is equivalent to the example below but more concise.
Optional<User> user = api.getCachedUserById(123L);
+Optional<User> botUser;
+if (user.isPresent() && user.get().isBot()) {
+ botUser = user;
+} else {
+ botUser = Optional.empty();
+}
+map(...)
The map method "converts" the type of an Optional. This is useful, if the type of an Optional does not contain the final value you need.
The following example gets the name of the bots current activity (the "Playing xyz" status) or "None" if the bot has no current activity.
String activityName = api.getYourself().getActivity().map(Activity::getName).orElse("None");
+For better understanding, here's the exact same code but with the types as comments:
String activityName = api.getYourself() // User
+ .getActivity() // Optional<Activity>
+ .map(Activity::getName) // Optional<String>
+ .orElse("None"); // String
+flatMap(...)
The flatMap method if very similar to the map methods. It is used to map values that itself are Optionals to prevent Optional nesting (a "box in a box").
String activityName = api.getCachedUserById(123L) // Optional<User>
+ .flatMap(User::getActivity) // Optional<Activity>
+ .map(Activity::getName) // Optional<String>
+ .orElse("None"); // String
+Without flatMap, the code would look like this:
String activityName = api.getCachedUserById(123L) // Optional<User>
+ .map(User::getActivity) // Optional<Optional<Activity>>
+ .filter(Optional::isPresent) // Optional<Optional<Activity>>
+ .map(Optional::get) // Optional<Activity>
+ .map(Activity::getName) // Optional<String>
+ .orElse("None"); // String
+📚 Further Read
This tutorial only focuses on the absolute basics. For an in-depth introduction to Optionals, you can take a look at Oracle's article about optionals.
Creating a Bot Account
After you added Javacord as a dependency with your favorite build manager, you should now create a bot account on the Discord website. This article will guide you through the process.
💡 Create a bot and get its token
1. Open https://discord.com/developers/applications/me and click on "Create an application".
2. Switch to Bot
TIP
If you want to, you can rename your application first
3. Click on Add bot and confirm the popup
4. Copy the bot's token. In this case the token would be NDc[...]pCs. You can just click on Copy.
DANGER
This token is used to login your bot. Keep it secret!
5. If you want to, you can change the bot's name and avatar on this page, too.
➕ How to add a bot to your server
Bots cannot join a server on their own like normal Discord users can. Instead, the owner of a server has to invite the bot using a so called Invite Link. There are multiple ways to create the invite link:
Use Javacord to create the invite link
The easiest way to obtain an invite link for your bot is by letting Javacord do it for you. Simply execute the following code, and it will print the invite link to your console:
DiscordApi api = new DiscordApiBuilder().setToken("your token").login().join();
+System.out.println(api.createBotInvite());
+If you don't have Javacord setup yet, you can also create the invite link manually.
Create the invite link manually
Get the client id
In order to add a bot to your server you need its client id.
You can get your client id from the same page where you created it.
With this id you can create an invite link for your bot.
If you are the owner or admin of the server, you can use this link to add your bot to your server. Otherwise, you have to give the link to the server owner/admins and ask them to add your bot.
TIP
Unlike the token, you don't have to keep your client id secret
Create the url
Just use the following link and replace 123456789 with your own client id.
https://discord.com/api/oauth2/authorize?client_id=123456789&scope=applications.commands%20bot&permissions=0
You can calculate the permissions (in the link above it's the 0) on the page where you created the bot:
🙋♂️ Use the invite link
You can now open the link and add the bot to your server:
TIP
Only the owner and admins of a server can invite bots. If you do not own a server yet, it is recommended to create one for testing.
Download / Installation
The recommended way to get Javacord is to use a build manager, like Gradle or Maven.
If you are not familiar with build managers, you can follow one of the beginner ide setup guides (see navigation) or download Javacord directly from GitHub.
📦 Javacord Dependency
repositories { mavenCentral() }
+dependencies { implementation 'org.javacord:javacord:$latest-version' }
+<dependency>
+ <groupId>org.javacord</groupId>
+ <artifactId>javacord</artifactId>
+ <version>$latest-version</version>
+ <type>pom</type>
+</dependency>
+libraryDependencies ++= Seq("org.javacord" % "javacord" % "$latest-version")
+Click to view snapshot repositories
Snapshots are automatically deployed from the development branch.
repositories {
+ maven {
+ url "https://oss.sonatype.org/content/repositories/snapshots/"
+ }
+}
+dependencies {
+ implementation 'org.javacord:javacord:$latest-snapshot-version'
+}
+<repository>
+ <id>snapshots-repo</id>
+ <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
+</repository>
+<dependency>
+ <groupId>org.javacord</groupId>
+ <artifactId>javacord</artifactId>
+ <version>$latest-snapshot-version</version>
+ <type>pom</type>
+</dependency>
+resolvers += "snapshots-repo" at "https://oss.sonatype.org/content/repositories/snapshots/"
+libraryDependencies ++= Seq("org.javacord" % "javacord" % "$latest-snapshot-version")
+📝 Optional Logger Dependency
In addition to Javacord, it is also recommended to install a Log4j-2-compatible logging framework. A logging framework can be used to provide a more sophisticated logging experience with being able to configure log format, log targets (console, file, database, Discord direct message, ...), log levels per class, and much more.
For example, Log4j Core:
dependencies { runtimeOnly 'org.apache.logging.log4j:log4j-core:2.17.0' }
+<dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-core</artifactId>
+ <version>2.17.0</version>
+</dependency>
+libraryDependencies ++= Seq("org.apache.logging.log4j" % "log4j-core" % "2.17.0")
+Take a look at the logger configuration wiki article for further information.
Frequently Asked Questions
Here you will find answers to some of the most asked questions.
Q: Why do I receive empty (no content) messages in i.e. the MessageCreateListener?
You are missing the privileged MESSAGE_CONTENT intent. For more information of how to enable privileged intents and enable them in your code see Gateway Intents.
Q: What is ... in the code examples?
You have to replace the ... with an instance that can be assigned to the datatype seen left.
For example, if you see TextChannel channel = ..., you have to replace ... with an instance that is a TextChannel which you can get from the API api.getTextChannelById(CHANNEL_ID) (note this returns an Optional<TextChannel>) or from an event like messageCreateEvent.getChannel().
Q: Why is my code not working?
There are multiple reasons why your code might not work. The most common ones are:
- Your code is not being reached. So make sure your code actually gets executed with a print statement or a debugger.
- Add at least
.exceptionally(ExceptionLogger.get())to every CompletableFuture (like when sending a message) to show any exceptions that might come from Discord. - Methods like
User#getRoles(Server)do not return the roles of the user. To fix this make sure to add theGUILD_MEMBERSintent. - You are getting a
NoSuchElementException. Congratulations, you have killed a kitten! You are most likely getting this Exception because you handle Optionals wrong. Read the article on Optionals to learn how to use them correctly.
If none of these tips will help you, you can ask your question in our Discord Server.
How to properly ask a question to get fast support?
Don't ask:
Why is my code not working?
+//Code
+Why am I getting Exception X?
+To ensure all information is provided that is needed to solve your issue, you should ask your question in a format like:
I have an issue with: YOUR_ISSUE
+I want to do: WHAT_YOU_WANT_TO_DO
+Currently this happens: WHAT_HAPPENS_NOW
+
+//Code
+
+//Exception
+The exception is thrown in the following line(not the number): CODE_LINE
+Q: What differs Javacord from JDA and D4J?
While all 3 libraries are Wrappers for the programming language Java, they use different techniques and concepts for their API.
- Javacord: Uses Java classes for its API like CompletableFuture for async requests and Optional for return types which may be
null.- Sending a Message:
channel.sendMessage("Javacord") - Checking if the Author of a message is a user:
message.getMessageAuthor().asUser().isPresent()
- Sending a Message:
- JDA: Has its own wrapper to execute requests and returns
nullif values are not present.- Sending a Message:
channel.sendMessage("JDA").queue() - Checking if the Author of a message is a user:
message.getMember() != null
- Sending a Message:
- Discord4J: Takes on the
reactiveapproach.- Sending a Message:
channel.createMessage("Pong!").block();
- Sending a Message:
Eclipse + Maven
This tutorial provides a beginner-friendly click by click guide to set up Javacord with Eclipse and Maven. If you are already familiar with Eclipse and Maven, you can just see the artifact locations at [Download / Installation](/wiki/getting-started/download-installation.md).Info
We recommend to use Intellij + Gradle unless you already have experience with one of the other IDEs or build managers.
🔧 Setup
1. Start Eclipse
2. Create a new project (File -> New -> Project)
3. Select Maven Project
4. Click Next
5. Check Create a simple project
6. Click Next
7. Enter a group id (e.g. com.github.yourname)
8. Enter an artifact id (e.g. myfirstbot)
9. Click Finish
10. Double click on the pom.xml file
11. Select pom.xml
12. Now you have to add Javacord as a dependency by editing the pom.xml file. Your file should now look like this:
<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>your.package.name</groupId>
+ <artifactId>myfirstbot</artifactId>
+ <version>1.0-SNAPSHOT</version>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.javacord</groupId>
+ <artifactId>javacord</artifactId>
+ <version>$latest-version</version>
+ <type>pom</type>
+ </dependency>
+ </dependencies>
+
+</project>
+ 13. Create a new package inside the src/main/java folder
14. Create a new class inside this package
15. Save the project (you should do this from time to time)
16. Now you can start coding! Example code:
package com.github.yourname.myfirstbot;
+
+import org.javacord.api.DiscordApi;
+import org.javacord.api.DiscordApiBuilder;
+
+public class Main {
+
+ public static void main(String[] args) {
+ // Insert your bot's token here
+ String token = "your token";
+
+ DiscordApi api = new DiscordApiBuilder().setToken(token).login().join();
+
+ // Add a listener which answers with "Pong!" if someone writes "!ping"
+ api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ });
+
+ // Print the invite url of your bot
+ System.out.println("You can invite the bot by using the following url: " + api.createBotInvite());
+ }
+
+}
+🏃♀️ Run the code
You can run your code by clicking on the small green arrow
IntelliJ + Gradle
This tutorial provides a beginner-friendly click by click guide to set up Javacord with Intellij and Gradle. If you are already familiar with IntelliJ and Gradle, you can just see the artifact locations at Download / Installation.
🔧 Setup
1. Start IntelliJ
2. Create a new project (File -> New -> Project)
3. Select Gradle
4. Make sure to select an SDK which is 1.8 (or greater)
5. Click Next
6. Enter a group id (e.g. com.github.yourname)
You can choose whatever you want
7. Enter an artifact id (e.g. myfirstbot)
You can choose whatever you want
8. Click Next
9. Check Use auto-import
10. Click Next
11. Click Finish
12. Locate the build.gradle file and open it
12. Add the Javacord dependency. Your build.gradle file should now look like this
plugins {
+ id 'java'
+}
+
+group 'com.github.yourname'
+version '1.0-SNAPSHOT'
+
+sourceCompatibility = 1.8
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ implementation 'org.javacord:javacord:$latest-version'
+}
+ 13. Create a new package in the src/main/java folder
14. Create a new class inside this package
15. You can now start coding!
Example code:
package com.github.yourname;
+
+import org.javacord.api.DiscordApi;
+import org.javacord.api.DiscordApiBuilder;
+
+public class Main {
+
+ public static void main(String[] args) {
+ // Insert your bot's token here
+ String token = "your token";
+
+ DiscordApi api = new DiscordApiBuilder().setToken(token).login().join();
+
+ // Add a listener which answers with "Pong!" if someone writes "!ping"
+ api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ });
+
+ // Print the invite url of your bot
+ System.out.println("You can invite the bot by using the following url: " + api.createBotInvite());
+ }
+
+}
+🏃♀️ Run the code
You can run your code by clicking on the small green arrow 
IntelliJ + Maven
This tutorial provides a beginner-friendly click by click guide to set up Javacord with Intellij and Maven. If you are already familiar with IntelliJ and Maven, you can just see the artifact locations at Download / Installation.
Info
We recommend to use Intellij + Gradle unless you already have experience with one of the other IDEs or build managers.
🔧 Setup
1. Start IntelliJ
2. Create a new project (File -> New -> Project)
3. Select Maven
4. Make sure to select an SDK which is 1.8 (or greater)
5.* Click Next
6. Enter a group id (e.g. com.github.yourname)
7. Enter an artifact id (e.g. myfirstbot)
8. Click Next
9. Click on Finish
10. Your project should now look like this. First click on Enable Auto-Import
11. Now you have to add Javacord as a dependency by editing the pom.xml file. Your file should now look like this:
<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>your.package.name</groupId>
+ <artifactId>myfirstbot</artifactId>
+ <version>1.0-SNAPSHOT</version>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.javacord</groupId>
+ <artifactId>javacord</artifactId>
+ <version>$latest-version</version>
+ <type>pom</type>
+ </dependency>
+ </dependencies>
+
+</project>
+12. Create a new package
13. Create a new class inside this package
14. You can now start coding! Example code:
package com.github.yourname;
+
+import org.javacord.api.DiscordApi;
+import org.javacord.api.DiscordApiBuilder;
+
+public class Main {
+
+ public static void main(String[] args) {
+ // Insert your bot's token here
+ String token = "your token";
+
+ DiscordApi api = new DiscordApiBuilder().setToken(token).login().join();
+
+ // Add a listener which answers with "Pong!" if someone writes "!ping"
+ api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ });
+
+ // Print the invite url of your bot
+ System.out.println("You can invite the bot by using the following url: " + api.createBotInvite());
+ }
+
+}
+🏃♀️ Run the code
You can run your code by clicking on the small green arrow
🚧 Possible problems
Note: If you get the following error:
you have to change your language level to 1.8
Writing your first bot
After you have successfully added Javacord as a dependency, created a bot user, and got its token, you are now ready to create your first simple bot! 🎉
❗ Enabling required intents
By default, all non-privileged intents are enabled. To receive the message content, attachments, components, and embeds you need a special privileged intent MESSAGE_CONTENT. To enable this privileged intent please see the Gateway Intents wiki article.
Slash Commands
Generally it is recommended to use Slash Commands instead of text commands because they offer many advantages like auto-completion, fixed and optional arguments, different kind of arguments with built-in types: numbers(with ranges), text, channel and a lot more.
🔑 Log the bot in
Everything starts with the DiscordApiBuilder class. It is used to create a DiscordApi object which is the most important class of your bot.
DiscordApi api = new DiscordApiBuilder()
+ .setToken("<your super secret token>")
+ .addIntents(Intent.MESSAGE_CONTENT)
+ .login().join();
+After executing this code, you should already see your bot online in Discord. Of course, just being online is not enough, so let's add some more code!
👂 Adding a listener
After you got your api instance, let's continue by adding a listener that answers every !ping message with a simple Pong!.
api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+});
+
👩🔧 Putting it all together
A good place for your code is the main(...) method that every executable Java program must have. Your complete class may look like this:
public class MyFirstBot {
+
+ public static void main(String[] args) {
+ // Log the bot in
+ DiscordApi api = new DiscordApiBuilder()
+ .setToken("<your super secret token>")
+ .addIntents(Intent.MESSAGE_CONTENT)
+ .login().join();
+
+ // Add a listener which answers with "Pong!" if someone writes "!ping"
+ api.addMessageCreateListener(event -> {
+ if (event.getMessageContent().equalsIgnoreCase("!ping")) {
+ event.getChannel().sendMessage("Pong!");
+ }
+ });
+ }
+
+}
+Congratulations, that's already everything you have to know for the beginning. Now, you can play around a little bit by exploring other listeners and methods. Or you just continue reading articles in the Basic Tutorials category.
Introduction
Welcome to the Javacord wiki! 👋
This wiki will help you to get started with your first Discord bot as fast as possible.
📚 Structure of the wiki
The wiki is divided into four groups:
- Getting Started focuses on teaching you how to setup up everything to get the most basic bot working.
- Basic tutorials contains articles about various concepts and classes of Javacord. Take a look at the headlines of each article and decide yourself, if it is relevant for you.
- Advanced Topics focuses on some more advanced topics that are not strictly necessary to start working with Javacord, but might become handy later on.
- Essential Knowledge teaches you the most important Java features/classes that you should know to comfortably work with Javacord. If you already have decent Java knowledge, you can skip this completely.
🤝 Support
While the wiki is great and covers many aspects of Javacord, we highly recommended you to join our Discord server if you have any questions:
- Join the Javacord server