🚀 Что нового
Теперь публичный 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"
}
}
⚙️ Как это работает под капотом
- Запрос: Вы отправляете JSON на
POST /v1/messages/send. - Очередь: Система проверяет доступы и ставит сообщение во внутреннюю очередь (вы моментально получаете ответ
HTTP 202). - Отправка: Система собирает сообщение по правилам WhatsApp, для шаблона с кодом добавляет кнопку копирования и отправляет шаблон в WhatsApp.
- Статусы: Уведомления о доставке и прочтении приходят вам через настроенные 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 никому не сообщает: его видит только ваш сайт, на который ведёт ссылка. Если нужно отметить действие клиента в своей системе (например, «Стоп»), делайте кнопку быстрого ответа.
