API для проверки WhatsApp: проверка регистрации из вашего бэкенда

Как команды бэкенд-разработки вызывают API для проверки WhatsApp, выбирают между проверкой регистрации, аватара и бизнес-аккаунта, а также обрабатывают неопределенные результаты.

API для проверки WhatsApp получает номер телефона с вашего сервера и возвращает в том же ответе информацию о том, был ли зарегистрирован аккаунт WhatsApp на этом номере на момент проверки. В WA Lookup один номер передается в POST /api/v1/check с ключом в заголовке X-API-Key и параметром service_type, который выбирает Проверка регистрации в WhatsApp, Проверка аватара WhatsApp или Проверка аккаунта WhatsApp Business, в то время как POST /api/v1/batch-check принимает до 100 номеров в одном синхронном запросе. Проверка, результат которой не удалось определить, возвращает ненулевой бизнес-код, который бэкенд-код должен интерпретировать как «повторить попытку позже», а не как ответ «Не зарегистрирован».

Что дает бэкенду API для проверки WhatsApp

Результаты поиска по этому запросу в основном представляют собой списки маркетплейсов и API-обертки, которые показывают параметр телефона и ответ «истина» или «ложь». Некоторые из них выполняют проверки через подключенную сессию WhatsApp, поэтому API перестает отвечать, когда этот телефон отключается. Лишь немногие объясняют, что означает ответ для использующего его кода или как обрабатывать случаи, когда получение ответа невозможно.

Для бэкенд-разработки полезна простая ментальная модель. API для проверки WhatsApp отвечает на один вопрос по каждому номеру: был ли зарегистрирован аккаунт WhatsApp на этом номере в момент выполнения проверки? Это сигнал о присутствии аккаунта на одной платформе. Он является хорошим входным данным для:

• выбора того, стоит ли пробовать WhatsApp для контакта перед использованием другого канала;
• очистки поля телефона в CRM или базе данных лидов;
• добавления контекста в очередь на проверку регистрации или онбординга.

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

Как вызвать API для проверки WhatsApp для одного номера

Вызов для одного номера — это один HTTPS-запрос с одним ответом. Не нужно создавать задачу, нечего опрашивать и не нужно предоставлять URL обратного вызова.

1. Нормализация до E.164. Отправляйте номер с символом «плюс», кодом страны и национальным номером в соответствии с ITU-T Recommendation E.164. Удалите пробелы, скобки и национальные префиксы. Немецкий мобильный номер, записанный локально как 0151 2345 6789, превращается в +4915123456789. Библиотека libphonenumber от Google анализирует исходные данные с учетом региона по умолчанию и является более надежной, чем написанные вручную правила для строк.
2. Выберите тип проверки. Установите service_type в значение ws, ws_avatar или ws_business в зависимости от решения, которое будет принято на основе результата.
3. Аутентификация с сервера. Отправляйте ключ в заголовке X-API-Key. Загружайте его из защищенного хранилища или конфигурации среды и никогда не размещайте в коде браузера, пакете мобильного приложения или публичном репозитории.
4. Отправьте POST /api/v1/check. Результат для этого номера придет в ответе на тот же запрос.
5. Ветвление по результату. Завершенный результат содержит ответ для выбранной проверки. Ненулевой бизнес-код означает, что проверку в данный момент выполнить не удалось.

Формируйте тело запроса и парсинг ответа согласно актуальной документации WA Lookup API. Полезные нагрузки из примеров других провайдеров отличаются, и их копирование является частой причиной ошибок интеграции.

Выбор типа проверки: ws, ws_avatar или ws_business

Значение service_type определяет, какой сигнал будет получен. Выбирайте наиболее узкую проверку, которая отвечает на вопрос вашего кода, так как каждая завершенная проверка оплачивается независимо от того, зарегистрирован номер или нет.

ws

Проверка регистрации. Она сообщает бэкенду, был ли у отправленного номера зарегистрированный аккаунт WhatsApp на момент проверки. Это стандартный выбор для принятия решений по каналам связи, очистки списков и проверки регистрации.

ws_avatar

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

ws_business

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

