💬 Командный WhatsApp-Инбокс на новой ПлатформеЕщё
1msg official logo

WhatsApp Business API для подтверждения нового входа

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

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

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

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

{{1}} Это ваш код подтверждения. Не делитесь им ни с кем.

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

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

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

Подтверждайте входы без чата
Утверждённый шаблон аутентификации открывает разговор при холодном старте, поэтому код подтверждения для входа приходит пользователю при попытке войти с нового устройства, браузера или местоположения, вместо ожидания в 24-часовом окне ответа.
Быстрый ввод кода на мобильном устройстве
Цифры поступают в виде одной переменной в теле, и это же значение используется в параметре кнопки «Копировать код». Так пользователь нажимает «Копировать код» и вставляет его на ваш экран проверки вместо того, чтобы перепечатывать из другого канала.
Безопасность там, где пользователи уже есть
Когда номер телефона аккаунта хранится в международном формате, сервер отправляет одноразовый код подтверждения через WhatsApp, поэтому проверка при входе поступает в канал, который пользователи уже просматривают, а не в отфильтрованный SMS-инбокс.
Отправка выполняется с первой попытки
В шаблонах аутентификации необходимо указать OTP как в теле сообщения, так и в полезной нагрузке кнопки копирования кода; указание обоих элементов предотвращает отправку только тела сообщения, которая возвращает `sent: false`.

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

  1. Триггер

    Пользователь входит в ваше приложение или портал с нового устройства, браузера или из нового местоположения.

    event · triggered

  2. Определяет новый вход в систему

    Ваш бэкенд обнаруживает новый контекст входа и создаёт одноразовый код подтверждения.

    event · triggered

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

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

    POST /sendTemplate

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

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

    delivered

  5. Статус отслеживается

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

    status: "read"

WhatsApp Business API for new login confirmation

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

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

  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

    Сопоставляет callback с id, возвращённым вызовом send

  • timestamp

    Unix-время в строковом формате

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

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