Шаблоны категории "Аутентификация"

Если ваше мобильное приложение предлагает пользователям возможность получать одноразовые пароли или коды подтверждения в WhatsApp, вам необходимо использовать шаблон категории "Аутентификация".

Шаблоны категории "Аутентификация" содержат:

• фиксированный предустановленный текст : Ваш код подтверждения: <VERIFICATION_CODE>;
• примечание системы безопасности (необязательно): "Из соображений безопасности никому не сообщайте этот код";
• предупреждение об истечении срока действия (необязательно): "Срок действия этого кода истекает через <NUM_MINUTES> мин.";
• кнопку автоматического заполнения, кнопку копирования кода или ни одной кнопки, если используется функция "Без нажатия".

Рекомендуется использовать кнопки автоматического заполнения, так как они обеспечивают наилучший опыт взаимодействия с приложением. Однако в настоящее время кнопки автоматического заполнения поддерживаются только в ОС Android, и вам потребуется внести дополнительные изменения в код приложения.

Информацию о том, когда следует использовать шаблоны категории "Аутентификация", см. в дополнительных инструкциях.

Шаблоны категории "Аутентификация" с кнопкой автоматического заполнения

Шаблоны категории "Аутентификация" содержат кнопку автоматического заполнения.

Когда пользователь WhatsApp нажимает эту кнопку, клиент WhatsApp запускает действие, которое открывает ваше приложение и передает ему пароль или код.

Информацию о том, как использовать эти кнопки, см. в статье Шаблоны категории "Аутентификация" с кнопкой автоматического заполнения.

Шаблоны категории "Аутентификация" с кнопкой копирования кода

Шаблоны категории "Аутентификация" с кнопкой копирования кода позволяют отправлять пользователям одноразовый пароль или код вместе с кнопкой копирования кода.

Когда пользователь WhatsApp нажимает кнопку копирования кода, клиент WhatsApp копирует пароль и код в буфер обмена устройства. Затем пользователь может перейти в ваше приложение и вставить там пароль или код.

Информацию о том, как использовать эти кнопки, см. в статье Шаблоны категории "Аутентификация" с кнопкой копирования кода.

Шаблоны категории "Аутентификация" с функцией "Без нажатия"

Шаблоны категории "Аутентификация" с функцией "Без нажатия" позволяют вашим пользователям получать одноразовые пароли или коды в WhatsApp, не выходя из вашего приложения.

Когда пользователь приложения запрашивает пароль или код, и вы отправляете его в использованием шаблона категории "Аутентификация" с функцией "Без нажатия", клиент WhatsApp транслирует этот пароль или код, а ваше приложение может получить его.

Информацию о том, как использовать эти кнопки, см. в статье Шаблоны категории "Аутентификация" с функцией "Без нажатия".

Рекомендации

• Перед отправкой одноразового пароля или кода подтвердите номер телефона пользователя WhatsApp.
• Объясните пользователю, что пароль или код будет доставлен на его номер телефона WhatsApp, особенно если вы предлагаете несколько способов получения пароля или кода. Дополнительные рекомендации см. в статье Получение согласия.
• Когда пользователь вставляет пароль или код в приложение либо приложение получает их в процессе работы кнопки автоматического заполнения, вы должны дать пользователю понять, что ваше приложение получило пароль или код.

См. также рекомендации по аутентификации пользователей через WhatsApp.

Время жизни

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

По умолчанию время жизни сообщений составляет 30 дней, однако для новых шаблонов категории Аутентификация время жизни по умолчанию составляет 10 минут.

Если нам не удастся отправить сообщение с шаблоном категории "Аутентификация" в течение времени, превышающего его время жизни, мы прекратим попытки и сбросим это сообщение. Если время с момента запроса на отправку сообщения с шаблоном категории "Аутентификация" превысило его время жизни и вы не получили Webhooks, можно сделать вывод, что сообщение было сброшено.

Чтобы переопределить время жизни по умолчанию при создании шаблона категории "Аутентификация", добавьте свойство message_send_ttl_seconds и задайте для него значение от 60 до 600 секунд.

Время жизни существующих шаблонов, созданных до появления этой функциональности, составляет 30 дней. При желании вы можете изменить существующий шаблон и переопределить его время жизни, задав для него свойство message_send_ttl_seconds.

Кроме того, для свойства message_send_ttl_seconds шаблона категории "Аутентификация" можно задать значение -1. Таким образом для него будет установлено время жизни 30 дней.

Мы рекомендуем по возможности устанавливать для всех шаблонов категории "Аутентификация" время жизни не дольше срока действия кода, чтобы клиенты получали сообщения, только если код ещё можно использовать.

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

Отправка шаблонов сообщений категории "Аутентификация"

Для отправки одобренных шаблонов сообщений категории "Аутентификация" используйте облачный или локальный API.

• Отправка шаблонов сообщений категории "Аутентификация" с помощью облачного API
• Отправка шаблонов сообщений категории "Аутентификация" с помощью локального API

