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

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

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

Обновлено: 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.
    Когда пользователь вашего приложения запрашивает пароль или код для отправки на свой номер WhatsApp, сначала инициируйте рукопожатие , а затем вызовите наш API для отправки шаблона сообщения аутентификации. Когда клиент WhatsApp получит сообщение, он выполнит проверку на соответствие требованиям , и если ошибок нет, начнет рассылку.
    Если вы не инициируете рукопожатие перед отправкой сообщения или сообщение не проходит проверку на соответствие требованиям, рассылка не будет начата. Вместо этого в доставленном сообщении отобразится кнопка автозаполнения в одно касание, если это возможно. Если это невозможно, отобразится кнопка копирования кода.

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

    При получении сообщения с шаблоном аутентификации клиент WhatsApp выполняет следующие проверки. Если какая-либо проверка не пройдена, он попытается отобразить кнопку автозаполнения в одно касание в сообщении. Если это не удастся, он вернется к кнопке копирования кода.
      code_expiration_minutes шаблона , если оно присутствует).Имя пакета в сообщении (определенное в package_name массива компонентов при создании шаблона) совпадает с именем пакета, заданным в интенте. Совпадение определяется методом getCreatorPackage , вызываемым в PendingIntent , предоставляемом вашим приложением. См. Класс кнопки автозаполнения в одно касание .Хэш ключа подписи приложения в сообщении (определенный в 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.
        <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>
        
        Это получатель, с которого приложение WhatsApp или WhatsApp Business начнет работу после получения сообщения с шаблоном аутентификации и прохождения всех проверок на соответствие требованиям .

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

        Использование SDK
        Мы рекомендуем использовать SDK для объявления приемника. Определите класс, который наследует BroadcastReceiver , затем определите onReceive , передав в него ваш контекст и намерение. Создайте WhatsAppOtpIncomingIntentHandler , затем запустите .processOtpCode() , который получит намерение, проверит идентификатор рукопожатия на соответствие ожидаемому значению, которое вы сохранили во время инициации рукопожатия, и обработает ошибки.
        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
        Класс широковещательного приемника должен извлекать и проверять request_id (идентификатор рукопожатия) из намерения, чтобы убедиться, что код OTP получен в результате легитимного рукопожатия, инициированного вашим приложением:
        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"); // ... } } }
        

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

        Необязательный.
        Если вы хотите, чтобы доставленное сообщение могло автоматически заполниться одним нажатием, если проверка на соответствие требованиям не пройдена, реализуйте в своем приложении этот фильтр действий и намерений, чтобы получать одноразовый пароль или код.
        Фильтр намерений должен иметь имя действия 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, если сообщение не пройдет проверку на соответствие требованиям, но при этом будет иметь право на отображение кнопки автозаполнения в одно касание.

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

        Необязательный.
        Если вы хотите, чтобы сообщение могло отображать кнопку автозаполнения в одно касание, если проверка на соответствие требованиям не пройдена, определите публичный класс Activity, который сможет принимать код после того, как пользователь нажмет кнопку. Activity должна проверять request_id ( идентификатор подтверждения связи), чтобы убедиться, что код OTP получен в результате легитимного подтверждения связи, инициированного вашим приложением.
        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
        Предпочтительный способ инициирования рукопожатия — через SDK. Для этого можно создать WhatsAppOtpHandler и передать контекст методу .sendOtpIntentToWhatsApp() . Метод возвращает UUID (идентификатор рукопожатия), который необходимо сохранить и использовать для последующей проверки входящего кода OTP.
        WhatsAppOtpHandler whatsAppOtpHandler = new WhatsAppOtpHandler(); UUID handshakeId = whatsAppOtpHandler.sendOtpIntentToWhatsApp(context); // Сохраняем handshakeId для последующей проверки полученного OTP-кода
        
        Без SDK
        В этом примере показан один из способов инициировать рукопожатие с помощью приложения WhatsApp или WhatsApp Business. Теперь рукопожатие включает в себя идентификатор запроса (UUID), который необходимо сохранить и проверить при получении кода OTP.
        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.
        Для начала необходимо добавить следующее в AndroidManifest.xml :
        
        
        <queries> <package android:name="com.whatsapp"/> <package android:name="com.whatsapp.w4b"/> </queries>
        Создайте экземпляр WhatsAppOtpHandler :
        WhatsAppOtpHandler whatAppOtpHandler = new WhatsAppOtpHandler();
        
        Проверьте, установлен ли клиент WhatsApp, передав .isWhatsAppInstalled()` в качестве условия в If :
        Если (whatsAppOtpHandler.isWhatsAppInstalled(context)) { // ... сделать что-нибудь }
        

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

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

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

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