1msg official logo

WhatsApp Business API для миграции sms на whatsapp otp

Отправляет одноразовый код подтверждения через шаблон аутентификации WhatsApp при переключении доставки OTP с SMS на WhatsApp.

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

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

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

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

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

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

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

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

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

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

    Пользователь запускает проверку в процессе, который ранее отправлял SMS с OTP.

    POST /sendTemplate

  2. Создать код

    Сервер создаёт код и отправляет шаблон аутентификации через WhatsApp.

    POST /sendTemplate

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

    Пользователь копирует код из WhatsApp и отправляет его в вашем приложении.

    user action

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

    Бэкенд проверяет код и выполняет тот же шаг, что и в старом варианте с SMS.

    delivered

WhatsApp Business API for sms to whatsapp otp migration

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

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

  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_OTPCODE="___"         # {{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_OTPCODE=$TEST_OTPCODE"; 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_OTPCODE}
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_OTPCODE}" }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": "0",
      "parameters": [ { "type": "text", "text": "${TEST_OTPCODE}" } ]
    }

  ]
}
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 and JSON "sent": true mean 1MSG accepted the message for sending — not that it already reached the customer's phone. Save the id field (looks like wamid.…) to correlate delivery callbacks.

200 OKОтвет
{
  "sent": true,
  "id": "wamid.HBgLMzgwNjM5...",
  "message": "Message accepted for delivery"
}
  • sent

    Принято для отправки — ещё не на телефоне клиента

  • id

    Сохраните это; hookInfo используйте для обратных вызовов при доставке как ключ

Доставка приходит позже как отдельный обратный вызов. Зарегистрируйте вебхук (POST …/webhook), и 1MSG будет отправлять обновления статуса на ваш HTTPS-endpoint в основной hooks[] полезной нагрузке.

200 OKВебхук статуса доставки — данные, которые вы получаете
{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}
  • status

    sent, delivered, read — или статус сбоя, если применимо

  • id

    Соотносит обратный вызов с id, возвращаемым вызовом функции отправки

  • timestamp

    Unix-время в виде строки

If you would rather not receive callbacks, poll GET {base}/{channel}/hookInfo?messageId=<id> instead. In practice delivery often completes within seconds — but the API contract does not guarantee it, so never block a flow waiting on it.

Распространённые ошибки

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

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