Elephant-Framework -- by [email protected]
A framework that helps simplify the creation of bots for mastodon/pleroma
Uses rufus-scheduler in the backend
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
gem install elephrame
bot that posts "trans right are human rights" every three hours:
require 'elephrame' my_bot = ::::. '3h' my_bot.run do |bot| bot.post("trans rights are human rights") end
$ INSTANCE="https://mastodon.social" TOKEN="your_access_token" ruby bot.rb
Check the examples directory for more example bots
If you're new to ruby development in general there is also a getting started document in the examples folder that I would recommend you to read. It takes a high level approach to getting started with ruby, some basic syntax, working with gems, basic project structure, and more!
So far the framework support 6 bot types: Periodic, Interact, PeroidInteract, Reply, Command, Watcher
Periodicsupports posting on a set schedule
Interactsupports callbacks for each type of interaction (favorites, boosts, replies, follows)
PeriodInteractsupports both of the above (I know, this isn't a good name)
Replyonly supports replying to mentions
Commandsupports running code when mentioned with commands it recognizes
Watchersupports watching streaming timelines (including lists, hashtags, public timeline, local timeline, and user timeline)
TraceryBotsupports automatically loading tracery rules. Overloads post method to automatically expand any text passed through it. This bot type provides certain options that ease the use of tracery grammar rules, please see examples and/or documentation for more explanation.
EbooksBotprovides a very quick and easy way to create an ebooks bot. Please see the example in the examples folder for a detailed explanation.
MarkovBotprovides a quick way to get started with making markov bots. Please see the example in the examples folder.
Both the Ebooks and Markov bots support a few commands out of the box.
!help. These commands will only work when sent from an account that the bot is following. The Ebooks bot supports
!update as well.
Any time a 'time' string is needed it must be either a 'Duration' or 'Cron' string as parsable by fugit
All the documentation is over at RubyDoc!
Every place that accepts a block provides access to the bot object. This allows for easy access to some provided helper methods, as well as the actual mastodon access object.
Exposed methods from bot object:
clientthis is the underlying mastodon rest client we use in the backend. use this to make custom calls to the api for which we don't provide a helper
usernamethe name of the bot as fetched by verify_credentials
strip_html(defaults to true) if set, the framework will automatically strip all html symbols from the post content
max_retries(defaults to 5) the maximum amount of times the framework will retry a mastodon request
faileda hash that represents the status of the last post or media upload.
failed[:media]; returns true if it failed, false if it succeeded
post(content, visibility: 'unlisted', spoiler: '', reply_id: '', hide_media: false, media: )this provides an easy way to post statuses from inside code blocks
reply(content, *options)a shorthand method to reply to the last mention (Note: only include the @ for the user who @ed the bot)
reply_with_mentions(content, *options)similar to
replybut includes all @s (respects #NoBot)
find_ancestor(id, depth = 10, stop_at = 1)looks backwards through reply chains for the most recent post the bot made starting at post
iduntil it hits
depthnumber of posts, or finds
stop_atnumber of it's own posts
no_bot?(account_id)returns true if user with
account_idhas some form of "#NoBot" in their bio or their profile fields
fetch_list_id(name)return the id of a list with given name
fetch_account_id(account_name)return the id of an account with given handle
(See RubyDocs for source code documentation)
In the Wild!
Here's a list of bots that are currently using this framework. If you are using it, add yourself to this list and submit a pull request!
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake test to run the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install.
Bug reports and pull requests are welcome on GitHub at https://github.com/theZacAttacks/elephrame. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
Code of Conduct
Everyone interacting in the Elephrame project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.