Поиск Telegram-имени пользователя по списку телефонных номеров

Руководство по добавлению Telegram-имен пользователей к списку телефонных номеров конкретной страны с помощью пакетной службы tg_active_batch, включая подготовку файлов, описание столбцов result.csv, обработку пустых имен и ответственное использование.

Чтобы найти Telegram-имя пользователя, привязанное к номерам телефонов из бизнес-списка, пропустите этот список через пакетную задачу, такую как tg_active_batch от TG Validator. Она возвращает статус регистрации в Telegram, а также uid, имя пользователя и activedays для каждого номера. Столбец с именем пользователя остается пустым, если у учетной записи нет публичного имени, поскольку в Telegram это необязательная настройка. Рассматривайте полученные данные как обогащение записей, которые уже есть у вашей команды, а не как способ поиска неизвестных людей.

Почему команды ищут Telegram-имя пользователя по номеру телефона

Большинство руководств по этому запросу описывают потребительский путь: сохраните номер в контактах, откройте профиль в приложении и прочитайте имя пользователя, если оно указано. Это работает для одного друга. Но это не подходит для экспорта из CRM, содержащего несколько тысяч лидов, и к тому же передает бизнес-данные через личную адресную книгу сотрудника.

У бизнес-команд обычно другие цели:

• Команды поддержки хотят получить имя пользователя, чтобы агенты могли ссылаться на профиль клиента в Telegram через ссылку t.me, если клиент попросил связаться с ним именно там.
• Команды по развитию сообществ хотят сопоставить существующие контакты с именами, которые уже фигурируют в их собственных группах или каналах.
• CRM-команды хотят иметь стабильный ключ Telegram рядом с каждой записью телефона, чтобы можно было объединять дубликаты.

Все три задачи — это обогащение записей, которыми организация уже владеет. Такая постановка вопроса важна как для метода, так и для последующего использования данных.

Как связаны Telegram-имена и номера телефонов

В Telegram учетная запись создается на основе номера телефона, а имя пользователя — это необязательный публичный идентификатор. В Telegram FAQ поясняется, что пользователям не обязательно иметь имя пользователя, они могут установить или удалить его в настройках, а также делиться ссылками t.me, чтобы другие могли связаться с ними, не видя их номера. Пользователи также сами решают, кто может видеть их номер телефона и кто может найти их по нему.

Из этого следуют два практических вывода:

1. У многих учетных записей нет имени пользователя, поэтому пустой столбец — это нормальный результат, а не ошибка.
2. Имена пользователей могут меняться или удаляться. Имя, полученное сегодня, должно сопровождаться датой его получения.

Telegram uid отличается: это числовой идентификатор учетной записи, который не меняется при смене имени пользователя. Это делает uid более надежным ключом для дедупликации, чем имя пользователя.

Какая служба TG Validator возвращает имена пользователей

Проверка регистрации в Telegram для одного номера, доступная в панели управления или через POST /api/v1/check, возвращает только статус регистрации. Это подходящий инструмент для определения того, есть ли у номера учетная запись в Telegram, но он не возвращает имена пользователей.

Имена пользователей предоставляются асинхронной пакетной службой tg_active_batch. Для каждого номера телефона она возвращает:

Дополнительные столбцы зависят от типа службы и могут быть пустыми для некоторых строк. Если команде также нужны URL-адреса аватаров и оценки на основе аватаров, используйте отдельную службу профилей tg_profile_batch; для данной задачи tg_active_batch является наиболее подходящим выбором.

Пошаговое руководство: от списка телефонов до столбца с именами

1. Выберите одну страну для файла. Пакетные задачи для номеров телефонов требуют выбора одной страны, и файл должен состоять преимущественно из номеров этой страны. Если 10% или более номеров используют другие коды стран, файл будет отклонен, поэтому сначала разделите смешанные списки по странам.
2. Нормализуйте формат до международного. Используйте коды стран в соответствии с ITU-T Recommendation E.164, удалите префиксы выхода на междугороднюю связь, пробелы и символы, а также удалите дубликаты.
3. Сохраните в формате TXT или CSV с одним номером в строке. Применяются ограничения на размер файла и количество записей для каждого продукта; ознакомьтесь с текущей документацией API.
4. Создайте задачу в разделе пакетной проверки (Bulk Check) панели управления или с помощью POST /api/v1/bulk-tasks, выбрав tg_active_batch и страну.
5. Дождитесь завершения задачи. Задача сообщает о статусах обработки, успешного выполнения или сбоя. При опросе через API делайте это не чаще одного раза в 30 секунд.
6. Загрузите result.csv и объедините его с исходным списком по столбцу identifier.

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

