README.md

---
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](https://github.com/tdlib/telegram-bot-api) 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](https://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

```python
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:**
```python
from telebot import apihelper
apihelper.API_URL = "https://YOUR-SPACE.hf.space/bot{0}/{1}"
```

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

**aiogram:**
```python
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`