> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botmux.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#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.                                                                                                                                                                                                                                                        |

<Note>
  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.
</Note>