Discord API is discord's way of allowing users to connect to their interface and data via code or program.
Below is a tutorial on using this API to your advantage.
Selecting a Library
You'll most likely be using Lua, so that's the language I'll be doing this tutorial in.
Discordia is a discord library for making bots in what's known as LuaJIT (Lua Just-In-Time), or Luvit, a mixture of Luv and luaJIT.
Getting a bot running in Discordia is simple, simply follow the steps below.
Discordia is a Lua wrapper for the official Discord API, and provides a high-level, object-oriented, event-driven interface for developing Discord bots. By using Lua's native coroutines, asynchronous HTTP and WebSocket communication is internally abstracted in a way that allows end-users to write blocking-style code without blocking I/O operations.
Join the Discord API community to discuss Discordia and other Discord libraries!
- To install Luvit, visit https://luvit.io and follow the instructions provided for your platform.
- To install Discordia, run
lit install SinisterRectus/discordia
- Run your bot script using, for example,
local discordia = require('discordia') local client = discordia.Client() client:on('ready', function() print('Logged in as '.. client.user.username) end) client:on('messageCreate', function(message) if message.content == '!ping' then message.channel:send('Pong!') end end) client:run('Bot INSERT_TOKEN_HERE')
Before you start using Discordia, you will need to make a new Discord bot application.
Creating Discord Applications
Step 1: Navigate to /developers/applications
Step 2: Create your first Application
- Click New App
- Enter your Application's name under App Name
Redirect URI, Description, and App Icon can be ignored for now and editted later. Redirect URI and Description can be ignored entirely as it is for Discord OAuth
App Icon will be the avatar for your bot, whilst App Name will be the original username for your bot.
Then hit the Big Blurple Create App Button at the bottom.
This will build your application and bring you to its page.
Setting Up Bot Accounts
When on your application information page scroll to the section labeled: Bot
Creating the Bot
Hit that lovely Create a Discord Bot button, again in Blurple.
This will prompt you about the repercussions of creating a bot account, after reading this hit Yes, do it!
You will see that your Bot Section has changed quite a bit with information about the user.
Getting and using your Token
You will see
Token: click to reveal in your Bot Information Section, your Token is sensitive information and should NEVER be shared. Be aware that the second section of your token is a base64 encoded timestamp of when it was created, so refreshing the page will regenerate the second section of your token.
If your token does get into somebody's hands who shouldn't have it click the: Regenerate new token button, this will invalidate all prior tokens.
Using your Token
Once inside your bot file you will call
client:run('Bot TOKEN'), replacing
TOKEN with the token received above.
Adding Bots To Servers
Generating OAuth Link
Discord makes this much easier with the Blurple Generate OAuth2 URL button on the bottom of the Bot Information Section
After visiting the link hit the copy button just below the scopes menu.
This will be the link you visit to add the bot to your Discord Server
Adding bot to A Discord Server requires that you have
ADMINISTRATOR permissions or hold owner in the guild
Discord Developer Mode
Discord Developer Mode allows you to right click and retrieve useful information about specific things.
This feature can be accessed via:
User Settings > Appearance > ADVANCED > Developer Mode
This allows you to get:
- User ids
- Guild ids
- Channel and Category ids
- Message ids
Discordia requires the Luvit framework to run. It will not run on a standard installation of Lua or LuaJIT. Luckily, installing both Luvit and Discordia is easy. Follow these steps:
Using a command prompt or terminal, create a new directory where you'd like to install the Luvit executables. For example:
cd C:\(on Windows) or
cd ~/(on Linux)
After you have done this, you can install Luvit using the instructions at https://luvit.io/install.html.
dir (on Windows) or
ls (on Linux) to make sure that you have a
luvit executable. If you do not, then your installation did not work.
With the three executables installed, run
lit install SinisterRectus/discordia (remember to prefix with
./ if on Linux). Note the lowercase D in "discordia" here. The project is officially named Discordia, but lit package names are traditionally lowercase. This should install the latest version of Discordia and its dependencies into a folder named
deps. Make sure that folder appeared.
If you are trying to update Discordia, lit will not handle this automatically. You must either install the new version to a new directory (recommended) or delete your old version of Discordia and its dependencies before installing the new version.
This tutorial will walk you through the steps required to get a simple bot up and running.
Step 1: Learn Lua
This tutorial assumes that you already know how to use the Lua programming language. If you do not, you will need to learn the basics before you write a Discord bot. Here are some resources that you can use to learn more about Lua, LuaJIT, and Luvit:
- https://www.lua.org/about.html - More about the Lua language
- http://lua-users.org/wiki/LuaTutorial - Introductory tutorial
- http://lua-users.org/wiki/TutorialDirectory - Main directory for the tutorial above
- https://www.tutorialspoint.com/lua/ - Contains all the basics and some extra
- https://www.lua.org/pil/contents.html - Programming In Lua textbook. The first version is available for free online.
- https://www.lua.org/manual/5.1/ - Lua reference manual most relevant to Luvit
- https://luvit.io/ - Luvit's website
- https://github.com/luvit - Luvit's repositories
- http://luajit.org/ - LuaJIT's website
Step 2: Find a good text editor
Any text editor will work, but simple ones like Notepad on Windows may not be sufficient. A popular alternative to Notepad is Notepad++. You might also want to consider Atom, VSCode, or Sublime. There is also Emacs, Vim, and a ton of others. Pick your favorite and install it.
Step 3: Create a Lua File
All Lua files have the extension
.lua. In the same directory where you installed Luvit earlier, make a new file with the name
bot.lua and open it with the text editor you installed above. The name can be anything, but we'll use "bot" for simplicity.
Step 4: Start Creating Your first Code
These are your
dependencies; do not delete these. They initialize Discordia and allow you to interact with it.
local discordia = require('discordia') local client = discordia.Client()
This code prints a success message and your bot's name to the console once your bot token has been authenticated and a connection to the Discord gateway has been established.
client:on('ready', function() -- client.user is the path for your bot print('Logged in as '.. client.user.username) end)
This is the method that will create your first command. It listens for a message event, and checks if the content of the message is "!ping". If so, it then sends "Pong!" to the channel from which the invoking message originated.
client:on('messageCreate', function(message) if message.content == '!ping' then message.channel:send('Pong!') end end)
This is what Authenticates your bot with the Discord Gateway and Discordia; replace
TOKEN with your bot's token. Note that all tokens MUST be prefixed with "Bot "!
Step 5: Starting up your bot
After doing this go into your folder/area with your
bot.lua file and type
If all goes to plan, your bot should start and connect to the Discord gateway.
For more information, visit Discordia's Github Wiki