Токен Telegram-бота

Чтобы подключить Telegram-бота к Меркурий-ИИ, понадобится специальный ключ — HTTP API token. Его выдаёт официальный бот Telegram @BotFather. В этой статье показано, как получить токен для нового бота или найти его у уже созданного, а затем подключить бота в Меркурии.

Токен — это секретный ключ, который позволяет Меркурию взаимодействовать с вашим ботом. Он не является ссылкой на бота и не предназначен для покупателей. Покупатели будут открывать бота по обычной ссылке Telegram, а токен нужен только для настройки интеграции.

Где указать токен в Меркурии

Откройте раздел Розница → Дисконтная программа → Боты и найдите блок «Telegram-бот».

В этом блоке находятся поля и кнопки для подключения, проверки и отключения вашего бота.

Поле «Токен бота»

Сюда нужно вставить HTTP API token, полученный от @BotFather. Токен обычно состоит из числовой части, двоеточия и длинной последовательности символов. Например, он может выглядеть как 123456789:ABC...XYZ. Это только пример формата, использовать его для подключения нельзя.

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

Статус подключения

Рядом с настройками отображается состояние Telegram-бота:

«Не подключён» — Меркурий пока не связан с этим ботом.
Ссылка на бота — подключение выполнено. По ссылке вида https://t.me/… можно открыть бота в Telegram.

После подключения поле токена очищается. Это нормальное поведение: токен не должен постоянно отображаться в настройках. Для проверки подключения ориентируйтесь на статус и ссылку.

Кнопка «Подключить Telegram»

После вставки токена нажмите «Подключить Telegram». Меркурий проверит возможность подключения и зарегистрирует webhook на своём сервере. Через этот механизм Telegram будет передавать Меркурию сообщения и события, связанные с работой бота.

Если операция прошла успешно, в блоке появится ссылка на бота. Если возникла проблема, прочитайте сообщение в строке ошибки и проверьте токен.

Кнопка «Синхронизировать Menu Button»

Эта кнопка не подключает бота заново. Она обновляет кнопку меню Telegram в соответствии с выбранным режимом WebApp: интернет-витрина или онлайн-запись.

Используйте её после изменения режима WebApp, чтобы настройки кнопки в Telegram соответствовали выбранному сценарию работы.

Кнопка «Отключить»

Снимает подключение Telegram-бота к Меркурию. Кнопка отображается, когда бот уже подключён.

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

Блок «WebApp для Telegram (@BotFather)»

После подключения становится доступен блок со ссылкой на мини-приложение. Адрес отображается в поле только для чтения. Кнопка «Копировать» позволяет скопировать его без выделения текста вручную.

Этот URL понадобится, если вы хотите, чтобы покупатель открывал интернет-витрину или онлайн-запись прямо внутри Telegram. Его нужно будет указать в настройках через @BotFather.

Обратите внимание: токен и URL WebApp — совершенно разные значения. Токен вставляется в Меркурий для подключения бота, а URL копируется из Меркурия и используется при настройке мини-приложения в Telegram.

Подробная инструкция: «Домен WebApp Telegram».

Режим WebApp

Выше по вкладке находится переключатель режима:

«Интернет-витрина (магазин)» — мини-приложение открывает магазин.
«Запись клиентов» — мини-приложение предназначено для онлайн-записи.

Выбранный режим влияет на назначение кнопки меню Telegram. После его изменения сохраните настройки программы и нажмите «Синхронизировать Menu Button».

Строка ошибки

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

Важное замечание: один токен — один бот

Один Telegram-токен относится к одному конкретному боту. Если вы укажете токен другого бота, Меркурий будет подключать именно его.

При подключении Меркурий регистрирует webhook на своём сервере. Если у этого токена ранее был зарегистрирован другой webhook, он переключится на сервер Меркурий-ИИ. Поэтому не используйте один и тот же токен одновременно для разных интеграций, если ожидаете, что каждая из них будет самостоятельно получать сообщения от Telegram.

Создание нового бота в @BotFather

Если у вашего магазина ещё нет Telegram-бота, его можно создать через официального служебного бота Telegram — @BotFather.

Для этого понадобится обычный аккаунт Telegram. Создание бота выполняется в переписке с @BotFather.

Шаг 1. Откройте @BotFather

Перейдите по ссылке t.me/BotFather и откройте чат. Нажмите Start или отправьте команду /start.

Убедитесь, что открыли именно официального @BotFather, а не стороннего бота с похожим названием.

Шаг 2. Запустите создание бота

Отправьте команду:

/newbot

BotFather начнёт задавать вопросы и предложит указать имя и username нового бота.

Шаг 3. Укажите отображаемое имя

Сначала введите имя бота. Это название, которое увидит покупатель в Telegram.

Например, если магазин называется «Продукты у дома», в качестве имени можно использовать «Продукты у дома». Имя должно помогать покупателю понять, с каким магазином он общается.

Шаг 4. Придумайте username

Затем BotFather попросит указать уникальное имя пользователя — username.

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

Именно по username формируется ссылка на бота в Telegram. Например, ссылка может иметь вид https://t.me/example_shop_bot.

Шаг 5. Скопируйте HTTP API token

После успешного создания BotFather отправит сообщение с данными нового бота. В нём будет указан HTTP API token.

Скопируйте токен целиком. Не копируйте вместо него username, ссылку на бота или другие строки из сообщения. Токен обычно содержит числовую часть, двоеточие и последовательность букв и цифр.

Важно: токен является секретным. Не публикуйте сообщение BotFather целиком и не пересылайте его посторонним. Для подключения в Меркурии нужен только сам токен.

Шаг 6. Подключите бота в Меркурии

Откройте «Розница → Дисконтная программа → Боты».
Найдите блок «Telegram-бот».
Вставьте скопированный HTTP API token в поле «Токен бота».
Нажмите «Подключить Telegram».
Дождитесь результата и проверьте, что в статусе появилась ссылка на вашего бота.

На этом подключение бота к Меркурию выполнено. Если вы планируете открывать интернет-витрину или онлайн-запись внутри Telegram, дополнительно настройте WebApp. Это отдельный этап, описанный в статье «Домен WebApp Telegram».

Как получить токен уже созданного бота

Если бот уже существует, создавать новый необязательно. Можно получить токен ранее созданного бота через @BotFather.

Откройте чат с @BotFather.
Отправьте команду /mybots.
Выберите из списка нужного бота. Ориентируйтесь на его имя и username, чтобы случайно не выбрать другой бот.
Откройте пункт API Token.
Получите и скопируйте текущий токен.
Вернитесь в Меркурий, вставьте токен в поле «Токен бота» и нажмите «Подключить Telegram».

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

Что такое Revoke

В меню BotFather также есть действие Revoke. Оно предназначено для отзыва старого токена и получения нового.

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

Используйте отзыв токена, если он стал известен посторонним или есть основания считать, что он скомпрометирован.

Дополнительные настройки BotFather

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

/setdescription — настройка описания бота.
/setabouttext — настройка краткого текста о боте.
/setuserpic — установка изображения профиля бота.
/setcommands — настройка списка команд, который Telegram показывает пользователю.

Например, для команды /start можно задать понятное название — «Регистрация в программе». Это текст в списке команд, а не настройка самого механизма регистрации.

Если вы используете интернет-витрину или онлайн-запись внутри Telegram, потребуется также настроить домен и адрес WebApp. Для этого используются команды /setdomain, /newapp и /setmenubutton. Не путайте эти действия с получением токена: они выполняются уже после создания и подключения бота.