Telegram-бот и Telegram Mini App

Что это за документ

Этот документ нужен компании, которая хочет подключить Telegram-бота к своему приложению и начать использовать Telegram Mini App как рабочую клиентскую витрину.

В документе разобран весь путь:

• где создать Telegram-бота
• что именно взять в Telegram
• что именно заполнить в Omnis
• какую ссылку потом скопировать из Omnis
• куда именно вставить ее в BotFather
• как проверить первый запуск Telegram Mini App

Если говорить совсем просто, Omnis помогает быстро собрать само приложение, а BotFather помогает связать это приложение с вашим ботом в Telegram.

Что важно понять сразу

Telegram Mini App в сценарии Omnis запускается через Telegram-бота.

Практически это означает следующее:

• сначала вы создаете или выбираете Telegram-бота
• затем указываете его данные в Omnis
• после создания приложения берете готовую ссылку запуска из Omnis
• потом вставляете эту ссылку в настройки бота через BotFather

Пока не выполнены обе части, запуск Mini App не будет завершен.

Удобно думать об этом так:

• Omnis создает и настраивает само приложение
• Telegram через BotFather делает это приложение доступным пользователю внутри бота

Что подготовить заранее

До начала работы подготовьте:

• доступ в Omnis
• доступ к разделу Управление -> CMS -> Конструктор приложений
• Telegram-аккаунт сотрудника, который будет работать с BotFather
• рабочее название приложения
• понимание, будете ли вы создавать нового бота или использовать уже существующего

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

Что именно копировать и куда вставлять

Во всем процессе обычно используются только три значения.

Это главная логика всего процесса:

• имя бота и токен приходят из Telegram
• готовая ссылка запуска приходит из Omnis

1. Где начинается настройка в Omnis

Обычно путь такой:

Управление -> CMS -> Конструктор приложений

На первом шаге создается само приложение:

• задается название
• выбирается тип Mini-app

После шага с названием приложение уже появляется в системе, а дальше вы последовательно заполняете остальные параметры.

Подробнее весь мастер разобран в отдельном документе:

• Конструктор приложений

2. Как создать Telegram-бота в BotFather

На шаге Telegram-бота в Omnis уже есть встроенная визуальная инструкция. Ниже тот же процесс описан простыми словами.

Шаг 1. Найдите BotFather

1. Откройте Telegram.
2. Найдите @BotFather.
3. Откройте диалог с ним.

BotFather является официальным помощником Telegram для создания и настройки ботов.

Шаг 2. Создайте нового бота

Дальше начните создание нового бота.

Обычно порядок такой:

1. Задайте обычное имя бота.
2. Затем задайте его user-name.

Важно понимать разницу:

• обычное имя видят люди в Telegram
• user-name нужен для поиска и связи бота с приложением

Если выбранный user-name не подходит, BotFather сообщит об этом и предложит выбрать другой.

Шаг 3. Скопируйте TG-bot user-name

После создания бота Telegram покажет его user-name.

Именно это значение нужно вставить в Omnis в поле:

• TG-bot user-name

Очень важное правило:

• в Omnis user-name указывается без символа @

Правильно:

my_best_shop_bot

Неправильно:

@my_best_shop_bot

Шаг 4. Скопируйте TG-bot token

После создания бота BotFather выдаст token.

Именно его нужно вставить в Omnis в поле:

• TG-bot token

Для пользователя здесь важно запомнить простую вещь:

• token нужен для связи вашего приложения с этим ботом
• его нельзя менять вручную
• его нельзя передавать посторонним

Если у токена лишний пробел, обрезана часть строки или скопировано не то значение, Omnis не сможет подтвердить его корректность.

3. Что заполнить в Omnis на шаге Telegram-бота

Когда user-name и token уже получены, вернитесь в Omnis на шаг Telegram-бота.

Здесь заполняются два обязательных поля:

• TG-bot user-name
• TG-bot token

На этом же экране Omnis дополнительно показывает:

• Код приложения
• Ваш TG URL

