Slash Commands

Slash commands are special message types that:

• Start with / (e.g., /help, /poll, /weather)
• Show up in autocomplete when users type / in Towns
• Display descriptions to help users understand what they do
• Are handled separately from regular messages (don’t trigger onMessage)

Example Commands

/help                         → Show bot commands
/ban @john                    → Ban a user
/weather San Francisco        → Get weather for a location
/remind 5m Check the oven     → Set a reminder

Creating commands

Commands are defined in a TypeScript file (typically src/commands.ts):

src/commands.ts

import type { BotCommand } from '@towns-protocol/bot'

export const commands = [
  {
    name: 'help',
    description: 'Show available bot commands'
  },
  {
    name: 'ping',
    description: 'Check if bot is responding'
  },
  {
    name: 'greet',
    description: 'Greet a user'
  },
  {
    name: 'weather',
    description: 'Get current weather for a location'
  }
] as const satisfies BotCommand[]

export default commands

Handling Commands

You can use bot.onSlashCommand() to handle each slash command:

src/index.ts

import { makeTownsBot } from '@towns-protocol/bot'
import commands from './commands'

const bot = await makeTownsBot(appPrivateData, jwtSecret, { commands })

// Handle /help command
bot.onSlashCommand('help', async (handler, event) => {
  const commandList = commands
    .map(cmd => `• \`/${cmd.name}\` - ${cmd.description}`)
    .join('\n')

  await handler.sendMessage(
    event.channelId,
    `**Available Commands**\n${commandList}`
  )
})

// Handle /ping command
bot.onSlashCommand('ping', async (handler, event) => {
  const latency = Date.now() - event.createdAt.getTime()
  await handler.sendMessage(event.channelId, `Pong! 🏓 (${latency}ms)`)
})

Working with Arguments

Slash commands can receive arguments after the command name.

You can get them from the args property of the event.

bot.onSlashCommand('weather', async (handler, { args, channelId }) => {
  // /weather San Francisco
  // args: ['San', 'Francisco']

  const location = args.join(' ')

  if (!location) {
    await handler.sendMessage(
      channelId,
      'Usage: /weather <location>\nExample: /weather San Francisco'
    )
    return
  }

  const weather = await callWeatherAPI(location)
  await handler.sendMessage(
    channelId,
    `Weather in ${location}: ${weather.temp}°F, ${weather.conditions}`
  )
})

Working with Mentions

Users can mention other users or the bot in slash commands.

You can get the mentions from the mentions property of the event.

// /greet @john @jane
bot.onSlashCommand('greet', async (handler, { channelId, mentions}) => {
  if (mentions.length === 0) {
    await handler.sendMessage(
      channelId,
      'Usage: /greet @user1 @user2 ...'
    )
    return
  }

  const greetings = mentions
    .map(m => `Hello <@${m.userId}>!`)
    .join('\n')

  await handler.sendMessage(channelId, greetings, { mentions })
})

Checking Permissions

You may want to check if the user has the necessary permissions to use a command.

You can use the hasAdminPermission method to check if the user is an admin. This is a shortcut for checking if the user has the ModifyBanning permission.

If you want to check for a specific permission, you can use the checkPermission method.

bot.onSlashCommand('ban', async (handler, { userId, spaceId, channelId, mentions }) => {
  // Check if user is admin
  const isAdmin = await handler.hasAdminPermission(userId, spaceId)
  if (!isAdmin) {
    await handler.sendMessage( channelId, '❌ Only admins can use this command')
    return
  }
  const userToBan = mentions[0]?.userId
  if (!userToBan) {
    await handler.sendMessage( channelId, 'Usage: /ban @user')
    return
  }
  try {
    await handler.ban(userToBan, spaceId)
    await handler.sendMessage(
      channelId,
      `✓ Banned <@${userToBan}>`
    )
  } catch {
    await handler.sendMessage( channelId, '❌ Failed to ban user')
  }
})

Paid Commands

You can create commands that require USDC payments. Payments are processed through the x402 protocol v2, supporting multi-chain payments and reusable sessions.

