Bot API для
Xirogram

Быстрый старт

Шлюз слушает порт 8081 и проксируется Caddy на публичный домен. Токен бота выдаётся BotFather внутри Xirogram — он же используется в MTProto-клиенте.

curl -s "https://xiroapi.duckdns.org/bot<TOKEN>/getMe"

Подключение библиотек

from telegram.ext import ApplicationBuilder

app = (
    ApplicationBuilder()
    .token("<TOKEN>")
    .base_url("https://xiroapi.duckdns.org/bot")
    .base_file_url("https://xiroapi.duckdns.org/file/bot")
    .build()
)
app.run_polling()

from aiogram import Bot
from aiogram.client.telegram import TelegramAPIServer

bot = Bot(
    token="<TOKEN>",
    server=TelegramAPIServer.from_base("https://xiroapi.duckdns.org"),
)

import { Bot } from "grammy";

const bot = new Bot("<TOKEN>", {
  client: { apiRoot: "https://xiroapi.duckdns.org" },
});

bot.command("start", (ctx) => ctx.reply("Привет из Xirogram"));
bot.start();

Туториал: бот за 10 минут

От @BotFather до первого ответа. Все шаги выполняются внутри Xirogram; официальные библиотеки Telegram подключаются через base URL шлюза.

curl -s "https://xiroapi.duckdns.org/bot<TOKEN>/getMe"

import requests, time

BASE = "https://xiroapi.duckdns.org"
TOKEN = "<TOKEN>"
offset = 0

while True:
    r = requests.get(
        f"{BASE}/bot{TOKEN}/getUpdates",
        params={"offset": offset, "timeout": 25},
        timeout=30,
    )
    for upd in r.json().get("result", []):
        offset = upd["update_id"] + 1
        msg = upd.get("message")
        if msg:
            requests.post(f"{BASE}/bot{TOKEN}/sendMessage", json={
                "chat_id": msg["chat"]["id"],
                "text": "Привет из Xirogram!",
            })
    time.sleep(0.2)

curl -s -X POST "https://xiroapi.duckdns.org/bot<TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://bot.example.com/hook"}'

from telegram.ext import ApplicationBuilder

app = (
    ApplicationBuilder()
    .token("<TOKEN>")
    .base_url("https://xiroapi.duckdns.org/bot")
    .base_file_url("https://xiroapi.duckdns.org/file/bot")
    .build()
)
app.run_polling()

from aiogram import Bot
from aiogram.client.telegram import TelegramAPIServer

bot = Bot(
    token="<TOKEN>",
    server=TelegramAPIServer.from_base("https://xiroapi.duckdns.org"),
)

import { Bot } from "grammy";

const bot = new Bot("<TOKEN>", {
  client: { apiRoot: "https://xiroapi.duckdns.org" },
});

bot.command("start", (ctx) => ctx.reply("Привет из Xirogram"));
bot.start();

Рецепты

Готовые сценарии, которые можно скопировать в проект и заменить <TOKEN> и chat_id.

curl -s -X POST "https://xiroapi.duckdns.org/bot<TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "Выбери действие",
    "reply_markup": {
      "inline_keyboard": [[
        {"text": "Сайт", "url": "https://example.com"},
        {"text": "Поздороваться", "callback_data": "hi"}
      ]]
    }
  }'

curl -s -X POST "https://xiroapi.duckdns.org/bot<TOKEN>/answerCallbackQuery" \
  -H "Content-Type: application/json" \
  -d '{"callback_query_id":"<ID>","text":"Привет!"}'

from fastapi import FastAPI, Request
import requests

app = FastAPI()
BASE = "https://xiroapi.duckdns.org"
TOKEN = "<TOKEN>"

@app.post("/hook")
async def hook(req: Request):
    upd = await req.json()
    msg = upd.get("message")
    if msg:
        requests.post(f"{BASE}/bot{TOKEN}/sendMessage", json={
            "chat_id": msg["chat"]["id"],
            "text": "echo: " + msg.get("text", ""),
        })
    return {"ok": True}

curl -s -X POST "https://xiroapi.duckdns.org/bot<TOKEN>/sendDocument" \
  -F chat_id=123456789 \
  -F document=@report.pdf

curl -s -X POST "https://xiroapi.duckdns.org/bot<TOKEN>/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {"command":"start","description":"Запустить бота"},
      {"command":"help","description":"Помощь"}
    ]
  }'

