Шаблоны

Страница для интегратора: почему свободного текста нет, как устроен шаблон и что проверяется до отправки.

Почему шаблон обязателен

Оператор принимает только зарегистрированные тексты: имя отправителя и шаблон проходят у него модерацию, и сообщение, не совпавшее с зарегистрированным, отвергается. Свободный текст в API означал бы отправку, отказ по которой приходит через минуты и не объясняется ничем.

Поэтому отправка идёт по шаблону, а меняется только подстановка.

Как выглядит

Тело шаблона написано операндами оператора, а не фигурными скобками:

Операнд	Что принимает
%d	только цифры
%w	одно слово (без пробелов)
%w{n,m}	от n до m слов

Vash kod dlya vhoda: %d
Zapis podtverzhdena na %w

Ваши имена переменных привязаны к операндам по позиции: первая объявленная переменная подставляется в первый операнд. Позиция, а не порядок аргументов — иначе правка текста молча меняла бы, какое значение куда попадёт.

Что проверяется на приёме

Каждое правило здесь существует потому, что его нарушение — отказ у оператора, то есть отказ, о котором вы узнали бы минутами позже вместо мгновенного ответа:

Проверка	Отказ
переменная не объявлена шаблоном / не передана обязательная	422 template_variables_mismatch
пустое значение	422 template_variable_invalid
перевод строки в значении	422 template_variable_invalid
символ % в значении	422 template_variable_invalid
%d получил не цифры	422 template_variable_invalid
%w получил несколько слов	422 template_variable_invalid
%w{n,m} получил слов меньше или больше	422 template_variable_invalid

Символ % в значении запрещён не из вредности: подстановка стала бы новым операндом и сдвинула бы разбор у оператора.

Сухой прогон

POST /v1/templates/{id}/render собирает текст с вашими значениями, ничего не отправляя: видно и результат, и число частей, на которые он разобьётся. Это дешевле, чем узнавать длину по факту списания.

Жизненный цикл

draft ──▶ pending_moderation ──▶ active
                              └─▶ rejected

• draft — черновик, заведённый вами;
• pending_moderation — отправлен оператору;
• active — зарегистрирован, годен к отправке;
• rejected — оператор отказал; причина приходит вместе со статусом.

В боевом режиме шаблон обязан быть active: иначе 422 template_not_active. В тестовом допускаются draft и pending_moderation — ждать ручной модерации, чтобы начать интеграцию, не нужно.

Вердикт модерации приезжает событием: template.activated или template.rejected. Очереди модерации вы не видите — она внутренняя.

Срок модерации у оператора уточняется: см. Ограничения MVP.

Категории и классы

У оператора категория (авторизационное, сервисное, рекламное), у хаба — класс трафика (otp, service, marketing). Они соответствуют друг другу, но это разные вещи: категория определяет, как шаблон модерируется у оператора, класс — сроки жизни, лимиты и то, действует ли отписка.

Класс marketing объявлен в контракте и выключен до третьей фазы: 422 class_not_enabled.

Отписка

У шаблона есть признак «уважает отписку» (respects_opt_out). Сервисные и рекламные шаблоны его уважают: отписавшемуся сообщение не уйдёт (422 recipient_opted_out). Одноразовые коды — нет: см. Одноразовые коды.