Events

How to use events

discorb uses event driven programming. You can register event handlers with Discorb::Client#on. Alternatively, you can use Discorb::Client#once to register a one-time event handler.

client.on :message do |event|
  puts event.message.content
end

This example will print the content of every message received.

Since v0.2.5, you can also register event handlers by adding a method to the client, with the prefix on_ and the event name as the method name.

client = Discorb::Client.new

class << client
  def on_standby
    puts "Ready!"
  end
end

If you want to separate event handlers from the client, consider using Discorb::Extension. Learn more about extensions.

Since v0.6.1, you can set :override to true to register event handlers that can be overridden.

client.on :message, override: true do |event|
  puts "This event handler can be overridden."
end

client.on :message do |event|
  puts "Override!"
end

This example will print Override!, but not This event handler can be overridden.. This is useful for registering event handlers as default behavior, such as error handlers.

# In the library...

client.on :command_error, override: true do |event, error|
  $stderr.puts "Command error:\n#{error.full_message}"
end

# In your code...

client.on :command_error do |event, error|
  event.message.reply "An error occurred while executing the command!\n#{error.full_message}"
end

Event reference

Client events

event_receive(event_name, data)

Fires when an event is received.

Parameter Type Description
event_name Symbol The name of the event.
data Hash The data of the event.

ready()

Fires when the client receives the READY event.

standby()

Fires when the client is standby. (When the client connects to Discord, and has cached guilds and members.)

resumed()

Fires when the client is resumed connection.

error(event_name, args, error)

Fires when an error occurs during an event. Defaults to printing the error to stderr, override to handle it yourself.

Parameter Type Description
event_name Symbol The name of the event.
args Array<Object> The arguments of the event.
error Exception The error that occurred.

setup()

Fires when discorb setup is run. This is useful for setting up some dependencies, such as the database.

shard_standby(shard)

Fires when a shard is standby.

Parameter Type Description
shard Discorb::Shard The shard that is standby.

shard_resumed(shard)

Fires when a shard is resumed connection.

Parameter Type Description
shard Discorb::Shard The shard that is standby.

Guild events

guild_join(guild)

Fires when client joins a guild.

Parameter Type Description
guild Discorb::Guild The guild that was joined.

guild_available(guild)

Fires when a guild becomes available.

Parameter Type Description
guild Discorb::Guild The guild that became available.

guild_update(before, after)

Fires when client updates a guild.

Parameter Type Description
before Discorb::Guild The guild before the update.
after Discorb::Guild The guild after the update.

guild_leave(guild)

Fires when client leaves a guild.

Parameter Type Description
guild Discorb::Guild The guild that was left.

guild_destroy(guild)

Fires when guild is destroyed.

Parameter Type Description
guild Discorb::Guild The guild that was destroyed.

guild_integrations_update(guild)

Fires when guild integrations are updated.

Parameter Type Description
guild Discorb::Guild The guild that integrations were updated for.

guild_ban_add(guild, user)

Fires when a user is banned from a guild.

Parameter Type Description
guild Discorb::Guild The guild that the user was banned from.
user Discorb::User The user that was banned.

guild_ban_remove(guild, user)

Fires when a user is unbanned from a guild.

Parameter Type Description
guild Discorb::Guild The guild that the user was unbanned from.
user Discorb::User The user that was unbanned.

Channel events

channel_create(channel)

Fires when a channel is created.

Parameter Type Description
channel Discorb::Channel The channel that was created.

channel_update(before, after)

Fires when a channel is updated.

Parameter Type Description
before Discorb::Channel The channel before the update.
after Discorb::Channel The channel after the update.

channel_delete(channel)

Fires when a channel is deleted.

Parameter Type Description
channel Discorb::Channel The channel that was deleted.

webhooks_update(event)

Fires when a webhook is updated.

Parameter Type Description
event Discorb::Gateway::WebhooksUpdateEvent The webhook update event.

thread_new(thread)

Fires when a thread is created.

Parameter Type Description
thread Discorb::ThreadChannel The thread that was created.

thread_join(thread)

Fires when client joins a thread.

Parameter Type Description
thread Discorb::ThreadChannel The thread that was joined.

