signup-bot

The signup-bot is a Discord bot that can manage event signups for your guild. This is a guide for getting started with it and operating it.

If you have any issues, please file reports with me on my Bot Testing Discord Server. Feature requests are also welcome.

N.B. The current version of the bot is v2.0.0, so these documents are somewhat outdated. They will be rewritten soon, since the bot is migrating to use new Discord APIs

This document is updated as of v0.25.0. The changelog details what has changed in recent versions.

NOTE: anywhere that mentions enclosing in quotes should work with any of the following quoting characters: “, “, ”, «, », and „.

Contents:

Inviting the Bot

To invite the eso-signup-bot to your server, visit this invite page to grant it permissions.

Initial Configuration

After inviting the bot, you will want to do some initial configuration. There are several choices to make:

The bot admin channel [adminchannel]
The default event announcement channel [announcechannel]
The default event signup channel [signupchannel]
Whether to show event status after every signup [showaftersignup]
Whether to show event status after every withdraw [showafterwithdraw]
The default group to reference in announcements [announceto]
Your control character(s) [controlsequence]
Which role, if any, can control the bot [adminrole]

To make these choices, you will need to be an Admin (owner) of the discord server you are on.

Setting Channels

To edit the default channels the bot looks for, run the following commands, replacing the ... with an appropriate value. For channel names, enter them without the leading # (so not a reference/link).

!config-su set adminchannel=...
!config-su set announcechannel=...
!config-su set signupchannel=...

Setting Auto-Show Options

If you want the signup status to show after every signup or withdraw, the following commands.

!config-su set showaftersignup=true
!config-su set showafterwithdraw=true

If you want to turn the options off, run the following commands.

!config-su set showaftersignup=false
!config-su set showafterwithdraw=false

Setting the Announce-To Target

By default, @everyone is referenced by an announcement. If you would like to change that, you can set your own announcement target with the following command (replacing the ... with a reference to the user or role you want to target).

!config-su set announceto=...

If you would like to announce to multiple roles, you can list them all in the way you would like to reference them (e.g., !config-su set announceto=@Role1,@Role2). If you would like include a space between the roles, enclose it with quotes like !config-su set announceto="@Role1 @Role2".

To remove the announcement reference entirely, you can set the ... to be a character like _ or something else non-obtrusive. Setting it to an empty value will return the default behavior of referencing @everyone.

Setting the Admin Role

If you would like users other than Admin (owner) users to be able to control the bot, you will need to set an admin role. You can set which role can control the bot with the following command (replacing the ... with the name of – not a reference to – the role you want to select).

!config-su set adminrole=...

If the role you would like to use has space in the name, you can enclose the name in quotes like adminrole="...".

If you would like to disable the admin role, you can run the same command replacing the ... with a blank.

Setting the Control Sequence

To keep the default control sequence (!), you can skip the following command if you desire. After this point in the guide, we will assume that the control sequence is the default. If you change it, replace any ! characters at the start of commands with the control sequence you have chosen.

!config-su set controlsequence=...

If you like, these commands can be combined into a single command

!config-su set controlsequence=... adminchannel=... announcechannel=... signupchannel=... (etc)

You can change these settings at any time, but the AnnounceChannel and SignupChannel will only affect future created trials, not existing ones. You can edit the existing trials (see below) to change their channel settings.

Managing Events

Contents:

Managing events with this bot is restricted to Admin (owner) users of your server and whoever has been assigned to the bot admin role.

Events managed by the signup bot are restricted to your Discord server. To further restrict who can see and sign up for trials and events, you should use Discord role settings combined with the ability to set a event’s signup channel.

At the start, your server will not have any events (unless the bot was previously invited). To verify this, in the AdminChannel that you set, you can run !admin list. The bot should respond with a message containing an empty list of available events and an empty list of closed events.

Creating an Event

To create a new event, you need to first select a name. A name is strongly recommended to be a single word (but may contain dashes and other special characters as separators if you wish). If you would like to use multiple words, it is possible but will be harder for all your members to use. Keep in mind that your server members will have to type or paste the name you select in order to sign up for, withdraw from, or see the status of the event.

An event also needs to have one or more roles defined, along with a desired number of occupants of the role. Without roles, no one will be able to sign up.

