rzaripov.kz

Интеграция Telegram Bot API в Delphi-приложение

Telegram давно используется не только для личной переписки, но и как удобный канал уведомлений, поддержки и управления внутренними системами. С помощью Bot API приложение на Delphi может отправлять сообщения, принимать команды, передавать документы и реагировать на действия пользователей.

Для FireMonkey-проектов это особенно удобно: один программный модуль можно собрать под Windows, macOS, Linux, Android и iOS, сохранив общую логику работы с Telegram. Платформа предоставляет обычный HTTPS-интерфейс, поэтому интеграция не требует установки отдельного сервера или специального SDK.

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

Подход Как работает Когда подходит Основное ограничение
Long polling Приложение периодически запрашивает новые обновления Desktop-утилиты, локальные сервисы, прототипы Требуется постоянный запущенный процесс
Webhook Telegram отправляет события на HTTPS-адрес Серверные приложения и веб-сервисы Нужен публичный домен и SSL
Отправка сообщений Приложение вызывает sendMessage и другие методы Уведомления, отчёты, автоматизация Не принимает входящие команды сама по себе
Библиотека-обёртка Готовый компонент скрывает детали HTTP и JSON Быстрая разработка типовых решений Зависимость от качества и актуальности библиотеки

Подготовка бота и Delphi-проекта

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

В Delphi удобно использовать System.Net.HttpClient, доступный в современных версиях RAD Studio. Он поддерживает HTTPS и подходит для общих модулей FireMonkey. Для работы с JSON применяются классы из System.JSON, а для потоков и передачи файлов — TMemoryStream, TStringStream и соответствующие HTTP-компоненты.

Базовый адрес Telegram выглядит так:

https://api.telegram.org/bot<ТОКЕН>/<МЕТОД>

Например, для проверки соединения вызывается метод getMe. Для отправки сообщения используется sendMessage, которому передаются идентификатор чата и текст. В реальном проекте токен лучше загружать из зашифрованного файла конфигурации, переменной окружения или защищённого хранилища операционной системы.

Отправка сообщений через HTTPS

Простейшая функция может принимать идентификатор чата и текст сообщения, формировать JSON-объект и выполнять POST-запрос. Для этого важно указать заголовок Content-Type: application/json. Ответ Telegram содержит поле ok, а при ошибке — код и описание причины.

uses
  System.SysUtils, System.Classes, System.JSON,
  System.Net.HttpClient, System.Net.URLClient;

function SendTelegramMessage(const Token, ChatId, Text: string): Boolean;
var
  Client: THTTPClient;
  Body: TStringStream;
  Json: TJSONObject;
  Response: IHTTPResponse;
begin
  Client := THTTPClient.Create;
  try
    Json := TJSONObject.Create;
    try
      Json.AddPair('chat_id', ChatId);
      Json.AddPair('text', Text);

      Body := TStringStream.Create(
        Json.ToJSON, TEncoding.UTF8);
      try
        Response := Client.Post(
          Format('https://api.telegram.org/bot%s/sendMessage',
            [Token]), Body,
          nil,
          [TNameValuePair.Create('Content-Type',
            'application/json')]);

        Result := Response.StatusCode = 200;
      finally
        Body.Free;
      end;
    finally
      Json.Free;
    end;
  finally
    Client.Free;
  end;
end;

В прикладном коде желательно возвращать не только Boolean, но и диагностическую информацию: HTTP-код, описание ошибки, идентификатор запроса. Это помогает различать неверный токен, неизвестный чат, превышение лимита частоты и временную недоступность сети.

Telegram поддерживает параметры форматирования parse_mode со значениями MarkdownV2 или HTML. При этом специальные символы необходимо экранировать. Если текст формируется из пользовательских данных, безопаснее использовать обычный режим без разметки либо выполнять корректное экранирование перед отправкой.

Получение команд через Long Polling

Для локального Delphi-приложения чаще всего подходит Long Polling. Метод getUpdates возвращает события, которые накопились после предыдущего запроса. Параметр offset позволяет подтвердить обработанные обновления и избежать повторного выполнения команд.

Рабочий цикл обычно выполняется в отдельном потоке. В каждом запросе указываются timeout, например 30 секунд, и текущий offset. После получения ответа приложение перебирает массив result, извлекает объект message, проверяет наличие текста и выполняет нужную команду.

function GetUpdates(const Token: string; Offset: Int64): string;
var
  Client: THTTPClient;
  Url: string;
begin
  Client := THTTPClient.Create;
  try
    Url := Format(
      'https://api.telegram.org/bot%s/getUpdates' +
      '?timeout=30&offset=%d',
      [Token, Offset]);

    Result := Client.Get(Url).ContentAsString;
  finally
    Client.Free;
  end;
end;

После успешной обработки события новое значение смещения получают как update_id + 1. Запросы нельзя выполнять в главном потоке FireMonkey: длительное ожидание ответа заморозит интерфейс. Сетевой поток должен передавать результат в UI через TThread.Queue или TThread.Synchronize.

Если бот должен работать на сервере с публичным HTTPS-адресом, вместо Long Polling применяется webhook. Метод setWebhook регистрирует URL, на который Telegram будет отправлять POST-запросы. Такой вариант снижает задержку и подходит для PHP-сервисов или серверных приложений, однако требует сертификата, маршрутизации и защиты конечной точки.

Команды, кнопки и передача файлов

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

Для команд можно применять /start, /help, /status и собственные параметры. Telegram также поддерживает клавиатуры: ReplyKeyboardMarkup создаёт кнопки в поле ввода, а InlineKeyboardMarkup добавляет кнопки под сообщением. Нажатие inline-кнопки приходит как callback query, которую нужно обработать и подтвердить методом answerCallbackQuery.

Отправка изображений, документов и архивов выполняется через multipart/form-data. В Delphi для этого удобно использовать TMultipartFormData. В запрос добавляются поля chat_id, подпись и поток файла. Методы sendPhoto, sendDocument и sendAudio принимают как локальное содержимое, так и file_id, полученный от Telegram ранее.

При работе с медиа стоит учитывать размер файлов, время загрузки и временные файлы. Для мобильного приложения полезно показывать состояние операции и разрешать отмену передачи. Долгие действия лучше выполнять асинхронно, чтобы пользовательский интерфейс оставался отзывчивым.

Безопасность и обработка ошибок

Токен бота не должен попадать в исходный код, если приложение распространяется среди клиентов. Для Windows и macOS можно использовать защищённое хранилище, а в серверных проектах — переменные окружения или секреты системы развёртывания. Если токен стал известен третьим лицам, его необходимо немедленно заменить через инструмент управления ботом.

Telegram ограничивает частоту запросов. При получении ответа 429 приложение должно прочитать параметр retry_after и повторить операцию через указанное количество секунд. При кодах 400 и 403 чаще всего требуется проверить параметры запроса, права бота и доступность чата. Ошибки сети следует обрабатывать отдельно от ответов API.

Надёжный клиент использует тайм-ауты подключения и чтения, ограничивает количество повторных попыток и записывает технические сведения без конфиденциальных данных. Для Long Polling важно корректно завершать поток при закрытии приложения, освобождать HTTP-клиент и сохранять последний обработанный offset, если потеря событий недопустима.

В кроссплатформенном Delphi-проекте полезно вынести Telegram-клиент в отдельный модуль с интерфейсом вроде ISender или ITelegramGateway. Тогда платформенные окна, фоновые службы и серверные обработчики обращаются к единому набору методов. Такой подход упрощает тестирование, замену транспорта и поддержку приложений для Windows, Linux, Android и других целевых систем.