Как подготовить список CSV или TXT для проверки номеров WhatsApp в реальном времени

Практическое руководство по подготовке списка номеров телефонов в CSV или TXT к проверке WhatsApp в реальном времени: форматирование E.164, выбор типа сервиса и получение сигналов наличия аккаунта через синхронные одиночный и множественный эндпоинты.

WA Lookup проверяет наличие аккаунта WhatsApp в реальном времени: отправьте один номер на синхронный эндпоинт проверки или до 100 номеров на синхронный множественный эндпоинт POST /api/v1/batch-check, и готовые результаты вернутся в ответе на исходный HTTP-запрос — ждать выполнения задания не нужно. Чтобы прогнать через него список CSV или TXT, приведите каждый идентификатор строго к международному стандарту нумерации E.164, удалите нецифровые символы и местные префиксы и выберите тип сервиса, нужный вашему процессу: ws для базового статуса регистрации, ws_avatar для дополнительной проверки наличия аватара или ws_business для выявления аккаунтов WhatsApp Business. Целый файл, намного превышающий один запрос в реальном времени, также можно загрузить как асинхронное задание массовой проверки (загрузка, ожидание, скачивание).

Сигналы проверки WhatsApp

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

Базовая проверка регистрации (ws)

Тип сервиса ws подтверждает, зарегистрирован ли указанный номер телефона в WhatsApp на текущий момент. Эта проверка возвращает поле registered, дающее простой сигнал наличия аккаунта. Он помогает принимать внутренние решения о том, какие номера из вашего файла CSV или TXT связаны с аккаунтом WhatsApp на момент проверки.

Проверка с обогащением аватаром (ws_avatar)

Тип сервиса ws_avatar включает базовую проверку регистрации и добавляет обогащение профиля. Помимо статуса registered, эта проверка возвращает логическое значение avatar, показывающее наличие аватара, и строку avatar_url. Если URL недоступен, поле остается пустым. Этот дополнительный контекст может служить одним из входных параметров наряду с другими проверками при анализе профилей пользователей.

Проверка бизнес-аккаунта (ws_business)

Тип сервиса ws_business проверяет регистрацию в WhatsApp и определяет, использует ли аккаунт WhatsApp Business. Он возвращает логическое значение business. Этот сигнал помогает командам сегментировать списки, отличая обычные аккаунты от бизнес-профилей, и точнее настраивать маршрутизацию в процессах.

Подготовка файла данных

Самое важное требование при проверке списка CSV или TXT в реальном времени — правильное форматирование данных. WA Lookup требует, чтобы все номера передавались в формате E.164. E.164 — это международный план нумерации телефонной связи, который присваивает каждому устройству глобально уникальный идентификатор. Чтобы подготовить файл CSV или TXT:

1. Укажите код страны: каждый номер должен начинаться с соответствующего международного кода страны.
2. Удалите символы форматирования: уберите из списка пробелы, дефисы, скобки и любые другие нецифровые символы.
3. Уберите ведущие нули: удалите местные префиксы междугородней связи (часто это ведущий ноль), которые не входят в международный код набора.

Например, номер из США должен быть записан как непрерывная последовательность цифр, начинающаяся с кода страны (например, 1). Если весь список соответствует стандарту E.164, это помогает избежать ошибок форматирования при синхронной проверке. Чистый стандартизированный входной файл необходим для получения точных сигналов наличия аккаунта по каждому отправленному номеру.

Отправка списка на проверку

Когда список CSV или TXT правильно отформатирован, идентификаторы можно отправить на платформу WA Lookup. Основной путь синхронный: результаты возвращаются в том же HTTP-ответе, что и запрос, а не доставляются позже. Технические команды, интегрирующие сервис, используют POST /api/v1/check для одного идентификатора или синхронный множественный эндпоинт POST /api/v1/batch-check для до 100 идентификаторов. Оба запроса требуют заголовка X-API-Key и заголовка Content-Type: application/json. Тело одиночной проверки содержит service_type и identifier; тело множественного запроса — service_type и identifiers. Соблюдайте рекомендации по параллельности из документации API. Целый файл CSV или TXT, намного превышающий один запрос в реальном времени, также можно загрузить как асинхронное задание массовой проверки; при отправке вы выбираете страну, к которой относятся номера, и список должен по существу состоять из номеров этой одной страны. За неудачные, прерванные по тайм-ауту и неопределенные проверки плата не удерживается. Актуальные условия биллинга приведены на странице цен.

Интерпретация результатов

Для завершенной проверки WhatsApp возвращаемый объект data содержит service_type, identifier и registered; ws_avatar дополнительно включает avatar и avatar_url, а ws_business — business. Внутренние поля записи, транзакции, статуса и биллинга не возвращаются. Результат registered отражает поля статуса WhatsApp, доступные в момент проверки. Важно понимать границы этого сигнала наличия аккаунта. Кроме того, проверка не сообщает о текущем присутствии в сети, истории сообщений или согласии на контакт. Она также не показывает, удастся ли связаться с номером и будут ли доставлены сообщения. Сигнал лишь дополняет вашу внутреннюю базу данных сведениями о регистрации на платформе и может служить одним из входных параметров наряду с другими проверками при организации CRM или маршрутизации записей.

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

В каком формате нужно передавать номера телефонов?

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

Можно ли проверить статус WhatsApp Business по списку?

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

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

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

Доставляются ли результаты проверки асинхронно?

Не на основном пути. Синхронные одиночный и множественный эндпоинты возвращают готовый результат в том же HTTP-ответе, что и запрос. Для целого большого списка в качестве дополнения доступно асинхронное задание массовой проверки (загрузка, ожидание, скачивание), но для повседневных проверок лучше всего подходят синхронные эндпоинты.