Documentation

Getting Started

To add Botomir to your Discord server, go to Botomir.com and select Add to Server. You must be the owner or admin of the guild you are trying to add to.

Required Permissions

  • Manage server
  • Change nickname
  • Manage nicknames
  • View channels
  • Send messages
  • Manage messages
  • Add reactions
  • Embedded links
  • Read message history

Botomir Admin

We recommend you create a botomir-admin role and assign it to the managing user in order to use the configuration commands.

Configurations

There are a number of ways you can configure Botomir to suit it to your server's needs.

Command Prefix

The default command prefix is !, however you can change it by using the the prefix command.

Enable Command

All commands come enabled by default. If you you have disabled a command and would like to enable it, you can do so by using the enable-command command.

Disable Command

You may want to prevent users from accessing certain commands on your server. You can do so by using the enable-command command.

Meme subreddits

You can configure the meme subreddits used in the !meme using the add-meme-sub command

Cute subreddits

You can configure the meme subreddits used in the !cute using the add-cute-sub command

Good bot response

You can configure the good bot responses using the add-goodbot command

Bad bot response

You can configure the bad bot responses using the add-badbot command

Role Reactions

Many servers choose to have roles that are assigned upon a user reacting to a message. You can set this up for your server using Botomir.

To do so, Botomir requires the following permissions for the specified role channel:

  • Send messages
  • Manage messages
  • Add reactions
  • Read message history

Set Role Channel

You must specify a role channel for Botomir to generate its message.

Set a channel to which the message will be autogenerated to using the set-role-channel command.

How to setup role reactions

First set a role channel. Then specify the message that members will see using the set-roles command.

Example

User
> !set-role-channel #welcome

Botomir 
> Settings updated.

User
> !set-roles This is a really cool message about automated role assignment
>      
> ---
> :fire: : role A : a super cool role
> :waffle: : role B

How to update role reactions

You can update this message by calling the set-roles command again with your new message and Botomir will update the message.

Common errors

  • The role name must be spelt exactly as it is set on your server
  • You must include a space between the colons
  • Botomir must have write permissions to the role channel

Spotify

Botomir has the ability to connect to Spotify and generate playlist based on Spotify links sent to a specified channel.

Authenticating with Spotify

To begin using the plugin you must first authenticate your Spotify account with Botomir using the authspotify command. Once the command is called, Botomir will message the caller through their DMs with a link to authenticate.

This is a per user command, once Botomir has been authenticated on a server, it does not have to be done again.

Setting a music channel

Next you must set a channel for Botomir to listen in on using the set-music-channel command.

Playlist configuration

You can configure the playlist including the title and description using the set-playlist-name and set-playlist-description commands. The default values are Awesome Discord Group Playlist and A playlist that contains all the songs that the discord group posted in the last little while. respectively.

Creating a playlist

You can create a playlist using the createplaylist command. This will generate generates a playlist using all of Spotify tracks that were shared in the past week in the music channel. The caller can specify other time periods as well.

Webhooks

Webhooks are a really cool way of registering for callbacks from a service. They let you tell some service, say [Github] for example, that you want to be told every time there is a new push to the main branch on Botomir/Botomir. You can register a callback URL and Github will send a payload whenever the event happens. This is super useful if you want to recieve a new notification for a project your working on or something like that.

Currently Botomir has supports for a couple types of webhook events, although we are planning on adding support for more soon.

Adding your webhook

To add a webhook its pretty simple:

  1. You need to go to botomir.com/settings and login if you need to
  2. Select the server that you want to configure, Note: you can only configure servers that you have the botomir admin role on.
  3. Select webhooks
  4. Click the New Webhook button
  5. Select the channel that you want the webhook to send the message in (this can be edited later)
  6. Select the type of webhook that you are adding, this is important so the message can be handled properly, and it can not be updated later.
  7. Fill in the message that you want to have sent when the event happens. You are able to include any of the fields from the original payload from the provider, see their documentation to see what they are called. The message can be updated later.
  8. Click save.
  9. Enter the webhook URL that you are given into the URL field for webhook provider, and make sure that you also enter the secret key, you will not be able to get that value again once you leave the page.
  10. Done, you can now start receiving webhooks for any of your events.

Webhook Message format

Instead of sending the exact same message every time the webhook happens you are able to configure it a little bit based off of the information that is included within the event. For example, if you were to sign up for the Github issue event, you can have a message like:

