Node Telegram Bot Framework

A Telegram bot framework built on Telegraf with filesystem-based handler routing, persisted sessions, built-in middleware, and TypeScript typings.

It ships built-in features for:

• admin/start-message mailing flows
• optional human-to-human help sessions (human_help_session/*)

Package output

This package is authored in TypeScript and published as compiled CommonJS from dist/.

• runtime entry: dist/index.js
• type declarations: dist/index.d.ts

If you are working inside this repository, build before consuming the package locally:

npm install
npm run build

Installation

npm install oira666_tg telegraf

telegraf is a peer dependency and must be installed by the consuming bot project.

Quick start

const path = require('path');
const { Telegraf, Markup } = require('telegraf');
const {
  apply_middlewares,
  start_builtin_human_help_workers,
} = require('oira666_tg');
const db = require('./db');

const bot = new Telegraf(process.env.BOT_TOKEN);

await apply_middlewares(bot, {
  db,
  Markup,
  handlers_path: path.resolve(__dirname, './dist/handlers'),
  resources_path: path.resolve(__dirname, './resources'),
  allowed_user_commands: ['start', 'help'],
  mailing: {
    enabled: true,
  },
  human_help: {
    enabled: true,
    support_phone: '8 800 551-62-60',
    operators: {
      roles: ['admin'],
    },
    session: {
      working_hours: {
        timezone: 'Europe/Moscow',
        start_hour: 9,
        end_hour: 19,
      },
    },
    workers: {
      enabled: true,
      auto_start: false,
    },
  },
});

start_builtin_human_help_workers(bot);

Built-in mailing feature

Before enabling built-in mailing, create the mailing tables (mailing_queue, mailing_autoschedule, mailing_autoschedule_queue). See docs/setup.md.

Config block

options.mailing supports these top-level sections:

• enabled
• admin.enabled
• schedule.enabled
• autoschedule.enabled
• start_messages.enabled
• start_messages.send_immediate_rules
• start_messages.enqueue_delayed_rules
• workers.enabled
• workers.auto_start
• workers.schedule_cron
• workers.autoschedule_cron
• workers.due_batch_size
• audiences
• artifacts.path
• send.pause_every
• send.pause_ms
• timezone

Defaults are merged automatically. If mailing.artifacts.path is omitted and resources_path is set, artifacts default to:

<resources_path>/autoschedule/artifacts

Consumer override caveat

Consumer handlers are resolved before framework built-ins. If your bot previously implemented its own mailing flow or admin stats handler, those local handlers will shadow the package handlers.

When migrating to the built-in mailing/stats features, archive/remove local admin/mailing and admin/stats handlers and old /start or cron wiring if you want only framework mailing behavior and no duplicate sends/UI.

/start semantics

The start-message pipeline runs before the resolved /start handler, but only when the resolved handler is:

• type === 'command'
• name === 'start'

Important runtime behavior:

• it runs on each real /start command, not just the first one
• zero-delay autoschedule rules are sent immediately on /start
• delayed autoschedule rules are enqueued on /start
• redirects or text buttons that eventually lead to start do not trigger the pipeline
• the built-in start handler is a no-op, so /start can still trigger mailing even if the consumer does not provide its own start handler

Workers

Built-in mailing workers auto-start inside apply_middlewares() when:

• mailing.enabled === true
• mailing.workers.enabled === true
• mailing.workers.auto_start === true

You can also manage them manually:

const {
  start_builtin_mailing_workers,
  stop_builtin_mailing_workers,
} = require('oira666_tg');

start_builtin_mailing_workers(bot);
stop_builtin_mailing_workers(bot);

The worker bootstrap helper is duplicate-safe for the same bot/config signature.

Built-in human-help feature

The framework can provide a reusable human-help flow under the built-in handler namespace:

• human_help_session/get_human_help
• human_help_session/start_session
• human_help_session/first_question
• human_help_session/request_operators
• human_help_session/first_answer
• human_help_session/on_message
• human_help_session/on_waiting_message
• human_help_session/finish_session
• human_help_session/no_commands
• human_help_session/no_questions
• human_help_session/cleanup_stale_sessions

The feature is disabled by default. Consumers keep control of entrypoints like /help, /start help, and menu buttons by redirecting into that namespace.

Config block

options.human_help supports these sections:

• enabled
• handlers.enabled
• intercept_active_messages
• support_phone
• operators.roles
• operators.resolve
• operators.format_display_name
• requests.send_immediately
• requests.resend_pending_via_workers
• requests.waiting_notice_delay_ms
• requests.operator_button_text
• session.stop_word
• session.inactivity_timeout_ms
• session.stale_waiting_timeout_minutes
• session.stale_active_timeout_minutes
• session.working_hours.timezone
• session.working_hours.start_hour
• session.working_hours.end_hour
• workers.enabled
• workers.auto_start
• workers.request_operators_cron
• workers.cleanup_cron

Defaults are merged automatically. Recommended opt-in stance:

human_help: {
  enabled: true,
  workers: {
    enabled: true,
    auto_start: false,
  },
}

Runtime behavior

When enabled, the framework inserts two human-help hooks into the middleware chain:

1. a context binder that loads ctx.human_help
2. a late session-state guard that:
   • replaces previously resolved handlers with human_help_session/on_message for active dialogs
   • replaces only unresolved/unhandled plain messages with human_help_session/on_waiting_message while a client is still waiting for an operator

This preserves consumer-first routing while still letting waiting/active support dialogs avoid the generic unhandled-message fallback.

Workers

Human-help workers are separate from mailing workers and are also duplicate-safe.

const {
  start_builtin_human_help_workers,
  stop_builtin_human_help_workers,
} = require('oira666_tg');

start_builtin_human_help_workers(bot);
stop_builtin_human_help_workers(bot);

Recommended production stance:

• keep auto_start: false
• explicitly start workers in exactly one process

Migration note for existing bots

If a consumer bot already had app-local human-help code:

• keep local /help, /start help, and menu-button entrypoints if desired
• migrate your prefixed human_session.operator_id column to NULL DEFAULT NULL when practical; the framework now falls back to legacy 0 writes when a live schema still rejects NULL, but nullable remains the intended schema
• remove local human_help_session/* handlers once parity is confirmed
• remove local human-help middleware once human_help.enabled is on
• remove duplicate human-help cron jobs if framework workers are used

Handler path note for TypeScript consumers

Handler discovery is runtime JS-based. If your bot handlers are authored in TypeScript, compile them first and point handlers_path at the compiled JavaScript output directory.

Supported handler file shapes under handlers_path:

• name.js
• name/index.js
• name/main.js

Exported TypeScript types

The package exports runtime helpers and public types, including:

• BotContext
• FrameworkOptions
• RuntimeConfig
• HandlerDescriptor
• DatabaseAdapter
• MailingFeatureOptions
• HumanHelpFeatureOptions
• HumanHelpOperatorResolver

Repository validation commands

npm run typecheck
npm test -- --runInBand
npm run lint
npm run build
npm pack --dry-run

Documentation

• Getting Started
• Installation & Setup
• Usage Guide
• Architecture & Internals