mattata is a powerful, plugin-based Telegram bot similar to topkecleon's. mattata boasts many nifty features such as a fully-fledged administration plugin, AI (native Cleverbot implementation, which utilises my mattata-ai library) and much more.
Installing & configuring mattata is very simple. Clone the repository using git clone git://github.com/wrxck/mattata.git. Then, run the appropriate installation script located inside mattata/install/.
You'll need sudo access to be able to install the dependencies required. Then, you need to fill in the values in configuration.example.lua. After you've done that, rename configuration.example.lua to configuration.lua, and use ./launch.sh to start your bot.
mattata features an extensive, robust plugin system, similar to topkecleon's. Below is a table containing a list of currently-documented plugins and their corresponding usage information.
| Command | Description | Aliases | Flag |
|---|---|---|---|
| /administration | Configure the administration settings for your chat through an interactive menu sent via private message. | /antispam | 2 |
| /apod [dd/mm/yyyy] | Sends the Astronomy Picture of the Day via NASA's API. If a date is given, the Astronomy Picture for that date is returned. | - | 1 |
| /appstore <query> | Displays information about the first app returned by iTunes for the given search query. | /app | 1 |
| /avatar <user> [offset] | Sends the profile photos of the given user, of which can be specified by username or numerical ID. If an offset is given after the username (which must be a numerical value), then the nth profile photo is sent (if available). | - | 1 |
| /ban [user] | Bans a user from the group. The user must be specified by username/ID, or by reply. | - | 2 |
| /base64 <text> | Converts a string of text into base64-encoded text. | /b64 | 1 |
| /bash <snippet> | Executes a snippet of Bash on the host server, and returns the result. | - | 4 |
| /belikebill <text> | Generates a Be Like Bill meme using the given text as the caption. | /blb | 1 |
| /binary <text> | Converts a numerical value into binary. | /bin | 1 |
| /bing <query> | Searches Bing for the given search query and returns the top results. | - | 1 |
| /blacklist [user] | Prevents a user from using the bot in the chat. The user must be specified by username/ID, or by reply. | - | 2 |
| /bugreport <text> | Reports a bug to the configured developer. | /bug, /br | 1 |
| /calc <expression> | Solves the given mathematical expression using mathjs.org. | - | 1 |
| /canitrust <url> | Reveals any known security issues with a website. | - | 1 |
| /catfact | Sends a random, cat-themed fact. | - | 1 |
| /cat | Sends a random photo of a cat. | /sarah | 1 |
| /channel <channel> <message> | Sends a message to a Telegram channel/group. The channel/group can be specified via ID or username. Messages can be formatted with Markdown. Users can only send messages to channels/groups they own and/or administrate. | /ch, /msg | 2 |
| /chuck | Sends a random Chuck Norris joke. | - | 1 |
| /clickbait | Generates a random, click-bait article headline. | - | 1 |
| /coinflip [guess] | Flips a coin and returns the result! If a guess is given, the result is tested against it and reveals the accuracy accordingly. | /cf | 1 |
| /copypasta | Riddles the replied-to message with cancerous emoji. | /?? | 1 |
| /counter | Adds a view count to the replied-to message. | /count | 1 |
| /currency <amount> <from> to <to> | Converts exchange rates for various currencies via Google Finance. | /convert, /cash | 1 |
| /demod [user] | Strip a user of their moderator status, revoking their ability to use administrative commands such as /ban, /kick and /unban. The user must be specified by username/ID, or by reply. | /demote | 3 |
| /developer | Connect with the developer through his social media. | /dev | 1 |
| /dice <number> <range> | Rolls a die - returning random numbers between 1 and the given range the given number of times. | - | 1 |
| /dictionary <word> | Looks up the given word in the Oxford Dictionary and returns the relevant definition(s). | /define | 1 |
| /dns <url> <record type> | Sends the given URL's DNS records of the given type. The record types currently supported are AAAA, A, CERT, CNAME, DLV, IPSECKEY, MX, NS, PTR, SIG, SRV and TXT. | - | 1 |
| /doge <text> | Doge-ifies the given text. Sentences are separated using slashes. Example: /doge hello world/this is a test sentence/make sure you type like this/else it won't work! | /dogify | 1 |
| /doggo | Sends a random photo of a dog. | /dog, /josh | 1 |
| /donate | Make an optional, monetary contribution to the mattata project. | - | 1 |
| /duckduckgo <query> | Searches DuckDuckGo's instant results for the given search query and returns the most relevant result. | /ddg | 1 |
| /echo <text> | Repeats the given string of text. | - | 1 |
| /eightball | Makes a decision for you using the (virtual) magic 8 ball! | /8ball | 1 |
| /exec <language> <code> | Executes the specified code in the given language and returns the output. | - | 1 |
| /facebook <username> | Sends the profile picture of the given Facebook user. | /fb | 1 |
| /fact | Returns a random (and somewhat-false!) fact. | - | 1 |
| /flickr <query> | Searches Flickr for a photo matching the given search query and returns the most relevant result. | - | 1 |
| /fortune | Sends your fortune (featuring a seasonally-adjusting ASCII animal!). | - | 1 |
| /frombin <binary> | Converts the given string of binary to a numerical value. | - | 1 |
| /gif <query> | Searches GIPHY for the given search query and returns a random, relevant result. | /giphy | 1 |
| /github <user> <repository> | Returns information about the specified GitHub repository. | /gh | 1 |
| /google <query> | Searches Google for the given search query and returns the most relevant result(s). | /g | 1 |
| /hackernews | Sends the top stories from Hacker News. | /hn | 1 |
| /help | A help-orientated menu with a sleep inline keyboard for navigation. | /start | 1 |
| /hexadecimal <text> | Converts the given string of text into hexadecimal. | /hex | 1 |
| /hextorgb <hex code> | Converts the given hex colour code into its RGB format. | /hrgb | 1 |
| /id [chat] | Sends information about the given chat. Input is also accepted via reply. | /whoami | 1 |
| /identicon <text> | Generates an identicon from the given string of text. | /icon | 1 |
| /imdb <query> | Searches IMDb for the given search query and returns the most relevant result(s). | - | 1 |
| /instagram <username> | Sends the profile picture of the given Instagram user. | /ig | 1 |
| /insult | Generates a random insult. | - | 1 |
| /isp <url> | Sends information about the given URL's Internet Service Provider (ISP). | - | 1 |
| /ispwned <account> | Returns the existence of the given account in any major data leaks. | - | 1 |
| /isup <url> | Checks to see if the given URL is down for everyone or just you. | - | 1 |
| /itunes <query> | Searches iTunes for the given search query and returns the most relevant result. | - | 1 |
| /jsondump | Returns the raw JSON of your message. | /json | 1 |
| /kick [user] | Bans, then unbans, a user from the chat (also known as a "soft-ban"). The user must be specified by username/ID, or by reply. | - | 2 |
| /lastfm [username] | Returns what you, or the given Last.fm user, last listened to on Last.fm. | /np | 1 |
| /license | View mattata's license. | - | 1 |
| /link | Sends the group link. | - | 1 |
| /lmgtfy <query> | Sends a LMGTFY link for the given search query. | - | 1 |
| /location [query] | Sends your location, or a location from Google Maps. | /loc | 1 |
| /loremipsum | Generates a paragraph of Lorem Ipsum text. | - | 1 |
| /lua <script> | Executes a snippet of Lua on the host server, and returns the result. | - | 4 |
| /lyrics <query> | Finds the lyrics to the given track. | - | 1 |
| /me <emote message> | Allows you to emote, Minecraft-style. | - | 1 |
| /minecraft <username> | Sends information about the given Minecraft user. | /mc | 1 |
| /mod [user] | Promote the given user to moderator status, allowing them use of administrative commands such as /ban, /kick and /unban. The user must be specified by username/ID, or by reply. | /promote | 3 |
| /msglink | Gets the link to the replied-to message. | - | 1 |
| /name <text> | Changes the name that the bot's AI responds to. | - | 2 |
| /netflix <query> | Searches Netflix for the given search query and returns the most relevant result. | /nf | 1 |
| /news <source> | Sends the current top story from the given news source. | - | 1 |
| /ninegag | Returns a random image from the latest 9gag posts. | /9gag | 1 |
| /nsources [query] | Returns a list of available sources that can be used with /news. If a query is given as a command argument, a Lua pattern match for the given query is made and a list of matching news sources is returned. | - | 1 |
| /paste <text> | Uploads the given text to a pasting service and returns the result URL. | - | 1 |
| /pay <amount> | Sends the replied-to user the given amount of mattacoins. | - | 1 |
| /plugins | Toggle the plugins you want to use in your chat with a slick inline keyboard, paginated and neatly formatted. | - | 2 |
| /pokedex <query> | Returns a Pokedex entry from pokeapi.co. | /dex | 1 |
| /prime <number> | Tells you if a number is prime or not. | - | 1 |
| /pun | Generates a random pun. | - | 1 |
| /qr <text> | Converts the given string of text to a QR code. | /qrcode | 1 |
| /randomword | Generates a random word. | /rw | 1 |
| /reddit <subreddit/query> | Returns the latest posts from the given subreddit, or for the given query. | /r, /r/subreddit | 1 |
| /remind <duration> <message> | Repeats a message after a duration of time, in the format 1w2d3h4m. The maximum number of reminders at one time is 4 per chat, and each reminder must be between 1 minute and 4 weeks in duration. Reminders cannot be any more than 256 characters in length. Use /reminders to view your current reminders. An example use of this command would be: /remind 1w2d3h4m test, which would remind you in 1 week, 2 days, 3 hours and 4 minutes. | - | 1 |
| /rimg <width> [height] [-g/-b] | Sends a random image which matches the dimensions provided, in pixels. If only 1 dimension is given, the other is assumed to be the same. Append -g to the end of your message to return a grayscale photo, or append -b to the end of your message to return a blurred photo. The maximum value for each dimension is 5000, and the minimum for each is 250. | - | 1 |
| /s/<pattern>/<substitution> | Replaces all occurences, of text matching a given Lua pattern, with the given substitution. | - | 1 |
| /setlang | Allows you to select your language. | - | 1 |
| /setloc <location> | Sets your location to the given value. | - | 1 |
| /setnews <source> | Sets your preferred news source for use with /news. | - | 1 |
| /setsteam <text> | Sets your Steam username to the given text | - | 1 |
| /setwelcome <text> | Sets the group's welcome message to the given text. Markdown formatting is supported. | - | 2 |
| /shorten <url> | Shortens the given URL using one of the given URL shorteners. | - | 1 |
| /shout <text> | Shouts the given text in multiple directions! | - | 1 |
| /slap [target] | Slaps someone, or something. | - | 1 |
| /snapchat <username> | Sends the "Snap" code for the given Snapchat username. | /sc | 1 |
| /spotify <query> | Searches Spotify for a track matching the given search query and returns the most relevant result. | - | 1 |
| /statistics | Shows statistical information about the current chat's top ten users (ordered by message count). | /stats | 1 |
| /steam [username] | Displays information about the given Steam user. If no username is specified then information about your Steam account (if applicable) is sent. | - | 1 |
| /synonym <word> | Sends a word similar to the one given. | - | 1 |
| /theme | Get a theme for Telegram Desktop created by mattata's developer! | - | 1 |
| /thoughts <query> | Discover what the Internet thinks about the given search query. | - | 1 |
| /time [location] | If no arguments are given; the current time, date, and timezone for your location are sent (if applicable). Otherwise, the current time, date and timezone for the given location is returned. The returned location is the first relevant result on Google Maps for the given search query. | - | 1 |
| /tpb | Sends a list of working Pirate Bay proxies. | /thepiratebay | 1 |
| /translate [locale] <text> | If a locale is given, the given text is translated into the said locale's language. If no locale is given then the given text is translated into the bot's configured language. If the command is used in reply to a message containing text, then the replied-to text is translated and the translation is returned. | /tl | 1 |
| /twitch <query> | Searches Twitch for the given search query and returns the most relevant result(s). | - | 1 |
| /unicode <text> | Returns the given text as a JSON-encoded table of Unicode (UTF-32) values. | - | 1 |
| /urbandictionary <query> | Searches the Urban Dictionary for the given search query and returns the most relevant result(s). | /urban, /ud | 1 |
| /uuid | Generates a random UUID. | /guid | 1 |
| /version | Returns information about this instance of mattata. | /about | 1 |
| /weather [location] | If no arguments are given, the weather forecast for your known location is given. If a location is given, then the weather forecast for that location is given instead. | - | 1 |
| /whitelist [user] | Allows a previously-blacklisted user to use the bot in the chat again. The user must be specified by username/ID, or by reply. | - | 2 |
| /whois <ip address> | Performs a WHOIS lookup for the given IP address and returns the result. | - | 1 |
| /wikipedia <query> | Searches Wikipedia for the given search query and returns the most relevant article. | /wiki, /w | 1 |
| /xkcd [query] | Returns the latest xkcd strip and its alt text. If a number is given, returns that number strip. If 'r' is passed in place of a number, returns a random strip. Any other text passed as the command argument will search Google for a relevant strip and, if applicable, return it. | - | 1 |
| /yify <query> | Searches Yify Torrents for the given search query and returns the most relevant result(s). | - | 1 |
| /yomama | Tells a Yo' Mama joke! | - | 1 |
| /youtube <query> | Searches YouTube for the given search query and returns the most relevant result(s). | /yt | 1 |
Arguments enclosed in [square brackets] are optional, and arguments enclosed in are required.
You will notice there is a "Flag" column. This is a number which indicated what rights the user must have in order to use the corresponding command(s). Below is a table which explains what each number means:
| Flag | Name | Description |
|---|---|---|
| 1 | User | All users are in this flag by default. It simply means they exist. This is the lowest flag. |
| 2 | Moderator | This flag contains all people of the moderator rank and higher. Moderators are non-official admins who have access to administrative commands, such as /ban, /kick and /unban. Moderators are granted this rank when an administrator replies to their message with /mod or /promote. |
| 3 | Administrator | This flag contains all of the official group administrators. These are all of the people who have been promoted to an administrator by the creator of the group/channel. These people will have a star displayed next to their name in the member list on your client. |
| 4 | Owner | This is a small category containing only the users who are in the admins array of the configuration.lua file. This rank means that the user has access to owner commands such as /bash and /lua, and can control the bot using /reload. This is the highest flag. |
All permissions levels are hereditary - meaning a user in flag 3 is also in flags 1 & 2.
As well as feedback and suggestions, you can contribute to the mattata project in the form of a monetary donation. This makes the biggest impact since it helps pay for things such as server hosting and domain registration. A donation of any sum is appreciated and, if you so wish, you can donate here.
I'd like to take a moment to thank the following people for their donation(s):
- j0shu4
- para949
- aRandomStranger
- mochicon
- xenial
- fizdog
- caidens
- LKD70
- xxdamage
- aaomidi