API Proxy

Transparent Telegram API proxy that captures outgoing bot messages

BotMux provides a Telegram API proxy at /tgapi/ that transparently forwards requests to api.telegram.org and captures outgoing messages. It also intercepts several management methods so your backend can use the standard Telegram Bot API without conflicting with BotMux’s internal state.

Why use the API proxy?

Telegram’s getUpdates only returns incoming messages — messages sent by the bot itself are not included. The API proxy solves this by intercepting send methods and saving the sent message to the database.

Setup

Change your backend’s API base URL:

# Before (direct)
https://api.telegram.org/bot{TOKEN}/sendMessage

# After (via BotMux proxy)
http://localhost:8080/tgapi/bot{TOKEN}/sendMessage

The proxy forwards all requests to Telegram and returns responses unchanged, except for intercepted methods that BotMux handles internally.

File download proxy

BotMux also provides a file download endpoint that makes it compatible as a drop-in base_file_url for Telegram bot libraries:

# Telegram default
https://api.telegram.org/file/bot{TOKEN}/{file_path}

# Via BotMux proxy
http://localhost:8080/tgapi/file/bot{TOKEN}/{file_path}

This endpoint downloads the file from Telegram and streams it to the client. WebP files (stickers) are automatically converted to PNG for browser compatibility.

Local Bot API Server upstream

BotMux can use a self-hosted Telegram Bot API Server as upstream instead of api.telegram.org:

./botmux -tg-api http://127.0.0.1:8081
# or
TELEGRAM_API_URL=http://127.0.0.1:8081 ./botmux

When the upstream runs in --local mode, getFile may return absolute filesystem paths. BotMux handles this in two ways:

1. Via /tgapi/ — getFile responses rewrite absolute file_path values to BotMux-relative paths, so backends can keep using base_file_url=http://botmux:8080/tgapi.
2. Direct filesystem reads — if BotMux shares a volume with the Local Bot API server, point it at the files directory:

./botmux -tg-api http://127.0.0.1:8081 -tg-api-files /var/lib/telegram-bot-api
# or
TELEGRAM_API_FILES=/var/lib/telegram-bot-api ./botmux

With -tg-api-files, /api/media and /tgapi/file/ can serve files directly from disk when colocated, avoiding redundant HTTP downloads. Large uploads (up to ~2 GB) and longer timeouts are enabled automatically when a custom -tg-api is set.

Captured methods

Method	Description
sendMessage	Text messages
sendPhoto	Photos
sendAudio	Audio files
sendDocument	Documents
sendVideo	Videos
sendAnimation	GIFs/animations
sendVoice	Voice messages
sendVideoNote	Video notes
sendSticker	Stickers
sendLocation	Locations
sendVenue	Venues
sendContact	Contacts
sendPoll	Polls
sendDice	Dice
forwardMessage	Forwarded messages
copyMessage	Copied messages
editMessageText	Edited text messages
editMessageCaption	Edited captions
editMessageMedia	Edited media

The API Proxy URL is displayed in the bot detail view when proxy mode is enabled (click to copy).

Intercepted methods

The following Telegram Bot API methods are intercepted by the proxy and handled internally by BotMux instead of being forwarded to Telegram:

Method	Behavior
setWebhook	Registers the webhook URL as the bot’s backend URL in BotMux and enables proxy mode. Auto-registration of unknown tokens requires the BOTMUX_ALLOW_AUTO_REGISTER=1 environment variable. The webhook URL must use HTTPS (HTTP is only allowed for loopback addresses unless BOTMUX_STRICT_WEBHOOK=1 is set). Supports url and drop_pending_updates parameters.
deleteWebhook	Clears the backend URL and disables proxy mode for the bot. Supports drop_pending_updates.
getWebhookInfo	Returns BotMux’s internal webhook state including the configured backend URL and pending update count.
getUpdates	When long polling is enabled, returns updates from BotMux’s internal queue instead of polling Telegram directly. For any other bot known to BotMux, returns an empty result to prevent conflict errors.
logOut	Returns success without forwarding to Telegram. Forwarding would disable the token for 10 minutes, breaking BotMux’s polling.
close	Returns success without forwarding to Telegram. Forwarding would shut down the bot instance on Telegram’s side.

When BOTMUX_ALLOW_AUTO_REGISTER=1 is set, the setWebhook interception enables zero-configuration migration: point your existing bot backend at BotMux’s API proxy URL, and BotMux will automatically register the bot and start forwarding updates to your backend.