Deep links Telegram-бота: параметр start и привязка аккаунтов
Deep link Telegram-бота передаёт параметр через команду /start в личном чате. Сам по себе он не доказывает, что аккаунт сайта и пользователь Telegram принадлежат одному человеку. Используйте параметр для поиска ожидающего запроса на сервере, дождитесь обновления для бота и явно подтвердите чувствительную привязку аккаунтов. Открытие URL — ещё не завершение операции.
Главное
- Параметр запуска допускает до 64 символов: латинские буквы, цифры, подчёркивания и дефисы.
startотносится к личному чату;startgroupзапускает отдельный сценарий добавления в группу.- Код кампании может быть публичным. Токен привязки должен быть непредсказуемым, короткоживущим и одноразовым.
- Начало диалога с ботом и авторизация существующего аккаунта Telegram — разные интеграции.
Что передаёт ссылка с параметром start
В документации возможностей ботов Telegram описывает deep linking, в том числе для связи пользователя Telegram с аккаунтом на другой платформе. Синтаксис: https://t.me/<bot_username>?start=<parameter>. Значения в угловых скобках поясняют структуру URL, а не обозначают работающего бота или реальный токен.
Спецификация ссылок для клиентов описывает кнопку Start, которая вызывает запуск бота с параметром. Поэтому интерфейс должен опираться на полученную команду, а не на клик в браузере или предполагаемую автоматическую отправку. Бот получает текст вроде /start airplane; здесь использован пример Telegram.
Допустимы A-Z, a-z, 0-9, _ и -, не более 64 символов. Для двоичных и других данных Telegram рекомендует base64url. Но кодирование не является шифрованием и не делает данные достоверными. Не помещайте в URL пароль, bot token, API hash, адрес электронной почты или повторно используемые данные входа.
Добавление в группу описано отдельно через startgroup. Команда в группе не должна считаться доказательством прохождения личного сценария привязки.
Разделяйте маршрутизацию и подтверждение личности
| Задача | Рекомендуемый параметр | Что устанавливает его получение |
|---|---|---|
| Открыть раздел справки | Публичный код из разрешённого списка | Пользователь запросил этот раздел |
| Зафиксировать источник кампании | Публичный код кампании | Источник входа, а не подтверждённую личность |
| Привязать аккаунт авторизованного пользователя сайта | Непрозрачная одноразовая ссылка на серверную запись | Ожидающую подтверждения связь |
Пользователь может набрать команду вручную или переслать ссылку. Номер клиента в параметре не доказывает, что отправитель владеет соответствующей записью. Даже непредсказуемый токен можно переслать или раскрыть: случайность не подтверждает, что выбрана именно нужная пара аккаунтов.
Если границы учётных данных пока неясны, сначала прочитайте сравнение Telegram API ID, API hash и bot token. Параметр запуска — входные данные приложения, а не одна из этих учётных данных.
Рекомендуемый сценарий привязки
Ниже — рекомендации по архитектуре приложения, а не готовый сервис токенов Telegram и не новый endpoint UnifyPort.
- Начните в авторизованной сессии сайта. Покажите аккаунт, который будет привязан, и потребуйте осознанное действие. Примените обычные средства защиты сессии и от подделки запросов.
- Создайте ожидающий запрос на сервере. Сгенерируйте криптографически стойкий случайный токен, допустимый в URL. Сохраните его хеш, целевой аккаунт сайта, целевого бота, назначение, срок действия и статус ожидания. Это рекомендуемые локальные записи, не поля Telegram API. Срок определяет ваша политика риска: формат параметра Telegram не задаёт время жизни токена приложения.
- Получите и проверьте настоящее обновление. Проверьте подлинность входящего запроса, принимайте только сообщение личного чата нужного бота, точно разбирайте
/startи проверяйте длину и алфавит параметра. Используйте отправителя из сообщения, а не ID, указанный в параметре. ОбъектыUpdateиMessageопределены в справочнике Bot API. - Зафиксируйте предъявителя, но не выдавайте доступ сразу. Атомарно свяжите ожидающий запрос с наблюдаемым пользователем Telegram. Отклоняйте истёкшие запросы и попытки другого пользователя предъявить уже закреплённый токен. Не раскрывайте сведения об аккаунте сайта неподтверждённому отправителю Telegram.
- Подтвердите пару в исходной сессии сайта. Покажите предложенную учётную запись Telegram и запросите согласие вошедшего владельца аккаунта. При несовпадении отмените запрос, не перезаписывая существующую связь. Для чувствительных операций добавьте подходящее подтверждение и в Telegram.
- Завершите операцию один раз и сохраните минимальный аудит. Окончательное погашение токена и создание связи должны быть атомарными. Повторная доставка или нажатие Start не должны создавать новую связь, переносить привязку или повторно выдавать бонус. Отвязку оформите отдельным действием с авторизацией.
Не записывайте исходные токены в аналитику, логи, снимки экрана и обращения в поддержку. Ограничивайте частоту неверных попыток. Если подтверждение не поступило, завершите срок действия запроса без выдачи доступа.
Ищите незавершённый этап
| Наблюдение | Что проверить дальше |
|---|---|
| Ссылка открывается, команда не приходит | Имя бота, нажатие Start и получение обновлений |
Приходит только /start | Покажите обычное начало работы; не угадывайте аккаунт без параметра |
| Параметр неверен или просрочен | Предложите новый запрос из авторизованной сессии сайта |
| То же обновление приходит повторно | Используйте сохранённый результат, не повторяйте привязку |
| Другой пользователь предъявляет закреплённый токен | Отклоните и предложите новый сценарий; не переносите связь автоматически |
| Бот получил команду, сайт всё ещё ждёт | Проверьте фиксацию предъявителя и подтверждение в приложении |
Для выбора транспорта используйте отдельное сравнение Bot API webhook и унифицированного входящего webhook. Ни polling, ни webhook сами по себе не решают задачу подтверждения личности.
Где подходит UnifyPort
Этот сценарий относится к официальному Telegram-боту. В справочнике авторизации Telegram в UnifyPort описан другой путь: подключение существующего аккаунта через неофициальный интерфейс с кодом, QR или импортом сессии. Параметр запуска бота не авторизует такой аккаунт и не заменяет согласие его владельца.
Если задача — получать сообщения существующего аккаунта для переписки, используйте эту авторизацию и документированное событие message.received. Не рассчитывайте, что deep link бота попадёт во входящие подключённого обычного аккаунта. Даже если поддержка работает также с WhatsApp, LINE или Zalo, привязка личности остаётся отдельной задачей приложения.
Частые вопросы
Открытие ссылки завершает привязку?
Нет. Нужны команда боту и подтверждающая транзакция вашего приложения. Клик не доказывает ни получение сообщения, ни владение аккаунтом.
Можно передавать ID клиента в start?
Как нечувствительное значение для маршрутизации — можно, как основание для доступа — нельзя. Для привязки используйте случайную серверную ссылку и явное подтверждение.
Защищает ли base64url секрет?
Нет, это кодирование. Чувствительные сведения храните на сервере, а URL привязки считайте секретным до погашения или истечения токена.
Это то же самое, что вход в пользовательский аккаунт Telegram?
Нет. Начало взаимодействия с ботом не создаёт авторизованную пользовательскую сессию. Выбирайте интеграцию по тому, от чьего имени должно работать приложение.
Следующий шаг и источники
Начните со спецификации deep links Telegram, затем проверьте отсутствие параметра, пересланную ссылку, истечение срока, дубли обновлений, конфликт пользователей и отмену. Это предлагаемые приёмочные проверки, а не отчёт о выполненных тестах.
Официальные материалы проверены 2026-11-10:
Превратите интеграцию сообщений в стабильный продуктовый pipeline.
Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.