В Telegram Bot API 6.0, вышедшем в 16-04-2022 была добавлена поддержка WebApps, которая позволяет открывать страницы HTML5 в окне приложения Telegram с поддержкой JavaScript, для которого доступно
Web Apps for Bots //core.telegram.org/bots/webapps
Введение
Автоматизация обработки сообщений и данных с помощью Telegram Bot API описана в публикации Бот для Telegram. Реализованный бот взаимодействует с пользователем в окне приложения Telegram и ограничен его возможностями. Приложения WebApp позволяют пользователю перейти из окна приложения Telegram в окно приложения WebApp для получения дополнительных возможностей, а затем вернутся обратно.
Дополнительные возможности приложений WebApp обеспечиваются тем, что они реализуются HTML5 с поддержкой JavaScript, SVG, MathML и других современных технологий. Технологически WebApp - это web-страница открытая в браузере приложения Telegram.
Технология Telegram WebApp реализуется бесшовно, и пользователь почти не ощущает перехода между приложениями, благодаря автоматическому обмену данными и цветовой схемой между приложением Telegram и приложения WebApp.
Общая схема технологии WebApp
В приватном чате
- Telegram Бот публикует в приватном чате пользователя обычное сообщение, которое включает объект reply_markup типа ReplyKeyboardMarkup, которое включает объект keyboard с массивом массивов объектов типа KeyboardButton, среди которых есть объект кнопки с объектом web_app типа WebAppInfo с свойство url типа String, содержащим URL, необходимый для вызова WebApp.
- При нажатии на KeyboardButton с объектом web_app файл по указанному URL загружается приложением Telegram
Запусть WebApp можно с помощью кнопки, которая отмечена специальным знаком
Кнопки WebApp работают в приложении Telegram и не работают в web.telegram.org в браузере.
К
Настройка кнопки меню
WebApp будет отображаться в приложении Telegram кнопкой в левом нижнем углу, если выполнить следующие действия:
1. В @BotFather команда /setmenubutton запускает процедуру установки кнопки приложения для бота.
2. Для выбора бота @BotFather отобразит кнопки доступных ботов, но если кнопки выбора не появятся, то имя бота нужно ввести вручную, точно соблюдая регистр: @ReKSbizBot.
3. Ввести URL файла WebApp, который будет запрашивать кнопка: https://reks.biz/webapp.php
4. Ввести надпись для кнопки: ReKS.
В приложении Telegram кнопка немедленно появится в приватном чате бота.
Бот /отправитель
!!!
Запуск бота с inline-кнопки даёт суть тоже самое, что и предыдущий вариант. Однако, запуск с keyboard button дает возможность отправлять данные из веб-приложения в бота.
2.1. Делаем все стандартные штуки для запуска бота - импорт библиотеки, ввод токена, infinity_polling, обработчик команды start. Если вы не понимаете о чем я, вам сюда.
2.2. Создаем функцию, которая вернет нам клавиатуру с нужной кнопкой.
Для того, чтобы создать кнопку, нужно сначала создать WebAppInfo-объект внутри которого будет url на наш сайт.
примере для библиотеки pytelegrambotapi:
1 2 3 4 5 6 |
def webAppKeyboard(): #создание клавиатуры с webapp кнопкой keyboard = types.ReplyKeyboardMarkup(row_width=1) #создаем клавиатуру webAppTest = types.WebAppInfo("https://telegram.mihailgok.ru") #создаем webappinfo - формат хранения url one_butt = types.KeyboardButton(text="Тестовая страница", web_app=webAppTest) #создаем кнопку типа webapp keyboard.add(one_butt) #добавляем кнопки в клавиатуру return keyboard #возвращаем клавиатуру |
2.3. Отправляем сообщение с нашей клавиатурой при отправке команды или любом другом действии:
bot.send_message( message.chat.id, 'Привет, я бот для проверки телеграмм webapps!)', reply_markup=webAppKeyboard())
!!!!!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
/** * { * "text": "Press me to call WebApp", * "request_contact": true, * "request_location": true, * "web_app": { * "url": "https://reks.biz/reksbizbot.php?id=1234567890&data={...}" * } * } */ $ReplyKeyboardMarkup = array( array( array( // KeyboardButton 'text' => 'Press me to call WebApp', // текст кнопки 'request_contact' => true, //?! добавляет контакты 'request_location' => true, //?! добавляет локацию 'web_app' => array( // WebAppInfo 'url': 'https://reks.biz/reksbizbot.php?id=1234567890&data={...}')))); |
//
!!! Вызвать WebApp можно и с помощью InlineKeyboardButton >>> Описание веб-приложения, которое будет запущено, когда пользователь нажмет кнопку. Веб-приложение сможет отправить произвольное сообщение от имени пользователя с помощью метода answerWebAppQuery. Доступно только в приватных чатах между пользователем и ботом.
Приложение WebApp
Приложение WebApp - Чтобы взаимодействовать с Telegram необходим скрипт:
1 |
<script src="https://telegram.org/js/telegram-web-app.js"></script> |
Скрипт реализует переменные цветовой схемы для применения в CSS:
--tg-theme-bg-color
--tg-theme-text-color
--tg-theme-hint-color
--tg-theme-link-color
--tg-theme-button-color
--tg-theme-button-text-color
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
body{ color: var(--tg-theme-text-color); background: var(--tg-theme-bg-color); } .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); } |
//
window.Telegram.WebApp
Скрипт реализует объект window.Telegram.WebApp, через который доступны свойства, методы и события приложения.
Свойство цветовой схемы ThemeParams
параметры цветовой схемы:
- bg_color
- text_color
- hint_color
- link_color
- button_color
- button_text_colorString
1 |
bg_color = window.Telegram.WebApp.ThemeParams.bg_color; |
Объект реализует обработчик события изменения цветовой схемы:
1 |
Telegram.WebApp.onEvent(themeChanged, function(){}); |
Свойства объекта и методы объект WebApp
!!!:
- initData //получаем данные от пользователя в виде строки (работает только при запуске из меню команд бота).
- initDataUnsafe // получаем данные от пользователя в виде объекта (работает только при запуске из меню команд бота).
- isExpanded // возвращает true, если приложение открыто на всю высоту, false - если нет.
- viewportHeight // вернёт ширину окна.
- sendData(data) // отправляет данные боту в строковом виде, после чего закрывает приложение (работает только если приложение запущено с keyboard button).
- ready() // метод позволяет отследить, когда приложение готово к отображению.
- expand() // метод позволяет растянуть окно на всю высоту.
- close() // метод закрывает приложение.
Внизу окна приложения расположена главная кнопка, реализованная свойством MainButton объекта WebApp:
- text // текст кнопки, по умолчанию: "Continue"
- color // цвет текста
- textColor // цвет подложки
- isVisible // видна ли кнопка (по умолчанию false)
- isActive // активна ли кнопка (по умолчанию true)
- setText(text) // метод для задания текста
- onClick(callback) // метод при нажатии на кнопку
- show() // показать кнопку
- hide() // скрыть кнопку
- enable() // сделать активной
- disable() // сделать неактивной
- setParams(params) // задает параметры в виде объекта
1 |
Telegram.WebApp.MainButton.setText( 'Press me' ); |
//
Данные !!! реализованны свойством initData объекта WebApp:
initData, который можно достать с помощью JavaScript. Объект имеет следующую структуру:
{
"query_id": "str",
"user": {
"id": 1,
"is_bot": false,
"first_name": "Pavel",
"last_name": "Durov",
"username": "durov",
"language_code": "ru",
"photo_url": "https://telegram.org/durov.jpg"
},
"auth_date": 1655210062,
"hash": "7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069"
}
!!!
Данные о пользователе реализованны свойством initDataUnsafe объекта WebApp:
user.id // уникальный идентификатор пользователя
isBot // бот ли пользователь (true/false)
first_name // имя пользователя
last_name // "фамилия" пользователя
username // username пользователя
language_code // код языка пользователя
1 |
if( Telegram.WebApp.initDataUnsafe.user.language_code == 'uk' ) {... } |
//
Бот /получатель
Теперь вешаем обработчик событий на сообщение, которое посылает веб-приложение в методе send (работать будет только с keyboard button):
1 2 3 4 5 6 |
@bot.message_handler(content_types="web_app_data") #получаем отправленные данные def answer(webAppMes): print(webAppMes) #вся информация о сообщении print(webAppMes.web_app_data.data) #конкретно то что мы передали в бота bot.send_message(webAppMes.chat.id, f"получили инофрмацию из веб-приложения: {webAppMes.web_app_data.data}") #отправляем сообщение в ответ на отправку данных из веб-приложения |
И все - теперь мы можем получать информацию с сайта и отвечать на нее.
Есть и другие способы - но это уже немного другая история.
Приложение WebApp, открытое кнопкой web_app в составе reply_keyboard при выполнении метода .sendData() формирует специальное обновление, которое передается боту. Свойство объекта message такого обновления включает объект web_app_data типа WebAppData с двумя строковыми свойствами:
- data (String) данные переданные из WebApp в качестве параметра метода .sendData()
- WebApps API предупреждает о потенциальной опасности этих данных: "плохой клиент может отправлять произвольные данные в этом поле", поэтому их следует подвергать проверке
- button_text (String) повторяет текст кнопки клавиатуры web_app, с помощью которой приложение WebApp было открыто (эти данные тоже потенциально опасны и требуют проверки)
1 2 3 4 5 6 7 8 9 10 11 12 13 |
{ "update_id": 1234567890, "message": { "message_id": 123, "from": {...}, "chat": {...}, "date": 1673197018, "web_app_data": { "data": "...", "button_text": "WebApp" } } } |
Источники
Создание telegram web apps и взаимодействие с ними в телеграм ботах //habr.com (17.05.2022)
- ...и обсуждение .../comments/
Telegram Web App bot: разбор и аспекты безопасности //krasovs.ky