Create a Discord Bot in Go

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.

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

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

Using the API

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

Flags

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

Logging

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.

Sharding

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.

Caching

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.

Examples

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.

Import

Get a specific version of disgo by specifying a tag or branch.

go get github.com/switchupcb/disgo@v1.10.1

Disgo branches are referenced by API version (i.e v10).

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(disgo.Handlers),
    Sessions:       disgo.NewSessionManager()
}

Need more information about configuration? Check out the bot example.

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: 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
}

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 Gateway Intent calculation.

Output

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.

Summary

// 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>

Features

Why Go?

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.

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

Library	Description
Copygen	Generate custom type-based code.
Dasgo	Go Type Definitions for the Discord API.
Ecosystem	View projects that use Disgo.

Credits

Name	Contributions
SwitchUpCB	Project Architecture, Generators, Dasgo, Requests, Events, Shard Manager
Thomas Rogers	Dasgo
Josh Dawe	Dasgo

Earn a credit! Contribute Now.

switchupcb/disgo