A new issue has been created by {{issue.user.login}} on the {{repository.name}} repo.

This would send the following messages:

  • A new issue has been created by MarshallAsch on the botomir repo.
  • A new issue has been created by SoorajModi on the botomir repo.

NOTE: the variable needs to be surrounded by {{ }} and it MUST exist in the payload otherwise it will not send.

Updating the webhook

NOT YET IMPLEMENTED

After the webhook is created you can update the channel that the message as well as the message contents, but nothing else. You also will not be able to get a new secret without deleting it and making a new one.

The process to update the webhook is really similar to the process of creating it.

  1. Navigate to the webhooks page for the server
  2. Find the webhook that you wish to update
  3. Click edit
  4. Edit the fields.
  5. Click save.

Removing the webhook

NOT YET IMPLEMENTED

Deleting a webhook is the same as update, except you click delete instead of edit.

  1. Navigate to the webhooks page for the server
  2. Find the webhook that you wish to update
  3. Click delete

Commands

Add bad bot response

  • Command: !add-badbot <custom response>
  • Returns: new response to user sending bad bot and success or failure message is sent
  • Example usage:
User:
> !add-badbot :'[
            
Botomir
> New bad bot response added

Add Botomir mention response

  • Command: !add-botomir <custom response>
  • Returns: new response to user sending Botomir mention and success or failure message is sent
  • Example usage:
User:
> !add-botomir I am a cool bot
            
    botomir
> New Botomir mention response added

Add cute subreddit

  • Command: !add-cute-sub <name of subreddit>
  • Returns: subreddit is added to list of cute subs and success or failure message is sent
  • Example usage:
    • !add-cute-sub aww
User:
> !add-cute-sub aww

Botomir
> Settings updated.

Add good bot response

  • Command: !add-goodbot <custom response>
  • Returns: new response to user sending good bot and success or failure message is sent
  • Example usage:
User:
> !add-goodbot <3

Botomir
> Settings updated.

Add meme subreddit

  • Command: !add-meme-sub <name of subreddit>
  • Returns: subreddit is added to list of meme subs and success or failure message is sent
  • Example usage:
User:
> add-meme-sub funny

Botomir
> Settings updated.

Disable Command

  • Command: !disable-command <name of command>
  • Returns: command is disabled and success or failure message is sent
  • Example usage:
User:
> !disable-command reddit

Botomir:
> Settings updated.

Enable Command

  • Command: !enable-command <name of command>
  • Returns: command is enabled and success or failure message is sent
  • Example usage:
User
> !enable-command reddit

Botomir
> Settings updated.

Make a role unassignable by Botomir

  • Command: !remove-unassignable <name of role>
  • Returns: role name is removed from the list of unassignable roles and success or failure message is sent
  • Example usage:
    • !remove-unassignable Admin
User:
> !remove-unassignable Admin

Botomir
> Settings updated.

Make a role unassignable by Botomir

  • Command: !add-unassignable <name of role>
  • Returns: role name is added to list of unassignable role and success or failure message is sent
  • Example usage:
    • !add-unassignable Admin
User:
> !add-unassignable Admin

Botomir
> Settings updated.

Set audit channel

  • Command: !set-audit-channel
  • Returns: audit channel Botomir will write to for is set and a success or failure message is sent
  • Example usage:
User:
> !set-audit-channel #audit

Botomir
> Settings updated.

Set command prefix

  • Command: set-admin-role-name
  • Args:
    • requires <new-role> as only argument
  • Returns: Botomir is updated to use the new admin role and a success or failure message is sent
  • Specifications:
    • Use the ping command to confirm the role name is updated
  • Example usage:
User
> !set-admin bot-lord

Botomir
> Settings updated.

Mental Health Links

  • Command: set-mental-health
  • Returns: Sends a message saying if the settings were updated successfully or not.
  • Example usage:
User
> !set-mental-health Mental Health Resources : https://www.ccmhs-ccsms.ca/mental-health-resources-1
Mental Health Services : https://switchandclick.com/2020/01/23/guide-to-mechanical-keyboard-cases/

Botomir
> Updated settings.

Set music channel

  • Command: !set-music-channel
  • Returns: music channel Botomir will watch for is set and a success or failure message is sent
  • Example usage:
User:
> !set-music-channel #songs

Botomir
> Settings updated.

Set playlist description

  • Command: !set-playlist-description
  • Returns: description of playlist Botomir will save songs to is set and a success or failure message is sent
  • Example usage:
