---
title: "Deploy Telegram Bot API Server | (Just Updated) Official Local Server, 2 GB Uploads"
description: "Official local Bot API server: 2 GB uploads, unlimited downloads"
category: "Bots"
url: https://railway.com/deploy/telegram-bot-api-server-or-just-updated-
---

# Deploy Telegram Bot API Server | (Just Updated) Official Local Server, 2 GB Uploads

Official local Bot API server: 2 GB uploads, unlimited downloads

**[Deploy Telegram Bot API Server | (Just Updated) Official Local Server, 2 GB Uploads on Railway](https://railway.com/template/telegram-bot-api-server-or-just-updated-)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/telegram-bot-api-server-or-just-updated-/manifest.json

- **Creator:** SuperSlowSloth
- **Category:** Bots

## Template content

### telegram-bot-api

- **Image:** ghcr.io/bon5co/telegram-bot-api-railway:latest
- **Public domain:** Yes

## Documentation

# Deploy and Host Telegram Bot API Server on Railway

The official `telegram-bot-api` server, self-hosted. Running your own local Bot API
server removes the limits the public `api.telegram.org` endpoint imposes on every
bot: downloads go from 20 MB to **unlimited**, uploads from 50 MB to **2 GB**, webhooks
can point at any local IP address, and files are served straight off this server's own
disk instead of being re-downloaded from Telegram.

This template runs the official server (`aiogram/telegram-bot-api`) with `--local`
enabled, the working directory on a persistent volume, and the HTTP port wired to
Railway's injected `$PORT` so the public URL works with no extra configuration.

## About Hosting Telegram Bot API Server

The server is a long-running C++ process that keeps every bot's session in RAM and
writes downloaded and uploaded media to disk. That makes it a poor fit for anything
ephemeral: without a volume, every file a bot has downloaded disappears on redeploy,
and the working directory has to survive restarts for local-mode file paths to remain
valid. This template mounts `/var/lib/telegram-bot-api` as a volume for exactly that
reason.

`TELEGRAM_LOCAL` is enabled by default here. Local mode is what unlocks the large
upload limit and local file paths; the upstream image leaves it off, so a stock deploy
looks like it is working while still behaving like the public endpoint.

## Why Deploy Telegram Bot API Server on Railway

Railway runs the container, gives it a TLS public domain, and keeps the volume attached
across deploys — which is the whole operational requirement of this service. The HTTP
port is injected, and this image passes it through to the server's `--http-port` flag,
so there is no port mismatch to debug and no reverse proxy to configure.

## Common Use Cases

- Bots that send or receive files larger than the public API allows (video, archives, datasets).
- Bots that download media at volume and want it served from their own disk.
- Bots that need webhooks on a private or non-standard address.

## Dependencies for Telegram Bot API Server

- `TELEGRAM_API_ID` and `TELEGRAM_API_HASH`, obtained free at https://my.telegram.org
  (Apps). These identify your application to Telegram; the server refuses to start
  without them.

### Deployment Dependencies

- https://my.telegram.org — create an application to obtain the API ID and hash.
- https://core.telegram.org/bots/api#using-a-local-bot-api-server — upstream documentation.

## Honest limits

The server cannot start without the two credentials above, which belong to the person
deploying it, so this template's live verification covers the container, the volume,
the port wiring and local mode — not a paired bot.


## Similar templates

- [Telegram JavaScript Bot](https://railway.com/deploy/5lRkWa) — A template for Telegram bot in JavaScript using grammY
- [Cobalt Tools [Updated Sep ’26]](https://railway.com/deploy/cobalt) — Cobalt Tools [Sep ’26] (Media Downloader, Converter & Automation) Self Host
- [Telegram Gateway](https://railway.com/deploy/railway-telegram-gateway) — Multi-bot Telegram webhook gateway with WebSocket event streaming

Open this page in a browser: https://railway.com/deploy/telegram-bot-api-server-or-just-updated-