WA Lookup
Номер телефона проходит через синхронный конвейер проверки регистрации и получает завершённый результат
Один запрос проводит один нормализованный номер через валидацию и возвращает один результат проверки регистрации.

Что означает «в реальном времени» для этого продукта

«В реальном времени» означает, что решение о регистрации возвращается в том же HTTP-запросе, а не через фоновую задачу, вебхук или последующий экспорт.

Вызывающая сторона отправляет один нормализованный номер телефона и ждёт ответа. Когда проверка завершается, data.registered сообщает, был ли этот номер зарегистрирован в WhatsApp на момент запроса. Результат можно использовать сразу, без опроса другого эндпоинта.

Это узкий контракт продукта. WA Lookup проверяет статус регистрации; он не устанавливает личность владельца номера, не отслеживает активность аккаунта и не является сервисом обмена сообщениями. Явно обозначенные границы облегчают корректное использование возвращаемого поля.

Возвращаемые данные Значение Рекомендуемое действие
code=0, registered=true Завершённая проверка показала, что номер зарегистрирован Используйте булево значение, возвращённое этим запросом
code=0, registered=false Завершённая проверка показала, что номер не зарегистрирован Используйте false как завершённый результат
Ненулевой бизнес-код Сервис не вернул решения о регистрации Не придумывайте булево значение; обработайте ошибку или повторите запрос согласно документации API

Чем полезны синхронные проверки

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

Типичные интеграции — внутренняя форма, проверяющая один номер, инструмент поддержки, проверяющий запись по требованию, или фоновый обработчик на бэкенде. Для небольших списков синхронный пакетный эндпоинт принимает до 100 идентификаторов в формате E.164 и возвращает завершённый пакет в ответе на исходный запрос. При этом клиентам всё равно следует самостоятельно контролировать степень параллелизма.

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

Путь запроса шаг за шагом

  1. Нормализуйте номер телефона — Преобразуйте достоверно известный код страны и национальный номер в формат E.164. Не угадывайте отсутствующий контекст страны.
  2. Отправьте одну проверку — Вызовите аутентифицированный эндпоинт проверки с нормализованным номером и service_type=ws.
  3. Прочитайте завершённый результат — Используйте data.registered при code=0; оставляйте значение пустым, если API вернул ненулевой бизнес-код.
  4. Сохраните время наблюдения — Регистрация — это результат на определённый момент, поэтому сохраняйте время проверки.
  5. Обрабатывайте отсутствие результата отдельно — Некорректный запрос или временный сбой требуют исправления или повторной попытки, а не значения регистрации false.

Моделируйте результат без потери смысла

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

Поле Назначение
source_phone Сохраняет значение, переданное исходной системой
e164_phone Хранит канонический номер, отправленный на проверку
outcome Классификация вашего приложения: завершено, можно повторить или ошибка запроса
registered Хранит true или false только для завершённой проверки
checked_at Фиксирует момент, когда было сделано наблюдение
service_type Фиксирует, какой контракт продукта дал результат

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

Практическое правило интеграции

Ветвитесь по data.registered только тогда, когда во внешнем ответе code=0.

Это единственное правило предотвращает самую распространённую ошибку интерпретации: когда тайм-аут, отклонённый запрос или некорректный номер воспринимаются так, будто WhatsApp сообщил, что номер не зарегистрирован. Если решение должно быть актуальным позднее, выполните новую синхронную проверку и сохраните её как новое наблюдение, а не меняйте незаметно старую метку времени.

Источники