Bot API

Начало работы#

1. Откройте Unixgram → меню → Мои боты → Создать. Придумайте имя и ник — он заканчивается на _bot.
2. Скопируйте токен вида 123456789:AAH…. Он показывается один раз; потерянный токен перевыпускается там же, старый перестаёт работать.
3. Проверьте токен:

curl https://unixgram.com/api/bot/<токен>/getMe

{
  "ok": true,
  "result": {
    "id": 4012,
    "is_bot": true,
    "first_name": "Погода",
    "username": "weather_bot",
    "can_join_groups": true,
    "can_read_all_group_messages": false,
    "supports_inline_queries": false
  }
}

Первый бот на Python, без зависимостей:

import json, time, urllib.request

TOKEN = "123456789:AAH..."
API = f"https://unixgram.com/api/bot/{TOKEN}/"

def call(method, **params):
    req = urllib.request.Request(API + method, data=json.dumps(params).encode(),
                                 headers={"Content-Type": "application/json"})
    return json.load(urllib.request.urlopen(req, timeout=35))["result"]

offset = 0
while True:
    for update in call("getUpdates", offset=offset, timeout=25):
        offset = update["update_id"] + 1
        message = update.get("message")
        if message and "text" in message:
            call("sendMessage", chat_id=message["chat"]["id"], text="Вы написали: " + message["text"])

Запросы и ответы#

Адрес метода — https://unixgram.com/api/bot/<токен>/<метод>. Принимаются GET с параметрами в строке запроса и POST с телом application/json, application/x-www-form-urlencoded или multipart/form-data. В форме составные значения (массивы, объекты) передаются JSON-строкой, логические — строками true/false.

Ответ всегда JSON:

{"ok": true, "result": …}
{"ok": false, "error_code": 400, "description": "Bad Request: text: Too small: expected string to have >=1 characters"}

Идентификаторы — целые числа. У групп chat_id отрицательный. В chat_id можно передать и @ник человека: если личного чата с ним ещё нет, он будет создан.

Обновления#

Получать обновления можно одним из двух способов — не обоими сразу:

• getUpdates — длинный опрос: запрос висит до 25 секунд и возвращается, как только что-то пришло. Передавайте offset = последний update_id + 1.
• setWebhook — сервер сам отправляет каждое Update POST-запросом на ваш https-адрес с заголовком X-Unixgram-Bot-Api-Secret-Token, если вы задали секрет. Проверяйте его — иначе адрес вебхука становится способом прислать боту что угодно.

Очередь хранится на сервере, пока вы её не заберёте: бот, выключенный на полдня, после запуска получит всё пропущенное. Виды обновлений: message, edited_message, callback_query, my_chat_member, pre_checkout_query.

Ссылка-приглашение в бота с меткой — https://unixgram.com/dashboard/messages?user=<ник_бота>&start=<метка>: бот получит сообщение /start <метка>. Метка — до 64 символов [A-Za-z0-9_-].

Форматирование#

parse_mode принимает HTML, Markdown и MarkdownV2 в синтаксисе Telegram. Вместо него можно передать готовый массив entities. Незнакомый тег — ошибка 400, а не молча выброшенный кусок текста.

<b>жирный</b> <i>курсив</i> <u>подчёркнутый</u> <s>зачёркнутый</s>
<tg-spoiler>спойлер</tg-spoiler> <code>код</code> <a href="https://unixgram.com">ссылка</a>
<pre>блок кода</pre>

Боту текст приходит без разметки, с массивом entities — так же, как в Bot API. Команды (/start) отмечены сущностью bot_command.

Клавиатуры#

InlineKeyboardMarkup#

Кнопки под сообщением: {"inline_keyboard": [[кнопка, …], …]}. До 100 рядов по 8 кнопок, текст кнопки — до 128 символов. У кнопки ровно одно действие:

ReplyKeyboardMarkup#

Клавиатура вместо системной: {"keyboard": [["Да", "Нет"]], "resize_keyboard": true, "one_time_keyboard": true, "input_field_placeholder": "…"}. Нажатие клавиши отправляет её текст обычным сообщением. {"remove_keyboard": true} убирает клавиатуру, {"force_reply": true} открывает поле ввода в режиме ответа.

