Events

Event system and listener types for handling Discord gateway events

The events package provides a comprehensive event system for handling Discord gateway events. All events extend from GenericEvent and provide type-safe access to Discord data.

Core event types

GenericEvent

The base event structure that all other events extend from.

type GenericEvent struct {
    client         *bot.Client
    sequenceNumber int
    shardID        int
}

client · *bot.Client

The bot client instance that dispatched this event

sequenceNumber · int

The sequence number of the gateway event

shardID · int

The shard ID the event was dispatched from

Methods

Client() · *bot.Client

Returns the bot.Client instance that dispatched the event

SequenceNumber() · int

Returns the sequence number of the gateway event

ShardID() · int

Returns the shard ID the event was dispatched from

ListenerAdapter

Provides a convenient way to selectively handle events by implementing only the handlers you need.

type ListenerAdapter struct {
    OnRaw                    func(event *Raw)
    OnHeartbeatAck          func(event *HeartbeatAck)
    OnReady                 func(event *Ready)
    OnGuildJoin             func(event *GuildJoin)
    OnGuildLeave            func(event *GuildLeave)
    OnMessageCreate         func(event *MessageCreate)
    OnInteraction           func(event *InteractionCreate)
    // ... and many more
}

Usage example:

client.AddEventListeners(&events.ListenerAdapter{
    OnMessageCreate: func(event *events.MessageCreate) {
        fmt.Printf("Message: %s\n", event.Message.Content)
    },
    OnGuildJoin: func(event *events.GuildJoin) {
        fmt.Printf("Joined guild: %s\n", event.Guild.Name)
    },
})

Guild events

GuildUpdate

Called when a guild is updated.

type GuildUpdate struct {
    *GenericGuild
    Guild    discord.Guild
    OldGuild discord.Guild
}

Guild · discord.Guild

The updated guild

OldGuild · discord.Guild

The old cached guild before the update

GuildJoin

Called when the bot joins a guild.

type GuildJoin struct {
    *GenericGuild
    Guild discord.GatewayGuild
}

GuildLeave

Called when the bot leaves a guild.

type GuildLeave struct {
    *GenericGuild
    Guild discord.Guild
}

GuildsReady

Called when all guilds are loaded after logging in.

type GuildsReady struct {
    *GenericEvent
}

GuildBan

Called when a user is banned from a guild.

type GuildBan struct {
    *GenericGuild
    User discord.User
}

GuildUnban

Called when a user is unbanned from a guild.

type GuildUnban struct {
    *GenericGuild
    User discord.User
}

Message events

GenericMessage

The base message event structure.

type GenericMessage struct {
    *GenericEvent
    MessageID snowflake.ID
    Message   discord.Message
    ChannelID snowflake.ID
    GuildID   *snowflake.ID
}

Methods

Channel() · (discord.GuildMessageChannel, bool)

Returns the channel where the message was sent

Guild() · (discord.Guild, bool)

Returns the guild where the message was sent, or nil if it was sent in DMs

MessageCreate

Called when a message is received.

type MessageCreate struct {
    *GenericMessage
}

MessageUpdate

Called when a message is updated.

type MessageUpdate struct {
    *GenericMessage
    OldMessage discord.Message
}

MessageDelete

Called when a message is deleted.

type MessageDelete struct {
    *GenericMessage
}

Interaction events

InteractionCreate

Called when a new interaction is created (commands, components, autocomplete, modals).

type InteractionCreate struct {
    *GenericEvent
    discord.Interaction
    Respond InteractionResponderFunc
}

Interaction · discord.Interaction

The interaction data

Respond · InteractionResponderFunc

Function to respond to the interaction

Methods

Guild() · (discord.Guild, bool)

Returns the guild where the interaction happened, if it happened in a guild

ApplicationCommandInteractionCreate

Called when an application command is invoked.

type ApplicationCommandInteractionCreate struct {
    *GenericEvent
    discord.ApplicationCommandInteraction
    Respond InteractionResponderFunc
}

