Telegram bot

Markdrop Bot is a Telegram bot that you run yourself. Send it a document, a photo, a link or a YouTube video in Telegram, and it replies with a .md file and a short preview. The bot does not convert anything itself: it passes your files to your own Markdrop Web server.

There is no public Markdrop bot to add. You create your own bot in Telegram and run the bot program on a computer you control.

What you need

• A running Markdrop Web server. By default the bot looks for it at http://127.0.0.1:8460.
• Python and uv, as in the project's instructions.
• A Telegram account.
• The Markdrop source code: git clone https://github.com/Dhiva-Labs/markdrop.git.

Set up the bot

1. In Telegram, open a chat with @BotFather, send /newbot and follow its questions. At the end it gives you a token, a long secret string.

   DANGER

   The token controls your bot. Do not share it or put it in a public repository. If it leaks, ask @BotFather for a new one.

2. Start Markdrop Web, as shown in Web app and API.

3. Install the bot's packages:

   cd markdrop/06-telegram-bot
   uv venv .venv && uv pip install -p .venv/bin/python "python-telegram-bot>=21" httpx

4. Start the bot with your token:

   MD_BOT_TOKEN=<token> .venv/bin/python -m bot.main

5. In Telegram, open your new bot and send /start.

   The bot replies with a short welcome and its commands.

Use the bot

You send	You get back
A document, such as a PDF, Word, Excel, PowerPoint, e-book or CSV file	A .md file of its contents
A photo	The photo converted as an image
A message with a link	The web page as a .md file
A YouTube link	The video's title, description and transcript

The reply has the file and a short preview of the text.

Files can be up to 20 MB, which is Telegram's limit for bots. For bigger files, use the web page of your Markdrop Web server.

Commands

Command	What it does
/start or /help	Shows the welcome message and commands.
/formats	Lists the formats the converter supports.
/id	Shows your Telegram user id.

Make the bot private

By default anyone who finds your bot can use it. To allow only certain people:

1. Ask each person to send /id to the bot, and note the numbers.

2. Start the bot with those numbers in MD_BOT_ALLOWED_IDS, separated by commas:

   MD_BOT_TOKEN=<token> MD_BOT_ALLOWED_IDS=11111111,22222222 .venv/bin/python -m bot.main

Anyone else gets a reply saying the bot is private, with their id so they can ask you to add them.

Configuration

Variable	Default	What it does
MD_BOT_TOKEN	None (required)	The token from @BotFather.
MD_API_URL	http://127.0.0.1:8460	The address of your Markdrop Web server.
MD_API_KEY	Empty	Sent to Markdrop Web as X-API-Key, if your server requires a key.
MD_BOT_ALLOWED_IDS	Empty (open to everyone)	Comma-separated Telegram user ids allowed to use the bot.

Privacy

Files you send to the bot pass through Telegram's servers to your bot program, then to your Markdrop Web server. Do not send documents through Telegram that you would not want stored there.

Next steps

• Web app and API
• MCP connector
• Troubleshooting and FAQ