1msg official logo

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

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

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

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

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

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

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

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

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

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

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

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

    Пользователь запрашивает доступ к сервису или защищённой функции и вводит свой телефон.

    user action

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

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

    POST /sendTemplate

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

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

    user action

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

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

    delivered

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

    Store it; delivery callbacks and hookInfo are keyed on this

Доставка приходит позднее, отдельным обратным вызовом. Зарегистрируйте 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

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

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