Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/disgoorg/disgo/llms.txt

Use this file to discover all available pages before exploring further.

The rest package provides a comprehensive HTTP client for interacting with Discord’s REST API. It handles rate limiting, error handling, and provides typed methods for all API endpoints.

​
Rest interface

The main interface combining all REST API functionality. 
type Rest interface {
    Client
    Applications
    OAuth2
    Gateway
    Guilds
    AutoModeration
    Members
    Channels
    Threads
    Interactions
    Invites
    GuildTemplates
    Users
    Voice
    Webhooks
    SoundboardSounds
    StageInstances
    Emojis
    Stickers
    SKUs
    GuildScheduledEvents
}

​
Creating a REST client

​
New

func New(client Client, opts ...ConfigOpt) Rest
Creates a new REST client with the given HTTP client and configuration options.

​
Client

The underlying HTTP client interface. 
type Client interface {
    HTTPClient() *http.Client
    RateLimiter() RateLimiter
    Close(ctx context.Context)
    Do(endpoint *CompiledEndpoint, rqBody any, rsBody any, opts ...RequestOpt) error
}

​
NewClient

func NewClient(botToken string, opts ...ClientConfigOpt) Client
Creates a new HTTP client for Discord’s API.
​
botToken
string
The bot token for authentication
​
opts
...ClientConfigOpt
Configuration options

​
Client configuration

​
WithUserAgent

func WithUserAgent(userAgent string) ClientConfigOpt
Sets a custom User-Agent header.

​
WithHTTPClient

func WithHTTPClient(httpClient *http.Client) ClientConfigOpt
Sets a custom HTTP client.

​
WithLogger

func WithLogger(logger *slog.Logger) ClientConfigOpt
Sets a custom logger for the REST client.

​
Guilds

Methods for managing guilds. 
type Guilds interface {
    GetGuild(guildID snowflake.ID, withCounts bool, opts ...RequestOpt) (*discord.RestGuild, error)
    GetGuildPreview(guildID snowflake.ID, opts ...RequestOpt) (*discord.GuildPreview, error)
    UpdateGuild(guildID snowflake.ID, guildUpdate discord.GuildUpdate, opts ...RequestOpt) (*discord.RestGuild, error)
    CreateGuildChannel(guildID snowflake.ID, guildChannelCreate discord.GuildChannelCreate, opts ...RequestOpt) (discord.GuildChannel, error)
    GetGuildChannels(guildID snowflake.ID, opts ...RequestOpt) ([]discord.GuildChannel, error)
    GetRoles(guildID snowflake.ID, opts ...RequestOpt) ([]discord.Role, error)
    CreateRole(guildID snowflake.ID, createRole discord.RoleCreate, opts ...RequestOpt) (*discord.Role, error)
    UpdateRole(guildID snowflake.ID, roleID snowflake.ID, roleUpdate discord.RoleUpdate, opts ...RequestOpt) (*discord.Role, error)
    DeleteRole(guildID snowflake.ID, roleID snowflake.ID, opts ...RequestOpt) error
    // ... many more methods
}

​
Example methods

​
GetGuild

func (g Guilds) GetGuild(guildID snowflake.ID, withCounts bool, opts ...RequestOpt) (*discord.RestGuild, error)
Retrieves a guild by ID.
​
guildID
snowflake.ID
The guild ID to fetch
​
withCounts
bool
Whether to include approximate member and presence counts

​
CreateRole

func (g Guilds) CreateRole(guildID snowflake.ID, createRole discord.RoleCreate, opts ...RequestOpt) (*discord.Role, error)
Creates a new role in a guild.

​
Channels

Methods for managing channels. 
type Channels interface {
    GetChannel(channelID snowflake.ID, opts ...RequestOpt) (discord.Channel, error)
    UpdateChannel(channelID snowflake.ID, channelUpdate discord.ChannelUpdate, opts ...RequestOpt) (discord.Channel, error)
    DeleteChannel(channelID snowflake.ID, opts ...RequestOpt) error
    GetMessages(channelID snowflake.ID, around snowflake.ID, before snowflake.ID, after snowflake.ID, limit int, opts ...RequestOpt) ([]discord.Message, error)
    GetMessage(channelID snowflake.ID, messageID snowflake.ID, opts ...RequestOpt) (*discord.Message, error)
    CreateMessage(channelID snowflake.ID, messageCreate discord.MessageCreate, opts ...RequestOpt) (*discord.Message, error)
    UpdateMessage(channelID snowflake.ID, messageID snowflake.ID, messageUpdate discord.MessageUpdate, opts ...RequestOpt) (*discord.Message, error)
    DeleteMessage(channelID snowflake.ID, messageID snowflake.ID, opts ...RequestOpt) error
    // ... many more methods
}

​
Example methods

​
CreateMessage

