Привязка Telegram

Полный перечень полей — в глоссарии.

​

Что это и зачем

Раздел отвечает за то, как сотрудник привязывает свой аккаунт Telegram к профилю в системе, чтобы получать в этот чат уведомления, и как он может отвязать его. Привязка нужна, потому что канал доставки в Telegram отправляет сообщения не по номеру телефона и не по логину, а по конкретному чату — и система должна заранее знать, какой чат принадлежит какому сотруднику в какой компании. Механика построена на подтверждении по одноразовому коду: сначала сотрудник открывает бот в Telegram, бот заводит предварительную (неподтверждённую) запись и выдаёт код, а затем сотрудник вводит этот код в веб- или мобильном интерфейсе, уже находясь под своим рабочим аккаунтом. Только после ввода кода чат «переезжает» на его аккаунт и текущую компанию.

​

Модель данных

В привязке участвует связка Пользователя Telegram — записи, соединяющей Telegram-чат с сотрудником и компанией. В процессе привязки таких записей две: временная неподтверждённая (её создаёт бот вместе с кодом) и итоговая подтверждённая (её формирует система после успешной проверки кода). У пары «Компания + Сотрудник» действует ограничение уникальности: в одной компании у сотрудника может быть только одна привязка Telegram.

​

Как проходит привязка

Привязка выполняется через endpoint привязки Telegram, доступный только авторизованному сотруднику. У него две операции:

• Отправка кода — сотрудник передаёт код, полученный от бота (принимается от 6 до 10 символов). На эту операцию действует лимит 10 попыток в минуту на сотрудника.
• Просмотр текущей привязки — возвращает уже существующую привязку сотрудника в текущей компании (если её нет — «не найдено»). Эта операция не ограничена лимитом: интерфейс опрашивает её, чтобы показать состояние привязки.

​

Проверка кода

При отправке кода формат привязки Telegram делает следующее:

1. Берёт текущую компанию (определённую по контексту запроса) и текущего сотрудника (из авторизации).
2. Ищет неподтверждённую запись Пользователя Telegram с таким же кодом подтверждения.
3. Если ни одной неподтверждённой записи с этим кодом нет — запрос завершается ответом «не найдено» (404), привязка не создаётся.
4. Если по одному коду нашлось несколько ожидающих чатов — код считается неоднозначным и тоже отклоняется ответом «не найдено». Произвольный выбор одного из чатов не делается: код нужно получить заново.

​

Перенос чата и подтверждение

Если неподтверждённая запись найдена, система:

1. Запоминает данные чата: ID чата, Telegram-логин, имя и фамилию.
2. Удаляет временную неподтверждённую запись.
3. Освобождает прежнюю привязку этого сотрудника в этой компании, если она была сделана к другому чату. Так «перепривязать» Telegram к новому чату можно сразу, не отвязывая старый вручную.
4. Создаёт (или обновляет, если такая уже есть) подтверждённую запись по ID чата: проставляет текущую компанию, текущего сотрудника, переносит логин/имя/фамилию, включает флаг «подтверждён» и обнуляет код подтверждения.
5. Отправляет в этот чат сообщение об успешной привязке (фоновой задачей доставки в Telegram).

Ключом переноса выступает именно ID чата: подтверждённая запись привязывается к тому же чату, что и временная. За счёт режима «обновить или создать» повторная привязка того же чата не плодит дубликаты, а перезаписывает существующую привязку — например, чат можно таким образом переназначить на другого сотрудника или другую компанию.

​

Как проходит отвязка

Отвязка выполняется через отдельный endpoint отвязки Telegram, тоже доступный только авторизованному сотруднику. Здесь формат отвязки Telegram не принимает никаких входных полей: он находит привязку текущего сотрудника в текущей компании и удаляет её. Если у сотрудника нет привязки в этой компании — ответ «не найдено» (404).

​

Как это используется

• После успешной привязки чат становится готовым адресатом для канала доставки в Telegram: уведомления, у которых включена доставка в этот канал, будут уходить в привязанный чат.
• Просмотр текущей привязки (операция чтения на endpoint привязки) позволяет интерфейсу показать, привязан ли уже Telegram у сотрудника, и под каким логином.
• Отвязка нужна, когда сотрудник хочет перестать получать уведомления в Telegram или сменить чат — после отвязки можно пройти привязку заново с новым кодом.

​

Особенности поведения

• Если по одному и тому же коду существует несколько неподтверждённых записей, привязка не выполняется вовсе: код отклоняется как неоднозначный, ни один из чатов не выбирается.
• Слишком частые попытки ввода кода отклоняются: больше 10 попыток в минуту от одного сотрудника не принимается. Просмотр состояния привязки лимитом не ограничен.
• Привязка выполняется в режиме «обновить или создать» по ID чата, поэтому повторный ввод кода для уже привязанного чата не создаёт дубликат, а перезаписывает существующую привязку (может сменить сотрудника или компанию у чата).
• Привязка нового чата, когда у сотрудника в этой же компании уже есть привязка к другому чату, проходит штатно: прежняя привязка освобождается автоматически, отвязывать старый чат вручную не нужно.
• Между удалением временной записи и созданием подтверждённой нет явной единой транзакции: при сбое на шаге создания временная запись уже удалена, и код придётся получать заново.
• Отвязка работает только в границах текущей компании: удаляется привязка сотрудника именно в той компании, в контексте которой сделан запрос, привязки в других компаниях остаются.
• Сообщение об успешной привязке отправляется фоновой задачей, поэтому доставка подтверждения в чат может произойти с задержкой или не произойти при сбое очереди, хотя сама привязка уже сохранена.
• У кода нет срока жизни: выданный ботом код остаётся действующим, пока чат не подтверждён или запись не удалена.

​

Связанные страницы