Проверка до 100 номеров с помощью эндпоинта batch-check

Когда у бэкенда уже есть группа номеров, например, при ночном импорте или отправке формы с несколькими контактами, POST /api/v1/batch-check отправляет до 100 номеров в одном синхронном запросе. Весь пакет возвращается в ответе на этот запрос, либо запрос целиком завершается ошибкой.

Такое поведение определяет клиентский код:

• Разбивайте большие списки. Разделяйте входные данные на группы по 100 или менее номеров и отправляйте их один за другим или с небольшим контролируемым количеством запросов в процессе выполнения.
• Рассматривайте неудачный запрос как единое целое. Если сам пакетный запрос не удался, повторите эту группу; не помечайте входящие в нее номера никаким результатом.
• Все равно читайте результаты по каждому номеру. Внутри успешного пакета каждый номер имеет свой завершенный или неопределенный результат, поэтому логика ветвления из потока для одного номера применяется к каждой записи.
• Сначала удалите дубликаты. Нормализация перед разбивкой на группы часто выявляет дубликаты, записанные в разных локальных форматах; проверка каждого номера один раз делает расходы предсказуемыми.

Эндпоинт для пакетной проверки по-прежнему работает по принципу «один запрос — один ответ». Это правильный инструмент для десятков или нескольких сотен номеров, обрабатываемых кодом приложения, а не для файла с очень большим списком.

Обработка неопределенных проверок и ошибок запросов

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

Практическая схема ветвления:

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

Запуск интеграции в продакшене

Несколько рабочих привычек облегчают поддержку интеграции проверки:

• Соблюдайте документированные ограничения. Текущая документация API описывает ограничения на параллелизм и тайм-ауты для каждого пользователя. Подстраивайте количество запросов в процессе выполнения под эти ограничения и перечитывайте документацию при масштабировании, вместо того чтобы предполагать фиксированный лимит в минуту.
• Следите за балансом аккаунта. Один баланс аккаунта покрывает дашборд, REST API и MCP-сервер, поэтому большая задача API и ручные проверки в дашборде расходуют один и тот же пул. Проверяйте баланс в дашборде перед запуском больших задач.
• Логируйте без утечек. Логируйте результаты запросов и коды ошибок, но маскируйте номера телефонов в общих логах приложения и никогда не логируйте API-ключ.
• Ротируйте ключи. Дашборд управляет API-ключами; ротируйте ключ, если он мог быть скомпрометирован, и обновите секретное хранилище за один шаг.
• Записывайте контекст. Сохраняйте, какая проверка была выполнена и когда. Результат месячной давности описывает номер на тот момент, а не сегодня.

Собственные Terms of Service WhatsApp ограничивают автоматизированный или неавторизованный доступ к его сервисам, что является одной из причин, по которой команды уходят от скриптов, управляющих личной сессией, к размещенному API с собственным ключом.

Когда файловая задача подходит лучше, чем API

Для очень большого списка лучше подходит асинхронная массовая задача: загрузите файл TXT или CSV с одним номером в строке, дождитесь обработки, затем скачайте result.csv. Массовые задачи используют POST /api/v1/bulk-tasks для отправки и GET /api/v1/bulk-tasks/{id} для отслеживания прогресса, при этом применяются ограничения для каждого продукта, как описано в документации API. Файл должен содержать номера преимущественно из одной страны, а массовые сервисы не покрывают номера материкового Китая, Гонконга или Макао. Баланс для массовых задач резервируется при отправке, а неиспользованная часть возвращается после обработки.

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

FAQ

Как команды могут протестировать API для проверки WhatsApp перед внедрением в продакшен?

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

Что должен делать бэкенд, когда номер возвращается как неопределенный?

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

Работает ли эндпоинт batch-check иначе, чем загрузка файла?

Да. Эндпоинт batch-check возвращает до 100 результатов в ответе на тот же запрос. Загрузка файла создает асинхронную массовую задачу, которая обрабатывается в фоновом режиме, после чего скачивается result.csv.

Какой тип проверки должна использовать CRM-интеграция по умолчанию?

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

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

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

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