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

WhatsApp Business API для сброса пароля с OTP-кодом

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

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

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

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

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

Копировать код
  • {{1}}
    код восстановления одноразового пароля (цифры)
  • “Копировать код”
    кнопка — исправлено в шаблоне Meta
WhatsApp Business API for password reset otp

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

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

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

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

  1. Действия клиента

    Пользователь запрашивает сброс пароля и вводит свой номер телефона.

    user action

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

    Сервер генерирует код восстановления и отправляет шаблон.

    POST /sendTemplate

  3. Копировать код

    Пользователь копирует код из WhatsApp и отправляет.

    user action

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

    Бекенд проверяет и разблокирует этап сброса пароля.

    delivered

WhatsApp Business API for password reset 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

    Соотносит callback с idвозвращаемым вызовом send call

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

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