Документация

Интеграция за пять минут

Как подключить прокси к своему боту: исходящие запросы Bot API, приём вебхуков и регистрация бота. Примеры на Python, TypeScript и JavaScript.

Открыть Swagger API ↗Войти в админку

О прокси

Прокси решает две задачи. Во-первых, принимает вебхуки от Telegram на зарубежном сервере и пересылает их на ваш «реальный» бэкенд. Во-вторых, служит drop-in заменой api.telegram.org: ваш бэкенд шлёт запросы на домен прокси, а тот прозрачно проксирует их в Telegram.

Адрес вашего прокси в примерах ниже — https://telegram.crossmark.ru — он подставляется автоматически из адреса вашего сервиса.

Исходящий Bot API (drop-in замена хоста)

Поменяйте базовый URL клиента c https://api.telegram.org на адрес прокси. Проксируются все методы и любой content-type, включая multipart/form-data.

send.py

import requests
 
PROXY = "https://telegram.crossmark.ru"
TOKEN = "123456789:AA..."
 
# Вместо https://api.telegram.org обращаемся к прокси — метод тот же.
resp = requests.post(
    f"{PROXY}/bot{TOKEN}/sendMessage",
    json={"chat_id": 12345, "text": "Привет через прокси!"},
    timeout=30,
)
print(resp.json())
 
# aiogram 3.x:
#   from aiogram.client.telegram import TelegramAPIServer
#   from aiogram.client.session.aiohttp import AiohttpSession
#   session = AiohttpSession(api=TelegramAPIServer.from_base(PROXY))
#   bot = Bot(TOKEN, session=session)
#
# python-telegram-bot 20+:
#   ApplicationBuilder().token(TOKEN) \
#       .base_url(f"{PROXY}/bot").base_file_url(f"{PROXY}/file/bot").build()

По умолчанию прокси обслуживает только токены ботов, зарегистрированных в админке (защита от открытого relay). Сначала добавьте бота — см. раздел 04.

Скачивание файлов

Файлы качаются через путь /file/bot<token>/<file_path> — тоже через прокси.

download.py

# getFile -> file_path, затем скачиваем сам файл через /file/...
info = requests.get(
    f"https://telegram.crossmark.ru/bot{TOKEN}/getFile",
    params={"file_id": file_id},
).json()
path = info["result"]["file_path"]
 
content = requests.get(f"https://telegram.crossmark.ru/file/bot{TOKEN}/{path}").content
open("photo.jpg", "wb").write(content)

Входящие вебхуки

Когда вы регистрируете бота (раздел 04), прокси сам вызывает Telegram setWebhook и направляет апдейты на https://telegram.crossmark.ru/webhook/<secret>. Дальше тело апдейта как есть пересылается на ваш targetWebhookUrl с заголовком X-Telegram-Bot-Api-Secret-Token.

webhook.py

from fastapi import FastAPI, Request, Header, HTTPException
 
# Тот же секрет, что показан в карточке бота в админке.
SECRET = "<webhook secret из админки>"
app = FastAPI()
 
@app.post("/telegram/webhook")
async def webhook(
    request: Request,
    x_telegram_bot_api_secret_token: str = Header(default=""),
):
    # Прокси пробрасывает этот заголовок — проверяем, как от Telegram.
    if x_telegram_bot_api_secret_token != SECRET:
        raise HTTPException(status_code=403)
 
    update = await request.json()
    # ... ваша обработка апдейта ...
 
    # Верните 2xx. Иначе прокси повторит доставку (по умолчанию до 3 раз).
    return {"ok": True}

Верните 2xx как можно быстрее. Если бэкенд ответил не-2xx или недоступен — прокси повторит доставку до 3 раз с нарастающей паузой, а Telegram в итоге получит 200 (чтобы не было шторма ретраев). Ответ бэкенда при успехе прозрачно возвращается Telegram — работает «ответ методом в теле ответа».

Регистрация бота

Проще всего — через веб-админку: добавьте бота, укажите токен и targetWebhookUrl, прокси сам проверит токен через getMe и поставит вебхук. Либо через админ-API:

bash

# 1) Логин — получить JWT
curl -X POST https://telegram.crossmark.ru/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"admin@example.com","password":"<пароль>"}'
 
# 2) Зарегистрировать бота (прокси проверит токен и поставит вебхук)
curl -X POST https://telegram.crossmark.ru/api/bots \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "name": "My Bot",
    "token": "123456789:AA...",
    "targetWebhookUrl": "https://your-backend.example.com/telegram/webhook"
  }'

Справочник API

Полное описание админ-API (логин, CRUD ботов, журнал доставок) с интерактивной консолью — в Swagger UI. Авторизация по JWT: получите токен через /auth/login и нажмите Authorize.

Открыть Swagger UI ↗