Telegram-бот и Telegram Mini App

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

Здесь описано, как подключить Telegram-бота к приложению и открыть клиентскую витрину в Telegram Mini App.

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

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

Приложение создаётся в Omniz, а связь с ботом настраивается через BotFather.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Откройте в группе CMS страницу Конструктор приложений.

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

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

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

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

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

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

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

Шаг 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.

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

• TG-bot user-name

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

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

Правильно:

my_best_shop_bot

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

@my_best_shop_bot

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

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

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

• TG-bot token

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Очень важно:

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

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

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

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

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

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

https://xxx.tg.omniz.ru/app__0123456789

То есть:

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

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

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

Пример:

https://xxx.tg.omniz.ru/app__0123456789

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

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

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

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

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

• Mini Apps

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

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

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

• Menu Button
• Main App

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Omniz:

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

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

Сотрудник:

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

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

• Omniz готовит приложение и дает правильную ссылку
• сотрудник завершает видимую настройку запуска в 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

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

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

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

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

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

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

Не нужно:

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

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

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

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

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

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

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