Интеграция WA Lookup API для обогащения профилей WhatsApp

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

WA Lookup API предоставляет синхронный REST-интерфейс, который помогает разработчикам автоматизировать обогащение профилей WhatsApp. Отправив POST-запрос на эндпоинт /api/v1/check с указанием типа сервиса — ws, ws_avatar или ws_business — и номером телефона в формате E.164, вы сразу получаете сигналы наличия аккаунта прямо в HTTP-ответе. Эти сигналы включают статус регистрации, наличие аватара, URL аватара и признаки бизнес-аккаунта; их можно использовать как входные данные для маршрутизации в CRM, сегментации аудитории и внутренних процессов поддержки решений.

Введение в WA Lookup API

При встраивании каналов коммуникации в бизнес-процессы техническим командам нужны точные сигналы наличия аккаунта, чтобы на их основе строить логику маршрутизации и сегментации. WA Lookup выполняет синхронные одиночные и небольшие пакетные проверки регистрации в WhatsApp, наличия аватара и статуса аккаунта Business. Одиночный эндпоинт проверяет один идентификатор, а синхронный множественный эндпоинт принимает до 100 идентификаторов; оба возвращают данные в том же HTTP-ответе. Такая синхронная архитектура позволяет принимать решения сразу, без асинхронных вебхуков, инфраструктуры опроса или очередей пакетной обработки. Крайне важно понимать границы этого сигнала наличия аккаунта. Результат registered отражает поля статуса WhatsApp, доступные в момент проверки. Он не сообщает о текущем присутствии в сети, истории сообщений, согласии пользователя или о том, можно ли сейчас связаться с этим номером. Вместо этого он служит частью более широкого процесса, помогая командам проверять записи и расставлять приоритеты в работе с контактами с учетом присутствия на платформе.

Типы сервисов

WA Lookup API объединяет свои возможности в одном синхронном эндпоинте. Разработчики определяют, какие именно сигналы профиля запрашиваются — и какая стоимость списывается с баланса, — изменяя параметр service_type в теле запроса. API поддерживает три типа сервиса:

• WhatsApp Checker (ws): базовый тип сервиса. Его задача — только подтвердить, зарегистрирован ли указанный номер телефона в WhatsApp. Он дает базовый сигнал регистрации на платформе.
• WhatsApp Avatar Checker (ws_avatar): этот тип сервиса расширяет базовую проверку за счет обогащения профиля. Помимо проверки регистрации в WhatsApp, он проверяет наличие аватара и возвращает поле avatar_url. Если URL недоступен, поле остается пустым.
• WhatsApp Business Checker (ws_business): этот тип сервиса ориентирован на B2B-процессы. Он проверяет стандартную регистрацию в WhatsApp и дополнительно определяет, использует ли аккаунт WhatsApp Business, предоставляя отдельный сигнал бизнес-профиля.

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

Техническая реализация

Интеграция WA Lookup API требует строгого соблюдения контракта JSON-запроса и правил форматирования. Все взаимодействие происходит через эндпоинт POST /api/v1/check. Для аутентификации и корректного оформления запроса разработчики должны передавать определенные заголовки: заголовок X-API-Key с действующим ключом API и заголовок Content-Type: application/json. JSON-тело запроса должно содержать ровно два поля:

1. service_type: строковое значение "ws", "ws_avatar" или "ws_business".
2. identifier: проверяемый номер телефона, строго в формате E.164.

Формат E.164 — это международный план нумерации телефонной связи, обеспечивающий глобальную однозначность номеров. Номер в формате E.164 должен начинаться со знака плюс (+), за которым сразу следуют код страны и абонентский номер, без пробелов, дефисов и скобок (например, +17253100591). Если не использовать формат E.164, проверка завершится неудачно. Поскольку API полностью синхронный, HTTP-соединение остается открытым на время проверки, а результаты передаются в немедленном HTTP-ответе.

Интерпретация ответов API

WA Lookup API возвращает предсказуемый набор полей в каждом ответе на проверку, а дополнительные поля добавляются в зависимости от выбранного service_type. Для завершенной проверки WhatsApp возвращаемый объект data содержит service_type, identifier и registered. ws_avatar дополнительно включает avatar и avatar_url, а ws_business — business; внутренние поля записи, транзакции, статуса и биллинга не возвращаются. Если service_type равен ws, результат содержит только поле registered вместе с возвращёнными без изменений service_type и identifier. Если service_type равен ws_avatar, схема ответа расширяется полем avatar (логическое значение, показывающее, установлен ли аватар) и полем avatar_url. Если URL недоступен, avatar_url содержит пустую строку. Если service_type равен ws_business, в схему ответа добавляется поле business — логическое значение, показывающее, связан ли зарегистрированный номер с аккаунтом WhatsApp Business.

Панель и управление использованием

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

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

Является ли WA Lookup API синхронным?

Да. Эндпоинты проверки в реальном времени синхронны: результаты возвращаются в том же HTTP-ответе, что и исходный запрос. Эндпоинт для одного номера проверяет один идентификатор, а синхронный множественный эндпоинт принимает до 100 идентификаторов без заданий, обратных вызовов и опроса. Более крупные списки обрабатываются отдельным асинхронным продуктом массовой проверки: вы загружаете файл и скачиваете результат позже.

Чем отличаются типы сервиса ws и ws_avatar?

Тип сервиса ws возвращает только базовый сигнал регистрации в WhatsApp. Тип сервиса ws_avatar возвращает сигнал регистрации и дополнительно проверяет наличие аватара, возвращая строку avatar_url, которая остается пустой, если URL недоступен.

В каком формате указывать номера телефонов?

Все номера телефонов, отправляемые в API, должны быть оформлены по стандарту E.164. Это означает знак плюс (+), за которым следуют код страны и абонентский номер, без пробелов и специальных символов.