← Все статьи
Гайд

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.

  1. Начните в авторизованной сессии сайта. Покажите аккаунт, который будет привязан, и потребуйте осознанное действие. Примените обычные средства защиты сессии и от подделки запросов.
  2. Создайте ожидающий запрос на сервере. Сгенерируйте криптографически стойкий случайный токен, допустимый в URL. Сохраните его хеш, целевой аккаунт сайта, целевого бота, назначение, срок действия и статус ожидания. Это рекомендуемые локальные записи, не поля Telegram API. Срок определяет ваша политика риска: формат параметра Telegram не задаёт время жизни токена приложения.
  3. Получите и проверьте настоящее обновление. Проверьте подлинность входящего запроса, принимайте только сообщение личного чата нужного бота, точно разбирайте /start и проверяйте длину и алфавит параметра. Используйте отправителя из сообщения, а не ID, указанный в параметре. Объекты Update и Message определены в справочнике Bot API.
  4. Зафиксируйте предъявителя, но не выдавайте доступ сразу. Атомарно свяжите ожидающий запрос с наблюдаемым пользователем Telegram. Отклоняйте истёкшие запросы и попытки другого пользователя предъявить уже закреплённый токен. Не раскрывайте сведения об аккаунте сайта неподтверждённому отправителю Telegram.
  5. Подтвердите пару в исходной сессии сайта. Покажите предложенную учётную запись Telegram и запросите согласие вошедшего владельца аккаунта. При несовпадении отмените запрос, не перезаписывая существующую связь. Для чувствительных операций добавьте подходящее подтверждение и в Telegram.
  6. Завершите операцию один раз и сохраните минимальный аудит. Окончательное погашение токена и создание связи должны быть атомарными. Повторная доставка или нажатие 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:

UnifyPort API

Превратите интеграцию сообщений в стабильный продуктовый pipeline.

Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.