Easy guide to building Mastodon bots

by @edent | , , | 7 comments | Read ~2,575 times.

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")
mastodon.status_post("What a great image!", media_ids=media)

Want to upload multiple images?

media1 = mastodon.media_post("1.jpg")
media2 = mastodon.media_post("2.jpg")
media3 = mastodon.media_post("3.jpg")
media4 = mastodon.media_post("4.jpg")
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.

7 thoughts on “Easy guide to building Mastodon bots

  1. Hu Man says:

    Could you write up something for WordPress to Mastadon?

  2. Nils Hitze says:

    Thx, works like a charm

  3. Tuss4 says:

    I made a docker-ized version of this. Thank you for the tutorial! https://github.com/Tuss4/mastodon-docker-bot

  4. savory says:

    easiest bot I ever made, though tumblr was pretty easy too.

Leave a Reply

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