discord.go

README

discord.go

A typed Go library for building Discord applications.
Low-level Discord API foundation and high-level bot facade.

---

Why choose discord.go?

• Two-layer architecture. A typed low-level protocol/REST foundation and a high-level bot facade with commands, middleware, collectors, and lifecycle management. Use the facade for application code, drop to the low-level API for protocol work.
• Gateway v10 with sharding. Dispatch, heartbeat, reconnect, resume, zlib-stream compression, multi-shard support with concurrency buckets, and automatic shard count detection.
• Voice with DAVE. WebSocket, UDP, RTP, AES-256-GCM transport encryption, Opus frame handling, and DAVE/MLS end-to-end encryption support.
• Components V2. Full support for Discord's Components V2 message model including containers, media galleries, separators, and section components.
• Typed throughout. Every REST resource, gateway event, and interaction type has a typed Go model. Nullable fields use pointers where omission differs from null.
• Production-oriented. Rate limiting with bucket hashing, invalid-request tracking to prevent Cloudflare bans, audit-log reasons, multipart uploads, and context-aware cancellation on all REST calls.

Installation

go get github.com/discord-go/discord.go

Requires Go 1.26 or newer. The library targets Discord API v10.

Quick Start

package main

import (
    "log"
    "os"

    "github.com/discord-go/discord.go/bot"
    "github.com/discord-go/discord.go/intents"
)

func main() {
    token := os.Getenv("DISCORD_TOKEN")
    if token == "" {
        log.Fatal("DISCORD_TOKEN is required")
    }

    router := bot.NewRouter()
    router.Command("ping", "Check bot status", func(ctx *bot.InteractionContext) {
        if err := ctx.Reply("Pong!"); err != nil {
            log.Printf("reply: %v", err)
        }
    })

    client := bot.New(token,
        bot.WithIntents(intents.Guilds),
        bot.WithRouter(router),
    )
    if err := client.Run(); err != nil {
        log.Fatal(err)
    }
}

Documentation

The complete documentation site is at discord-go.github.io/discord.go.

Start with the high-level guides for application code or the low-level guides for protocol and REST work. Runnable examples are organized under docs/examples/.

API reference is available on pkg.go.dev.

See the FAQ and Troubleshooting pages for common questions and solutions.

Development

go test ./...
go test -race ./...
go vet ./...

Nested example modules can be tested independently from their directories. See CONTRIBUTING.md before opening a pull request.

Security

Never commit bot tokens, OAuth client secrets, webhook tokens, database credentials, or generated coverage and build artifacts. Report security issues privately via GitHub's security advisory system rather than opening a public issue. See the security policy for details.

License

This project is licensed under the Apache License 2.0.