Номера материкового Китая (+86), Гонконга (+852) и Макао (+853) не поддерживаются в пакетных файловых задачах, поэтому исключите их из загружаемого файла.

Чтение и хранение результатов с именами пользователей

После того как result.csv будет объединен с исходным списком, распределите строки по практическим группам:

• Учетная запись есть, имя пользователя есть. Сохраните имя пользователя и uid в выделенных полях CRM с датой выполнения задачи.
• Учетная запись есть, имя пользователя пустое. Учетная запись существует, но у нее нет публичного идентификатора. Сохраните uid для дедупликации, а поле имени пользователя оставьте пустым, не придумывая значений.
• Учетной записи нет. Отметьте поле Telegram и сохраните номер для других каналов связи.
• Столбцы пусты по другим причинам. Некоторые дополнительные столбцы могут быть пустыми для ряда строк; рассматривайте их как неизвестные данные, а не как нулевые значения.

Несколько правил хранения помогут избежать путаницы в будущем:

• Храните имена пользователей без символа @ и приводите их к нижнему регистру, так как имена пользователей в Telegram нечувствительны к регистру.
• Используйте uid как основной ключ для объединения, так как имя пользователя может быть изменено или удалено.
• Храните activedays как приблизительное значение с указанием даты; оно описывает количество дней с момента последней активности, а не то, находится ли человек в сети прямо сейчас.
• Обновляйте данные обогащения по графику, соответствующему вашему рабочему процессу, а не считайте один запуск окончательным.

Обогащение списка, а не поиск человека

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

Ответственные команды устанавливают несколько внутренних правил перед запуском обогащения:

• Обогащайте только те номера, которые были собраны для целей, предусматривающих контакт или поддержку через Telegram.
• Ограничьте количество хранимых столбцов тем, что действительно используется в рабочем процессе. Руководство ICO Великобритании по минимизации данных требует, чтобы персональные данные были адекватными, релевантными и ограниченными тем, что необходимо.
• Исправляйте или удаляйте устаревшие значения в соответствии с принципом точности ICO.
• Уважайте пользователей, которые решили не устанавливать имя пользователя; пустое поле — это их выбор, а не пробел, который нужно заполнять другими способами.

Эти правила являются примерами внутренней политики, а не юридической консультацией для конкретной юрисдикции.

Часто задаваемые вопросы

Почему столбец с именем пользователя пуст для некоторых номеров, у которых есть учетная запись Telegram?

Имена пользователей в Telegram необязательны. Если у учетной записи нет публичного имени, tg_active_batch по-прежнему сообщает статус регистрации и другие доступные данные, но столбец имени пользователя остается пустым.

Может ли проверка одного номера вернуть Telegram-имя пользователя?

Нет. Проверка регистрации в Telegram для одного номера возвращает только статус регистрации. Имена пользователей, uid и activedays предоставляются пакетной службой tg_active_batch.

Как команды могут использовать уже имеющиеся у них имена пользователей для обогащения записей?

Если исходный список содержит имена пользователей, а не номера телефонов, отдельная служба tg_username_batch проверяет, принадлежат ли эти имена существующим учетным записям, а tg_username_profile_batch добавляет uid, activedays и URL аватара. Задачи по именам пользователей не требуют указания страны и принимают идентификаторы как с символом @, так и без него.

Должна ли команда использовать в качестве ключа CRM-записей Telegram-имя пользователя или uid?

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

Узнать больше

Выберите информацию о продукте, которая соответствует следующему шагу в вашем рабочем процессе.

• Просмотреть документацию по продукту →
• Связаться с командой →