Class TelegramAdapter

Адаптер, обеспечивающий поддержку платформы Telegram. Позволяет разрабатывать чат-ботов для Телеграм на TypeScript с использованием кросс-платформенного функционала: обработка текстовых запросов, работа с карточками и кнопками.

Подключение адаптера не требует изменения существующей бизнес-логики: после интеграции все команды и обработчики, написанные для umbot, автоматически становятся доступны для Telegram. Единый интерфейс позволяет одновременно использовать одну бизнес-логику для нескольких платформ (Telegram, VK, Алиса и др.) без дублирования кода.

Этот адаптер автоматически обрабатывает входящие вебхуки от мессенджера Telegram, преобразует их в унифицированный формат фреймворка и формирует ответ, совместимый с требованиями платформы. Подключается одной строкой и не мешает работе других адаптеров (например, для Алисы или Маруси).

Поддерживает:

текстовые запросы, callback-кнопки, inline-запросы;
карточки, кнопки;

Подключается как любой другой адаптер: bot.use(new TelegramAdapter(token)). Несколько адаптеров могут работать одновременно — система сама выберет подходящий на основе заголовков и структуры входящего запроса.

Example

// Простейший бот для Telegram, который отвечает на приветствие
import { Bot } from 'umbot';
import { TelegramAdapter } from 'umbot/plugins';

const bot = new Bot()
    .use(new TelegramAdapter('YOUR_BOT_TOKEN'))
    .addCommand('start', ['привет'], (_text, ctx) => {
        ctx.text = 'Привет! Я твой первый бот для Telegram';
    });

bot.start('localhost', 3000);

See

Bot
BotController
BasePlatform

Hierarchy (View Summary)

BasePlatformAdapter<string | ITelegramContent>
- TelegramAdapter

Constructors

constructor

new TelegramAdapter(
platformToken?: string,
additionalPlatformOptions?: IAdapterOptions,
): TelegramAdapter
Конструктор базового адаптера платформы.
Parameters
- OptionalplatformToken: string
  Токен платформы (опционально)
- OptionaladditionalPlatformOptions: IAdapterOptions
  Дополнительные опции платформы (опционально)
Returns TelegramAdapter
Inherited from BasePlatformAdapter.constructor
- Defined in plugins/platforms/Base/Base.ts:124

Properties

`Protected` `Optional`_platformOptions

_platformOptions?: IAdapterOptions

`Protected` `Optional`_token

_token?: string

`Optional`appContext

appContext?: AppContext<unknown, string | ITelegramContent>

Контекст приложения

isVoice

isVoice: boolean = false

Telegram — чат-платформа (не голосовая).

limit

limit: number = 30

Лимит запросов/сек для входящего rateLimiter (лимит Telegram Bot API).

`Protected`MAX_TIME_REQUEST

MAX_TIME_REQUEST: number = 2900

Максимальное время обработки запроса в миллисекундах: при его превышении в лог записывается ошибка (ответ платформе при этом не модифицируется)

platformName

platformName: string = T_TELEGRAM

Идентификатор платформы Telegram.

signatureName

signatureName: string = 'x-telegram-bot-api-secret-token'

Имя поля в заголовке запроса, по которому можно проверить корректность полученного запроса от платформы.

supportedEvents

supportedEvents: readonly TEventType[] = ...

Универсальные события, выставляемые адаптером Telegram (для валидации addEvent).

`Protected`WARNING_TIME_REQUEST

WARNING_TIME_REQUEST: number = 2000

Порог предупреждения в миллисекундах: при его превышении в лог записывается warning

Methods

`Protected`_initTTS

_initTTS(controller: BotController): void | Promise<void>
Protected
Инициализирует TTS (Text-to-Speech) в контроллере. Обрабатывает звуки и стандартные звуковые эффекты
Parameters
- controller: BotController
  Контроллер приложения
Returns void | Promise<void>
Inherited from BasePlatformAdapter._initTTS
- Defined in plugins/platforms/Base/Base.ts:466

