Программное управление именами пользователей WhatsApp Business

Техническое руководство по встраиванию синхронных проверок регистрации, аватара и бизнес-аккаунта WhatsApp в процессы CRM с помощью эндпоинта POST /api/v1/check.

Программное сопоставление идентичности в WhatsApp предполагает использование документированного эндпоинта POST /api/v1/check для проверки статуса регистрации, наличия аватара и типа бизнес-аккаунта. Передавая номера в формате E.164 с соответствующим service_type в теле запроса, команды получают синхронные JSON-данные в том же HTTP-ответе. Этот сигнал наличия аккаунта помогает обогащать записи CRM, очищать списки лидов и выстраивать автоматическую маршрутизацию, давая операционным командам контекст, необходимый для сегментации контактов без асинхронного опроса или вебхуков.

Роль программных проверок WhatsApp

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

Сигналы идентичности WhatsApp

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

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

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

Реализация синхронных API-процессов

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

• service_type: строковое значение ws, ws_avatar или ws_business.
• identifier: номер телефона в формате стандарта E.164.

Для поддержки интеграции панель платформы предоставляет полный набор административных инструментов. Команды разработки и эксплуатации могут управлять ключами API, отслеживать баланс, просматривать историю проверок и получать отчётность по продуктам. Панель также показывает недавние проверки, показатели расхода баланса и активность аккаунта, помогая отслеживать использование API и объём процессов.

Лучшие практики обеспечения целостности данных и маршрутизации

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

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

Чем проверка регистрации отличается от проверки бизнес-аккаунта?

Стандартная проверка регистрации (с типом сервиса ws) возвращает сигнал наличия аккаунта, указывающий, зарегистрирован ли переданный номер в формате E.164 в WhatsApp. Проверка бизнес-аккаунта (с типом сервиса ws_business) возвращает тот же статус регистрации, но добавляет булево поле business, указывающее, использует ли аккаунт WhatsApp Business.

Нужно ли настраивать вебхуки для проверок WhatsApp?

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

В каком формате должны быть номера телефонов для API?

Все передаваемые номера телефонов должны соответствовать стандарту международного плана нумерации E.164.

Означает ли статус «зарегистрирован», что я могу отправить пользователю сообщение?

Результат «зарегистрирован» — это исключительно сигнал наличия аккаунта на момент проверки. Он не сообщает о присутствии в сети, истории сообщений, согласии контакта или о том, сможет ли номер успешно получить сообщение.

Как оплачиваются неудачные или неопределённые проверки?

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