DEV Community: Stefan Bohacek

Making a trivia quiz chatbot on Mastodon

Stefan Bohacek — Mon, 06 Mar 2023 13:36:45 +0000

TLDR: Here's the finished code | Get in touch if you get stuck

I made the original @what_capital bot, which lets you play a trivia game where you identify capitals based on a country's flag, about seven years ago, for a tutorial that you'd no longer be able to follow. For one, the web-based IDE I used was sold to Amazon, and I'm not sure you can easily use it for free. Second, the hosting service I used seem to no longer offer a free plan. And finally, Twitter, whose API I used, is in disarray.

Yes, seven years is a really long time on the web.

But as some technologies and platforms disappear, new ones arise. And one that I am particularly excited about is the fediverse. It's an open standard for making a better social web with roots going back to 2008. And the way many folks are being introduced to it is via the rise of Mastodon, both a social media site, and software to make your own version, that's built on this standard.

And a fun way to explore the fediverse is using Mastodon's API to re-create my bot.

And for that, I am going to use my Creative Bots project. You have a few options how to host it, but for this tutorial I am going to go with Glitch for its ease of use. Note that you don't need an account to follow along, but you will need a paid plan to keep your bot running after we're done.

First, you will need to set up an account for your bot. Any Mastodon instance will do. Note that the popular botsin.space instance has a manual review process in place, so you might have to wait a bit if you decide to go with that one.

Once we have our account ready, let's make a remix of the Creative Bots Glitch app.

Next, we'll update our .env file (see the sidebar on the left) and add the following variables.

WHAT_CAPITAL_BOT_MASTODON_API_URL="https://botsin.space/api/v1/"
WHAT_CAPITAL_BOT_MASTODON_ACCESS_TOKEN="123456789-abcd"

Replace botsin.space with the name of your bot's instance, if you're not using that one. For example, if your bot is on mastodon.social, you will use:

WHAT_CAPITAL_BOT_MASTODON_API_URL="https://mastodon.social/api/v1/"
WHAT_CAPITAL_BOT_MASTODON_ACCESS_TOKEN="123456789-abcd"

So far, so good.

Now, back in the sidebar, open bots/reply-mastodon.js. This is a simple example of a bot that replies to messages sent to it, and we will expand on it to make our bot.

But before we write any code, we will need to prepare some data. Using the sidebar again, add a file called data/capitals.js.

You can get the contents from the finished project here.

Note that the JSON object with answers also contains description of each flag. More on that in a bit.

Now, let's update your bot's code to use the correct access token and API URL.

const mastodon = new mastodonClient({
   access_token: process.env.WHAT_CAPITAL_BOT_MASTODON_ACCESS_TOKEN,
   api_url: process.env.WHAT_CAPITAL_BOT_MASTODON_API_URL
});

At this point, you can already try speaking with your bot. Go ahead and say hello!

After you have a bit of fun with your new bot, let's get back to writing some more code. All that's next will come before the module.exports section.

Here's the finished code again so that you can check your progress.

To start, we will need to load our capitals.js file, so let's do just that.

const fs = require("fs"),
      helpers = require(__dirname + "/../helpers/helpers.js"),
      capitals = require(__dirname + "/../data/capitals.js"),
      mastodonClient = require(__dirname + "/../helpers/mastodon.js");

Note that I also added the fs module. This will be useful to keep track of a leaderboard, to make the game a bit competitive.

Note that the .data folder, which we will use, is a built-in way for Glitch to store data for your app.

const savedDataPath = __dirname + "/../.data/what_capital.json";

let savedData = {
  country: "",
  capital: "",
  scores: {},
};

if (fs.existsSync(savedDataPath)) {
  savedData = JSON.parse(fs.readFileSync(savedDataPath, "utf8"));
}

const saveData = () => {
  fs.writeFileSync(savedDataPath, JSON.stringify(savedData, null, 2), "utf8");
};

const updateScores = (user) => {
  if (savedData.scores.hasOwnProperty(user)) {
    savedData.scores[user] = savedData.scores[user] + 1;
  } else {
    savedData.scores[user] = 1;
  }
  saveData();
};

Great. Now we'll need a pair of functions that will handle picking a new question and verifying the answer.