Response methods

Acknowledge(opts) · error

Acknowledges the interaction with a 202 Accepted response

CreateMessage(messageCreate, opts) · error

Responds to the interaction with a new message

DeferCreateMessage(ephemeral, opts) · error

Responds with a “bot is thinking…” message that should be edited later

Modal(modalCreate, opts) · error

Responds to the interaction with a modal

LaunchActivity(opts) · error

Responds by launching an activity associated with the app

ComponentInteractionCreate

Called when a component (button, select menu) is interacted with.

type ComponentInteractionCreate struct {
    *GenericEvent
    discord.ComponentInteraction
    Respond InteractionResponderFunc
}

Response methods

CreateMessage(messageCreate, opts) · error

Responds to the interaction with a new message

UpdateMessage(messageUpdate, opts) · error

Responds by updating the message the component is from

DeferUpdateMessage(opts) · error

Responds with nothing, acknowledging the interaction

Modal(modalCreate, opts) · error

Responds to the interaction with a modal

AutocompleteInteractionCreate

Called when autocomplete options are requested.

type AutocompleteInteractionCreate struct {
    *GenericEvent
    discord.AutocompleteInteraction
    Respond InteractionResponderFunc
}

Response methods

AutocompleteResult(choices, opts) · error

Responds with autocomplete choices

ModalSubmitInteractionCreate

Called when a modal is submitted.

type ModalSubmitInteractionCreate struct {
    *GenericEvent
    discord.ModalSubmitInteraction
    Respond InteractionResponderFunc
}

Response methods

CreateMessage(messageCreate, opts) · error

Responds to the modal submission with a new message

UpdateMessage(messageUpdate, opts) · error

Responds by updating the original message

DeferCreateMessage(ephemeral, opts) · error

Defers the response with a loading state

Event categories

The events package includes events for:

• Gateway events: Ready, Resumed, HeartbeatAck, GatewayRateLimited
• Guild events: GuildUpdate, GuildJoin, GuildLeave, GuildAvailable, GuildUnavailable
• Channel events: GuildChannelCreate, GuildChannelUpdate, GuildChannelDelete, ThreadCreate, ThreadUpdate
• Member events: GuildMemberJoin, GuildMemberUpdate, GuildMemberLeave
• Role events: RoleCreate, RoleUpdate, RoleDelete
• Message events: MessageCreate, MessageUpdate, MessageDelete
• Reaction events: MessageReactionAdd, MessageReactionRemove
• Voice events: VoiceServerUpdate, GuildVoiceStateUpdate, GuildVoiceJoin, GuildVoiceMove, GuildVoiceLeave
• Interaction events: InteractionCreate, ApplicationCommandInteractionCreate, ComponentInteractionCreate
• Presence events: PresenceUpdate, UserActivityStart, UserActivityUpdate
• Scheduled events: GuildScheduledEventCreate, GuildScheduledEventUpdate, GuildScheduledEventDelete
• Auto-moderation events: AutoModerationRuleCreate, AutoModerationActionExecution
• Emoji/Sticker events: EmojiCreate, EmojiUpdate, StickerCreate, StickerUpdate
• Webhook events: WebhooksUpdate
• Integration events: IntegrationCreate, IntegrationUpdate, IntegrationDelete
• Entitlement events: EntitlementCreate, EntitlementUpdate, EntitlementDelete

Usage example

package main

import (
    "github.com/disgoorg/disgo"
    "github.com/disgoorg/disgo/events"
)

func main() {
    client, _ := disgo.New(token,
        bot.WithEventListeners(&events.ListenerAdapter{
            OnReady: func(e *events.Ready) {
                fmt.Println("Bot is ready!")
            },
            OnMessageCreate: func(e *events.MessageCreate) {
                if e.Message.Author.Bot {
                    return
                }
                fmt.Printf("Message from %s: %s\n", 
                    e.Message.Author.Username, 
                    e.Message.Content,
                )
            },
        }),
    )
}