Mirror your favorite Twitter accounts in the Fediverse, so you can follow their updates from the comfort of your favorite instance. Or migrate your own to the Fediverse using a Twitter archive.
You can find this project at:
GitHub | Gitlab | Gitea |
---|---|---|
pleroma-bot | pleroma-bot | pleroma-bot |
Supports:
Mastodon | Pleroma | Misskey |
---|---|---|
![]() |
![]() |
![]() |
After using the pretty cool mastodon-bot for a while, I found it was lacking some features which were of use to me.
For precisely those cases I've written this Python project that automates them, asking such info to Twitter's API and updating the relevant fields on the Pleroma API/Mastodon API/Misskey API side.
So basically, it does the following:
$ pip install pleroma-bot
Here's a list of the available packages.
Package type | Link | Maintainer |
---|---|---|
AUR (Arch) | https://aur.archlinux.org/packages/python-pleroma-bot | robertoszek |
$ pleroma-bot [-c CONFIG] [-l LOG] [--noProfile] [--daemon] [--forceDate [FORCEDATE]] [-a ARCHIVE]
Bot for mirroring one or multiple Twitter accounts in Pleroma/Mastodon.
optional arguments:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG
path of config file (config.yml) to use and parse. If
not specified, it will try to find it in the current
working directory.
-d, --daemon run in daemon mode. By default it will re-run every
60min. You can control this with --pollrate
-p POLLRATE, --pollrate POLLRATE
only applies to daemon mode. How often to run the
program in the background (in minutes). By default is
60min.
-l LOG, --log LOG path of log file (error.log) to create. If not
specified, it will try to store it at your config file
path
-n, --noProfile skips Fediverse profile update (no background image,
profile image, bio text, etc.)
--forceDate [FORCEDATE]
forces the tweet retrieval to start from a specific
date. The twitter_username value (FORCEDATE) can be
supplied to only force it for that particular user in
the config
-s, --skipChecks skips first run checks
-a ARCHIVE, --archive ARCHIVE
path of the Twitter archive file (zip) to use for
posting tweets.
-t THREADS, --threads THREADS
number of threads to use when processing tweets
-L LOCKFILE, --lockfile LOCKFILE
path of lock file (pleroma-bot.lock) to prevent
collisions with multiple bot instances. By default it
will be placed next to your config file.
--verbose, -v
--version show program's version number and exit
There are multiple options for using the bot.
You can either choose to use:
You'll need to create a configuration file and obtain the Fediverse tokens for your accounts no matter what you choose to use.
If you plan on retrieving tweets from an account which has their tweets protected, you'll also need the following:
You'll may also need Elevated access in your Twitter's API project in order for the bot to function properly.
Refer to the docs for more info about this.
Create a config.yml
file in the same path where you are calling pleroma-bot
(or use the --config
argument to specify a different path).
There's a config example in this repo called config.yml.sample
that can help you when filling yours out.
For more information you can refer to the "Configuration" page on the docs.
Here's what a minimal config looks like:
# Change this to your target Fediverse instance
pleroma_base_url: https://pleroma.instance
# How many tweets to gather per-user in every execution
# Twitter's API hard limit is 3,200
max_tweets: 40
# Twitter bearer token
twitter_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
users:
- twitter_username: User1
pleroma_username: MyPleromaUser1
# Mastodon/Pleroma bearer token
pleroma_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
If you're running the bot for the first time it will ask you for the date you wish to start retrieving tweets from (it will gather all from that date up to the present).
If you leave it empty and just press enter it will default to the oldest date that Twitter's API allows ('2010-11-06T00:00:00Z
') for tweet retrieval.
To force this behaviour in future runs you can use the --forceDate
argument (be careful, no validation is performed with the already posted toots/posts by that Fediverse account and you can end up with duplicates posts/toots!).
Additionally, you can provide a twitter_username
if you only want to force the date for one user in your config.
For example:
$ pleroma-bot --forceDate WoolieWoolz
If the --noProfile
argument is passed, the profile picture, banner, display name and bio will not be updated on the Fediverse account. However, it will still gather and post the tweets following your config's parameters.
NOTE: An error.log
file will be created at the path from which pleroma-bot
is being called.
(everyday at 6:15 AM) update profile and (every 10 min.) post new tweets:
# Post tweets every 10 min
*/10 * * * * cd /home/robertoszek/myvenv/ && . bin/activate && pleroma-bot noProfile
# Update pleroma profile with Twitter info every day at 6:15 AM
15 6 * * * cd /home/robertoszek/myvenv/ && . bin/activate && pleroma-bot
NOTE: If you have issues with cron running the bot you may have to specify the full path of your Python executable
*/10 * * * * /usr/bin/python /usr/local/bin/pleroma-bot
These projects proved to be immensely useful, they are Python wrappers for the Mastodon API and Twitter API respectively:
They were part of the impetus for this project, challenging myself to not just import them and use them, instead opting to directly do the heavy lifting with built-in python modules.
That and mastodon-bot not working after upgrading the Pleroma instance I was admin on 😅. This event lead to repurposing this project (initially it only updated the profile info) and adding the tweet gathering and posting capabilities.
Patches, pull requests, and bug reports are more than welcome, please keep the style consistent with the original source.
MIT License
Copyright (c) 2023 Roberto Chamorro / project contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Tested and confirmed working against :
Pleroma BE 2.4.2
Mastodon v3.2.1
Misskey 12.110.1
Twitter API v1.1 and v2