const pickNewCapital = () => {
  const capital = helpers.randomFromArray(capitals);
  const flagUrl = `https://static.stefanbohacek.dev/images/flags/${capital.country.replace(
    / /g,
    "_"
  )}.png`;

  savedData.capital = capital.capital;
  savedData.country = capital.country;
  saveData();

  helpers.loadImage(flagUrl, (err, imgData) => {
    if (err) {
      console.log(err);
    } else {
      let altText = capital.flag_description;

      if (capital.flag_description.length > 1000) {
        altText = capital.flag_description.slice(0, 2) + "...";
      }

      mastodon.postImage({
        status: "What is the capital of this country?",
        image: imgData,
        alt_text: `An unspecified country flag: ${altText}`,
      });
    }
  });
};

const checkAnswer = (answer) => {
  answer = answer
    .trim()
    .toLowerCase()
    .normalize("NFD")
    .replace(/\p{Diacritic}/gu, "");
  const correctAnswer = savedData.capital
    .toLowerCase()
    .normalize("NFD")
    .replace(/\p{Diacritic}/gu, "");
  return answer.includes(correctAnswer);
};

This is the really tricky part. People will likely include words that are not part of the answer in their message, like "Hmm", or "I think...". And some city names may contain special characters. To make a bot that's fun to interact with, we need to account for all the possible ways people will talk to it.

We could actually go a step further here, and use an array with acceptable variations of each city's name, maybe even the translation in its native language. There's an idea for a future update.

And going back to the code above, you will notice that I am using the flag description as an alt text for the image. This way your bot can be enjoyed by everyone.

let altText = capital.flag_description;

Now we're ready to bring this all together inside the reply function of our bot object.

let reply = "";

if (
  fullMessage.data.status.visibility === "public" ||
  fullMessage.data.status.visibility === "unlisted"
) {
  if (checkAnswer(messageText)) {
    updateScores(from);
    reply = `Yes, ${savedData.capital} is the capital of ${
      savedData.country
    }, correct! ${getLeaderboard()}`;
    pickNewCapital();
  } else {
    reply = "That doesn't seem correct, sorry! Or perhaps a new flag was posted?";
  }
} else {
  reply = "Sorry, do you mind responding publicly?";
}

mastodon.reply(fullMessage, reply);

And there you have it, your very own interactive game bot, running on the open web.

Feel free to browse more examples of bots I've made using my starter project, and you can find even more resources for creative botmakers over at botwiki.org, and join the botmakers.org Slack group.

I hope you find this tutorial fun. If you have any questions or suggestions, feel free to reach out.

Until next time!

Introduction to Mastodon bots

Stefan Bohacek — Fri, 07 Sep 2018 12:55:40 +0000

2022 UPDATE: Glitch no longer allows a method that’s been used to keep bots running on their free plan. While I work on an updated version of this tutorial, here are some useful resources to check out:

my general guide to making creative bots which also has a few Mastodon-specific tips
my Creative Bots starter project that lets you make bots for Mastodon, Twitter, and Tumblr
the Coding Train’s Mastodon bot video tutorial series
open-source bots on Botwiki

And as a bonus, here’s my 2018 interview with the creator of botsin.space, a Mastodon instance dedicated to bots. Be sure to also follow Botwiki-related Mastodon accounts:

And you can find me at @stefan@stefanbohacek.online.

It's been a few weeks since the big exodus of creative botmakers from Twitter, mainly due to the recent changes to the platform (and, well, other reasons). Some of them gave up on making art bots altogether, but many tried to find a new home for their bots. And some of them ended up on Mastodon.

If you haven't heard about Mastodon before, it's a social networking software that lets anyone host their own social network site. (There are similar projects, for example GNU social). All of these sites can be connected in what is known as the fediverse. (You can head to Wikipedia for a more detailed description.)

Mastodon has a very easy to use API, so it's a great replacement for Twitter if you'd like to experiment with generative art, natural language processing, or make a useful tool that posts updates on weather, or bills being passed by your government. As a bonus, you can easily get an RSS feed of your bot's posts.

Making your first Mastodon bot

Setting up a new account for your bot is a breeze. First, you need to choose which Mastodon instance you want your bot to be on. I recommend botsin.space, which was created specifically to run friendly bots.

After you confirm your email, click the “Edit profile” link under your username and check off “This is a bot account”.

After this, go to the Preferences page (the “cog” icon) and then click Development.

Now click the New Application button. Name your application, keep the settings the way they are, and click the Submit button at the bottom of the page.

Now you can click your application’s name to reveal the access token for your bot. If you only see your API key, use this tool to generate your token.

And you’re done. Now for the fun part. For this tutorial I'm going to use my generative-art-bot starter project on Glitch. You don't need to sign up for an account right now, Glitch lets you create temporary projects for you to test things out.