To create a trial, in the AdminChannel that you set for your server, you can run the following (replacing EventName with the name you selected and specifying each of your roles in the comma-separated list as RoleName:Ct). If your event name contains spaces, you must enclose it in quotes like "Event Name"

!admin create EventName roles=RoleName:Ct,RoleName:Ct...

For example: !admin create TestTrial roles=Tank:2,Heals:2,Melee:4,Ranged:4

New! If you would like to use reaction-based signups for your events, you can attach an emoji from either the standard discord set or your server’s custom emojis to each role. To do this, the role would be specified like RoleName:Ct:Emoji.

For example: !admin create TestTrial roles=Tank:2:🛡️,Heals:2:⛑,DPS:8:⚔️

An event will almost certainly also need a description containing information about what date and time it is scheduled for, what exactly will be happening, and other details. To specify a description as part of the creation process, you can add description="..." to the end of the creation command above. If you have already created your event, you can also add it after the fact by editing the event (see below).

The double-quotes around the description are important, since your description almost certainly will contain spaces. If you would like to use a " character in your description itself, you can write it like \" so it does not interfere with the quotes around the entire description.

Editing an Event

Almost everything about a trial or event is editable EXCEPT the name.

Editing Roles

To change the roles in an event, in the AdminChannel that you set for your server, you can execute the following command (replacing EventName with the name of the event and specifying each of your roles in the comma-separated list as RoleName:Ct). To REMOVE a role, just set its Ct value to 0.

As always, if your event name contains a space, it must be enclosed with quotes.

!admin edit EventName roles=RoleName:Ct...

If people were signed up for a role that is removed, their signups will still exist in the database and will be immediately reinstated if/when you re-add the role, unless they choose to change their signup. If people are signed up for a role whose count is reduced, they will be bumped into the overflow for that role. If people are signed up for a role whose count is expanded, anyone in the overflow will fill in the newly available spots automatically.

To change the order that the roles are displayed in for an event, you can exeute the following command (replacing EventName with the name of the event). If this command is not executed, the default order is to display the roles in alphabetical order.

!admin edit EventName roleorder=Role1,Role2,Role3

Editing Description

If you did not set a description when you created an event or you wish to edit it for whatever reason, you can run, in the AdminChannel that you set for your server, the following command (replacing EventName with the name of the event and the ... with whatever text you desire).

!admin edit EventName description="..."

Editing Channels

