Как спланировать процесс массовой проверки телефонов через API

Техническое руководство по планированию процесса массовой проверки телефонов через API с использованием синхронных пакетных эндпоинтов, формата E.164 и сигналов наличия аккаунта WhatsApp.

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

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

Проектирование автоматизированного конвейера проверки начинается с понимания того, как данные перемещаются между вашими внутренними сервисами и эндпоинтом проверки. Многие корпоративные системы рассчитывают на асинхронную пакетную обработку с фоновыми очередями воркеров, опросом статуса или обработчиками вебхуков. WA Lookup, напротив, реализует синхронную модель «запрос — ответ» как для одиночных проверок, так и для пакетных операций. В этой модели клиентское приложение инициирует HTTP-запрос POST и получает готовые данные проверки прямо в теле ответа. Пакетный эндпоинт принимает до 100 номеров телефонов в одном запросе. Обработка выполняется на лету: возвращаются результаты по всему набору либо пакет целиком завершается ошибкой. Это избавляет от операционных затрат на отслеживание идентификаторов заданий, хранение временных состояний заданий в базе данных или поддержку инфраструктуры обработчиков вебхуков. Поскольку ответы возвращаются синхронно, инженерным командам нужно соответствующим образом настроить HTTP-клиенты своих приложений. Тайм-аут запроса должен учитывать время, необходимое для проверки до 100 идентификаторов. Вместо того чтобы вводить уровни ограничения частоты на основе произвольных поминутных квот, командам следует проектировать клиентские пулы соединений с учетом задокументированных ограничений параллельности на пользователя и политик тайм-аутов, описанных в официальной документации API.

Подготовка и нормализация номеров телефонов

Надежный конвейер проверки требует строгой гигиены данных на стороне клиента еще до того, как записи попадут на сетевой уровень. API проверки требует, чтобы каждый отправляемый номер телефона соответствовал международному стандарту E.164. Отправка неотформатированных, записанных в местном формате или некорректных номеров приводит к ошибкам валидации или неопределенным результатам. Форматирование E.164 приводит телефонные номера к единой строке, содержащей ведущий знак плюс, код страны и национальный абонентский номер без пробелов, дефисов, скобок и префиксов вроде нуля междугородней связи. Клиентские конвейеры должны выполнять нормализацию как автоматический этап предварительной обработки:

1. Удалите нецифровые символы, такие как знаки препинания, пробелы и символы форматирования.
2. Определите нужный код страны по метаданным о стране или полям пользовательского ввода.
3. Удалите местные префиксы, например ведущие нули, которые обычно используются при внутреннем наборе.
4. Добавьте в начало международный код страны и ведущий знак плюс.
5. Проверьте длину строки по стандартным спецификациям страны перед формированием пакетов.

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

Выбор подходящего типа проверки

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

Правильный выбор типа проверки помогает системам минимизировать затраты на обработку данных. Для фильтрации больших объемов, когда командам нужно знать лишь, зарегистрирован ли идентификатор в WhatsApp, стандартная проверка ws дает эффективный индикатор доступности. Для CRM-процессов, где приоритетом является качество лидов или коммерческая категоризация, ws_business предоставляет ценный контекст для маршрутизации, определяя, работает ли аккаунт как официальный субъект WhatsApp Business.

Обработка ответов API и ошибок

Надежная интеграция требует детерминированного разбора ответов и устойчивой обработки ошибок. Завершенные запросы возвращают стандартную JSON-обертку из полей code, msg и data. Для завершенных проверок объект data содержит service_type, identifier и логическое значение registered. При разборе объектов вывода системы должны точно обрабатывать представления состояний:

• Успешные определения: завершенная проверка возвращает registered: true или registered: false. При использовании ws_avatar ответ дополнительно включает логическое значение avatar и avatar_url (может быть пустой строкой). При использовании ws_business он включает логическое значение business.
• Неопределенные результаты: если идентификатор невозможно однозначно определить в момент проверки, API возвращает ненулевой бизнес-код, а не объект готового результата с null-значениями. Клиентским приложениям следует проверять поле верхнего уровня code, прежде чем разбирать свойства data.
• Биллинг и возвраты: оплата взимается за каждую проверку. Если проверка завершается неудачей или неопределенным статусом, платформа автоматически возвращает соответствующую сумму на баланс аккаунта. Последующие сервисы должны опираться исключительно на задокументированные публичные поля ответа.

Превращение сигналов наличия аккаунта в бизнес-логику

Заключительный этап процесса массовой проверки — передача проверенных записей во внутреннюю маршрутизацию, CRM-системы или системы рассылки сообщений. Чтобы сохранить целостность данных, командам нужно правильно понимать, что именно означает сигнал регистрации на платформе. Он подтверждает, что идентификатор зарегистрирован на платформе. Организациям следует использовать результаты регистрации как входные данные для поддержки решений наряду с существующими операционными данными. Например, маркетинговые платформы и платформы поддержки могут использовать сигналы доступности, чтобы направлять сообщения в WhatsApp для зарегистрированных номеров, а незарегистрированные контакты — в альтернативные каналы связи, такие как SMS или электронная почта. Использование этих проверенных сигналов помогает командам оптимизировать операционные ресурсы, сокращать количество неудачных попыток отправки сообщений и поддерживать порядок в базах контактов.

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

Поддерживает ли API массовой проверки асинхронные очереди или вебхуки?

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

Что происходит, если идентификатор в пакете не удается обработать?

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

Можно ли использовать одни и те же учетные данные для одиночных и пакетных проверок?

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

Подробнее

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

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