API Proxy

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.

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.

Getting Started

Core Concepts

Features

Routing

Bridges

Authentication

Configuration

Architecture

Deployment

Why use the API proxy?

Setup

File download proxy

Captured methods

Intercepted methods

​Why use the API proxy?

​Setup

​File download proxy

​Captured methods

​Intercepted methods

Why use the API proxy?

Setup

File download proxy

Captured methods

Intercepted methods