В обновлении Bot API 6.0 телеграм-боты получили много новых функций. Из них для разработчиков самая примечательная - Telegram Web Apps (Веб-приложения внутри телеграм). С этим нововведением разработчики могут подключать к своим ботам web-приложения, которые открываются в дополнительном окне, что сильно расширяет инструментарий, а, следовательно и функционал ботов в телеграм.
Приложения Telegram известны своей скоростью, плавностью и кросс-платформенным дизайном. Ваше веб-приложение в идеале должно соответствовать этим принципам.
- Все элементы должны быть отзывчивыми и спроектированы с учетом мобильной ориентации устройств.
- Интерактивные элементы должны имитировать стиль, поведение и назначение уже существующих компонентов пользовательского интерфейса.
- Все анимации должны быть плавными, в идеале 60 кадров в секунду.
- Все input и изображения должны содержать label для доступности.
- Приложение должно обеспечивать бесшовную работу, отслеживая изменение цветов темы с помощью API, и используя их соответствующим образом.
Создание кнопки
Первое, что нам нужно сделать - создать кнопку запуска веб-приложения. Это можно сделать двумя способами:
1. При помощи @botfather - кнопка на месте кнопки команд
1.1. Идем в @botfather и пишем команду: /setmenubutton
1.2. Далее выбираем бота, которому нужна кнопка веб приложения
1.3. Отправляем ссылку по которой доступно наше веб-приложение
1.4. Пишем имя кнопки - будет отображаться внизу слева
Вот и все. В целом, если у вас есть адаптивный сайт и вы хотели просто добавить его в бота, тут можете остановиться.
Только при добавлении этим способом мы можем получить информацию о пользователе.
Хостинг в РФ.
Проверенные сервера и VDS в РФ и за рубежом (для VPN, например)
Проверенные сервера и VDS за рубежом
2. В коде бота - клавиатурные кнопки.
Запуск бота с inline-кнопки даёт суть тоже самое, что и предидущий вариант. Однако, запуск с keyboard button дает возможность отправлять данные из веб-приложения в бота.
Покажу на примере pytelegrambotapi - я понимаю, что это не самая популярная библиотека для написания телеграмм-ботов, но так получилось, что я пишу именно на ней. Если вы пользуетесь другой библиотекой / языком, думаю, вам не составит труда действовать по аналогии, Вы можете сразу посмотреть пример или перейти в репозиторий и посмотреть код с комментариями:
2.1. Делаем все стандартные штуки для запуска бота - импорт библиотеки, ввод токена, infinity_polling, обработчик команды start. Если вы не понимаете о чем я, вам сюда.
2.2. Создаем функцию, которая вернет нам клавиатуру с нужной кнопкой.
Для того, чтобы создать кнопку, нужно сначала создать WebAppInfo-объект внутри которого будет url на наш сайт.
2.3. Отправляем сообщение с нашей клавиатурой при отправке команды или любом другом действии:
bot.send_message( message.chat.id, 'Привет, я бот для проверки телеграмм webapps!)', reply_markup=webAppKeyboard())
Готово. Кнопки у нас есть.
Тут можно вообще закончить, если вы просто хотели, чтобы пользователь мог открыть ваш сайт из бота (зачем-то). Работать это будет вот так:
Работа с веб-приложением
Теперь идем в наше веб-приложение. На момент написания статьи открывается любая ссылка, даже на codepen, поэтому если вы укажете ее как url кнопки, то сможете удобно редактировать свое приложение прямо на ходу.
В любом случае - идем в веб-приложение.
Хостинг в РФ.
Проверенные сервера и VDS в РФ и за рубежом (для VPN, например) Проверенные сервера и VDS за рубежом
Инициализация
Чтобы взаимодействовать с телеграм подключаем скрипт:
<script src="https://telegram.org/js/telegram-web-app.js"></script>
После этого нам будет доступен объект: window.Telegram.WebApp
Записываем его в переменную и начинаем нашу работу.
let tg = window.Telegram.WebApp;
Что же мы теперь можем? Не так много, как хотелось бы, но и не мало. Приложение состоит из: основной кнопки (telegram-объект) и самой страницы, которая загрузилась по ссылке. Остальные элементы telegram-интерфейса нам не доступны. Однако, доступны цвета темы пользователя:
Цвета
Они доступны в формате hex как css-переменные:
var(--tg-theme-bg-color)
var(--tg-theme-text-color)
var(--tg-theme-hint-color)
var(--tg-theme-link-color)
var(--tg-theme-button-color)
var(--tg-theme-button-text-color)
Или как объект ThemeParams в js (вместо window.Telegram.WebApp я использую переменную tg):
tg.ThemeParams.bg_color
tg.ThemeParams.text_color
tg.ThemeParams.hint_color
tg.ThemeParams.link_color
tg.ThemeParams.button_color
tg.ThemeParams.button_text_colorString
Но будьте осторожны, цвета - не обязательный параметр, поэтому стоит проверять, есть ли они, перед тем как использовать.
Также имеется обработчик события изменения цветовой схемы:
Telegram.WebApp.onEvent(themeChanged, function(){});
При изменении цветов можно их поменять и в нашем веб-приложении.
Основные возможности
С цветами разобрались - теперь к другим основным параметрам:
tg.initData - получаем данные от пользователя в виде объекта (работает только при запуске из меню команд бота).
tg.initDataUnsafe - получаем данные от пользователя в виде строки (работает только при запуске из меню команд бота).
tg.isExpanded - возвращает true, если приложение открыто на всю высоту, false - если нет.
tg.viewportHeight - вернёт ширину окна.
tg.sendData(data) - отправляет данные боту в строковом виде, после чего закрывает приложение (работает только если приложение запущено с keyboard button).
tg.ready() - метод позволяет отследить, когда приложение готово к отображению.
tg.expand() - метод позволяет растянуть окно на всю высоту.
tg.close() - метод закрывает приложение.
Main button
Мы можем взаимодействовать с кнопкой внизу приложения. Изменять ее текст, цвет фона и текста, показывать/скрывать, делать активной и деактивировать:
tg.MainButton.text - текст кнопки, по умолчанию: "Continue"
tg.MainButton.color - цвет текста
tg.MainButton.textColor - цвет подложки
tg.MainButton.isVisible - видна ли кнопка (по умолчанию false)
tg.MainButton.isActive - активна ли кнопка (по умолчанию true)
tg.MainButton.setText(text) - метод для задания текста
tg.MainButton.onClick(callback) - метод при нажатии на кнопку
tg.MainButton.show() - показать кнопку
tg.MainButton.hide() - скрыть кнопку
tg.MainButton.enable() - сделать активной
tg.MainButton.disable() - сделать неактивной
tg.MainButton.setParams(params) - задает параметры в виде объекта: text
И еще информация о пользователе, мы можем разобрать строку tg.initData или использовать tg.initDataUnsafe объект:
tg.initDataUnsafe.user.id - уникальный идентификатор пользователя
tg.initDataUnsafe.user.isBot - бот ли пользователь (true/false)
tg.initDataUnsafe.user.first_name - имя пользователя
tg.initDataUnsafe.user.last_name - "фамилия" пользователя
tg.initDataUnsafe.user.username - username пользователя
tg.initDataUnsafe.user.language_code - код языка пользователя
Пишем веб-приложение
С этой информацией мы можем написать небольшое приложение, которое наглядно отобразит основные возможности.
1. Создадим небольшую html-основу:
2. Пропишем изменения текста основной кнопки и изменение цвета:
3. Далее повесим обработчик события на первую html-кнопку и при нажатии будем показывать/скрывать основную telegram-кнопку:
4. Еще один обработчик события на вторую html-кнопку, при нажатии которой будем активировать/деактивировать основную telegram-кнопку:
5. В итоге отправляем данные при нажатии на основную telegram-кнопку:
Telegram.WebApp.onEvent('mainButtonClicked', function(){
tg.sendData("some string that we need to send");
//при клике на основную кнопку отправляем данные в строковом виде
//работает только при запуске с keyboard button
});
Благодаря этому методу мы можем получить данные из веб-приложения в боте.
6. Также выведем всю информацию о пользователе (будет доступна только при запуске с кнопки, добавленной с помощью @botfather).
Нам доступно: id / isBot / first_name / last_name / username / language_code
7. И добавляем стили, используя telegram-css переменные:
В итоге получаем такое веб-приложение:
Оно отображает основные возможности - получение информации о пользователе, задействование цветов его темы и управление главной кнопкой приложения.
Получаем данные от веб-приложения в боте
Теперь вешаем обработчик событий на сообщение, которое посылает веб-приложение в методе send (работать будет только с keyboard button):
И все - теперь мы можем получать информацию с сайта и отвечать на нее.
Есть и другие способы - но это уже немного другая история.
Исходники: github, codepen
Бот-пример
Хостинг в РФ.
Проверенные сервера и VDS в РФ и за рубежом (для VPN, например) Проверенные сервера и VDS за рубежом