Create a Discord Bot in Go

This repository is USABLE. For more information, read the roadmap.

Disgo is a Discord API Wrapper is designed to be flexible, performant, secure, and thread-safe. Disgo aims to provide every feature in the Discord API along with optional caching, shard management, rate limiting, and logging. Use the only Go module to provide a 100% one-to-one implementation of the Discord API.

A Next Generation Discord API Wrapper

High quality code merits easy development. Disgo uses developer operations to stay up-to-date with the ever-changing Discord API. Code generation is used to provide a clean implementation for every request and event. Data race detection is used with an integration test that covers nearly 100% of the Discord API in order to ensure that Disgo is safe for concurrent usage.

Don't Miss Out On These Exclusive Features

• EVERY Rate Limit (Global, Per Route, Per Resource, Emoji, Gateway)
• Automatic Intent Calculation (Gateway)

Table of Contents

Using the API

This breakdown provides you with a full understanding on how to use the API.

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?

Flags

A flag is a flag, type, key, level or any other option that Discord provides. All flags are denoted by Flag in disgo: For example, disgo.FlagUserSTAFF, disgo.FlagVerificationLevelHIGH, disgo.FlagPremiumTierNONE, etc.

Sharding

Read What is a Discord Shard for a simple yet full understanding of sharding on Discord. Using the Shard Manager is optional. You can manually implement a shard manager through the disgo.Client.Sessions array.

Caching

Read What is a Cache for a simple yet full understanding of the Disgo Cache. The Disgo Cache is optional. The cache interface allows you to replace the built-in cache with another store (such as Redis or Memcached) and/or provide your own method of caching data.

Examples

The main example creates a bot that creates an application command and handles it. Check out the examples directory for more examples.

Import

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).

NOTE: v0.10.0 is a BETA version. For more information, read the State of Disgo (v0.10.0).

Configuration

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(Handlers),
    Sessions: new(Sessions)
}

Create a Command

Create an application command request to add an application command.

// Create a Create Global Application Command request.
request := disgo.CreateGlobalApplicationCommand{
    Name: "main",
    Description: "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)
}

Handle an Event

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 intent calculation.

Output

Open a WebSocket Session to receive events.

// Connect the session to the Discord Gateway (WebSocket Connection).
if err := bot.Connect(disgo.NewSession()); err != nil {
    log.Printf("can't open websocket session to Discord: %v", err)
}

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 SCB

Summary

// 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 the client to manage the bot's settings.
disgo.Client.Config.Request.<Settings>
disgo.Client.Config.Gateway.<Settings>
disgo.Client.Authentication.<Settings>
disgo.Client.Authorization.<Settings>

// Use requests to exchange data with Discord's REST API.
disgo.<Endpoint>.Send()

// Use sessions to handle events from Discord's WebSocket Sessions (Gateways).
disgo.Client.Handle(<event>, <handler>)
disgo.Client.Remove(<event>, <index>)

// Use flags to specify options.
disgo.Flag<Option><Name>

// Use the client's shard manager to handle sharding automatically or manually.
disgo.Client.Shard.<Settings>
disgo.Client.Shard.<map[Session][]map[Shard][]GuildIDs>

// Use the client to manage the optional cache.
disgo.Client.Cache.<Settings>
disgo.Client.Cache.<Requests>
disgo.Client.Cache.<...>

Features

Why Go?

Go is a statically typed language with a garbage collector. As a result, 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 useful since a Discord Bot is a server-side software.

Comparison

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

CPU

Disgo places a priority on performance. For more information, view library decisions.

Memory

Every struct uses fieldalignment to reduce the memory footprint of your application.

Storage

Disgo adds 3.5 MB to a compiled binary.

Contributing

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.

Ecosystem

License

The Apache License 2.0 is permissive for commercial use. For more information, read Apache Licensing FAQ.

Libraries

Credits

Earn a credit! Contribute Now.