Скилл WhatsApp API для ИИ агентаЕщё
1msg official logo

WhatsApp Business API для запроса проверки

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

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

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

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

Здравствуйте, {{1}}! Чтобы продолжить, пройдите {{2}}. {{3}} проверку, нажав кнопку ниже. Если у вас есть вопросы, мы вам поможем.

Начать верификацию
  • {{1}}
    имя клиента
  • {{2}}
    процесс верификации (например, подтверждение личности, KYC-проверка, проверка документов)
  • {{3}}
    следующие действия (например, загрузить удостоверение личности и сделать селфи в портале до пятницы)
  • “Начать верификацию”
    кнопка — исправлена в шаблоне Meta
WhatsApp Business API for verification request

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

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

Проверка начинается до того, как лимиты или выплаты заблокируют клиента
Три переменные в теле содержат имя клиента, название процесса верификации и инструкцию по следующему шагу, чтобы запрос объяснял, зачем нужна верификация, вместо общей рассылки о соответствии требованиям.
Одним касанием в портал проверки
Статическая кнопка URL с надписью «Начать проверку» открывает портал или процесс загрузки документа — ссылка фиксирована в утверждённом шаблоне Meta, а по API отправляется только текст.
Связываться с клиентами вне 24-часового окна
Так как активного чата нет, отправка происходит с использованием согласованного шаблона WhatsApp через 1MSG API — это единственный канал, который может инициировать верификацию, когда первым не написал клиент.
Нет необходимости вручную отслеживать контрольные точки
Когда срабатывает триггер, требующий проверки, например, регистрация, проверка соответствия или разблокировка функции, система определяет номер телефона и отправляет шаблон на это событие вместо того, чтобы кто-то копировал данные вручную.
Доставка зарегистрирована для соблюдения требований
Результат доставки фиксируется после отправки, чтобы команды CRM или по комплаенсу могли видеть, кого попросили верифицировать, и обрабатывать ошибки в соответствии с правилами платформы.

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

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

    Бизнес-правило или шаг онбординга требует от клиента пройти идентификацию или проверку KYC.

    user action

  2. Событие захвата

    Система обнаруживает событие, требующее проверки, и определяет номер телефона получателя.

    phone: "+…"

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

    Персонализированное сообщение-шаблон создаётся с тремя переменными в теле и статической кнопкой URL.

    POST /sendTemplate

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

    Клиент получает запрос на подтверждение в WhatsApp с описанием процесса и инструкциями по следующим шагам.

    delivered

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

    Результат доставки записывается в журнал; клиент может начать проверку по ссылке на портал.

    status: "read"

WhatsApp Business API for verification request

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

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

  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_CUSTOMERNAME="___"         # {{1}} customer name
TEST_PROCESS="___"         # {{2}} process name
TEST_NEXTSTEP="___"         # {{3}} next step

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_CUSTOMERNAME=$TEST_CUSTOMERNAME" \
            "TEST_PROCESS=$TEST_PROCESS" \
            "TEST_NEXTSTEP=$TEST_NEXTSTEP"; 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 ONLY. Button text is fixed in the Meta template — no button param.

# {{1}} customer name → ${TEST_CUSTOMERNAME}
# {{2}} process name → ${TEST_PROCESS}
# {{3}} next step → ${TEST_NEXTSTEP}
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_CUSTOMERNAME}" },
        { "type": "text", "text": "${TEST_PROCESS}" },
        { "type": "text", "text": "${TEST_NEXTSTEP}" }
      ]
    }

  ]
}
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[] полезной нагрузке.

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

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