WhatsApp Lookup API: руководство по проверке регистрации в режиме реального времени

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

WA Lookup API предоставляет возможности синхронной проверки в режиме реального времени, позволяя подтвердить, зарегистрирован ли номер телефона в WhatsApp в момент запроса. Отправляя запросы к специализированным REST эндпоинтам, команды получают данные о наличии аккаунта непосредственно в теле HTTP-ответа. Эта архитектура поддерживает как проверку отдельных номеров, так и синхронные пакетные запросы, помогая организациям очищать очереди рассылки, защищать рабочие процессы доставки и избегать отправки сообщений на неактивные номера.

Понимание сигналов регистрации в WhatsApp

Проверка регистрации определяет, существует ли аккаунт, привязанный к конкретному идентификатору, на момент выполнения запроса. Этот сигнал о присутствии на платформе предоставляет технический контекст доступности перед началом коммуникации.

Номера телефонов должны соответствовать международному формату общественной электросвязи, описанному в ITU-T Recommendation E.164, который требует наличия кода страны и ограничивает длину номера 15 цифрами. Приведение номеров к структуре E.164 стандартизирует входные данные для различных международных систем.

С операционной точки зрения данные о регистрации помогают в маршрутизации аудитории, а не устанавливают личность, право собственности на линию или согласие получателя. Организации, проводящие коммерческие рассылки, должны вести отдельные записи о согласии (opt-in) для соблюдения WhatsApp Business Messaging Policy. Согласование проверок присутствия аккаунта с требованиями минимизации данных согласно GDPR Article 5 (Regulation (EU) 2016/679) гарантирует, что системы обрабатывают только те технические индикаторы доступности, которые необходимы для рабочих процессов доставки.

Синхронные рабочие процессы проверки в реальном времени

WhatsApp Lookup API предоставляет синхронные эндпоинты, разработанные для принятия решений в режиме реального времени. Поскольку эти эндпоинты работают синхронно, инициирующий HTTP-запрос получает атрибуты проверки непосредственно в полезной нагрузке ответа без необходимости вторичных циклов опроса.

Проверка отдельного номера

Для транзакционных событий, таких как формы регистрации или обработка отдельных лидов, интеграция вызывает POST /api/v1/check с использованием заголовка аутентификации X-API-Key. Запрос отправляет строку номера телефона в формате E.164 и выбирает целевой тип сервиса.

Синхронная пакетная проверка

Когда рабочие процессы требуют одновременной валидации небольших очередей, эндпоинт POST /api/v1/batch-check принимает до 100 номеров телефонов за один вызов. Эндпоинт оценивает весь пакет синхронно и возвращает единый набор результатов в инициирующем ответе.

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

Сравнение типов проверок сервиса в реальном времени

Lookup API структурирует запросы на регистрацию в три специфических типа сервиса для поддержки различных требований к риску и обогащению данных.

Выбор ws предоставляет основной индикатор доступности. Для рабочих процессов, требующих обогащения профиля, ws_avatar добавляет данные о наличии аватара и ссылку на размещенное изображение, если оно доступно. Опция ws_business определяет, работает ли зарегистрированный номер на платформе WhatsApp Business, что позволяет сегментировать потребительские и коммерческие аккаунты.

Интерпретация кодов статуса и расхода баланса

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

Завершенная проверка формирует код успешного ответа с данными, где поле data.registered установлено в значение true или false. Как записи с подтвержденным наличием аккаунта, так и записи с подтвержденным отсутствием представляют собой завершенные проверки и соответствующим образом расходуют баланс.

Неопределенное состояние или прерывание работы вышестоящего сервиса возвращает ненулевой бизнес-код, а не значение registered=false. Нижестоящие системы должны изолировать ненулевые коды для логики повторных попыток, вместо того чтобы рассматривать их как нераспределенные номера телефонов. Зарегистрированные пользователи могут связаться с поддержкой, чтобы получить 100 бесплатных проверок для тестирования обработки ответов в средах разработки.

Асинхронные пакетные задачи для обработки списков

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

Файлы для пакетных задач должны быть представлены в формате TXT или CSV, содержащем по одному номеру телефона в строке. Файл должен быть сфокусирован на одном целевом направлении (стране), так как списки, содержащие 10% и более номеров вне целевой страны, вызывают отклонение при предварительной проверке. Применяются лимиты на файлы для каждого продукта; командам следует ознакомиться с официальной документацией по текущим правилам размера файлов.

Региональное покрытие также различается в зависимости от рабочих процессов. Синхронные проверки отдельных номеров в реальном времени поддерживают номера из материкового Китая (+86), Гонконга (+852) и Макао (+853) при небольших объемах, тогда как асинхронные пакетные задачи исключают эти направления. Покрытие Тайваня остается неподтвержденным для всех режимов обработки.

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

Чем синхронные проверки в реальном времени отличаются от асинхронных пакетных задач?

Проверки в реальном времени отправляют номера непосредственно в POST /api/v1/check или POST /api/v1/batch-check и доставляют результаты немедленно в том же HTTP-ответе. Асинхронные пакетные задачи принимают отформатированные файлы через POST /api/v1/bulk-tasks, сначала возвращают ID задачи, а по завершении обработки генерируют CSV-файл с результатами, доступный для скачивания.

Как API обрабатывает списания за неопределенные проверки?

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

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

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

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