API для фото профиля WhatsApp: анализ аватаров в реальном времени по номеру телефона

Руководство для разработчиков по API для фото профиля WhatsApp: что возвращают инструменты, предоставляющие только URL, чем отличаются запросы к AvatarLookup в реальном времени от синхронных пакетных запросов, а также как сохранять результаты и выполнять повторные попытки.

API для фото профиля WhatsApp принимает номер телефона и возвращает информацию об общедоступном фото профиля, привязанном к этому номеру. Многие инструменты ограничиваются временным URL-адресом изображения, который вам приходится загружать и интерпретировать самостоятельно. Анализ аватаров WhatsApp от AvatarLookup возвращает структурированный результат: через одиночный запрос в реальном времени POST /api/v1/check или синхронный пакетный запрос POST /api/v1/batch-check (от 1 до 100 номеров за раз). Атрибуты внешности в результате являются алгоритмическими оценками. Анализируются только общедоступные аватары, поэтому если пользователь ограничил видимость своего фото только для сохраненных контактов, общедоступное изображение не будет показано. Результат «Не определено» следует рассматривать как повод для повторной проверки, а не как вердикт о существовании аккаунта.

Три типа API для фото профиля WhatsApp

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

Официальные бизнес-настройки предназначены для фото вашего собственного аккаунта, а не для поиска по другим номерам. Инструменты, возвращающие только URL, предоставляют ссылки, которые часто перестают работать, из-за чего командам приходится самостоятельно загружать, хранить и классифицировать изображения. Анализ аватаров исключает этап обработки изображений и возвращает данные, подходящие для записи контакта. Все три типа ограничены одним правилом: фото должно быть общедоступным.

Одиночный запрос в реальном времени через POST /api/v1/check

Используйте одиночный запрос, когда ответ по одному номеру нужен внутри интерактивного процесса, например, когда оператор поддержки открывает карточку контакта.

1. Нормализуйте номер. Преобразуйте его в международный формат с кодом страны, следуя структуре ITU-T Recommendation E.164, и удалите пробелы, тире и скобки.
2. Отправьте один аутентифицированный запрос к POST /api/v1/check, указав продукт для аватаров WhatsApp и номер. Следуйте документации API для формирования тела запроса; не пытайтесь угадать имена полей.
3. Прочитайте ответ один раз и сохраните его с датой проверки и меткой источника WhatsApp.
4. Обработайте результат: аватар найден, общедоступный аватар отсутствует или результат не определен.

Выполняйте вызов вне критических путей, ожидаемых клиентом. Если проверка идет медленно или результат не определен, запись все равно должна быть сохранена с пустыми полями аватара и флагом необходимости повторной проверки. Номера материкового Китая, Гонконга и Макао поддерживаются только через одиночные запросы в реальном времени, поэтому направляйте их сюда, а не в пакетные файлы.

Синхронный пакетный запрос через POST /api/v1/batch-check

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

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

• Не смешивайте продукты. Отправляйте номера WhatsApp в одном запросе, а поддерживаемые адреса Gmail, Yandex или Mail.ru — в другом.
• Опирайтесь на порядок, но проверяйте. Результаты следуют в порядке ввода; тем не менее, сопоставляйте каждый результат с соответствующим номером перед записью в базу данных.
• Разбивайте длинные списки. Разделите список из 350 номеров на четыре запроса по 100 штук.
• Используйте пакетные задачи для больших файлов. Если список значительно больше, асинхронный пакетный продукт WhatsApp принимает файл TXT или CSV и возвращает один CSV-файл с результатами.

Нетехнические команды могут использовать панель управления, которая принимает до 500 идентификаторов и обрабатывает их по одному. В любом случае, только WhatsApp и поддерживаемые почтовые домены имеют проверку в реальном времени и пакетную проверку; Telegram, Viber, MAX, LINE и Zalo доступны только через пакетные продукты.

Обработка результатов «Не определено» и «Нет аватара»

Большинство ошибок интеграции возникает из-за сведения разных исходов к одному пустому значению. Разделяйте их:

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

Записывайте каждое состояние в свое значение, например, «общедоступный», «нет» или «повторить», и регистрируйте причину для повторных попыток. Четкая модель состояний также делает отчетность достоверной: счетчик «нет аватара» на панели управления никогда не должен включать элементы, которые были просто неопределенными.

Хранение результатов в виде оценок

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

Простая модель хранения:

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

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

Как команды могут получить сам файл изображения вместо полей анализа?

Анализ аватаров разработан для возврата структурированных результатов об общедоступном аватаре, а не для загрузки изображений. Если рабочий процесс действительно требует отображения изображений, оцените, необходимо ли это для поставленной цели и как файлы будут храниться и удаляться. Многим процессам работы с контактными данными достаточно знать, существует ли общедоступный аватар и какого он типа, что анализ уже предоставляет.

Как разработчикам выполнять повторные попытки для неопределенных проверок WhatsApp?

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

Как команды могут проверить изображение, которое у них уже есть, а не номер телефона?

Используйте анализ профиля по изображению. Он принимает файлы JPEG, PNG, WebP или GIF и вызывается через задокументированную конечную точку профиля изображения с помощью multipart-загрузки файла. Он описывает само изображение, возвращая тип изображения и атрибуты внешности в виде алгоритмических оценок, без участия номера телефона или аккаунта. Это подходит для изображений, которые клиент загрузил напрямую, например, фото профиля, отправленное через форму.

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

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

• Посетить сайт продукта →