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

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

Шаблоны аутентификации без касания

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

Ограничения

Функция аутентификации без касания поддерживается только на Android. Если вы отправите шаблон аутентификации без касания пользователю WhatsApp, использующему устройство, отличное от Android, клиент WhatsApp отобразит вместо этого кнопку «Копировать код».
URL-адреса, медиафайлы и эмодзи не поддерживаются.

Передовые методы

    Не используйте WhatsApp в качестве основного способа получения паролей/кодов.Четко объясните пользователям вашего приложения, что пароль или код будут автоматически отправлены в приложение, когда они выберут WhatsApp для доставки.Если ваши пользователи обеспокоены автоматической доставкой пароля или кода, перейдите по ссылке на нашу «О кодах безопасности, которые автоматически заполняются в WhatsApp» .После ввода пароля/кода в вашем приложении четко сообщите пользователю, что он был успешно получен.
    Вот несколько примеров, которые наглядно демонстрируют пользователю приложения, что его код автоматически появится в приложении.

    Хэш ключа подписи приложения

    В текст сообщения необходимо включить хэш ключа подписи вашего приложения.
    Чтобы вычислить хеш, следуйте инструкциям 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.
    When a user in your app requests a password or code to be delivered to their WhatsApp number, first initiate the handshake, then call our API to send the authentication template message. When the WhatsApp client receives the message, it will perform an проверка соответствия требованиям, and if there are no errors, start a broadcast.
    Если вы не инициируете рукопожатие перед отправкой сообщения или сообщение не проходит проверку на соответствие требованиям, рассылка не будет начата. Вместо этого в доставленном сообщении отобразится кнопка автозаполнения в одно касание, если это возможно. Если это невозможно, отобразится кнопка копирования кода.

    Проверка соответствия требованиям

    При получении сообщения с шаблоном аутентификации клиент WhatsApp выполняет следующие проверки. Если какая-либо проверка не пройдена, он попытается отобразить кнопку автозаполнения в одно касание в сообщении. Если это не удастся, он вернется к кнопке копирования кода.
      The handshake was initiated no more than 10 minutes ago (or no more than the number of minutes indicated by the template’s code_expiration_minutes property, if present).The package name in the message (defined in the package_name недвижимость в компоненты array upon template creation) matches the package name set on the intent. The match is determined through the getCreatorPackage method called in the PendingIntent object provided by your application. See One-Tap Autofill Button Class.The app signing key hash in the message (defined in the signature_hash property in the components array upon template creation) matches your installed app’s signing key hash.В вашем приложении определена активность и класс для кнопки автозаполнения в одно касание, предназначенные для приема пароля или кода.В вашем приложении определен приемник широковещательных сообщений с нулевым перехватом и класс для приема пароля или кода.

      Уведомления Android

      Уведомления Android, указывающие на получение сообщения с шаблоном аутентификации WhatsApp, будут отображаться на устройстве Android пользователя только в том случае, если:
        Пользователь авторизован в приложении WhatsApp или WhatsApp Business, используя номер телефона (аккаунт), на который было отправлено сообщение.Пользователь авторизован в вашем приложении.Операционная система Android — KitKat (4.4, API 19) или выше.Show notifications is enabled (Настройки > Уведомления) in the WhatsApp app or WhatsApp Business app.Уведомления на уровне устройства включены для приложения WhatsApp или приложения WhatsApp Business.Предыдущие сообщения в приложениях WhatsApp или WhatsApp Business между пользователем и вашей компанией не отключаются.

        Использование SDK

        OTP Android SDK можно использовать для выполнения рукопожатий, а также других функций как в шаблонах аутентификации в одно касание, так и в шаблонах аутентификации без касания.
        Для доступа к функционалу SDK добавьте следующую конфигурацию в ваш файл Gradle:
        зависимости { … реализация 'com.whatsapp.otp:whatsapp-otp-android-sdk:1.0.0' … }
        
        To your repositories, add mavenCentral():
        репозитории { … mavenCentral() … }
        

        Приемник вещания без отвода

        Объявите получателя и фильтр намерений, которые могут принимать одноразовый пароль или код. Фильтр намерений должен иметь имя действия com.whatsapp.otp.OTP_RETRIEVED.
        <receiver android:name=".app.receiver.OtpCodeReceiver" android:enabled="true" android:exported="true"> <intent-filter> <action android:name="com.whatsapp.otp.OTP_RETRIEVED" /> </intent-filter> </receiver>
        
        This is the receiver that the WhatsApp app or WhatsApp Business app will start once the authentication template message is received and it passes all eligibility checks.

        Класс приемника без отвода

        Использование SDK
        We recommend using the SDK to declare a receiver. Define a class that extends BroadcastReceiver, then define the onReceive method, passing in your context and intent. Instantiate a WhatsAppOtpIncomingIntentHandler object, then run the .processOtpCode() method which will receive the intent, validate the handshake ID against the expected value you stored during handshake initiation, and handle errors.
        public class OtpCodeReceiver extends BroadcastReceiver { @Override public void onReceive(Context context, Intent intent) { WhatsAppOtpIncomingIntentHandler whatsAppOtpIncomingIntentHandler = new WhatsAppOtpIncomingIntentHandler(); // Получаем ожидаемый идентификатор рукопожатия, сохраненный во время инициации рукопожатия String expectedHandshakeId = retrieveStoredHandshakeId(); whatsAppOtpIncomingIntentHandler.processOtpCode(intent, expectedHandshakeId, (code) -> { // Идентификатор рукопожатия проверен SDK validateCode(code); }, // вызываем вашу функцию для обработки ошибок (error, exception) -> handleError(error, exception)); } }
        
        Без SDK
        The broadcast receiver class should extract and validate the request_id (handshake ID) from the intent to ensure the OTP code is coming from a legitimate handshake initiated by your app:
        public class OtpCodeReceiver extends BroadcastReceiver { @Override public void onReceive(Context context, Intent intent) { String incomingRequestId = intent.getStringExtra("request_id"); // Получаем ранее сохраненный ID рукопожатия String storedRequestId = retrieveStoredRequestId(); // Проверяем совпадение ID рукопожатия if (storedRequestId != null && storedRequestId.equals(incomingRequestId)) { // используем OTP-код String otpCode = intent.getStringExtra("code"); // ... } } }
        

        Активность кнопки автозаполнения одним нажатием

        Необязательный.
        Если вы хотите, чтобы доставленное сообщение могло автоматически заполниться одним нажатием, если проверка на соответствие требованиям не пройдена, реализуйте в своем приложении этот фильтр действий и намерений, чтобы получать одноразовый пароль или код.
        The intent filter must have the action name com.whatsapp.otp.OTP_RETRIEVED.
        <activity android:name=".ReceiveCodeActivity" android:enabled="true" android:exported="true" android:launchMode="standard"> <intent-filter> <action android:name="com.whatsapp.otp.OTP_RETRIEVED" /> </intent-filter> </activity>
        
        Это действие запустит клиент WhatsApp, если сообщение не пройдет проверку на соответствие требованиям, но при этом будет иметь право на отображение кнопки автозаполнения в одно касание.

        Класс активности кнопки автозаполнения в одно касание

        Необязательный.
        If you want the message to be able to display a one-tap autofill button if the if fails an eligibility check, define the activity public class that can accept the code once the user taps the button. The activity should validate the request_id (handshake ID) to ensure the OTP code is coming from a legitimate handshake initiated by your app.
        public class ReceiveCodeActivity extends AppCompatActivity { @Override protected void 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
        The preferred method for handshake initation is via SDK. Performing a handshake via SDK can be done by instantiating a WhatsAppOtpHandler object and passing in your context to the .sendOtpIntentToWhatsApp() method. The method returns a UUID (handshake ID) that must be stored and used to validate the incoming OTP code later:
        WhatsAppOtpHandler whatsAppOtpHandler = new WhatsAppOtpHandler(); UUID handshakeId = whatsAppOtpHandler.sendOtpIntentToWhatsApp(context); // Сохраняем handshakeId для последующей проверки полученного OTP-кода
        
        Без SDK
        This example demonstrates one way to initiate a handshake with the WhatsApp app or WhatsApp Business app. The handshake now includes a request_id (UUID) that must be stored and validated when receiving the OTP code.
        private String currentRequestId; public void sendOtpIntentToWhatsApp() { // Генерируем уникальный идентификатор рукопожатия currentRequestId = UUID.randomUUID().toString(); // Сохраняем этот идентификатор для последующей проверки при получении OTP storeRequestId(currentRequestId); // Отправляем интент OTP_REQUESTED в WhatsApp и WhatsApp Business App sendOtpIntentToWhatsApp("com.whatsapp", currentRequestId); sendOtpIntentToWhatsApp("com.whatsapp.w4b", currentRequestId); } 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

        Если вы планируете использовать WhatsApp и ваше приложение на одном устройстве, перед тем как предлагать их в качестве варианта, вы можете проверить наличие установленного WhatsApp.
        First, you need to add the following to your AndroidManifest.xml file:
        
        
        <queries> <package android:name="com.whatsapp"/> <package android:name="com.whatsapp.w4b"/> </queries>
        Instantiate the WhatsAppOtpHandler объект:
        WhatsAppOtpHandler whatAppOtpHandler = new WhatsAppOtpHandler();
        
        Check if the WhatsApp client is installed by passing the .isWhatsAppInstalled() method as the clause in an Если statement:
        Если (whatsAppOtpHandler.isWhatsAppInstalled(context)) { // ... сделать что-нибудь }
        

        сигналы ошибок

        См. раздел «Сигналы ошибок» , который может помочь в отладке.

        Коды ошибок идентификации рукопожатия

        При использовании SDK с проверкой идентификатора подтверждения могут возвращаться следующие коды ошибок:
        Код ошибки Описание
        HANDSHAKE_ID_MISSING
        Идентификатор подтверждения рукопожатия не был включен в Intent от WhatsApp
        HANDSHAKE_ID_INVALID_FORMAT
        Идентификатор подтверждения соединения не является допустимым форматом UUID
        HANDSHAKE_ID_MISMATCH
        Идентификатор подтверждения в намерении не соответствует ожидаемому значению