func (c Channels) CreateMessage(
    channelID snowflake.ID,
    messageCreate discord.MessageCreate,
    opts ...RequestOpt,
) (*discord.Message, error)
Sends a message to a channel.
​
channelID
snowflake.ID
The channel ID to send the message to
​
messageCreate
discord.MessageCreate
The message data to send
Example: 
message, err := client.Rest.CreateMessage(
    channelID,
    discord.MessageCreate{
        Content: "Hello, world!",
        Embeds: []discord.Embed{
            {
                Title: "Example Embed",
                Description: "This is an example embed",
                Color: 0x00FF00,
            },
        },
    },
)

​
GetMessages

func (c Channels) GetMessages(
    channelID snowflake.ID,
    around snowflake.ID,
    before snowflake.ID,
    after snowflake.ID,
    limit int,
    opts ...RequestOpt,
) ([]discord.Message, error)
Retrieves messages from a channel.

​
Users

Methods for managing users. 
type Users interface {
    GetUser(userID snowflake.ID, opts ...RequestOpt) (*discord.User, error)
    GetSelfUser(opts ...RequestOpt) (*discord.User, error)
    UpdateSelfUser(userUpdate discord.UserUpdate, opts ...RequestOpt) (*discord.User, error)
    GetDMChannel(userID snowflake.ID, opts ...RequestOpt) (*discord.DMChannel, error)
    // ... more methods
}

​
Interactions

Methods for responding to interactions (slash commands, buttons, etc.). 
type Interactions interface {
    CreateInteractionResponse(
        interactionID snowflake.ID,
        interactionToken string,
        interactionResponse discord.InteractionResponse,
        opts ...RequestOpt,
    ) error
    GetOriginalInteractionResponse(
        applicationID snowflake.ID,
        interactionToken string,
        opts ...RequestOpt,
    ) (*discord.Message, error)
    UpdateOriginalInteractionResponse(
        applicationID snowflake.ID,
        interactionToken string,
        messageUpdate discord.MessageUpdate,
        opts ...RequestOpt,
    ) (*discord.Message, error)
    DeleteOriginalInteractionResponse(
        applicationID snowflake.ID,
        interactionToken string,
        opts ...RequestOpt,
    ) error
    // ... more methods
}

​
Example methods

​
CreateInteractionResponse

func (i Interactions) CreateInteractionResponse(
    interactionID snowflake.ID,
    interactionToken string,
    interactionResponse discord.InteractionResponse,
    opts ...RequestOpt,
) error
Responds to an interaction. Example: 
err := client.Rest.CreateInteractionResponse(
    interactionID,
    token,
    discord.InteractionResponse{
        Type: discord.InteractionResponseTypeChannelMessageWithSource,
        Data: &discord.InteractionResponseDataMessage{
            Content: "Command executed!",
        },
    },
)

​
Applications

Methods for managing application commands. 
type Applications interface {
    GetGlobalCommands(
        applicationID snowflake.ID,
        withLocalizations bool,
        opts ...RequestOpt,
    ) ([]discord.ApplicationCommand, error)
    CreateGlobalCommand(
        applicationID snowflake.ID,
        commandCreate discord.ApplicationCommandCreate,
        opts ...RequestOpt,
    ) (discord.ApplicationCommand, error)
    UpdateGlobalCommand(
        applicationID snowflake.ID,
        commandID snowflake.ID,
        commandUpdate discord.ApplicationCommandUpdate,
        opts ...RequestOpt,
    ) (discord.ApplicationCommand, error)
    DeleteGlobalCommand(
        applicationID snowflake.ID,
        commandID snowflake.ID,
        opts ...RequestOpt,
    ) error
    // ... more methods for guild commands
}

​
Rate limiting

The REST client automatically handles Discord’s rate limits.

​
RateLimiter interface

type RateLimiter interface {
    Wait(ctx context.Context, endpoint *CompiledEndpoint) error
    Unlock(endpoint *CompiledEndpoint, rs *http.Response) error
    Close(ctx context.Context)
    MaxRetries() int
    Reset()
}
Rate limiting is handled automatically - you don’t need to manage it manually. The client will wait when rate limits are hit and retry requests as needed.

​
Error handling

​
Error type

type Error struct {
    Request        *http.Request
    RequestBody    []byte
    Response       *http.Response
    ResponseBody   []byte
    Code           int
    Message        string
    Errors         json.RawMessage
}
REST API errors implement the error interface and provide detailed information about what went wrong. Example: 
message, err := client.Rest.CreateMessage(channelID, messageCreate)
if err != nil {
    if restErr, ok := err.(*rest.Error); ok {
        log.Printf("Discord error: %d - %s", restErr.Code, restErr.Message)
    }
    return err
}

​
Request options

All REST methods accept optional RequestOpt parameters for customizing requests.

​
WithDelay

func WithDelay(delay time.Duration) RequestOpt
Delays the request by the specified duration.

​
WithReason

func WithReason(reason string) RequestOpt
Adds an audit log reason header (for moderation actions).

​
WithContext

func WithContext(ctx context.Context) RequestOpt
Sets the request context. Example: 
err := client.Rest.DeleteMessage(
    channelID,
    messageID,
    rest.WithReason("Spam message"),
)

Build docs developers (and LLMs) love

Get started for freeTalk to us