Saber bot

Invite to Discord | Saber on GitHub | Get Support

Features

Roadmap

Command Action
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
listm list with better compatability for the mobile client

The default command prefix is !, however @Saber can also be used to trigger bot commands.


Quick Start

  1. Invite Saber-Bot and create a channel named #saber_control

  2. Use !init in #saber_control to create a schedule.

    • If a channel named #new_schedule is not created, give Saber-Bot Manage Channel permissions.
  3. Use !config #new_schedule to view schedule settings

  4. Use !guild prefix $ to change the command prefix to $.

  5. Use $zones "US" to view available timezone codes for the United States.

    • Experiment with this command to find a timezone which best represents your locale.
  6. Use $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.
  7. Use $create #new_schedule "Hi mom!" 5:45pm to create a new event

    • If no message appears in #new_schedule, check to insure Saber-Bot has read, write, and manage message perms
  8. To delete the test schedule and event use $delete #new_schedule to 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!


Server Setup

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.


Commands

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: #event_schedule, Rampage on Monday, 8:00am, and 9:00pm.

For each of the following commands, <argument> denotes an argument and [argument(s)] denotes optional arguments.



Synchronize with Google Calendar

  1. Create a public calendar with Google Calendar. To set the calendar public, you should find a sharing setting near that looks something like this:


    Make calendar public


  2. (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:


    Change calendar share settings


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


    Your calendar's public address


  4. 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 sync command.


  5. If you wish to unsync the channel from your google calendar, use the config command (ex. !config #channel sync off).


Create and Edit Options

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

Keyword Aliases Values
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.


Config Command Options

Keyword Aliases Values
Announcement Settings
msg m A message format phrase
chan ch The target channel for event announcements
end-msg m A message format phrase. This overrides msg for end announcements.
end-chan ch The target channel for event announcements. This overrides chan for end announcements.
Reminder Settings
remind r List of comma separated numbers
remind-msg rm A message format phrase. This overrides msg for reminders.
remind-chan rch The target channel for event reminders. This overrides chan for reminders.
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


Guild Command Options

Keyword Aliases Values
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 @here Event: %t : @here Event: PoE Cut-throat League
%c[n] The [n]th comment of the event @everyone %c1 : @everyone Dont forget to signup for our weekly raids!
%a "begins [in x minutes]" or "ends [in x minutes]" @here %t %a : @here Raid practice begins in 5 minutes
%b "begins" or "ends" @here %t %b : @here Raid practice begins
%x "in [x] minutes" @here %t %x : @here Raid practice in 5 minutes


Self-Hosting Saber Bot

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

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

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

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

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