BotKit by Fedify

Appearance

Events ​

BotKit provides a way to handle events that are emitted from the fediverse. You can handle events by setting event handlers on the bot instance. Event handlers are properties of the Bot instance with the on prefix followed by the event name. For example, to handle a mention event, you can set the onMention property of the bot instance:

typescript
bot.onMention = async (session, message) => {
  await message.reply(text`Hi, ${message.actor}!`);
};

Every event handler receives a session object as the first argument, and the event-specific object as the second argument.

The following is a list of events that BotKit supports:

Follow ​

The onFollow event handler is called when someone follows your bot. It receives an Actor object, which represents the follower, as the second argument.

The following is an example of a follow event handler that sends a direct message to new followers:

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

Unfollow ​

The onUnfollow event handler is called when some follower unfollows your bot. It receives an Actor object, who just unfollowed your bot, as the second argument.

The following is an example of an unfollow event handler that sends a direct message when someone unfollows your bot:

typescript
bot.onUnfollow = async (session, follower) => {
  await session.publish(text`Goodbye, ${follower}!`, {
    visibility: "direct",
  });
};

Mention ​

The onMention event handler is called when someone mentions your bot. It receives a Message object, which represents the message that mentions your bot, as the second argument.

The following is an example of a mention event handler that replies to a message that mentions your bot:

typescript
bot.onMention = async (session, message) => {
  await message.reply(text`You called me, ${message.actor}?`);
};

Reply ​

The onReply event handler is called when someone replies to your bot's message. It receives a Message object, which represents the reply message, as the second argument.

The following is an example of a reply event handler that sends a second reply message when someone replies to your bot's message:

typescript
bot.onReply = async (session, reply) => {
  await reply.reply(text`Thanks for your reply, ${reply.actor}!`);
};

If you want to get the parent message of a reply message, you can use the replyTarget property. See also the Traversing the conversation section in the Message concept document.

CAUTION

In many ActivityPub implementations including Mastodon, reply messages often contain the mention of the original author. In such cases, both onMention and onReply event handlers are called. You should be careful not to perform unexpected actions.

The below example shows how to avoid the on-mention event handler from being called when a reply message is received:

typescript
bot.onReply = async (session, reply) => {
  await reply.reply(text`Thanks for your reply, ${reply.actor}!`);
};

bot.onMention = async (session, message) => {
  if (message.replyTarget == null) {  
    await message.reply(text`You called me, ${message.actor}?`);
  }
};

Or the other way around, you can avoid the on-reply event handler from being called when a reply message mentioning the bot is received:

typescript
bot.onMention = async (session, message) => {
  await message.reply(text`You called me, ${message.actor}?`);
};

bot.onReply = async (session, reply) => {
  if (!reply.mentions.some(m => m.href.href === session.actorId.href)) {
    await reply.reply(text`Thanks for your reply, ${reply.actor}!`);
  }
};