First, click the Remix button.

Next, update your .env file with your access token. For MASTODON_API you can use https://botsin.space/api/v1/. Also update the value of BOT_ENDPOINT. This can be anything, for example 12345. You will then be able to use the URL of your project together with the endpoint with a site like cron-job.org to wake up your bot and do something. (I'll explain this part later in this tutorial.)

The Glitch project is structured so that the code for your bot goes inside bot.js. Here we load one of the generators (see the generators folder) that will produce our image, and then we can either share it on Mastodon, or Twitter, or both.

For this tutorial, let's try the triangular mesh generator.

Delete the content of your bot.js file so that we have a fresh start and add this:

const helpers = require(__dirname + '/helpers.js'),
      generators = {
        triangular_mesh: require(__dirname + '/generators/triangular-mesh.js'),
      },
      mastodon = require(__dirname + '/bot/fediverse/mastodon.js');

helpers is a module that has a few helper functions, for example random_from_array, which will let us change up the text of the bot's status message every time it posts. And color-scheme is a library that lets you generate color palettes, which we can use for our artwork.

And this is what connects the bot.js file with the main app that powers our bot:

module.exports = () => {

}

The code inside this exported function is what runs when you visit your bot's endpoint URL.

First, let's set up messages for our bot to pick from when it posts:

const helpers = require(__dirname + '/helpers.js'),
      generators = {
        triangular_mesh: require(__dirname + '/generators/triangular-mesh.js'),
      },
      mastodon = require(__dirname + '/bot/fediverse/mastodon.js');

module.exports = () => {
  const status_text = helpers.random_from_array([
    'Check this out!',
    'New picture!',
    'Just look at that!'
  ]);
}

Next, we're going to need some colors. I'm going to go with the petals color scheme from colourlovers.com. And I'm going to have the bot post images with the size of 1200x500px.

const helpers = require(__dirname + '/helpers.js'),
    generators = {
      triangular_mesh: require(__dirname + '/generators/triangular-mesh.js'),
    },
    mastodon = require(__dirname + '/bot/fediverse/mastodon.js');

module.exports = () => {

  const status_text = helpers.random_from_array([
      'Check this out!',
      'New picture!',
      'Just look at that!'
    ]);
  }

  const options = {
    width: 1200,
    height: 500,
    colors: ['571014', 'D4292F', 'FC5978', 'FE7B35', 'FBAC00']
  };

Now, let's generate a random triangular mesh using our settings.

const helpers = require(__dirname + '/helpers.js'),
      generators = {
        triangular_mesh: require(__dirname + '/generators/triangular-mesh.js'),
      },
      mastodon = require(__dirname + '/bot/fediverse/mastodon.js');

module.exports = () => {

  const status_text = helpers.random_from_array([
    'Check this out!',
    'New picture!',
    'Just look at that!'
  ]);

  const options = {
    width: 1200,
    height: 500,
    colors: ['571014', 'D4292F', 'FC5978', 'FE7B35', 'FBAC00']
  };

  generators.triangular_mesh(options, (err, image) => {


  });

}

And now we're ready to share our art.

const helpers = require(__dirname + '/helpers.js'),
      generators = {
        triangular_mesh: require(__dirname + '/generators/triangular-mesh.js'),
      },
      mastodon = require(__dirname + '/bot/fediverse/mastodon.js');

module.exports = () => {

  const status_text = helpers.random_from_array([
    'Check this out!',
    'New picture!',
    'Just look at that!'
  ]);

  const options = {
    width: 1200,
    height: 500,
    colors: ['571014', 'D4292F', 'FC5978', 'FE7B35', 'FBAC00']
  };

  generators.triangular_mesh(options, (err, image) => {
    mastodon.post_image(status_text, image.path, (err, data) => {


    });
  });

}

As a final touch, let's log whether the bot did in fact post the image, and an error message if it didn't so that we can debug the problem.

This is what your bot.js file should look like:

const helpers = require(__dirname + '/helpers.js'),
      generators = {
        triangular_mesh: require(__dirname + '/generators/triangular-mesh.js'),
      },
      mastodon = require(__dirname + '/bot/fediverse/mastodon.js');

module.exports = () => {

  const status_text = helpers.random_from_array([
    'Check this out!',
    'New picture!',
    'Just look at that!'
  ]);

  const options = {
    width: 1200,
    height: 500,
    colors: ['571014', 'D4292F', 'FC5978', 'FE7B35', 'FBAC00']
  };

  generators.triangular_mesh(options, (err, image) => {
    mastodon.post_image(status_text, image.path, (err, data) => {
      if (err){
        console.log('oh no...', err)
      } else {
        console.log('image was posted!');
        console.log(data.url);
      }
    });
  });

}

