eso-signup-bot

The eso-signup-bot is a Discord bot that can manage trial and 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.

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

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:

  1. The bot admin channel [adminchannel]
  2. The default trial announcement channel [announcechannel]
  3. The default trial signup channel [signupchannel]
  4. Whether to show trial/event status after every signup [showaftersignup]
  5. Whether to show trial/event status after every withdraw [showafterwithdraw]
  6. The default group to reference in announcements [announceto]
  7. Your control character(s) [controlsequence]
  8. 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 Trials/Events

Contents:

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

Trials and 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 trial/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 trials and an empty list of closed trials.

Creating a Trial/Event

To create a new trial or 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 trial or event.

A trial 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 TrialName with the name you selected and specifying each of your roles in the comma-separated list as RoleName:Ct). If your trial name contains spaces, you must enclose it in quotes like "Trial Name"

  • !admin create TrialName roles=RoleName:Ct,RoleName:Ct...

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

A trial 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 trial or 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 a Trial/Event

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

Editing Roles

To change the roles in a trial, in the AdminChannel that you set for your server, you can execute the following command (replacing TrialName with the name of the trial 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 trial name contains a space, it must be enclosed with quotes.

  • !admin edit TrialName 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.

Editing Description

If you did not set a description when you created a trial 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 TrialName with the name of the trial and the ... with whatever text you desire).

  • !admin edit TrialName description="..."

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 Channels

Trials and 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 trial or event, you can run, in the AdminChannel that you set for your server, the following commands (replacing TrialName with the name of the trial and the ... with the name of the channel, without the leading #).

  • !admin edit TrialName announcechannel=...
  • !admin edit TrialName signupchannel=...

Editing Announcement Targets

If you would like to customize the announcement target of a trial or event from the global guild setting, you can run the following command (replacing the ... with whoever you would like to mention).

  • !admin edit TrialName announceto=...

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

Inspecting a Trial/Event

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

  • !admin show TrialName

Announcing a Trial/Event

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

  • !admin announce TrialName

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

  • !admin grouping TrialName

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

Opening/Closing a Trial/Event

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

To close a trial, run the following command in the AdminChannel that you set for your server (replacing TrialName with the name of the trial).

  • !admin close TrialName

To open a trial, run the following command in the AdminChannel that you set for your server (replacing TrialName with the name of the trial).

  • !admin open TrialName

Managing Signups for a Trial/Event

Sometimes you may need to execute signups and withdraws from a trial/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 trial 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, TrialName with the name of the trial, and Role with the name of the role).

  • !admin signup TrialName 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 TrialName 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, TrialName with the name of the trial)

  • !admin withdraw TrialName @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 TrialName @User1 @User2 @User3

Clearing Signups for a Trial/Event

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

  • !admin clear TrialName

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

Deleting a Trial/Event

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

  • !admin delete TrialName

Trial Signups and Status

Contents:

Trial and event signups can be done by anyone with permission to send a message to the trial/event’s signup channel.

Listing Available Trials/Events

To see what trials/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.

Displaying Status of a Trial/Event

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

  • !show TrialName

Signup for a Trial/Event

To sign up for a trial or event, you must select a role. The roles are defined by the bot admins for each trial or 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 trial/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 a trial/event, you can execute the following command (replacing the ! with whatever the command sequence is for your discord server, and replacing TrialName with the name of the trial or event and Role with the name of the role you are signing up for).

  • !signup TrialName Role

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

  • !su TrialName Role

Withdraw from a Trial/Event

In the event that you have signed up for a trial or 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 a trial/event, you can execute the following command (replacing the ! with whatever the command sequence is for your discord server, and replacing TrialName with the name of the trial or event)

  • !withdraw TrialName

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

  • !wd TrialName