Events

Create custom events for when a user joins, a channel is created, etc.

The Custom Events module is where you can trigger actions based on things that occur in your server, on a timed basis, from an IFTTT trigger, and even from a BotGhost webhook.

Getting Started

  1. 1

    Located in the Custom Events module, you will see the "New Custom Event" section, click the "Custom Event Builder" yellow block to create a new event.

    Click the "Custom Event Builder"

  2. 2

    Select a custom event from the options currently provided.

    These options will activate when a condition is met. For instance, if a user joins your server, you can then have the bot greet them, like the announcement module, and DM them.

  3. 3

    Under the yellow main block, click on it and set an "Event Nickname". This will be shown in the dashboard if you are ever looking to edit a certain event. You can name it to whatever you'd want.

Blocks

In the custom event builder, the blocks you can use vary to the custom command builder. While creating an event, you cannot use options or certain conditions. As an example, you cannot use a "User Condition" in a timed event as the event has no user trigger. You can however use it if you have at least one button or select menu in your event.

Available Events

The type of events you may use in the custom events builder can be found below.

Action Events

Action Events are a category of pre-built, powerful events in BotGhost that combine multiple actions into a single block.
They are designed to simplify the creation of common bot features, allowing you to accomplish complex tasks without needing multiple custom event blocks. Check out the Action Events page for more information.

Timed Events

Timed events are a special type of events that can run on a scheduled (every day at 5 pm) or a set interval (every 10 minutes). Check out the Timed Events page for more.

IFTTT Events