Perfect.

Before we generate our first artwork, let's pull up the log, so we can see what the bot is doing. You can open the Activity Log using the Log button under your project icon.

And now you can go to the endpoint URL of your bot (you can click the "Show" button on top of the page to see the URL of your project, and then add /BOT_ENDPOINT at the end, just like in the example I used earlier:

https://generative-art-bot.glitch.me/12345

Open this URL in a new browser tab or window -- and you will see this in your Activity Log back in the Glitch editor:

You can copy the URL from the log to see your bot's post:

Every time you visit the endpoint URL a new image will be generated. (I will explain later in this tutorial how to do this automatically.)

Now, time to experiment a little bit.

Let's look at what's actually inside generators/triangular-mesh.js and maybe poke around, to see if we can make the bot's output more fun and interesting.

When you open the file, you will see a link to the tutorial that inspired this generator. We see how the options are being set up. (I'll get to the animate option in a little bit.)

The generator uses something called canvas to make your image, which is an HTML element designed just for that. We can see a function called drawTriangle, which, we might correctly assume draws the triangles. It looks pretty straightforward, let's change it up a bit. How about adding a smaller triangle inside the triangle?

  const drawTriangle = (pointA, pointB, pointC) => {
    ctx.beginPath();
    ctx.moveTo(pointA.x, pointA.y);
    ctx.lineTo(pointB.x, pointB.y);
    ctx.lineTo(pointC.x, pointC.y);
    ctx.lineTo(pointA.x, pointA.y);
    ctx.closePath();
    ctx.fillStyle = '#' + helpers.random_from_array(options.colors); 
    ctx.fill();
    ctx.stroke();

    /* Adding new code for a smaller triangle.*/

    ctx.beginPath();
    ctx.moveTo(pointA.x + 10, pointA.y - 10);
    ctx.lineTo(pointB.x - 10, pointB.y - 10);
    ctx.lineTo(pointC.x - 10, pointC.y + 10);
    ctx.lineTo(pointA.x + 10, pointA.y - 10);
    ctx.closePath();
    ctx.fillStyle = '#' + helpers.random_from_array(options.colors); 
    ctx.fill();
    ctx.stroke();

  }

There is a little bit of math involved, as with all good art, but all I'm doing is moving the points closer to the center. Let's go back to our bot's endpoint URL and see what this does.

Alright, this is not exactly what I had in mind, I calculated the points of the inner triangle wrong. But it actually looks good! And this is cool about generative art, sometimes "mistakes" can make for a more interesting output.

Feel free to play some more with this generator, or check out the other examples, or even create your own generator. What's that? Oh, you're still wondering about the animate option?

Alright, let's go back to bot.js and add this to our options object:

  const options = {
    width: 100,
    height: 100,
    colors: ['571014', 'D4292F', 'FC5978', 'FE7B35', 'FBAC00'],
    animate: true
  };

(Make sure to add a comma after colors.)

For the sake of speeding things up, I also changed the size of the image.

Back to our bot's endpoint--

This particular generator produces GIFs that are too large for Mastodon's 8MB file size limit, so the quality is a little too low, but you could experiment with the encoder settings and maybe find a way to improve this.

Automating your bot

The final step in this tutorial will be automating our bot. Glitch puts inactive apps (that is, apps that don't get any outside traffic) to sleep after 5 minutes, so you will have to either periodically refresh your bot's endpoint URL all day, or, a much more convenient solution, use a site like cron-job.org or uptimerobot.com to do that for you.

I'm going to use cron-job.org to show you how to set this up.

Once you sign up for an account, head to the "Cronjobs" section and add a new cronjob.

Click "User defined" under "Schedule". Here, select all the options under Days of months, Days of week, Months. Under Minutes, select 0. And under Hour, select on which hour your bot will post.

For example, if you want to post every 6 hours, select the options 0, 6, 12, and 18.

Hit the "Create cronjob" button at the bottom of the page, and you're all set!

If you want to keep your bot running permanently, you will need to sign up for a Glitch account, which I would highly recommend even for other projects, not just bots.

If you get stuck at any point during this tutorial, feel free to join the Botmakers group and someone will be happy to help you out.

Thanks for following along, and have fun making generative art bots!