Self-hosted server

Telegram bot

Stirling PDF can run a Telegram bot that saves each PDF sent to it into a watched folder, then sends back the result of that folder's pipeline JSON. It only makes outbound HTTPS calls to api.telegram.org, so you don't need to open a port or set up a webhook.

Community feature

Community-built beta, available on every licence tier but not covered by Team or Enterprise support; settings may change.

1. Create the bot#

In Telegram, open @BotFather and send /newbot.
Pick a display name and a username ending in bot.
Copy the token BotFather returns.

To use the bot in groups, also send /setprivacy to BotFather, select your bot and choose Disable. Otherwise the bot only sees commands and mentions in groups.

2. Configure Stirling PDF Login required#

Open Settings → Server → Integrations → Telegram Bot, or edit the telegram block that is already in settings.yml:

yaml

telegram:
  enabled: true
  botToken: "your-token-from-botfather"
  botUsername: "your_bot_username"
  allowUserIDs: [123456789]

bash

TELEGRAM_ENABLED=true
TELEGRAM_BOTTOKEN=your-token-from-botfather
TELEGRAM_BOTUSERNAME=your_bot_username
TELEGRAM_ALLOWUSERIDS=123456789

Restart Stirling PDF after changing these settings.

3. Add a pipeline JSON#

The bot only processes files once the chat's inbox folder has a .json pipeline file.

Each chat's inbox is /pipeline/watchedFolders/telegram/<chat ID>/ by default.
The subfolder is created the first time a chat sends the bot a PDF. Send one (the bot replies that no JSON configuration file was found), then look for the new folder. @userinfobot also tells you your user ID.
Build the workflow in the Automate tool, select Export for Folder Scanning, and put the downloaded file in the folder. Any .json filename works.

4. Send a PDF#

Send the bot a PDF. The result comes back in the same chat.

Only application/pdf files are accepted, up to 20 MB (a Telegram bot limit).
If the pipeline produces several files, each arrives as a separate message.

Access control#

Chat type	Who is allowed
Private chats	Users listed in `allowUserIDs`. An empty list allows everyone.
Channels	Channels listed in `allowChannelIDs`. An empty list allows every channel.
Groups and supergroups	Always allowed. To keep the bot out of groups, send BotFather `/setjoingroups` and choose Disable.

On a shared server, always fill in at least one list.

To post in a channel, add the bot as a channel admin with permission to post messages.

Settings reference#

All keys sit under telegram.

Key	Default	Purpose
`enabled`	`false`	Turn the bot on.
`botToken`	empty	Token from BotFather.
`botUsername`	empty	Bot username, without `@`.
`pipelineInboxFolder`	`telegram`	Inbox subfolder under `/pipeline/watchedFolders/`.
`customFolderSuffix`	`true`	Give each chat its own subfolder, named after its chat ID.
`enableAllowUserIDs`	`true`	Apply `allowUserIDs` to private chats.
`allowUserIDs`	`[]`	Allowed Telegram user IDs.
`enableAllowChannelIDs`	`true`	Apply `allowChannelIDs` to channels.
`allowChannelIDs`	`[]`	Allowed channel IDs, usually negative, such as `-1001234567890`.
`processingTimeoutSeconds`	`180`	How long to wait for a pipeline result. Folder scanning runs once a minute, so keep it at 90 or more.
`pollingIntervalMillis`	`2000`	How often to check for a result.
`feedback.user.`, `feedback.channel.`	all `true`	Status replies in private chats and channels: `noValidDocument`, `errorProcessing`, `errorMessage`, `processing`. Set to `false` to cut noise.

Edit this page on GitHub