thread_delete(thread)

Fires when a thread is deleted.

Parameter Type Description
thread Discorb::ThreadChannel The thread that was deleted.

thread_update(before, after)

Fires when a thread is updated.

Parameter Type Description
before Discorb::ThreadChannel The thread before the update.
after Discorb::ThreadChannel The thread after the update.

thread_members_update(thread, added, removed)

Fires when a thread's members are updated.

Parameter Type Description
thread Discorb::ThreadChannel The thread that the members were updated for.
added Array<Discorb::ThreadChannel::Member> An array of Discorb::ThreadChannel::Member objects that were added to the thread.
removed Array<Discorb::ThreadChannel::Member> An array of Discorb::ThreadChannel::Member objects that were removed from the thread.

thread_member_update(before, after)

Fires when a thread member is updated.

Parameter Type Description
thread Discorb::ThreadChannel The thread that the member was updated for.
before Discorb::ThreadChannel::Member The thread member before the update.
after Discorb::ThreadChannel::Member The thread member after the update.

Integration events

integration_create(integration)

Fires when a guild integration is created.

Parameter Type Description
integration Discorb::Integration The created integration.

integration_update(after)

Fires when a guild integration is updated.

Parameter Type Description
after Discorb::Integration The integration after the update.

integration_delete(integration)

Fires when a guild integration is deleted.

Parameter Type Description
integration Discorb::Integration The deleted integration.

Message events

message(message)

Fires when a message is created.

Parameter Type Description
message Discorb::Message The created message.

message_update(event)

Fires when a message is updated.

Parameter Type Description
event Discorb::Gateway::MessageUpdateEvent The message after the update.

message_delete(message, channel, guild)

Fires when a message is deleted.

Parameter Type Description
message Discorb::Message The deleted message.
channel Discorb::Channel The channel the message was deleted from.
guild ?Discorb::Guild The guild the message was deleted from.
Note

This will fire when cached messages are deleted.

message_delete_id(message_id, channel, guild)

Fires when a message is deleted. Not like #message_delete this will fire even message is not cached.

Parameter Type Description
message_id Discorb::Snowflake The deleted message ID.
channel Discorb::Channel The channel the message was deleted from.
guild ?Discorb::Guild The guild the message was deleted from.

message_delete_bulk(messages)

Fires when a bulk of messages are deleted.

Parameter Type Description
messages Array<Discorb::Message, Discorb::Gateway::UnknownDeleteBulkMessage> The deleted messages.

message_pin_update(event)

Fires when a message is pinned or unpinned.

Parameter Type Description
event Discorb::Gateway::MessagePinEvent The event object.

typing_start(event)

Fires when a user starts typing.

Parameter Type Description
event Discorb::Gateway::TypingStartEvent The event object.

Reaction events

reaction_add(event)

Fires when a reaction is added to a message.

Parameter Type Description
event Discorb::Gateway::ReactionEvent The event object.

reaction_remove(event)

Fires when someone removes a reaction from a message.

Parameter Type Description
event Discorb::Gateway::ReactionEvent The event object.

reaction_remove_all(event)

Fires when all reactions are removed from a message.

Parameter Type Description
event Discorb::Gateway::ReactionRemoveAllEvent The event object.

reaction_remove_emoji(event)

Fires when a reaction is removed from a message.

Parameter Type Description
event Discorb::Gateway::ReactionRemoveEmojiEvent The event object.

Role events

role_create(role)

Fires when a role is created.

Parameter Type Description
role Discorb::Role The created role.

role_update(before, after)

Fires when a role is updated.

Parameter Type Description
before Discorb::Role The role before the update.
after Discorb::Role The role after the update.

role_remove(role)

Fires when a role is deleted.

Parameter Type Description
role Discorb::Role The deleted role.

Member events

Note

These events require the guild_members intent.

member_add(member)

Fires when a member joins a guild.

Parameter Type Description
member Discorb::Member The member that joined.

member_update(before, after)

Fires when a member is updated.

Parameter Type Description
before Discorb::Member The member before the update.
after Discorb::Member The member after the update.

member_remove(member)

Fires when a member is removed from a guild.

