Зачем использовать WhatsApp для подтверждения?
Добавьте еще один канал доставки наряду с SMS
WhatsApp принимает сообщения через интернет-соединение. Это дает клиентам еще один способ получить код, когда доступен Wi-Fi, но прием SMS ненадежен. Получателю по-прежнему необходимы WhatsApp и работающее подключение к интернету.Сократите количество шагов для ввода кода
Кнопки копирования кода уменьшают необходимость ручного ввода. Варианты в один клик (One-tap) и без клика (Zero-tap) позволяют сократить переключение между приложениями в поддерживаемых интегрированных приложениях для Android. Для клиентов, которые уже используют WhatsApp, эти варианты могут упростить прохождение верификации. Оцените влияние на завершаемость в вашем собственном сценарии.Оптимизируйте стоимость успешной верификации
Рассмотрите WhatsApp как потенциальный способ снижения затрат на верификацию в зависимости от рынка. Сравните тарифы на аутентификацию и применимые международные тарифы на аутентификацию, сборы YCloud, затраты на резервную доставку через SMS и показатели успешности. В качестве практического показателя используйте общие расходы на каналы верификации, разделенные на количество успешных подтверждений. Meta взимает плату за доставленные сообщения; за недоставленное сообщение соответствующая плата Meta за сообщение не списывается. Прочие расходы зависят от вашего тарифа YCloud. См. Цены WhatsApp и Цены Meta.Находите этапы оттока в процессе верификации
Отслеживайте принятие запроса, доставку сообщений и успешную верификацию отдельно. Это поможет вам отличить проблемы с отправкой от проблем с получением или вводом кода. WhatsApp доставляет код. Ваша система верификации по-прежнему определяет, действителен ли он, не истек ли срок его действия, не был ли он уже использован и разрешен ли он для запрашиваемого действия.Перед началом работы
- Войдите в YCloud и подключите WABA и отправителя.
- Подготовьте логику запроса, генерации, хранения и проверки кодов. В этом руководстве используется WhatsApp Messages API; ваша система управляет жизненным циклом кодов. Информацию о службе верификации YCloud см. в разделе Verify.
- Подготовьте серверный API-ключ и приемник Webhook.
- Используйте тестового получателя, который запросил код. Запрос кода не является разрешением на последующую рассылку маркетинговых сообщений.
- Настройте и протестируйте канал SMS, если вам нужен резервный вариант доставки. WhatsApp Messages API не отправляет SMS автоматически при соблюдении рекомендаций из этого руководства.
1. Выберите способ работы с кодом
Варианты в один клик или без клика могут переключаться на другой способ, например копирование кода, если требования к устройству или приложению не соблюдены. Обеспечьте поддержку этого резервного варианта. Выбор опции в редакторе не выполняет интеграцию вашего клиентского приложения автоматически.
Meta также описывает предложения OTP-кода на клавиатуре из уведомлений на iOS 26 и новее. Это работает отдельно от вариантов One-tap и Zero-tap на Android; тестируйте их раздельно. См. Шаблоны аутентификации и Документация Meta по аутентификации.
Meta example: the customer copies the verification code and enters it in your app. The code and expiry shown are demonstration values.
2. Создайте шаблон аутентификации
Выберите WABA, имя и язык
Откройте Шаблоны для нужного WABA в YCloud, выберите Добавить шаблон и укажите Аутентификация. Используйте строчные буквы, цифры и символы подчеркивания для имени, напримерlogin_verification. Выберите язык вашего клиента и сохраните точное утвержденное имя и код языка для отправки. См. Создать шаблон.
Настройте содержимое и действие для кода
Для аутентификации используется предустановленный текст кода с поддерживаемыми уведомлениями о безопасности и сроке действия. Не вставляйте в текст сообщения обычные рекламные тексты, URL-адреса, медиафайлы или эмодзи. Выберите Копировать код, Автозаполнение или Zero Tap. Для вариантов «Автозаполнение» и «Zero Tap» укажите фактическое имя пакета Android и хэш подписи, а затем выполните интеграцию приложения. Для Zero Tap также требуется принять соответствующие условия. Для настройки API используйте актуальный контрактsupported_apps, а не устаревшие примеры верхнего уровня package_name и signature_hash. Ознакомьтесь с руководствами по интеграции аутентификации для получения подробной информации об Android SDK и процессе подтверждения связи.
Настройте три отдельных параметра срока действия
Текущий контракт YCloud поддерживает стандартные кастомные значения TTL аутентификации в диапазоне 30–900 секунд, со значением по умолчанию 10 минут для новых шаблонов. Ранее использовавшиеся значения по умолчанию могут отличаться; проверьте сохраненный
messageSendTtlSeconds. Отображаемое уведомление о сроке действия поддерживает 1–90 минут , но не изменяет срок действия на бэкенде и не расширяет стандартный диапазон TTL доставки.
Контракт также поддерживает -1, который устанавливает кастомный TTL на 30 дней. Это не рекомендуется для короткоживущих кодов и не означает мгновенное истечение срока действия или отключение повторных попыток. См. контракт YCloud OpenAPI.
Например, если код сгенерирован в 10:00 и истекает в 10:05, у него останется одна минута, если он будет доставлен в 10:04. Получение сообщения не перезапускает срок действия. Истечение TTL прекращает незавершенные попытки доставки; оно не отзывает сообщение, уже доставленное на устройство клиента.
Отправьте на проверку и проверьте доступность
Отправьте шаблон и проверьте его фактический статус модерации. Отправляйте сообщения только после того, как он будет одобрен и станет доступен для использования. В случае отклонения выясните причину и следуйте руководству Модерация и жизненный цикл шаблонов. Не рассчитывайте на фиксированное время одобрения.3. Отправка через API
Отправляйте сообщение сразу после того, как клиент запросит код. Выберите поведение отправки, необходимое для вашего сценария:
Имя эндпоинта
sendDirectly описывает тайминг отправки. Оно не связано с функцией Utility Direct Send, которая отвечает за генерацию шаблонов. В этом сценарии по-прежнему используется одобренный шаблон аутентификации.
Подготовка запроса
- Выполняйте аутентификацию на стороне сервера с помощью
X-API-Key. - Используйте номера в формате E.164, включая телефонные коды стран, для
fromиto. - Установите для
typeзначениеtemplateи используйте одобренное имя и язык для выбранного WABA. - Передавайте один и тот же код в теле сообщения и в параметрах кнопки OTP.
- Свяжите ваш запрос верификации с идентификатором сообщения YCloud. Параметр
externalIdпомогает при сопоставлении данных, но не гарантирует идемпотентность.
123456 является вымышленным и в рабочей среде должно генерироваться вашей системой верификации:
sub_type: url; не используйте стандартную структуру кнопок с промокодами для маркетинга. См. разделы Аутентификация с копированием кода и Отправка сообщения WhatsApp. Вы также можете выбрать Ещё → Копировать как cURL для одобренного шаблона и сверить сгенерированные параметры с его конфигурацией.
Успешный ответ API не подтверждает факт доставки. Если время ожидания запроса истекло, проверьте доступные записи сообщений и колбэки перед повторной отправкой.
4. Получение обновлений о доставке
В разделе Разработчикам → Webhook-уведомления создайте эндпоинт, укажите ваш callback-URL и подпишитесь наwhatsapp.message.updated. Ознакомьтесь с руководством по Webhook для настройки проверки подписи, подтверждений и повторных попыток.
Связывайте каждый идентификатор сообщения с соответствующим запросом верификации:
Отмечайте верификацию как завершенную только тогда, когда ваш бэкенд проверит код. Обрабатывайте дублирующиеся и запоздалые обратные вызовы, не допуская перезаписи более позднего статуса более ранним. Используйте Журналы сообщений для ручного анализа.
5. Проектирование интерфейса и резервного канала SMS
Четко информируйте о канале доставки
Перед отправкой укажите, что код придет через WhatsApp. После отправки отобразите маскированный номер получателя, сообщение об ожидании, обратный отсчет до повторной отправки и доступные альтернативы. Предоставьте клиентам возможность вернуться и исправить номер.
Если операционная система позволяет, ваше приложение может использовать проверку наличия WhatsApp для предложения канала. Установка приложения не гарантирует, что введенный номер зарегистрирован или доступен. Отрицательный результат не исключает получение кода на другом устройстве. Не используйте проверку установки приложения вместо проверки номера.
Разделяйте обработку ошибок и задержек
Интервал 15–60 секунд из исходного руководства можно использовать в качестве экспериментального диапазона ожидания. Скорректируйте его на основе наблюдаемой задержки и доли отказов. Это не требование WhatsApp и не гарантия времени доставки.
Для одного и того же запроса проверки можно отправить тот же действующий код по резервному каналу. При генерации нового кода аннулируйте предыдущий в соответствии с вашей политикой и сообщите об этом поведении пользователю. Переход на резервный канал не должен продлевать срок действия старого кода.
Используйте один запрос на верификацию для управления попытками отправки по каналам, временем ожидания перед повторной отправкой и завершением процесса. Повторные нажатия или дублирующиеся и запоздалые обратные вызовы не должны приводить к отправке нескольких SMS. Если придут сообщения и по WhatsApp, и по SMS, плата может взиматься за каждый канал.
6. Тестирование перед запуском
После запуска сравнивайте процент доставки, задержку доставки, долю завершенных верификаций, долю резервных переходов на SMS и стоимость одной успешной верификации по рынкам, каналам и устройствам. Используйте эти данные для настройки приоритета каналов и порогов ожидания вместо обещаний того, что WhatsApp всегда быстрее или дешевле, чем SMS.