Что такое WebApp и как правильно использовать кнопки со ссылками

В Telegram-ботах часто используют кнопки — по ним можно открыть сайт, анкету, форму или платёжную страницу.
Но важно понимать: ссылки в таких кнопках могут вести себя по-разному. Иногда сайт открывается прямо в чате Telegram, а иногда — в обычном браузере.

Вот тут и появляется WebApp — специальный формат кнопки, при котором сайт открывается прямо внутри Telegram, без выхода из мессенджера. Это удобно, красиво и не сбивает пользователя с пути.

В этой инструкции мы подробно объясним:

• чем WebApp отличается от обычной ссылки (URL),

• когда какую кнопку использовать,

• какие сайты подходят для WebApp, а какие — нет,

• и что делать, чтобы всё работало корректно.

📌 Обратите внимание: в ВКонтакте кнопок WebApp нет.
Они работают только в Telegram.

Если вы вставите ссылку с типом WebApp в сценарий для ВК — кнопка просто не отобразится, и шаг может не сработать.
Для ВКонтакте используйте обычные кнопки со ссылкой (тип: URL).

В чём разница между WebApp и обычной кнопкой со ссылкой

В Telegram есть два способа открыть ссылку с кнопки:

1. Обычная кнопка со ссылкой (тип: URL)

Это самый простой вариант. Когда человек нажимает на кнопку — Telegram открывает сайт в браузере.
То есть, человек покидает Telegram и переходит, например, в Chrome или Safari.

Такой тип кнопки удобно использовать, если:

• вы отправляете ссылку на Telegram-канал, чат или бота;

• вы ведёте на сайт, где не важно, где он откроется (в браузере или нет);

• сайт технически не может открыться внутри Telegram.

2. Кнопка WebApp

Это более современный и удобный вариант.
Когда человек нажимает на такую кнопку — сайт открывается не в браузере, а прямо в Telegram, в отдельном окошке поверх чата.
Никуда не надо переходить, всё работает внутри мессенджера.

WebApp подходит, если:

• вы хотите, чтобы пользователь не выходил из Telegram;

• вы показываете анкету, калькулятор, магазин, форму или оплату;

• у вас есть сайт, который нормально открывается внутри Telegram.

Главное отличие:

• URL-кнопка — это просто “перейти по ссылке”.

• WebApp-кнопка — это “открыть сайт внутри Telegram, как встроенное приложение”.

Когда использовать WebApp, а когда — обычную ссылку (URL)

Чтобы кнопка работала правильно, нужно понимать: куда ведёт ссылка и как вы хотите, чтобы она открывалась.
Вот несколько простых ситуаций, которые помогут сориентироваться:

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

• Вы хотите, чтобы сайт открылся прямо в Telegram, не выкидывая пользователя в браузер.

• У вас анкета, форма регистрации, квиз, мини-магазин, оплата, личный кабинет — всё, что должно быть “встроено” в Telegram.

• Вы хотите, чтобы пользователь оставался внутри чата, не терял фокус и не уходил с экрана бота.

Например:
Вы отправляете кнопку “Заполнить анкету” → открывается сайт с анкетой прямо в Telegram.

Когда лучше использовать обычную ссылку (URL):

• Ссылка ведёт на другой Telegram-канал, чат или бота.
  (В WebApp такие ссылки не работают — Telegram не открывает сам себя.)

• Сайт не поддерживает работу внутри Telegram — не загружается, просит “открыть в браузере” или просто остаётся пустым.

• Вы не уверены, будет ли сайт корректно работать как WebApp.

Например:
Вы отправляете кнопку “Перейти в наш канал” → пользователь нажимает и открывает ссылку в Telegram. Это должна быть обычная ссылка (URL).

Какие ссылки ПОДХОДЯТ для WebApp

Чтобы ссылка открылась внутри Telegram через кнопку WebApp, она должна соответствовать нескольким техническим условиям. Если хотя бы одно из них нарушено — WebApp не сработает. Ниже — признаки «хороших» ссылок и пояснение, как это проверить.

 1. Поддерживается HTTPS

WebApp работает только с защищёнными сайтами, которые начинаются с https://. Сайты без SSL-сертификата (то есть с адресом http://) Telegram просто не откроет внутри чата.

🔒 Это требование безопасности: Telegram блокирует любые небезопасные подключения внутри WebApp.

Пример:
✅ https://mydomain.com/form — подходит
❌ http://mydomain.com/form — не откроется

Как это проявляется:

• Ничего не происходит при нажатии на кнопку.