`Protected`_timeLimitLog

_timeLimitLog(controller: BotController): void
При превышении допустимого времени обработки запроса логирует информацию. Вызывается вручную в конце getContent() голосовых адаптеров (Alisa, Marusia, SmartApp); адаптеры чат-платформ его не вызывают.
- >= WARNING_TIME_REQUEST (по умолчанию 2000 мс) — warning в лог.
- >= MAX_TIME_REQUEST (по умолчанию 2900 мс) — текст ошибки пишется в controller.platformOptions.error (не в лог).
Пороги вынесены в protected поля — при необходимости переопределите в потомке.
Parameters
- controller: BotController
Returns void
Inherited from BasePlatformAdapter._timeLimitLog
- Defined in plugins/platforms/Base/Base.ts:440

createApi

createApi(controller: BotController): IControllerApi | null
API-фасад Telegram для controller.api (отправка медиа, ответ на callback-кнопку). Подключается ядром через контракт IPlatformAdapter.
Parameters
- controller: BotController
  Контроллер текущего запроса
Returns IControllerApi | null
Overrides BasePlatformAdapter.createApi
- Defined in plugins/platforms/Telegram/Adapter.ts:110

destroy

destroy(_bot: Bot): void | Promise<void>
Метод, который вызывается при уничтожении плагина. В данном методе можно добавить отписку, либо выполнить другие действия.
Parameters
- _bot: Bot
  Основной класс приложения
Returns void | Promise<void>
Inherited from BasePlatformAdapter.destroy
- Defined in plugins/Base.ts:21

getContent

getContent(controller: BotController): Promise<string | Record<string, unknown>>
Формирует и отправляет ответ Telegram: текст, карточки (media group), звуки, кнопки; при необходимости — inline-ответ или webhook-reply.
Parameters
- controller: BotController
  Контроллер приложения
Returns Promise<string | Record<string, unknown>>
Тело ответа для webhook ('ok' либо конверт webhook-reply)
Overrides BasePlatformAdapter.getContent
- Defined in plugins/platforms/Telegram/Adapter.ts:585

getLocalStorage

getLocalStorage<TStorageResult = unknown>(
_controller: BotController,
): TStorageResult | Promise<TStorageResult>
Получает данные из локального хранилища платформы.
Type Parameters
- TStorageResult = unknown
Parameters
- _controller: BotController
  контроллер приложения
Returns TStorageResult | Promise<TStorageResult>
данные, сохранённые ранее
Inherited from BasePlatformAdapter.getLocalStorage
- Defined in plugins/platforms/Base/Base.ts:498

getProcessingTime

getProcessingTime(controller: BotController): number
Получает время выполнения запроса в миллисекундах
Parameters
- controller: BotController
Returns number
Время выполнения запроса
Inherited from BasePlatformAdapter.getProcessingTime
- Defined in plugins/platforms/Base/Base.ts:426

getQueryExample

getQueryExample(
    query: string,
    userId: string,
    count: number,
): Record<string, unknown>
Формирует пример webhook-запроса Telegram для локального тестирования (BotTest).
Parameters
- query: string
  Текст команды пользователя
- userId: string
  Идентификатор пользователя (chat.id)
- count: number
  Номер сообщения (подставляется в update_id и message_id)
Returns Record<string, unknown>
Заготовка update-запроса в формате webhook Telegram
Overrides BasePlatformAdapter.getQueryExample
- Defined in plugins/platforms/Telegram/Adapter.ts:681

getRatingContext

getRatingContext(controller: BotController): TContent
Формирует ответ на запрос оценки (по умолчанию — обычный ответ getContent; спец-формат — например, SmartApp).
Parameters
- controller: BotController
  контроллер приложения
Returns TContent
Inherited from BasePlatformAdapter.getRatingContext
- Defined in plugins/platforms/Base/Base.ts:364

init

