Zero to Bot in 30 Minutes

Vibe‑Code Your
Towns Bot

Build production‑ready bots using AI assistance. No coding experience required—just follow the steps, paste the code, and deploy to the world.

30
Minutes to Deploy
0
Coding Experience
∞
Possibilities

Your Journey to Bot Mastery

Follow these 7 simple steps to build and deploy your first Towns bot

1

Get the Bot Starter Template

Clone the starter template with AI or manually

2 min
Easy
2

Prime Cursor AI

Load knowledge base files into Cursor

2 min
Easy
3

Customize with AI

Add features using AI assistance

∞
Fun
4

Create Bot Account

Register bot in Towns Developer Portal

3 min
Easy
5

Push to GitHub & Deploy to Render

Push your code to GitHub and deploy it live

8 min
Medium
6

Configure Webhook in Towns

Connect your deployed bot to Towns Protocol

2 min
Easy
7

Install Bot

Install your bot in a Towns space and verify it works

3 min
Easy

Step 1: Get the Bot Starter Template

Choose your preferred method to get started - both work perfectly!

Option A: Pure Vibe Coding ✨

EASIEST

Let AI clone it for you - Zero effort!

Just copy this prompt and paste into Cursor/Codex AI:

🎨 Vibe Coding Prompt
Run this install command for me:
bunx towns-bot init my-towns-bot

Please:
1. if bun isn't installed, install it using instructions here: https://bun.sh/docs/installation
2. follow the instructions to install dependences
3. Confirm when it's ready

Let me know if you need any permissions or have questions!

🎯 True vibe coding: AI handles git, install, everything. You just approve when it asks!

Option B: Terminal

For developers who prefer CLI

Run these commands in your terminal:

Terminal
bunx towns-bot init my-towns-bot
Terminal
cd my-towns-bot
Terminal
bun install

Then open the folder in Cursor: File → Open Folder → select `my-towns-bot`

Step 2: Prime Cursor AI

Ask Cursor to read the project rules and docs so it follows them automatically.

Send this once per session

Open the Cursor chat (Cmd/Ctrl + K), paste the prompt below, and press Enter. Cursor will read the files that already live in the repo—no copying required.

