Disgo is a Discord API Wrapper designed to be flexible, performant, secure, and thread-safe. Disgo aims to provide every feature in the Discord API along with optional rate limiting, structured logging, shard management, and caching. Use the only Go module to provide a 100% one-to-one implementation of the Discord API.
This repository is STABLE. For more information, read the roadmap.
High-quality code merits easy development.
Disgo uses developer operations to stay up-to-date with the ever-changing Discord API.
- Code generation provides a clean implementation for every request and event.
- Data race detection is run on an integration test that covers the entire Discord API to ensure that Disgo is safe for concurrent usage.
In addition, Disgo provides the following 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.
| 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 |
This breakdown provides you with a full understanding on how to use the API.
| 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. |
You create a Client that calls for Resources using Requests and handles Events from Sessions using event handlers.
For more information, please read What is a Request? and What is an Event?.
A flag is a flag, type, key, level or any other option that Discord provides. All flags are denoted by disgo.Flag (e.g., disgo.FlagUserSTAFF, disgo.FlagVerificationLevelHIGH, disgo.FlagPremiumTierNONE).
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 allows you to 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),
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>
// 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>Go is a statically typed, compiled programming language (with a garbage collector). So it performs computationally better compared to most languages that provide Discord API Wrappers.
Go maintains superior asynchronous handling due to the use of Goroutines and Channels: This is helpful since a Discord Bot is server-side software.
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.
- DiscordGo is not feature-complete.
- Disgord is limiting.
Look no further than the name. The word disgo contains 5 letters — while the others have 7+ — saving you precious keyboard strokes.
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, Shard Manager |
| Thomas Rogers | Dasgo |
| Josh Dawe | Dasgo |
Earn a credit! Contribute Now.