@twa-dev/sdk: Как создавать Telegram Мини-приложения, которые реально работают

Если вы создаёте Telegram Мини-приложение и читаете официальную документацию, то заметите, что там упоминается «сырой» объект window.Telegram.WebApp. Он работает — но громоздкий, нетипизированный и неудобный в современных фреймворках. Именно здесь на помощь приходит @twa-dev/sdk.

Пакет @twa-dev/sdk — это неофициальная, но широко используемая TypeScript-обёртка над Telegram Web App API. Она даёт полную типобезопасность, более чистый синтаксис и значительно лучший опыт разработки — без какой-либо лишней нагрузки. Если вы серьёзно занимаетесь разработкой на Telegram Мини-приложениях, это именно тот SDK, который вам нужен.

Что на самом деле делает @twa-dev/sdk

Официальный Telegram Web App API доступен через глобальный JavaScript-объект, который внедряет клиент Telegram. Для простых скриптов это работает нормально, но как только вы оказываетесь в проекте на React, Vue или Svelte, работа с сырыми глобальными переменными быстро превращается в хаос.

@twa-dev/sdk оборачивает этот глобальный объект в типизированный, импортируемый модуль. Вот что вы получаете из коробки:

• Полные TypeScript-типы — автодополнение для каждого метода, события и свойства

• Чистые импорты — используйте import WebApp from '@twa-dev/sdk' вместо обращения к window.Telegram.WebApp

• Совместимость с реактивными фреймворками — отлично работает с React, Vue и другими компонентными фреймворками

• Актуальность — пакет следит за официальным Telegram API, так что вам не придётся поддерживать собственные объявления типов

Это тонкая прослойка. Никакой магии и никакого сокрытия основного API. Думайте о нём как о строго типизированном интерфейсе, а не как о фреймворке.

Как установить и настроить

Установка занимает около 30 секунд:

npm install @twa-dev/sdk

npm install @twa-dev/sdk

npm install @twa-dev/sdk

Затем импортируйте там, где это нужно:

import WebApp from '@twa-dev/sdk'

import WebApp from '@twa-dev/sdk'

import WebApp from '@twa-dev/sdk'

Всё. Теперь у вас есть доступ ко всему Telegram Web App API — данные пользователя, темы оформления, кнопки, попапы, тактильная обратная связь и многое другое.

Минимальный рабочий пример

Вот простой React-компонент, который получает информацию о текущем пользователе и сигнализирует о готовности приложения:

import WebApp from '@twa-dev/sdk'
import { useEffect } from 'react'

export default function App() {
  useEffect(() => {
    WebApp.ready()
    console.log(WebApp.initDataUnsafe.user)
  }, [])

  return <div>Привет, {WebApp.initDataUnsafe.user?.first_name}</div>
}

import WebApp from '@twa-dev/sdk'
import { useEffect } from 'react'

export default function App() {
  useEffect(() => {
    WebApp.ready()
    console.log(WebApp.initDataUnsafe.user)
  }, [])

  return <div>Привет, {WebApp.initDataUnsafe.user?.first_name}</div>
}

import WebApp from '@twa-dev/sdk'
import { useEffect } from 'react'

export default function App() {
  useEffect(() => {
    WebApp.ready()
    console.log(WebApp.initDataUnsafe.user)
  }, [])

  return <div>Привет, {WebApp.initDataUnsafe.user?.first_name}</div>
}

WebApp.ready() сообщает Telegram, что приложение загрузилось и индикатор загрузки можно скрыть. Всегда вызывайте его как можно раньше. Если пропустить — пользователи будут видеть бесконечный спиннер.

Функции, которые вы будете использовать чаще всего

Telegram Web App API достаточно широкий. Вот части, к которым вы будете обращаться почти в каждом проекте:

MainButton

MainButton — это заметная CTA-кнопка, которая появляется внизу Мини-приложения. Вы полностью управляете ею:

WebApp.MainButton.setText('Оформить заказ')
WebApp.MainButton.show()
WebApp.MainButton.onClick(() => handleSubmit())

WebApp.MainButton.setText('Оформить заказ')
WebApp.MainButton.show()
WebApp.MainButton.onClick(() => handleSubmit())

WebApp.MainButton.setText('Оформить заказ')
WebApp.MainButton.show()
WebApp.MainButton.onClick(() => handleSubmit())

