Listening to Events

In many cases, you’ll want your bot to respond to user interactions such as replies and mentions. The Bot class is preconfigured to emit events whenever the bot account receives a like, mention, follow, reply, repost, or quote post. You can listen to these events by calling the on method on your bot instance.

const bot: Botbot.Bot.on(event: "reply", listener: (post: Post) => void): Bot (+8 overloads)Emitted when the bot receives a reply.
@sincev0.1.101@parameventName The name of the event.@paramlistener The callback functionon("reply", async (reply: Postreply) => {
	await reply: Postreply.PostReference.like(): Promise<StrongRef>Like the post.like();
	await reply: Postreply.PostReference.reply(payload: PostPayload, options?: BotPostOptions | undefined): Promise<PostReference>Reply to the post.
@parampayload The post payload.@paramoptions Optional configuration.@returnsA reference to the created post.reply({ PostPayload.text: string | RichTextThe post text. Can be a string or a RichText instance containing facets.text: "Thanks for the reply!" });
})

In this example, the bot listens for replies and responds by liking the reply and replying with a message. The full list of events you can listen to are:

like: Emitted when the bot receives a like.
mention: Emitted when the bot is mentioned.
follow: Emitted when the bot is followed.
reply: Emitted when the bot receives a reply.
repost: Emitted when the bot receives a repost.
quote: Emitted when one of the bot’s posts is quoted.

The documentation for the Bot#on method provides more information on the data you can receive for each event.

Configuration

The bot uses a polling mechanism to listen for events. This means that the bot will periodically check for new events via the same endpoint used by client applications to receive notifications. You can configure the polling interval by passing an eventEmitterOptions object to the Bot constructor.

const const bot: Botbot = new new Bot({ service, langs, emitEvents, rateLimitOptions, cacheOptions, eventEmitterOptions, }?: BotOptions | undefined): BotCreate a new bot.
@paramoptions Configuration options.Bot({
    BotOptions.eventEmitterOptions?: BotEventEmitterOptions | undefinedOptions for the event emitter.eventEmitterOptions: {
        BotEventEmitterOptions.pollingInterval?: number | undefinedThe interval in seconds at which the bot will poll the notifications endpoint. Only used if strategy is EventStrategy.Polling.
@default5pollingInterval: 10 // Poll every 10 seconds
    }
});

By default, the bot will poll every 5 seconds. Keep in mind that the total rate limit available to an account, as of writing, is 3000 requests per 5 minutes. Polling for notifications uses 60 requests per 5 minutes under the default interval. If you expect to receive a high volume of events or will be doing several actions for each event, you may want to increase the polling interval to avoid hitting the rate limit.

The eventEmitterOptions object also takes a processFrom Date object, allowing you to ignore notifications that occurred before a certain time. This can be useful if you want to avoid processing old notifications when your bot starts up.

Firehose

If real-time updates are important to your bot, you can configure your Bot instance to listen for events directly via a WebSocket connection to the Relay.

Be aware that this will mean maintaining an open WebSocket connection that will receive all events occurring on the Bluesky network. This can be resource-intensive compared to polling.

To begin, you will need to install the @skyware/firehose package:

npm install @skyware/firehose

Then, you’ll need to set the strategy option accordingly:

import { class BotA bot that can interact with the Bluesky API.Bot, type EventStrategy = string
const EventStrategy: {
    Polling: string;
    Firehose: string;
}How the bot will receive and emit events.
@enumEventStrategy } from "@skyware/bot";
const const bot: Botbot = new new Bot({ service, langs, emitEvents, rateLimitOptions, cacheOptions, eventEmitterOptions, }?: BotOptions | undefined): BotCreate a new bot.
@paramoptions Configuration options.Bot({
    BotOptions.eventEmitterOptions?: BotEventEmitterOptions | undefinedOptions for the event emitter.eventEmitterOptions: {
        BotEventEmitterOptions.strategy?: string | undefinedHow the bot will receive and emit events.
@defaultEventStrategy.Pollingstrategy: const EventStrategy: {
    Polling: string;
    Firehose: string;
}How the bot will receive and emit events.
@enumEventStrategy.type Firehose: stringThe bot will open a websocket connection to the relay and receive events in real-time.
This will consume more bandwidth and CPU than the polling strategy, but the bot will receive
events as soon as they are emitted.Firehose
    }
});

Alongside the strategy option, you can optionally pass a firehoseOptions object within eventEmitterOptions, which will allow you to set a cursor to resume from a specific point in the event stream.

After the initial setup, use of the Bot#on method remains the same.

Shutting Down

When you’re done listening for events, you can call the Bot#off method to remove an event listener, or the Bot#removeAllListeners method to stop listening for events entirely. It is recommended to shut down the bot gracefully using these methods, especially if you are using the firehose strategy.

Next Steps

Now that you know how to listen for events, you can start building interactivity into your bot. Continue to the next guide to learn how to parse user commands and respond to them.