Частые ошибки на старте

Транспорт

<METHOD> сопоставляется без учёта регистра. Диспетчер доступен и по GET, и по POST, поэтому urlencoded-запросы методом GET работают.

Аутентификация

Токен в пути — это пара <bot_id>:<secret>. Секрет сверяется со значением, сохранённым для бота. Всё остальное даёт 401 с ACCESS_TOKEN_INVALID. Отдельного auth-заголовка нет: токен в URL и есть credential, ровно как на официальном шлюзе.

Скачивание файлов (/file/bot…) аутентифицируется так же.

Формат запросов и ответов

{
  "ok": true,
  "result": {}
}

{
  "ok": false,
  "error_code": 400,
  "description": "CHAT_ID_INVALID"
}

error_code — это HTTP-статус. description — маркер ошибки в верхнем регистре (SCREAMING_SNAKE), не обязательно в официальных формулировках Telegram: сопоставляйте по маркеру, а не по всей строке.

Разбор полей универсальный: JSON-тело «расплющивается» в строки, нестроковые значения перемаршируются в свой JSON, а в multipart берётся первое значение каждого поля. Поэтому часть методов принимает и сокращение message_text, и полный объект InputTextMessageContent, а setChatMenuButton — и вложенный menu_button, и «плоское» тело с type на верхнем уровне.

Ошибки

Маркеры, которые шлюз может вернуть напрямую. Полный список — ниже.

Обновления

Шлюз порождает только три вида обновлений:

allowed_updates — JSON-массив из не более 100 строк; неизвестные имена разбираются без ошибки, но не совпадают ни с чем. Не рассчитывайте на фильтрацию как на способ спрятать обновления — отбрасывайте лишние поля в боте.

Ephemeral-сообщения (Bot API 10.2) приходят как обычные message-обновления, но их message_id принадлежит ephemeral-пространству. Ответ идёт через reply_parameters.ephemeral_message_id.

Разметка и entities

reply_markup принимает ровно один конструктор:

Кнопки inline-клавиатуры

Ровно одно действие на кнопку, иначе BUTTON_INVALID: url, callback_data (до 64 байт), web_app, login_url (url, bot_username, forward_text, request_write_access), switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chat, copy_text. У каждой кнопки также есть text (обязателен), style (primary / danger / success / пусто) и icon_custom_emoji_id. Неизвестные поля отклоняются, а не игнорируются.

Кнопки reply-клавиатуры

Обычная строка либо объект с text и одним из: request_contact, request_location, request_poll, request_users, request_chat, web_app.

Message entities

bold, italic, underline, strikethrough, code, pre (language), text_link (url), text_mention (user.id), spoiler, blockquote, expandable_blockquote, custom_emoji (custom_emoji_id), mention, hashtag, cashtag, bot_command, url, email, phone_number, bank_card_number, date_time (unix_time + date_time_format).

Лимиты: 256 entity на сообщение (ENTITIES_TOO_LONG), смещения в кодовых единицах UTF-16, неизвестные типы — ENTITY_TYPE_UNSUPPORTED.

Лимиты

Не реализовано

Все остальные официальные методы возвращают HTTP 404 METHOD_NOT_FOUND. Чаще всего до них доходят:

• Правка: editMessageMedia, editMessageLiveLocation, stopMessageLiveLocation, stopPoll, а также inline_message_id для editMessageCaption / editMessageReplyMarkup.
• Медиагруппы: sendMediaGroup, sendPoll, sendDice, sendGame.
• Администрирование чатов: banChatMember, promoteChatMember, setChatPermissions, pinChatMessage, setChatTitle, leaveChat и смежные.
• Запросы: getChat, getChatAdministrators, getChatMember, getForumTopic*.
• Сообщения: forwardMessage, copyMessage, copyMessages.
• Администрирование бота: setMyName, setMyDescription, close, logOut.
• Реакции, игры и методы business-аккаунтов.

MTProto-клиенты это не затрагивает: всё, что реализовано для официальных клиентов Android/iOS/Desktop, доступно по MTProto, а не по HTTP.

Машинно-читаемые форматы

Та же спецификация, что и на этой странице, — для генерации клиентов, импорта в Postman и проверки в CI.

Состояние шлюза