TelegramCRMintegration

Смена username в Telegram: как не потерять контакт в CRM

11 мин чтения

Политика идентичности для собственной Telegram-интеграции: изменяемые псевдонимы, границы отправителя, локальный SQLite-тест и перенос старых записей.

Смена username в Telegram: как не потерять контакт в CRM

Привязывайте Telegram-аккаунт к контакту CRM по доверенно полученному User.id, а username храните как изменяемый атрибут. Тогда новое имя того же аккаунта обновит подпись существующей карточки. Совпадение имени у другого ID не должно объединять историю обращений, открывать старые документы или менять получателя ответа.

Это проектная политика для собственной интеграции Telegram Bot API с CRM. Она не описывает подтверждённую настройку 24go.site и не требует собирать чужие номера. Пример ниже работает только с обычными входящими сообщениями в личном чате с ботом после проверки доставки и структуры события. Он не устанавливает личность человека, права на сделку или согласие на рекламные сообщения.

Какие поля отвечают за имя, аккаунт и беседу

В объекте User поле id обозначено как уникальный идентификатор пользователя или бота. Поле username необязательно. Имя и фамилия нужны для отображения; даже заполненное имя не является доказательством, что два отправителя принадлежат одному клиенту.

Разделите три сущности. Telegram-аккаунт связывается с внутренним контактом вашей системы. Беседа определяет контекст, в котором получено сообщение. Сделка отражает отдельный запрос клиента. Один аккаунт может отправить несколько разных запросов, а одна организация может общаться через нескольких сотрудников. Эти отношения задаёт процесс CRM, не строка username.

Для маршрута ответа сохраняйте message.chat.id из разрешённого события. Не восстанавливайте адресата по старой ссылке t.me/.... В sendMessage строковый username в chat_id описан для целевого бота, супергруппы или канала. Это не обещание отправки обычному частному пользователю по любому псевдониму. Даже корректный числовой маршрут сам по себе не даёт разрешения написать человеку.

В FAQ Telegram прямо указано, что username необязателен, а его удаление не влияет на существующие беседы. У collectible usernames также есть возможность назначения другому чату или передачи владельца. Поэтому историю обращений нельзя защищать уникальностью текстового псевдонима в вашей таблице.

Сначала проверьте, кого представляет событие

Нельзя брать любой вложенный id из JSON и считать его человеком, который сейчас обратился в компанию. У Message поле from необязательно. При отправке от имени чата sender_chat несёт соответствующий контекст, а from для обратной совместимости может содержать фиктивного пользователя-отправителя.

Простой маршрут этой статьи допускает только message.chat.type == "private", объект from с целочисленным положительным ID и is_bot == false. События с sender_chat, business_connection_id или guest_query_id он оставляет отдельному обработчику. Такой отказ - выбранная граница примера, а не заявление, что эти события нельзя обрабатывать вообще.

Telegram Business и гостевые вызовы требуют собственной модели контекста. Документация предупреждает, что их беседа может быть независимой от обычного чата бота с тем же идентификатором. Добавление одного общего ключа по имени не решает эту разницу. Перед расширением обработчика отдельно определите владельца подключения, права доступа и маршрут ответа.

Пересланный текст и упоминание @name в сообщении тоже не меняют отправителя текущего события. Не присваивайте автору пересланного материала CRM-контакт собеседника автоматически. Если задача - записать номер из присланного контакта, используйте отдельную проверку владельца contact.

Таблица решений перед записью в CRM

Сначала находите связь по идентификатору аккаунта в пространстве вашей организации. Под пространством здесь понимается tenant: отдельный клиент вашего SaaS или изолированный проект. Одинаковый Telegram ID у двух tenants не должен автоматически открыть им общую карточку.

Наблюдение Действие интеграции Что сохраняется
Известный ID, новый username Обновить наблюдаемую подпись Тот же внутренний контакт и история
Известный ID, username отсутствует в полном User Снять текущую подпись либо явно отметить отсутствие Привязка по ID остаётся
Другой ID, знакомый username Отдельная связь; спорную бизнес-привязку проверить Истории не объединяются
Нет допустимого from или есть sender_chat Не запускать этот маршрут Исходное событие для ограниченного разбора
Другой tenant, тот же Telegram ID Искать только внутри нового tenant Изоляция данных проектов
Известный контакт, новый вопрос Применить правило открытия сделки Контакт и сделка не смешиваются

Отсутствие username в полной структуре User и отсутствие поля в частичном обновлении вашей CRM - разные вещи. Первый случай может означать, что отображаемого имени нет. Второй может означать, что источник ничего не сообщил об атрибуте. Задайте контракт адаптера: полная замена наблюдаемого профиля или частичная правка. Не очищайте поля по отсутствию ключа в произвольном промежуточном JSON.

