Easy guide to building Mastodon bots

Twitter is dead! Long live Mastodon!

I've written lots of 'bots for Twitter - and been part of their developer outreach programme. Lots of us have politely requested improvements to the bot experience on Twitter, but to no avail.

So, today I'm going to show you how to quickly and easily write your first Mastodon-bot.

Bots In Spaaaaaaace

Step 1 - you need to set up a new account for your bot. Create it on https://BotsIn.Space/ - a Mastodon instance specifically for robots.

Set it up just like a regular account. Give it a name, an avatar image, and a description. As you edit the profile, be sure to tick the box marked "This is a bot account".

Bio set up page.

Like Twitter, there's no way to officially link a bot to its owner. I suggest using the profile metadata to say who you are. But that's optional.

Step 2 - create an application. Unlike Twitter, you don't have to sign up for a development programme. Nor do you have to verify yourself with a phone number. Just go to preferences and click Development - it should take you to https://botsin.space/settings/applications

You need to set an application name - that's it. You can ignore all the other fields. By default your bot can read and write its own timeline.
New application page.
Hit save when you're done.

Click on the name of your application - and you'll see some long alphanumeric strings. These are your secret tokens.
API keys.
Do not share these with anyone. Don't take screenshots of them and post them online.

You're going to need "Your access token" for the next stage.


I'm going to assume you're using Python 3. These instructions will work on Linux. You may need to adjust this depending on your software.

Step 3 - we're going to use the Mastodon.py library.

On the commandline, run:

pip3 install Mastodon.py

After a few moments, your library will be installed.

Step 4 - create a new file called token.secret
In this file, paste the long alphanumeric string from "Your access token". Make sure you don't have a space at the start or end of the string. Save the file.

Step 5 - create a new file called bot.py
Paste the following into the file:

from mastodon import Mastodon

#   Set up Mastodon
mastodon = Mastodon(
    access_token = 'token.secret',
    api_base_url = 'https://botsin.space/'

mastodon.status_post("hello world!")

Step 6 - run the file using

python3 bot.py

You bot will "toot" - that is, post a message on Mastodon.

If all you want to do is automagically toot something - that's it. You're done. Shouldn't take you longer than 5 minutes.


You can post up to 4 images on Mastodon.

Assuming you have the image save as test.png here's the code you need:

media = mastodon.media_post("test.png", description="Some alt text.")
mastodon.status_post("What a great image!", media_ids=media)

Want to upload multiple images?

media1 = mastodon.media_post("1.jpg", description="A photo of a lovely horse.")
media2 = mastodon.media_post("2.png", description="A diagram of a starship's warp core.")
media3 = mastodon.media_post("3.jpg", description="A drawing .")
media4 = mastodon.media_post("4.gif", description="An animation of a dancing polar bear.")
mastodon.status_post("Lots of photos.", media_ids=[media1,media2,media3,media4])

There we go, nice and easy!


You can follow my Colours bot

What about...?

This is just a basic guide to getting your bot to post to Mastodon. If there's interest, I'll write about other topics.

20 thoughts on “Easy guide to building Mastodon bots

  1. […] Frühstück, Schwimmen, die Kinder spielen im Garten, Wespen!!, Ostseebot tootet, Ostseebot2 ebenfalls (ist Python nicht was feines?), Schwimmen, Feuer am Strand mit Stockbrot und […]

  2. Rebekah says:

    Thank you. I have been trying to learn about Mastodon bots. Your bot is the first one that has worked as described.

  3. kal says:

    Hello! I've never done any coding before but I guess this is how I start. Thank you for the guide! I'm gonna be playing around in Python for a while now I guess haha

  4. DJ Adams says:

    Thanks, great little tutorial, I was up and got to Hello, world! in no time.

    1. @edent says:

      Hi Mike, I've updated the tutorial. You need to pass description="Your Alt Text." when uploading.

Leave a Reply

Your email address will not be published. Required fields are marked *