Parameter Type Description
member Discorb::Member The member that left.

Role events

role_create(role)

Fires when a role is created.

Parameter Type Description
role Discorb::Role The created role.

role_update(before, after)

Fires when a role is updated.

Parameter Type Description
before Discorb::Role The role before the update.
after Discorb::Role The role after the update.

role_remove(role)

Fires when a role is deleted.

Parameter Type Description
role Discorb::Role The deleted role.

Invite events

invite_create(invite)

Fires when an invitation is created.

Parameter Type Description
invite Discorb::Invite The created invite.

invite_delete(invite)

Fires when an invitation is deleted.

Parameter Type Description
invite Discorb::Invite The deleted invite.

Interaction events

interaction_create(interaction)

Fires when an interaction is created. This will fire for all interactions.

Parameter Type Description
interaction Discorb::Interaction The created interaction.

application_command(interaction)

Fires when an application command is used.

Parameter Type Description
interaction Discorb::CommandInteraction The created interaction.

slash_command(interaction)

Fires when a slash command is used.

Parameter Type Description
interaction Discorb::CommandInteraction::ChatInputCommand The created interaction.

message_command(interaction)

Fires when a message command is used.

Parameter Type Description
interaction Discorb::CommandInteraction::MessageMenuCommand The created interaction.

user_command(interaction)

Fires when a user command is used.

Parameter Type Description
interaction Discorb::CommandInteraction::UserMenuCommand The created interaction.

button_click(interaction)

Fires when a button is clicked.

Parameter Type Description
interaction Discorb::MessageComponentInteraction::Button The interaction object.

select_menu_select(interaction)

Fires when a select menu is selected.

Parameter Type Description
interaction Discorb::MessageComponentInteraction::SelectMenu The interaction object.

Fires when a modal is submitted.

Parameter Type Description
interaction Discorb::ModalInteraction The interaction object.

Voice events

Because it's big, it's documented in voice_events.

Guild scheduled event events

scheduled_event_create(event)

Fires when a scheduled event is created.

Parameter Type Description
event Discorb::ScheduledEvent The created scheduled event.

scheduled_event_cancel(event), scheduled_event_delete(event)

Fires when a scheduled event is canceled or deleted.

Parameter Type Description
event Discorb::ScheduledEvent The deleted scheduled event.

scheduled_event_edit(before, after)

Fires when a scheduled event is edited.

Parameter Type Description
before Discorb::ScheduledEvent The scheduled event before the edit.
after Discorb::ScheduledEvent The scheduled event after the edit.

scheduled_event_start(event)

Fires when a scheduled event is started.

Parameter Type Description
event Discorb::ScheduledEvent The scheduled event that started.

scheduled_event_end(event)

Fires when a scheduled event is ended.

Parameter Type Description
event Discorb::ScheduledEvent The scheduled event that ended.

Automod events

auto_moderation_rule_create(rule)

Fires when an auto moderation rule is created.

Parameter Type Description
rule Discorb::AutoModRule The created auto moderation rule.

auto_moderation_rule_update(rule)

Fires when an auto moderation rule is updated.

Parameter Type Description
rule Discorb::AutoModRule The updated auto moderation rule.

auto_moderation_rule_delete(rule)

Fires when an auto moderation rule is deleted.

Parameter Type Description
rule Discorb::AutoModRule The deleted auto moderation rule.

auto_moderation_action_execution(event)

Parameter Type Description
event Discorb::Gateway::AutoModerationActionExecutionEvent The auto moderation event.

Low-level events

guild_create(guild)

Fires when GUILD_CREATE is received.

Parameter Type Description
guild Discorb::Guild The guild of the event.

guild_delete(guild)

Fires when GUILD_DELETE is received.

Parameter Type Description
guild Discorb::Guild The guild of the event.

thread_create(thread)

Fires when THREAD_CREATE is received.

Parameter Type Description
thread Discorb::ThreadChannel The thread of the event.

scheduled_event_update(before, after)

Fires when SCHEDULED_EVENT_UPDATE is received.

Parameter Type Description
before Discorb::ScheduledEvent The scheduled event before the update.
after Discorb::ScheduledEvent The scheduled event after the update.