Минимальная модель данных и защита от конфликтов

Храните внутренний ID контакта отдельно от Telegram ID. Для таблицы внешних связей можно выбрать уникальный ключ (tenant_id, source, telegram_user_id), где source явно равен telegram. Это предлагаемая схема вашей системы, не формат Telegram. Если несколько ботов одного tenant должны видеть общий контакт, согласуйте это как правило доступа; иначе добавьте bot/integration namespace.

Username лучше хранить в поле вроде observed_username с временем и источником наблюдения. Исторический псевдоним, если он действительно нужен, помечайте прошлым значением без права адресации или автоматического поиска владельца. Не создавайте уникальный ключ контакта по username и не делайте его запасным ключом, когда ID неизвестен.

Документация User предупреждает, что ID может не поместиться в 32 бита и имеет не более 52 значащих бит. Выберите тип без потери точности на всём маршруте: например, signed BIGINT в базе и явно согласованное представление в сообщениях очереди. Если ваша граница использует десятичную строку, проверяйте и преобразуйте её намеренно; обрезанный 32-битный ID нельзя исправить последующим приведением типа.

Поставьте ограничение уникальности в базе, а запись связи выполняйте в транзакции. Предварительный поиск без защиты записи оставляет гонку: два обработчика могут одновременно решить, что контакта ещё нет. Если CRM находится в другом сервисе, локальная транзакция не охватывает удалённое создание. Для этого нужен отдельный протокол операции и разбор повторных вебхуков и неоднозначных таймаутов.

Локальная проверка на искусственных сообщениях

Этот пример проверяет выбор контакта в SQLite. Нужен Python 3 со стандартным модулем sqlite3. Сохраните блок как identity_policy_test.py и выполните python3 identity_policy_test.py без флага -O: он отключает assert. Входные ID и псевдонимы искусственные, код не обращается к Telegram или CRM и не отправляет сообщения.

Функция предполагает уже проверенную структуру сообщения: chat и from, если присутствуют, должны быть объектами. Она дополнительно отказывает нескольким контекстам, но не заменяет парсер произвольного JSON или проверку секрета вебхука. Tenant передаётся сервером из доверенной конфигурации, его нельзя брать из текста клиента.

import copy
import json
import sqlite3


def bind(db, tenant, message):
    if message.get("chat", {}).get("type") != "private":
        return None
    if any(message.get(k) is not None for k in (
        "sender_chat", "business_connection_id", "guest_query_id"
    )):
        return None
    user = message.get("from", {})
    uid = user.get("id")
    if type(uid) is not int or uid <= 0 or user.get("is_bot") is not False:
        return None
    username = user.get("username")
    if username is not None and not isinstance(username, str):
        return None
    with db:
        db.execute(
            "INSERT INTO identity(tenant, source, uid, username) "
            "VALUES (?, 'telegram', ?, ?) "
            "ON CONFLICT(tenant, source, uid) DO UPDATE "
            "SET username=excluded.username",
            (tenant, uid, username),
        )
        row = db.execute(
            "SELECT contact_id FROM identity "
            "WHERE tenant=? AND source='telegram' AND uid=?",
            (tenant, uid),
        ).fetchone()
    return row[0]


db = sqlite3.connect(":memory:")
db.execute("CREATE TABLE identity (contact_id INTEGER PRIMARY KEY, "
           "tenant TEXT NOT NULL, source TEXT NOT NULL, uid INTEGER NOT NULL, "
           "username TEXT, UNIQUE(tenant, source, uid))")
base = {"chat": {"type": "private", "id": 1001},
        "from": {"id": 1001, "is_bot": False, "username": "sample_old"}}
a = bind(db, "tenant-a", base)
renamed = copy.deepcopy(base)
renamed["from"]["username"] = "sample_new"
assert bind(db, "tenant-a", renamed) == a
removed = copy.deepcopy(base)
del removed["from"]["username"]
assert bind(db, "tenant-a", removed) == a
assert db.execute("SELECT username FROM identity WHERE contact_id=?",
                  (a,)).fetchone()[0] is None
other = copy.deepcopy(base)
other["from"]["id"] = 2002
other["chat"]["id"] = 2002
b = bind(db, "tenant-a", other)
c = bind(db, "tenant-b", base)
assert len({a, b, c}) == 3
for field in ("sender_chat", "business_connection_id", "guest_query_id"):
    unsupported = copy.deepcopy(base)
    unsupported[field] = {} if field == "sender_chat" else "TEST"
    assert bind(db, "tenant-a", unsupported) is None