Файлы#

Поле с вложением (photo, document, …) принимает:

• ссылку https://… — файл берётся по адресу как есть;
• сам файл частью multipart/form-data под именем поля;
• attach://<имя> — файл лежит в другой части формы под этим именем (так отправляют библиотеки).

Пределы: изображения 10 МБ, голосовые 12 МБ, видео и документы 50 МБ.

curl -F chat_id=1234 -F caption="График за неделю" -F photo=@chart.png \
  https://unixgram.com/api/bot/<токен>/sendPhoto

Мини-приложения#

Кнопка web_app открывает вашу страницу поверх чата. Страница получает данные о том, кто её открыл, во фрагменте адреса — параметр unixgramWebAppData: строка запроса с полями и подписью hash. Проверка подписи — как у Telegram, но ключ выводится из хеша секретной половины токена (сам токен мы не храним):

import hashlib, hmac, urllib.parse

def check(init_data: str, token: str) -> bool:
    fields = dict(urllib.parse.parse_qsl(init_data))
    received = fields.pop("hash")
    check_string = "\n".join(f"{k}={v}" for k, v in sorted(fields.items()))
    secret_half = token.split(":", 1)[1]
    key = hmac.new(b"WebAppData", hashlib.sha256(secret_half.encode()).digest(), hashlib.sha256).digest()
    return hmac.compare_digest(hmac.new(key, check_string.encode(), hashlib.sha256).hexdigest(), received)

JavaScript-моста вида window.Telegram.WebApp нет: кнопок внизу, событий закрытия и темы страница не получает.

Платежи#

1. sendInvoice — в чате появляется счёт с кнопкой «Оплатить N ⭐».
2. Человек нажимает кнопку — боту приходит pre_checkout_query.
3. Бот за 10 секунд отвечает answerPreCheckoutQuery: проверьте, что товар есть и цена в силе.
4. Звёзды списываются, в чат приходит служебное сообщение, боту — message с successful_payment.

Деньги получает владелец бота. Доход три дня находится на удержании — в это время возможен возврат через refundStarPayment; потом его можно вывести в разделе «Мои боты».

Типы#

Поля, которых нет в ответе, отсутствуют, а не равны null.

Отличия от Telegram#

• Нет инлайн-режима (inline_query) и платёжных провайдеров — только звёзды.
• file_id — прямой URL файла; getFile не нужен.
• banChatMember исключает, но не блокирует; promoteChatMember знает одну роль — администратор.
• Группа — тип group; супергрупп и каналов в Bot API пока нет.
• Счёт оплачивается один раз — для второго покупателя отправьте новый.

Библиотеки#

Python: unixgram-py#

Наша библиотека в форме pyTelegramBotAPI, без зависимостей, Python 3.9+.

pip install unixgram-py

from unixgram import Bot, InlineKeyboardMarkup, InlineKeyboardButton

bot = Bot("123456789:AAH...")

@bot.message_handler(commands=["start"])
def start(message):
    kb = InlineKeyboardMarkup()
    kb.row(InlineKeyboardButton("Нажми", callback_data="ping"))
    bot.send_message(message.chat.id, "Привет!", reply_markup=kb)

@bot.callback_query_handler(func=lambda q: q.data == "ping")
def on_ping(query):
    bot.answer_callback_query(query.id, "Понг!", show_alert=True)

bot.polling()

aiogram 3#

Бот для Telegram переносится сменой адреса сервера:

from aiogram import Bot
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer

session = AiohttpSession(api=TelegramAPIServer(
    base="https://unixgram.com/api/bot/{token}/{method}",
    file="https://unixgram.com/{path}",
))
bot = Bot(token="123456789:AAH...", session=session)

Любая другая библиотека Bot API подключается так же — замените https://api.telegram.org/bot на https://unixgram.com/api/bot/. Остальное — в Client API, если вашей программе нужно больше, чем умеют боты.