Отправка кодов верификации через WhatsApp

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

Зачем использовать WhatsApp для верификации?

Добавление дополнительного канала доставки наряду с SMS

WhatsApp позволяет клиентам получать коды через интернет, когда прием SMS ненадежен. Клиентам необходимы WhatsApp и активное подключение к интернету.

Сокращение шагов при вводе кода

Кнопки копирования кода уменьшают количество ручного ввода. Сценарии One-tap и Zero-tap позволяют сократить переключение между приложениями на поддерживаемых интегрированных приложениях для Android.

Оптимизация стоимости успешной верификации

Сравнивайте общие расходы на каналы в расчете на одну успешную верификацию по рынкам, включая тарифы на аутентификацию, применимые международные тарифы на аутентификацию, списания YCloud и резервную отправку по SMS. Meta взимает плату за доставленные сообщения; недоставленное сообщение не влечет за собой соответствующую комиссию Meta за сообщение. Другие списания зависят от вашего плана YCloud. См. разделы Цены WhatsApp и Цены Meta.

Поиск точек оттока в процессе верификации

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

Перед началом работы

Войдите в YCloud и подключите WABA и отправителя.
Подготовьте логику запроса, генерации, хранения и валидации кодов. В этом руководстве используется API сообщений WhatsApp; жизненный цикл кода контролируется вашей системой. Информацию о сервисе верификации YCloud см. в разделе Verify.
Подготовьте серверный API-ключ и обработчик webhook.
Используйте тестового получателя, который запросил код. Запрос кода не является согласием на получение последующих маркетинговых рассылок.
Настройте SMS-канал и реализуйте правила резервного переключения (fallback) в вашем бэкенде.

1. Выберите способ работы с кодом

Пользовательский опыт и интеграция	Пример
Копирование кода Скопируйте в WhatsApp, затем вставьте на своем веб-сайте или в приложении. Работает на всех платформах. Поле ввода кода и валидация на бэкенде.
В одно касание / Автозаполнение Нажмите Автозаполнение, чтобы передать код в приложение для Android. Интегрируйте Android SDK для OTP от Meta и настройте имя пакета и хеш ключа подписи приложения.
Zero-tap Ваше приложение для Android получает код без переключения в WhatsApp или нажатия кнопки. Интегрируйте Android SDK для OTP от Meta, настройте имя пакета и хеш ключа подписи приложения, а также примите условия использования Zero-tap.	Иллюстративный экран ввода кода. Для Zero-tap требуется Android.

Предусмотрите резервный вариант копирования кода на случай, если требования для Android One-tap или Zero-tap не выполнены. Информацию о подсказках клавиатуры на iOS см. в разделе FAQ ниже.

2. Создайте шаблон аутентификации

Выберите WABA, название и язык

Откройте раздел Шаблоны для нужного WABA в YCloud, выберите Добавить шаблон и укажите категорию Аутентификация. Используйте строчные буквы, цифры и символы подчеркивания для названия, например login_verification. Выберите язык ваших клиентов и зафиксируйте точное одобренное название и код языка для отправки. См. раздел Создание шаблона.

Настройка содержимого и действия с кодом

Аутентификация использует предварительно заданный текст с кодом, а также поддерживаемые уведомления о безопасности и сроке действия. Не добавляйте в текст сообщения обычный рекламный текст, URL, медиафайлы или эмодзи. Выберите Копировать код, Автозаполнение или Zero Tap. Для вариантов «Автозаполнение» и Zero Tap укажите фактическое имя пакета Android и хеш подписи, а также завершите интеграцию с приложением. Для Zero Tap также требуется принять соответствующие условия. Для конфигурации API используйте текущий формат supported_apps, а не устаревшие примеры с верхнеуровневыми параметрами package_name и signature_hash. Следуйте руководствам по интеграции аутентификации для получения подробных сведений об Android SDK и процедуре согласования.

Настройка трех независимых параметров срока действия

Параметр	Что контролирует	Пример на пять минут
Срок действия кода на бэкенде	Когда сервер отклоняет код.	Через пять минут после генерации.
Отображаемое уведомление о сроке действия	Что сообщается клиенту.	Пять минут, в соответствии с вашей фактической политикой.
Срок жизни доставки (TTL)	Время, в течение которого могут предприниматься попытки доставки.	Не дольше оставшегося срока действия кода с учётом времени между генерацией и отправкой.

Мы рекомендуем установить TTL доставки OTP (messageSendTtlSeconds) на 30–60 секунд в шаблоне аутентификации. Не превышайте оставшийся срок действия кода. YCloud поддерживает диапазон 30–900 секунд со значением по умолчанию 10 минут для новых шаблонов. Отображаемое уведомление об истечении срока действия поддерживает значения 1–90 минут и не обеспечивает принудительное истечение срока на бэкенде. TTL доставки останавливает ожидающие попытки доставки; он не отзывает уже доставленные сообщения. См. контракт API YCloud.

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

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