init(appContext: AppContext): void
Инициализирует адаптер: вызывает базовую инициализацию и пробрасывает переданный в конструкторе токен в конфигурацию платформы.
Parameters
- appContext: AppContext
  Контекст приложения (конфиги, токены, логгер)
Returns void
Overrides BasePlatformAdapter.init
- Defined in plugins/platforms/Telegram/Adapter.ts:119

isCorrectQuery

isCorrectQuery(
query: string | ITelegramContent,
headers?: Record<string, unknown>,
): boolean
Проверка webhook-запроса от Telegram.

Telegram шлёт webhook secret как обычную строку в заголовке x-telegram-bot-api-secret-token. Этот secret НЕ совпадает с bot token — он задаётся отдельно при вызове setWebhook(..., {secret_token: 'your-secret'}).

Поэтому для проверки используется отдельное поле appConfig.tokens.telegram.webhookSecret. Если оно не задано — проверка пропускается (обратная совместимость и webhook без secret).
Parameters
- query: string | ITelegramContent
  Тело запроса
- Optionalheaders: Record<string, unknown>
  HTTP-заголовки запроса
Returns boolean
true, если подпись совпадает (или проверка не настроена), иначе false
Overrides BasePlatformAdapter.isCorrectQuery
- Defined in plugins/platforms/Telegram/Adapter.ts:166

isLocalStorage

isLocalStorage(_controller: BotController): boolean
Указывает, поддерживает ли платформа локальное хранилище.
Parameters
- _controller: BotController
  контроллер приложения
Returns boolean
true, если локальное хранилище доступно
Inherited from BasePlatformAdapter.isLocalStorage
- Defined in plugins/platforms/Base/Base.ts:488

isPlatformOnQuery

isPlatformOnQuery(
query: ITelegramContent,
headers?: Record<string, unknown>,
): boolean
Проверяет, что входящий webhook-запрос принадлежит Telegram. Опознаёт запрос по подписи x-telegram-bot-api-secret-token или по наличию числового update_id.
Parameters
- query: ITelegramContent
  Входящий webhook-запрос (update)
- Optionalheaders: Record<string, unknown>
  Заголовки HTTP-запроса (проверяется подпись webhook)
Returns boolean
true, если запрос относится к платформе Telegram
Overrides BasePlatformAdapter.isPlatformOnQuery
- Defined in plugins/platforms/Telegram/Adapter.ts:137

isSignatureCheckEnabled

isSignatureCheckEnabled(): boolean
Telegram проверяет именно webhookSecret, а не токен бота: токен в конструкторе не включает проверку подписи.

Returns boolean
Overrides BasePlatformAdapter.isSignatureCheckEnabled
- Defined in plugins/platforms/Telegram/Adapter.ts:194

send

send(
userId: string | number,
controllerOrText: string | BotController<IUserData, IPlatformData>,
): boolean | TContent
Отправка текста пользователю Этот метод используется для активных рассылок — когда голосовой навык или чат-бот инициирует диалог первым (например, уведомление). В методе реализована механика преобразования текстового значения controllerOrText в контроллер, а также базовый механизм для отправки ответа.

Переопределять данный метод не рекомендуется. Переопределить стоит только в том случае, если по каким-то технических условиям текущая реализация метода вам не подходит.

Если платформа не поддерживает возможность начать диалог самостоятельно, то можно оставить метод пустым, либо вывести любую заглушку.
Parameters
- userId: string | number
  Ид пользователя, которому нужно отправить сообщение
- controllerOrText: string | BotController<IUserData, IPlatformData>
  Контроллер приложения или текст. Если необходимо отправить просто текст, можно передать строку, в случае, если необходимо передать картинку звук и тд, то необходимо корректно заполнить контроллер.
Returns boolean | TContent
Результат getContent() — ответ в формате платформы (TContent), либо boolean для платформ без рассылки
Example
```
// Отправка простого текста
adapter.send('user123', 'Привет!');

// Отправка через контроллер (текст + кнопки/карточки)
const controller = new BaseBotController(appContext);
controller.text = 'Уведомление';
adapter.send('user123', controller);
```
Inherited from BasePlatformAdapter.send
- Defined in plugins/platforms/Base/Base.ts:391