Это служебная, но полезная для пользователя информация:

• Код приложения отличает именно это приложение от других
• Ваш TG URL показывает основу адреса, который Omnis использует для запуска Telegram Mini App

Что Omnis проверяет автоматически

После вставки TG-bot token Omnis автоматически запускает проверку токена.

Пользователь обычно видит это так:

• появляется сообщение Проверяем токен...
• если все в порядке, можно переходить дальше
• если есть проблема, система сообщает, что токен не прошел проверку

Чаще всего ошибка связана с одной из причин:

• токен скопирован не полностью
• в начале или в конце попал лишний пробел
• токен взят от другого бота
• в поле вставлен не токен, а другое значение

Что здесь особенно важно проверить

Перед переходом дальше убедитесь, что:

• TG-bot user-name вставлен без @
• TG-bot token вставлен целиком
• бот действительно тот, который нужен для этого приложения

4. Что делает Omnis после заполнения Telegram-данных

После шага Telegram-бота вы продолжаете мастер:

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

После этого Omnis:

• сохраняет данные приложения
• сохраняет связь приложения с Telegram-ботом
• создает стартовую структуру страниц
• создает стартовые компоненты
• добавляет демонстрационное наполнение для первого запуска

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

5. Что показывает последний экран после создания

После успешного создания приложения Omnis показывает отдельный экран завершения.

На нем пользователь видит:

• что приложение успешно создано
• что стартовые страницы уже подготовлены автоматически
• что добавлены информационные страницы с тестовым содержимым
• что дальше нужно закончить настройку Mini App в BotFather

Именно этот экран особенно важен для запуска в Telegram, потому что он показывает готовый дальнейший маршрут.

На практике здесь удобно запомнить главное:

• Omnis уже подготовил приложение
• теперь нужно только корректно перенести ссылку запуска в Telegram

6. Где взять ссылку запуска Telegram Mini App

После создания приложения Omnis показывает готовую ссылку, которую нужно использовать в Telegram.

Очень важно:

• не нужно придумывать эту ссылку самостоятельно
• не нужно заменять ее адресом главного сайта компании
• не нужно сокращать ее или менять вручную

Нужно просто скопировать ту ссылку, которую показывает Omnis.

Если вам важно понимать, откуда она берется, логика у нее простая:

• Omnis берет Ваш TG URL
• добавляет к нему Код приложения
• в результате получается ссылка запуска именно этого Mini App

Но в обычной работе лучше не собирать ее вручную, а копировать готовое значение из Omnis.

На практике ссылка выглядит по такой схеме:

https://xxx.tg.omnis-commerce.ru/app__0123456789

То есть:

• https://xxx.tg.omnis-commerce.ru это Ваш TG URL
• app__0123456789 это Код приложения

Если по какой-то причине готовая ссылка не сохранилась, потерялась или не была скопирована на финальном экране мастера, ее можно восстановить вручную:

1. Возьмите Ваш TG URL.
2. Возьмите Код приложения.
3. Соедините их в один адрес через /.
4. Используйте получившуюся ссылку в BotFather для Menu Button и Main App.

Пример:

https://xxx.tg.omnis-commerce.ru/app__0123456789

7. Как закончить настройку в BotFather

После этого снова перейдите в BotFather.

На последнем экране Omnis путь уже показан карточками. Ниже он расписан в понятном рабочем порядке.

Шаг 1. Откройте раздел Mini Apps

В BotFather откройте раздел:

• Mini Apps

Именно здесь Telegram позволяет подключить Mini App к вашему боту.

Шаг 2. Подготовьте Menu Button и Main App

В BotFather Omnis предлагает настроить два способа запуска:

• Menu Button
• Main App

Для пользователя это удобно понимать так:

• Menu Button это кнопка запуска приложения в диалоге с ботом
• Main App это основной запуск приложения из профиля и карточки бота

Оба варианта лучше включить сразу, чтобы пользователю было проще открыть вашу витрину в Telegram.

Шаг 3. Вставьте ссылку в Menu Button

