#19616: feat(telegram): support custom apiRoot for Telegram Bot API
channel: msteams
channel: telegram
size: S
Cluster:
Messaging Platform Improvements
## Summary
Allow users to configure a custom Telegram Bot API server URL via the `apiRoot` config option on Telegram accounts. This enables use of [local Bot API servers](https://core.telegram.org/bots/api#using-a-local-bot-api-server) which bypass the 20MB file download limit imposed by the official API.
## Config Example
```yaml
channels:
telegram:
accounts:
default:
apiRoot: http://localhost:8081
```
## Changes
- **`src/config/types.telegram.ts`** — Add `apiRoot?` to `TelegramAccountConfig`
- **`src/config/zod-schema.providers-core.ts`** — Add `apiRoot` to Zod schema with URL validation
- **`src/telegram/accounts.ts`** — Resolve `apiRoot` (default: `https://api.telegram.org`) in `ResolvedTelegramAccount`
- **`src/telegram/bot.ts`** — Pass `apiRoot` to grammY's `ApiClientOptions` and handler registration
- **`src/telegram/bot-handlers.ts`** — Thread `apiRoot` through to `resolveMedia` calls
- **`src/telegram/bot-native-commands.ts`** — Add `apiRoot` to handler params type
- **`src/telegram/bot/delivery.ts`** — Use `apiRoot` for file download URLs
- **`src/telegram/probe.ts`** — Use `apiRoot` for bot probing
- **`src/telegram/audit.ts`** — Use `apiRoot` for group membership audit
- **`extensions/telegram/src/channel.ts`** — Pass `apiRoot` to probe/audit calls
- **`src/channels/plugins/onboarding/telegram.ts`** — Use `apiRoot` in onboarding help text and `getChat` calls
## Testing
- TypeScript compiles cleanly (`tsc --noEmit` passes)
- All changes are backward-compatible (default remains `https://api.telegram.org`)
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Added support for custom Telegram Bot API server URLs via the `apiRoot` configuration option. This enables users to bypass the official API's 20MB file download limit by using [local Bot API servers](https://core.telegram.org/bots/api#using-a-local-bot-api-server).
**Key changes:**
- Added `apiRoot` field to `TelegramAccountConfig` type with URL validation in Zod schema
- Resolved `apiRoot` in `resolveTelegramAccount` with default value `https://api.telegram.org`
- Threaded `apiRoot` through bot creation, file downloads, probing, and audit functions
- Updated onboarding flow to display correct API URL in help text based on configuration
The implementation is backward-compatible (defaults to official API) and consistently applied across all Telegram API interactions.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with no identified risks
- The implementation is clean, consistent, and well-structured. The `apiRoot` parameter is properly validated (URL schema), has sensible defaults, and is threaded correctly through all code paths. No logic errors, security issues, or breaking changes were found. TypeScript types are properly updated, and the change is fully backward-compatible.
- No files require special attention
<sub>Last reviewed commit: 52e2d06</sub>
<!-- greptile_other_comments_section -->
<sub>(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#13070: feat: Add support for custom Telegram Bot API server URL via apiRoo...
by vfiee · 2026-02-10
88.3%
#9577: feat: Add apiRoot option for custom Telegram Bot API server endpoint
by vfiee · 2026-02-05
87.8%
#18170: feat(telegram): support local Bot API server via `apiRoot` config
by iemesowum · 2026-02-16
85.9%
#8310: feat(telegram): Add allowBots support for groups (parity with Disco...
by vishaltandale00 · 2026-02-03
78.5%
#22434: feat(telegram): support sending original quality images
by godenjan · 2026-02-21
77.4%
#21029: Feature/telegram bot avatar clean
by aleonnet · 2026-02-19
76.6%
#7058: feat(telegram): add channel_post handler for broadcast channels
by waifu7498173 · 2026-02-02
75.9%
#19942: feat(telegram): configurable SSRF policy for media fetch
by onewesong · 2026-02-18
74.8%
#19213: Telegram: preserve DM topic thread in direct replies
by Kemalau · 2026-02-17
73.6%
#20170: fix(irc): add configurable commandPrefix to avoid IRC reserved / pr...
by yxshee · 2026-02-18
73.6%