no_id = copy.deepcopy(base)
del no_id["from"]["id"]
assert bind(db, "tenant-a", no_id) is None
group = copy.deepcopy(base)
group["chat"]["type"] = "supergroup"
assert bind(db, "tenant-a", group) is None
assert db.execute("SELECT COUNT(*) FROM identity").fetchone()[0] == 3
print(json.dumps({"contacts": 3, "rename_same_contact": True,
                  "missing_username_same_contact": True,
                  "alias_reuse_separate": True, "tenants_separate": True,
                  "unsupported_rejected": True}))

При успехе вывод содержит contacts: 3 и все пять проверочных признаков со значением true. Три записи соответствуют исходному аккаунту, другому аккаунту с таким же искусственным псевдонимом и отдельному tenant. Отсутствующий username записывается как SQL NULL, а внутренний ID первого контакта не меняется.

Это проверка предложенной политики в памяти одного процесса. Она не доказывает обработку одновременных HTTP-запросов, работу вашей CRM, актуальность реального псевдонима или аутентификацию Telegram. В демонстрации contact_id одновременно служит внутренним ключом строки связи; в настоящей CRM обычно есть отдельные таблицы контактов и внешних идентификаторов. При AssertionError сначала найдите нарушенную ветку, не удаляйте проверку ради зелёного вывода.

Как перенести старые карточки с ключом по username

Не запускайте массовое объединение по совпадению старого и нового имени. Сначала сделайте резервную копию и создайте таблицу предлагаемых связей без изменения CRM. Для каждой записи сохраните основание: доверенно полученное событие, существующая подтверждённая связь или необходимость ручного разбора. Псевдоним из старого CSV сам по себе таким основанием не является.

  1. Выделите карточки, у которых уже есть проверенный Telegram ID. Проверьте точность типа и источник значения, затем сгруппируйте конфликты внутри tenant. Два CRM-контакта для одного ID требуют решения владельца процесса, не выбора «первого найденного».
  2. Username-only карточки оставьте непроверенными. При новом входящем сообщении создайте или найдите связь по ID, но не прикрепляйте старую историю только потому, что имя похоже. Если нужен доступ к прежним заказам, проведите отдельную разрешённую проверку клиента.
  3. Проверьте предложения на копии данных. Зафиксируйте число записей без основания, конфликтов и изменений маршрута. Не выдавайте необработанный список за успешно перенесённую базу.
  4. Переносите согласованные связи ограниченными партиями с журналом старого и нового ключа. Запись партии должна быть повторяемой без нового объединения, а отмена - возвращать только её собственные изменения.
  5. Оставьте старый username как историческое наблюдение с ограниченным доступом, если для хранения есть цель. Запретите старому индексу самостоятельно выбирать адресата или открывать документы после переключения.

Если пользователь удалил аккаунт и зарегистрировался заново, FAQ Telegram описывает его как нового пользователя. Новый ID нельзя автоматически считать доказательством того, что это тот же клиент, чья связь была подтверждена ранее. Похожее имя, фотография или сообщение «это снова я» подходят для начала проверки, но не для выдачи архивных данных.

Что проверить в настоящей интеграции

Отдельно проведите приёмку на тестовом боте и тестовой CRM с согласованными участниками. Локальный SQLite-вывод не подтверждает следующие результаты. Для каждого случая сохраните время, выбранную ветку и внутренние ссылки на тестовые записи без токенов и полных переписок.

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

Проверьте два разных тестовых ID с одинаковой искусственной подписью в изолированных fixtures, а также один ID в разных tenants. Во втором случае пользователь может быть тем же Telegram-аккаунтом, но доступ сотрудников и CRM-данные проектов должны оставаться разделёнными. Для первого случая не требуется захватывать чужой реальный username.

Передайте неподдерживаемые контексты, повторную доставку и сбой удалённого создания контакта. Ожидайте отказа ограниченного маршрута, отсутствие лишнего эффекта от повтора и остановку неоднозначной операции до сверки. В старом общем материале об интеграции Telegram с CRM среди советов встречается поиск дублей по username. Для политики идентичности из этой статьи этот совет не подходит: имя не должно решать, кому принадлежит история. Конкретные гарантии вашей CRM проверяются отдельно.

Где заканчивается идентификация аккаунта

Telegram ID помогает не перепутать технические аккаунты в разрешённых событиях. Он не подтверждает полномочия сотрудника компании, владение договором, номер телефона или право получить закрытые файлы. Проверку доступа выполняйте перед каждым соответствующим действием по текущей связи с клиентом и роли оператора.

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

Для проекта на 24go.site сначала зафиксируйте эти требования в задании интегратору, затем проверьте реальные поддерживаемые функции и права подключения. Начинать перенос стоит с копии и отчёта о конфликтах: корректное обновление подписи должно сохранять связь аккаунта, не расширяя доступ к чужой истории.

Источники