> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Отправка кодов подтверждения через WhatsApp Используйте коды подтверждения WhatsApp для регистрации, входа в систему, восстановления учетной записи и дополнительной проверки важных действий. После того как клиент выбирает WhatsApp, ваша система отправляет шаблон аутентификации. Клиент копирует или автозаполняет код, а ваш бэкенд проверяет его. ## Зачем использовать WhatsApp для подтверждения? ### Добавьте еще один канал доставки наряду с SMS WhatsApp принимает сообщения через интернет-соединение. Это дает клиентам еще один способ получить код, когда доступен Wi-Fi, но прием SMS ненадежен. Получателю по-прежнему необходимы WhatsApp и работающее подключение к интернету. ### Сократите количество шагов для ввода кода Кнопки копирования кода уменьшают необходимость ручного ввода. Варианты в один клик (One-tap) и без клика (Zero-tap) позволяют сократить переключение между приложениями в поддерживаемых интегрированных приложениях для Android. Для клиентов, которые уже используют WhatsApp, эти варианты могут упростить прохождение верификации. Оцените влияние на завершаемость в вашем собственном сценарии. ### Оптимизируйте стоимость успешной верификации Рассмотрите WhatsApp как потенциальный способ снижения затрат на верификацию в зависимости от рынка. Сравните тарифы на аутентификацию и применимые международные тарифы на аутентификацию, сборы YCloud, затраты на резервную доставку через SMS и показатели успешности. В качестве практического показателя используйте общие расходы на каналы верификации, разделенные на количество успешных подтверждений. Meta взимает плату за доставленные сообщения; за недоставленное сообщение соответствующая плата Meta за сообщение не списывается. Прочие расходы зависят от вашего тарифа YCloud. См. [Цены WhatsApp](/ru/documentation/whatsapp-business-platform/pricing-limits-and-quality/whatsapp-pricing) и [Цены Meta](https://business.whatsapp.com/products/platform-pricing). ### Находите этапы оттока в процессе верификации Отслеживайте принятие запроса, доставку сообщений и успешную верификацию отдельно. Это поможет вам отличить проблемы с отправкой от проблем с получением или вводом кода. WhatsApp доставляет код. Ваша система верификации по-прежнему определяет, действителен ли он, не истек ли срок его действия, не был ли он уже использован и разрешен ли он для запрашиваемого действия. ## Перед началом работы 1. Войдите в [YCloud](https://www.ycloud.com/console/#/entry/login) и [подключите WABA и отправителя](/ru/documentation/quick-start/connect-whatsapp-to-ycloud). 2. Подготовьте логику запроса, генерации, хранения и проверки кодов. В этом руководстве используется WhatsApp Messages API; ваша система управляет жизненным циклом кодов. Информацию о службе верификации YCloud см. в разделе [Verify](/ru/documentation/integrations/channels/verify/index). 3. Подготовьте [серверный API-ключ](/ru/documentation/developer/manage-api-keys) и [приемник Webhook](/ru/documentation/developer/webhooks). 4. Используйте тестового получателя, который запросил код. Запрос кода не является разрешением на последующую рассылку маркетинговых сообщений. 5. Настройте и протестируйте канал SMS, если вам нужен резервный вариант доставки. WhatsApp Messages API не отправляет SMS автоматически при соблюдении рекомендаций из этого руководства. ## 1. Выберите способ работы с кодом | Вариант | Действие клиента | Что нужно подготовить | Когда выбирать | | - | - | - | - | | **Копирование кода** | Скопируйте в WhatsApp, затем введите код на сайте или в приложении. | Экран ввода и бэкенд-верификация. | Сайты, различные платформы и первоначальная интеграция. | | **В один клик / Автозаполнение (One-tap / Autofill)** | Нажмите кнопку, которая передает код в поддерживаемое приложение Android. | Имя пакета, хеш подписи и интеграция квитирования (handshake). | Сокращение переключений и вставки на Android. | | **Без клика (Zero-tap)** | Поддерживаемое приложение Android получает код без переключения в WhatsApp. | Интеграция с Android, проверка соответствия требованиям и принятие применимых условий. | Дополнительное сокращение взаимодействия при возможности протестировать поддерживаемые условия. | Варианты в один клик или без клика могут переключаться на другой способ, например копирование кода, если требования к устройству или приложению не соблюдены. Обеспечьте поддержку этого резервного варианта. Выбор опции в редакторе не выполняет интеграцию вашего клиентского приложения автоматически. Meta также описывает предложения OTP-кода на клавиатуре из уведомлений на iOS 26 и новее. Это работает отдельно от вариантов One-tap и Zero-tap на Android; тестируйте их раздельно. См. [Шаблоны аутентификации](/ru/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/index) и [Документация Meta по аутентификации](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates/). Пример аутентификации Meta с короткой стрелкой, указывающей на Копировать код. Источник: [Шаблоны аутентификации Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-templates/). ## 2. Создайте шаблон аутентификации ### Выберите WABA, имя и язык Откройте **Шаблоны** для нужного WABA в YCloud, выберите **Добавить шаблон** и укажите **Аутентификация**. Используйте строчные буквы, цифры и символы подчеркивания для имени, например `login_verification`. Выберите язык вашего клиента и сохраните точное утвержденное имя и код языка для отправки. См. [Создать шаблон](/ru/documentation/channels/whatsapp-accounts-management/template-management/create-template/index). ### Настройте содержимое и действие для кода Для аутентификации используется предустановленный текст кода с поддерживаемыми уведомлениями о безопасности и сроке действия. Не вставляйте в текст сообщения обычные рекламные тексты, URL-адреса, медиафайлы или эмодзи. Выберите **Копировать код**, **Автозаполнение** или **Zero Tap**. Для вариантов «Автозаполнение» и «Zero Tap» укажите фактическое имя пакета Android и хэш подписи, а затем выполните интеграцию приложения. Для Zero Tap также требуется принять соответствующие условия. Для настройки API используйте актуальный контракт `supported_apps`, а не устаревшие примеры верхнего уровня `package_name` и `signature_hash`. Ознакомьтесь с [руководствами по интеграции аутентификации](/ru/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/index) для получения подробной информации об Android SDK и процессе подтверждения связи. ### Настройте три отдельных параметра срока действия | Параметр | Что контролирует | Пример для 5 минут | | - | - | - | | Срок действия кода на бэкенде | Момент, когда ваш сервер отклоняет код. | Пять минут после генерации. | | Отображаемое уведомление о сроке действия | Какая информация сообщается клиенту. | Пять минут, в соответствии с вашей фактической политикой. | | Время жизни доставки (TTL) | В течение какого времени могут предприниматься попытки доставки. | Не дольше оставшегося полезного срока действия кода, с учетом времени между генерацией и отправкой. | Текущий контракт YCloud поддерживает стандартные кастомные значения TTL аутентификации в диапазоне **30–900 секунд**, со значением по умолчанию **10 минут** для новых шаблонов. Ранее использовавшиеся значения по умолчанию могут отличаться; проверьте сохраненный `messageSendTtlSeconds`. Отображаемое уведомление о сроке действия поддерживает **1–90 минут** , но не изменяет срок действия на бэкенде и не расширяет стандартный диапазон TTL доставки. Контракт также поддерживает `-1`, который устанавливает кастомный TTL на 30 дней. Это не рекомендуется для короткоживущих кодов и не означает мгновенное истечение срока действия или отключение повторных попыток. См. [контракт YCloud OpenAPI](https://newdocs.ycloud.com/openapi/endpoints/ycloud-api-v2.yaml). Например, если код сгенерирован в 10:00 и истекает в 10:05, у него останется одна минута, если он будет доставлен в 10:04. Получение сообщения не перезапускает срок действия. Истечение TTL прекращает незавершенные попытки доставки; оно не отзывает сообщение, уже доставленное на устройство клиента. ### Отправьте на проверку и проверьте доступность Отправьте шаблон и проверьте его фактический статус модерации. Отправляйте сообщения только после того, как он будет одобрен и станет доступен для использования. В случае отклонения выясните причину и следуйте руководству [Модерация и жизненный цикл шаблонов](/ru/documentation/whatsapp-business-platform/messaging/message-templates/template-review-and-lifecycle). Не рассчитывайте на фиксированное время одобрения. ## 3. Отправка через API Отправляйте сообщение сразу после того, как клиент запросит код. Выберите поведение отправки, необходимое для вашего сценария: | Эндпоинт | Поведение | | - | - | | `POST /v2/whatsapp/messages/sendDirectly` | Синхронная отправка в WhatsApp Business API; удобно, когда сценарию OTP требуется результат отправки немедленно. | | `POST /v2/whatsapp/messages` | Постановка сообщения в очередь для асинхронной отправки. | Имя эндпоинта `sendDirectly` описывает тайминг отправки. Оно не связано с функцией Utility Direct Send, которая отвечает за генерацию шаблонов. В этом сценарии по-прежнему используется одобренный шаблон аутентификации. ### Подготовка запроса * Выполняйте аутентификацию на стороне сервера с помощью `X-API-Key`. * Используйте номера в формате E.164, включая телефонные коды стран, для `from` и `to`. * Установите для `type` значение `template` и используйте одобренное имя и язык для выбранного WABA. * Передавайте один и тот же код в теле сообщения и в параметрах кнопки OTP. * Свяжите ваш запрос верификации с идентификатором сообщения YCloud. Параметр `externalId` помогает при сопоставлении данных, но не гарантирует идемпотентность. Пример тела запроса с кнопкой «Копировать код». Замените плейсхолдеры; значение `123456` является вымышленным и в рабочей среде должно генерироваться вашей системой верификации: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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`; не используйте стандартную структуру кнопок с промокодами для маркетинга. См. разделы [Аутентификация с копированием кода](/ru/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/copy-code-authentication) и [Отправка сообщения WhatsApp](/ru/api-reference/guides/whatsapp-platform/send-whatsapp-message). Вы также можете выбрать **Ещё → Копировать как cURL** для одобренного шаблона и сверить сгенерированные параметры с его конфигурацией. Успешный ответ API не подтверждает факт доставки. Если время ожидания запроса истекло, проверьте доступные записи сообщений и колбэки перед повторной отправкой. ## 4. Получение обновлений о доставке В разделе **Разработчикам → Webhook-уведомления** создайте эндпоинт, укажите ваш callback-URL и подпишитесь на `whatsapp.message.updated`. Ознакомьтесь с [руководством по Webhook](/ru/documentation/developer/webhooks) для настройки проверки подписи, подтверждений и повторных попыток. Связывайте каждый идентификатор сообщения с соответствующим запросом верификации: | Статус | Значение | Реакция сценария | | - | - | - | | `sent` | Отправлено, без подтверждения доставки на устройство клиента. | Ожидать обновлений о доставке или сбое. | | `delivered` | Доставлено получателю. | Ожидать успешной проверки кода. | | `read` | Получен отчет о прочтении. | Не отмечайте верификацию как завершенную и не считайте отсутствие отчетов ошибкой. | | `failed` | Ошибка отправки или доставки. | Проверьте ошибку перед исправлением конфигурации, повторной попыткой или сменой канала. | Отмечайте верификацию как завершенную только тогда, когда ваш бэкенд проверит код. Обрабатывайте дублирующиеся и запоздалые обратные вызовы, не допуская перезаписи более позднего статуса более ранним. Используйте [Журналы сообщений](/ru/documentation/channels/whatsapp-accounts-management/data-analysis/message-logs) для ручного анализа. ## 5. Проектирование интерфейса и резервного канала SMS ### Четко информируйте о канале доставки Перед отправкой укажите, что код придет через WhatsApp. После отправки отобразите маскированный номер получателя, сообщение об ожидании, обратный отсчет до повторной отправки и доступные альтернативы. Предоставьте клиентам возможность вернуться и исправить номер. | Стратегия | Когда подходит | Пользовательский опыт | | - | - | - | | Сначала WhatsApp, затем SMS | Ваши данные показывают, что клиенты преимущественно используют WhatsApp. | Укажите первый канал; предложите SMS в случае ошибки или задержки либо отправьте сообщение в соответствии с описанной политикой резервирования. | | Клиент выбирает сам | Рынки, устройства или предпочтения различаются. | Предложите WhatsApp и SMS одновременно и сохраняйте соответствующие предпочтения. | Если операционная система позволяет, ваше приложение может использовать проверку наличия WhatsApp для предложения канала. Установка приложения не гарантирует, что введенный номер зарегистрирован или доступен. Отрицательный результат не исключает получение кода на другом устройстве. Не используйте проверку установки приложения вместо проверки номера. ### Разделяйте обработку ошибок и задержек | Ситуация | Рекомендуемое действие | | - | - | | Явная ошибка | Классифицируйте ошибку. Используйте SMS, если это допускается политикой резервирования, а номер и код остаются действительными. Исправляйте ошибки ключей API, шаблонов или аккаунта, а не маскируйте их только переходом на резервный канал. | | Отправка без своевременного подтверждения доставки | Используйте настраиваемое время ожидания перед предложением другого канала или применением резервирования. Отсутствие подтверждения не является доказательством недоставки. | | Доставлено без завершения верификации | Оставляйте доступными поля ввода и варианты повтора; не отправляйте повторные сообщения непрерывно только потому, что верификация еще не завершена. | | Верификация завершена или срок действия кода истек | Остановите дальнейшие отправки для этого запроса. | Интервал **15–60 секунд** из исходного руководства можно использовать в качестве экспериментального диапазона ожидания. Скорректируйте его на основе наблюдаемой задержки и доли отказов. Это не требование WhatsApp и не гарантия времени доставки. Для одного и того же запроса проверки можно отправить тот же действующий код по резервному каналу. При генерации нового кода аннулируйте предыдущий в соответствии с вашей политикой и сообщите об этом поведении пользователю. Переход на резервный канал не должен продлевать срок действия старого кода. Используйте один запрос на верификацию для управления попытками отправки по каналам, временем ожидания перед повторной отправкой и завершением процесса. Повторные нажатия или дублирующиеся и запоздалые обратные вызовы не должны приводить к отправке нескольких SMS. Если придут сообщения и по WhatsApp, и по SMS, плата может взиматься за каждый канал. ## 6. Тестирование перед запуском | Тест | Ожидаемый результат | | - | - | | Обычная верификация | Значения в тексте сообщения и на кнопке совпадают; правильный неистекший код успешно проходит проверку. | | Неверный, истекший или повторно использованный код | Бэкенд отклоняет его в соответствии с политикой, а интерфейс объясняет результат. | | Запрос нового кода | Срок действия старого и нового кодов соответствует вашей политике. | | Получатель оффлайн или с задержкой связи | Срок доставки TTL не зависит от срока действия кода; ожидание и переход на резервный канал происходят согласно конфигурации. | | Неподдерживаемые условия автозаполнения на Android | Доступный резервный вариант позволяет клиенту продолжить. | | iOS и несколько устройств | Протестируйте получение уведомлений, копирование и ввод на реальных клиентах; не предполагайте одинакового поведения. | | Дублирующиеся обратные вызовы, запоздалые обратные вызовы, таймаут запроса | Не создавайте дублирующихся результатов или неконтролируемых повторных отправок. | | Резервный канал SMS | Используйте правильный номер назначения и действительный код; остановите отправку после успешной верификации. | После запуска сравнивайте процент доставки, задержку доставки, долю завершенных верификаций, долю резервных переходов на SMS и стоимость одной успешной верификации по рынкам, каналам и устройствам. Используйте эти данные для настройки приоритета каналов и порогов ожидания вместо обещаний того, что WhatsApp всегда быстрее или дешевле, чем SMS. ## Дополнительный сценарий: верификация, инициированная клиентом В сценарии верификации, инициируемой клиентом, пользователь открывает WhatsApp из приложения, отправляет сообщение с информацией для текущей проверки и затем возвращается в приложение. Оценивайте этот сценарий отдельно. Обычного входящего сообщения в WhatsApp самого по себе недостаточно для входа на сайт или в приложение. Для этого подхода требуются одноразовый запрос (challenge), привязка к сессии, срок действия, защита от повторного воспроизведения и подтверждение пользователя. Упомянутые материалы YCloud не предоставляют готовой функции входа, поэтому данное руководство не рассматривает ее как стандартный шаг интеграции. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.