Скилл WhatsApp API для ИИ агентаЕщё
1msg official logo

WhatsApp Business API для подтверждения OTP

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

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

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

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

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

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

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

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

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

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

  1. Триггер

    Пользователь начинает вход, регистрацию или дополнительную проверку в вашем приложении или портале.

    event · triggered

  2. Событие захвата

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

    phone: "+…"

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

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

    POST /sendTemplate

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

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

    delivered

  5. Отслеживаемый статус

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

    status: "read"

WhatsApp Business API for otp verification

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

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

  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 в строковом формате

Если вы предпочитаете не получать обратные вызовы, 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 за часы
без проблем с инфраструктурой