Откройте настройку Menu Button и вставьте туда ссылку запуска из Omnis в поле URL.

Здесь нужна именно ссылка из Omnis, а не любой другой адрес компании.

Шаг 4. Вставьте ту же ссылку в Main App

Затем откройте настройку Main App и вставьте туда ту же самую ссылку запуска.

В стандартном сценарии Omnis для Menu Button и Main App используется один и тот же адрес.

Шаг 5. Убедитесь, что оба варианта включены

После вставки ссылки проверьте, что:

• Menu Button находится в статусе Enabled
• Main App находится в статусе Enabled

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

8. Как начать использовать Telegram Mini App

После завершения настройки в BotFather приложение уже можно открывать в Telegram.

Обычно первый запуск выглядит так:

1. Найдите бота по его user-name.
2. Откройте диалог с ним.
3. Нажмите Start, если бот открывается впервые.
4. Откройте приложение через кнопку запуска.

Дальше стоит сразу проверить:

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

Также Omnis подсказывает, что приложение может открываться быстрым запуском из интерфейса Telegram. Это тоже полезно проверить после первого успешного запуска.

9. Что Omnis делает сам, а что делает сотрудник

Это один из самых важных вопросов при первом запуске.

Что Omnis делает сам

Omnis:

• создает приложение
• проверяет TG-bot token
• сохраняет Telegram-данные приложения
• подготавливает стартовые страницы и компоненты
• показывает готовую ссылку запуска

Что делает сотрудник вручную

Сотрудник:

• создает бота в BotFather
• копирует TG-bot user-name
• копирует TG-bot token
• вставляет оба значения в Omnis
• после создания приложения вставляет ссылку из Omnis в Menu Button
• вставляет ту же ссылку в Main App
• проверяет запуск в Telegram

Если говорить совсем коротко:

• Omnis готовит приложение и дает правильную ссылку
• сотрудник завершает видимую настройку запуска в Telegram

10. Что делать, если данные бота изменились позже

Иногда после запуска нужно поменять Telegram-данные приложения. Например:

• подключить другой бот
• обновить токен
• исправить ошибку в user-name

В таком случае обычно действуют так:

1. Откройте карточку приложения в разделе Приложения.
2. Исправьте Telegram bot user name и/или Telegram bot token.
3. Сохраните изменения.
4. После этого заново проверьте настройки Mini Apps в BotFather.
5. Затем снова откройте приложение в Telegram и убедитесь, что запуск работает корректно.

Если меняется именно бот, а не только токен, особенно внимательно проверьте, что ссылка запуска указана у нужного бота.

11. Что чаще всего путают при настройке

Ошибка 1. Добавляют @ в TG-bot user-name

В Omnis имя бота нужно вставлять без @.

Ошибка 2. Путают user-name и token

Это разные значения:

• user-name нужен для поиска и идентификации бота
• token нужен для рабочей связи приложения с ботом

Ошибка 3. Копируют не ту ссылку

Для Menu Button и Main App нужна именно ссылка запуска из Omnis.

Не нужно:

• брать адрес главного сайта компании
• вставлять произвольную ссылку
• собирать адрес вручную, если Omnis уже показал готовый

Ошибка 4. Настраивают только один способ запуска

Если заполнить только Menu Button или только Main App, часть привычных сценариев запуска у пользователя может не сработать.

Ошибка 5. Не проверяют итоговый запуск

После настройки всегда стоит открыть реального бота в Telegram и проверить запуск Mini App вручную.

12. Короткий чек-лист перед запуском

• создан Telegram-бот
• скопирован TG-bot user-name
• скопирован TG-bot token
• в Omnis создано приложение типа Mini-app
• в Omnis заполнены поля TG-bot user-name и TG-bot token
• приложение успешно создано
• ссылка запуска скопирована из Omnis
• ссылка вставлена в Menu Button
• ссылка вставлена в Main App
• Menu Button включен
• Main App включен
• бот найден в Telegram
• Telegram Mini App открывается у сотрудника без ошибок