Class Application

Main application class responsible for managing handlers, polling loops, webhook servers, and error handling.

Example

const app = new Application(process.env.BOT_TOKEN!);
app.addHandler(new CommandHandler("start", startCallback));
await app.runPolling();

Index

Constructors

constructor

new Application(
token: string,
options?: ApplicationOptions & BotOptions,
): Application
Constructs a new Application from a bot token or existing Bot.
Parameters
- token: string
- Optionaloptions: ApplicationOptions & BotOptions
Returns Application
new Application(bot: Bot, options?: ApplicationOptions): Application
Parameters
- bot: Bot
- Optionaloptions: ApplicationOptions
Returns Application

Properties

`Readonly`bot

bot: Bot

The underlying Bot API client.

isRunning

isRunning: boolean = false

Indicates whether the polling loop is actively running.

`Readonly`persistence

persistence: Persistence

Active persistence store for conversation and context data.

`Readonly`scheduler

scheduler: JobQueue

Background task scheduler and timer engine.

Accessors

job_queue

get job_queue(): JobQueue

Compatibility alias for Application.scheduler.

Returns JobQueue

Methods

addErrorHandler

addErrorHandler(callback: ErrorHandlerCallback): void
Registers a global error handler callback.
Parameters
- callback: ErrorHandlerCallback
  Function invoked when an error occurs during update processing or polling.
Returns void

addHandler

addHandler(handler: BaseHandler, group?: number): void
Registers an update handler into a numerical priority group.
Parameters
- handler: BaseHandler
  The BaseHandler instance.
- group: number = 0
  Numerical priority group (lower runs earlier, default: 0).
Returns void

addHandlers

addHandlers(
    handlers: BaseHandler<
        CallbackContext<
            Record<string, unknown>,
            Record<string, unknown>,
            Record<string, unknown>,
        >,
        unknown,
    >[],
    group?: number,
): void
Registers multiple update handlers simultaneously into a handler group.
Parameters
- handlers: BaseHandler<
      CallbackContext<
          Record<string, unknown>,
          Record<string, unknown>,
          Record<string, unknown>,
      >,
      unknown,
  >[]
  Array of BaseHandler instances.
- group: number = 0
  Numerical priority group (default: 0).
Returns void

callbackQuery

callbackQuery(
    pattern:
        | string
        | boolean
        | RegExp
        | (string | RegExp)[]
        | ((data: string) => boolean),
    callback: HandlerCallback,
    group?: number,
): this
Registers an inline callback query button listener shortcut.
Parameters
- pattern: string | boolean | RegExp | (string | RegExp)[] | ((data: string) => boolean)
  Callback data string, RegExp pattern, or boolean (match all).
- callback: HandlerCallback
  Callback function invoked when matching button is tapped.
- group: number = 0
  Handler priority group (default: 0).
Returns this
This Application instance for chaining.
Example
```
app.callbackQuery("buy_item", async (update, context) => {
  await context.answerCallbackQuery({ text: "Item added to cart!" });
});
```

command

command(
    command: string | string[],
    callback: HandlerCallback,
    group?: number,
): this
Registers a command handler shortcut (e.g. /start, /help).
Parameters
- command: string | string[]
  Command name (without leading /) or array of command names.
- callback: HandlerCallback
  Callback function invoked when matching command is received.
- group: number = 0
  Handler priority group (default: 0).
Returns this
This Application instance for chaining.
Example
```
app.command("start", async (update, context) => {
  await context.reply("Welcome to our bot!");
});
```

conversation

conversation(name: string, handler: AsyncConversationHandlerFn): this
Registers a named linear async/await conversation flow.
Parameters
- name: string
  Unique string identifier for the conversation.
- handler: AsyncConversationHandlerFn
  Sequential asynchronous conversation generator or callback.
Returns this
This Application instance for chaining.
Example
```
app.conversation("survey", async (conv, ctx) => {
  const name = await conv.ask("What is your name?");
  await ctx.reply(`Nice to meet you, ${name}!`);
});
```

enterConversation