Предпросмотр шаблонов

Вы можете сгенерировать предпросмотр текста шаблона категории "Аутентификация" на разных языках, который содержит или не содержит строку рекомендаций по безопасности и строку истечения срока действия кода безопасности. Используйте для этого конечную точку Аккаунт WhatsApp Business > Предпросмотр шаблона сообщений.

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

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_template_previews
  ?category=AUTHENTICATION,
  &language=<LANGUAGE>, // Optional
  &add_security_recommendation=<ADD_SECURITY_RECOMMENDATION>, // Optional
  &code_expiration_minutes=<CODE_EXPIRATION_MINUTES>, // Optional
  &button_types=<BUTTON_TYPES> // Optional

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

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

curl 'https://graph.facebook.com/v17.0/102290129340398/message_template_previews?category=AUTHENTICATION&languages=en_US,es_ES&add_security_recommendation=true&code_expiration_minutes=10&button_types=OTP' \
-H 'Authorization: Bearer EAAJB...'

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

{
  "data": [
    {
      "body": "*{{1}}* is your verification code. For your security, do not share this code.",
      "buttons": [
        {
          "autofill_text": "Autofill",
          "text": "Copy code"
        }
      ],
      "footer": "This code expires in 10 minutes.",
      "language": "en_US"
    },
    {
      "body": "Tu código de verificación es *{{1}}*. Por tu seguridad, no lo compartas.",
      "buttons": [
        {
          "autofill_text": "Autocompletar",
          "text": "Copiar código"
        }
      ],
      "footer": "Este código caduca en 10 minutos.",
      "language": "es_ES"
    }
  ]
}

Массовое управление

Для массового обновления и создания шаблонов категории "Аутентификация" на разных языках, которые содержат или не содержат дополнительные предупреждения о безопасности и сроке истечения действия, используйте конечную точку Аккаунт WhatsApp Business > Шаблоны сообщений обновления или вставки.

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

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

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

Тело публикации

{
  "name": "<NAME>",
  "languages": [<LANGUAGES>],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": <ADD_SECURITY_RECOMMENDATION> // Optional
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": <CODE_EXPIRATION_MINUTES> // Optional
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "<OTP_TYPE>",
          "package_name": "<PACKAGE_NAME>", // One-tap buttons only
          "signature_hash": "SIGNATURE_HASH>", // One-tap buttons only
        }
      ]
    }
  ]
}

Свойства

Поддерживаются все свойства создания шаблона со следующими исключениями:

• Свойство language не поддерживается. Вместо него используйте languages и укажите в качестве его значения массив строк, содержащих код языка и локаль. Пример: ["en_US","es_ES","fr"].
• Свойство text не поддерживается.
• Свойство autofill_text не поддерживается.

Пример запроса (копированием кода)

В этом примере показано создание трех шаблонов категории "Аутентификация" на английском, испанском и французском языках с кнопками копирования кода. Каждый шаблон имеет название "authentication_code_copy_code_button" и содержит рекомендацию по безопасности и время истечения срока действия.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_copy_code_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 10
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE"
        }
      ]
    }
  ]
}'

Пример запроса (кнопки автоматического заполнения)

В этом примере 1) обновляется уже существующий шаблон с именем "authentication_code_autofill_button" и языком "en_US" и 2) создаются два новых шаблона категории "Аутентификация" на испанском и французском языках с кнопками автоматического заполнения. Оба новых шаблона имеют название "authentication_code_autofill_button" и содержат рекомендацию по безопасности и время истечения срока действия.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_autofill_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 15
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "ONE_TAP",
          "package_name": "com.example.luckyshrub",
          "signature_hash": "K8a%2FAINcGX7"
        }
      ]
    }
  ]
}'

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

{
  "data": [
    {
      "id": "954638012257287",
      "status": "APPROVED",
      "language": "en_US"
    },
    {
      "id": "969725527415202",
      "status": "APPROVED",
      "language": "es_ES"
    },
    {
      "id": "969725530748535",
      "status": "APPROVED",
      "language": "fr"
    }
  ]
}

Пример приложения

См. наш пример приложения с одноразовым паролем (OTP) в WhatsApp для Android на Github. В примере приложения показано, как отправлять и получать одноразовые пароли и коды через API, интегрировать автоматическое заполнение одним нажатием и кнопки копирования кода, создавать шаблоны, а также запускать сервер.

Статьи по теме

• Официальный бизнес-аккаунт: вы можете запросить официальный статус аккаунта, чтобы повысить доверие пользователей и снизить вероятность того, что они отклонят или проигнорируют ваши сообщения.
• Webhooks для отчетов о прочтении: рекомендуем подписаться на поля Webhooks сообщений, чтобы получать уведомления, когда пользователь получает и читает ваш шаблон категории "Аутентификация" с кнопкой одноразового пароля. Подробности см. в статьях о Webhooks для облачного и локального API.