User
> !set-playlist-description Songs from my Discord serve

Botomir
> Settings updated.

Set playlist name

  • Command: !set-playlist-name
  • Returns: name of playlist Botomir will save songs to is set and a success or failure message is sent
  • Example usage:
User
> !set-playlist-name An Awesome Discord Playlist

Botomir
> Settings updated.

Set command prefix

  • Command: set-prefix
  • Args:
    • requires <new_prefix> as only argument
  • Returns: Botomir is updated to use the new command prefix and a success or failure message is sent
  • Specifications:
    • Use the ping command to confirm the prefix is updated
  • Example usage:
User
> !set-prefix \

Botomir
> Settings updated.

Weather Timezone

  • Command: set-timezone
  • Returns: sets server timezone for the scheduled messages and sends success or failure message
  • Example usage:
User
> !set-timezone America/Toronto

Botomir
> Updated settings.

Weather Location

  • Command: set-weather-location
  • Returns: sets server weather location for weather command and sends success or failure message
  • Example usage:
User
> !set-weather-location Vancouver

Botomir
> Updated settings.

Docs

  • Command: docs
  • Returns: an embedded message with a link to Botomir.com/documentation.
  • Example usage:
User
> !docs

Botomir
> <embedded message with link to Botmir's documentation>

Help

  • Command: help
  • Args:
    • optional, <command>| <category> | categories | all | admin
  • Returns:
    • list of commands available to Botomir '
    • specific information about the passed in command if command specified '
  • Example usage:
User
'> !help

Botomir
> <embedded help message>

User
> !help ping

Botomir
> <embedded message with information about ping command>

User
> !help categories

Botomir
> Botomir has a lot of commands, to reduce the amount of spam please specify a category you would like some help with, valid categories to get help for are: `all`, `admin`, `information`, `music`, `reddit`, `roles`, `utility`

User
> !help music

Botomir
> <embedded message with information about different music commands>

Mechanical Keyboard

  • Command: keeb
  • Returns: embedded message with mechanical keyboard resources
  • Example usage:
User
> !keeb

Botomir
> <embedded message with links to mechanical keyboard resources>

Mental Health

  • Command: mental-health
  • Returns: embedded message with mental health resources
  • Example usage:
User
> !mental-health

Botomir
> <embedded message with link to mental-health resources>

Show current server configuration

  • Command: show-settings
  • Args: None
  • Returns: a message that says how botomir is configured
  • Example usage
User
> !show-settings
Botomir
>
embed

Site

  • Command: site
  • Returns: an embedded message with a link to Botomir.com
  • Example usage:
User
> !site

Botomir
> <embedded message with link to Botomir.com>

Source

  • Command: source
  • Returns: an embedded message with a link to Botomir's source code on GitHub
  • Example usage:
User
> !source

Botomir
> <embedded message with link to source code>

Version

  • Command: version
  • Returns: a message with the version number
  • Example usage:
User
> !version

Botomir
> Version: `1.2.3`
Build: `4ba590e`

Weather

  • Command: weather
  • Returns: an embedded message with the weather information for a city
  • Example usage:
User
> !weather

Botomir
> <embedded weather message>

Purge Messages from Channel

  • Command: purge
  • Returns: removed the specified number of messages from the channel this is called in.
  • Example usage:
User
> !purge 5

Botomir
> :skull_crossbones: Poof 1 messages were successfully deleted by @username

Authenticate Spotify

  • Command: !authspotify
  • Returns: DM is sent to caller with link to authenticate Spotify
  • Example usage:
User
> !authspotify

Botomir
> <sends DM with authentication link>

Create playlist

  • Command: !createplaylist
  • Returns: creates a new playlist with recently posted songs in the music channel, can also specify time period
  • Example usage:
User
> !create-playlist

Assign user role

  • Command: give
  • Args:
    • requires @user as first argument
    • requires <name of role> as second argument
  • Returns: specified user is assigned the specified role and a success or failure message is sent
  • Limitations:
    • user must be specified with @ tag
    • role must be assignable, cannot be a privileged role or a higher role than Botomir
    • role must be spelt exactly as it appears
    • do not specify role with @ tag
  • Example usage:
User
> !give @User minecraft

Botomir
> Successfully added role `minecraft` to user `User`

Remove role

  • Command: remove
  • Args:
    • requires <name of role> as only argument
  • Returns: specified role assignment is removed from user and a success or failure message is sent- Limitations:
    • role must be assignable, cannot be a privileged role or a higher role than Botomir
    • role must be spelt exactly as it appears
    • do not specify role with @ tag
  • Example usage:
