1msg official logo

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

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

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

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

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

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

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

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

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

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

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

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

    Пользователь отправляет данные для регистрации в приложении и запрашивает подтверждение.

    user action

  2. Захват события

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

    phone: "+…"

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

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

    POST /sendTemplate

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

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

    delivered

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

    Бэкенд проверяет отправленный код и активирует аккаунт; ошибки доставки обрабатываются по правилам платформы.

    status: "read"

WhatsApp Business API for app registration 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 будет отправлять POST-запросы со статусами на ваш 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.

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

Да — для холодного запуска WhatsApp-сообщений требуется одобренный Meta шаблон.

Связанные

Подтверждение OTP
WhatsApp Business API для уведомления о рассмотрении ekyc
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, когда их eKYC или проверка личности на рассмотрении.
Подтверждение OTP
WhatsApp Business API для уведомления о необходимом действии kyc
Сценарий отправляет клиенту персонализированный WhatsApp шаблон, когда проверка KYC или соответствия выявляет необходимость действия с дедлайном.
Подтверждение OTP
WhatsApp Business API для запроса проверки
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, когда требуется проверка личности или KYC, но она ещё не началась.
Подтверждение OTP
WhatsApp Business API для безопасного логина через одноразовый пароль
Сценарий отправляет шаблон аутентификации WhatsApp с одноразовым кодом подтверждения, когда нужно подтвердить вход в защищённый или безопасный сервис.
Подтверждение OTP
WhatsApp Business API для миграции sms на whatsapp otp
Отправляет одноразовый код подтверждения через шаблон аутентификации WhatsApp при переключении доставки OTP с SMS на WhatsApp.
Подтверждение OTP
WhatsApp Business API для безопасного подтверждения действий OTP
Сценарий отправляет шаблон аутентификации WhatsApp с одноразовым кодом, когда требуется подтвердить безопасное действие.
Подтверждение OTP
WhatsApp Business API для подтверждения доступа к сервису
Отправляет одноразовый код подтверждения через шаблон аутентификации WhatsApp, когда нужно подтвердить личность перед использованием защищённого сервиса.
Подтверждение OTP
WhatsApp Business API для подтверждения авторизации через otp
Отправляет одноразовый код через шаблон подтверждения WhatsApp, когда пользователю нужно подтвердить вход или доступ.

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