Class TelegramAdapter

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

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

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

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

голосовые и текстовые запросы;
карточки, кнопки;

Подключается как любой другой адаптер: 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:94

Properties

`Protected` `Optional`_platformOptions

_platformOptions?: IAdapterOptions

`Protected` `Optional`_token

_token?: string

`Optional`appContext

appContext?: AppContext<unknown, string | ITelegramContent>

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

isVoice

isVoice: boolean = false

Определяет тип платформы(голосовая или чат-бот)

limit

limit: number = 30

Определяет лимит платформы. В значение указывается количество запросов, которое можно отправить платформе за 1 секунду. В случае если у платформы нет ограничений, можно указать 0 или null. По умолчанию null

`Protected`MAX_TIME_REQUEST

MAX_TIME_REQUEST: number = 2900

Максимальное время ответа навыка в миллисекундах при превышении этого времени, будет отправлена ошибка

platformName

platformName: string = T_TELEGRAM

Имя платформы

signatureName

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

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

`Protected`WARMING_TIME_REQUEST

WARMING_TIME_REQUEST: number = 2000

Время ответа навыка в миллисекундах при превышении этого времени, будет отправлено предупреждение

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:311

`Protected`_timeLimitLog

_timeLimitLog(controller: BotController): void
При превышении установленного времени исполнения, пишет информацию в лог После вызова getContent() автоматически проверяется время выполнения. Если оно превышает 2000 мс — пишется warning, если >2900 мс — ошибка.
Parameters
- controller: BotController
Returns void
Inherited from BasePlatformAdapter._timeLimitLog
- Defined in plugins/platforms/Base/Base.ts:285

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>
Формирует тело ответа для отправки пользователю.

Возвращает платформо-специфичный ответ (например, JSON для Алисы). Для платформ, которые отправляют ответ напрямую (например, Telegram через sendMessage), метод может возвращать { ok: true } или аналог.
Parameters
- controller: BotController
  контроллер с готовым ответом
Returns Promise<string>
ответ в формате, понятном платформе
Overrides BasePlatformAdapter.getContent
- Defined in plugins/platforms/Telegram/Adapter.ts:154

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:334

getProcessingTime

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

getQueryExample

getQueryExample(
    query: string,
    userId: string,
    count: number,
): Record<string, unknown>
Генерирует пример входящего запроса для локального тестирования вашего приложения. Позволяет эмулировать запрос от платформы с заданным текстом, ID пользователя, номером сообщения и состоянием. Необходимо указывать для того, чтобы можно было корректно проверить работоспособность приложения.

Обязательно определите метод, если планируется тестирования приложения через инструменты предоставляемые платформой. Это существенно упростит процесс разработки приложения.
Parameters
- query: string
  Запрос пользователя
- userId: string
  Идентификатор пользователя
- count: number
  Порядковый номер запроса
Returns Record<string, unknown>
Overrides BasePlatformAdapter.getQueryExample
- Defined in plugins/platforms/Telegram/Adapter.ts:201

getRatingContext

getRatingContext(controller: BotController): TContent
Формирует ответ с оценкой
Parameters
- controller: BotController
  контроллер приложения
Returns TContent
Inherited from BasePlatformAdapter.getRatingContext
- Defined in plugins/platforms/Base/Base.ts:227

init

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

isCorrectQuery

isCorrectQuery(
query: string | ITelegramContent,
headers?: Record<string, unknown>,
): boolean
Проверяет полученный запрос от платформы на корректность. Из коробки проверка идет по sha256. Если по какой-то причине поведение по умолчанию не подходит, то просто переопределите метод.
Parameters
- query: string | ITelegramContent
- Optionalheaders: Record<string, unknown>
Returns boolean
Inherited from BasePlatformAdapter.isCorrectQuery
- Defined in plugins/platforms/Base/Base.ts:165

isLocalStorage

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

isPlatformOnQuery

isPlatformOnQuery(
query: ITelegramContent,
headers?: Record<string, unknown>,
): boolean
Возвращает признак того, соответствует ли запрос текущей платформе или нет
Parameters
- query: ITelegramContent
  Запрос, который пришел в приложение
- Optionalheaders: Record<string, unknown>
  Заголовок с которым был отправлен запрос
Returns boolean
true, если запрос относится к этой платформе, иначе false
Example: Telegram
```
isPlatformOnQuery(query, headers) {
  return headers?.['x-telegram-bot-api-secret-token'] === this._token;
}
```
Example: Алиса (тело содержит "meta.session_id")
```
isPlatformOnQuery(query) {
  return typeof query === 'object' && query.meta?.session_id;
}
```
Overrides BasePlatformAdapter.isPlatformOnQuery
- Defined in plugins/platforms/Telegram/Adapter.ts:63

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
Inherited from BasePlatformAdapter.send
- Defined in plugins/platforms/Base/Base.ts:242

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:346

setQueryData

setQueryData(
query: ITelegramContent,
controller: BotController,
): Promise<boolean>
Обрабатывает входящий запрос и заполняет контроллер данными.

Обязательно установите:
- controller.userCommand и controller.originalUserCommand — текст сообщения пользователя
- controller.userId — уникальный ID пользователя
- controller.appType = this.platformName
Опционально:
- controller.userToken — если платформа присылает токен авторизации
- controller.userMeta — если платформа присылает метаданные
- controller.state — если платформа поддерживает локальное хранилище
- controller.nlu — если платформа присылает NLU/интенты (через controller.nlu.setNlu(...))
Parameters
- query: ITelegramContent
  Запрос от платформы
- controller: BotController
  Контроллер приложения
Returns Promise<boolean>
false, если запрос повреждён или не может быть обработан; иначе true
Overrides BasePlatformAdapter.setQueryData
- Defined in plugins/platforms/Telegram/Adapter.ts:109

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:301

updateTimeStart

updateTimeStart(controller: BotController): void
Устанавливает время начала обработки запроса. Используется для измерения времени выполнения
Parameters
- controller: BotController
Returns void
Inherited from BasePlatformAdapter.updateTimeStart
- Defined in plugins/platforms/Base/Base.ts:268

`Static`isVoice

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

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

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

ProtectedWARMING_TIME_REQUEST

Methods

Protected_initTTS

Parameters

Returns void | Promise<void>

Protected_timeLimitLog

Parameters

Returns void

destroy

Parameters

Returns void | Promise<void>

getContent

Parameters

Returns Promise<string>

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

Example: Telegram

Example: Алиса (тело содержит "meta.session_id")

send

Parameters

Returns boolean | TContent

setLocalStorage

Type Parameters

Parameters

Returns void | Promise<void>

setQueryData

Parameters

Returns Promise<boolean>

soundProcessing

Parameters

Returns void | Promise<void>

updateTimeStart

Parameters

Returns void

StaticisVoice

Returns boolean

`Protected` `Optional`_platformOptions

`Protected` `Optional`_token

`Optional`appContext

`Protected`MAX_TIME_REQUEST

`Protected`WARMING_TIME_REQUEST

`Protected`_initTTS

`Protected`_timeLimitLog

`Static`isVoice