1msg official logo

WhatsApp Business API для безопасного логина через одноразовый пароль

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

Обзор сценария

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

Пример шаблона

{{1}} — это ваш код подтверждения. Для безопасности не делитесь этим кодом с кем-либо.

Скопировать код
  • {{1}}
    одноразовый безопасный код для входа в сервис (цифры)
  • “Скопировать код”
    кнопка — исправлено в шаблоне Meta
WhatsApp Business API for secure service login otp

Когда использовать

Используйте этот сценарий, когда пользователь входит в защищённый сервис — банковский портал, админ-консоль, VPN-шлюз или внутренний инструмент — и требуется одноразовый код в WhatsApp перед началом сессии. Обычно открытого чата ещё нет, поэтому сообщение в свободной форме не разрешается при холодном старте. Это подходит для сценариев входа IAM и финтех, повышения защиты перед привилегированными порталами, а также для команд, подключающих аутентификацию защищённых сервисов в веб-приложения, мобильные приложения или бекенды через API 1MSG.

Проверьте учётные данные перед открытием защищённого сеанса
Бэкенд генерирует краткосрочный код, когда пользователь начинает вход в защищённый сервис, и отправляет его в одной переменной в теле через шаблон аутентификации; он остаётся связан с попыткой входа до завершения проверки.
Быстрый ввод кода на экране входа
Кнопка копирования кода содержит тот же одноразовый пароль, что и текст сообщения, поэтому пользователь может вставить его в вашу защищённую форму входа, а не перепечатывать из чата.
Соответствующая доставка при холодном старте
Шаблоны категории аутентификации доставляют OTP, даже если сеанс поддержки не открыт, поэтому подтверждение безопасного входа в сервис работает с холодного старта без необходимости сначала запускать активную переписку.
Меньше отклонённых отправок через API
В шаблонах аутентификации требуется OTP как в теле сообщения, так и в кнопке копирования кода; это предотвращает запросы только с телом, которые возвращают `sent: false`.

Как это работает

  1. Триггер

    Пользователь начинает вход в защищённый или безопасный сервис в вашем приложении или портале.

    event · triggered

  2. Захватить событие

    Ваш бэкенд генерирует одноразовый проверочный код и определяет номер пользователя в WhatsApp.

    phone: "+…"

  3. Собрать и отправить

    Шаблон сообщения создаётся с кодом в теле и таким же значением в параметре кнопки «Копировать код».

    POST /sendTemplate

  4. Доставлено

    Пользователь получает сообщение в WhatsApp и копирует код или читает его.

    delivered

  5. Отслеживание статуса

    Ваш серверный компонент проверяет предоставленный код и предоставляет или отказывает в безопасном доступе к сервису; ошибки доставки обрабатываются по правилам платформы.

    status: "read"

WhatsApp Business API for secure service login otp

Техническая реализация

Предварительные условия

  1. Ключ API 1MSG · Как получить ключ API
  2. Аккаунт WhatsApp Business · Как подключить WABA
  3. Шаблон WhatsApp · Как утвердить шаблон WABA
  4. Согласие клиента на получение сообщений · Как управлять согласием клиентов

Примеры кода

#!/usr/bin/env bash
set -euo pipefail

# === Configuration (replace "___" placeholders) ===

API_BASE_URL="https://api.1msg.io"        # production 1MSG API base URL
CHANNEL_ID="___"                           # channel ID from 1MSG dashboard
API_TOKEN="___"                            # channel JWT token (Bearer)

TEMPLATE_NAME="___"                        # approved template name
TEMPLATE_NAMESPACE="___"                   # template namespace (required — send fails without it)
TEMPLATE_LANGUAGE="___"                    # template language code, e.g. "en"



# === Test data ===
TEST_PHONE="___"                 # client phone in international format
TEST_CODE="___"         # {{1}} otp code

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"

for pair in "CHANNEL_ID=$CHANNEL_ID" "API_TOKEN=$API_TOKEN" \
            "TEMPLATE_NAME=$TEMPLATE_NAME" "TEMPLATE_NAMESPACE=$TEMPLATE_NAMESPACE" \
            "TEMPLATE_LANGUAGE=$TEMPLATE_LANGUAGE" "TEST_PHONE=$TEST_PHONE" \
            "TEST_CODE=$TEST_CODE"; do
    val="${pair#*=}"
    if [ -z "$val" ] || [ "$val" = "___" ]; then
        echo "Missing configuration value: ${pair%%=*}" >&2
        exit 1
    fi
done

if [ -z "$PHONE_NORM" ]; then
    echo "Error: phone number has no digits after normalization" >&2
    exit 1
fi

URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendTemplate"

# params carries body and button blocks.

