Add Telegram bot integration for pipeline processing (#5185)

# Description of Changes This pull request introduces Telegram bot integration to the application, enabling users to send files via Telegram for processing through the pipeline. The main changes add configuration options, dependency management, and a new service for handling Telegram interactions. **Telegram bot integration:** * Added a new `TelegramPipelineBot` service (`TelegramPipelineBot.java`) that listens for incoming Telegram messages, downloads attached files or photos, places them in a pipeline inbox folder, waits for processing results, and sends the output files back to the user. The service includes error handling and status messaging. * Introduced a `TelegramBotConfig` configuration class to initialize and register the Telegram bot only when enabled via application properties. * Added a new `Telegram` configuration section to `ApplicationProperties` and the `settings.yml.template`, supporting options like enabling/disabling the bot, bot token/username, pipeline folder, processing timeout, and polling interval. [[1]](diffhunk://#diff-1c357db0a3e88cf5bedd4a5852415fadad83b8b3b9eb56e67059d8b9d8b10702R63) [[2]](diffhunk://#diff-1c357db0a3e88cf5bedd4a5852415fadad83b8b3b9eb56e67059d8b9d8b10702R580-R589) [[3]](diffhunk://#diff-12f23603ae35319a3ea08f91b6340d5d935216941fda2e69d2df1b6cd22a63f2R108-R115) **Dependency management:** * Added the `org.telegram:telegrambots` library to the project dependencies to support Telegram bot functionality. --- ## Checklist ### General - [ ] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md) (if applicable) - [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable) - [ ] I have performed a self-review of my own code - [ ] My changes generate no new warnings ### Documentation - [ ] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) - [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### UI Changes (if applicable) - [ ] Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR) ### Testing (if applicable) - [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing) for more details. --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Anthony Stirling <[email protected]>
2026-07-14 10:34:06 +02:00 · 2026-01-13 22:14:59 +00:00
parent 83e96a9aa3
commit e7b030e6b5
13 changed files with 1313 additions and 84 deletions
@@ -61,6 +61,7 @@ public class ApplicationProperties {
    private AutomaticallyGenerated automaticallyGenerated = new AutomaticallyGenerated();

    private Mail mail = new Mail();
+    private Telegram telegram = new Telegram();

    private Premium premium = new Premium();

@@ -551,10 +552,10 @@ public class ApplicationProperties {
        @Override
        public String toString() {
            return """
-      Driver {
-        driverName='%s'
-      }
-      """
+            Driver {
+              driverName='%s'
+            }
+            """
                    .formatted(driverName);
        }
    }
@@ -607,6 +608,7 @@ public class ApplicationProperties {
        private boolean ssoAutoLogin;
        private CustomMetadata customMetadata = new CustomMetadata();

+        @Deprecated
        @Data
        public static class CustomMetadata {
            private boolean autoUpdateMetadata;
@@ -614,16 +616,23 @@ public class ApplicationProperties {
            private String creator;
            private String producer;

+            @Deprecated
            public String getCreator() {
                return creator == null || creator.trim().isEmpty() ? "Stirling-PDF" : creator;
            }

+            @Deprecated
            public String getProducer() {
                return producer == null || producer.trim().isEmpty() ? "Stirling-PDF" : producer;
            }
        }
    }

+    /**
+     * Mail server configuration properties.
+     *
+     * @since 0.46.1
+     */
    @Data
    public static class Mail {
        private boolean enabled;
@@ -646,6 +655,102 @@ public class ApplicationProperties {
        private Boolean sslCheckServerIdentity;
    }

+    /**
+     * Telegram bot configuration properties.
+     *
+     * @since 2.2.x
+     */
+    @Data
+    public static class Telegram {
+        private Boolean enabled = false;
+        @ToString.Exclude private String botToken;
+        private String botUsername;
+        private String pipelineInboxFolder = "telegram";
+        private Boolean customFolderSuffix = false;
+        private Boolean enableAllowUserIDs = false;
+        private List<Long> allowUserIDs = new ArrayList<>();
+        private Boolean enableAllowChannelIDs = false;
+        private List<Long> allowChannelIDs = new ArrayList<>();
+        private long processingTimeoutSeconds = 180;
+        private long pollingIntervalMillis = 2000;
+        private Feedback feedback = new Feedback();
+
+        /**
+         * Configuration for feedback messages sent by the Telegram bot.
+         *
+         * @since 2.2.x
+         */
+        @Data
+        public static class Feedback {
+            private Channel channel = new Channel();
+            private User user = new User();
+
+            /**
+             * Channel-specific feedback settings.
+             *
+             * @since 2.2.x
+             */
+            @Data
+            public static class Channel {
+                /**
+                 * Set to {@code false} to hide/suppress "no valid document" feedback messages to
+                 * the channel (to avoid spam).
+                 */
+                private Boolean noValidDocument = true;
+
+                /**
+                 * Set to {@code false} to hide/suppress generic error feedback messages to the
+                 * channel (to avoid spam).
+                 */
+                private Boolean errorMessage = true;
+
+                /**
+                 * Set to {@code false} to hide/suppress processing error feedback messages to the
+                 * channel (to avoid spam).
+                 */
+                private Boolean errorProcessing = true;
+
+                /**
+                 * Set to {@code false} to hide/suppress "processing" feedback messages to the
+                 * channel (to avoid spam).
+                 */
+                private Boolean processing = true;
+            }
+
+            /**
+             * User-specific feedback settings.
+             *
+             * @since 2.2.x
+             */
+            @Data
+            public static class User {
+                /**
+                 * Set to {@code false} to hide/suppress "no valid document" feedback messages to
+                 * users (to avoid spam).
+                 */
+                private Boolean noValidDocument = true;
+
+                /**
+                 * Set to {@code false} to hide/suppress generic error feedback messages to users
+                 * (to avoid spam).
+                 */
+                private Boolean errorMessage = true;
+
+                /**
+                 * Set to {@code false} to hide/suppress processing error feedback messages to users
+                 * (to avoid spam).
+                 */
+                private Boolean errorProcessing = true;
+
+                /**
+                 * Set to {@code false} to hide/suppress "processing" feedback messages to users (to
+                 * avoid spam).
+                 */
+                private Boolean processing = true;
+            }
+        }
+    }
+
    @Data
    public static class Premium {
        private boolean enabled;
@@ -59,6 +59,7 @@ dependencies {
    implementation project(':common')
    implementation 'org.springframework.boot:spring-boot-starter-jetty'
    implementation 'com.posthog.java:posthog:1.2.0'
+    implementation 'org.telegram:telegrambots:6.9.7.1'
    implementation 'commons-io:commons-io:2.21.0'
    implementation "org.bouncycastle:bcprov-jdk18on:$bouncycastleVersion"
    implementation "org.bouncycastle:bcpkix-jdk18on:$bouncycastleVersion"
@@ -0,0 +1,18 @@
+package stirling.software.SPDF.config;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.telegram.telegrambots.meta.TelegramBotsApi;
+import org.telegram.telegrambots.meta.exceptions.TelegramApiException;
+import org.telegram.telegrambots.updatesreceivers.DefaultBotSession;
+
+@Configuration
+@ConditionalOnProperty(prefix = "telegram", name = "enabled", havingValue = "true")
+public class TelegramBotConfig {
+
+    @Bean
+    public TelegramBotsApi telegramBotsApi() throws TelegramApiException {
+        return new TelegramBotsApi(DefaultBotSession.class);
+    }
+}
@@ -0,0 +1,20 @@
+package stirling.software.SPDF.service.telegram;
+
+/**
+ * Enumeration representing different feedback types for Telegram service.
+ *
+ * @since 2.2.x
+ */
+public enum FeedbackEnum {
+    /** Indicates that the provided document is not valid. */
+    NO_VALID_DOCUMENT,
+
+    /** Represents a generic error message. */
+    ERROR_MESSAGE,
+
+    /** Indicates that an error occurred during processing. */
+    ERROR_PROCESSING,
+
+    /** Indicates that processing is ongoing. */
+    PROCESSING
+}
@@ -0,0 +1,524 @@
+package stirling.software.SPDF.service.telegram;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.MalformedURLException;
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.net.URL;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Set;
+import java.util.UUID;
+import java.util.stream.Stream;
+
+import org.apache.commons.io.FilenameUtils;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.stereotype.Component;
+import org.telegram.telegrambots.bots.TelegramLongPollingBot;
+import org.telegram.telegrambots.meta.TelegramBotsApi;
+import org.telegram.telegrambots.meta.api.methods.GetFile;
+import org.telegram.telegrambots.meta.api.methods.send.SendDocument;
+import org.telegram.telegrambots.meta.api.methods.send.SendMessage;
+import org.telegram.telegrambots.meta.api.objects.Chat;
+import org.telegram.telegrambots.meta.api.objects.Document;
+import org.telegram.telegrambots.meta.api.objects.File;
+import org.telegram.telegrambots.meta.api.objects.InputFile;
+import org.telegram.telegrambots.meta.api.objects.Message;
+import org.telegram.telegrambots.meta.api.objects.Update;
+import org.telegram.telegrambots.meta.api.objects.User;
+import org.telegram.telegrambots.meta.exceptions.TelegramApiException;
+
+import jakarta.annotation.PostConstruct;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.configuration.RuntimePathConfig;
+import stirling.software.common.model.ApplicationProperties;
+
+/**
+ * Telegram bot that processes incoming files through a defined pipeline.
+ *
+ * @since 2.2.x
+ */
+@Slf4j
+@Component
+@ConditionalOnProperty(prefix = "telegram", name = "enabled", havingValue = "true")
+public class TelegramPipelineBot extends TelegramLongPollingBot {
+
+    private static final String CHAT_PRIVATE = "private";
+    private static final String CHAT_GROUP = "group";
+    private static final String CHAT_SUPERGROUP = "supergroup";
+    private static final String CHAT_CHANNEL = "channel";
+
+    private static final Set<String> SUPPORTED_CHAT_TYPES =
+            Set.of(CHAT_PRIVATE, CHAT_GROUP, CHAT_SUPERGROUP, CHAT_CHANNEL);
+
+    private static final Set<String> ALLOWED_MIME_TYPES = Set.of("application/pdf");
+
+    private final Object pipelinePollMonitor = new Object();
+
+    private final ApplicationProperties.Telegram telegramProperties;
+    private final RuntimePathConfig runtimePathConfig;
+    private final TelegramBotsApi telegramBotsApi;
+
+    public TelegramPipelineBot(
+            ApplicationProperties applicationProperties,
+            RuntimePathConfig runtimePathConfig,
+            TelegramBotsApi telegramBotsApi) {
+
+        super(applicationProperties.getTelegram().getBotToken());
+        this.telegramProperties = applicationProperties.getTelegram();
+        this.runtimePathConfig = runtimePathConfig;
+        this.telegramBotsApi = telegramBotsApi;
+    }
+
+    @PostConstruct
+    public void register() {
+        if (StringUtils.isAnyBlank(getBotUsername(), getBotToken())) {
+            log.warn("Telegram bot disabled because botToken or botUsername is not configured");
+            return;
+        }
+        try {
+            telegramBotsApi.registerBot(this);
+            log.info("Telegram pipeline bot registered as {}", getBotUsername());
+        } catch (TelegramApiException e) {
+            log.error("Failed to register Telegram bot", e);
+        }
+    }
+
+    @Override
+    public void onUpdateReceived(Update update) {
+        Message message = extractMessage(update);
+        if (message == null) {
+            return;
+        }
+
+        Chat chat = message.getChat();
+        if (chat == null || !isSupportedChatType(chat.getType())) {
+            log.info(
+                    "Ignoring message {}, unsupported chat type {}",
+                    message.getMessageId(),
+                    chat != null ? chat.getType() : "null");
+            return;
+        }
+
+        if (!isAuthorized(message, chat)) {
+            return;
+        }
+
+        if (update.hasMessage() && update.getMessage().hasText()) {
+            String messageText = update.getMessage().getText();
+            long chatId = update.getMessage().getChatId();
+            if ("/start".equals(messageText)) {
+                sendMessage(
+                        chatId,
+                        """
+                        Welcome to the SPDF Telegram Bot!
+
+                        To get started, please send me a PDF document that you would like to process.
+                        Make sure the document is in PDF format.
+
+                        Once I receive your document, I'll begin processing it through the pipeline.
+                        """);
+                return;
+            }
+        }
+
+        if (message.hasDocument()) {
+            handleIncomingFile(message);
+            return;
+        }
+        if (feedback(FeedbackEnum.NO_VALID_DOCUMENT, chat.getType())) {
+            sendMessage(
+                    chat.getId(),
+                    "No valid file found in the message. Please send a document to process.");
+        }
+    }
+
+    private boolean feedback(FeedbackEnum feedbackEnum, String chatType) {
+        return switch (feedbackEnum) {
+            case NO_VALID_DOCUMENT ->
+                    switch (chatType) {
+                        case CHAT_CHANNEL ->
+                                telegramProperties.getFeedback().getChannel().getNoValidDocument();
+                        case CHAT_PRIVATE ->
+                                telegramProperties.getFeedback().getUser().getNoValidDocument();
+                        default -> true;
+                    };
+            case ERROR_MESSAGE ->
+                    switch (chatType) {
+                        case CHAT_CHANNEL ->
+                                telegramProperties.getFeedback().getChannel().getErrorMessage();
+                        case CHAT_PRIVATE ->
+                                telegramProperties.getFeedback().getUser().getErrorMessage();
+                        default -> true;
+                    };
+            case ERROR_PROCESSING ->
+                    switch (chatType) {
+                        case CHAT_CHANNEL ->
+                                telegramProperties.getFeedback().getChannel().getErrorProcessing();
+                        case CHAT_PRIVATE ->
+                                telegramProperties.getFeedback().getUser().getErrorProcessing();
+                        default -> true;
+                    };
+            case PROCESSING ->
+                    switch (chatType) {
+                        case CHAT_CHANNEL ->
+                                telegramProperties.getFeedback().getChannel().getProcessing();
+                        case CHAT_PRIVATE ->
+                                telegramProperties.getFeedback().getUser().getProcessing();
+                        default -> true;
+                    };
+            default -> true;
+        };
+    }
+
+    // ---------------------------
+    // Message Extraction / Chat Type
+    // ---------------------------
+
+    private Message extractMessage(Update update) {
+        if (update.hasMessage()) return update.getMessage();
+        if (update.hasChannelPost()) return update.getChannelPost();
+        return null;
+    }
+
+    private boolean isSupportedChatType(String type) {
+        return type != null && SUPPORTED_CHAT_TYPES.contains(type);
+    }
+
+    // ---------------------------
+    // Authorization
+    // ---------------------------
+
+    private boolean isAuthorized(Message message, Chat chat) {
+        if (!(telegramProperties.getEnableAllowUserIDs()
+                || telegramProperties.getEnableAllowChannelIDs())) {
+            return true;
+        }
+
+        return switch (chat.getType()) {
+            case CHAT_CHANNEL -> checkChannelAccess(message, chat);
+            case CHAT_PRIVATE -> checkUserAccess(message, chat);
+            case CHAT_GROUP, CHAT_SUPERGROUP -> true; // groups allowed by default
+            default -> false;
+        };
+    }
+
+    private boolean checkUserAccess(Message message, Chat chat) {
+        if (!telegramProperties.getEnableAllowUserIDs()) return true;
+
+        User from = message.getFrom();
+        List<Long> allow = telegramProperties.getAllowUserIDs();
+
+        if (allow.isEmpty()) {
+            log.warn("No allowed user IDs configured - allowing all users.");
+            return true;
+        }
+
+        if (from == null || !allow.contains(from.getId())) {
+            log.info(
+                    "Rejecting user {} in private chat {}",
+                    from != null ? from.getId() : "unknown",
+                    chat.getId());
+            if (feedback(FeedbackEnum.ERROR_MESSAGE, chat.getType())) {
+                sendMessage(chat.getId(), "You are not authorized to use this bot.");
+            }
+            return false;
+        }
+
+        return true;
+    }
+
+    private boolean checkChannelAccess(Message message, Chat chat) {
+        if (!telegramProperties.getEnableAllowChannelIDs()) return true;
+
+        Chat senderChat = message.getSenderChat();
+        List<Long> allow = telegramProperties.getAllowChannelIDs();
+
+        if (allow.isEmpty()) {
+            log.warn("No allowed channel IDs configured - allowing all channels.");
+            return true;
+        }
+
+        if (senderChat == null || !allow.contains(senderChat.getId())) {
+            log.info(
+                    "Rejecting channel {} in chat {}",
+                    senderChat != null ? senderChat.getId() : "unknown",
+                    chat.getId());
+            if (feedback(FeedbackEnum.ERROR_MESSAGE, chat.getType())) {
+                sendMessage(chat.getId(), "This channel is not authorized to use this bot.");
+            }
+            return false;
+        }
+
+        return true;
+    }
+
+    // ---------------------------
+    // File Handling
+    // ---------------------------
+
+    private void handleIncomingFile(Message message) {
+        Long chatId = message.getChatId();
+        Document doc = message.getDocument();
+        String chatType = message.getChat().getType();
+
+        if (doc == null) {
+            if (feedback(FeedbackEnum.NO_VALID_DOCUMENT, chatType)) {
+                sendMessage(chatId, "No document found.");
+            }
+            return;
+        }
+
+        if (doc.getMimeType() != null
+                && !ALLOWED_MIME_TYPES.contains(doc.getMimeType().toLowerCase())) {
+            if (feedback(FeedbackEnum.NO_VALID_DOCUMENT, chatType)) {
+                sendMessage(
+                        chatId,
+                        "Unsupported MIME type: "
+                                + doc.getMimeType()
+                                + "\nAllowed: "
+                                + String.join(", ", ALLOWED_MIME_TYPES));
+            }
+            return;
+        }
+
+        if (!hasJsonConfig(chatId)) {
+            if (feedback(FeedbackEnum.ERROR_PROCESSING, chatType)) {
+                sendMessage(
+                        chatId,
+                        "No JSON configuration file found in the pipeline inbox folder. Please"
+                                + " contact the administrator.");
+            }
+            return;
+        }
+
+        try {
+            if (!CHAT_CHANNEL.equalsIgnoreCase(chatType)
+                    && feedback(FeedbackEnum.PROCESSING, chatType)) {
+                sendMessage(chatId, "File received. Starting processing...");
+            }
+
+            PipelineFileInfo info = downloadMessageFile(message);
+            List<Path> outputs = waitForPipelineOutputs(info);
+
+            if (outputs.isEmpty()) {
+                if (feedback(FeedbackEnum.ERROR_PROCESSING, chatType)) {
+                    sendMessage(
+                            chatId,
+                            "No results were found in the pipeline output folder. Check"
+                                    + " configuration.");
+                }
+                return;
+            }
+
+            for (Path file : outputs) {
+                SendDocument out = new SendDocument();
+                out.setChatId(chatId);
+                out.setDocument(new InputFile(file.toFile(), file.getFileName().toString()));
+                execute(out);
+            }
+
+        } catch (TelegramApiException e) {
+            log.error("Telegram API error", e);
+            if (feedback(FeedbackEnum.ERROR_MESSAGE, chatType)) {
+                sendMessage(chatId, "Telegram API error occurred.");
+            }
+        } catch (IOException e) {
+            log.error("IO error", e);
+            if (feedback(FeedbackEnum.ERROR_MESSAGE, chatType)) {
+                sendMessage(chatId, "An IO error occurred.");
+            }
+        } catch (Exception e) {
+            log.error("Unexpected error", e);
+            if (feedback(FeedbackEnum.ERROR_MESSAGE, chatType)) {
+                sendMessage(chatId, "Unexpected error occurred.");
+            }
+        }
+    }
+
+    private PipelineFileInfo downloadMessageFile(Message message)
+            throws TelegramApiException, IOException {
+        Document document = message.getDocument();
+        String filename = document.getFileName();
+        String name =
+                StringUtils.isNotBlank(filename) ? filename : document.getFileUniqueId() + ".bin";
+
+        return downloadFile(document.getFileId(), name, message);
+    }
+
+    private PipelineFileInfo downloadFile(String fileId, String originalName, Message message)
+            throws TelegramApiException, IOException {
+
+        Long chatId = message.getChatId();
+
+        Path inboxFolder = getInboxFolder(chatId);
+
+        GetFile getFile = new GetFile(fileId);
+        File tgFile = execute(getFile);
+
+        if (tgFile == null || StringUtils.isBlank(tgFile.getFilePath())) {
+            throw new IOException("Telegram did not return a file path.");
+        }
+
+        URL url = buildDownloadUrl(tgFile.getFilePath());
+
+        String base = FilenameUtils.getBaseName(originalName) + "-" + UUID.randomUUID();
+        String ext = FilenameUtils.getExtension(originalName);
+        String outFile = ext.isBlank() ? base : base + "." + ext;
+
+        Path targetFile = inboxFolder.resolve(outFile);
+
+        try (InputStream in = url.openStream()) {
+            Files.copy(in, targetFile);
+        }
+
+        log.info("Saved Telegram file {} to {}", originalName, targetFile);
+        return new PipelineFileInfo(targetFile, base, Instant.now());
+    }
+
+    private URL buildDownloadUrl(String filePath) throws MalformedURLException {
+        try {
+            URI uri =
+                    new URI(
+                            "https",
+                            "api.telegram.org",
+                            "/file/bot" + getBotToken() + "/" + filePath,
+                            null);
+            return uri.toURL();
+        } catch (URISyntaxException e) {
+            throw new MalformedURLException("Failed to build Telegram download URL");
+        } catch (MalformedURLException e) {
+            MalformedURLException sanitized =
+                    new MalformedURLException("Failed to build Telegram download URL");
+            sanitized.initCause(e);
+            throw sanitized;
+        }
+    }
+
+    // ---------------------------
+    // Inbox-Ordner & JSON-Check
+    // ---------------------------
+
+    private Path getInboxFolder(Long chatId) throws IOException {
+        Path baseInbox =
+                Paths.get(
+                        runtimePathConfig.getPipelineWatchedFoldersPath(),
+                        telegramProperties.getPipelineInboxFolder());
+
+        Files.createDirectories(baseInbox);
+
+        Path inboxFolder =
+                telegramProperties.getCustomFolderSuffix()
+                        ? baseInbox.resolve(chatId.toString())
+                        : baseInbox;
+
+        Files.createDirectories(inboxFolder);
+
+        return inboxFolder;
+    }
+
+    private boolean hasJsonConfig(Long chatId) {
+        try {
+            Path inboxFolder = getInboxFolder(chatId);
+            try (Stream<Path> s = Files.list(inboxFolder)) {
+                return s.anyMatch(p -> p.toString().endsWith(".json"));
+            }
+        } catch (IOException e) {
+            log.error("Failed to check JSON config for chat {}", chatId, e);
+            return false;
+        }
+    }
+
+    // ---------------------------
+    // Pipeline polling
+    // ---------------------------
+
+    private List<Path> waitForPipelineOutputs(PipelineFileInfo info) throws IOException {
+
+        Path finishedDir = Paths.get(runtimePathConfig.getPipelineFinishedFoldersPath());
+        Files.createDirectories(finishedDir);
+
+        Instant start = info.savedAt();
+        Duration timeout = Duration.ofSeconds(telegramProperties.getProcessingTimeoutSeconds());
+        Duration poll = Duration.ofMillis(telegramProperties.getPollingIntervalMillis());
+        List<Path> results = new ArrayList<>();
+
+        while (Duration.between(start, Instant.now()).compareTo(timeout) <= 0) {
+            try (Stream<Path> s = Files.list(finishedDir)) {
+                results =
+                        s.filter(Files::isRegularFile)
+                                .filter(path -> matchesBaseName(info.uniqueBaseName(), path))
+                                .filter(path -> isNewerThan(path, start))
+                                .sorted(Comparator.comparing(Path::toString))
+                                .toList();
+            }
+
+            if (!results.isEmpty()) {
+                break;
+            }
+
+            synchronized (pipelinePollMonitor) {
+                try {
+                    pipelinePollMonitor.wait(poll.toMillis());
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    break;
+                }
+            }
+        }
+
+        return results;
+    }
+
+    private boolean matchesBaseName(String base, Path file) {
+        return file.getFileName().toString().contains(base);
+    }
+
+    private boolean isNewerThan(Path path, Instant since) {
+        try {
+            return Files.getLastModifiedTime(path).toInstant().isAfter(since);
+        } catch (IOException e) {
+            log.info("Could not read modification time for {}", path);
+            return false;
+        }
+    }
+
+    // ---------------------------
+    // Messaging
+    // ---------------------------
+
+    private void sendMessage(Long chatId, String text) {
+        if (chatId == null) return;
+
+        SendMessage msg = new SendMessage();
+        msg.setChatId(chatId);
+        msg.setText(text);
+        try {
+            execute(msg);
+        } catch (TelegramApiException e) {
+            log.warn("Failed to send message to {}", chatId, e);
+        }
+    }
+
+    private record PipelineFileInfo(Path originalFile, String uniqueBaseName, Instant savedAt) {}
+
+    @Override
+    public String getBotUsername() {
+        return telegramProperties.getBotUsername();
+    }
+
+    @Override
+    public String getBotToken() {
+        return telegramProperties.getBotToken();
+    }
+}
@@ -16,30 +16,30 @@ security:
  loginResetTimeMinutes: 120 # lock account for 2 hours after x attempts
  loginMethod: all # Accepts values like 'all' and 'normal'(only Login with Username/Password), 'oauth2'(only Login with OAuth2) or 'saml2'(only Login with SAML2)
  initialLogin:
-    username: '' # initial username for the first login
-    password: '' # initial password for the first login
+    username: "" # initial username for the first login
+    password: "" # initial password for the first login
  oauth2:
    enabled: false # set to 'true' to enable login (Note: enableLogin must also be 'true' for this to work)
    client:
      keycloak:
-        issuer: '' # URL of the Keycloak realm's OpenID Connect Discovery endpoint
-        clientId: '' # client ID for Keycloak OAuth2
-        clientSecret: '' # client secret for Keycloak OAuth2
+        issuer: "" # URL of the Keycloak realm's OpenID Connect Discovery endpoint
+        clientId: "" # client ID for Keycloak OAuth2
+        clientSecret: "" # client secret for Keycloak OAuth2
        scopes: openid, profile, email # scopes for Keycloak OAuth2
        useAsUsername: preferred_username # field to use as the username for Keycloak OAuth2. Available options are: [email | name | given_name | family_name | preferred_name]
      google:
-        clientId: '' # client ID for Google OAuth2
-        clientSecret: '' # client secret for Google OAuth2
+        clientId: "" # client ID for Google OAuth2
+        clientSecret: "" # client secret for Google OAuth2
        scopes: email, profile # scopes for Google OAuth2
        useAsUsername: email # field to use as the username for Google OAuth2. Available options are: [email | name | given_name | family_name]
      github:
-        clientId: '' # client ID for GitHub OAuth2
-        clientSecret: '' # client secret for GitHub OAuth2
+        clientId: "" # client ID for GitHub OAuth2
+        clientSecret: "" # client secret for GitHub OAuth2
        scopes: read:user # scope for GitHub OAuth2
        useAsUsername: login # field to use as the username for GitHub OAuth2. Available options are: [email | login | name]
-    issuer: '' # set to any Provider that supports OpenID Connect Discovery (/.well-known/openid-configuration) endpoint
-    clientId: '' # client ID from your Provider
-    clientSecret: '' # client secret from your Provider
+    issuer: "" # set to any Provider that supports OpenID Connect Discovery (/.well-known/openid-configuration) endpoint
+    clientId: "" # client ID from your Provider
+    clientSecret: "" # client secret from your Provider
    autoCreateUser: true # set to 'true' to allow auto-creation of non-existing users
    blockRegistration: false # set to 'true' to deny login with SSO without prior registration by an admin
    useAsUsername: email # default is 'email'; custom fields can be used as the username
@@ -47,14 +47,14 @@ security:
    provider: google # set this to your OAuth Provider's name, e.g., 'google' or 'keycloak'
  saml2:
    enabled: false # Only enabled for paid enterprise clients (enterpriseEdition.enabled must be true)
-    provider: '' # The name of your Provider
+    provider: "" # The name of your Provider
    autoCreateUser: true # set to 'true' to allow auto-creation of non-existing users
    blockRegistration: false # set to 'true' to deny login with SSO without prior registration by an admin
    registrationId: stirling # The name of your Service Provider (SP) app name. Should match the name in the path for your SSO & SLO URLs
    idpMetadataUri: https://dev-XXXXXXXX.okta.com/app/externalKey/sso/saml/metadata # The uri for your Provider's metadata
    idpSingleLoginUrl: https://dev-XXXXXXXX.okta.com/app/dev-XXXXXXXX_stirlingpdf_1/externalKey/sso/saml # The URL for initiating SSO. Provided by your Provider
    idpSingleLogoutUrl: https://dev-XXXXXXXX.okta.com/app/dev-XXXXXXXX_stirlingpdf_1/externalKey/slo/saml # The URL for initiating SLO. Provided by your Provider
-    idpIssuer: '' # The ID of your Provider
+    idpIssuer: "" # The ID of your Provider
    idpCert: classpath:okta.cert # The certificate your Provider will use to authenticate your app's SAML authentication requests. Provided by your Provider
    privateKey: classpath:saml-private-key.key # Your private key. Generated from your keypair
    spCert: classpath:saml-public-cert.crt # Your signing certificate. Generated from your keypair
@@ -110,21 +110,45 @@ mail:
  enableInvites: false # set to 'true' to enable email invites for user management (requires mail.enabled and security.enableLogin)
  host: smtp.example.com # SMTP server hostname
  port: 587 # SMTP server port
-  username: '' # SMTP server username
-  password: '' # SMTP server password
-  from: '' # sender email address
+  username: "" # SMTP server username
+  password: "" # SMTP server password
+  from: "" # sender email address
  startTlsEnable: true # enable STARTTLS (explicit TLS upgrade after connecting) when supported by the SMTP server
  startTlsRequired: false # require STARTTLS; connection fails if the upgrade command is not supported
  sslEnable: false # enable SSL/TLS wrapper for implicit TLS (typically used with port 465)
-  sslTrust: '' # optional trusted host override, e.g. "smtp.example.com" or "*"; defaults to "*" (trust all) when empty
+  sslTrust: "" # optional trusted host override, e.g. "smtp.example.com" or "*"; defaults to "*" (trust all) when empty
  sslCheckServerIdentity: false # enable hostname verification when using SSL/TLS

+telegram:
+  enabled: false # set to 'true' to enable Telegram bot integration
+  botToken: "" # Telegram bot token obtained from BotFather
+  botUsername: "" # Telegram bot username (without @)
+  pipelineInboxFolder: telegram # Name of the pipeline inbox folder for Telegram uploads
+  customFolderSuffix: true # set to 'true' to allow users to specify custom target folders via UserID
+  enableAllowUserIDs: true # set to 'true' to restrict access to specific Telegram user IDs
+  allowUserIDs: [] # List of allowed Telegram user IDs (e.g. [123456789, 987654321]). Leave empty to allow all users.
+  enableAllowChannelIDs: true # set to 'true' to restrict access to specific Telegram channel IDs
+  allowChannelIDs: [] # List of allowed Telegram channel IDs (e.g. [-1001234567890, -1009876543210]). Leave empty to allow all channels.
+  processingTimeoutSeconds: 180 # Maximum time in seconds to wait for processing a Telegram request
+  pollingIntervalMillis: 2000 # Interval in milliseconds between polling for new messages
+  feedback:
+    channel:
+      noValidDocument: true # set to 'false' to hide/suppress feedback messages in channels (to avoid spam)
+      errorProcessing: true # set to 'false' to hide/suppress feedback messages in channels (to avoid spam)
+      errorMessage: true # set to 'false' to hide/suppress error messages in channels (to avoid spam)
+      processing: true # set to 'false' to hide/suppress processing messages in channels (to avoid spam)
+    user:
+      noValidDocument: true # set to 'false' to hide/suppress feedback messages to users (to avoid spam)
+      errorProcessing: true # set to 'false' to hide/suppress feedback messages to users (to avoid spam)
+      errorMessage: true # set to 'false' to hide/suppress error messages to users (to avoid spam)
+      processing: true # set to 'false' to hide/suppress processing messages to users (to avoid spam)
+
 legal:
  termsAndConditions: https://www.stirling.com/legal/terms-of-service # URL to the terms and conditions of your application (e.g. https://example.com/terms). Empty string to disable or filename to load from local file in static folder
  privacyPolicy: https://www.stirling.com/legal/privacy-policy # URL to the privacy policy of your application (e.g. https://example.com/privacy). Empty string to disable or filename to load from local file in static folder
-  accessibilityStatement: '' # URL to the accessibility statement of your application (e.g. https://example.com/accessibility). Empty string to disable or filename to load from local file in static folder
-  cookiePolicy: '' # URL to the cookie policy of your application (e.g. https://example.com/cookie). Empty string to disable or filename to load from local file in static folder
-  impressum: '' # URL to the impressum of your application (e.g. https://example.com/impressum). Empty string to disable or filename to load from local file in static folder
+  accessibilityStatement: "" # URL to the accessibility statement of your application (e.g. https://example.com/accessibility). Empty string to disable or filename to load from local file in static folder
+  cookiePolicy: "" # URL to the cookie policy of your application (e.g. https://example.com/cookie). Empty string to disable or filename to load from local file in static folder
+  impressum: "" # URL to the impressum of your application (e.g. https://example.com/impressum). Empty string to disable or filename to load from local file in static folder

 system:
  defaultLocale: en-US # set the default language (e.g. 'de-DE', 'fr-FR', etc)
@@ -143,8 +167,8 @@ system:
  disableSanitize: false # set to true to disable Sanitize HTML; (can lead to injections in HTML)
  maxDPI: 500 # Maximum allowed DPI for PDF to image conversion
  corsAllowedOrigins: [] # List of allowed origins for CORS (e.g. ['http://localhost:5173', 'https://app.example.com']). Leave empty to disable CORS. For local development with frontend on port 5173, add 'http://localhost:5173'
-  backendUrl: '' # Backend base URL for SAML/OAuth/API callbacks (e.g. 'http://localhost:8080' for dev, 'https://api.example.com' for production). REQUIRED for SSO authentication to work correctly. This is where your IdP will send SAML responses and OAuth callbacks. Leave empty to default to 'http://localhost:8080' in development.
-  frontendUrl: '' # Frontend URL for invite email links (e.g. 'https://app.example.com'). Optional - if not set, will use backendUrl. This is the URL users click in invite emails.
+  backendUrl: "" # Backend base URL for SAML/OAuth/API callbacks (e.g. 'http://localhost:8080' for dev, 'https://api.example.com' for production). REQUIRED for SSO authentication to work correctly. This is where your IdP will send SAML responses and OAuth callbacks. Leave empty to default to 'http://localhost:8080' in development.
+  frontendUrl: "" # Frontend URL for invite email links (e.g. 'https://app.example.com'). Optional - if not set, will use backendUrl. This is the URL users click in invite emails.
  enableMobileScanner: false # Enable mobile phone QR code upload feature. Requires frontendUrl to be configured.
  mobileScannerSettings:
    convertToPdf: true # Automatically convert uploaded images to PDF format. If false, images are kept as-is.
@@ -162,14 +186,14 @@ system:
      level: MEDIUM # Security level: MAX (whitelist only), MEDIUM (block internal networks), OFF (no restrictions)
      allowedDomains: [] # Whitelist of allowed domains (e.g. ['cdn.example.com', 'images.google.com'])
      blockedDomains: [] # Additional domains to block (e.g. ['evil.com', 'malicious.org'])
-      internalTlds: ['.local', '.internal', '.corp', '.home'] # Block domains with these TLD patterns
+      internalTlds: [".local", ".internal", ".corp", ".home"] # Block domains with these TLD patterns
      blockPrivateNetworks: true # Block RFC 1918 private networks (10.x.x.x, 192.168.x.x, 172.16-31.x.x)
      blockLocalhost: true # Block localhost and loopback addresses (127.x.x.x, ::1)
      blockLinkLocal: true # Block link-local addresses (169.254.x.x, fe80::/10)
      blockCloudMetadata: true # Block cloud provider metadata endpoints (169.254.169.254)
  datasource:
    enableCustomDatabase: false # Enterprise users ONLY, set this property to 'true' if you would like to use your own custom database configuration
-    customDatabaseUrl: '' # eg jdbc:postgresql://localhost:5432/postgres, set the url for your own custom database connection. If provided, the type, hostName, port and name are not necessary and will not be used
+    customDatabaseUrl: "" # eg jdbc:postgresql://localhost:5432/postgres, set the url for your own custom database connection. If provided, the type, hostName, port and name are not necessary and will not be used
    username: postgres # set the database username
    password: postgres # set the database password
    type: postgresql # the type of the database to set (e.g. 'h2', 'postgresql')
@@ -178,29 +202,29 @@ system:
    name: postgres # set the name of your database. Should match the name of the database you create
  customPaths:
    pipeline:
-      watchedFoldersDir: '' # Defaults to /pipeline/watchedFolders
-      finishedFoldersDir: '' # Defaults to /pipeline/finishedFolders
+      watchedFoldersDir: "" # Defaults to /pipeline/watchedFolders
+      finishedFoldersDir: "" # Defaults to /pipeline/finishedFolders
    operations:
-      weasyprint: '' # Defaults to /opt/venv/bin/weasyprint
-      unoconvert: '' # Defaults to /opt/venv/bin/unoconvert
-      calibre: '' # Defaults to /usr/bin/ebook-convert
-      ocrmypdf: '' # Defaults to /usr/bin/ocrmypdf
-      soffice: '' # Defaults to /usr/bin/soffice
-  fileUploadLimit: '' # Defaults to "". No limit when string is empty. Set a number, between 0 and 999, followed by one of the following strings to set a limit. "KB", "MB", "GB".
+      weasyprint: "" # Defaults to /opt/venv/bin/weasyprint
+      unoconvert: "" # Defaults to /opt/venv/bin/unoconvert
+      calibre: "" # Defaults to /usr/bin/ebook-convert
+      ocrmypdf: "" # Defaults to /usr/bin/ocrmypdf
+      soffice: "" # Defaults to /usr/bin/soffice
+  fileUploadLimit: "" # Defaults to "". No limit when string is empty. Set a number, between 0 and 999, followed by one of the following strings to set a limit. "KB", "MB", "GB".
  tempFileManagement:
-    baseTmpDir: '' # Defaults to java.io.tmpdir/stirling-pdf
-    libreofficeDir: '' # Defaults to tempFileManagement.baseTmpDir/libreoffice
-    systemTempDir: '' # Only used if cleanupSystemTemp is true
+    baseTmpDir: "" # Defaults to java.io.tmpdir/stirling-pdf
+    libreofficeDir: "" # Defaults to tempFileManagement.baseTmpDir/libreoffice
+    systemTempDir: "" # Only used if cleanupSystemTemp is true
    prefix: stirling-pdf- # Prefix for temp file names
    maxAgeHours: 24 # Maximum age in hours before temp files are cleaned up
    cleanupIntervalMinutes: 30 # How often to run cleanup (in minutes)
    startupCleanup: true # Clean up old temp files on startup
    cleanupSystemTemp: false # Whether to clean broader system temp directory
  databaseBackup:
-    cron: '0 0 0 * * ?' # Cron expression for automatic database backups "0 0 0 * * ?" daily at midnight
+    cron: "0 0 0 * * ?" # Cron expression for automatic database backups "0 0 0 * * ?" daily at midnight

 ui:
-  appNameNavbar: '' # name displayed on the navigation bar
+  appNameNavbar: "" # name displayed on the navigation bar
  logoStyle: classic # Options: 'classic' (default - classic S icon) or 'modern' (minimalist logo)
  languages: [] # If empty, all languages are enabled. To display only German and Polish ["de_DE", "pl_PL"]. British English is always enabled.

@@ -581,6 +581,7 @@ public class AdminSettingsController {
            case "processexecutor", "processExecutor" -> applicationProperties.getProcessExecutor();
            case "autopipeline", "autoPipeline" -> applicationProperties.getAutoPipeline();
            case "legal" -> applicationProperties.getLegal();
+            case "telegram" -> applicationProperties.getTelegram();
            default -> null;
        };
    }
@@ -602,7 +603,8 @@ public class AdminSettingsController {
                    "processexecutor",
                    "autoPipeline",
                    "autopipeline",
-                    "legal");
+                    "legal",
+                    "telegram");

    // Pattern to validate safe property paths - only alphanumeric, dots, and underscores
    private static final Pattern SAFE_KEY_PATTERN =