• Сообщение бота может не отображаться вообще — Telegram «ломает» шаг.

• Пользователь остаётся без ответа, а сценарий как будто не сработал.

Что делать:

• Всегда используйте только https://.

• Проверьте вручную: нажмите на кнопку и убедитесь, что страница загружается внутри Telegram.

 2. Разрешено открытие в iframe

WebApp по сути — это встроенное iframe-окно. Если сайт в своих настройках запрещает отображение в iframe (например, использует заголовки X-Frame-Options: DENY или SAMEORIGIN), Telegram не сможет его показать.

Как это проявляется:

• При нажатии на кнопку WebApp появляется пустой экран.

• Telegram-окно открывается, но сайт не грузится.

Что делать:

• Уточните у разработчика сайта: «Разрешает ли сайт открытие в iframe?»

• Проверьте ссылку в iframe-тестере — если не работает там, не сработает и в Telegram.

3. Нет автоматических редиректов и внешних вызовов

Сайт должен открываться напрямую. Если он делает автоматический переход на другой адрес, мессенджер или магазин приложений — Telegram WebApp не сможет это обработать.

Как это проявляется:

• Страница быстро исчезает после загрузки.

• Telegram закрывает окно WebApp.

• Иногда возникает сообщение об ошибке.

Что делать:

• Избегайте использования window.location, meta refresh, target="_blank" без необходимости.

• Настройте сайт так, чтобы он открывался сразу, без внешних переходов.

 4. Авторизация через Telegram не требуется

Если сайт настроен на автоматическую авторизацию через Telegram SDK (initData), но не получает данные — он не сможет работать внутри WebApp.

Как это проявляется:

• Страница показывает ошибку авторизации.

• Контент не отображается.

• Пользователь видит «Вы не авторизованы» или пустой экран.

Что делать:

• Уточните, обязательно ли авторизация через Telegram SDK.

• Если можно — сделайте сайт независимым от Telegram-логина.

• Вариант: передавайте нужные параметры вручную через ссылку (?user_id=...).

Совет: протестируйте WebApp-кнопку на мобильном в Telegram до публикации сценария.

 5. Работают открытые видео-сервисы (YouTube, Vimeo)

Ссылки на YouTube и Vimeo отлично работают в WebApp, если видео не ограничено по возрасту или доступу.

Как это проявляется:

• Видео загружается прямо в Telegram.

• Пользователь может смотреть его, не покидая чат.

Что делать:

