Disgo helps you create a Discord Bot using the Go programming language.
Disgo is a Discord API Wrapper designed to be flexible, performant, secure, and thread-safe. Disgo provides every feature in the Discord API along with optional rate limiting, structured logging, shard management, and caching.
This repository is STABLE. For more information, read the roadmap.
Use the only Go module to provide a 100% one-to-one horizontally scalable implementation of the Discord API.
Your development is also simplified with these exclusive features.
- EVERY Rate Limit (Global, Per Route, Per Resource, Custom, Gateway)
- Automatic Gateway Intent Calculation
- Selective Event Processing
Disgo uses NO reflection or type assertion.
Disgo uses developer operations to stay up-to-date with the ever-changing Discord API.
- Code generation provides an optimal implementation for every request and event.
- Data race detection is run on an integration test covering the entire Discord API to make Disgo safe for concurrent usage.
| Topic | Categories |
|---|---|
| Using the API | Breakdown, Logging, Sharding, Caching |
| Examples | Import, Configuration, Create a Command, Handle an Event, Output, Summary |
| Features | Why Go?, Comparison, Contributing |
| Ecosystem | License, Libraries, Credits |
Use this breakdown to learn how the Discord API works.
| Abstraction | Usecase | Example |
|---|---|---|
| Resource | A Discord API Resource. | Guild Object. User Object. |
| Event | A Discord API Event. | A message is created. A user joins a channel. |
| Client | The Discord Bot Application that you develop. Bot = Client = Application. |
Configure the bot settings. Set the token. |
| Request | Uses the Discord HTTP REST API to make one-time requests for information. | Create an application command. Request guild information. |
| Session | Uses a Discord WebSocket Connection (Gateway) to receive events that contain information. | Send a message when an application command is used or a user joins a voice channel. |
Here is an example.
You create a Client that Requests Resources and handles Events from Sessions using Event Handlers.
For more information, please read What is a Request? and What is an Event?.
All flags are denoted by disgo.Flag (e.g., disgo.FlagUserSTAFF, disgo.FlagVerificationLevelHIGH, disgo.FlagPremiumTierNONE).
A flag is a flag, type, key, level or any other option that Discord provides.
Disgo provides structured, leveled logging of the API Wrapper via the disgo.Logger global variable (disabled by default). Enable the logger using zerolog.SetGlobalLevel(zerolog.LEVEL).
Read What is a Log for a simple yet full understanding of logging.
Using the automatic Shard Manager is optional and customizable.
Read What is a Discord Shard for a simple yet full understanding of sharding on Discord.
The Disgo Cache is optional and customizable.
The cache interface lets you replace the built-in cache with another store (such as Redis or Memcached) or provide your own caching implementation.
Read What is a Cache for a simple yet full understanding of the Disgo Cache.
| Example | Description |
|---|---|
| main | Learn how to use disgo. |
| command | Create an application command and respond to interactions. |
| message | Send a message with text, emojis, files, and components. |
| image | Set the bot's avatar using an image. |
Check out the examples directory for more examples.
Get a specific version of disgo by specifying a tag or branch.
go get github.com/switchupcb/[email protected]
Disgo branches are referenced by API version (i.e v10).
You must create a Discord Application in the Discord Developer Portal to receive your Bot Token.
Use the client to configure the bot's settings.
bot := &disgo.Client{
ApplicationID: "APPID", // optional
Authentication: disgo.BotToken("TOKEN"), // or BearerToken("TOKEN")
Authorization: &disgo.Authorization{ ... },
Config: disgo.DefaultConfig(),
Handlers: new(disgo.Handlers),
VoiceHandlers: new(disgo.VoiceHandlers),
Sessions: disgo.NewSessionManager()
}Need more information about configuration? Check out the bot example.
Create an application command request to add an application command.
// Create a Create Global Application Command request.
request := disgo.CreateGlobalApplicationCommand{
Name: "main",
Description: disgo.Pointer("A basic command."),
}
// Register the new command by sending the request to Discord using the bot.
//
// returns a disgo.ApplicationCommand
newCommand, err := request.Send(bot)
if err != nil {
log.Printf("failure sending command to Discord: %v", err)
return
}Create an event handler and add it to the bot.
// Add an event handler to the bot.
bot.Handle(disgo.FlagGatewayEventNameInteractionCreate, func(i *disgo.InteractionCreate) {
log.Printf("main called by %s", i.User.Username)
})Disgo provides automatic Gateway Intent calculation.
Open a WebSocket Session to receive and send events.
// Connect a new session to the Discord Gateway (WebSocket Connection).
s := disgo.NewSession()
if err := s.Connect(bot); err != nil {
log.Printf("can't open websocket session to Discord Gateway: %v", err)
return
}The following message will be logged when a user creates an InteractionCreate event by using /main in a Direct Message with the Bot on Discord.
main called by switchupcb.
// Use flags to specify options from Discord.
disgo.Flag<Option><Name>
// Use resources to represent Discord objects in your application.
disgo.<API Resources>
// Use events to represent Discord events in your application.
disgo.<API Events>
// Use requests to exchange data with Discord's REST API.
disgo.<Endpoint>.Send()
// Use sessions to connect to the Discord Gateway.
disgo.Session.Connect()
disgo.Session.Disconnect()
// Use send events to send data to Discord's Gateway.
disgo.<Event>.SendEvent()
// Use event handlers to handle events from Discord's Gateway.
disgo.Client.Handle(<event>, <handler>)
disgo.Client.Remove(<event>, <index>)
disgo.Client.Handlers.<Handler>
disgo.Client.VoiceHandlers.<Handler>
// Use the client to manage the bot's settings.
disgo.Client.ApplicationID
disgo.Client.Authentication.<Settings>
disgo.Client.Authorization.<Settings>
disgo.Client.Config.Request.<Settings>
disgo.Client.Config.Gateway.<Settings>A Discord Bot is server-side software.
A server-side software uses asynchronous logic to operate. Go maintains superior asynchronous handling with Goroutines and Channels.
Go is a statically typed, compiled programming language (with a garbage collector). So, it also performs better computationally compared to most languages that provide Discord API Wrappers.
Disgo supports every feature in the Discord API and is the most customizable Discord API Wrapper due to its optional caching, shard management, rate limiting, and logging.
Most important is Disgo's performance, which saves you money by reducing server costs.
Don't believe me? Check this out!
Disgo places a priority on performance. For more information, view library decisions.
Every struct uses fieldalignment to reduce the memory footprint of your application.
Disgo adds 5 MB to a compiled binary.
Disgo is the easiest Discord Go API for developers to use and contribute to: You can contribute to this repository by viewing the Project Structure, Code Specifications, and Roadmap.
The Apache License 2.0 is permissive for commercial use. For more information, read Apache Licensing FAQ.
| Library | Description |
|---|---|
| Copygen | Generate custom type-based code. |
| Dasgo | Go Type Definitions for the Discord API. |
| Ecosystem | View projects that use Disgo. |
| Name | Contributions |
|---|---|
| SwitchUpCB | Project Architecture, Generators, Dasgo, Requests, Events, Voice Connection, Shard Manager |
| Thomas Rogers | Dasgo |
| Josh Dawe | Dasgo |
Earn a credit! Contribute Now.