discord.jar is
a work in progress Java wrapper for the Discord API.
Everything that needs doing can be found in the Issues tab, so if you're
interested in helping out it would be greatly appreciated! Developed & maintained by @seailz
🧵Multi-Threaded
🌐Supports interaction only/http-only bots!
🔗Supports linked roles
🏃Efficient!
Our official Discord server: https://discord.gg/tmvS8A57J4
Before we start - please note that discord.jar is still a work in progress and there are some risks of deploying it in a production enviroment.
- Tune An example Discord Music bot built using discord.jar & LavaPlayer in just 1 hour, that's how simple it is!
- Discript - a scripting language to simplify bot development.
You'll need to add discord.jar to your project's dependencies. We are currently using JitPack to host our builds. See tutorials for your dependency management system here.
Above will change soon
When discord.jar officially releases, we'll be using our own repository. (Thanks @joeecodes). I'm also looking into getting djar on maven central.
A Discord bot token is required to use the API. You can get one by creating a bot account here.
To initialize a bot that uses the gateway (is able to receive events), you can use the following code:
DiscordJar djar = new DiscordJarBuilder("token").build();You can specify intents to use with the gateway by using the following code:
DiscordJar djar = new DiscordJarBuilder("token")
.addIntents(Intent.GUILDS, Intent.GUILD_MESSAGES).build();Doing so will override the default intents.
Note: You can use the Intent.ALL constant to specify all intents. This does not include privileged intents.
To make your bot an HTTP only bot, you'll need to specify a couple more parameters.
DiscordJar djar = new DiscordJarBuilder("token_here")
.setHTTPOnly(true)
.setHTTPOnlyInfo(new HTTPOnlyInfo(
"interactions",
"EXAMPLE_APPLICATION_PUBLIC_KEY"
)).build();You should set "interactions" to whatever endpoint you want to use to receive post requests from Discord. This will be
the endpoint you set in the Discord Developer Portal.
This WILL break some methods and is only recommended to be used if you know what you are doing. Otherwise, making a normal bot is recommended. HTTP-only bots (or Interaction-only bots) are bots that do not connect to the gateway, and therefore cannot receive events. They receive interactions through POST requests to a specified endpoint of your bot. This is useful if you want to make a bot that only uses slash commands.
Voice will not work, neither will setting your status & most gateway events.
Interaction-based events will still be delivered as usual.
To change the port of your web server, create a new file in the running directory called `application.properties` and add the following line:
server.port=8081
- Go to the Discord Developer Portal
- You'll want to start your bot if you haven't already.
- Select your bot.
- Go to the "General Information" tab.
- Scroll down to "INTERACTIONS ENDPOINT URL" and set it to the URL of your bot's endpoint. For example, if my bot's IP
was 123, the port was 321, and the endpoint was "interactions", I would set it to
http://123:321/interactions.
If it fails to save after that, please contact Seailz#0001 on Discord.
As far as I know, discord.jar is the only Java library to support linked roles, so here's a quick guide on how to use them:
- First, lets get everything set up in the developer portal. Start by going to the OAuth2 > General tab.
- You'll want to add a redirect URL, which should be the place where you are going to host your bot. For now, set it to
http://localhost:8080/verify
- Once you've done that, save your changes and go to the OAuth2 > URL Generator tab. On this page you'll see a big menu of scopes, and you need to select
identify&role_connections.write. - After those are selected, a "SELECT REDIRECFT URL" drop down will appear - select the url you set earlier.
- You'll end up with a "GENERATED URL" field. Note this down.
- Head to the General Information tab, and scroll down until you find "LINKED ROLES VERIFICATION URL". Set this to the URL you noted in the last step.
- Now, invite the bot to your server as usual, and you should be able to make a Linked Role! (As of writing, linked roles are only 50% rolled out yet).
- We actually need to implement this into our code now. Head to your code, and you'll want to add this:
discordJar.getSelfInfo().setRoleConnections(
new ApplicationRoleConnectionMetadata(
ApplicationRoleConnectionMetadata.Type.BOOLEAN_EQUAL,
"isdeveloper",
"Developer",
"Is a Developer"
)
);This code informs Discord of what role connection metadata you would like to have, so feel free to modify the metadata or add different ones. 9. We can now start getting set up with our webserver. You'll need a MySQL database for this. Here's an example of how to do that:
Database db = new Database(
"DATABASE_IP", // set these to your database credentials
3306,
"DATABASE_USER",
"DATABASE_PASS",
"DATABASE_NAME"
);
LinkedRoles lr = new LinkedRoles(
"CLIENT_ID", // can be found in the oauth2 > general tab
"CLIENT_SECRET", // can be found in the oauth2 > general tab
"http://localhost:8080/verify",
"/verify",
"APPLICATION_ID", // can be found in the GENERAL_INFORMATION tab
true, // should discord.jar redirect back to https://discord.com/oauth2/authorized when code is completed?
discordJar, // your discord.jar instance
db
);- Great! Now when you start your bot, it should be listenings to connections to the web server and will store data accordingly.
- Finally, to set metadata for a user, you can use this method:
HashMap<String, Object> values = new HashMap<>();
values.put("isdeveloper", 1); // discord requires boolean fields to use 1, or 0. (I don't know why)
lr.updateRoles("USER_ID", "discord.jar", "Seailz", values); // you can adjust these values accordinglyExamples can be found here
Javadocs can be found here.
If you want to contribute to this project, feel free to do so! Everything that needs doing can be found in the Issues tab, and if an issue there has the available tag you are free to make a PR fixing/adding it! :)
Make sure you first check the active PRs and branches for the feature/bug you're fixing/adding. If you make a PR for an issue with the claimed tag, and you are not the one who claimed it, (or in other words if there is a PR open for the issue you're looking to fix/add), then your PR will be closed.
If you've opened a PR, but it's not yet finished, please mark it as a draft PR.
Branches should be named either:
feature/[feature]
or
bug/[bugfix]
or
other[description].
To contribute to the /examples module, please see here.
/.github is off limits for contirubtions, please make an issue if there is an error in that folder.
License info can be found here. This project is licensed under GNU General Public License V3
Our official Discord server: https://discord.gg/tmvS8A57J4
