Build a bot in 60 seconds.

Construct a bot. Does not open the connection — call connect() for that.

Register a command handler. Call before connect(). Duplicate names throw.

bot.cmd('greet', async (ctx) => {
  // ctx.command  — 'greet'
  // ctx.args     — parsed args from the consumer
  // ctx.msgId    — unique id for this invocation
  await ctx.reply({ text: `Hello, ${ctx.args.name ?? 'world'}!` });
});

Reply body supports three optional fields:

Reply with a scrollable list — each item renders as a row in the chat UI. One reply per command, exactly like ctx.reply().

bot.cmd('headlines', async (ctx) => {
  await ctx.replyList(
    [
      { label: 'AP', title: 'Markets rally on rate news', secondary: '2m', href: 'https://example.com/a' },
      { label: 'Reuters', title: 'Chip demand keeps climbing', secondary: '14m', href: 'https://example.com/b' },
    ],
    { header: 'Top stories' },
  );
});

Reply with a table. rows is an array of rows, each an array of cells (string | number | null) lined up with headers.

bot.cmd('prices', async (ctx) => {
  await ctx.replyTable({
    headers: ['Ticker', 'Price', 'Change'],
    rows: [
      ['AAPL', 231.4, '+1.2%'],
      ['MSFT', 502.1, '-0.4%'],
    ],
  });
});

Reply with an inline image. image accepts raw bytes (Buffer / Uint8Array), a base64 string, or a full data: URL. Only raster types (png / jpeg / gif / webp) — SVG is rejected because inline SVG can run script.

bot.cmd('qr', async (ctx) => {
  const png = await makeQrPng(ctx.args.text ?? 'hello'); // returns a Buffer
  await ctx.replyImage(png, { mimeType: 'image/png', alt: 'QR code' });
});

Send an intermediate progress frame. Only available when the bot opts into streaming via new Bot({ id, streaming: true }) or per-command bot.cmd(name, { streaming: true }, handler). Multiple calls allowed; ctx.reply() marks the dispatch complete.

bot.cmd('analyze', { streaming: true }, async (ctx) => {
  await ctx.update({ progress: 10, text: 'Fetching…' });
  await ctx.update({ progress: 60, text: 'Crunching…' });
  await ctx.reply({
    text: 'done',
    mimeType: 'image/png',
    data: chartBytesBase64,
  });
});

progress accepts a number (0–100 percent), { current, total } for step counters, or { label: string } for indeterminate progress (renders as a spinner + label in the chat UI).

Requires SDK @localhostdevs/sdk@^0.4.0. See /docs/api for the consumer side.

Declare the mimeType this command's reply returns. Shown on the bot detail page so consumers know what to expect.

bot.cmd('chart', { streaming: true, mimeType: 'image/png' }, async (ctx) => {
  await ctx.update({ progress: 50 });
  await ctx.reply({ data: chartBytes, mimeType: 'image/png' });
});

Advertising only — the actual mimeType on the wire is whatever ctx.reply({ mimeType }) passes at runtime.

Reply with clickable buttons. A click is a new, separate dispatch — it does not resume the command that showed the buttons. Route each click to a hidden handler registered with bot.action. Each button is { label, action, args?, style?, charge? } — style is 'primary' | 'danger' | 'default'.

bot.cmd('deploy', async (ctx) => {
  await ctx.replyButtons('Ship to production?', [
    { label: 'Deploy', action: 'do-deploy', args: { go: true }, style: 'primary' },
    { label: 'Cancel', action: 'do-deploy', args: { go: false }, style: 'default' },
  ]);
});

bot.action('do-deploy', async (ctx) => {
  await ctx.reply({ text: ctx.args.go ? 'Deploying…' : 'Cancelled.' });
});

Clicks are free by default; pass charge: true on a button to bill it like a command. ctx.user?.id identifies who clicked.

Shorthands over replyButtons. askYesNo dispatches its action with { answer: 'yes' | 'no' }; askChoice renders one button per option and dispatches { choice: '<option>' }. Any args you pass are merged into the click dispatch.

bot.cmd('reset', async (ctx) => {
  await ctx.askYesNo('Wipe all data?', { action: 'do-reset' });
});
bot.action('do-reset', async (ctx) => {
  await ctx.reply({ text: ctx.args.answer === 'yes' ? 'Wiped.' : 'Kept.' });
});

bot.cmd('size', async (ctx) => {
  await ctx.askChoice('Pick a size', { action: 'pick-size', options: ['S', 'M', 'L'] });
});
bot.action('pick-size', async (ctx) => {
  await ctx.reply({ text: `You picked ${ctx.args.choice}.` });
});

Register a HIDDEN handler — same shape as bot.cmd, but it never appears in the command list. It runs only when a consumer clicks a button whose action matches id, and replies exactly once just like a command.

Opens the WebSocket, sends IDENTIFY, waits for HELLO from the gateway, starts the heartbeat loop. Resolves once the bot is ready to receive commands.

Closes the WebSocket cleanly. After ~30s of silence the marketplace marks your bot offline.