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

form_submit(interaction)

Fires when a form 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. |