Module 1

Bot SDK Fundamentals

Learn the fundamentals of the Towns Protocol Bot SDK and set up your development environment. Understand what the Bot SDK is, how it works, and prepare your project for building and deploying a production-ready bot.

6 steps
Beginner

Learning Objectives

By the end of this module, you will be able to:

Understand what the Bot SDK is and how it works
Initialize a bot project using the official scaffolding tool
Install dependencies and understand the generated file structure
Configure environment variables for development
Understand the basic bot code and webhook setup
Run your bot locally for testing
1

What is the Bot SDK?

Learn what the Towns Protocol Bot SDK is and how it helps you build bots.

The Towns Protocol Bot SDK (@towns-protocol/bot) is a framework that makes it easy to build interactive bots. It handles webhook communication, slash commands, and event processing so you can focus on your bot's functionality.

How It Works

Your bot runs as a web server that receives events from Towns via webhooks. When users interact with your bot (messages, commands, reactions), the SDK processes these events and provides simple handler functions to respond.

Key Features

  • • Send messages to channels
  • • Handle slash commands
  • • React to user events
  • • Secure webhook validation

Main Packages

  • • @towns-protocol/bot
  • • @towns-protocol/sdk
  • • hono (web server)
2

Initialize Your Bot

Use the official scaffolding tool to create your bot project with all necessary files.

Create Your Bot Project

Run this command to create a new bot project with the official scaffolding:

Initialize Bot Project
bunx towns-bot init my-towns-bot
cd my-towns-bot

Generated Project Structure

The init command creates a complete bot project with this structure:

my-towns-bot/
├── src/
│   ├── index.ts         # Main bot file with webhook setup
│   └── commands.ts      # Slash command definitions
├── .env.sample          # Environment variable template
├── .gitignore          # Git ignore (protects secrets)
├── package.json        # Dependencies and scripts
└── tsconfig.json       # TypeScript configuration

What You Get

  • • Bot server setup with Hono and webhook handling
  • • Example commands ready to customize
  • • TypeScript configuration optimized for bot development
  • • Build scripts for development and production
3

Install Dependencies

Install all required packages for your bot.

Install Packages

The generated project includes all necessary dependencies. Install them with:

Install Dependencies
bun install

Available Scripts

Your package.json includes these useful scripts:

bun run dev

Start development server with hot reload (watches for file changes)

bun run start

Run the production build (used by Render in Module 6)

4

Configure Environment

Set up environment variables for your bot.

Create .env File

Copy the sample environment file to create your .env:

Create .env file
cp .env.sample .env

Environment Variables

Your .env file should contain:

.env
# Bot Credentials (you'll get these in Module 6)
APP_PRIVATE_DATA=your_private_data_here
JWT_SECRET=your_jwt_secret_here

# Server Port
PORT=5123

Getting Your Credentials

You'll get your actual APP_PRIVATE_DATA and JWT_SECRET from the Towns Developer Portal in Module 6: Deployment. For now, the placeholder values are fine for local development.

5

Understanding the Bot Code

Walk through the generated bot code to understand how it works.

Generated src/index.ts

The init command created a complete bot server. Here are the key parts:

src/index.ts (generated)
import { Hono } from 'hono'
import { makeTownsBot } from '@towns-protocol/bot'
import commands from './commands.js'

// Initialize bot with credentials and commands
const bot = await makeTownsBot(
  process.env.APP_PRIVATE_DATA!,
  process.env.JWT_SECRET!,
  { commands }
)

// Start bot and get middleware
const { jwtMiddleware, handler } = bot.start()

// Create Hono app
const app = new Hono()

// Webhook endpoint - receives events from Towns
app.post('/webhook', jwtMiddleware, handler)

export default app

How It Works

1. Bot Initialization

makeTownsBot() creates your bot using credentials from .env and registers your slash commands.

2. Webhook Setup

The /webhook endpoint receives events from Towns (messages, commands, reactions). The jwtMiddleware validates requests for security.

3. HTTP Server

Hono creates a lightweight HTTP server on port 5123 (or your configured PORT).

Command Definitions src/commands.ts

The generated file includes example commands. We'll customize these in Module 2:

src/commands.ts (example)
export default [
  {
    name: 'hello',
    description: 'Say hello to the bot',
  },
  {
    name: 'help',
    description: 'Get help with bot commands',
  },
]

Module 1 Complete!

Excellent! You've initialized your bot project and installed dependencies. Your bot foundation is ready for adding commands and features in the next modules!

What You've Accomplished:

Initialized bot project with official scaffolding
Installed all required dependencies
Configured environment variables
Understood the bot code structure

Coming Up Next:

Module 2: Create custom slash commands
Module 3: Handle messages and events
Module 4: Add admin permissions
Module 5: Integrate database storage
Module 6: Deploy to Render
Continue to Module 2

Back to Course Overview

© River Eridanus Association, Switzerland, 2025

TermsPrivacy