3. Отправка через API

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

Эндпоинт	Поведение
`POST /v2/whatsapp/messages/sendDirectly`	Синхронная отправка в WhatsApp Business API; полезно, если сценарию OTP результат отправки требуется немедленно.
`POST /v2/whatsapp/messages`	Добавление сообщения в очередь для асинхронной отправки.

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

Подготовка запроса

Выполняйте аутентификацию на стороне сервера с помощью X-API-Key.
Используйте номера в формате E.164, включая коды стран, для from и to.
Установите для type значение template и используйте одобренное имя и язык для выбранного WABA.
Передавайте один и тот же код в теле сообщения и в параметрах кнопки OTP.
Связывайте запрос на верификацию с идентификатором сообщения YCloud. Поле externalId помогает при сверке данных, но не гарантирует идемпотентность.

Пример тела запроса с кнопкой «Скопировать код». Замените плейсхолдеры; значение 123456 приведено для примера и в рабочей среде должно генерироваться вашей системой верификации:

{
  "from": "BUSINESS_PHONE_NUMBER",
  "to": "CUSTOMER_PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "APPROVED_TEMPLATE_NAME",
    "language": { "code": "APPROVED_LANGUAGE_CODE" },
    "components": [
      {
        "type": "body",
        "parameters": [{ "type": "text", "text": "123456" }]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 0,
        "parameters": [{ "type": "text", "text": "123456" }]
      }
    ]
  },
  "externalId": "VERIFICATION_REQUEST_REFERENCE"
}

Параметры отправки для кнопки OTP используют sub_type: url; не используйте обычную структуру кнопок с кодами маркетинговых купонов. См. разделы Аутентификация с копированием кода и Отправка сообщения WhatsApp. Вы также можете выбрать Ещё → Копировать как cURL у одобренного шаблона и проверить сгенерированные параметры по его конфигурации. Успешный ответ API не подтверждает доставку. Если время ожидания запроса истекло, проверьте доступные записи сообщений и колбэки перед повторной отправкой.

4. Получение обновлений о доставке

В разделе Разработчикам → Вебхуки создайте эндпоинт, укажите URL колбэка и подпишитесь на whatsapp.message.updated. Инструкции по проверке подписи, подтверждениям и повторным попыткам см. в руководстве по Webhook. Сопоставляйте каждый идентификатор сообщения с соответствующим запросом на верификацию:

Статус	Значение	Реакция сценария
`sent`	Отправлено, без подтверждения получения на устройстве клиента.	Ожидайте обновлений о доставке или ошибке.
`delivered`	Доставлено получателю.	Ожидайте успешной проверки кода.
`read`	Получен отчёт о прочтении.	Не отмечайте верификацию завершённой и не считайте отсутствие отчёта ошибкой.
`failed`	Ошибка отправки или доставки.	Проанализируйте ошибку перед исправлением конфигурации, повторной попыткой или переключением каналов.

Отмечайте верификацию завершённой только после того, как ваш бэкенд проверит код. Обрабатывайте дублирующиеся и запоздалые колбэки так, чтобы более ранний статус не перезаписывал более поздний. Используйте Журналы сообщений для ручного анализа.

5. Проектирование интерфейса и резервный канал SMS

Чётко информируйте о канале доставки

Перед отправкой предупредите, что код придёт через WhatsApp. После отправки отобразите маскированный номер получателя, сообщение об ожидании, обратный отсчёт до повторной отправки и доступные альтернативные варианты. Предоставьте клиентам возможность вернуться назад и исправить номер.

Стратегия и пользовательский опыт	Пример интерфейса
Сначала WhatsApp, резервный канал SMS Начните с WhatsApp и предложите SMS, если доставка не удалась или занимает слишком много времени.
Выбор клиента Предложите WhatsApp и SMS перед отправкой, затем покажите обратный отсчёт до повторной отправки и экран ввода кода.

Настройка резервного канала SMS

Установите TTL доставки OTP на 30–60 секунд в шаблоне аутентификации WhatsApp и согласуйте с ним таймер переключения на резервный канал SMS.

Триггер	Правило резервной отправки по SMS
Отправка через API завершилась явным сбоем	Немедленно отправьте SMS и выясните причину ошибки API. Сам по себе тайм-аут запроса не является явным отклонением; проверьте записи сообщений и обратные вызовы.
Webhook со статусом `whatsapp.message.updated` возвращает `failed`	Немедленно отправьте SMS и изучите ошибку. Распространенный код — `131026` (сообщение не доставлено): возможно, номер не зарегистрирован в WhatsApp, однако вероятны и другие причины.
Срок TTL доставки истек, получен отчет `sent`, но нет отчета `delivered` или `read`	Отправьте SMS, если запрос на верификацию все еще активен. Отслеживайте предельный срок доставки на своем бэкенде; не перезапускайте TTL при получении запоздавшего Webhook.
Сообщение WhatsApp доставлено, верификация завершена или срок действия кода истек	Не запускайте автоматическую резервную отправку SMS для этого запроса.

