Table of Contents
- Display events on dedicated schedule channels.
- Send announcements when event begins / ends.
- Send reminders before an event begins.
- Configure timezone per schedule.
- Sync schedules to Google Calendars
- Users can RSVP to events
- Custom command prefix
- Bug Fixes and Patches
- Feature revisions
|init||Create a new schedule|
|create||Add a new event to a preexisting schedule|
|edit||Modify a preexisting event|
|delete||Delete an event or schedule|
|guild||Display and modify guild-wide settings|
|config||Display and modify schedule settings|
|zones||Show all timezones that the bot understands|
|help||Direct message the user a list of commands with additional information|
|sync||Sync a schedule to load events from a Google Calendar|
|test||Test an event's notification message|
|sort||Chronologically reorder the events on the schedule|
|list||View list of users who have rsvp'ed for an event|
The default command prefix is
@Saber can also be used to trigger bot commands.
Invite Saber-Bot and create a channel named #saber_control
!init in #saber_controlto create a schedule.
- If a channel named #new_schedule is not created, give Saber-Bot Manage Channel permissions.
!config #new_scheduleto view schedule settings
!guild prefix $to change the command prefix to
$zones "US"to view available timezone codes for the United States.
- Experiment with this command to find a timezone which best represents your locale.
$config #new_schedule zone [timezone], where
[timezone]is the timezone you found in step 5.
- It is best to always configure your schedule's timezone before adding events.
$create #new_schedule "Hi mom!" 5:45pmto create a new event
- If no message appears in #new_schedule, check to insure Saber-Bot has read, write, and manage message perms
- To delete the test schedule and event use
$delete #new_scheduleto remove the schedule.
- Alternatively, the schedule channel can be manually deleted for the same affect. The same goes for the event messages.
Make use of the
help command, read the docs, or ask in the support server to learn more about the commands. I hope @Saber fulfills your guild's scheduling needs!
Saber bot is designed to save events of schedule on dedicated "schedule channels."
Scheduling channels require Saber be given some permissions, which should already have been requested if Saber joined your server using the above oath link. Insure that Saber has the Manage Channels permission and the ability to read/write on any channel you plan to have her announce on.
In addition to schedule channels, Saber bot is configured to listen for scheduling commands only on a dedicated channel. Create a channel with the name "saber_control," and allow Saber to view and send messages to it.
After the first
guild command is issued in
#saber_control, the name of the control channel can be customized without affecting the behavior of the bot.
Saber commands are of the form
!command <arguments>; an argument is any space separated, quotation enclosed phrase -- with the exception of single word phrases which may drop the quotations.
Here's an example :
!create #event_schedule "Rampage on Monday" 8:00am 9:00pm. Saber will parse out four tokens from that command:
Rampage on Monday,
For each of the following commands,
<argument> denotes an argument and
[argument(s)] denotes optional arguments.
!create <#channel> <title> <start> [<end> <option(s)>]
Every new entry MUST be initialized with a title and a starting time. Start and end times should be of form h:mm with optional am/pm appended on the end (ex.
<end>parameter may be ommitted to create an event which does not end at any particular time.
Events can be created with a variety of extra options by adding specific keywords followed by a required value to the
<option(s)>section. Comments are the only exception to the previous rule. Comments may be added to an event's description by simply appending quotation enclosed phrases to the end of the command (see examples). A list of
<option>keywords can be found later in this document.
!create #event_schedule "Party in the Guild Hall" 19:00 2:00 date 04/10
!create "#event_channel Reminders" "Sign up for Raids" 4:00pm
!create "#event_channel Raids" "Weekly Raid Event" 7:00pm 12:00pm repeat "Fr,Sa" "Healers and tanks always in demand." "DM @RaidCaptain with your role and level if attending."
!edit <id> <option> <changes>
This command can be used to change any parameter of an event given the event's ID. The first argument is always the event ID, the second argument should be the keyword for the parameter you wish to change, and the third argument is the new value. The edit command uses the same option keywords as the create command.
commentis the only exception to this rule. When 'comment' is the second argument, the third argument needs to be either
remove(to denote the which action to take). The fourth argument should then either be the new comment to add or the number of the comment to remove.
!edit 3fa0 comment add "Attendance is mandatory"
!edit 0abf start 21:15
!edit 49af end 2:15pm
!edit 80c0 comment remove 1
This command can be used to delete an event or schedule. Passing the event ID as the first argument will delete the individual event, passing a channel mention to a schedule's channel will delete the schedule, and passing the word 'all' will result in the deletion of every scheduled event on the server. This command is not necessary to safely delete events and schedules. Guild administrators can delete the discord message or discord channel which represents the event or schedule to safely remove both.
!config <#channel> <option> <new_config>
When only the first argument (#channel) is provided, the currently configured settings for that schedule is return. Those settings can be modified by issuing the settings name as the second argument and the new configuration as the third argument. The list of
<option>keywords are detailed later in this documentation.
!config #schedule msg "@here Event %a: %t"
!config #schedule chan general
!config #schedule clock 12
!config #schedule remind "30, 10, 5 min"
!guild <option> <new_config>
This command may be used to modify guild-wide settings, such as your guild's command prefix and control channel. Issuing the guild command without arguments will output the current settings for your discord server. With this command you can specify which commands are 'restricted' and 'unrestricted'. A restricted command can only be used in the designated bot control channel. An unrestricted command may be used in any channel and by anyone so long as the bot has appropriate permissions to view and post in that channel. The list of
<option>keywords are detailed later in this documentation.
!guild prefix $
!guild restrict init
!guild unrestrict help
!sync <#schedule_channel> <calendar address>
This command will replace all events in the specified channel with events imported from a public google calendar. Up to the next 7 days of events will be imported. To learn more, see the Synchronize a Schedule with Google Calendar guide below. The schedule will re-import from the google calendar once per day automatically. While a schedule is synchronizing, the schedule can not be modified and new events may not be added.
!sync #schedule [. . .]
This command will output all timezones which match the provided filter. The filter is a character or string, any timezone whose name contains the the filter will be matched. The filter is required.
The test command will send an test announcement for the event to the bot control channel. The announcement message format is controlled by the schedule to which the event belongs to, and can be changed using the config command.
The list command will show all users who have rsvp'ed for an event. The command takes a single argument which should be the ID of the event you wish query. The schedule holding the event must have 'rsvp' turned on in the configuration settings. RSVP can be enabled on a channel using the config command as followed,
!config #channel rsvp on. The output of this command can be filtered by role, user, and type. Reference examples 2 and 3 below to see how this can be done.
!list 109ad2a "u: @notem
!list 019fa92 "t: yes" "r: @admin"
The sort command will re-sort the entries in a schedule. Entries are reordered so that the top event entry is the next event to begin. The schedule cannot be modified while in the process of sorting. Schedules with more than 10 entries will not be sorted. The order in which the schedule is sorted can be specified by appending 'asc' (ascending order) or 'desc' (descending order) to the command.
!sort #my_schedule asc
!sort #my_schedule desc
Direct messages the user a list of commands that can be used in Saber's dedicated control channel. If a command is supplied as the optional first argument, additional usage information for that command is provided. The information provided by the
helpcommand is likely to be more up-to-date than the documentation here.
Create a public calendar with Google Calendar. To set the calendar public, you should find a sharing setting near that looks something like this:
(optional) If you already have a calendar setup, but not yet made it public, you can toggle the calendar's share settings in the 'Calendar settings'>>'Share this calendar tab' It should look something like this:
Next, you'll need to find the calendar's public address. The calendar's public address is listed near the end in the calendar's settings webpage under the 'Calendar details' tab. It should look something like this:
Finally, use the
!sync <#channel> <address>command in your discord server's saber_control channel to sync the events in your public calendar to the schedule.
The timer is automatically setup to resync the channel to your calendar once every day. However, if changes are made to the Google Calendar the channel will not show such changes until resync. Either wait until auto-sync, or reuse the
- If you wish to unsync the channel from your google calendar, use the
!config #channel sync off).
An edit command should be formatted like
!edit <ID> <keyword> <argument(s)>
A create command differs in that several keywords and arguments may be used.
So, a create command should look something like
!create <#channel> <title> <start> [end] [keyword] [argument(s)] ... [keyword] [argument]
The table below details what can be used in the [keyword] and [argument(s)] sections of the command
|repeat||r||A comma separated list of days of week to repeat|
|interval||i||A (reasonably sized) number|
|date||d||A date in the format of yyyy/mm/dd|
|start-date||sd||A date in the format of yyyy/mm/dd|
|end-date||ed||A date in the format of yyyy/mm/dd|
|url||u||The url address for the event message's title|
|expire||ex||A date in the format of yyyy/mm/dd|
|Edit Command Only|
|title||t||The name given to the event|
|start||s||The time of day the event begins, formatted as hh:mm|
|end||e||The time of day the event ends, formatted as hh:mm|
|comment||c||"add" or "remove" followed by the comment encapsulated in quotations.|
|quiet-start||qs||No arguments. This silences the start announcement.|
|quiet-end||qs||No arguments. This silences the end announcement.|
|quiet-remind||qs||No arguments. This silences any reminders.|
|msg||m||A message format phrase|
|chan||ch||The target channel for event announcements|
|end-msg||m||A message format phrase. This overrides
|end-chan||ch||The target channel for event announcements. This overrides
|remind||r||List of comma separated numbers|
|remind-msg||rm||A message format phrase. This overrides
|remind-chan||rch||The target channel for event reminders. This overrides
|Miscellaneous Schedule Settings|
|clock||cl||For 12 hour format use "12", for 24 hour format use "24"|
|zone||z||A zone from !zones|
|rsvp||rs||Use "on" to enable rsvp, "off" to disable rsvp|
|style||st||Use "full" for the full event display, "narrow" for a shortened display format.|
|sort||so||Use "asc" to auto-sort the entries in ascending order, "desc" for descending order, and "off" to disable auto-sort.|
|Schedule Sync Settings|
|sync||s||A valid address, anything else will result in "off".|
|time||t||The time of day to schedule Google Calendar sync.|
|length||l||The number of days to sync from the Google Calendar|
|prefix||p||The prefix used to trigger bot commands.|
|control||c||The designated channel to listen for restricted commands.|
|restrict||r||The name of the command to restrict. Do not include the command prefix.|
|unrestrict||u||The name of the command to set as unrestricted.|
Setting a Custom Announcement Message
Every schedule channel is configured with it's own message to announce to a specified channel when an event begins or ends. With the
config command the message can be configured.
Saber will announce the message string verbatum unless a '%' character is encountered. When a '%' character is encountered, Saber will read the next character(s) and substitute the token with whatever value is associated that character combination.
|% token||Text Substituted in||Example msg : Possible Results|
|%t||Title of event announced||
|%c[n]||The [n]th comment of the event||
|%a||"begins [in x minutes]" or "ends [in x minutes]"||
|%b||"begins" or "ends"||
|%x||"in [x] minutes"||
Saber-bot has been developed using the Java 8 programming language. To run this application, you will need to download and install the Java 8 runtime environment for your system.
Saber-bot uses MongoDB to store the persistent event and schedule data. Install the latest version of MongoDB on your system. I suggest you setup MongoDB to run on system startup as well.
With the prequisite software installed, you should now be able to launch the bot application. Download the latest version of the bot from here, or compile from the bot from source using Maven.
Running the .jar file for the first time should cause the application to generate a fresh configuration file and close. Add your discord bot token and your discord user ID to the configuration file and restart the bot.
- To have Google Calendar integration, you need to generate new credentials on the Google Developer Console. Generate a new 'service account key' and download the key as a JSON file type. Modify the configuration file's 'google_service_key' settings to indicate the location of your service key file.
Documentation last updated: 2017-08-06