@towns-protocol/bot

@towns-protocol/bot

A bot framework for Towns.

Usage

import { makeTownsBot } from "@towns-protocol/bot";
import { serve } from "@hono/node-server";

const bot = await makeTownsBot("<app-private-data-base64>", "<jwt-secret>");

bot.onMessage((client, { channelId, isMentioned }) => {
  if (isMentioned) {
    client.sendMessage(channelId, "Hello, world!");
  }
});

const { fetch } = await bot.start();
serve({ fetch });

Running Bots

The @towns-protocol/bot package is compatible with the following approaches:

• Bun ESM - Bun runtime with ES modules
• esbuild + Node CJS - Bundled CommonJS for Node.js
• tsx ESM - TypeScript execution with ES modules

For working examples and configurations, see the examples directory.

tsx with ESM

Install tsx, then run your bot with:

tsx src/index.ts

Bundled with esbuild as CommonJS

Install esbuild, then bundle your bot to a single CJS file and run with Node.js:

You can take a look at the bot-quickstart example for a working esbuild configuration.

# Build the bundle
yarn build

# Run with Node.js
node dist/bot.cjs

Bun with ESM

bun run src/index.ts

Debug Logging

Bot framework uses debug package for logging. You can enable by setting the DEBUG environment variable to csb:bot.

DEBUG=csb:bot node dist/bot.cjs