A pretty simple random message bot using Mastodon
Go to file
Clement Bois d555d58917 v0.0.1 2019-06-17 17:06:01 +02:00
src v0.0.1 2019-06-17 17:06:01 +02:00
.env.sample v0.0.1 2019-06-17 17:06:01 +02:00
.gitignore WIP 2019-06-14 17:10:20 +02:00
README.md v0.0.1 2019-06-17 17:06:01 +02:00
package.json v0.0.1 2019-06-17 17:06:01 +02:00
tsconfig.json v0.0.1 2019-06-17 17:06:01 +02:00
tslint.json WIP 2019-06-14 17:10:20 +02:00



A pretty simple random message bot using Mastodon statuses as source of truth.

  • no database: store volatile data in statuses
  • easy edit: allows easy edit from web ui or apps.
  • community: allows public submit with strict or community driven moderation



  • Create an account for this bot. Please mark it as bot in configuration page.
  • In settings page, create a new application with read write permission and copy the private key.
    • Or read:accounts read:statuses write:statuses write:media
    • Could use npm run token-add (requires DOMAIN in .env)
  • Create a status to store actions (could be private) containing #botodon and copy its id. Called root status after
  • Create a status to store content (could be private) and copy its id. Called data status after
    • Reply to this status to add content. (Removing @acct, to limit self spam)
  • Reply to root status with options tags (See action status) like #botodon #global #data_from_{DATA_STATUS_ID}


Download folder from releases.

In .env set


Run node index.js with cron.


Main ideas

It uses statuses tags as configuration like #xxx_yyy. So content doesn't really matter except obviously for content statuses

There is 3 types of statuses:

  • The root status contains global options. See Root status
  • action status contains action to run and is descendant of root status. See Action status
  • data status is a data source like a folder containing content statuses
  • content status is a normal status its content (including medias) will send

Root status

Its a folder containing action statuses and global options as tags.

tag description
botodon Required Enable tags processing
async Enable actions parallel processing
deep Use replies to actions as actions
shared Unsafe Include other users actions
file Also load actions from actions.json

Action status

It describe an action to run


#botodon #global #data_from_xxxxxxxxxxxx

Send standard status with random content from xxxxxxxxxxxx status


tag default description
botodon false Required Enable tags processing
Data source content send
data_file empty Use database.json as source (See database.sample.json)
data_from_ID empty Add a source of content: data status id
data_deep false Use replies to content as content
data_shared false Warning Include other users content
data_tagged_TAG empty Require content to have this tag (Tags are lowercase on backend)
data_favourited false Require content to be fav by bot account
data_favourites_N false Require at least N favourites
data_last_N disabled Only include N last statuses
data_weighted false Use favourites_count as promotional random weight
data_same false Send same content for all targets
Targets target accounts
global false Send without target
followers false Send to each followers
followers_of_ID empty Send to each followers of given account id Don't be evil
replies_to_ID empty Send to each repliers of given status id
replies_deep false Include replies to replies
replies_visibility false Use reply visibility
favourites_ID empty Send to each use who fav given status id
visibility unlisted Visibility to use. One of public, unlisted, private, direct

Multiple bots

Add .env.XXX files and run BOT_NAME=XXX node index.js


Mastodon context API use an arbitrary limit of 4096 since #7564, it's so the limit were new replies are excluded.

Mastodon api limit to 300 requests within 5 minutes. Using a rate limiter at 150 requests for 5 minutes.

Followers soft limit of 999 (must include pagination) and hard limit of 7500.


It supports Mastodon API but uses case-sensitive ids which can't be stored as tag.

You have to use actions and database json files as fallback.


tools folder contains some useful script which could be as helpful as dangerous.


  • Add abstract and inherit on deep actions
  • Add actions time validators
  • Use followers pagination
  • Add options on data status
  • Add move pick options
  • Handle errors
  • Move to Go ?