Getting started

Installing Deno

NOTE

BotKit currently supports only Deno. Once BotKit is more stable, we will support Node.js and Bun.

BotKit is a TypeScript framework written in Deno. To install BotKit, you need to have Deno 2 or higher installed on your machine. There are multiple ways to install Deno, but the easiest way is to use the following command:

Linux

curl -fsSL https://deno.land/install.sh | sh

macOS

curl -fsSL https://deno.land/install.sh | sh

Windows

irm https://deno.land/install.ps1 | iex

Installing BotKit

Once you have Deno installed, you need to create a new project for your bot and install BotKit as a dependency:

mkdir my-bot/
cd my-bot/
deno add jsr:@fedify/botkit@^0.1.0-dev

Since BotKit uses the Temporal API which is still unstable in Deno, you need to turn it on in your deno.json settings:

deno.json

{
  "imports": {
    "@fedify/botkit": "jsr:@fedify/botkit@0.1.0-dev.13+d94fa9e4"
  },
  "unstable": ["temporal"]
}

Creating a bot

To create a bot, you need to create a new TypeScript file and define your Bot instance using the createBot() function:

bot.ts

import {
  createBot,
  InProcessMessageQueue,
  MemoryKvStore,
  text,
} from "@fedify/botkit";

const bot = createBot<void>({
  username: "mybot",
  name: "My Bot",
  summary: text`A bot powered by BotKit.`,
  kv: new MemoryKvStore(),
  queue: new InProcessMessageQueue(),
});

In the above code snippet, we created a new bot instance named bot with the username mybot—the first part of the fediverse handle. The bot will be addressed as @mybot@your-domain in the fediverse.

The name and summary are the display name and the bio of the bot, respectively. Note that the summary is not a string, but a Text object that can be used to format rich text. For more information on Text, see the Text chapter.

The kv is the underlying key–value store that BotKit uses to store data. In the above code snippet, we used the MemoryKvStore class, which stores data in memory for development purposes.

The queue is the message queue that BotKit uses to deal with background tasks. In the above code snippet, we used the InProcessMessageQueue class, which processes messages in the same process for development purposes.

CAUTION

Although MemoryKvStore and InProcessMessageQueue are useful for development, they must not be used in production. You should use a persistent key–value store and a message queue service in production. For more drivers available, see the Fedify's related docs:

• Key–value store
• Message queue

Handling events

BotKit supports various events such as onFollow and onMention. You can handle these events by setting the corresponding event handlers on the Bot instance.

Here, we will let the bot publish a direct message when someone follows the bot:

bot.ts

bot.onFollow = async (session, follower) => {
  await session.publish(text`Thanks for following me, ${follower}!`, {
    visibility: "direct",
  });
};

Running the bot

To run the bot, you need to first connect the bot to the HTTP server. We will utilize deno serve command. In order to connect the bot to Deno's HTTP server, you need to export the bot instance as a default export in the bot.ts file:

bot.ts

export default bot;

Then, you can run the bot using the following command:

deno serve -A ./bot.ts

Then, it will show the following message:

deno serve: Listening on http://0.0.0.0:8000/

And your bot will be available at http://localhost:8000/.

Exposing the bot to the public internet

However, other fediverse servers cannot interact with your bot if it is only available on your local machine. To expose your bot to the public internet, you can use a tunneling service like fedify tunnel, ngrok, Tailscale Funnel, etc.

Since those tunneling services practically act as an L7 reverse proxy, you need to turn on the behindProxy option:

bot.ts

const bot = createBot<void>({
  username: "mybot",
  name: "My Bot",
  summary: text`A bot powered by BotKit.`,
  kv: new MemoryKvStore(),
  queue: new InProcessMessageQueue(),
  behindProxy: true,  
});

Here, we will use fedify tunnel to expose the bot to the public internet. Install the fedify command first, and then run the following command:

fedify tunnel --port 8000

The above command will expose your bot to the public internet, and you will get a temporary public hostname that your bot can be accessed from the fediverse:^[1]

✔ Your local server at 8000 is now publicly accessible:

https://c4d3933be87bc2.lhr.life/

Press ^C to close the tunnel.

Testing the bot

To test the bot, you can use ActivityPub.Academy, a development-purpose Mastodon instance. ActivityPub.Academy allows you to immediately create an ephemeral fediverse account and provides several tools to debug your ActivityPub application such as Activity Log.

Okay, let's create a new account on ActivityPub.Academy and follow your bot account: @mybot@c4d3933be87bc2.lhr.life—replace c4d3933be87bc2.lhr.life with the domain name assigned by the fedify tunnel command.

Here's how you can follow your bot account—in ActivityPub.Academy's search bar, type @mybot@c4d3933be87bc2.lhr.life and click the account:

Then, click the Follow button:

Few seconds later, you will receive a direct message from your bot:

---

1. The hostname will be different in your case. ↩︎