Проверка номеров Telegram — массовая верификация через платформу или API

Сервис проверки номеров Telegram обрабатывает номера телефонов в формате E.164 и возвращает сигнал Telegram для каждой строки. Используйте базовую задачу tg, если вам нужен только статус регистрации. Проверки активности и публичного профиля — это отдельные продукты с другими полями и стоимостью; не рассчитывайте, что базовый результат их содержит.

Запустить пакет без кода можно в интерфейсе продукта Telegram, а регулярные списки — автоматизировать через REST API, описанный ниже.

Сначала выберите глубину результата Telegram

Проверка	Тип задачи API	Основной результат	Для чего подходит
Регистрация	`tg`	Отправленный номер и статус регистрации	Удаление незарегистрированных строк и базовая сегментация списка
Активность	`tg_active`	Регистрация, а также доступные идентификаторы, время последнего посещения, активные дни и статус участника	Внутренняя сегментация по давности активности
Публичный профиль	`tg_avatar`	Регистрация, а также доступные данные профиля, аватар, активность и атрибуты, определённые по изображению	Санкционированное обогащение профилей

Необязательные поля профиля могут быть пустыми. Возраст и пол, определённые по публичному аватару, — это вероятностные оценки, а не подтверждённые факты; их не следует использовать для принятия значимых решений о человеке. Актуальные выходные данные каждого уровня показаны на странице продукта Telegram.

Подготовьте входной файл

Создайте файл .txt или .csv, в котором каждая строка — один номер телефона в международном формате. Храните собственный стабильный ID записи в исходной системе, чтобы каждую строку экспорта можно было надёжно сопоставить с исходной записью.

+14155550100
+41798284651
+447700900123

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

Отправьте задачу проверки регистрации в Telegram

Официальная документация: Telegram Bulk CheckNumber API.

POST https://api.checknumber.ai/v1/tasks

Параметр	Описание
`file`	Один номер телефона в формате E.164 на строку
`task_type`	`tg` для базовой проверки регистрации в Telegram

curl --location 'https://api.checknumber.ai/v1/tasks' \
  --header 'X-API-Key: API-KEY' \
  --form 'file=@"./numbers.txt"' \
  --form 'task_type="tg"'

Сохраните возвращённый task_id. Не раскрывайте API-ключ в клиентском коде, логах браузера, аналитических событиях или скриншотах, которыми вы делитесь.

Опрашивайте задачу и скачивайте результаты

POST https://api.checknumber.ai/v1/gettasks

curl --location 'https://api.checknumber.ai/v1/gettasks' \
  --header 'X-API-Key: API-KEY' \
  --form 'task_id="TASK_ID"'

Опрашивайте статус с разумным интервалом, а не отправляйте запросы непрерывно. Когда задача перейдёт в статус exported, скачайте файл по result_url.

Поле задачи	Значение
`created_at`, `updated_at`	Время создания и последнего изменения статуса
`task_id`	Идентификатор для запросов статуса
`status`	Например, `pending`, `processing` или `exported`
`total`	Количество строк, отправленных в задаче
`success`, `failure`	Количество обработанных и неудачных строк
`result_url`	Ссылка для скачивания после экспорта

Для базовой задачи tg важны столбцы результата с отправленным номером Number и вердиктом регистрации telegram. Ориентируйтесь на актуальные ключи ответа из документации, а не жёстко прописывайте поля из старого экспорта.

Обрабатывайте ошибки, не портя список

Ответ	Тарификация согласно API	Поведение приложения
`200`	Успешный запрос, оплачивается	Сохраните ID задачи или возвращённый статус
`400`	Не оплачивается	Исправьте параметры или формат файла перед повторной попыткой
`500`	Не оплачивается	Повторите позже с экспоненциальной задержкой

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

Что регистрация в Telegram не доказывает

Совпадение по регистрации не доказывает, что аккаунт недавно был активен, принадлежит ожидаемому человеку, что владелец согласен на контакт или ответит. Точно так же сигнал о последнем посещении или публичном профиле может отсутствовать из-за условий доступности и настроек приватности.

Используйте минимальную глубину результата, которая нужна вашему процессу, документируйте цели обработки данных и соблюдайте местные требования к приватности и коммуникациям. CheckNumber.AI не нужно отправлять сообщения на проверяемый номер, чтобы получить описанный результат регистрации.

Чек-лист внедрения

Приведите номера к формату E.164 и сохраните ID исходной записи.
Выбирайте tg, tg_active или tg_avatar исходя из нужных полей, а не из максимально доступного набора.
Отправьте одну задачу для конкретной платформы и сохраните её task_id.
Опрашивайте статус с увеличивающейся задержкой, пока задача не достигнет финального состояния.
Скачайте результат без промедления и отделите подтверждённые результаты от ошибок.
Перед запуском в продакшене изучите официальную документацию API и актуальные цены.

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

Сколько времени занимает задача на миллион номеров?

Время обработки зависит от нагрузки на серверы и лимитов платформы. Не стройте интеграцию в расчёте на гарантированное время выполнения — вместо этого отслеживайте статус задачи.

Отправляет ли проверка сообщение в Telegram?

Нет. Проверка регистрации не отправляет сообщений и уведомлений на проверяемый номер.

Может ли одна задача проверить Telegram и другие платформы?

Нет. Каждая задача относится к одной платформе. Если процессу нужны результаты по нескольким платформам, отправляйте отдельные задачи.

Что будет, если доступных кредитов недостаточно?

Кредиты списываются за успешно обработанные строки. Проверяйте возвращённые статусы задачи и строк, а не предполагайте, что каждая отправленная строка обработана.

Проверка номеров Telegram — массовая верификация через платформу или API | CheckNumber.AI