Human Usage

Direct-code usage guide for @ghostpaw/telegram.

For agent builders wiring this into an LLM harness, read LLM.md instead.

Setup

import { DatabaseSync } from 'node:sqlite';
import { createBot, initTelegramTables } from '@ghostpaw/telegram';

const db = new DatabaseSync('bot.db');
initTelegramTables(db); // idempotent — safe to call on every restart

const bot = createBot({
  token: process.env.TELEGRAM_TOKEN!,
  db,
  onMessage:        async ({ message, user, chat, reply }) => { /* ... */ },
  onEditedMessage:  async ({ message, user }) => { /* ... */ },
  onCallback:       async ({ callback, user, chat, answer }) => { /* ... */ },
  onMemberUpdate:   async ({ chatId, member, oldMember }) => { /* ... */ },
  onReaction:       async ({ chatId, messageId, userId, oldReactions, newReactions }) => { /* ... */ },
  onPollAnswer:     async (ctx) => { /* ... */ },
  onJoinRequest:    async (ctx) => { /* ... */ },
});

await bot.start(); // begins long-polling
bot.stop();        // graceful shutdown

Webhook mode, pass webhook instead:

const bot = createBot({
  token: process.env.TELEGRAM_TOKEN!,
  db,
  webhook: { path: '/webhook', port: 8443, secretToken: process.env.TG_SECRET },
  onMessage: async ({ message, user }) => { /* ... */ },
});

await bot.start(); // HTTP server on port 8443; stop() closes it cleanly

initTelegramTables initialises all tables in dependency order (users → chats → members → messages → files → reactions → callbacks → bot_state). TelegramDb is satisfied directly by DatabaseSync.

Every incoming message with media (photo, document, voice, video, audio, animation, sticker, video_note) is eagerly downloaded and stored as a BLOB in SQLite before your handler is called.

Reading Data (read)

All read functions take db as the first argument and never call the Telegram API.

Users

Chats

Members

Messages

searchMessages uses FTS5 on text_plain. Cross-chat search is not supported, always supply chatId.

Reactions, Files, Callbacks, State

Files store the largest photo resolution, main media file, and thumbnails for video/audio/document. Retrieve the raw bytes with write.getFileBlob(db, fileId) → Buffer | null. Any file where the background download failed has checksum: null and can be retried with write.downloadFile(bot, db, fileId).

Sending Messages and Media (write)

All write functions take a MockBot (or grammy Bot via adaptBot) as the first argument and return a Promise.

Text

Media

Each media send accepts MediaInput: a string (file_id), Buffer, or { url: string }.

SendMediaOpts: caption?, parseMode?, replyToMessageId?, replyMarkup?.

File BLOBs

Actions and Keyboards

Build inline keyboards with the keyboards namespace:

import { keyboards, write } from '@ghostpaw/telegram';

const markup = keyboards.inlineKeyboard([
  [keyboards.callbackButton('✅ Yes', 'confirm:yes'), keyboards.callbackButton('❌ No', 'confirm:no')],
  [keyboards.urlButton('Docs', 'https://github.com/GhostPawJS/telegram')],
]);

await write.sendMessage(bot, chatId, 'Proceed?', { replyMarkup: markup });

Streaming

write.createStream(bot, opts) returns a StreamHandle for progressive in-place edits:

const stream = write.createStream(bot, { chatId, parseMode: 'HTML' });

// fire-and-forget with debounce (good for token-by-token LLM output)
stream.write('<b>chunk</b> ');

// immediate flush — good for explicit progress steps
await stream.append('Step 1 done\n');
await stream.append('Step 2 done\n');

// replace entire buffer and flush immediately
await stream.replace('Final answer.');

await stream.end(); // flush and mark done
stream.text;        // accumulated text so far
stream.done;        // true after end() resolves

StreamOpts: chatId, messageId?, parseMode?, debounceMs? (default 300), maxLength? (default 4096), onError?. Omit messageId to send a new message and edit in-place; provide it to start editing an existing one.

broadcast returns BroadcastResult: { sent: number; failed: number; errors: Array<{ chatId, error }> }.

Network (network)

Low-level transport layer for custom polling loops.

PollingContext requires: getUpdates, getMe, onUpdate, onError, signal (AbortSignal).

Rendering (render)

Pure functions, no I/O, no grammy dependency.

Always render before sending, Telegram's parse modes are strict. Use markdownToHtml + parseMode: 'HTML' for most cases.

Error Handling

import { isTelegramError, TelegramNotFoundError, TelegramValidationError } from '@ghostpaw/telegram';

try {
  await write.sendMessage(bot, chatId, text);
} catch (err) {
  if (err instanceof TelegramNotFoundError) {
    // chat not found or bot was removed
  } else if (isTelegramError(err)) {
    console.error(err.code, err.message);
  }
}

isTelegramError(e) narrows any unknown to TelegramError.