Note: This bot flow uses a facilitator to verify and settle payments after a user signs an authorization inside Towns. It does not use the standard x402 HTTP middleware headers (PAYMENT-SIGNATURE / PAYMENT-RESPONSE) because Towns bots are not HTTP endpoints.

Defining Paid Commands

Add a paid property to your command definition with a price in USDC:

src/commands.ts

import type { BotCommand } from '@towns-protocol/bot'

export const commands = [
  {
    name: 'generate',
    description: 'Generate AI content',
    paid: { price: '$0.20' }
  }
] as const satisfies BotCommand[]

export default commands

How it works

When a user invokes a paid command:

1. Bot sends a signature request for USDC transfer authorization
2. User signs the request in their wallet
3. Payment is verified and settled via the x402 facilitator
4. Your command handler executes after successful payment

Configuring the Facilitator

Configure which x402 facilitator the bot will call for verify/settle:

src/index.ts

const bot = await makeTownsBot(
  process.env.APP_PRIVATE_DATA!,
  process.env.JWT_SECRET!,
  {
    commands,
    paymentConfig: {
      // Public facilitator (recommended default):
      url: 'https://www.x402.org/facilitator',
      // Optional: some facilitators require an API key
      // apiKey: process.env.X402_API_KEY,
    },
  }
)

If you’re using Coinbase/CDP’s hosted facilitator, set:

paymentConfig: {
  url: 'https://api.cdp.coinbase.com/platform/v2/x402',
  // apiKey: process.env.X402_API_KEY,
}

// Handler only runs after payment succeeds
bot.onSlashCommand('generate', async (handler, event) => {
  // Payment already processed at this point
  await handler.sendMessage(
    event.channelId,
    'Thank you for your purchase! Here is your generated content...'
  )
})

Sessions (Pay Once, Use Many)

Enable session-based access to reduce friction for users who call your command frequently. With sessions, users pay once and can use the command multiple times within a time window.

src/commands.ts

export const commands = [
  {
    name: 'generate',
    description: 'Generate AI content',
    paid: {
      price: '$1.00',
      session: {
        duration: 3600,  // 1 hour session
        maxUses: 10      // Optional: limit uses per session
      }
    }
  }
] as const satisfies BotCommand[]

When a user with an active session invokes the command:

• The command executes immediately without payment
• Session usage is tracked and displayed to the user
• After session expires or uses are exhausted, payment is required again

Multi-Chain Support

Accept payments on multiple blockchain networks. The x402 v2 protocol uses CAIP-2 network identifiers.

src/commands.ts

import { EVM_NETWORKS } from '@towns-protocol/bot'

export const commands = [
  {
    name: 'premium',
    description: 'Premium feature',
    paid: {
      price: '$5.00',
      networks: [
        EVM_NETWORKS.base,           // eip155:8453
        EVM_NETWORKS['base-sepolia'], // eip155:84532
        EVM_NETWORKS.ethereum,        // eip155:1
        EVM_NETWORKS.arbitrum,        // eip155:42161
      ]
    }
  }
] as const satisfies BotCommand[]

Supported Networks:

Network	CAIP-2 Identifier
Base	eip155:8453
Base Sepolia	eip155:84532
Ethereum	eip155:1
Ethereum Sepolia	eip155:11155111
Arbitrum One	eip155:42161
Optimism	eip155:10
Polygon	eip155:137

Note: Solana CAIP-2 identifiers are part of the broader x402 v2 ecosystem, but the Towns bot paid-command flow currently supports EVM networks only.

Custom Payment Recipient

By default, payments go to your bot’s app address. You can specify a different recipient:

src/commands.ts

export const commands = [
  {
    name: 'donate',
    description: 'Donate to charity',
    paid: {
      price: '$10.00',
      payTo: '0x742d35Cc6634C0532925a3b844Bc9e7595f...' // Custom recipient
    }
  }
] as const satisfies BotCommand[]

Updating Commands

Commands are automatically synced with Towns when your bot starts.

To update your bot’s slash commands:

1. Modify your command definitions in src/commands.ts
2. Restart your bot

The new commands will be automatically registered and appear in Towns’ autocomplete.

Next Steps

• Learn about handling other events
• Explore message formatting and attachments
• See permission-based features