umbot
Version:
Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф
260 lines (259 loc) • 12.6 kB
TypeScript
import { ITelegramMedia, ITelegramParams, ITelegramResult, TTelegramChatId } from '../Telegram/interfaces/ITelegramPlatform';
import { AppContext } from '../../../index';
/**
* Класс для взаимодействия с API Telegram
* Предоставляет методы для отправки сообщений, файлов и других типов контента
* @see (https://core.telegram.org/bots/api) Смотри тут
*
* @example
* ```ts
* import { TelegramRequest } from './api/TelegramRequest';
*
* // Создание экземпляра
* const telegram = new TelegramRequest();
* telegram.initToken('your-bot-token');
*
* // Отправка простого сообщения
* await telegram.sendMessage(12345, 'Привет!');
*
* // Отправка форматированного сообщения
* await telegram.sendMessage(12345,
* '*Жирный текст* и _курсив_\n' +
* '[Ссылка](http://localhost)\n' +
* '`code` и ```pre```',
* { parse_mode: 'Markdown' }
* );
*
* // Отправка сообщения с клавиатурой
* const keyboard = {
* keyboard: [[
* { text: 'Кнопка 1' },
* { text: 'Кнопка 2' }
* ]],
* resize_keyboard: true,
* one_time_keyboard: true
* };
*
* await telegram.sendMessage(12345, 'Выберите:', {
* reply_markup: JSON.stringify(keyboard)
* });
*
* // Отправка файлов
* await telegram.sendPhoto(12345, 'photo.jpg', 'Описание фото');
* await telegram.sendDocument(12345, 'document.pdf');
* await telegram.sendAudio(12345, 'audio.mp3', {
* title: 'Название',
* performer: 'Исполнитель'
* });
* ```
*/
export declare class TelegramRequest {
#private;
/**
* Токен доступа к Telegram API
*/
token: string | null;
/**
* Создает экземпляр класса для работы с API Telegram
* Устанавливает токен из конфигурации приложения, если он доступен
*/
constructor(appContext: AppContext);
/**
* Инициализирует токен доступа к Telegram API
* @param token Токен для доступа к API
*/
initToken(token: string | null): void;
/**
* Формирует URL для отправки запроса
* @returns Полный URL для API запроса
*
*/
protected _getUrl(): string;
/**
* Отправляет запрос к Telegram API
* @param method Название метода API
* @param userId ID пользователя или чата
* @returns Результат выполнения метода или null при ошибке
*/
call(method: string, userId?: TTelegramChatId | null): Promise<ITelegramResult | null>;
/**
* Отправляет текстовое сообщение
* @param chatId ID чата или пользователя
* @param message Текст сообщения
* @param params Дополнительные параметры:
* - parse_mode: формат текста
* - Markdown: *жирный*, _курсив_, [ссылка](http://localhost), `код`, ```pre```
* - HTML: <b>жирный</b>, <i>курсив</i>, <a href="http://localhost">ссылка</a>, <code>код</code>, <pre>pre</pre>
* - disable_web_page_preview: отключить предпросмотр ссылок
* - disable_notification: отключить уведомление
* - reply_to_message_id: ID сообщения для ответа
* - reply_markup: клавиатура в JSON формате
* - keyboard: обычная клавиатура
* - inline_keyboard: встроенная клавиатура
* - remove_keyboard: удалить клавиатуру
* - force_reply: форсировать ответ
*
* @example
* ```ts
* // Простое сообщение
* await telegram.sendMessage(12345, 'Привет!');
*
* // Форматированное сообщение
* await telegram.sendMessage(12345,
* '<b>Жирный</b> и <i>курсив</i>\n' +
* '<a href="http://localhost">Ссылка</a>\n' +
* '<code>code</code>',
* { parse_mode: 'HTML' }
* );
*
* // Сообщение с обычной клавиатурой
* const keyboard = {
* keyboard: [[
* { text: 'Кнопка 1' },
* { text: 'Кнопка 2' }
* ]],
* resize_keyboard: true
* };
* await telegram.sendMessage(12345, 'Выберите:', {
* reply_markup: JSON.stringify(keyboard)
* });
*
* // Сообщение с inline-клавиатурой
* const inlineKeyboard = {
* inline_keyboard: [[{
* text: 'Кнопка',
* callback_data: 'button_1'
* }]]
* };
* await telegram.sendMessage(12345, 'Нажмите:', {
* reply_markup: JSON.stringify(inlineKeyboard)
* });
* ```
*
* @returns Информация об отправленном сообщении или null при ошибке
*/
sendMessage(chatId: TTelegramChatId, message: string, params?: ITelegramParams | null): Promise<ITelegramResult | null>;
/**
* Отправляет опрос
* @param chatId ID чата или пользователя
* @param question Текст вопроса
* @param options Массив вариантов ответов (2-10 вариантов)
* @param params Дополнительные параметры:
* - is_anonymous: анонимный опрос (по умолчанию true)
* - type: тип опроса
* - 'regular': обычный опрос (по умолчанию)
* - 'quiz': викторина с одним правильным ответом
* - allows_multiple_answers: разрешить несколько ответов (только для regular)
* - correct_option_id: ID правильного ответа (0-9, только для quiz)
* - explanation: пояснение правильного ответа (только для quiz)
* - explanation_parse_mode: формат пояснения (HTML/Markdown)
* - open_period: время в секундах, когда опрос активен
* - close_date: дата закрытия опроса (Unix timestamp)
* - is_closed: закрыть опрос сразу
*
* @example
* ```ts
* // Обычный опрос
* await telegram.sendPoll(12345,
* 'Любимый цвет?',
* ['Красный', 'Синий', 'Зеленый'],
* { allows_multiple_answers: true }
* );
*
* // Викторина
* await telegram.sendPoll(12345,
* 'Столица России?',
* ['Санкт-Петербург', 'Москва', 'Новосибирск'],
* {
* type: 'quiz',
* correct_option_id: 1,
* explanation: 'Москва - столица России с 1918 года',
* explanation_parse_mode: 'HTML'
* }
* );
* ```
*
* @returns Информация об отправленном опросе или null при ошибке
*/
sendPoll(chatId: TTelegramChatId, question: string, options: string[], params?: ITelegramParams | null): Promise<ITelegramResult | null> | null;
/**
* Отвечает на callback-запрос от инлайн-кнопки.
* @param callbackQueryId - ID запроса из поля callback_query.id
* @param text - Текст уведомления (показывается всплывающим окном)
* @param showAlert - Показывать как alert (true) или всплывающее уведомление (false)
* @param url - URL для открытия после нажатия
* @param cacheTime - Время кэширования ответа (сек)
*/
answerCallbackQuery(callbackQueryId: string, text?: string, showAlert?: boolean, url?: string, cacheTime?: number): Promise<ITelegramResult | null>;
/**
* Отправляет фотографию
* @param userId ID чата или пользователя
* @param file Путь к файлу или его содержимое
* Поддерживаемые форматы:
* - JPEG, JPG, PNG, GIF, WEBP
* - Максимальный размер: 10MB
* - Максимальное разрешение: 10000x10000
* @param desc Подпись к фотографии
* @param params Дополнительные параметры:
* - caption: подпись к фото (0-1024 символа)
* - caption: подпись к фото
* - parse_mode: формат текста
* - disable_notification: отключить уведомление
* - reply_to_message_id: ID сообщения для ответа
* - reply_markup: клавиатура в JSON
* @returns Информация об отправленной фотографии или null при ошибке
*/
sendPhoto(userId: TTelegramChatId, file: string, desc?: string | null, params?: ITelegramParams | null): Promise<ITelegramResult | null>;
/**
* Отправляет документ
* @param userId ID чата или пользователя
* @param file Путь к файлу или его содержимое
* @param params Дополнительные параметры:
* - caption: подпись к документу
* - parse_mode: формат текста
* - disable_notification: отключить уведомление
* - reply_to_message_id: ID сообщения для ответа
* - reply_markup: клавиатура в JSON
* @returns Информация об отправленном документе или null при ошибке
*/
sendDocument(userId: TTelegramChatId, file: string, params?: ITelegramParams | null): Promise<ITelegramResult | null>;
/**
* Отправляет аудиофайл
* @param userId ID чата или пользователя
* @param file Путь к файлу или его содержимое
* @param params Дополнительные параметры:
* - caption: подпись к аудио
* - parse_mode: формат текста
* - duration: длительность в секундах
* - performer: исполнитель
* - title: название
* - disable_notification: отключить уведомление
* - reply_to_message_id: ID сообщения для ответа
* - reply_markup: клавиатура в JSON
* @returns Информация об отправленном аудио или null при ошибке
*/
sendAudio(userId: TTelegramChatId, file: string, params?: ITelegramParams | null): Promise<ITelegramResult | null>;
/**
* Отправляет видео
* @param userId ID чата или пользователя
* @param file Путь к файлу или его содержимое
* @param params Дополнительные параметры:
* - caption: подпись к видео
* - parse_mode: формат текста
* - duration: длительность в секундах
* - width: ширина
* - height: высота
* - disable_notification: отключить уведомление
* - reply_to_message_id: ID сообщения для ответа
* - reply_markup: клавиатура в JSON
* @returns Информация об отправленном видео или null при ошибке
*/
sendVideo(userId: TTelegramChatId, file: string, params?: ITelegramParams | null): Promise<ITelegramResult | null>;
/**
* Отправляет группу медиа
* @param userId ID чата или пользователя
* @param media Массив объектов ITelegramMedia
* @param params Дополнительные параметры:
*/
sendMediaGroup(userId: TTelegramChatId, media: ITelegramMedia[], params?: ITelegramParams | null): Promise<ITelegramResult | null>;
}