• Используйте обычные ссылки на видео (https://youtube.com/watch?v=... или https://youtu.be/...).

• Не вставляйте приватные или «18+» ролики — Telegram не сможет их открыть.

 6. Поддерживаются Google-документы, формы и таблицы (при открытом доступе)

Google-сервисы работают в WebApp, если включён свободный доступ без входа в аккаунт.

Как это проявляется:

• При открытом доступе — документ/форма загружается корректно.

• При закрытом — Telegram WebApp остаётся пустым или просит авторизацию.

Что делать:

• Включите доступ “Просмотр по ссылке” в Google.

• Для презентаций используйте «Файл → Публиковать в Интернете» и вставляйте опубликованную ссылку.

Подходят:

• https://docs.google.com/document/d/...

• https://docs.google.com/forms/d/...

• https://docs.google.com/spreadsheets/d/...

• https://docs.google.com/presentation/d/... (в режиме публикации)

Не подойдут:

• Ссылки, требующие входа в аккаунт

• Доступ «только по приглашению»

• Корпоративные Google-доки

 7. Подходят ссылки на платёжные сервисы (если они работают в iframe)

Многие платёжные системы позволяют открыть страницу оплаты прямо в Telegram — если она не блокирует встраивание.

Как это проявляется:

• Форма оплаты загружается внутри WebApp.

• Пользователь может оплатить прямо в чате.

Что делать:

• Используйте платёжные страницы, не ведущие напрямую на банковский шлюз.

• Убедитесь, что сервис не требует открытия в новой вкладке.

Подходят:

• ЮKassa (страница оплаты)

• Prodamus

• CloudPayments

• Stripe (в embedded-режиме)

• Робокасса

Может не подойти:

• Сбербанк Онлайн

• Tinkoff (редиректы)

• PayPal (обычно требует внешний браузер)

Совет:

• Перед вставкой ссылки проверьте её поведение через кнопку WebApp в Telegram.

❌ Какие ссылки НЕ подойдут для WebApp

Не все ссылки можно использовать в кнопке WebApp. Telegram запускает WebApp внутри встроенного окна (iframe) и не поддерживает некоторые типы ссылок или действий, которые работают в обычном браузере.

Вот распространённые случаи, когда WebApp не сработает или “сломает” шаг.

1. Ссылки на Telegram-ботов, каналы и чаты

Ссылки вроде https://t.me/имя_бота, https://t.me/канал, https://t.me/joinchat/... не открываются в WebApp, потому что Telegram не позволяет открыть самого себя внутри встроенного окна.

Как это проявляется:

• Кнопка никак не реагирует.

• WebApp не запускается.

• Бот может “замолчать” — шаг с кнопкой не выполнится.

Что делать:

• Используйте тип кнопки URL, а не WebApp.

• Такие ссылки должны открываться внешне, а не встраиваться.

2. Ссылки на мессенджеры и внешние приложения

Это касается:

• WhatsApp (https://wa.me/...)

• Viber (viber://chat?...)

• Telegram-ссылок (tg://...)

• Zoom, Skype, Instagram, TikTok

• а также протоколов mailto:, tel:

Такие ссылки:

• либо требуют открытия отдельного приложения,

• либо не являются полноценными веб-страницами.

Как это проявляется:

• Кнопка не срабатывает.

• Telegram может просто игнорировать нажатие.

• WebApp-окно сразу закрывается.

Что делать:

• Используйте такие ссылки только в обычных URL-кнопках.

• Не вставляйте их в WebApp — они технически не поддерживаются.

3. Ссылки без HTTPS (начинаются с http://)

Если ссылка не защищена (http:// вместо https://), Telegram не разрешит её открыть в WebApp.

Как это проявляется:

• Telegram WebApp не запускается.

• Кнопка “молчит”, шаг не происходит.

• Пользователь ничего не видит.

Что делать:

• Всегда используйте https://.

• Убедитесь, что у сайта есть SSL-сертификат.

• Проверьте в браузере: если написано “не защищено” — WebApp не откроет эту ссылку.

4. Ссылки на файлы, почту и звонки

Например:

• mailto:support@example.com

• tel:+79991234567

• https://site.com/document.pdf (или другие документы: .docx, .pptx и т.д.)

Эти ссылки:

• не ведут на полноценную веб-страницу,

• открывают почтовый клиент, вызывают звонок или запускают загрузку файла.

Как это проявляется:

• Кнопка не работает.

• Telegram может закрыть окно WebApp сразу после открытия.

• Ничего не происходит.

Что делать:

• Такие действия не поддерживаются в WebApp.

• Используйте обычные кнопки-ссылки или просто вставьте ссылку в текст сообщения.

5. Ссылки на сайты, которые требуют авторизацию или просят открыть в браузере

Некоторые сайты при открытии:

• сразу показывают сообщение “Откройте в браузере”,

• делают системный редирект,

• используют защиту, блокирующую встроенное открытие (например, банковские страницы, защищённые порталы).

Как это проявляется:

• Пустой экран.

• Мгновенное закрытие окна WebApp.

• Ошибка доступа.

Что делать:

• Проверяйте такие сайты вручную через кнопку WebApp.

• Если есть подобное поведение — используйте обычную кнопку URL.

Чек-лист перед запуском WebApp-кнопки

Проверьте ссылку:

• Ссылка начинается с https://, а не http://

• Страница открывается без необходимости авторизации или входа в аккаунт

• Нет автоматических переходов на App Store, мессенджеры, другие сайты или приложения

• Сайт не требует открытия в новой вкладке

• Страница не блокирует загрузку внутри iframe (проверено вручную)

• Если используется Google-документ или форма — включён доступ по ссылке без входа

• Если это видео — ссылка ведёт на открытый ролик (не приватный, не возрастной)

• Если это платёж — форма открывается прямо, без редиректов и внутри WebApp

Проверьте шаг с кнопкой:

• Кнопка действительно настроена как WebApp, а не обычная ссылка

• Вставлена корректная, полная ссылка — без лишних пробелов и ошибок

• Шаг не содержит других ошибок, которые могут прервать сценарий

• Тестирование проводилось в Telegram (на мобильном устройстве) — именно через WebApp, а не в браузере

Проверьте результат:

• Ссылка открывается внутри Telegram, без выхода в браузер

• Страница загружается полностью и отображается корректно

• Пользователь может взаимодействовать с сайтом: отправить форму, нажать кнопку, оплатить и т.д.

• Нет сообщений об ошибке, авторизации или блокировке