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

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

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

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

    Ограничения

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

    Создание шаблонов аутентификации

    Для создания шаблонов аутентификации используйте «Аккаунт WhatsApp Business» > «Шаблоны сообщений»

    Синтаксис запроса

    curl 'https://graph.facebook.com/ v25.0 / /message_templates' \ - H 'Content-Type: application/json' \ - H 'Authorization: Bearer EAAJB...' \ - d '{ "name": " ", "язык": " ", "category": "authentication", "message_send_ttl_seconds": , // Необязательные "компоненты": [ { "type": "body", "add_security_recommendation": // Необязательно }, { "type": "footer", "code_expiration_minutes": // Необязательно }, { "type": "buttons", "buttons": [ { "type": "otp", "otp_type": "one_tap", "text": " ", // Необязательный параметр "autofill_text": " ", // Необязательно "supported_apps": [ { "package_name": " ", "signature_hash": " " } ] } ] } ] }'
    Обратите внимание, что в запросе на создание шаблона тип кнопки указан как otp , но при создании шаблона тип кнопки будет установлен на url . Вы можете подтвердить это, выполнив GET-запрос к только что созданному шаблону аутентификации и проанализировав его компоненты.

    Параметры запроса

    Заполнитель Описание Пример значения
    <AUTOFILL_BUTTON_TEXT>
    Нить
    Необязательный.
    Текст надписи кнопки автозаполнения одним касанием.
    Если этот параметр опущен, текст автозаполнения будет по умолчанию использовать предустановленное значение, локализованное для языка шаблона. Например, « Автозаполнение для английского языка (США)».
    Максимум 25 символов.
    Автозаполнение
    <CODE_EXPIRATION>
    Целое число
    Необязательный.
    Указывает количество минут, в течение которых пароль или код действителен.
    Если код включен, в отправленном сообщении будет отображено предупреждение об истечении срока его действия и это значение. Кнопка будет отключена в отправленном сообщении через указанное количество минут после отправки сообщения.
    Если этот параметр отсутствует, предупреждение об истечении срока действия кода не будет отображаться в отправленном сообщении. Кроме того, кнопка будет отключена через 10 минут после отправки сообщения.
    Минимум 1, максимум 90.
    5
    <COPY_CODE_BUTTON_TEXT>
    Нить
    Необязательный.
    Скопировать текст надписи кнопки с кодом.
    Если этот параметр опущен, текст по умолчанию будет содержать предустановленное значение, локализованное для языка шаблона. Например, «Код для английского языка (США)».
    Если сообщение шаблона аутентификации включено, в случае неудачной проверки соответствия требованиям .
    Максимум 25 символов.
    Скопировать код
    <PACKAGE_NAME>
    Нить
    Необходимый.
    Имя пакета вашего Android-приложения.
    Строка должна состоять как минимум из двух сегментов (одной или более точек), и каждый сегмент должен начинаться с буквы.
    Все символы должны быть буквенно-цифровыми или представлять собой символ подчеркивания [ a-zA-Z0-9_ ].
    При использовании Graph API версии 20.0 или более ранней вы можете указать имя пакета вашего приложения вне supported_apps , но это не рекомендуется. См. раздел «Поддерживаемые приложения» ниже.
    Максимальное количество символов: 224.
    com.example.luckyshrub
    <SECURITY_RECOMMENDATION>
    Логический
    Необязательный.
    Установите значение true если хотите, чтобы шаблон включал эту строку . В целях безопасности не делитесь этим кодом. Установите значение false , чтобы исключить эту строку.
    истинный
    <SIGNATURE_HASH>
    Нить
    Необходимый.
    Хэш ключа подписи вашего приложения. См. Хэш ключа подписи приложения ниже.
    Все символы должны быть буквенно-цифровыми, + , / или = ( a-zA-Z0-9+/= ).
    При использовании Graph API версии 20.0 или более ранней вы можете определить хэш подписи вашего приложения вне массива supported_apps , но это не рекомендуется. См. раздел «Поддерживаемые приложения» ниже.
    Должно быть ровно 11 символов.
    K8a/AINcGX7
    <TEMPLATE_LANGUAGE>
    Нить
    Необходимый.
    шаблона и код локали .
    en_US
    <TEMPLATE_NAME>
    Нить
    Необходимый.
    Название шаблона.
    Максимальное количество символов: 512.
    проверочный код
    <TIME_TO_LIVE>
    Целое число
    Необязательный.
    Значение времени жизни аутентификационного сообщения в секундах. См. раздел « Настройка времени жизни» .
    60

    Пример запроса

    В этом примере создается шаблон с именем «authentication_code_autofill_button», относящийся к категории аутентификации , с возможностью ввода всех необязательных текстовых строк и кнопкой автозаполнения в одно касание.
    curl 'https://graph.facebook.com/ v25.0 /102290129340398/message_templates' \ - H 'Content-Type: application/json' \ - H 'Authorization: Bearer EAAJB...' \ - d ' { "name": "authentication_code_autofill_button", "language": "en_US", "category": "authentication", "message_send_ttl_seconds": 60, "components": [ { "type": "body", "add_security_recommendation": true }, { "type": "footer", "code_expiration_minutes": 10 }, { "type": "buttons", "buttons": [ { "type": "otp", "otp_type": "one_tap", "text": "Copy Code", "autofill_text": "Автозаполнение", "package_name": "com.example.luckyshrub", "signature_hash": "K8a/AINcGX7" } ] } ] }'

    Пример ответа

    {
    "id"
    : "594425479261596" , "status"
    : "PENDING" , "category"
    : "AUTHENTICATION" }

    Вебхуки

    Веб -перехватчик для сообщений, отправляемых с помощью кнопок, срабатывает всякий раз, когда пользователь нажимает кнопку «Я не запрашивал код» в сообщении.

    Пример веб-перехватчика

    {
    "object": "whatsapp_business_account",
    "entry": [
    {
    "id": "320580347795883",
    "changes": [
    {
    "value": {
    "messaging_product": "whatsapp",
    "metadata": {
    "display_phone_number": "12345678",
    "phone_number_id": "1234567890"
    },
    "contacts": [
    {
    "profile": {
    "name": "John"
    },
    "wa_id": "12345678"
    }
    ],
    "messages": [
    {
    "context": {
    "from": "12345678",
    "id": "wamid.HBgLMTIxMTU1NTE0NTY
    VAgARGBJDMDEyMTFDNTE5NkFCOUU3QTEA" },
    "from": "12345678",
    "id": "wamid.HBgLMTIxMTU1NTE0NTYVA
    gASGCBBQ0I3MjdCNUUzMTE0QjhFQkM4RkQ4MEU3QkE0MUNEMgA =", "timestamp": "1753919111",
    "from_logical_id": "13106310813302
    0", "type": "button",
    "button": {
    "payload": "DID_NOT_REQUEST_CODE
    ", "text": "Я не запрашивал код
    " }
    }
    ]
    },
    "field": "messages"
    }
    ]
    }
    ]
    }

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

    В текст сообщения необходимо включить хэш ключа подписи вашего приложения.
    Чтобы вычислить хеш, следуйте инструкциям Google по - строки вашего приложения .
    В качестве альтернативы, если вы будете следовать инструкциям Google и загрузите сертификат ключа подписи вашего приложения (шаг 1), вы сможете использовать свой сертификат со оболочки sms_retriever_hash_v9.sh для вычисления хеша. Например:
    . /sms_retriever_hash_v9.sh --package "com.example.myapplication" --keystore ~/ . android / debug . keystore

    Поддерживаемые приложения

    Массив supported_apps позволяет задавать пары имен пакетов приложений и хешей ключей подписи для до 5 приложений. Это может быть полезно, если у вас есть разные сборки приложений, и вы хотите, чтобы каждая из них могла инициировать рукопожатие:
    "кнопки"
    : [ {
    "тип"
    : "otp" , ...
    "поддерживаемые_приложения"
    : [ {
    "имя_пакета"
    : " " , "signature_hash"
    : " " },
    {
    "package_name"
    : " " , "signature_hash"
    : " " },
    ...
    ]
    }
    ]
    В качестве альтернативы, если вы используете Graph API версии 20.0 или более старой и у вас только одно приложение, вы можете определить имя пакета приложения и хэш ключа подписи в качестве buttons , но это не рекомендуется, поскольку мы прекратим поддержку этого метода начиная с версии 21.0:
    "кнопки"
    : [ {
    "тип"
    : "otp" , ...
    "имя_пакета"
    : " " , "signature_hash"
    : " " }
    ]

    Рукопожатие

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

        Отправка шаблона аутентификации

        В этом документе объясняется, как отправлять утвержденные шаблоны аутентификации с кнопками для ввода одноразовых паролей .
        Обратите внимание, что сначала необходимо инициировать процедуру установления соединения между вашим приложением и клиентом WhatsApp. См. раздел «Установление соединения» выше.

        Запрос

        Синтаксис запроса

        curl -X POST
        "https://graph.facebook.com/v23.0/ SS_PHONE_NUMBER_ID>/messages" \ -H
        "Авторизация: Bearer " \ -H
        "Content-Type: application/json" \ -d '{
        "messaging_product"
        : "whatsapp" , "recipient_type"
        : "individual" , "to"
        : " " , "type"
        : "template" , "template"
        : { "name"
        : " " , "language"
        : { "code"
        : " " },
        "components"
        : [ {
        "type"
        : "body" , "parameters"
        : [ {
        "type"
        : "text" , "text"
        : " " }
        ]
        },
        {
        "type"
        : "button" , "sub_type"
        : "url" , "index"
        : 0 , "parameters"
        : [ {
        "type"
        : "text" , "text"
        : " " }
        ]
        }
        ]
        }
        }'

        Параметры запроса

        Заполнитель Описание Пример значения
        <CUSTOMER_PHONE_NUMBER>
        Номер телефона клиента в WhatsApp.
        12015553931
        <ONE-TIME PASSWORD>
        Одноразовый пароль или проверочный код, который будет выдан клиенту.

        Обратите внимание, что это значение должно встречаться в полезной нагрузке дважды.

        Максимум 15 символов.
        J$FpnYnP
        <TEMPLATE_LANGUAGE_CODE>
        en_US
        <TEMPLATE_NAME>
        Название шаблона.
        проверочный код

        Ответ

        В случае успеха API ответит следующим образом:
        {
        "messaging_product"
        : "whatsapp" , "contacts"
        : [ {
        "input"
        : " " , "wa_id"
        : " " }
        ],
        "messages"
        : [ {
        "id"
        : " " }
        ]
        }

        Параметры отклика

        Заполнитель Описание Пример значения
        <INPUT>
        Нить
        Номер телефона клиента, на который было отправлено сообщение. Он может не совпадать с wa_id .
        +16315551234
        <WA_ID>
        Нить
        Идентификатор WhatsApp клиента, которому было отправлено сообщение. Он может не совпадать с введенными данными .
        +16315551234
        <ID>
        Нить
        Идентификатор сообщения WhatsApp. Вы можете использовать идентификатор, указанный после «wamid.», чтобы отслеживать статус вашего сообщения.
        wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI3N0EyQUJDMjFEQzZCQUMzODMA

        Пример запроса

        curl - L 'https://graph.facebook.com/ v25.0 /105954558954427/messages' \ - H 'Content-Type: application/json' \ - H 'Authorization: Bearer EAAJB...' \ - d '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "12015553931", "type": "template", "template": { "name": "verification_code", "language": { "code": "en_US" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "J$FpnYnP" } ] }, { "type": "button", "sub_type": "url", "index": "0", "parameters": [ { "type": "text", "текст": "J$FpnYnP" } ] } ] } }'

        Пример ответа

        {
        "messaging_product"
        : "whatsapp" , "contacts"
        : [ {
        "input"
        : "12015553931" , "wa_id"
        : "12015553931" }
        ],
        "messages"
        : [ {
        "id"
        : "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI4Qzc5QkNGNTc5NTM yMDU5QzEA" }
        ]
        }