enterConversation(
    userId: number,
    name: string,
    initialContext?: CallbackContext<
        Record<string, unknown>,
        Record<string, unknown>,
        Record<string, unknown>,
    >,
): Promise<void>
Enters a registered linear async conversation for a specific user.
Parameters
- userId: number
  Target user identifier.
- name: string
  Name of the registered conversation to enter.
- OptionalinitialContext: CallbackContext<
      Record<string, unknown>,
      Record<string, unknown>,
      Record<string, unknown>,
  >
  Optional initial callback context.
Returns Promise<void>
Resolves with the conversation execution promise.
Example
```
await app.enterConversation(123456, "survey");
```

flushPlugins

flushPlugins(): this

Installs all deferred plugins whose dependencies are now satisfied.

Called automatically by every Application.usePlugin; invoke manually only if you need deterministic installation before registering further plugins.

Returns this
This Application instance for chaining.

hasPlugin

hasPlugin(name: string): boolean
Returns whether a plugin with the given name is currently installed.
Parameters
- name: string
  Plugin name to look up.
Returns boolean
True if the plugin is installed.

hears

hears(
    pattern: string | RegExp | (string | RegExp)[],
    callback: HandlerCallback,
    group?: number,
): this
Registers a text pattern listener shortcut matching text strings or regular expressions.
Parameters
- pattern: string | RegExp | (string | RegExp)[]
  String text or RegExp pattern to match in incoming text messages.
- callback: HandlerCallback
  Callback function invoked when pattern matches.
- group: number = 0
  Handler priority group (default: 0).
Returns this
This Application instance for chaining.
Example
```
app.hears(/order ([0-9]+)/i, async (update, context) => {
  const orderId = context.matches?.[0]?.[1];
  await context.reply(`Checking order ${orderId}...`);
});
```

initializePersistence

initializePersistence(): Promise<void>

Initializes persistent conversation states from persistence storage.

Returns Promise<void>

on

on(
    filterOrType:
        | string
        | BaseFilter
        | ((update: RawUpdate | Update) => boolean | Promise<boolean>),
    callback: HandlerCallback,
    group?: number,
): this
Registers a message filter or update type listener shortcut.
Parameters
- filterOrType:
      | string
      | BaseFilter
      | ((update: RawUpdate | Update) => boolean | Promise<boolean>)
  A BaseFilter, update property key string (e.g. 'message', 'inline_query'), or custom predicate function.
- callback: HandlerCallback
  Callback function invoked when update matches.
- group: number = 0
  Handler priority group (default: 0).
Returns this
This Application instance for chaining.
Example
```
app.on(filters.PHOTO, async (update, context) => {
  await context.reply("Thanks for the photo!");
});
```

onInit

onInit(hook: () => void | Promise<void>): this
Registers a hook invoked once, in registration order, right before the application starts serving updates (polling or webhook). Use it for asynchronous plugin setup such as opening connections or warming caches.
Parameters
- hook: () => void | Promise<void>
  Callback executed before startup completes.
Returns this
This Application instance for chaining.
Example
```
app.onInit(async () => {
  await loadTranslations();
});
```

onShutdown

onShutdown(hook: () => void | Promise<void>): this
Registers a hook invoked once, in registration order, during Application.stop after the server stops and persisted state is flushed. Use it to release resources held by plugins.
Parameters
- hook: () => void | Promise<void>
  Callback executed during shutdown.
Returns this
This Application instance for chaining.
Example
```
app.onShutdown(() => metricsClient.close());
```

pluginState

pluginState<T extends Record<string, unknown> = Record<string, unknown>>(
name: string,
): T
Returns the mutable namespaced state object for a plugin, creating it on first access.

Gives plugins their own key space so they never collide with bot code or other plugins in user_data/bot_data. The object lives for the application's lifetime; persist anything important into bot_data from an onShutdown hook.
Type Parameters
- T extends Record<string, unknown> = Record<string, unknown>
  Shape the caller expects the state to have.
Parameters
- name: string
  Plugin name owning the state (usually plugin.name).
Returns T
The plugin's state object.
Example
```
const state = app.pluginState<{ counter?: number }>("my-plugin");
state.counter = (state.counter ?? 0) + 1;
```

