Отправка WABA-шаблонов и OTP через API

    3 мин чтения
    ·
    362 просмотра
    ·
    Обновлено 17.11.2026

    🚀 Что нового

    Теперь публичный API WazzaBee поддерживает отправку согласованных шаблонов WhatsApp (HSM). Это открывает возможность для автоматизации рассылок и, что особенно важно, отправки OTP-кодов (AUTHENTICATION) прямо из вашего приложения или CRM.

    🛠️ Метод API

    POST /v1/messages/send

    Эндпоинт для отправки сообщений был расширен. Чтобы отправить шаблон, вам необходимо вместо стандартных параметров (text или mediaUrl) передать параметр templateName с сопутствующими данными.

    📋 Параметры тела запроса (JSON)

    Параметр Тип Описание
    channelId строка (обязательно) ID вашего подключенного WABA-канала.
    chatId строка (обязательно) Номер телефона получателя (с кодом страны, без "+").
    templateName строка (обязательно) Системное имя согласованного шаблона в Meta (например, auth_code_123).
    templateLanguage строка (опционально) Код языка шаблона (например, "ru", "en"). По умолчанию: "ru".
    templateVariables объект (опционально) Переменные для подстановки в текст. В WhatsApp они нумеруются как {{1}}, {{2}}. Пример: {"1": "Значение 1"}.
    templateHeader объект (опционально) Медиа-заголовок шаблона (картинка, видео, документ). Пример: {"type": "image", "link": "https://..."}.

    📱 Пример: Отправка OTP-кода (AUTHENTICATION)

    Шаблон аутентификации содержит одну переменную, сам код, и кнопку копирования кода COPY_CODE. Передайте код в templateVariables под номером "1", а в кнопку тот же код API подставит сам. Если кода в запросе нет, сообщение не уйдёт, а в его статусе будет ошибка с подсказкой.

    ⚠️ Важно: Убедитесь, что ваш шаблон в Meta согласован именно в категории AUTHENTICATION и настроен на принятие кода.

    {
      "channelId": "ВАШ_CHANNEL_ID",
      "chatId": "77771234567",
      "templateName": "my_otp_template",
      "templateLanguage": "ru",
      "templateVariables": {
        "1": "456789"
      }
    }

    ⚙️ Как это работает под капотом

    1. Запрос: Вы отправляете JSON на POST /v1/messages/send.
    2. Очередь: Система проверяет доступы и ставит сообщение во внутреннюю очередь (вы моментально получаете ответ HTTP 202).
    3. Отправка: Система собирает сообщение по правилам WhatsApp, для шаблона с кодом добавляет кнопку копирования и отправляет шаблон в WhatsApp.
    4. Статусы: Уведомления о доставке и прочтении приходят вам через настроенные Webhook.

    🔘 Кнопки шаблона: templateButtons

    Параметр templateButtons (массив, опционально) передаёт значения в кнопки шаблона. Подходит для двух случаев:

    • URL-кнопка с переменной (ссылка вида https://site.kz/check/{{1}}): в value передайте хвост ссылки.
    • Кнопка быстрого ответа: в value передайте свой payload, например ID клиента или чека. При нажатии он вернётся вам в вебхуке messages_button в поле button.payload.
    ПолеТипОписание
    indexчислоНомер кнопки в шаблоне по порядку, с нуля. Нумерация кнопок своя и не зависит от переменных текста {{1}}, {{2}}.
    typeстрокаurl или quick_reply. По умолчанию url.
    valueстрокаХвост ссылки для url или payload для quick_reply, до 2000 символов.

    Пример: в шаблоне три кнопки ответа «Отлично», «Нормально», «Не понравилось» (номера 0, 1, 2) и URL-кнопка (номер 3).

    {
      "channelId": "ВАШ_CHANNEL_ID",
      "chatId": "77771234567",
      "templateName": "check_rating",
      "templateVariables": { "1": "Подмышки ваксинг", "2": "480" },
      "templateButtons": [
        { "index": 0, "type": "quick_reply", "value": "rate_5:client_42" },
        { "index": 3, "type": "url", "value": "42" }
      ]
    }

    Кнопки, которые не переданы, уходят как в шаблоне. Если номер кнопки или тип не совпадают с шаблоном, WhatsApp отклонит сообщение, ошибка придёт в статусе отправки.

    ℹ️ Какую кнопку выбрать. Нажатие кнопки быстрого ответа приходит вам событием messages_button. Переход по URL-кнопке WhatsApp никому не сообщает: его видит только ваш сайт, на который ведёт ссылка. Если нужно отметить действие клиента в своей системе (например, «Стоп»), делайте кнопку быстрого ответа.