Это один из самых заметных элементов UI в Мини-приложении. Используйте её для основных действий — оплата, подтверждение, отправка — и скрывайте, когда она не актуальна для текущего экрана.

initDataUnsafe

Даёт вам данные текущего пользователя Telegram: ID, имя, никнейм, код языка и наличие Premium. Называется «unsafe» («небезопасный»), потому что это клиентские данные — всегда проверяйте их на сервере с помощью initData и токена бота, прежде чем доверять им что-то важное.

HapticFeedback

Маленькая деталь с большим эффектом. Тактильная обратная связь делает ваше приложение по-настоящему нативным на мобильных устройствах:

WebApp.HapticFeedback.impactOccurred('medium')
WebApp.HapticFeedback.notificationOccurred('success')

WebApp.HapticFeedback.impactOccurred('medium')
WebApp.HapticFeedback.notificationOccurred('success')

WebApp.HapticFeedback.impactOccurred('medium')
WebApp.HapticFeedback.notificationOccurred('success')

Тема и цветовая схема

Telegram передаёт текущую тему пользователя (светлую/тёмную) и цветовые переменные. Используйте WebApp.colorScheme и CSS-переменные, которые внедряет Telegram (--tg-theme-bg-color и другие), чтобы соответствовать нативному виду без лишних настроек.

sendData и close

WebApp.sendData() отправляет строковые данные обратно вашему боту. Используйте это для простых форм, когда боту нужно обработать ввод пользователя. WebApp.close() закрывает Мини-приложение — вызывайте его по завершении сценария.

@twa-dev/sdk против сырого window.Telegram.WebApp — что выбрать?

Честно? Используйте @twa-dev/sdk для любого проекта, в котором больше одного разработчика или сложность выше, чем на выходные.

• Если вы делаете прототип маленького скрипта — сырой API подойдёт

• Если вы работаете на React, Vue или в TypeScript-проекте — используйте SDK

• Если хотите ловить ошибки на этапе компиляции, а не в рантайме — используйте SDK

Сырой API никуда не денется. Но SDK избавит вас от написания собственных объявлений типов, опечаток в именах методов и ошибок, которые обнаруживаются только на устройстве пользователя в два часа ночи.

Для более глубокого погружения в то, как работает основной API и что на нём можно построить, читайте нашу статью о Telegram Mini App API.

Безопасность: не доверяйте initDataUnsafe на сервере

Это ошибка, на которую натыкается большинство на раннем этапе. initDataUnsafe — это данные, предоставленные клиентом. Их может подделать кто угодно. Если вы используете их для идентификации пользователей на бэкенде, вы строите на песке.

Правильный подход:

1. Отправьте сырую строку WebApp.initData на сервер (не initDataUnsafe)

2. На сервере проверьте HMAC-подпись с помощью токена вашего бота

3. Доверяйте данным пользователя только после прохождения этой проверки

Telegram документирует алгоритм верификации в официальной документации. Это несложно — несколько строк на любом серверном языке. Не пропускайте этот шаг. Подробнее о соображениях безопасности для Мини-приложений читайте в нашей статье о безопасности Telegram Мини-приложений.

Создание продакшн-приложений в Telegram

Когда ваше Мини-приложение готово, следующая задача — интегрировать его в реальные продажи и бизнес-процессы. Именно здесь проявляется разница между «классным демо» и «действительно полезным инструментом».

Если вы создаёте продажи или CRM-воронку на базе Telegram — а не просто разовое Мини-приложение — обратите внимание на CRMChat API. Он позволяет выстраивать кастомные интеграции с Telegram: отправлять лиды из Мини-приложения в CRM-пайплайн, запускать последовательности аутрича или синхронизировать данные переписки, не выстраивая всю инфраструктуру с нуля.

Для общего понимания того, как Telegram вписывается в современный процесс продаж, эта статья об интеграции CRM с Telegram хорошо раскрывает практическую сторону вопроса.

Коротко о главном

@twa-dev/sdk — это правильный выбор по умолчанию для всех, кто создаёт Telegram Мини-приложения на современном JS/TS-стеке. Установите, импортируйте, вызывайте WebApp.ready() как можно раньше, валидируйте initData на сервере и используйте MainButton для основных CTA.

Поверхность API большая, но хорошо задокументированная. Не нужно изучать всё сразу. Начните с initDataUnsafe, MainButton и sendData — это покрывает 80% того, что делает большинство Мини-приложений.