-
Notifications
You must be signed in to change notification settings - Fork 0
Features
Private Parlor XT's most notable features, and how to use them, are described below.
The system messages, log messages, and command descriptions seen in the bot are all pulled from files. One of the existing files in the locales folder can be chosen using the locale field in the configuration file, config.yaml.
Alternatively, a copy of a locale file can be made and edited to alter how the messages will appear. This edited file should be located in the same folder as the other locales, and the file can be chosen by updating the locale field with the file name, without the .yaml extension.
As well as logging to the console and/or a file, log messages can be relayed to a Telegram channel.
To do this, the bot must first be an admin in the channel with the 'post messages' permission. When the log_channel field in the configuration file must is set to the ID of the channel, log messages will then be relayed to the channel.
If the channel is private, this ID should start with -100.
Over time, information about a message is forgotten by the program once the message is too old and expired. Once forgotten, the message can no longer be replied to, deleted, or interacted with in any way. The duration for which a message may exist is the message lifespan, and can be configured.
The default message lifespan is 24 hours, but can be made to be less or longer than that by setting the message_lifespan field in the configuration file. Message lifespan can be disabled all together, persisting messages until the bot restarts, by setting message_lifespan to 0
Note that keeping track of messages uses up RAM; the program will use up more RAM keeping message around for longer than if they were kept around for less time.
As well, messages that are 48 hours old or older cannot be deleted, but they can still be interacted with. For instance, if the message_lifespan is 72 hours, and a message is 48 hours old, it can still be replied to, but it cannot be removed or deleted for everyone in the chat. If a messages should be deleted, it should be deleted within 2 days.
Because of the RAM requirements for keeping messages, the database can be used to store messages without using RAM.
Toggling the database_history field in the configuration file will store message information such as sender ID, receivers, and sent time in the SQLite database used for keeping track of users. This information will persist after a restart, and message_lifespan can be safely set to 0 to disable message expiration, keeping messages around forever.
The bot can be made to record statistics during runtime and make them viewable to users by enabling statistics in the configuration file.
This field will enable a module that will record the date it started and then record message information. The information the module records is as follows:
- Date that the module was first enabled
- Total number of messages sent
- Total number of each type of message sent (Photos, text messages, GIFs)
- Total number of unoriginal messages sent
- Total number of upvotes/downvotes
This information can then be viewable using the /stats command, which will showcase the following information:
- Date that the module was first enabled
- How long the bot has been running
- Relevant configuration information (Message lifespan, whether or not Robot9000 is enabled, media limit period)
- Total number of users
- How many users joined/left today, this week, and this month
- Total number of messages
- Total number of messages for each type
- How many messages were sent today, this week, and this month
- Total number of upvotes/downvotes
- How many upvotes/downvotes were sent today, this week, and this month
- Total number of unoriginal messages
- Total number of users for each karma level
What information to show can also be modified in a locale file.
Messages containing media such as photos, videos, and animations can be sent with a spoiler animation that covers the contents when media_spoilers in the configuration file is enabled.
Otherwise, a message containing media that has already been sent can be given a spoiler using the /spoiler command. Using the command on the same message will remove the spoiler.
Upvotes and downvotes can include a reason detailing why the message was upvoted or downvoted when karma_reasons is enabled. This reason will be logged and privately sent to the receiving user.
Users who have not sent a message for too long can be kicked for inactivity. Setting inactivity_limit in the configuration file will kick users from the chat, as though they had used the /stop command, if the user has not sent a message in the set number of days.
Disabling registration_open in the configuration file will prevent new users from joining. If this is enabled, the /whitelist command can be used to manually permit a user to join.
Setting pseudonymous in the configuration file will make it so that every user must use a tripcode. This will prompt the user to make a tripcode if the user does not have one, and automatically add the tripcode to every one of the user's messages.
The tripcode can be replaced with a signature composed of flags/Emoji by setting flag_signatures
A tripcode_salt can be set to be used when generating tripcodes, making it more difficult for a tripcode password to be bruteforced.
Users can be given a level based on the amount of karma a user has if karma_levels is set.
Users can then view their progress towards the next level using the /karma_info command, and sign messages with the name of their karma level using the /ksign command.
Robot9000 can be enabled in the bot to enforce uniqueness in text and media.
Setting either or both of toggle_r9k_text and toggle_r9k_media will enable the Robot9000 module.
With toggle_r9k_text, only text in text messages and media captions are judged for uniqueness. This will make the module behave similarly as Robot9000 works on the 4chan /r9k/ board.
With toggle_r9k_media, only photos, videos, GIFs, files, and other forms of media are judged for uniqueness.
Both settings can be enabled to judge text and media for uniqueness at the same time.
By default, the contents of forwarded messages are not validated for uniqueness unless toggle_r9k_forwards is enabled.
Users who are caught sending unoriginal messages will be automatically notified that the message is not unique. The user can be prevented from sending messages for a period of time if r9k_cooldown is enabled. Enabling r9k_warn will give the user a warning and a cooldown, which will scale based on the number of warnings the user has. If both are enabled, only r9k_cooldown will be relevant; the two fields are mutually exclusive.
Due to Robot9000's validation of text for uniqueness, it is possible for the user to send text with different characters that look similar to bypass the checks. For instance the strings "text" and "𝗍𝖾x𝗍" may look the same but the former uses ASCII and the latter uses some mathematical alphanumeric characters. Robot9000 considers these two strings are different and unique, but their meanings are the same.
To fix this, the valid_codepoints field can be set to contain an array of acceptable characters; text which contains any characters not found in these ranges will be deemed invalid and Robot9000 will not accept them.
These ranges are represented as 2 element arrays of at most 32 bit hexadecimal numbers, describing the start and end of the character range. By default, Robot9000 uses the character ranges [0x0000, 0x007F] for ASCII and [0x1F600, 0x1F64F] for basic Emojis. This means that only English text and some Emojis are permitted; anything else, such as Chinese text or food emojis will not be accepted.
To find ranges for other character ranges, the Unicode Character Code Charts can be used. Some examples of possible character ranges are as follows:
- [0x0080, 0x00FF] - Latin characters with diacritics
- [0x4E00, 0x9FFF] - CJK ideographs (Hanzi, Kanji, Hanja)
- [0x1F900, 0x1F9FF] - Miscellaneous symbols, may be rendered as Emojis on Telegram
Every user has a rank which determines what the user can and cannot do. These ranks can be configured in the ranks field of the configuration file. There can be multiple ranks with varying names and permissions. Permissions can permit users to send different kinds of messages or use certain commands. Permissions for any given rank are described in the Rank Permissions page.
A rank with the value -10 is required by default and will be set if it does not exist in ranks. This rank can be renamed, but no permissions given to it will matter, as this rank represents a blacklisted user who cannot chat in the bot.
Users of ranks with values greater than 0 are considered privileged and are not subject to the media limit period, while users of ranks less than 0 can be considered restricted.
Users with ranks that can use the /ranksay command can sign a message with the name of the rank. The user can alternatively use a command in the format /[name]say where [name] is the name of the user's rank. Because commands must be English with only underscores and digits, the name of the rank with all non-English characters stripped will be used for this kind of /[name]say command. Names can still have non-English characters, but the generated /[name]say command may not be obvious.
The default_rank field can be set which will make new users or demoted users members of that rank. The value for this field should match one of the values for a rank set in ranks. If it does not, it will be set to 0 and represent a basic user rank.
Specific types of messages and certain commands can be disabled in the configuration file.
For message toggles, these take either true or false, enabling or disabling users to send messages of that type. For instance, setting relay_photos to true will allow users to send photos, while setting relay_text to false will prevent users from sending text messages.
Command toggles work similarly, but take a two-element array of either true or false. The first element determines whether the command is enabled, whereas the second element determines if the command should be registered with @BotFather, so that the command shows up in the menu. For example, setting enable_info to [true, false] will make that command useable, but will not make it available in the bot menu.
Command and message toggles take precedent over rank permissions. That is, if a command is disabled, a rank with permission to use that command still wont be able to use it. The bot will notify if a rank has a permission for a command or message type that is disabled, and will remove it from that rank during runtime.
Messages can be pinned to the chat for everybody like a group chat using the /pin command.
Messages can be unpinned using the /unpin command. This will either unpin the most recently pinned message, or unpin a specific messaged replied to. If using a reply, the message replied to much not have expired.
Users who join after a message is pinned, however, won't see the pinned message since the message does not exist for them.
Users who do not want to /sign and make their usernames public to everyone can chose to privately reveal their usernames to a specific user being replied to. The username revealed will be logged along with the message replied to.
Albums can be relayed by the bot when relay_media_groups is set. These albums can contain at most 10 items being photos, videos, animations, or files, just like albums do in general. Each item in the album is considered a message, and any item can be deleted, spoiled, or upvoted without affected the rest of the album.
The duration of a cooldown and its severity can be configured using cooldown_base, warn_lifespan, and warn_deduction.
When a user is given a cooldown either from having a message deleted (using /delete) or warned, the user cannot send another message for a duration of time. This duration is determined by the cooldown_base multiplied by itself according to how many warnings the user has, making cooldowns increase exponentially; the resulting number is the amount of minutes the user is cooldowned. Cooldown durations cannot exceed 1 year, even if the resulting number far exceeds 1 year's worth of minutes.
When a user is cooldowned, a warning is also given that will affect future cooldowns. A warning will eventually expire, making the next cooldown less severe. The time in hours that a warning can exist before expiring is determined by warn_lifespan.
A user's hard-earned karma can be removed with each cooldown as well. The amount to remove is determined by warn_deduction.
Users can be prevented from sending a specific type of message unless they have the sufficient amount of karma. If the user has sufficient karma, that message will be sent and the amount the message was worth will be deducted.
For instance, if karma_photo is set to 5, a user must have 5 karma or more to send a photo. Upon sending the photo, the user's karma will be 5 points less than what it was previously.
A cutoff_rank can also be set, making it so that users ranks equal to or greater in value are not required to have a certain amount of karma for any message.
Spam scores for different message types can be configured, changing how much they are worth towards the spam_limit.
If the spam_handler is enabled, messages sent by a user will be judged based on their score, and the amount will be added to the user's spam score. If the user's score exceeds spam_limit, the user is temporarily cooldowned until their score decreases below the limit. The amount at which spam scores decrease is determined by decay_amount, and the interval in seconds at which these scores decay is determined by spam_interval. Setting spam_interval to 0 will disable spam prevention entirely.
Limits for upvotes, downvotes, and username-signed messages can be configured using upvote_limit_interval, downvote_limit_interval and sign_limit_interval, respectively. These values are measured in seconds and prevent the user from sending another upvote, downvote, or username-signed message within the interval of seconds of sending a previous message of that type. These intervals do not apply if spam prevention is disabled.