Help:Create Your Own Bot

Note: If you need help with this bot then you should contact Kocka Hey. If you're on this user subpage, it means I or somebody else directed you to it when you asked how to make a chat bot. This page should explain that. Kind of.

This documentation might be outdated, so if you're confident in your Ruby knowledge you might as well want to check out the latest commits to see what changed since the last documentation update.

Introduction

 * Read this section. I know reading is boring but if you don't read this part you'll most probably get confused later. Believe me, it's worth it.

Chat bot is just like a normal user in chat, except that it takes automatic action under certain circumstances. Some examples of how can it be used are logging chat, automatically detecting chat policy violations (caps, swearing) and taking automated actions to prevent them (warnings, kicks, bans), checking when was a user last time on chat, delivering a message to the user while they are out of chat or even relaying the chat to Discord. But before setting up a chat bot, ask yourself if you really need any of those features, or you wanted to make a chat bot just to look cool.

The fact is, a lot of the features chat bots across FANDOM provide are already covered by Discord's functionalities, either its core features or its user-made and user-maintained bots. Unlike the Chat extension on FANDOM, Discord is a whole platform dedicated to chatting (that, despite their branding, is not only "for gamers") and is years ahead of the Chat extension in terms of functionality, API, integration, etc. I'm not going to continue with promotion of Discord in this paragraph as it's largely irrelevant to the article, but at the point of needing a bot for your chat you should probably make the decision whether to remain on FANDOM Chat or use one of the Discord integration scripts and move your chatting community to Discord.

is a chat bot framework built by Kerri Amber. Due to an unfortunate accident, the original chatbot-rb repository has been deleted and I kept the last stable version in my fork of it.

Requirements
In order to make a chat bot, you need to fulfill these requirements: If you don't fulfill those requirements, there's no need to proceed to the installation section.
 * 1) Have a permission from administration/community. If you are a regular user on the wiki, and want to set up a chat bot, you need to ask the administration to allow that. If you are already in the local administration of that wiki, it might be a good idea to inform others users of the wiki about the chat bot.
 * 2) Have a computer you can leave running all the time. A chat bot is a program. If you run that program, the chat bot is in chat. If you don't run it, it isn't in chat. So if you want your chat bot to be in chat all the time, you have to run it all the time, which requires the machine the chat bot is running on to be turned on all the time.
 * 3) Don't be globally blocked. Easy enough?

Installation
Now, these are the installation steps for the chat bot.

Ruby
As chatbot-rb is built on Ruby, it also requires a Ruby interpreter in order to be run.
 * Windows
 * To install Ruby on Windows, download the latest version of Ruby from this page. Complete the installation process properly, and do not forget to check "Add Ruby executables to your PATH".


 * Linux
 * To install Ruby on Linux, install Ruby Version Manager (RVM) as described here. Or just Google it, it shouldn't be too hard. Remember not to use sudo when installing it, though. Or something like that, I forgot as I installed it long ago.


 * Mac OS
 * I dunno, I don't use Mac.

Dependencies
After installing Ruby, you need to install chatbot-rb dependencies. You can do that by opening your console window (on Windows, click Windows Button + R and in the Run window that appears enter " " and then click the OK button). After the console window is open, enter gem install httparty mediawiki-gateway in it.

If installing these fails because an SSL certificate is invalid, please update your RubyGems.

Account
While you're waiting for Ruby and dependencies to get installed, you might want to create a new account for the chat bot. Just go to this page to log out of your current account, then to this page to register a new one.

chatbot-rb
Second step is setting up chatbot-rb. If you don't know how to use Git, you can just use this link to download the chatbot-rb repository in a .zip file, and don't forget to extract that .zip file after you download it. If you do know how to use Git, git clone https://github.com/KockaAdmiralac/chatbot-rb.git

Now, before you proceed you might want to enable viewing file extensions for known file types, if you're using Windows. To do that, you'd have to do something like this or this in your file explorer. If it doesn't appear for any reason, then go to Control Panel -> Appearance and Personalization -> File Explorer Options/Folder Options, select the "View" tab and in the Advanced settings find "Hide extensions for known file types" checkbox, uncheck it and save.

After getting the code, you would need to modify the configuration to suit your needs. In the downloaded folder, you'll see  and   files. Rename them to  and , respectively.

