Web Apps в Telegram
Безусловно,сейчас все обсуждают последнее обновление Telegram Bot API, в котором были добавлены Web Apps — кастомные страницы, которые открываются прямо внутри переписки с ботами!
Нам начало поступать множество вопросов от клиентов касательно этой новой фичи, поэтому мы решили подробно пройтись по документации API и разложить все по полочкам. Поехали:
1. Как отобразить пользователю Web App?
Сейчас доступно 3 способа: по нажатию на reply-кнопку, по нажатию на inline-кнопку, по нажатию на кнопку «Меню» внутри бота (за которой раньше скрывался список команд). Во всех способах пользователю открывается указанный вами URL по HTTPS, поэтому вам нужно иметь собственный веб-сервер с SSL-сертификатом для отображения страниц.
2. Как боты общаются с Web Apps?
Это происходит через специальный объект Telegram.WebApp, который вы можете использовать с помощью JavaScript внутри своей кастомной страницы. Кроме этого, никто не запрещает передавать в URL открытия Web App’а нужные вам параметры для получения информации о юзере.
3. Как сделать интерфейс для Web App?
Доступны все возможности HTML, CSS и JavaScript, без каких-либо ограничений (по крайней мере, они не описаны в документации). Важно понимать, что у всех пользователей разные размеры экрана и цветовые настройки, поэтому при разработке Web App нужно учитывать множество вариантов, благо Telegram с этим помогает.
#8 – Web Apps. Полноценные веб приложения в Телеграм
Одним из новшеств Телеграм Ботов являются Веб приложения. За урок мы научимся создавать Web Apps, работать с их API, выводить данные про пользователя, а также получать информацию из Web App.
Видеоурок
Полезная ссылка:
- Документация по Web Apps
Веб приложения были добавлены не так давно в Телеграм и уже стали очень популярным инструментом. Благодаря Web Apps вы можете добавить к вашему боту полноценное веб приложения, что может быть сайтом, игрой, магазином или чем-то еще.
Создание таковых веб приложений вовсе не сложный процесс. Для их создания требуется прописать веб сайт, что по итогу подгружается в мини-браузер в вашем телеграм боте.
Telegram WebApps. Как встроить веб-приложения в чат-бота?
Относительно недавно команда Telegram выпустила обновление, с которым появилась возможность встраивать в мессенджер веб-приложения. Как заявляют разработчики: «Telegram-бот нового поколения станет полноценной заменой любому сайту».
Встроенные веб-приложения поддерживают авторизацию пользователя (проверку его подлинности), встроенную оплату через различных провайдеров, кастомизацию под выбранную пользователем тему и многое другое. И все это на JavaScript.
Эта статья — обзор основных моментов внедрения веб-приложениий в телеграм-ботов. Она написана скорее для новичков или тех, кто хочет быстро узнать, «что к чему».
Внедряем веб-приложения
Веб-приложения для встраивания Telegram поддерживает только защищенные протоколом HTTPS. Для тестирования вы можете обеспечить его самостоятельно с помощью самописного сертификата.
Переход к ним стал возможен через инлайн-кнопки (InlineKeyboardButton) и кнопки клавиатуры (KeyboardButton): к соответствующим типам был добавлен параметр web_app, необходимое значение для которого — добавленный тип WebAppInfo со ссылкой на веб-приложение. Пример реализации:
# Python 3: AIOgram v2.23.1 from aiogram import InlineKeyboardButton, KeyboardButton, WebAppInfo # . ikb = InlineKeyboardButton("Перейти", web_app=WebAppInfo('https://')) kb = KeyboardButton("Перейти", web_app=WebAppInfo('https://')) # . 
Переход к одному веб-приложению возможен через меню: его можно закрепить с помощью BotFather. А также через закрепленные: достаточно создать кнопку с обычной ссылкой на бота (например, с помощью тех-же инлайн-кнопок) с параметром startattach — InlineKeyboardButton(«Перейти», url=’https://t.me/?startattach’) ; однако переход через закрепленные оказывается доступным не для всех ботов.
Программируем веб-приложение
Чтобы подключать веб-приложение к пользователю Telegram, достаточно вставить в HTML-код страницы скрипт telegram-web-app.js в тег до всех скриптов:
После его подключения в скриптах, объявленных после, мы можем пользоваться всеми возможностями Telegram WebApps с помощью объекта window.Telegram.WebApp.
Список методов и объектов в window.Telegram.WebApp достаточо большой, полностью ознакомиться с каждым из них вы можете здесь. Например, вы можете поприветствовать пользователя, который перешел в веб-приложение через бота:
var WebApp = window.Telegram.WebApp; WebApp.showAlert(`Добро пожаловать, @$.`);
Также мы можем обрабатывать различные события. Например, нажатие «главной» кнопки (MainButton) или кнопки «Назад» (BackButton), причем несколькими способами:
var MainButton = WebApp.MainButton; var BackButton = WebApp.BackButton; MainButton.show(); BackButton.show(); MainButton.onClick(function() < WebApp.showAlert("Хорошо, ты нажал на главную кнопку."); >); WebApp.onEvent('mainButtonClicked', function() < /* also */ >); BackButton.onClick(function() < WebApp.showAlert("Нет пути назад!"); BackButton.hide(); >); WebApp.onEvent('backButtonClicked', function() < /* also */ >);Особый интерес представляет возможность перейти к встроенной оплате из веб-приложения. Сделать это можно через метод openInvoice. Однако прежде необходимо сформировать ссылку на оплату (инвоис-линк). Формировать ее прямо в скрипте с помощью запроса к Telegram API оказывается плохой идеей, так-как для этого потребуется раскрыть секретные данные бота (токены бота, провайдера оплаты и т.п.). Поэтому формировать ее следует, например, на сервере веб-приложения (через бота), а из скрипта сделать запрос к нему:
let xhrURL = new URL('https:///'); xhrURL.searchParams.set('title', . ); /* . setting other non-private optional parameters */ let xhr = new XMLHttpRequest(); xhr.open('GET', xhrURL); xhr.send(); xhr.onload = function()
После чего у нас будет открываться карточка товаров/услуг с возможностью их оплатить. На примере встроенной в веб-приложение оплаты Liot:
Также мы можем обрабатывать события после закрытия окна оплаты:
WebApp.onEvent('invoiceClosed', function(object) < if (object.status == 'paid') < WebApp.close(); >else if (object.status == 'failed') < WebApp.showAlert("Не беспокойтесь. Мы сохраним ваш выбор."); >>);Особое внимание стоит уделить безопасности. Для проверки подлинности пользователя («Настоящий ли пользователь зашел в веб-приложение и через Telegram ли?») предусмотрен способ валидации получаемых [через скрипт] данных.
Содержимое переменной initData [в window.Telegram.WebApp] представляет из себя строку формата ключ=значение , разделенных & — в общем и целом, параметры для поиска в ссылках. Формат включает в себя параметры auth_date, query_id, user и hash. Из этой строки состоит еще одна — data-check-string. Она включает в себя почти те же параметры, кроме hash, только отсортированные и разделенные \n . Именно она участвует в валидации.
Следующее значение, участвующее в валидации — secret_key. Оно представляет из себя хэш варианта HMAC-SHA-256 по значению токена бота и ключу «WebAppData» .
И так, по условию, если хэш варианта HMAC-SHA-256 по значению data-check-string и ключу secret_key равно hash [из initData], значит пользователь подлинный. Какой псевдо-код демонстрируют разработчики:
data_check_string = . secret_key = HMAC_SHA256(, "WebAppData") if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) < // data is from Telegram >Очевидно, что генерировать secret_key и валидировать следует на стороне, например, на сервере, чтобы не раскрыть токен бота. Пример реализации:
let initDataURLSP = new URLSearchParams(WebApp.initData); var hash = initDataURLSP.get('hash'); initDataURLSP.delete('hash'); initDataURLSP.sort(); var checkDataString = initDataURLSP.toString().replaceAll('&', '\n'); let xhrURL = new URL('https:///'); xhrURL.searchParams.set('hash', hash); xhrURL.searchParams.set('checkDataString', checkDataString); let xhr = new XMLHttpRequest(); xhr.open('GET', xhrURL); xhr.send(); xhr.onload = function() < if (JSON.parse(xhr.response).result == true) < WebApp.showAlert(`Добро пожаловать, @$.`); > else < WebApp.showAlert("Ты что, хакер?"); WebApp.close(); >>Дизайн веб-приложения можно подстраивать под пользователя с помощью объекта ThemeParams, внутри которого содержатся подстроенные под выбранную пользователем тему мессенджера: фон, текст, ссылки и т.п. При этом, вы можете использовать их не только в скриптах, но и в стилях (CSS) с помощью var :
h1 < color: var(--tg-theme-text-color); >p < color: var(--tg-theme-hint-color); >/* . */
Возможности встроенного в чат-бот веб-приложения вы можете также увидеть на примере Liot — концептуального телеграм-бота для записи в один из салонов красоты. Он же на ГитХабе по ссылке.
Надеюсь, вы смогли из этой статьи вынести для себя что-то полезное 🙂
Разработка Web Apps в Telegram: инструкция
Telegram Web Apps – это Telegram Bot + Web App, интернет-магазин или сайт в Телеграмме. Технология является аналогом VK Mini Apps ВКонтакте.
Официальный релиз Веб Апп Телеграмма состоялся 16 апреля 2022 (Bot API 6.0). На момент написания статьи ТГ предлагает работать с Bot API 6.7 от 21 апреля 2023 (добавлены метод switchInlineQuery и возможность открыть веб-приложения по прямой ссылке).
Что такое Web App Telegram: примеры, как выглядит, как работает
Если коротко – как сайт (интернет-магазин, витрина), только в Телеграмме.
WebApp боты – это PWA, т.е. Progressive Web Apps, которые запускаются внутри WebView.
Официальный пример Telegram Web App bot example – @DurgerKingBot. Вот как он выглядит после перехода и запуска (клик на start).
Веб-приложение в Телеграмме выглядит как сайт (интернет-магазин) и позволяет:
- разместить витрину товаров или услуг;
- внедрить корзину и форму заказа с заполнением данных;
- подключить системы оплаты (в том числе с использованием Google Pay and Apple Pay);
- настроить пуш-уведомления;
- интегрировать веб-приложения Телеграмма с учетной системой или CRM (iiko, RetailCRM, Битрикс24, VirtualPOS, Workabox, amoCRM, ClientBase или прочими);
- подключить поиск по каталогу и сделать многое другое.
Мы в ChatLabs протестировали разработку WebApp в Телеграмм буквально через несколько недель после того, как в ТГ анонсировали функционал. Пример реального веб-бота, разработанного для интернет-магазина доставки еды, ниже.
Но на самом деле веб-ботов в Телеграмме можно заказать не только для служб доставки. Telegram WebApp используют для:
- интернет-магазинов;
- онлайн-школ;
- курсов и марафонов;
- ресторанов и кафе;
- отелей, хостелов, усадеб и многих других бизнесов.
Разработку Telegram Web App bot заказывают для квизов, онлайн-бронирования, геймификации, проведения акций и розыгрышей, запуска опросов или любых других задач.
ChatLabs разрабатывает Web App bot с нуля без использования конструкторов. О том, какие подводные камни имеют боты на конструкторах, рассказывали в отдельном материале. Если коротко: бот на конструкторе – это ежемесячная плата за использование (около 3000 рублей в зависимости от тарифа и количества контактов), хранение бота на «чужом хостинге», невозможность масштабирования и внедрения нетиповых настроек.
Создание бота Telegram Web App: как сделать веб-приложение для Телеграмм самостоятельно
Пошаговая инструкция, как создать Telegram bot WebApp, подразумевает действия:
- Создать бота через @BotFather (/newbot). Нужно задать ему имя и получить токен (API-ключ) для доступа к HTTP API Telegram. Не передавайте Token третьим лицам!
- Создать новое приложение с использованием команды /newapp. BotFather попросит указать название и короткое описание (description), загрузить фото и выставить настройки.
- Разработать клиентское приложение Telegram Web App js, используя любые frontend-технологии (HTML, CSS, JavaScript (ES6), Vue.js, React). Back end можно писать на Питоне (Python), node js или других.
Создать веб-приложение в Телеграмм через @BotFather
О том, как создать чат-бота в Телеграмме с использованием @BotFather, мы рассказывали в отдельной инструкции. Поэтому перейдем сразу к тому, как сделать веб-бота через команду /newapp.
- /newapp – BotFather спрашивает, к какому чат-боту нужно привязать веб-приложение (указываем через @);
- title for the web app – название веб-бота (к примеру, ChatLabsWebApp);
- short description of the web app – короткое описание (в нашем примере это «ChatLabsWebApp – веб-приложение, как создавать»);
- upload a photo, 640×360 pixels – загрузка логотипа (дальше система предложит загрузить gif, но командой /empty можно пропустить этот шаг и вернуться к нему позже, используя /editapp);
- выбрать Web App URL – прямая ссылка, по которой будет открываться приложение (к примеру, мы указали https://chatlabs.ru/);
- short name for your web app – параметр, который будет использоваться в short_name Bot API (нужно для разработки).
BotFather выдаст ссылку, по которой нужно перейти для старта разработки веб-бота для Телеграмм.
Чтобы найти нужного веб-бота, используйте команду /myapps. После ее ввода BotFather предложит список созданных Web Apps в Telegram.
В примере с ChatLabsWebApp это:
- Edit Title – редактировать тайтл;
- Edit Description – редактировать дескрипшн (описание);
- Edit Photo – редактировать фото;
- Edit Web App URL – редактировать урл (ссылку);
- Delete Web App – удалить веб-приложение.
Поздравляем! Вы создали веб-бота (сайт) в Телеграмм самостоятельно и без навыков программирования. Правда, пока он полноценно работать не сможет. При клике по ссылке появляется ошибка: «Не удалось найти IP-адрес сервера».
В Телеграмме веб-приложение не работает, т.к. нам нужен хостинг, домен, бэкенд (Web Apps Telegram Python) и база данных (MySQL, MariaDB, PostgreSQL, SQLite, MongoDB, RethinkDB), а также frontend-часть.
Чтобы после создания бота Web App Telegram bot Python, node js начал работать и выглядел так, как было задумано, нужны навыки программирования.
Разработка веб-бота (интернет-магазина) для Телеграм с Web Apps на JS
Для разработки веб апс в Телеге нужно изучить API. Application Programming Interface Телеграм находится по ссылке: методы, сущности, параметры, функции.
На основе API можно вывести, какие опции можно подключить к веб-боту Webapp TG (промокоды, оповещения, история заказов, рассылка по пользователям, загрузка товаров в веббот, перевод заказов в различные состояния, статистика новых юзеров web-app, подключение ЮКассы, рассылка по пользователям и так далее).
Чтобы упростить для Telegram WebApp создание бота, используют библиотеки. К примеру:
- pyTelegramBotAPI (Питон);
- Node.js Telegram Bot API (Нод Джс);
- Nutgram или Telegraph (PHP);
- Golang Telegram Bot library, Telegrambot, Telego (Go);
- Frankenstein, Ferrisgram, tgbotapi (Rust);
- TelegramBotAPI, Telegram Bot API in Kotlin Multiplatform, Kotlin Telegram Bot (для Kotlin)
- Telegram Vapor Bot, Telegrammer (Web Apps Telegram бот на Swift);
- TelegramBots или ReBot (Java), а также многие другие.
Список с примерами библиотек для Телеграм-бота Bot API Library Examples находится на сайте Телеграмма.
Чтобы создать Telegram bot интернет-магазин (веб-приложение) с минимальным функционалом – карточками товара и характеристиками на node.js – нужно сделать проект (используем IDE вроде Microsoft Visual Studio, Xcode, Webstorm для удобства), настроить окружение и установить зависимости.
Node.js скачивается с официального сайта. Поскольку мы разрабатываем Телеграм WebApp на node.js, используем библиотеку node-telegram-bot-api (она появится в зависимостях – dependencies). Чтобы установить зависимости проекта Telegram Bot API, заходим в папку и используем команду:
Для запуска проекта используем команду:
yarn run start
Если используете пакет npm, то команда будет npm install node-telegram-bot-api + изменится команда для старта.
В папке проекта нужно создать минимум 2 файла:
- index.js – входной файл с кодом WebApp Телеграмм;
- package.json – пакет с зависимостями.
В файле package.json должен быть код:
< "name": "webapp", // название веб-приложения – может быть любым: webAppTG, WebAppTelegram // "version": "0.0.1", // название веб-приложения – версия// "license": "MIT", // лицензия // "scripts": < "start" : "node index.js" >, "dependencies": < "node-telegram-bot-api": "^0.61.0" >> // зависимости – библиотека, которая должна быть установлена для работы проекта
Обратите внимание, что комментарии указаны справочно (для отображения, что происходит в коде и понимания). В реальном проекте в package.json комментарии нужно убирать, т.к. будет показывать ошибку.
В файле index.js должен быть код:
const TelegramBot = require('node-telegram-bot-api'); // подключаем (инициализируем) библиотеку, которую установили ранее const token = 'Указываем в кавычках токен, который выдал Телеграм' // задаем токен, сам API-ключ храним в отдельном файле // const bot = new TelegramBot('token', ); // создаем bot, polling в значении true необходим для получения обновлений с серверов ТГ, чтобы бот работал корректно// function formatProductCaption(product) < return `*$*\nPrice: $\nDescription: $`; > // функция formatProductCaption принимает переменную product и возвращает название, цену, описание, но вы можете добавлять другие необходимые поля// const products = [ < id: 1, name: 'Product 1', price: '$10', description: 'Description of Product 1', imageUrl: 'https://plus.unsplash.com/premium_photo-1684534125661-614f59f16f2e?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=1170&q=80' >, < id: 2, name: 'Product 2', price: '$20', description: 'Description of Product 2', imageUrl: 'https://images.unsplash.com/photo-1594212699903-ec8a3eca50f5?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=1171&q=80' >, ]; // создаем массив products, в котором лежат товары с нужными нам переменными: id, name, price, description, imageUrl // bot.onText(/\/start/, async (msg) => < const chatId = msg.chat.id; const response = 'Привет! Добро пожаловать в Telegram Bot web app!\n\nЗдесь есть вот такие товары:'; // Проходимся по массиву products методом map и создаем сами карточки // const messageOptions = products.map((product) =>< return < chat_id: chatId, photo: product.imageUrl, caption: formatProductCaption(product), parse_mode: 'Markdown' >; >); await bot.sendMessage(chatId, response); // Отправляем сообщение с карточками продуктов await Promise.all(messageOptions.map((options, index) => < return bot.sendMessage(options.chat_id, options.caption, < parse_mode: options.parse_mode, reply_markup: < inline_keyboard: [[`>]] > >); >)); >); bot.on('callback_query', async (query) => < console.log('Здесь сообщение'); const chatId = query.message.chat.id; const data = query.data; if (data === 'back') < // Отправляем карточки продуктов при запросе через inline keyboard return sendProductList(chatId, 'Посмотрите, вот здесь есть продукты:'); >const productId = data.split('_')[1]; const selectedProduct = products[productId]; if (selectedProduct) < await bot.sendPhoto(chatId, selectedProduct.imageUrl, < caption: formatProductCaption(selectedProduct), parse_mode: 'Markdown', reply_markup: < inline_keyboard: [[]] > >); > >); async function sendProductList(chatId, response) < await bot.sendMessage(chatId, response); const messageOptions = products.map((product, index) =>< return < chat_id: chatId, photo: product.imageUrl, caption: formatProductCaption(product), parse_mode: 'Markdown', callback_data: `product_$` // Изменяем значение callback_data value >; >); await Promise.all(messageOptions.map((options, index) => < return bot.sendMessage(options.chat_id, options.caption, < parse_mode: options.parse_mode, reply_markup: < inline_keyboard: [[]] > >); >)); > console.log('Бот запускается. '); После запуска простейший Telegram Web App example выглядит таким образом и работает локально:
Работа со статикой в веб-приложении Телеграмма
Веб-приложение Телеграмм разрешает указывать ссылки на свои источники. К примеру, мы можем добавить на кнопку тест ссылку https://telegram/chatlabs.ru/, а пользователь увидит наш контент внутри попапа. По сути, как будто бы работает браузер поверх мессенджера.
В каждой точке входа статики нужно указать:
Чтобы передать данные со нашего статического сайта в Телеграмм-бот и обеспечить двустороннее сообщение, используются методы (sendMessage, deleteMessage, sendData и другие с передачей нужных параметров).
В index.html необходимо указать:
Telegram WebApps API от ChatLabs После того, как подключили скрипт через , становится доступен объект window.Telegram.WebApp со следующими полями:
Подробнее про Initializing Web Apps в веб-приложении Телеграмма в API.
Дальше в тегах и задаем дизайн карточек и кнопок, указываем расположение элементов и т.д. – в общем, работаем с визуальной частью и версткой:
body < display: flex; color: var(--tg-theme-text-color); background: var(--tg-theme-bg-color); align-items: center; flex-direction: column; font-size: 20px; >.hint < color: var(--tg-theme-hint-color); >.link < color: var(--tg-theme-link-color); >.button < background: var(--tg-theme-button-color); color: var(--tg-theme-button-text-color); border: none; font-size: 20px; >.button:not(:last-child) < margin-bottom: 15px >#usercard Здесь текст о компании ChatLabs
Ссылка на ChatLabs Текст подсказки от ChatLabs
Если проект большой, то стили обычно выносят в отдельный файл .css, а затем подключают к index.html.
На этом заканчивается «дизайновая часть». Начинается фронтенд-код на Javascript. Сложностей с ним не должно возникнуть, т.к. работа с объектами классическая: слушатель событий addEventListener, метод getElementById, API Телеграмма и другие.
Чтобы создать приложение-аналог @DurgerKingBot, нужно использовать в web_app тип Inline KeyboardButton. Всего есть варианты:
inline button – инлайн-кнопка веб-бота в Телеграмме;
bot menu button – кнопка меню бота (голубая, надпись «Order Food», можно изменять);
keyboard button – клавиатурная;
inline mode – инлайновый режим;
direct link – по прямой ссылке.
