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

WhatsApp Business API для регистрации OTP

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

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

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

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

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

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

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

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

WhatsApp вместо SMS для OTP
Сервер генерирует одноразовый регистрационный код и отправляет его через утверждённый шаблон аутентификации с помощью API 1MSG, так что проверка выполняется в WhatsApp, а не через отдельный SMS-канал при регистрации.
Доставка, соответствующая cold-start
Только утверждённый шаблон аутентификации позволяет открыть чат при первом контакте — это правило канала для связи с пользователем, который никогда раньше не писал вашему бизнесу.
Быстрый ввод кода
Одна переменная в теле содержит числовой код, а кнопка копирования кода отображает это же значение, чтобы пользователь вставил его в вашу форму регистрации, вместо того чтобы вводить по памяти.
Меньше скрытых неудач отправки
Шаблоны аутентификации требуют OTP как в параметрах тела, так и в параметрах кнопки для копирования кода; если в нагрузке есть только тело, возвращается `sent: false`, и в этом случае для обоих параметров используется одно и то же значение из бэкенда.

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

  1. Зафиксировать событие

    Пользователь начинает регистрацию и запрашивает проверку телефона.

    phone: "+…"

  2. Генерация одноразового кода

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

    phone: "+…"

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

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

    POST /sendTemplate

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

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

    delivered

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

    Сервер проверяет код и завершает регистрацию.

    status: "read"

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

    Храните это — на этом основываются callbacks доставки и 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 за часы
без проблем с инфраструктурой