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

WhatsApp Business API для кода проверки номера телефона

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

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

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

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

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

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

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

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

Доставка с холодным стартом без открытой сессии
Шаблоны категории аутентификации требуются для OTP вне 24-часового окна, чтобы код дошёл до нового номера, даже если пользователь никогда не писал вам в WhatsApp.
Надёжная отправка с первого раза
Одноразовый код указывается и в переменной в теле, и в параметрах кнопки копирования кода — API-запросы только с телом возвращают sent: false для аутентификационных шаблонов.
Меньше сложностей при вводе кода
Кнопка «Скопировать код» помещает цифры в буфер обмена, чтобы пользователь мог вставить их в форму вашего профиля, а не запоминать из чата.
Проверка номера перед сохранением
Ваш сервер генерирует OTP, отправляет шаблон на номер в международном формате и сохраняет новый телефон только после того, как пользователь введёт правильный код.

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

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

    Пользователь вводит новый номер телефона и запрашивает подтверждение.

    user action

  2. Создать и отправить

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

    POST /sendTemplate

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

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

    user action

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

    Серверная часть проверяет и сохраняет подтверждённый номер.

    delivered

WhatsApp Business API for phone number verification code

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

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

  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[] payload.

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 вместо этого. На практике доставка часто завершается за считанные секунды — но контракт 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.

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

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

Связанные

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

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