User
> !remove minecraft

Botomir
> Successfully removed role `minecraft` from user `User`

Revoke role from user

  • Command: revoke
  • Args:
    • requires @user as first argument
    • requires <name of role>as second argument
  • Returns: specified role assignment is removed from specified user and a success or failure message is sent
  • Limitations:
    • user must be specified with @ tag
    • role must be assignable, cannot be a privileged role or a higher role than Botomir '
    • role must be spelt exactly as it appears '
    • do not specify role with @ tag
  • Example usage: '
User
> !revoke @User minecraft

Botomir
> Successfully removed role `minecraft` from user `User`

Assign role

  • Command: role
  • Args:
    • requires <name-of-role> as only argument
  • Returns: user is assigned the specified role and a success or failure message is sent
  • Limitations:
    • role must be assignable, cannot be a privileged role or a higher role than Botomir
    • role must be spelt exactly as it appears
    • do not specify role with @ tag
  • Example usage:
User
> !role minecraft

Botomir
> Successfully added role `minecraft` to user `User`

Cute

  • Command: cute
  • Returns: an embedded link to a post from a set of default subreddits
  • How to configure:
    • botomir-admin role required to configure
    • !add-cute-sub subreddit will add a specified subreddit to the list of subreddits meme will randomly pull from
  • Example usage:
User
> !cute

Botomir
> <embedded message with image of cute animal>

Image

  • Command: image
  • Args:
    • required, <subreddit>
  • Returns: an embedded link to a post from the specified subreddit
  • Limitations:
    • Cannot send links to text, video, or audio posts. Only pictures or gifs
  • Example usage:
User
> !image funny

Botomir
> <embedded message with reddit post>

Meme

  • Command: meme
  • Returns: an embedded link to a post from a set of default subreddits
  • How to configure:
    • botomir-admin role required to configure
    • !add-meme-sub subreddit will add a specified subreddit to the list of subreddits meme will randomly pull from
  • Example usage:
User
> !meme

Botomir
> <embedded message with meme>

Puppy

  • Command: puppy
  • Returns: an embedded link to a post from r/puppy
  • Example usage:
User
> !puppy

Botomir
> <embedded message with puppy image>

Set role mappings for reaction assignment

  • Command: `!create-role-reaction #channel intro

<mapping>`

  • Returns: Botomir will autogenerate a role assignment message to the specified channel
  • Specifications
    • The role assignment can start with a message and be followed by --- to specify role reactions
    • You can specify role reactions using the following format: <emoji> : <name of role>
    • To set a custom name for the role you can use the following format: <emoji> : <name of role> : <custom name>
    • Will filter out any roles that have been marked as unassignable on the server or that dont exist
    • The channel Must be specified
    • use the update-role-reaction command to edit the message
  • Example usage:
User
!create-role-reaction #general
This is a really cool message about automated role assignment
---
: fire: : role A : a super cool role
: waffle: : role B

And will auto-generate the following message in #general:

This is a really cool message about automated role assignment
:fire: a super cool role
:waffle: role B

Delete role mappings message

  • Command: !remove-role-reaction <messageLink>
  • Returns: stop watching the message for reactions and remove the message
  • Specifications
    • The message link must be a link to an existing role watch message
  • Example usage:
User
!remove-role-reaction https://discord.com/channels/788091112476770353/840781330538168350/848597559614111764

Will remove the existing message from #general that has the role reactions

List role reaction messages

  • Command: !list-role-reaction
  • Returns: list of all the role reaction message botomir is watching
  • Example usage:
User
!list-role-reaction

Botomir
> I am currently watching the following messages for reactions:
https://discord.com/channels/788091112476770353/840781330538168350/848597559614111764
https://discord.com/channels/788091112476770353/840781330538168350/848597559614111764
https://discord.com/channels/788091112476770353/840781330538168350/848597559614111764

Update role mappings for reaction assignment

  • Command: `!update-role-reaction <messageLink> intro

<mapping>`

  • Returns: Botomir will autogenerate a role assignment message to the specified channel
  • Specifications
    • The role assignment can start with a message and be followed by --- to specify role reactions
    • You can specify role reactions using the following format: <emoji> : <name of role>
    • To set a custom name for the role you can use the following format: <emoji> : <name of role> : <custom name>
    • Will filter out any roles that have been marked as unassignable on the server or that dont exist
    • The message link must be a link to an existing role watch message
  • Example usage:
