Instructions for dummies from a dummy.
As some of you might know, I am a big Suikoden fan. What’s Suikoden you ask? A great JRPG series created from Konami back in 1995 for the first PlayStation. Each game stars 108 (more or less) playable characters and the story revolves around political intrigues and personal conflicts. Overall, it’s a great series which hasn’t seen a new entry since 2012, but will see the first two games remastered for current consoles soon.
Not only do I run the oldest and largest (because it’s the only) German Suikoden fanpage suikoversum.de, but I’ve also been involved with the Suikoden Revival Movement, a fan movement I started with several other dedicated individuals back in 2011 to campaign for rereleases of older games, see new merch etc. Altogether, the fandom is great, and one of the finest works in the fandom next to the dozens of highly talented fanartists was the No Context Suikoden Twitter account, which posted random bits of dialogue from the games which were mostly very silly in nature.
Now, with Twitter becoming a digital hell and my move to the Fediverse, I wanted to bring such an account also over to Mastodon (after having asked the person who ran the account if it was ok to repost images). I thought this would be easy - I mean, there are dozens of bots on Mastodon that post random cat pictures every hour, so how hard can it be?
Well, pretty hard for someone as tech savy as me. I think the most complex piece of code I’ve ever written was to change the name of every file in a directory by adding a terminal e, and even that takes me hours to write. So naturally, I was looking for good tutorials on the matter which I could simply copy&paste, but I just couldn’t find one that fitted my needs. After a couple of hours, I managed to get the bot running, and I’m so proud that I wanted to share my knowledge here in a short tutorial so if you’re also interested in writing a bot, this might help you in getting started! I try to be very detailed - possibly too detailed - in a lot of steps, but if you are a programming beginner like me, I hope you appreciate the effort.
Disclaimer As I said, I am no coding expert. The code I’m showing here works, but at what cost? Well, I have no idea, but I would greatly appreciate if people with more expertise in coding (with Python) would give feedback on the code to improve it. Also, for me, it’s mostly an educational experience, so I want to learn something, so any feedback is appreciated! You can post it directly as a comment under this post if you have a github account or contact me over at Mastodon.
As mentioned earlier, I looked for tutorials, but didn’t find any that wanted to do exactly what I do and/or were so elusive that I couldn’t follow them. I still consider it good practice to link to them, since they might be useful to you:
Going through each of these was very educational, since it helped me understanding where my understanding was still lacking! If you have found other tutorials, please share them!
To use this guide, you should fulfill the following conditions:
And that’s essentially it! All of the above is free, but you can of course use different websites and programs to start a bot. I’m not even sure my approach applies with the github ToS … but that’s a problem for another day.
First, we need to define what our bot should do in the end. I sketched the workflow as follows:
All of this should be automated and my only job is the selection of images and generation of status text and alt text. I don’t want to do anything manually afterwards at all!
Even though I talk about a bot, the entire thing is actually divided in two parts:
This guide will help you set up both. Let’s go!
We will use the fantastic mastodon.py package which will streamline a lot of the process of our small program. However, it also takes a bit of time to get used to, so we let’s say “Hello!” to our new friend.
If your app should communicate with your Mastodon account, you first need to register the app. While this can be done also using mastodon.py, I think it’s easier to just do it manually. If you want to start 100 bots, doing it automatically is probably a big time saver.
Log into your Mastodon bot account and go to Settings > Development and click on new application. Give your application a name (it doesn’t matter, but it will be visible later on the Mastodon interface, so chose something neutral like “Autoposter”) and ignore the website field. Here, you select the permissions of your bot. Since the bot I envision only posts text and photo posts, the only permissions I need are
I deselect every other option. Of course, if you want a more elaborate bot that automatically favourites certain posts or should be a bit interactive, you’ll need to select these permissions. I won’t cover any of that here, though. You can also change the permissions (but not the name of the bot) afterwards if you need to.
After you submitted your application, you find it listed in the Development tab. Click on it and you see a bunch of parameters on top. Don’t share your client key, secret, or access token with anybody. With these, anyone could access your bot and do all kind of things. We will need them later for our bot.
You’re already finished, but it is good practice to mark your account as a bot account. To do so, you find a checkbox under Settings > Profile. Checking it will put a small “bot” icon next to your account name.
Now we are ready to write our first small program. As a test, we will send a small “Hello world!” message to our profile, because … well, why not. So create a file called run.py
(or be more creative than me) and start editing it.
We’ll need to first import the Mastodon module:
from mastodon import Mastodon
This allows us to use all the nice mastodon.py
functions! And we will directy start with one, which is probably the most important one, as it tells our program where to find our bot and that it is authenticated:
# Setting up Mastodon
mastodon = Mastodon(
access_token='[ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789]', # this is your access token from the Development tab from the step before
api_base_url='botsin.space' # this is the URL of your bot's server
)'
As I said earlier, the access token is very sensitive information. If you plan on making your bot somehow public, you shouldn’t put it in the file as we did now. We will address this later in more detail and how to avoid it!
Finally, we write our small post using the Mastodon.status_post
function (more details on the function can be found here). We can use this function and use lots of attributes. The full function looks like this:
Mastodon.status_post(status, in_reply_to_id=None, media_ids=None, sensitive=False, visibility=None, spoiler_text=None, language=None, idempotency_key=None, content_type=None, scheduled_at=None, poll=None, quote_id=None)
`
And the attributes we’ll need are:
status
- is the text of the postsmedia_ids
- will be used later for our photo positionssensitive
- whether the photos will be marked as sensitive or notespoiler_text
- whether our post will include a spoiler/content warninglanguage
- will be default the language set in our profile (in our case, en
), but I plan to include multi-language posts in the futureWe can safely ignore the remaining attributes. To write our small “Hello World!” message, we need to simply input the following:
Mastodon.status_post("Hello World!")
The final program looks like this:
from mastodon import Mastodon
# Setting up Mastodon
mastodon = Mastodon(
access_token='[ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789]', # this is your access token from the Development tab from the step before
api_base_url='botsin.space' # this is the URL of your bot's server
)'
# Write a "Hello World!" post
Mastodon.status_post("Hello World!")
Run the program and see how the post is posted. Congrats on the first step!
Let’s now try something more complicated and upload an image. First, we’ll