Анализ аватаров Telegram для списков телефонных номеров

Пошаговое руководство по пакетному продукту для номеров телефонов Telegram, объясняющее, почему проверка в реальном времени отсутствует и как подготовить, запустить и прочитать задачу.

Чтобы проанализировать аватар Telegram по номеру телефона, отправьте подготовленный список в пакетный продукт AvatarLookup для номеров телефонов Telegram. Анализ аватаров Telegram доступен только в виде асинхронной пакетной задачи, поэтому проверка одного номера в реальном времени невозможна. Вы загружаете файл TXT или CSV с одним номером (включая код страны) на каждой строке, отслеживаете выполнение задачи до её завершения и скачиваете один CSV-файл. Результаты описывают только публичные аватары и не показывают, кто является владельцем аккаунта.

Почему анализ аватаров Telegram доступен только в пакетном режиме

Поиск аватара Telegram по номеру телефона часто ошибочно воспринимается как контактный поиск: ввел номер — увидел лицо. Telegram работает иначе. Он рассматривает номер телефона и фотографию профиля как отдельные настройки конфиденциальности. В разделе «Конфиденциальность» каждый пользователь выбирает, кто может видеть его номер и кто может видеть его фото, используя такие параметры, как «Все», «Мои контакты» или «Никто», что описано в официальном FAQ Telegram. Таким образом, фотография видна только тогда, когда её владелец разрешил это.

В каталоге AvatarLookup анализ номеров телефонов Telegram представлен одним продуктом: асинхронной пакетной задачей. Проверка Telegram в реальном времени (как для одного, так и для нескольких номеров) отсутствует, поэтому командам не следует планировать интеграцию, ожидающую мгновенного ответа для одного номера. Синхронные проверки в реальном времени задокументированы только для WhatsApp и поддерживаемых адресов электронной почты Gmail, Yandex и Mail.ru.

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

Подготовка файла с номерами телефонов и кодами стран

От подготовки файла зависит успех задачи, поэтому уделите этому время. Продукт для номеров телефонов Telegram ожидает файл TXT или CSV с одним идентификатором на каждой строке. Форматы XLSX и другие форматы электронных таблиц не принимаются, поэтому экспортируйте таблицу в CSV или вставьте номера в текстовый файл.

Используйте этот контрольный список:

1. Записывайте каждый номер цифрами, включая код страны, без знака «плюс», пробелов, тире или скобок.
2. Выбирайте одну страну для задачи. Список должен по существу принадлежать этой стране, поэтому разделяйте международные списки на отдельные файлы для каждой страны.
3. Удалите дубликаты, пустые строки и заголовки.
4. Убедитесь, что размер списка соответствует опубликованным минимальным и максимальным значениям, указанным в документации API и на странице цен.
5. Сохраните копию исходного списка, чтобы иметь возможность сопоставить результаты с вашими записями.

При отправке через API направляйте задачу на POST /api/v1/bulk-tasks. При отправке составного запроса (multipart) поле страны должно идти перед полем файла, что легко упустить, если клиентская библиотека меняет порядок частей формы. Задача для номеров телефонов не принимает номера +86, +852 или +853, так как эти регионы доступны только через проверку одного номера в реальном времени, а эти проверки не охватывают Telegram.

Запуск задачи и загрузка CSV

Пакетная задача является асинхронной. Отправка файла возвращает задачу, которую можно отслеживать, проверяя её прогресс с помощью GET /api/v1/bulk-tasks/{id}. Сервис не устанавливает фиксированное время завершения, поэтому планируйте работу исходя из статуса, а не времени.

Соблюдайте следующие правила работы:

• Опрашивайте статус не чаще, чем раз в 30 секунд. Более частый опрос создает нагрузку и не дает преимуществ.
• Когда статус показывает успех, скачайте один CSV-файл, созданный для этой задачи.
• Ссылки на скачивание действуют 12 часов. Если срок действия ссылки истек, снова запросите ту же задачу, чтобы обновить её.
• Своевременно сохраняйте CSV в своей системе, указывая дату и имя отправленного файла.

Перед запуском большого объема протестируйте процесс на небольшом файле, близком к минимальному размеру продукта, чтобы убедиться, что форматирование, выбор страны и последующий импорт работают корректно. Исправить проблему с заголовком в маленьком файле проще, чем обнаруживать её после обработки полного списка. Следите за балансом аккаунта через GET /api/v1/balance, чтобы длительная задача не остановилась из-за нехватки средств.

Чтение CSV-файла Telegram без избыточной интерпретации

CSV-файл для номеров телефонов Telegram имеет свои собственные столбцы, и не стоит предполагать, что они совпадают с другими продуктами. Пакетные файлы для Viber, MAX, LINE, Zalo и электронной почты возвращают свои собственные поля, поэтому создайте отдельное сопоставление импорта для каждого продукта, а не одну общую схему. Перед созданием сопоставления ознакомьтесь со списком столбцов в документации API.

Правила интерпретации важнее, чем сами столбцы:

• Строка с публичной фотографией означает, что был проанализирован публичный аватар. Атрибуты внешности, если они присутствуют, являются алгоритмическими оценками, а не демографическими фактами.
• Строка без фотографии означает, что публичный аватар был недоступен. Это может отражать настройки конфиденциальности владельца и не является доказательством того, что у номера нет аккаунта в Telegram.
• Строка со статусом «Не определено» означает, что проверка не пришла к выводу. Ни один из результатов не доказывает отсутствие аккаунта.
• Завершенные строки подлежат оплате, даже если ответ отрицательный.

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

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

Существует ли проверка аватара Telegram в реальном времени для одного номера?

Нет. Анализ аватаров Telegram задокументирован только как асинхронный пакетный продукт: один для номеров телефонов и один для имен пользователей. Проверки в реальном времени (одиночные и синхронные пакетные) охватывают только WhatsApp и поддерживаемые адреса электронной почты Gmail, Yandex и Mail.ru, поэтому рабочие процессы Telegram должны быть спроектированы вокруг файла и задачи.

Какой формат файла принимает продукт для номеров телефонов Telegram?

TXT или CSV с одним идентификатором на каждой строке. Номера записываются как цифры с кодом страны без знака «плюс», для задачи выбирается одна страна. Загрузка XLSX не поддерживается, поэтому электронные таблицы следует сначала экспортировать в CSV.

Означает ли отсутствие фотографии, что у номера нет аккаунта в Telegram?

Нет. Отсутствие фотографии может отражать настройки конфиденциальности владельца или отсутствие фото. Как командам работать с такими строками? Оставляйте их как результат «Нет аватара» или «Не определено» и избегайте выводов о наличии аккаунта.

Можно ли включать номера Telegram из Гонконга или Макао?

Пакетные задачи не поддерживают номера +852, +853 или +86, которые ограничены проверкой одного номера в реальном времени, а эти проверки не охватывают Telegram. Поддержка Тайваня (+886) не подтверждена, поэтому командам следует проверить актуальную документацию перед включением таких номеров.

Дополнительная информация

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

• Посетить сайт продукта →