README.md

metadata

title: Telegram Bot API Server
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
pinned: true
app_port: 7860

Telegram Bot API Server

A self-hosted instance of the official Telegram Bot API server running on HuggingFace Spaces.

It speaks MTProto internally to Telegram's DCs (port 443), so it works even where api.telegram.org HTTP is blocked — including HuggingFace Spaces.

---

Setup

1. Get API credentials

Go to my.telegram.org, log in, and create an app. You'll get an API ID (number) and API Hash (string).

2. Set Space secrets

In your HF Space → Settings → Repository secrets, add:

Name	Value
API_ID	your numeric API ID
API_HASH	your API hash string

3. Use in your bot

from telebot import apihelper

apihelper.API_URL = "https://YOUR-SPACE-NAME.hf.space/bot{0}/{1}"

bot = telebot.TeleBot(os.environ["BOT_TOKEN"])

Replace YOUR-SPACE-NAME with your actual HF Space URL slug (e.g. yourusername-telegram-bot-api-server).

---

How it works

your bot (HTTP)
     ↓
this HF Space (Bot API server)
     ↓ MTProto on port 443
Telegram Data Centers

The Bot API server translates standard HTTP Bot API calls into MTProto, which HuggingFace does not block.

---

Supported by all pyTelegramBotAPI / python-telegram-bot bots

pyTelegramBotAPI:

from telebot import apihelper
apihelper.API_URL = "https://YOUR-SPACE.hf.space/bot{0}/{1}"

python-telegram-bot:

from telegram.constants import BOT_API_URL
application = Application.builder() \
    .token(TOKEN) \
    .base_url("https://YOUR-SPACE.hf.space/bot") \
    .build()

aiogram:

from aiogram.client.session.aiohttp import AiohttpSession
session = AiohttpSession(api=TelegramAPIServer.from_base("https://YOUR-SPACE.hf.space"))
bot = Bot(token=TOKEN, session=session)

---

Notes

• This space is meant to be private — set it to private in HF settings so only you can use it
• All your bots can share this single space
• The /data directory stores temporary files (file downloads etc.)
• Logs are written to /var/log/telegram-bot-api/server.log