Events also have associated AnnounceChannel and SignupChannel attributes. By default, these are copies of the values you had set in your server’s config at the time the event was created. If you want to change these for a given event, you can run, in the AdminChannel that you set for your server, the following commands (replacing EventName with the name of the event and the ... with the name of the channel, without the leading #).

!admin edit EventName announcechannel=...
!admin edit EventName signupchannel=...

Editing Announcement Targets

If you would like to customize the announcement target of an event from the global guild setting, you can run the following command (replacing EventName with the name of the event and the ... with whoever you would like to mention).

!admin edit EventName announceto=...

If you would like to metion more than one role, you can list them all inside double quotes like announceto="@Role1 @Role2".

Inspecting an Event

To inspect the settings you have chosen for an event, you can run, in the AdminChannel that you set for your server, the following command (replacing EventName with the name of the event).

!admin show EventName

Announcing an Event

Once you have an event created and edited to your liking, you can use the bot to announce it in the AnnounceChannel you selected. To announce the event, in the AdminChannel that you set for your server, execute the following command (replacing EventName with the name of the event).

!admin announce EventName

If you want to ping everyone who signed up that an event is starting, you can also announce to the AnnounceChannel that the event is grouping. To announce the event is grouping, in the AdminChannel that you set for your server, execute the following command (replacing EventName with the name of the event).

!admin grouping EventName

You can include an optional custom message with both the !admin announce and !admin grouping messages by simply typing it after the EventName.

Opening/Closing an Event

When created, events are considered open by default. Users can only sign up for and withdraw from open events. So, when your signups are over (perhaps shortly before your event), you can close the event to freeze the current state. You can always view the state of an event, regardless of whether it is open or closed, and you can re-open an event if you decide that you closed it too soon.

To close an event, run the following command in the AdminChannel that you set for your server (replacing EventName with the name of the event).

!admin close EventName

To open an event, run the following command in the AdminChannel that you set for your server (replacing EventName with the name of the event).

!admin open EventName

Managing Signups for an Event

Sometimes you may need to execute signups and withdraws from an event on behalf of other users. Each of the following commands must be executed in the AdminChannel that you set up for your server, but will send a message to the SignupChannel of the event that you are managing.

Signing up a user as an admin will behave exactly as if the user had signed up themselves (including overwriting previously selected roles and resetting any waitlist position). To sign up a user, you can use the following command (replacing @User with a mention of the user, EventName with the name of the event, and Role with the name of the role).

!admin signup EventName Role @User

You can also specify more than one user at a time for the same role. To specify more than one user, space-separate mentions for each of them on the same line.

!admin signup EventName Role @User1 @User2 @User3

Withdrawing a user as an admin will also behave exactly as if the user had withdrawn themselves (including resetting any waitlist position). To withdraw a user, you can use the following command (replacing @User with a mention of the user, EventName with the name of the event)

!admin withdraw EventName @User

You can also specify more than one user at a time to withdraw. To specify more than one user, space-separate mentions for each of them on the same line.

!admin withdraw EventName @User1 @User2 @User3

Clearing Signups for an Event

If you want to totally reset an event, you can run, in the AdminChannel that you set up for your server, the following command (replacing EventName with the name of the event).

!admin clear EventName

Keep in mind that this will remove all history of which users signed up for the event in the past.

Deleting an Event

In general, closing an event is likely good enough for marking it as over. However, if you want to re-use the event name, you might want to consider deleting it entirely. Deleting an event is not recommended at this time but it is possible. Once an event has been deleted, the data associated with it is irrecoverable. To delete an event, run the following command in the AdminChannel that you set for your server (replacing EventName with the name of the event).

!admin delete EventName

Event Signups and Status

Contents:

Event signups can be done by anyone with permission to send a message to the event’s signup channel.

Listing Available Events

To see what events are open and currently accepting signups, you can execute the following command (replacing the ! with whatever the command sequence is for your discord server).

!list

Along with the list of events, there will be references to the signup channel for each event.

Listing Signed-up Events

To see what events are open that you have signed for, you can execute the following command (replacing the ! with whatever the command sequence is for your discord server).

!myevents

Along with the list of events, there will be references to the signup channel for each event.

Displaying Status of an Event

To see the current description, signups, and status of an event, you can execute the following command (replacing the ! with whatever the command sequence is for your discord server, and replacing EventName with the name of the event).

!show EventName

Signing Up for an Event

To sign up for an event, you must select a role. The roles are defined by the bot admins for each event separately. A list of roles for a given event can be seen by showing the status of the event (see above). You can only be signed up for a given event once. If you try to sign up a second time, your first signup will be canceled (losing your space in line).

Each role has a designated number of desired signups. If you sign up for that role when it is already full, you will be put into an overflow queue for the role. If someone else ahead of you withdraws from the event or signs up for a different role, you will advance in line, possibly moving out of the overflow into the main list of signups for that role. This requires no additional action on your part.

To sign up for an event, you can execute the following command (replacing the ! with whatever the command sequence is for your discord server, and replacing EventName with the name of the event and Role with the name of the role you are signing up for).

!signup EventName Role

There is also a shorter alias available, if you prefer.

!su EventName Role

If the event has reaction-based signups turned on, you can also react to the emoji for the role you wish to sign up for that are attached to the event details message(s).

Additionally, if you are in the signup channel for each of the events, you can sign up for more than one event at a time.

!su EventName1 Role1 EventName2 Role2 (can continue for as many as you like and discord can handle)

Withdrawing from an Event

In the event that you have signed up for an event and realize you cannot make it or no longer wish to attend, you can withdraw from your signup. Withdrawing will remove you from the line; later signups will put you at the end of the line.

To withdraw from an event, you can execute the following command (replacing the ! with whatever the command sequence is for your discord server, and replacing EventName with the name of the event)

!withdraw Eventname

There is also a shorter alias available, if you prefer.

!wd EventName

Getting Help

If the bot is not behaving as expected there are a few options.

You can join the Bot Testing Discord Server and post the results of running !config-su-debug info (NOTE: the control sequence for this command is always !, not whatever you might have configured)
You can try to factory-reset the bot settings by running !config-su-debug factory-reset (NOTE: the control sequence for this command is always !, not whatever you might have configured)