Discord API

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.

Introduction

Discord is a freeware, multi-platform, voice and text client designed for gamers. It has a documented RESTful API that allows developers to make Discord bots for use on their servers.

Luvit is an open-source, asynchronous I/O Lua runtime environment. It is a combination of LuaJIT and libuv, layered with various libraries to provide server-side functionality similar to that of Node.js, but with Lua instead of JavaScript. Luvit's companion package manager, lit, makes it easy to set up the Luvit runtime and its published libraries.

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!

Installation

  • 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, luvit bot.lua

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

Point your browser to the url: discordapp.com/developers/applications/me or click here
this is where all Discord bots and OAuth applications are are born.

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 MANAGE_SERVER or 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:

Installing Luvit

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)
  • mkdir luvit
  • cd luvit

After you have done this, you can install Luvit using the instructions at https://luvit.io/install.html.

Enter dir (on Windows) or ls (on Linux) to make sure that you have a lit, luvi, and luvit executable. If you do not, then your installation did not work.

Installing Discordia

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.

Updating Discordia

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:

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 "!

client:run('Bot TOKEN')

Step 5: Starting up your bot

After doing this go into your folder/area with your bot.lua file and type
luvit bot.lua

If all goes to plan, your bot should start and connect to the Discord gateway.


For more information, visit Discordia's Github Wiki