processUpdate

processUpdate(rawUpdate: Record<string, unknown> | RawUpdate): Promise<void>
Processes a single update through the registered handler pipeline.
Parameters
- rawUpdate: Record<string, unknown> | RawUpdate
  The update payload received from Telegram.
Returns Promise<void>

removePlugin

removePlugin(name: string): this
Uninstalls a plugin: runs its optional uninstall hook, deregisters every middleware, handler, lifecycle hook, and error handler it registered, removes its tagged bot hooks, and drops its Application.pluginState. The name can be reused afterwards.
Parameters
- name: string
  Name of the installed plugin to remove.
Returns this
This Application instance for chaining.
Throws
When no plugin with that name is installed.
Example
```
app.removePlugin("telebot-plugin-i18n");
```

runPolling

runPolling(options?: PollingLoopOptions): Promise<void>
Starts long polling for updates from Telegram Bot API.
Parameters
- options: PollingLoopOptions = {}
  Polling configuration options.
Returns Promise<void>
Resolves when polling stops.

runWebhook

runWebhook(options?: WebhookServerOptions): Promise<void>
Starts a webhook HTTP server to receive updates pushed directly by Telegram.
Parameters
- options: WebhookServerOptions = {}
  Webhook server configuration options.
Returns Promise<void>

Throws
If the application is already running in polling or webhook mode.

stop

stop(): Promise<void>

Stops the active polling loop or webhook server, shuts down the scheduler, and flushes persistent state.

Returns Promise<void>

use

use(...middlewares: (MiddlewareFn | { middleware: () => MiddlewareFn })[]): this
Registers one or more global middleware functions or middleware-providing objects (e.g. Menu) executed on every incoming update.
Parameters
- ...middlewares: (MiddlewareFn | { middleware: () => MiddlewareFn })[]
  Middleware functions or objects with a middleware() method to execute in order.
Returns this
This Application instance for chaining.
Example
```
app.use(async (context, next) => {
  const start = Date.now();
  await next();
  console.log(`Update processed in ${Date.now() - start}ms`);
});

// Or with Menu
app.use(myMenu);
```

usePlugin

usePlugin(plugin: Plugin): this
Installs a Plugin into the application.

The plugin's install hook receives this application and wires up middleware, handlers, and lifecycle hooks synchronously. Installing two plugins with the same name throws. Plugins whose dependsOn dependencies are not installed yet are deferred and installed automatically (in ascending priority order) once their dependencies arrive.
Parameters
- plugin: Plugin
  The plugin instance to install.
Returns this
This Application instance for chaining.
Throws
When a plugin with the same name is already installed.
Example
```
import { plugins } from "telebot-ts";

app.usePlugin(
  plugins.i18n({ default_locale: "en", locales: { en: { hello: "Hello!" } } }),
);
```

`Static`builder

builder(): ApplicationBuilder

Creates a new fluent ApplicationBuilder instance.

Returns ApplicationBuilder
An ApplicationBuilder instance.

Class Application

Example

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns Application

Parameters

Returns Application

Properties

Readonlybot

isRunning

Readonlypersistence

Readonlyscheduler

Accessors

job_queue

Returns JobQueue

Methods

addErrorHandler

Parameters

Returns void

addHandler

Parameters

Returns void

addHandlers

Parameters

Returns void

callbackQuery

Parameters

Returns this

Example

command

Parameters

Returns this

Example

conversation

Parameters

Returns this

Example

enterConversation

Parameters

Returns Promise<void>

Example

flushPlugins

Returns this

hasPlugin

Parameters

Returns boolean

hears

Parameters

Returns this

Example

initializePersistence

Returns Promise<void>

on

Parameters

Returns this

Example

onInit

Parameters

Returns this

Example

onShutdown

Parameters

Returns this

Example

pluginState

Type Parameters

Parameters

Returns T

Example

processUpdate

Parameters

Returns Promise<void>

removePlugin

Parameters

`Readonly`bot

`Readonly`persistence

`Readonly`scheduler

`Static`builder