Meta взимает плату за доставленные сообщения WhatsApp. Сообщение, срок действия которого истек без доставки, не облагается комиссией Meta; при этом плата за SMS по-прежнему взимается. Отсутствие Webhook о доставке само по себе не доказывает факт недоставки, поэтому списание может произойти за оба канала, если сообщение WhatsApp было доставлено до истечения срока. См. раздел Тарифы WhatsApp. Отправляйте SMS не более одного раза на один запрос верификации, даже если обратные вызовы дублируются или приходят с опозданием. Используйте тот же неистекший код либо аннулируйте старый код при выпуске нового. Резервная отправка не должна продлевать время жизни кода.

6. Тестирование перед запуском

Тест	Ожидаемый результат
Обычная верификация	Значения в тексте и кнопке совпадают; правильный неистекший код принимается успешно.
Неверный, истекший или повторно использованный код	Бэкенд отклоняет его в соответствии с политикой, а интерфейс поясняет результат.
Запрос нового кода	Срок действия старого и нового кодов соответствует вашей политике.
Получатель не в сети или отвечает с задержкой	TTL доставки остается независимым от времени жизни кода; ожидание и резервная отправка выполняются согласно конфигурации.
Неподдерживаемые условия автозаполнения на Android	Работающий резервный сценарий позволяет клиенту продолжить процесс.
iOS и несколько устройств	Протестируйте уведомления, копирование и автозаполнение на реальных клиентах; не предполагайте одинакового поведения.
Дублирующиеся обратные вызовы, запоздалые вызовы, тайм-аут запроса	Не допускайте создания повторяющихся результатов или неконтролируемых повторных отправок.
Резервная отправка SMS	Используйте корректный номер назначения и валидный код; прекратите отправку после успешной верификации.

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

Дополнительный сценарий: верификация, инициируемая клиентом

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

FAQ

Как проверить, установлен ли WhatsApp на Android или iOS?

На Android объявите com.whatsapp и com.whatsapp.w4b в блоке package queries манифеста, затем вызовите метод OTP Android SDK от Meta isWhatsAppInstalled(context) на экземпляре WhatsAppOtpHandler. На iOS используйте UIApplication.shared.canOpenURL(URL(string: "whatsapp://otp")!) и настройте разрешения для запросов URL-схем, необходимые вашему приложению. Проверка установки помогает предложить оптимальный канал на текущем устройстве. При этом она не подтверждает, что введенный номер телефона зарегистрирован в WhatsApp. Предоставьте клиентам возможность подтвердить свой номер WhatsApp и выбрать другой канал. См. раздел Проверка установки на Android и iOS от Meta.

Поддерживает ли iOS автозаполнение в одно касание (one-tap) или без касания (zero-tap)?

iOS 26 и более поздние версии по умолчанию включают подсказки клавиатуры для всех шаблонов аутентификации. iOS распознает код в push-уведомлении WhatsApp и предлагает подсказку автозаполнения в одно касание на клавиатуре. Никаких изменений в интеграции не требуется. Более ранние версии iOS не поддерживают такое автозаполнение; используйте шаблоны с копированием кода. Интеграция кнопки one-tap и zero-tap на Android — это отдельные сценарии; zero-tap поддерживается только на Android. См. раздел Подсказки клавиатуры от Meta.

Могут ли клиенты просматривать коды верификации на связанных устройствах?

Коды аутентификации доступны только на основном устройстве WhatsApp клиента. На связанных устройствах отображается скрытое сообщение с просьбой проверить основное устройство. Эта функция безопасности Cloud API включена по умолчанию, не требует изменений в коде и не может быть настроена или кастомизирована. См. безопасность связанных устройств Meta.

​Зачем использовать WhatsApp для верификации?

​Добавление дополнительного канала доставки наряду с SMS

​Сокращение шагов при вводе кода

​Оптимизация стоимости успешной верификации

​Поиск точек оттока в процессе верификации

​Перед началом работы

​1. Выберите способ работы с кодом

​2. Создайте шаблон аутентификации

​Выберите WABA, название и язык

​Настройка содержимого и действия с кодом

​Настройка трех независимых параметров срока действия

​Отправьте и проверьте доступность

​3. Отправка через API

​Подготовка запроса

​4. Получение обновлений о доставке

​5. Проектирование интерфейса и резервный канал SMS

​Чётко информируйте о канале доставки

​Настройка резервного канала SMS

​6. Тестирование перед запуском

​Дополнительный сценарий: верификация, инициируемая клиентом

​FAQ

​Как проверить, установлен ли WhatsApp на Android или iOS?

​Поддерживает ли iOS автозаполнение в одно касание (one-tap) или без касания (zero-tap)?

​Могут ли клиенты просматривать коды верификации на связанных устройствах?