@astralibx/telegram-bot

A customizable Telegram bot factory with command registration, keyboard builder, webhook/polling support, user tracking, and Express admin routes. Create a fully functional bot with a single factory call.

Getting started? See the Quick Start Tutorial for a step-by-step walkthrough, Integration Guide for multi-package setup, or the Glossary for ID terminology.

Install

npm install @astralibx/telegram-bot

Peer Dependencies

| Package | Required | |---------|----------| | express | Yes | | mongoose | Yes | | node-telegram-bot-api | Yes |

npm install express mongoose node-telegram-bot-api

Quick Start

import express from 'express';
import mongoose from 'mongoose';
import { createTelegramBot } from '@astralibx/telegram-bot';

const app = express();
app.use(express.json());

const db = await mongoose.createConnection('mongodb://localhost:27017/myapp');

const bot = createTelegramBot({
  token: process.env.TELEGRAM_BOT_TOKEN!,
  mode: 'polling',
  db: { connection: db },
  commands: [
    {
      command: 'start',
      description: 'Start the bot',
      handler: async (msg, bot) => {
        await bot.sendMessage(msg.chat.id, `Welcome, ${msg.from?.first_name}!`);
      },
    },
    {
      command: 'help',
      description: 'Show help',
      handler: async (msg, bot) => {
        await bot.sendMessage(msg.chat.id, 'Available commands: /start, /help');
      },
    },
  ],
  callbacks: [
    {
      pattern: /btn_.*/,
      handler: async (query, bot) => {
        await bot.answerCallbackQuery(query.id, { text: 'Button clicked!' });
      },
    },
  ],
  hooks: {
    onUserStart: ({ firstName }) => console.log(`New user: ${firstName}`),
    onError: ({ error, context }) => console.error(`Error in ${context}:`, error.message),
  },
});

// Admin routes (protect with your own auth middleware)
app.use('/api/bot', bot.routes);

// Start the bot
await bot.start();

// Graceful shutdown
process.on('SIGTERM', () => bot.stop());

app.listen(3000);

Runtime Command Registration

bot.registerCommand({
  command: 'status',
  description: 'Show bot status',
  handler: async (msg, instance) => {
    const info = bot.getBotInfo();
    await instance.sendMessage(msg.chat.id, `Bot: ${info?.username}, Running: ${bot.isRunning()}`);
  },
});

bot.removeCommand('status');

Keyboard Builder

const kb = bot.keyboards;

// Inline keyboard
const inline = kb.inline([
  [{ text: 'Yes', callback_data: 'confirm_yes' }, { text: 'No', callback_data: 'confirm_no' }],
]);
await bot.sendMessage(chatId, 'Confirm?', { reply_markup: inline });

// Reply keyboard
const reply = kb.reply([['Option A', 'Option B'], ['Option C']], { oneTimeKeyboard: true });
await bot.sendMessage(chatId, 'Choose:', { reply_markup: reply });

// Remove keyboard
const remove = kb.remove();
await bot.sendMessage(chatId, 'Keyboard removed.', { reply_markup: remove });

Features

• Polling and webhook modes -- Choose between long-polling or webhook with automatic setup. Details
• Command registration -- Define commands at creation or register them at runtime. Details
• Callback and inline query handlers -- Pattern-matched handlers for interactive elements. Details
• Keyboard builder -- Fluent API for inline, reply, and remove keyboards. Details
• Middleware chain -- Intercept messages before command handlers execute. Details
• User tracking -- Automatic contact tracking with interaction history per bot. Details
• Admin API routes -- 4 REST endpoints for bot status, stats, and user management. Details
• Lifecycle hooks -- React to new users, blocked users, commands, and errors. Details
• Account Manager Bridge -- Optional integration with @astralibx/telegram-account-manager for sending messages via TDLib clients. Details

Getting Started Guide

1. Configuration -- Token, mode, database, commands, callbacks, middleware, hooks
2. API Routes -- 4 admin REST endpoints for status, stats, and users
3. Types -- All importable types, constants, errors, and service classes

Account Manager Bridge

Optional utility for integrating with @astralibx/telegram-account-manager. Allows bot commands to send messages via TDLib clients.

import { createAccountManagerBridge } from '@astralibx/telegram-bot';
import { createTelegramAccountManager } from '@astralibx/telegram-account-manager';

const tam = createTelegramAccountManager(config);
const bridge = createAccountManagerBridge(tam);

// In a bot command handler:
commands: [{
  command: 'send',
  description: 'Send via TDLib',
  handler: async (msg, bot) => {
    await bridge.sendViaTDLib('account-id', msg.chat.id.toString(), 'Hello from TDLib!');
  },
}]

See Types for the AccountManagerBridge and AccountManagerLike interfaces.

License

MIT