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

Настройка бота через BotFather для mini-app

Создашь бота, привяжешь HTTPS URL Mini App через Menu Button и проверишь запуск из Telegram.

BotFather и точка входа

Mini App открывается по HTTPS URL, который ты регистрируешь у бота. Через @BotFather создаёшь бота, получаешь токен и указываешь, откуда запускать WebApp: Menu Button, кнопка клавиатуры web_app или прямая ссылка t.me/<bot>/<app>.

Без валидного HTTPS URL клиент не откроет приложение.

Создаём бота и Menu Button

В чате с BotFather (пошагово):

text
1. /newbot
   — имя (отображаемое) и username (*_bot)
   — сохрани токен: 123456:ABC-DEF...

2. /mybots → выбери бота → Bot Settings → Menu Button
   — Configure menu button
   — укажи текст кнопки, например: Open
   — укажи HTTPS URL: https://app.example.com/

3. (опционально) /newapp  — отдельное Mini App с short name
   — получишь ссылку вида https://t.me/MyBot/myapp

Программная установка Menu Button через Bot API (удобно для CI/скриптов):

typescript
// Telegram Bot API 7.0+ setChatMenuButton
// Документация: https://core.telegram.org/bots/api#setchatmenubutton

const BOT_TOKEN = process.env.BOT_TOKEN!;
const MINI_APP_URL = "https://app.example.com/";

async function setMenuButton(): Promise<void> {
  const res = await fetch(
    `https://api.telegram.org/bot${BOT_TOKEN}/setChatMenuButton`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        menu_button: {
          type: "web_app",
          text: "Open",
          web_app: { url: MINI_APP_URL },
        },
      }),
    },
  );

  const data = (await res.json()) as { ok: boolean; description?: string };
  if (!data.ok) {
    throw new Error(data.description ?? "setChatMenuButton failed");
  }
}

await setMenuButton();

Клавиатура с web_app (нужна, если используешь sendData):

typescript
// reply_markup для sendMessage — кнопка типа web_app
const replyMarkup = {
  keyboard: [
    [
      {
        text: "Открыть форму",
        web_app: { url: "https://app.example.com/form" },
      },
    ],
  ],
  resize_keyboard: true,
};

await fetch(`https://api.telegram.org/bot${BOT_TOKEN}/sendMessage`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    chat_id: 123456789,
    text: "Заполни форму:",
    reply_markup: replyMarkup,
  }),
});

Как это работает

  • Токен бота — секрет для Bot API и для HMAC initData на бэкенде. Не коммить в репозиторий.
  • Menu Button — постоянная кнопка слева от поля ввода в чате с ботом; открывает URL.
  • /newapp + short name — deep link t.me/bot/app, удобно для шаринга.
  • web_app keyboard — отдельный сценарий; только из него корректно работает sendData.

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

Указал http:// или localhost без туннеля → Telegram отклонит или не откроет. Нужен публичный HTTPS (см. деплой).

Перепутал Menu Button и Keyboard web_app → sendData из Menu Button / прямой ссылки не доставит данные боту так же, как из keyboard button.

Засветил токен в фронтенде → токен только на сервере. В Mini App его быть не должно.

Что дальше

Материалы gramdocs.tech носят образовательный характер и не являются финансовой, юридической или инвестиционной рекомендацией. Работа с блокчейном TON и токеном Gram связана с рисками потери средств. Правовая информация