IFTTT events can be triggered by IFTTT when something occurs (ex. you've created an applet that triggers a custom event when a video is posted on YouTube). Learn more on how to use them here.

Webhook Events

Webhook events can be triggered by an API Request sent to BotGhost. Learn more on the Webhooks page.

Application Events

The application events are based on actions in your server related to application command permissions.

  • When an application command’s permissions are updated
Audit Events

The audit events are based on actions in your server related to Discord’s audit log system.

  • When an audit log entry is created
Auto Moderation Events

The Auto Moderation events are based on actions in your server related to Discord’s built-in AutoMod feature.

  • When an Auto Moderation action is executed
  • When an Auto Moderation rule is created
  • When an Auto Moderation rule is deleted
  • When an Auto Moderation rule is updated
Boost Events

The boost events are based on actions in your server related to server boosts.

  • When a member boosts the server for the first time
  • When a member unboosts the server
  • When a server boost level increases
  • When a server boost level decrease
Bot Events

The bot events are related to actions that occur within your bot.

  • When the bot joins a server
  • When the bot leaves a server
  • When the bot starts or is restarted
  • When a custom variable's value changes
  • When the bot is updated through the dashboard

When a custom variable's value changes also runs for changes on your BotPanel server dashboard: when a server admin saves a setting, presses Undo in the change log, or applies a preset. It runs once for each stored value that changed. A new server's starting preset doesn't run it.

Channel Events

The channel events are based on actions in your server that are related to channels.

  • When a channel is created
  • When a channel is deleted
  • When a channel is updated
  • When a channel's permissions are updated
  • When a guild channel’s topic is updated
  • When a channel’s pins are updated
Invite Events

The invite events are based on actions in your server that are related to invites.

  • When a invite is created
  • When a invited is deleted
  • When someone's invite count changes

When someone's invite count changes runs after every change Change Invite Counts makes. See When someone's invite count changes below.

Member Events

The member events are based on actions in your server that are related to users.

  • When a new user joins the serer
  • When a user is banned from the server
  • When a user is unbanned from the server
  • When a user leaves or is kicked from the server
  • When a role is added to a user
  • When a role is removed from a user
  • When a guild member is updated
  • When a user changes their nickname
  • When a user changes their status
  • When a guild’s features are updated
  • When a guild’s ownership is transferred to another user
  • When a guild becomes a Partner
  • When a guild loses its Partner status
  • When a guild’s name is changed
  • When an AFK channel is set
  • When the AFK channel is removed
  • When a guild banner is added
  • When a guild banner is removed
  • When a member passes membership screening
  • When a guild’s integrations are updated

When a new user joins can also say who invited them: see Find the invite they used below.

Message Events

The message events are based on actions in your server that are related to messages.

  • When a new message is sent
  • When a message is updated or edited
  • When a message is deleted
  • When a message is pinned
  • When a user starts typing

By default, When a new message is sent only runs on messages from people. In the event's settings, under Messages From Other Bots and Webhooks:

  • Run on messages from other bots runs it on messages and slash command replies from other bots too, like sending a bump reminder after Disboard replies.
  • Also run on webhook messages runs it on messages posted by webhooks, like a feed from another service.

Messages your own bot sends never start it, and neither does a webhook your bot has posted through in the last 30 minutes. If one bot or webhook starts the event more than 10 times in 10 seconds in a channel, its messages there are ignored for 30 seconds.

Music Events

The music events are events triggered by music actions and the music module.

  • Track Events
    • When a track starts playing
    • When a track finishes playing
    • When the queue finishes playing
    • When a track encounters an error
    • When a track gets stuck/frozen
  • Player Controls
    • When playback is started
    • When playback is paused
    • When playback is resumed
    • When a track is skipped
    • When seeking in a track
    • When queue is shuffled
    • When playback is stopped
  • Queue Events
    • When a track is added to the queue
    • When a track is removed from the queue
  • Settings Events
    • When AutoPlay is toggled
    • When AutoLeave is toggled
    • When the player volume is changed
    • When player loop mode is changed
  • Connection Events
    • When bot connects to voice channel
    • When bot disconnects from voice channel
    • When bot is moved to a different voice channel
    • When bot automatically leaves voice due to inactivity
  • System Events
    • When a music player is created
    • When a music player is destroyed
    • When a music player switches Lavalink node
    • When a music player's WebSocket connection closes
    • When a music player state updates (fires frequently)
  • Other Music Events
    • When audio filters are changed
    • When player is resuming playback
    • When player has successfully resumed
    • When player mute status changes
    • When player deaf status changes
    • When a user joins the voice channel with the bot
    • When a user leaves the voice channel with the bot
Poll Events

The poll events are based on actions in your server related to the discord builtin poll feature.

  • When a user votes on a poll
  • When a user removes their vote on a poll
Reaction Events

The reaction events are based on actions in your server that are related to reactions on messages.

  • When a reaction is added to a message
  • When a reaction is removed from a message
  • When all reactions are removed from a message
  • When a specific reaction is removed from a message
Role Events

The role events are based on actions in your server that are related to roles.

  • When a role is created
  • When a role is updated
  • When a role is deleted
Scheduled Events Events

The scheduled events events are based on actions in your server that are related to the scheduled events feature.

  • When a scheduled event is created
  • When a scheduled event is updated
  • When a scheduled event is deleted
  • When a user joins a scheduled event
  • When a user leaves a scheduled event
Stage Events

The stage events are based on actions in your server related to stage instances.

  • When a stage instance is created
  • When a stage instance is deleted
  • When a stage instance is updated
Sticker Events

The sticker events are based on actions in your server related to stickers.

  • When a sticker is created
  • When a sticker is deleted
  • When a sticker is updated
Thread Events

The thread events are based on actions in your server that are related to threads or forum posts.

  • When a thread is created
  • When a thread is deleted
  • When a thread is updated
  • When thread lists are synced
  • When thread members are updated
  • When a thread member is updated
Voice Events

The voice events are based on actions in your server that are related to voice channels and users inside of them.

  • When a member joins a voice channel
  • When a member switches voice channels
  • When a member leaves a voice channel
  • When a member starts streaming in a voice channel
  • When a member stops streaming in a voice channel
  • When a member is server muted
  • When a member self mutes
  • When a member is server unmuted
  • When a member self unmutes
  • When a member is server deafened
  • When a member self deafens
  • When a member is server undeafened
  • When a member self undeafens
  • When a voice server is updated

Find the invite they used

In the settings of a When a new user joins event, under Invites, turn on Find the invite they used. It's off to start with. The bot then works out which invite the new member used and fills in the variables below. It needs Manage Server in the server. On that event, a block that reads one of these variables turns it on by itself.

Variable What it gives
{event_invite_code} The invite code they used, or empty
{event_inviter_id} Who it counts for: the person who made the invite, or the member a personal link belongs to
{event_inviter_mention} The same, as a mention
{event_inviter_name} The inviter's name
{event_invite_uses} The invite's uses after this join
{event_invite_channel_id} The channel the invite opens
{event_join_type} How they joined: invite, personal, campaign, vanity, no_inviter, bot, guest or unknown
{event_join_type_text} The same in words: "Tom's invite", "Tom's link", "the Summer ad link", "the vanity link", "an app or Discovery"
{event_invite_campaign} The campaign's name, for a campaign link
{event_invite_problem} Why it's unknown: no_permission (no Manage Server), too_close (two joins at once), no_change (Discovery or an app) or just_started
{event_inviter_total} The inviter's invite total before this join
{event_member_rejoined} true when Discord says they've been in the server before. Filled in on every join

The bot never guesses: when two people join at the same moment through different links, both are unknown.

When a user leaves or is kicked from the server gets how long they stayed, and, when the bot has a record of their join, who had invited them:

Variable What it gives
{event_member_joined_at} When they joined, as a Discord timestamp
{event_member_time_in_server} How long they stayed, like 3 months
{event_member_time_in_server_seconds} The same in seconds
{event_left_inviter_id} Who had invited them
{event_left_inviter_mention} The same, as a mention
{event_left_join_type} How they had joined, like invite or vanity
{event_left_invite_code} The invite code they had used
{event_left_counted} How their join counted: real, fake, rejoin, pending, not_counted, or empty with no record

The Invite Tracker module uses all of these.

When someone's invite count changes

This event runs once after each change Change Invite Counts makes (unless the block's Quietly is on), and for changes server admins make on your BotPanel website. It runs for the member whose count changed.

Variable What it gives
{event_invites_member_id} Whose count changed
{event_invites_mention} The same, as a mention
{event_invites_before} Their total before
{event_invites_after} Their total after
{event_invites_change} How much it changed, like 1 or -1
{event_invites_reason} Why: join, fake, leave, rejoin, bonus, set, reset or import
{event_invites_joined_id} The member who joined or left, for a join or a leave
{event_invites_by} Who made a staff change
{event_invites_note} The reason given with a staff change

Use it for a staff log of bonus changes or an alert when someone gains a lot of invites quickly. Discord's rules forbid rewarding people for invites, so don't use it to give roles, prizes or perks.

Variables

All specific and special variables can be found in the variable tab, the variable list changes per event type.

All event specific variables can be found in the variable list (represented by a clipboard icon), that appears on every input in your event builder. Those vary per event type. Learn more about variables and other variable types in the Variables page.