So you want to make a fediverse bot?

Principles for well-behaved ActivityPub bots

18 November 2023

Every so often, somebody makes a bot account in the fediverse, expects people to love it, and is then surprised when people get mad. If you are thinking of writing or hosting a bot account on Mastodon, Pleroma or other fediverse software, here are some tips that will make it less likely that a server admin will ban your bot and yell at you.

1. Identify your bot as a bot

On Mastodon and some other fediverse platforms it is possible to identify an account as a bot. On Mastodon you can do this in the settings at If this is possible on the platform your bot is using, you should do so. If you are building your own ActivityPub software, consider providing a type value of bot or Application in the actor's ActivityPub JSON profile. Mastodon software recognises "bot" as the relevant type value, whilst the activitystreams-vocabulary suggests "Application" is probably more appropriate since "bot" is not mentioned. This is, however, a contested point amongst ActivityPub developers depending on how "software application" is defined.

2. Publish statuses with privacy "unlisted", "followers", or "direct"

Some people will love your bot! Other people will ...not. It's also important to understand that fediverse servers come in all sorts of flavours and sizes. is huge, with tens of thousands of daily users. But there are also many, many fediverse servers with only a dozen or a few hundred users in total. The timeline moves a lot slower on these sites. To avoid spamming the timeline of lower-traffic and smaller servers, you should avoid publishing statuses as public. If you want your bot's posts to be available to everyone, use unlisted instead. If posts are only relevant to followers, use followers, and if only relevant to a particular user, consider direct.

3. Restrict the publication schedule of "announcing"-style bots to a maximum of three times per 24 hours

Unless there is a specific, genuine reason for posting on a particular more-frequent schedule (e.g. Big Ben bot posting on the hour), bots should be restricted to a maximum of three posts a day. This avoids filling up smaller servers with a large stream of content from the same bot. As noted above, ActivityPub servers tend to be significantly smaller with "slower" feeds than the large commercial social networks – your bot should take this into account.

4. Do not interact with other actors unless they have actively consented

This is also known as "opt-in". Bots that interact with other actors – for example by @mentioning a user – must only do so if the other actor has actively consented to interaction.

"Interaction" includes following, mentioning, boosting, liking, etc.

"Active consent" means that the actor (or someone controlling the actor in the case of other bots) has taken some kind of autonomous action to explicitly provide permission for interaction with your bot. Examples include:

  • following your bot account
  • posting a specified code word in a direct message to your bot, e.g. "START" or "ALLOW"
  • @mentioning your bot account using a specified word or phrasing e.g. "Hey"

5. Do not use a bot or automated account to circumvent server privacy and security settings, or harvest fediverse messages

Yes, you are very clever. But ask yourself - why am I building a database of messages not intended for me? "Federation" accounts intended to "connect my server to the fediverse" are routinely blocked by admins as they serve no purpose other than leaking out messages to servers that don't need them. Just stop.

6. Provide clear information about your bot and contact information for the owner

You should provide clear information about how your bot works either in the profile of the bot or at a page linked from the bot's profile, or preferably both where possile. This should include information on how to contact you as the owner/administrator of the bot, as well as how to "unsubscribe" and otherwise interact with the bot.

7. Make a plan for shutting down your bot

Other people won't notice this when your bot appears, but it's a good idea to plan at the beginning what you will do when you are no longer willing or able to run your bot. Stuff happens: you get a new job, lose an old one, have a baby, decide the joke isn't funny any more, lose access to the API you needed, or whatever. If you have built a bot that shares knock-knock jokes, it probably won't matter if it simply stops telling them one day. If you build a bot that publishes real-time information about local extreme weather events ...well, that's a different story. If your bot was working last summer and nobody knows it's been turned off, that could have serious consequences. Building a bot can be "just for Christmas" - that's totally ok, we don't all have to be so serious all the time! - but if you're building something somebody else might end up relying on, you need to have a plan to clearly communicate when it comes to the end of its life.

If you need a working example, take a look at my auspol clippy bot.