Perfect AI Setup Prompt
You are my Towns Protocol bot partner. Before changing any code, READ (don't summarize) these files in this workspace:

- .cursorrules
- README.md
- AGENTS.md
- src/index.ts
- src/commands.ts

Confirm when you've loaded them and let me know you're ready.
What Cursor just learned:

Those files contain Bot SDK knowledge and best practices:

  • • .cursorrules - AI coding rules (what's allowed, what to avoid)
  • • AGENTS.md - AI agent patterns and architecture
  • • README.md - Deployment workflow and troubleshooting
Now you're ready to customize!

With all that knowledge loaded, simply ask Cursor to add features in plain English:

  • • "Add a response when users say 'wagmi'"
  • • "Create a verification system with ✅ reactions"
  • • "Build a points system with leaderboard command"
  • • "Add moderation for bad words"

Cursor will use the knowledge base to write correct, production-ready code!

Step 3: Customize with AI

Add features before deploying your bot

Perfect time to customize!

Your bot template is ready! Now use the AI prompts from Step 2 to add any features you want BEFORE deploying. This way you deploy once with everything you need.

Popular Features to Add:

  • • Custom word responses (WAGMI, moon, etc.)
  • • User points and leaderboards
  • • Welcome verification system
  • • Joke and fun commands
  • • Moderation and spam protection

Advanced Features:

  • • Database integration for user data
  • • Reaction-based interactions
  • • Thread conversation handling
  • • Admin-only commands
  • • Integration with external APIs
When you're done customizing:

Save your changes in Cursor, then move to Step 4 to create your bot account and deploy your fully customized bot to production!

Step 4: Create Bot Account

Register your bot in the Towns Developer Portal

What you'll get

Two critical credentials that connect your bot to the Towns Protocol network. Keep these safe - they're like your bot's passport!

  1. 1

    Go to app.towns.com/developer

    Complete bot details and click "Create Bot"

  2. !

    Save your credentials

    APP_PRIVATE_DATA

    Your bot's private key and encryption device.

    JWT_SECRET

    Used to verify webhook requests from Towns servers

    Do not share these with anyone. They are very sensitive and can be used to impersonate your bot.

Step 5: Push to GitHub & Deploy to Render

Push your code to GitHub and deploy it live

Prerequisites

You need a GitHub account and Render account (both free). Create them if you haven't already.

Part A: Push to GitHub

Use AI to help with Git!

Ask Cursor to help you push to GitHub. Copy this prompt:

AI Prompt
Help me push my Towns bot to GitHub. I need to:
1. Initialize git in this project
2. Create a new repository on GitHub
3. Push all my code to GitHub

Guide me through each step.

The AI will guide you through creating a GitHub repository and pushing your code. Follow its instructions!

Part B: Deploy on Render

  1. 1

    Go to render.com

    Create a Render account and connect it with your GitHub

  2. 2

    Create a new Web Service

    Click "New" → "Web Service" and connect your GitHub repository

  3. 3

    Configure deployment settings:

    Name: my-bot

    Environment: Node

    Build Command: bun install

    Start Command: bun run start

  4. 4

    Add environment variables (click "Advanced"):

    APP_PRIVATE_DATA = Your saved credential

    JWT_SECRET = Your saved credential

  5. 5

    Click "Create Web Service" and wait for deployment

Note: After deployment, you'll get a URL like https://my-bot.onrender.com. Save this URL - you'll need it in the next step!

Free tier note: Free Render services may experience 30-60 second delays after inactivity while the service spins up.

Step 6: Configure Webhook in Towns

Connect your deployed bot to Towns Protocol

What's a webhook?

A webhook tells Towns where to send messages so your bot can respond. It's like giving Towns your bot's phone number!

  1. 1

    Go to Towns Developer Portal

    Find your bot and click "Edit"

  2. 2

    Enter your webhook URL:

    https://my-bot.onrender.com/webhook

    Important: Add /webhook to the end of your Render URL!

  3. 3

    Configure message forwarding preferences:

    All Messages

    Bot receives all messages

    Mentions, Replies, Reactions, Slash Commands

    Recommended. Bot only receives messages when directly mentioned or replied to.

    No Messages

    Bot only receives status checks (not recommended for interactive bots)

  4. 4

    Click "Save Changes" to activate your bot

Step 7: Install Bot

Install your bot in a Towns space and verify it works

The moment of truth!

Time to see your bot come alive in Towns. If everything worked, your bot will respond to messages!

Install Your Bot

  1. 1

    Go to your space in Towns app

    Navigate to Space Settings → Bots

  2. 2

    Install your bot to the space

    Find your bot and click install. Choose which channels it can access.

Test Your Bot

Go to a channel where your bot is installed and mention it:

@mybot hello

Expected response:

Hello there! 👋

🎉 Congratulations!

You've built, customized, and deployed your first Towns Protocol bot!

Your bot is now live and responding in Towns. Keep customizing with AI to add more features!

🔧 Troubleshooting

Bot not responding?

  • • Check Render logs for errors
  • • Verify environment variables are set correctly
  • • Make sure webhook URL ends with /webhook
  • • Check bot permissions in Developer Portal

Deployment failed?

  • • Check build logs in Render dashboard
  • • Verify package.json has correct scripts
  • • Make sure all files are committed to GitHub
  • • Try redeploying from Render dashboard

Need help?

Join the Towns Developer Town for support, or check the complete documentation in your template's README.md file.

📚 Learn More

Level up your bot building skills with comprehensive courses and tutorials

Now that you've built your first bot, explore the Towns Academy to dive deeper into advanced bot development, learn best practices, and discover new ways to leverage the Towns Protocol.

Explore Towns Academy

© River Eridanus Association, Switzerland, 2025

TermsPrivacy