Шаблоны аутентификации с автозаполнением в одно касание | Документация для разработчиков
Шаблоны аутентификации с автозаполнением в одно касание
Обновлено: 6 февраля 2026 г
Предстоящее устаревание: начиная с 15 апреля 2026 года , метод установления соединения на основе
PendingIntent для шаблонов аутентификации будет признан устаревшим. Если вы в настоящее время используете PendingIntent для инициирования установления соединения или проверки подлинности приложения, предпочтительным способом перехода является использование OTP Android SDK Шаблоны аутентификации с автозаполнением в одно касание позволяют отправлять пользователям одноразовый пароль или код вместе с кнопкой автозаполнения. Когда пользователь WhatsApp нажимает кнопку автозаполнения, клиент WhatsApp запускает действие, которое открывает ваше приложение и отправляет ему пароль или код.

Шаблоны аутентификации с кнопкой автозаполнения в одно касание включают в себя:
Предварительно заданный текст: <VERIFICATION_CODE> is your verification code.Дополнительное предупреждение о безопасности: В целях вашей безопасности не передавайте этот код третьим лицам.Необязательное предупреждение об истечении срока действия: Срок действия этого кода истекает через Кнопка автозаполнения в одно касание.
Примечание: SDK OTP для Android предлагает упрощенный рабочий процесс для реализации шаблонов аутентификации в одно касание и без касаний. Ниже вы можете узнать, как его использовать.
Ограничения
Кнопки автозаполнения в одно касание поддерживаются только на Android. Если вы отправите шаблон аутентификации пользователю WhatsApp, использующему устройство, отличное от Android, клиент WhatsApp отобразит вместо него кнопку «Скопировать код».
URL-адреса, медиафайлы и эмодзи не поддерживаются.
Хэш ключа подписи приложения
В текст сообщения необходимо включить хэш ключа подписи вашего приложения.
Чтобы вычислить хеш, следуйте инструкциям Google по вычислению хеш - строки вашего приложения.
В качестве альтернативы, если вы будете следовать инструкциям Google и загрузите сертификат ключа подписи вашего приложения (шаг 1), вы сможете использовать свой сертификат со sms_retriever_hash_v9.shоболочки для вычисления хеша. Например:
./sms_retriever_hash_v9.sh --package "com.example.myapplication" --keystore ~/.android/debug.keystoreПоддерживаемые приложения
Массив
supported_apps позволяет задавать пары имен пакетов приложений и хешей ключей подписи для до 5 приложений. Это может быть полезно, если у вас есть разные сборки приложений, и вы хотите, чтобы каждая из них могла инициировать рукопожатие:В качестве альтернативы, если вы используете Graph API версии 20.0 или более старой и у вас только одно приложение, вы можете определить имя пакета приложения и хэш ключа подписи в качестве
buttons , но это не рекомендуется, поскольку мы прекратим поддержку этого метода начиная с версии 21.0:Рукопожатие
Необходимо дать понять клиенту WhatsApp, что вы ожидаете скорую доставку пароля или кода. Это можно сделать, инициировав «рукопожатие».
«Рукопожатие» — это Android-интент и публичный класс, который вы реализуете, но который может запустить клиент WhatsApp.
Когда пользователь в вашем приложении запрашивает одноразовый пароль или код подтверждения и выбирает доставку на свой номер WhatsApp, сначала выполняется рукопожатие, затем вызывается наш API для отправки шаблона сообщения аутентификации. Когда клиент WhatsApp получает сообщение, он выполняет проверку соответствия требованиям, и если ошибок нет, запускает Intent и отображает сообщение пользователю. Наконец, когда пользователь нажимает кнопку автозаполнения в сообщении, мы автоматически загружаем ваше приложение и передаем ему пароль или код.