Then open the  file with a text editor (if there's no associated text editor with YML files on Windows, select Notepad). Replace "Username Here" with the username of your bot, "pa55w0rd h3r3" with the password of your bot and "communitytest (replace this with your wiki's URL, e.g. The My Little Pony wiki at https://mlp.wikia.com would have 'mlp' here)" with... well... exactly what is described. Don't forget to save the file.

Then open your  file and replace it with   Don't forget to save the file.

Testing
Now you'd need to test if your installation is working.


 * Windows
 * In the directory where  and   are, create a new text file and then rename it to  . Then open it in Notepad, and insert

@echo off ruby main.rb pause
 * in it. Then save that file and double-click on it to run it.


 * Linux
 * In the directory where  and   are, create a new file and name it  . Then open it, and insert ruby main.rb in it. Then save that file, run chmod +x start.sh to make it executable and then run it with ./start.sh


 * Mac OS
 * No idea.

If you see errors in the console window, or the bot isn't entering chat after running the file, check out the troubleshooting section. If you see bot entering the chat, enter  and it should list all available commands.

Configuration
Now, the bot has some commands, and that's nice, but you didn't run the bot just to have a few commands that aren't too useful in the long run, did you? You probably didn't, so you'd have to install plugins for chatbot-rb

Installing plugins
To install a plugin, you would have to modify your  file. There are two configuration parts of it, first one is used for importing the plugins of the bot and the second one is used for registering them. Every plugin consists of their file name and class name.

In the first configuration section, to import a plugin, add a line with  replacing   with the file name of the plugin.

In the second configuration section, you can register imported plugins with adding their class names on a new line, but don't forget to separate them from earlier ones with a comma. For example:

Available plugins
Only plugins that may be of interest to a normal user are listed, there are additionally,  ,   and   plugins.


 * It's a plugin for general commands of the bot. It should be generally enabled.
 * Available commands:
 * Available commands:


 * — Makes the bot quit the chat. Requires administrator permissions
 * — Lists all available plugins. Requires chat moderator permissions
 * — Specified user will not be able to use bot commands in future. Requires chat moderator permissions
 * — Reverts effects of . Requires chat moderator permissions
 * — Lists all available commands
 * — Returns the link to the source code repository of chatbot-rb
 * This plugin makes the bot log chat into a file titled  on the local disk.
 * This plugin makes the bot log chat into a file titled  on the local disk.


 * Provides a way of checking when was a user last online.
 * Also provides a way of delivering a message to a user that is offline.
 * Available commands:
 * Available commands:


 * — Checks when was a user last seen on chat
 * — Tells the specified user a specified message. Note: Spaces in  parameter in   must be replaced with underscores, for example,   would become
 * — Cancels the delivery of a message to the specified user
 * — Checks if the message was delivered to the specified user
 * — Enables the  command. Requires chat moderator permissions
 * — Disables the  command. Requires chat moderator permissions
 * — Enables the  command. Requires chat moderator permissions
 * — Disables the  command. Requires chat moderator permissions
 * Makes the bot log the chat into wiki pages.
 * This plugin isn't guaranteed to work when the bot is hosted from a machine running Windows.
 * A bot flag on the bot would be advised if this plugin is enabled, so logging doesn't clog recent changes
 * Available commands:
 * Available commands:


 * — Posts a link to [ Project:Chat/Logs] page on the wiki.
 * — Checks when were the logs last updated
 * — Updates chat logs manually. Requires chat moderator permissions
 * Upon installing the plugin the normal way, the following lines need to be inserted into :


 * To change the location of chat logs, change  to something else.   represents the date,   month name and   year.
 * To change the category logs are categorized under, change  to something else.
 * To change how often are chat logs automatically updated, change  to the number of seconds you want to update logs on.


 * Automatic kicking/banning/warning of users upon matching certain rules.
 * See below for configuration.
 * Does not work on mods and the bot itself.
 * Does not work on mods and the bot itself.

Configuring plugin
In your config.yml file, add the following on the bottom: Adding these lines is the equivalent of not doing anything to configuration. However, now you can modify these options to your liking:
 * This is the option for configuring the word filter. Every time somebody mentions a word from this list, they get an antispam point.
 * You can configure it as following:
 * You can configure it as following:


 * If you want to use any regular expressions to detect bad words, you can put them here.
 * Format and behaviour is the same as for the  option.
 * Format and behaviour is the same as for the  option.


 * After how many antispam points gained should the user be warned about their behavior.
 * Set to a very large number to (practically) disable.
 * Set to a very large number to (practically) disable.


 * After how many antispam points gained should the user be kicked from chat.
 * Set to a very large number to (practically) disable.
 * Set to a very large number to (practically) disable.


 * After how many antispam points gained should the user be banned from chat.
 * Set to a very large number to (practically) disable.
 * Set to a very large number to (practically) disable.


 * Message to be sent after the user reaches the warn limit.
 * If there's a  in the message, it will be replaced with the user's username, only once.
 * For example, "%s, please be nice!" will show up as "&lt;username>, please be nice!" but "%s, %s, %s... you've deeply disappointed me." will throw an error and the warning won't be displayed.
 * For example, "%s, please be nice!" will show up as "&lt;username>, please be nice!" but "%s, %s, %s... you've deeply disappointed me." will throw an error and the warning won't be displayed.


 * How many seconds will the ban last after the user reaches the ban limit.
 * By default set to 31536000000, which means infinite.
 * By default set to 31536000000, which means infinite.


 * A reason for the ban after the user reaches the ban limit.
 * By default set to "Misbehaving in chat".
 * By default set to "Misbehaving in chat".


 * and
 * These configuration options control after how many messages in which amount of time should the user gain an antispam point.
 * For example, if  is set to 10 and   is set to 5, like it is by default, a user will gain an antispam point if they write more than 10 messages in the span of 5 seconds.

FAQ
Also known as frequently asked questions.


 * Can I run the bot from my account?
 * Only one instance of a user can be present in chat at once. That means if you're running the bot that logs into your account, once you enter the chat the bot would crash. So no, it's not advised to run the bot from your account.


 * Can the bot kick and ban?
 * Yes, if it has chat moderator permissions and proper instructions on how to kick and ban.
 * If you need an automoderation plugin, I could write one for you if you ask to Kocka on his FANDOM Developers Wiki talkpage


 * Do I need bot permissions on the bot account?
 * If the bot is supposed to log the chat onto the wiki, it would be advisable to ask Staff to give bot permissions to the account, so it doesn't flood recent changes.
 * If it doesn't do any edits, no, it doesn't need bot rights.

Troubleshooting
If you encountered an error when starting the bot: If none of these worked, contact Kocka on His FANDOM Developers Wiki talkpage, paste your  and   files onto Pastebin and then link them to me as well, but do not forget to remove the password of the bot before pasting contents of  . It would also be preferable if you copy or screenshot the error you're seeing in the console, if you're seeing one.
 * 1) Check if your   and   files are set up properly
 * 2) Ensure you didn't modify any other files
 * 3) Make sure you installed Ruby and the dependencies.
 * 4) Make sure username and password of the bot are correct