If you've used Discord for any amount of time, I'm sure that you've come across at least a few Discord bots. Given MEE6 or Groovy, they all do the same thing and that's add functionality as well as a new way to interact with the platform. This is a fascinating idea as not many other platforms allow you to implement your own modifications. If you look at the Bots job postings on Discord's careers website, you'll see a big part of what they are trying to do with bots is “empower developers” and “give their dev community more ways to express their creativity and build exciting apps”.
Let me be the first to tell you, this is exactly what they are doing. By giving people a way to interact with a piece of software that they use every day, it can inspire new and experience developers alike to share and develop their creativity.
A prime example of this are the dev communities behind the Discord.JS and Discord.py libraries. These teams work to build something that allows their dev peers to create easily as well as express their uniqueness. I have used both libraries and I can tell you firsthand that both are fantastic contributions to the Discord community.
I currently have another post in the works describing both libraries in-depth and which to choose when first starting out. Both have their ups and downs, but both are great contributions nonetheless.
More recently though, I’ve been more interested in what is going on under the hood. By reading through the official Discord API documentation, you really get a sense of how deep the rabbit hole goes.
The layer of abstraction between your code and the API created by the aforementioned libraries really simplify the process for getting your ideas out there. You don’t have know anything about HTTP request or WebSockets to be able to interact with Discord’s API, so many people doing bother to go through the official documentation. This blog post is going to be about my journey through the documentation and what I’ve learned from reading it.
Connecting to the API
When creating my first bot I didn’t think much about how the data is being received or transferred. All that I was really interested in was that I was going to have my bot send a picture of Nicolas Cage on command, and to have the bot play Imperial March when I joined a voice channel. After a few bots, I started to get interested in this topic though, and I turned to the documentation.
It all starts with an interaction. The documentation defines an interaction as “the message that your application receives when a user uses an application command or a message component”. That means that when you use a slash command, user command, or message command as well as interact with a message component, Discord will send your application an interaction object. What’s more interesting is that you don’t really need a “bot user” to be able to get these interactions. If you scroll down the page from the interaction object definition, you’ll see a section called “Interactions and Bot Users”.
In this section it specifies that interactions give you the ability to interact with an app without a bot user needed. This was news to me and where my interest really started to take off. That being said a bot token is still needed to interact with gateway events or to query information, which is what anyone that has created a bot is more familiar with.
Ok, that makes sense, but how does your bot receive this interaction? The documentation states that there are two mutually exclusive ways to receive these interactions. The first being to connect to a WebSocket gateway, and the second being to create a webhook.
To connect to the gateway, you first should send a HTTP GET request to “https://discord.com/api/gateway” or “https://discord.com/api/gateway/bot” which will respond with a WebSocket URL. The client should cache this value and only request a new WebSocket URL if it is unable to connect to the previous. The bot gateway will return with a few extra fields including the recommended number of shards and the session start limit. Once you have the URL you can complete the handshake and begin to handle interactions that come through.
The second approach is to use outgoing webhooks. To set up outgoing webhooks, go to your application in Discord’s developer portal. Once there, in “General Information” you can scroll down and find “INTERACTIONS ENDPOINT URL”, insert the URL that you would like to handle interactions with as an HTTP POST request. Discord’s documentation shows an example of handling a ping interaction using Flask.
There are a few steps that you do have to complete before this endpoint would be considered valid. The first is that the endpoint must be ready to send an acknowledge signal back to Discord when the ping interaction comes. The second being that you must set up is the signature headers. After setting up the proper security and authorization, Discord will save the URL and you will start receiving HTTP POST request with interactions.
A very important note to mention is that once you set up a webhook, you can no longer use the gateway. Discord only allows you to use one form of interaction at a time. Of course, you can change your mind later and simply delete the URL in your application inside the developer portal and it will be able to use the gateway again.
Congratulations, you are now connected to Discord’s bot API.
What's Next?
Well depending on what path you took to receive interactions from Discord, your path will vary. The post discussing the webhook approach is coming soon.