# {{1}} otp code → ${TEST_CODE}
read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "template": "${TEMPLATE_NAME}",
  "namespace": "${TEMPLATE_NAMESPACE}",
  "language": { "policy": "deterministic", "code": "${TEMPLATE_LANGUAGE}" },
  "params": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "${TEST_CODE}" }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": "0",
      "parameters": [ { "type": "text", "text": "${TEST_CODE}" } ]
    }

  ]
}
JSON

RESPONSE="$(curl -s -w '\n%{http_code}' -X POST "$URL" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${API_TOKEN}" \
    -d "$PAYLOAD")"

HTTP_CODE="$(printf '%s' "$RESPONSE" | tail -n1)"
BODY="$(printf '%s' "$RESPONSE" | sed '$d')"

case "$BODY" in
    *'"sent":true'*) ok=1 ;;
    *) ok=0 ;;
esac

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ] && [ "$ok" -eq 1 ]; then
    echo "Message sent to client."
    echo "API response: $BODY"
else
    echo "Send failed. HTTP status: $HTTP_CODE" >&2
    echo "$BODY" >&2
    exit 1
fi

Статус ответа и доставки

HTTP 2xx и JSON "sent": true означают, что 1MSG приняла сообщение для отправки, но не то, что оно уже достигло телефона клиента. Сохраните id поле (выглядит как wamid.…), чтобы сопоставить обратные вызовы о доставке.

200 OKОтвет
{
  "sent": true,
  "id": "wamid.HBgLMzgwNjM5...",
  "message": "Message accepted for delivery"
}
  • sent

    Принято для отправки — ещё не поступило на телефон клиента

  • id

    Сохраните это — обратные вызовы доставки и hookInfo используют его в качестве ключа

Сама доставка приходит позже, в виде отдельного обратного вызова. Зарегистрируйте вебхук (POST …/webhook), и 1MSG отправит обновления статуса на ваш HTTPS-эндпоинт в корневом hooks[] сообщении.

200 OKВебхук статуса доставки — данные, которые вы получаете
{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}
  • status

    sent, delivered, read — или статус ошибки, если это уместно

  • id

    Соотносит обратный вызов с id, возвращённым вызовом send

  • timestamp

    Секунды Unix в виде строки

Если вы предпочитаете не получать callbacks, вместо этого используйте опрос. GET {base}/{channel}/hookInfo?messageId=<id>На практике доставка часто завершается в течение нескольких секунд — но контракт API этого не гарантирует, поэтому никогда не блокируйте поток в его ожидании.

Распространённые ошибки

СтатусОтветПричина
200Message was not sent: template is not definednamespace, template or language missing from the request body.
200template name (…) does not exist in <language>The template is approved in a different language than the one requested.
200Message was not sent: provide chatId, phone, bsuid, or usernameNo recipient the channel could resolve.
403access deniedThe token is wrong, or belongs to a different channel than the URL.
429too many requests. please try laterThe channel is over its send rate.

ЧАСТО ЗАДАВАЕМЫЕ ВОПРОСЫ

Да, для холодных WhatsApp-сообщений нужен одобренный Meta шаблон.

Связанные

Подтверждение OTP
WhatsApp Business API для уведомления о рассмотрении ekyc
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, когда их eKYC или проверка личности на рассмотрении.
Подтверждение OTP
WhatsApp Business API для уведомления о необходимом действии kyc
Сценарий отправляет клиенту персонализированный WhatsApp шаблон, когда проверка KYC или соответствия выявляет необходимость действия с дедлайном.
Подтверждение OTP
WhatsApp Business API для запроса проверки
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, когда требуется проверка личности или KYC, но она ещё не началась.
Подтверждение OTP
WhatsApp Business API для подтверждения регистрации приложения
Отправляет в WhatsApp шаблон аутентификации с одноразовым кодом подтверждения регистрации в теле сообщения и кнопкой «Копировать код».
Подтверждение OTP
WhatsApp Business API для миграции sms на whatsapp otp
Отправляет одноразовый код подтверждения через шаблон аутентификации WhatsApp при переключении доставки OTP с SMS на WhatsApp.
Подтверждение OTP
WhatsApp Business API для безопасного подтверждения действий OTP
Сценарий отправляет шаблон аутентификации WhatsApp с одноразовым кодом, когда требуется подтвердить безопасное действие.
Подтверждение OTP
WhatsApp Business API для подтверждения доступа к сервису
Отправляет одноразовый код подтверждения через шаблон аутентификации WhatsApp, когда нужно подтвердить личность перед использованием защищённого сервиса.
Подтверждение OTP
WhatsApp Business API для подтверждения авторизации через otp
Отправляет одноразовый код через шаблон подтверждения WhatsApp, когда пользователю нужно подтвердить вход или доступ.

Интегрируйте WhatsApp за часы
без проблем с инфраструктурой