Bot API

Bot API Yobi по форме совместим с Bot API Telegram: те же адреса, методы, параметры и объекты. Бота, написанного на python-telegram-bot, aiogram, Telegraf или grammY, можно перенести, поменяв базовый адрес сервера.

Как начать

1. В Yobi откройте чат с @BotMaker и отправьте /newbot.
2. Задайте имя и username бота — он должен оканчиваться на bot.
3. Получите токен вида 123:AbCdEf… и проверьте его:

curl https://yobi.chat/bot<токен>/getMe

Запросы

Адрес метода: https://yobi.chat/bot<токен>/<метод>. Параметры принимаются в строке запроса, application/x-www-form-urlencoded, application/json или multipart/form-data (для загрузки файлов). Имена методов не зависят от регистра.

Ответ: {"ok": true, "result": ...} или {"ok": false, "error_code": 400, "description": "Bad Request: ..."}. При превышении лимита — код 429 и parameters.retry_after.

Перенос существующего бота

python-telegram-bot:

from telegram.ext import ApplicationBuilder
app = (ApplicationBuilder().token(TOKEN)
       .base_url("https://yobi.chat/bot")
       .base_file_url("https://yobi.chat/file/bot")
       .build())

aiogram 3:

from aiogram import Bot
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer
session = AiohttpSession(api=TelegramAPIServer.from_base("https://yobi.chat"))
bot = Bot(TOKEN, session=session)

Telegraf (Node.js):

const bot = new Telegraf(TOKEN, { telegram: { apiRoot: 'https://yobi.chat' } });

Без библиотек, на Python:

import requests, time
API = "https://yobi.chat/bot" + TOKEN
offset = 0
while True:
    r = requests.get(API + "/getUpdates", params={"offset": offset, "timeout": 30}).json()
    for u in r["result"]:
        offset = u["update_id"] + 1
        m = u.get("message")
        if m and "text" in m:
            requests.post(API + "/sendMessage", json={"chat_id": m["chat"]["id"], "text": m["text"]})

Идентификаторы чатов

• личный чат — id пользователя (положительное число);
• группа и канал — отрицательное число вида -100…, как у супергрупп Telegram;
• публичный канал или группу можно указать как @username.

Бот не может написать пользователю первым: сначала пользователь должен начать диалог (кнопка «Запустить» отправляет /start).

Получение обновлений

Два способа, одновременно работает только один.

getUpdates (long polling): offset, limit (до 100), timeout (до 50 с), allowed_updates. Обновления с update_id меньше offset считаются подтверждёнными и удаляются. Хранятся сутки.

Вебхук: setWebhook с параметрами url (только HTTPS), secret_token, allowed_updates, drop_pending_updates. Сервер отправляет POST с объектом Update и заголовками X-Yobi-Bot-Api-Secret-Token и X-Telegram-Bot-Api-Secret-Token. Ответ 2xx подтверждает доставку, иначе запрос повторяется с нарастающей паузой до минуты. В ответе на вебхук можно сразу вызвать метод: {"method": "sendMessage", "chat_id": ..., "text": "..."}. Состояние — getWebhookInfo, отключение — deleteWebhook.

Типы обновлений: message, edited_message, channel_post, edited_channel_post, callback_query, my_chat_member, message_reaction (только если указан в allowed_updates).

Режим приватности в группах

По умолчанию бот в группе получает только команды (/команда или /команда@имя_бота), упоминания @имя_бота, ответы на свои сообщения и служебные сообщения. Бот-администратор и бот с выключенной приватностью (/setprivacy у Мастера ботов) получают все сообщения. В каналах бот получает публикации, только если он администратор.

Методы

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

parse_mode: HTML (теги b, i, u, s, code, pre, a href, tg-spoiler, blockquote), MarkdownV2 или Markdown. Вместо разметки можно передать entities — смещения в UTF-16.

Клавиатуры

• inline_keyboard — кнопки под сообщением: callback_data (до 64 байт) присылает боту callback_query, url открывает ссылку. На каждое нажатие нужно ответить answerCallbackQuery.
• keyboard — кнопки вместо обычной клавиатуры, нажатие отправляет текст кнопки. Поддерживаются one_time_keyboard, resize_keyboard, input_field_placeholder.
• remove_keyboard: true — убрать клавиатуру.

Опросы

sendPoll создаёт опрос или викторину. Если опрос неанонимный, бот получает poll_answer на каждый голос; после stopPoll или окончания open_period — обновление poll с итогами.

Инлайн-режим

Включается в Мастере ботов командой /setinline (там же задаётся подсказка в поле ввода). Пользователь набирает @ваш_бот запрос в любом чате — бот получает inline_query и в течение 10 секунд отвечает answerInlineQuery. Поддерживаемые результаты: article (с input_message_content), photo, gif, mpeg4_gif (по *_url или *_file_id), sticker, document, video, audio, voice (по *_file_id). Отправленное сообщение помечается «через @бота». chosen_inline_result приходит, если указать его в allowed_updates.

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

Кнопки web_app (под сообщением, в клавиатуре или кнопкой меню через /setmenubutton и setChatMenuButton) открывают ваш сайт внутри Yobi. Подключите на странице https://yobi.chat/js/telegram-web-app.js — он совместим с официальным telegram-web-app.js (window.Telegram.WebApp): initData, MainButton, BackButton, sendData, showPopup, close и др. Пример: https://yobi.chat/webapp/demo.

initData подписана так же, как в Telegram: secret = HMAC_SHA256(key="WebAppData", msg=<токен бота>), hash = hex(HMAC_SHA256(key=secret, msg=data_check_string)), где data_check_string — пары ключ=значение без hash, отсортированные по ключу и разделённые \n. Приложение из кнопки клавиатуры отправляет sendData — бот получает сообщение с web_app_data. Приложение из кнопки под сообщением или меню получает query_id и отвечает через answerWebAppQuery.

Игры и приложения в диалогах

setMyActivities, getMyActivities, deleteMyActivities объявляют действия для двоих в окне «Игры и приложения» личного диалога. Бот получает событие activity_session, обновляет карточку приглашения методом editActivitySession и сообщает итог через finishActivitySession; getActivitySession возвращает текущее состояние. Подробно — Игры и приложения.

Платежи

sendInvoice выставляет счёт; пользователь заполняет форму, бот получает pre_checkout_query и в течение 10 секунд отвечает answerPreCheckoutQuery. После списания в чат приходит сообщение с successful_payment. Для проверки используйте provider_token: "TEST" — тестовый провайдер подтверждает оплату без списания денег. Настоящий провайдер подключается на сервере (интерфейс PaymentProvider).

Ограничения

• не больше 100 команд, текст сообщения — до 4096 символов;
• файлы по URL: фото до 20 МБ, остальное до 50 МБ;
• загрузка файлов напрямую — до лимита сервера (по умолчанию 2 ГБ);
• игры, доставка с расчётом стоимости (is_flexible) и Telegram Stars пока не поддерживаются.