Skip to main content

Mini Apps

Мини-приложения — это веб-страницы, которые открываются прямо внутри Telefon с доступом к Telefon API.

Когда использовать​

  • Магазин с корзиной и оплатой
  • Форма заказа / заявка
  • Калькулятор / конвертер
  • Список товаров с фильтрами
  • Бронирование
  • Игры

Запуск Mini App​

Бот шлёт inline-кнопку с web_app:

{
  "chat_id": 12345,
  "text": "Откройте магазин:",
  "reply_markup": {
    "inline_keyboard": [[
      {"text": "🛍 Открыть", "web_app": {"url": "https://shop.example.com"}}
    ]]
  }
}

При тапе откроется ваш URL внутри Telefon с доступом к JS API.

Привязка к боту​

В настройках бота → секция Mini App → введите URL и текст кнопки меню. Эта кнопка будет видна в шапке чата с ботом.

JS API внутри мини-аппы​

<script src="https://telefon.chat/web-app.js"></script>
<script>
  const tg = window.Telefon.WebApp;
  tg.ready();

  // Данные пользователя
  console.log(tg.initData);
  console.log(tg.initDataUnsafe.user);

  // Главная кнопка снизу
  tg.MainButton.setText('Заказать').show();
  tg.MainButton.onClick(() => {
    tg.sendData(JSON.stringify({order: 'pizza'}));
    tg.close();
  });

  // Тема
  tg.setHeaderColor('#0a84ff');
  if (tg.colorScheme === 'dark') {
    document.body.classList.add('dark');
  }
</script>

Получение данных в боте​

После tg.sendData(...):

{
  "update_id": 123,
  "message": {
    "web_app_data": {
      "data": "{\"order\": \"pizza\"}",
      "button_text": "Заказать"
    },
    ...
  }
}

Проверка подлинности initData​

initData содержит подписанные данные пользователя. Проверять обязательно:

import hashlib, hmac
from urllib.parse import parse_qsl

def verify_init_data(init_data: str, bot_token: str) -> bool:
    parsed = dict(parse_qsl(init_data))
    received_hash = parsed.pop('hash')
    sorted_pairs = sorted(parsed.items())
    data_check_string = '\n'.join(f'{k}={v}' for k, v in sorted_pairs)
    secret_key = hmac.new(b'WebAppData', bot_token.encode(), hashlib.sha256).digest()
    expected_hash = hmac.new(secret_key, data_check_string.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected_hash, received_hash)

Прямая ссылка на Mini App с параметром:

https://telefon.chat/<BOT_USERNAME>?startapp=PARAMETER

Параметр PARAMETER приходит в initData как start_param. Удобно для deep-linking — например, ссылка на конкретный товар.

Готовые шаблоны​

  • Открытые мини-приложения на GitHub — большинство совместимы с нашей платформой.
  • React-обёртка для удобного использования API доступна как npm-пакет в виде хуков (useWebApp, useMainButton и т.д.).