Варианты API для работы с телефонными номерами Telegram: Bot API, Client API или API для проверки регистрации

Сравнение для разработчиков между Telegram Bot API, Telegram client API и API для проверки регистрации при работе с телефонными номерами.

Единого API Telegram для работы с телефонными номерами не существует. Telegram Bot API получает номер только тогда, когда пользователь решает поделиться им, Telegram client API работает через реальную учетную запись пользователя и ее учетные данные, а API для проверки регистрации, такой как TG Validator, отвечает на вопрос, зарегистрирован ли предоставленный номер в Telegram. Выберите тот вариант, который соответствует вашей задаче: сбор номера от пользователя, автоматизация собственного аккаунта или проверка уже имеющихся у вас номеров.

Что разработчики подразумевают под API Telegram для телефонных номеров

Поисковые запросы «telegram phone number api» обычно связаны с одной из трех задач:

1. Сбор номера пользователя внутри бота, например, для привязки чата Telegram к учетной записи клиента.
2. Автоматизация учетной записи пользователя Telegram, например, для управления контактами или создания собственного клиента.
3. Проверка уже имеющихся у вас номеров, например, для определения того, у каких контактов из CRM есть аккаунт в Telegram, перед выбором канала связи.

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

Bot API: получение номера, которым пользователь решил поделиться

Telegram Bot API не выполняет поиск пользователей по номеру телефона. Бот получает номер только тогда, когда пользователь отправляет его:

• Кнопка в клавиатуре ответа с параметром request_contact запрашивает у пользователя разрешение поделиться своим номером телефона как контактом. В документации указано, что это работает только в личных чатах.
• Сообщение с общим контактом содержит объект Contact, в котором указан номер телефона и, при наличии, идентификатор пользователя в Telegram.

Это подходящий инструмент, если вы хотите, чтобы клиент связал свой чат Telegram с вашим сервисом посредством явного действия с его стороны. Он не позволяет проверять списки номеров, а боты не могут вызывать метод импорта контактов client API, который, согласно документации Telegram, доступен только пользователям (contacts.importContacts).

Client API: автоматизация реальной учетной записи Telegram

Telegram client API (MTProto) используется официальными и сторонними приложениями. Библиотеки, такие как TDLib, Telethon и Pyrogram, являются его обертками, и большинство скриптов для «проверки номеров» с открытым исходным кодом построены на его основе.

Прежде чем приступать к разработке, ознакомьтесь с тем, что Telegram указывает в Obtaining api_id:

• Вам потребуются api_id и api_hash с сайта my.telegram.org, созданные на основе существующей учетной записи Telegram; каждый номер телефона может быть привязан только к одному api_id.
• Сторонние клиенты должны соблюдать Условия использования API. Учетные записи, использующие неофициальные клиенты, попадают под наблюдение, а рассылка спама или чрезмерная активность через API могут привести к перманентной блокировке.
• Импорт контактов сохраняет их в той учетной записи, которая выполняет код.

Client API хорошо подходит для создания полноценного клиента Telegram или автоматизации собственного аккаунта. При проверке списков бизнес-контактов это означает, что данные компании хранятся в учетной записи одного человека, и потеря доступа к этому аккаунту остановит рабочий процесс.

API для проверки регистрации: определение наличия номера в Telegram

API для проверки регистрации создан для третьей задачи. REST API сервиса TG Validator работает без необходимости использования вашей учетной записи Telegram:

• Одиночная проверка: POST /api/v1/check с заголовком X-API-Key, содержащим ваш ключ с префиксом sk_. В теле JSON указывается тип сервиса tg и номер телефона в формате E.164.
• Небольшие пакеты: POST /api/v1/batch-check принимает до 100 номеров за один запрос.
• Поток с мгновенным ответом: оба эндпоинта возвращают результаты в ответе; нет необходимости создавать задачу и опрашивать статус.
• Конверт ответа: задокументированный формат ответа содержит бизнес-код и сообщение для каждого запроса. Завершенный результат сразу сообщает, зарегистрирован ли отправленный номер в Telegram. Если проверка не может быть выполнена, возвращается ненулевой бизнес-код без результата.
• Баланс: GET /api/v1/balance позволяет вашему сервису проверить остаток средств перед выполнением большой задачи.

Текущая документация API описывает параметры параллелизма и контроля времени ожидания для каждого пользователя, а не лимит запросов в минуту: до пяти одновременных проверок, время ожидания 60 секунд для одиночной проверки и 300 секунд для пакетной, при этом разрешена одна пакетная проверка на аккаунт в один момент времени. Уточните эти данные в документации перед настройкой воркеров, так как они могут измениться.

Для списков, значительно превышающих 100 номеров, предусмотрены отдельные асинхронные bulk-эндпоинты, которые принимают загрузку файлов TXT или CSV и возвращают один файл result.csv по завершении задачи.

Сравнение API Telegram для телефонных номеров

Многие продукты комбинируют два этих подхода: бот для общения с пользователями, которые дали согласие, и проверка регистрации для определения того, какие из существующих контактов стоит приглашать через Telegram.

Контрольный список интеграции для API проверки регистрации

• Сначала нормализуйте данные. Преобразуйте номера в формат E.164 (знак «плюс», код страны, без префикса выхода на межгород или пунктуации) перед вызовом API.
• Храните ключ на стороне сервера. Никогда не включайте его в мобильное приложение или браузерный бандл; управляйте ключами через панель управления.
• Обрабатывайте три результата. Да, нет и не определено. Храните результаты «не определено» отдельно и повторяйте попытку позже, вместо того чтобы помечать их как негативные.
• Соблюдайте параллелизм. Настраивайте пулы воркеров в соответствии с задокументированным лимитом одновременных запросов и делайте паузы при ошибках, вместо того чтобы повторять запросы в бесконечном цикле.
• Сохраняйте время проверки. Регистрация — это сигнал на момент проверки; сохраняйте дату, чтобы устаревшие результаты можно было обновить.
• Планируйте бюджет на успешные проверки. Каждая завершенная проверка оплачивается по установленному тарифу независимо от ответа, поэтому удаляйте дубликаты перед отправкой.
• AI-клиенты: MCP-эндпоинт по адресу https://tgvalidator.com/mcp предоставляет те же возможности проверки и проверки баланса для MCP-совместимых клиентов, используя аутентификацию Bearer с тем же ключом. Bulk-задачи остаются в REST API.

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

Может ли бот Telegram найти пользователя по номеру телефона?

Нет. Бот получает номер телефона только тогда, когда пользователь делится им, обычно через кнопку в клавиатуре ответа, запрашивающую контакт в личном чате. Для проверки списка номеров требуется либо учетная запись пользователя через client API, либо API для проверки регистрации.

Как команды могут проверить регистрацию в Telegram без учетной записи Telegram?

Используйте API для проверки регистрации. TG Validator принимает номер в формате E.164 через POST /api/v1/check или до 100 номеров через POST /api/v1/batch-check, используя аутентификацию через заголовок X-API-Key, и возвращает результат в том же ответе.

Существует ли лимит запросов в минуту для API TG Validator?

Лимит запросов в минуту не установлен. В документации вместо этого описаны параметры параллелизма и контроля времени ожидания для каждого пользователя, поэтому интеграции должны настраивать воркеры в соответствии с этими параметрами и следить за изменениями в документации.

Как команды могут протестировать API перед масштабным внедрением?

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

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

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

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