Перейти к основному содержимому

Шаблоны аутентификации с автозаполнением в одно касание | Документация для разработчиков

Шаблоны аутентификации с автозаполнением в одно касание

Обновлено: 6 февраля 2026 г
Предстоящее устаревание: начиная с 15 апреля 2026 года , PendingIntent для шаблонов аутентификации будет признан устаревшим. Если вы в настоящее время используете PendingIntent для инициирования установления соединения или проверки подлинности приложения, предпочтительным способом перехода является использование OTP Android SDK
Шаблоны аутентификации с автозаполнением в одно касание позволяют отправлять пользователям одноразовый пароль или код вместе с кнопкой автозаполнения. Когда пользователь WhatsApp нажимает кнопку автозаполнения, клиент WhatsApp запускает действие, которое открывает ваше приложение и отправляет ему пароль или код.
Шаблоны аутентификации с кнопкой автозаполнения в одно касание включают в себя:
Предварительно заданный текст: Это ваш проверочный код.Дополнительное предупреждение о безопасности: В целях вашей безопасности не передавайте этот код третьим лицам.Необязательное предупреждение об истечении срока действия: Срок действия этого кода истекает через минут.Кнопка автозаполнения в одно касание.
Примечание : 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 выполняет следующие проверки. Если какая-либо проверка не пройдена, кнопка автозаполнения в одно касание будет заменена кнопкой копирования кода.
code_expiration_minutes шаблона , если оно присутствует).Имя пакета в сообщении (определенное в package_name массива компонентов при создании шаблона) совпадает с именем пакета, заданным в интенте. Совпадение определяется методом getCreatorPackage , вызываемым в PendingIntent, предоставляемом вашим приложением. supported_apps шаблона, 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 .
 android:name = ".ReceiveCodeActivity" android:enabled = "true" android:exported = "true" android:launchMode = "standard" >  android:name = "com.whatsapp.otp.OTP_RETRIEVED" />
Это действие, которое приложение WhatsApp или WhatsApp Business запустит после получения сообщения с шаблоном аутентификации и прохождения всех проверок на соответствие требованиям .

Занятие по практической деятельности

Использование SDK (предпочтительно)
Определите публичный класс активности и создайте WhatsAppOtpIncomingIntentHandler для обработки намерения. .processOtpCode() проверяет идентификатор рукопожатия на соответствие ожидаемому значению, которое вы сохранили во время инициации рукопожатия, и обрабатывает ошибки.
public class ReceiveCodeActivity extends AppCompatActivity { @Override protected void onCreate ( Bundle savedInstanceState ) { super . onCreate ( savedInstanceState ); WhatsAppOtpIncomingIntentHandler incomingIntentHandler = new WhatsAppOtpIncomingIntentHandler (); // Получаем ожидаемый ID рукопожатия, сохраненный во время инициации рукопожатия String expectedHandshakeId = retrieveStoredHandshakeId (); incomingIntentHandler . processOtpCode ( getIntent (), expectedHandshakeId , ( code ) -> { // ID рукопожатия был проверен SDK validateCode ( code ); }, // вызываем вашу функцию для обработки ошибок ( error , exception ) -> handleError ( error , exception )); }
Без SDK
Определите публичный класс Activity, который сможет принимать код после его передачи в ваше приложение. Activity должна проверять request_id ( идентификатор подтверждения связи), чтобы убедиться, что код OTP получен в результате легитимного подтверждения связи, инициированного вашим приложением.
public class ReceiveCodeActivity extends AppCompatActivity { @Override protected void onCreate ( Bundle savedInstanceState ) { super . onCreate ( savedInstanceState ); Intent intent = getIntent (); // Извлекаем ID подтверждения из Intent 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 ( ); // Сохраняем этот  проверки при получении 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 android:name = "com.whatsapp" / > < package
android :name = "com.whatsapp.w4b " / >
запросы >
Использование SDK (предпочтительно)
Создайте экземпляр WhatsAppOtpHandler :
WhatsAppOtpHandler whatsAppOtpHandler = new WhatsAppOtpHandler ();
Проверьте, установлен ли клиент 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 : "  : // 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, как интегрировать кнопки автозаполнения в одно касание и копирования кода, как создать шаблон и как запустить тестовый сервер.