setLocalStorage

setLocalStorage<TStorageData>(
_data: TStorageData,
_controller: BotController,
): void | Promise<void>
Сохраняет данные в локальное хранилище платформы.
Type Parameters
- TStorageData
Parameters
- _data: TStorageData
  данные для сохранения
- _controller: BotController
  контроллер приложения
Returns void | Promise<void>
Inherited from BasePlatformAdapter.setLocalStorage
- Defined in plugins/platforms/Base/Base.ts:510

setQueryData

setQueryData(
query: ITelegramContent,
controller: BotController,
): Promise<boolean>
Разбирает update Telegram и наполняет контроллер данными: сообщение, callback-запрос, пост канала, редактирование, inline-запрос и т.д.
Parameters
- query: ITelegramContent
  Входящий webhook-запрос (update)
- controller: BotController
  Контроллер приложения
Returns Promise<boolean>
true, если запрос успешно разобран
Overrides BasePlatformAdapter.setQueryData
- Defined in plugins/platforms/Telegram/Adapter.ts:326

soundProcessing

soundProcessing(_controller: BotController): void | Promise<void>
Дополнительная обработка для звуков. В данном методе стоит реализовать логику, с помощью которой будут наложены дополнительные эффекты для озвучивания текста пользователю
Parameters
- _controller: BotController
  Контроллер бота
Returns void | Promise<void>
Inherited from BasePlatformAdapter.soundProcessing
- Defined in plugins/platforms/Base/Base.ts:456

updateTimeStart

updateTimeStart(controller: BotController): void
Публичная точка входа для сброса времени начала обработки запроса. Вызывайте перед началом бизнес-логики, чтобы метрики (см. getProcessingTime) считались отсюда.
Parameters
- controller: BotController
Returns void
Inherited from BasePlatformAdapter.updateTimeStart
- Defined in plugins/platforms/Base/Base.ts:418

`Static`isVoice

isVoice(): boolean
Метод-флаг: указывает, что платформа голосовая (например, Алиса, Маруся).

Returns boolean
Overrides BasePlatformAdapter.isVoice
- Defined in plugins/platforms/Telegram/Adapter.ts:670

Class TelegramAdapter

Example

See

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns TelegramAdapter

Properties

Protected Optional_platformOptions

Protected Optional_token

OptionalappContext

isVoice

limit

ProtectedMAX_TIME_REQUEST

platformName

signatureName

supportedEvents

ProtectedWARNING_TIME_REQUEST

Methods

Protected_initTTS

Parameters

Returns void | Promise<void>

Protected_timeLimitLog

Parameters

Returns void

createApi

Parameters

Returns IControllerApi | null

destroy

Parameters

Returns void | Promise<void>

getContent

Parameters

Returns Promise<string | Record<string, unknown>>

getLocalStorage

Type Parameters

Parameters

Returns TStorageResult | Promise<TStorageResult>

getProcessingTime

Parameters

Returns number

getQueryExample

Parameters

Returns Record<string, unknown>

getRatingContext

Parameters

Returns TContent

init

Parameters

Returns void

isCorrectQuery

Parameters

Returns boolean

isLocalStorage

Parameters

Returns boolean

isPlatformOnQuery

Parameters

Returns boolean

isSignatureCheckEnabled

Returns boolean

send

Parameters

Returns boolean | TContent

Example

setLocalStorage

Type Parameters

Parameters

Returns void | Promise<void>

setQueryData

Parameters

Returns Promise<boolean>

soundProcessing

Parameters

Returns void | Promise<void>

`Protected` `Optional`_platformOptions

`Protected` `Optional`_token

`Optional`appContext

`Protected`MAX_TIME_REQUEST

`Protected`WARNING_TIME_REQUEST

`Protected`_initTTS

`Protected`_timeLimitLog

`Static`isVoice