User
!update-role-reaction https://discord.com/channels/788091112476770353/840781330538168350/848597559614111764
This is a really cool message about automated role assignment
---
: fire: : role A : a super cool role
: waffle: : role B

And will auto-generate and update the following message in #general:

This is a really cool message about automated role assignment
:fire: a super cool role
:waffle: role B

Cancel scheduled jobs

  • Command: cancel-job
  • Alias: cancel-reminder
  • Returns: Cancels any future runs of a job
  • Example usage:
User
> !cancel-job 60adab0d980931395d457341

Botomir
> Canceled the scheduled message

List scheduled reminders

  • Command: list-reminders
  • Returns: A listing of all the scheduled reminders to be sent, and the times they will be sent
  • Example usage:
User
> !list-reminders

Botomir
> I currently have the following reminders messages scheduled:
=================================================

jobID: 60adab0d980931395d457341
Tomorrow at 6:00 AM
Channel: #testing
Text: `test message to be sent at 10pm`
--------

jobID: 60adab38e004013972571888
Today at 4:30 PM
Channel: #testing
Text: `also test message to be sent at 10pm`
--------

List scheduled jobs

  • Command: list-jobs
  • Returns: A listing of all the scheduled messages to be sent, and their intervals
  • Example usage:
User
> !list-jobs

Botomir
> I currently have the following recurring messages scheduled:
=================================================

jobID: 60adab0d980931395d457341
Schedule: At 10:00 PM, every day
Channel: #testing
Text: `test message to be sent at 10pm`
--------

jobID: 60adab38e004013972571888
Schedule: At 10:00 PM, every day
Channel: #testing
Text: `also test message to be sent at 10pm`
--------

Remind Message

  • Command: remind
  • Returns: Schedules a message to be sent at a later time.
  • This uses date formats specified to say when the reminder message should be sent. It is mostly able to identify normal english dates but the date must come before the month. The message must be on the second line and can go on for as long as you want.
  • Example usage:
User
> !remind in 3 hours
look at this later

Botomir
> I will send you the reminder on Thursday March 25th at 6:00pm.

......
Thursday at 6:
Botomir
> Hey @user! Don't forget: look at this later.

https://discord.com/channels/12345/124/098765

User
> !remind in 5:00pm on the 4th of July
look at this later

Botomir
> I will send you the reminder on 07/04/2021.

......
July 4th at 5:
Botomir
> Hey @user! Don't forget: look at this later.

https://discord.com/channels/12345/124/098765

Schedule Message

  • Command: schedule
  • Returns: Schedules a message to be sent periodicity in the channel that the command is called from.
  • This uses Crontab formatted time strings, they are a little bit more confusing to write but they are very powerful and can be very specific.
  • Example usage:
User
> !schedule 0 6 * * THU
Hey everyeryone, remember we have DND soon!

Botomir
> Message has been scheduled to be sent on Thursday March 25th at 6:00pm.

......
Thursday at 6:
Botomir
> Hey everyeryone, remember we have DND soon!

Missing Letters

  • Command: missing-letters
  • Returns: A list of possible words that match the pattern
  • Example usage:
User
> !missing-letters pri...ul

Botomir
> Possible words are:
  prideful

Flip coin

  • Command: toss-coin
  • Returns: heads or tails
  • Example usage:
User
> !toss-coin

Botomir
> heads

Roll dice

  • Command: roll
  • Returns: Rolls some dice and adds an optional modifier to the result
  • Example usage:
User
> !roll

Botomir
> 🎲 (1) + 0 = 1

User
> !roll 1d20

Botomir
> 🎲 (11) + 0 = 11

User
> !roll 3d10 + 4

Botomir
> 🎲 (3, 5, 4) + 4 = 16

Ping

  • Command: ping
  • Returns: Pong
  • Example usage:
User
> !ping

Botomir
> Pong

XKCD

  • Command: xkcd
  • Returns: image of XKCD comic
  • Example usage:
User
> !xkcd

Botomir
> embedded message with image

User
> !xkcd 5

Botomir
> embedded message with image

Getting Help

Join the Botomir Support Discord Server here on Discord if you have any questions not covered by the documentation.

Reporting Issues/Bugs/Feature Requests

Please submit a new issue on our repository. If it is a security issue please email [email protected] with a description of the issue and how to reproduce it.