Если перед отправкой сообщения не будет выполнено подтверждение соединения, или сообщение не пройдет проверку на соответствие требованиям, в доставленном сообщении вместо кнопки быстрого доступа будет отображаться кнопка копирования кода.
Проверка соответствия требованиям
При получении сообщения с шаблоном аутентификации клиент WhatsApp выполняет следующие проверки. Если какая-либо проверка не пройдена, кнопка автозаполнения в одно касание будет заменена кнопкой копирования кода.
Соглашение было инициировано не более 10 минут назад (или не более чем за количество минут, указанное свойством code_expiration_minutes шаблона , если оно присутствует).Имя пакета в сообщении (определенное в package_name массива компонентов при создании шаблона) совпадает с именем пакета, заданным в интенте. Совпадение определяется методом getCreatorPackage , вызываемым в PendingIntent, предоставляемом вашим приложением.Ни одно из других приложений, включенных вами в список supported_apps шаблона, не инициировало соединение за последние 10 минут (или за количество минут, указанное свойством code_expiration_minutes шаблона , если оно присутствует).Хэш ключа подписи приложения в сообщении (определенный в signature_hash в массиве компонентов при создании шаблона) совпадает с хэшем ключа подписи установленного приложения.В сообщении содержится текст кнопки автозаполнения одним касанием.В вашем приложении определено действие для получения пароля или кода.
Уведомления Android
Уведомления Android, указывающие на получение сообщения с шаблоном аутентификации WhatsApp, будут отображаться на устройстве Android пользователя только в том случае, если:
Пользователь авторизован в приложении WhatsApp или WhatsApp Business, используя номер телефона (аккаунт), на который было отправлено сообщение.Пользователь авторизован в вашем приложении.Операционная система Android — KitKat (4.4, API 19) или выше.Включение функции «Показывать уведомления» ( Настройки > Уведомления ) возможно в приложении WhatsApp или WhatsApp Business.Уведомления на уровне устройства включены для приложения WhatsApp или приложения WhatsApp Business.Предыдущие сообщения в приложениях WhatsApp или WhatsApp Business между пользователем и вашей компанией не отключаются.
Использование SDK
OTP Android SDK можно использовать для выполнения рукопожатий, а также других функций как в шаблонах аутентификации в одно касание, так и в шаблонах аутентификации без касания.
Для доступа к функционалу SDK добавьте следующую конфигурацию в ваш файл Gradle:
зависимости {…
реализация 'com.whatsapp.otp:whatsapp-otp-android-sdk:1.0.0'…}Добавьте в ваши репозитории
mavenCentral():репозитории {…
mavenCentral()…}Активность
Объявите фильтр действий и намерений, который может принимать одноразовый пароль или код. Фильтр намерений должен иметь имя действия
com.whatsapp.otp.OTP_RETRIEVED.<activityandroid:name=".ReceiveCodeActivity"android:enabled="true"android:exported="true"android:launchMode="standard"><intent-filter><actionandroid:name="com.whatsapp.otp.OTP_RETRIEVED"/></intent-filter></activity>Это действие, которое приложение WhatsApp или WhatsApp Business запустит после получения сообщения с шаблоном аутентификации и прохождения всех проверок на соответствие требованиям.
Занятие по практической деятельности
Использование SDK (предпочтительно)
Определите публичный класс активности и создайте
WhatsAppOtpIncomingIntentHandler для обработки намерения. .processOtpCode() проверяет идентификатор рукопожатия на соответствие ожидаемому значению, которое вы сохранили во время инициации рукопожатия, и обрабатывает ошибки.publicclassReceiveCodeActivityextendsAppCompatActivity{@Overrideprotectedvoid onCreate(Bundle savedInstanceState){super.onCreate(savedInstanceState);WhatsAppOtpIncomingIntentHandler incomingIntentHandler =newWhatsAppOtpIncomingIntentHandler();// Получаем ожидаемый ID рукопожатия, сохраненный во время инициации рукопожатияString expectedHandshakeId = retrieveStoredHandshakeId();
incomingIntentHandler.processOtpCode(
getIntent(),
expectedHandshakeId,(code)->{// ID рукопожатия был проверен SDK
validateCode(code);},// вызываем вашу функцию для обработки ошибок(error, exception)-> handleError(error, exception));}Без SDK
Определите публичный класс Activity, который сможет принимать код после его передачи в ваше приложение. Activity должна проверять request_id
( идентификатор подтверждения связи), чтобы убедиться, что код OTP получен в результате легитимного подтверждения связи, инициированного вашим приложением.publicclassReceiveCodeActivityextendsAppCompatActivity{@Overrideprotectedvoid onCreate(Bundle savedInstanceState){super.onCreate(savedInstanceState);Intent intent = getIntent();// Извлекаем ID подтверждения из интентаString incomingRequestId = intent.getStringExtra("request_id");// Получаем ранее сохраненный ID подтвержденияString storedRequestId = retrieveStoredRequestId();// Проверяем совпадение ID подтвержденияif(storedRequestId !=null&& storedRequestId.equals(incomingRequestId)){// используем OTP-кодString otpCode = intent.getStringExtra("code");// ...}}}Начало рукопожатия
Использование SDK (предпочтительно)
Для выполнения рукопожатия можно создать
WhatsAppOtpHandler и передать контекст методу .sendOtpIntentToWhatsApp() . Метод возвращает UUID (идентификатор рукопожатия), который необходимо сохранить и использовать для последующей проверки входящего кода OTP:WhatsAppOtpHandler whatsAppOtpHandler = new WhatsAppOtpHandler ();
UUID handshakeId = whatsAppOtpHandler.sendOtpIntentToWhatsApp ( context ); // Сохраняем handshakeId для последующей проверки полученного OTP-кодаБез SDK
Этот пример демонстрирует один из способов инициировать рукопожатие с клиентом WhatsApp. Рукопожатие включает в себя идентификатор
запроса (UUID), который необходимо сохранить и проверить при получении кода OTP.private String currentRequestId ; public void sendOtpIntentToWhatsApp () { // Генерируем уникальный идентификатор рукопожатия
currentRequestId = UUID.randomUUID (). toString ( ); // Сохраняем этот ID для последующей проверки при получении OTP
storeRequestId ( currentRequestId ); //
Отправляем
интент OTP_REQUESTED в WhatsApp и WhatsApp Business } private void sendOtpIntentToWhatsApp ( String packageName , String requestId ) { /** * Начиная с Build.VERSION_CODES.S, потребуется явно * указать изменяемость PendingIntents при создании либо с помощью * (@link #FLAG_IMMUTABLE}, либо FLAG_MUTABLE */ int flags = Build.VERSION.SDK_INT > = Build.VERSION_CODES.S ? FLAG_IMMUTABLE : 0 ; PendingIntent pi = PendingIntent.getActivity ( getApplicationContext ( ) , 0 , new Intent (
) , flags )
; // Отправить интент OTP_REQUESTED в WhatsApp Intent intentToWhatsApp = new Intent ( ) ;
intentToWhatsApp.setPackage ( packageName ) ;
intentToWhatsApp.setAction ( "com.whatsapp.otp.OTP_REQUESTED" ) ; // WhatsApp будет использовать это для проверки личности вызывающего приложения. Bundle extras = intentToWhatsApp.getExtras ( ) ; if ( extras == null ) {
extras = new Bundle (); }
extras.putParcelable ( "_ci_" , pi ); // Добавляем идентификатор рукопожатия для безопасной проверки
intentToWhatsApp.putExtra ( " request_id" , requestId ) ; intentToWhatsApp.putExtras
( extras ) ; getApplicationContext
( ). sendBroadcast ( intentToWhatsApp ); }Проверка наличия установленного WhatsApp на Android
Если вы планируете использовать WhatsApp и ваше приложение на одном устройстве, перед тем как предлагать их в качестве варианта, вы можете проверить наличие установленного WhatsApp.
Для начала необходимо добавить следующее в
AndroidManifest.xml :<queries>>> <package:name="com.whatsapp"/< queriesandroid packageandroid:name="com.whatsapp.w4b"/>
Использование SDK (предпочтительно)
Создайте экземпляр
WhatsAppOtpHandler :WhatsAppOtpHandler whatsAppOtpHandler =newWhatsAppOtpHandler();Проверьте, установлен ли клиент WhatsApp, передав
isWhatsAppInstalled в качестве условия в If :Если ( whatsAppOtpHandler.isWhatsAppInstalled ( context )) { // ... сделать что - нибудь }Без SDK
if ( this.isWhatsAppInstalled ( context ) ) { // ... сделать что-то } public boolean isWhatsAppInstalled ( final @NonNull Context context ) { return isWhatsAppInstalled ( context , " com.whatsapp " ) || isWhatsAppInstalled (
context , " com.whatsapp.w4b " ); } public boolean isWhatsAppInstalled ( final @NonNull Context context , final @NonNull String type ) { final Intent intent = new Intent ( ) ;
intent.setPackage ( type ) ; intent.setAction ( " com.whatsapp.otp.OTP_REQUESTED " ) ; PackageManager packageManager = context.getPackageManager ( ) ; List <ResolveInfo> receivers = packageManager.queryBroadcastReceivers ( intent , 0 ) ; return ! receivers.isEmpty (
) ; } }Проверка наличия установленного WhatsApp на iOS
Используйте следующий код в своем iOS-приложении, чтобы проверить, установлен ли WhatsApp
let schemeURL = URL ( string : " whatsapp : // otp" ) ! let isWhatsAppInstalled = UIApplication.shared.canOpenURL ( schemeURL )сигналы ошибок
См. раздел «Сигналы ошибок» , который может помочь в отладке.
Коды ошибок идентификации рукопожатия
При использовании SDK с проверкой идентификатора подтверждения могут возвращаться следующие коды ошибок:
| Код ошибки | Описание |
|---|---|
HANDSHAKE_ID_MISSING |
Идентификатор подтверждения рукопожатия не был включен в Intent от WhatsApp |
HANDSHAKE_ID_INVALID_FORMAT |
Идентификатор подтверждения соединения не является допустимым форматом UUID |
HANDSHAKE_ID_MISMATCH |
Идентификатор подтверждения в намерении не соответствует ожидаемому значению |
Пример приложения
Посмотрите наш пример приложения WhatsAppдля Android, загружаемого через API, на Github. В примере приложения показано, как отправлять и получать пароли и коды OTP через API, как интегрировать кнопки автозаполнения в одно касание и копирования кода, как создать шаблон и как запустить тестовый сервер.
Комментарии отсутствуют
Комментарии отсутствуют