Quickstart

Build a channel monitor bot in 5 minutes

Build a bot that watches a channel and responds to messages. You’ll use all three SDK modes: queries to read, mutations to write, and realtime to subscribe.

Prerequisites

A start.chat server you admin
An API key from Server Settings → API Keys
Node.js 18+

1. Set up

Terminal

mkdir my-bot && cd my-bot
npm init -y
npm install @start-chat/sdk

Create bot.ts:

import { setup, query, mutate, realtime } from '@start-chat/sdk'

await setup({ apiKey: 'sk_live_your_api_key' })

2. Find your channel

// list servers you belong to
const servers = await query.userServers()
console.info(
  'Servers:',
  servers.map((s) => `${s.name} (${s.id})`),
)

// list channels in your server
const channels = await query.channelsByServer({
  serverId: servers[0].id,
})
console.info(
  'Channels:',
  channels.map((c) => `#${c.name} (${c.id})`),
)

Run it to get IDs:

Terminal

npx tsx bot.ts

3. Read messages

const messages = await query.channelMessages({
  serverId: 'srv_...',
  channelId: 'ch_...',
  limit: 5,
})

for (const msg of messages) {
  console.info(`${msg.user?.name}: ${msg.content}`)
}

4. Send a message

await mutate.message.send({
  channelId: 'ch_...',
  content: 'Hello from my bot!',
})

This is where it gets interesting. Instead of polling, subscribe to the channel and react to new messages in real-time:

import { setup, mutate, realtime } from '@start-chat/sdk'
import { channelMessages } from '@start-chat/sdk/queries'

await setup({ apiKey: 'sk_live_your_api_key' })

const SERVER = 'srv_...'
const CHANNEL = 'ch_...'

let lastSeen = 0

realtime.subscribe(
  channelMessages,
  { serverId: SERVER, channelId: CHANNEL },
  (messages) => {
    // find new messages since last check
    const newMessages = messages.filter((m) => m.createdAt > lastSeen)
    if (newMessages.length === 0) return

    lastSeen = Math.max(...messages.map((m) => m.createdAt))

    for (const msg of newMessages) {
      // don't respond to our own messages
      if (msg.type === 'bot') continue

      console.info(`New: ${msg.user?.name}: ${msg.content}`)

      // respond to mentions of "hello"
      if (msg.content?.toLowerCase().includes('hello')) {
        mutate.message.send({
          channelId: CHANNEL,
          content: `Hey ${msg.user?.name}!`,
        })
      }
    }
  },
)

console.info('Bot is running. Press Ctrl+C to stop.')

// keep alive
await new Promise(() => {})

Run it:

Terminal

npx tsx bot.ts

Your bot is now watching the channel. Send “hello” in the channel and it responds instantly — no polling, no webhooks, no WebSocket boilerplate.

6. Error handling

import { setup, query } from '@start-chat/sdk'

try {
  await setup({ apiKey: 'sk_live_your_api_key' })
} catch (e) {
  // invalid key, network error, etc.
  console.error('Setup failed:', e.message)
  process.exit(1)
}

try {
  const messages = await query.channelMessages({
    serverId: 'srv_...',
    channelId: 'ch_...',
  })
} catch (e) {
  // permission denied, channel not found, etc.
  console.error('Query failed:', e.message)
}

Overview

Queries

Quickstart

Build a channel monitor bot in 5 minutes

Prerequisites

1. Set up

2. Find your channel

3. Read messages

4. Send a message

5. Subscribe to live updates

6. Error handling