Студия контента

Студия контента (пункт Контент в боковом меню) нужна, чтобы написать сообщение один раз и переиспользовать его: в email-рассылках, в поп-апах на сайте и везде, где принимается ссылка на контент. Документ контента не привязан к каналу: один и тот же документ проверяется и отрисовывается отдельно для каждого канала.

Для редактирования нужно то же право на бота, что и для реакций. Без него раздел открывается только на чтение: документы видно, а создавать, править, публиковать, архивировать и отправлять тесты нельзя.

Документы, черновики и версии

У каждого документа есть тип, который определяет, где его можно использовать: Сообщение, Email, Попап, Внутри приложения, Push-уведомление, Быстрый ответ, Лид-бот.

У документа всегда ровно один редактируемый черновик и произвольное число опубликованных версий:

  • редактирование меняет только текущий черновик;
  • Опубликовать фиксирует черновик как неизменяемую версию и сразу открывает следующий черновик с тем же содержимым;
  • опубликованная версия никогда не переписывается. Запланированная рассылка или включённый поп-ап продолжают ссылаться ровно на ту версию, которую они зафиксировали.

Поэтому правка документа не может незаметно изменить уже идущую рассылку. Чтобы изменить живую отправку, опубликуйте новую версию и переключите на неё потребителя.

Сохранение защищено от параллельных правок: интерфейс отправляет версию и ревизию, которые он загрузил, а сервер отвечает 409, если документ за это время изменил кто-то другой. Перезагрузите страницу и повторите.

Архивировать убирает документ из списка. Архивация запрещена, пока на документ ссылается включённый поп-ап, запланированная, идущая или поставленная на паузу email-рассылка либо принятая или идущая push-рассылка. Сначала уберите эти ссылки.

Блоки и ограничения

Документ собирается из блоков:

  • Текст, Заголовок, Список, Разделитель – текст с необязательным форматированием;
  • Изображение, Файл, Видео – файл из медиатеки или URL плюс подпись;
  • Кнопка – текст со ссылкой или данными callback;
  • Колонки – группа не больше чем из четырёх дочерних блоков. Это способ сгруппировать блоки в редакторе: при доставке дочерние блоки идут друг за другом, а канал, который не заявляет поддержку колонок, добавляет предупреждение columns_flattened;
  • Условный контент – группа, которая показывается только при выполнении условия.

Сервер проверяет эти ограничения при сохранении и повторно при публикации:

  • название документа: от 1 до 120 символов;
  • минимум один блок, максимум 200 блоков всего;
  • глубина вложенности не больше 8;
  • не больше 10 кнопок на одном уровне;
  • у блока Колонки не больше 4 дочерних блоков;
  • у каждого блока должен быть идентификатор, и внутри документа они уникальны.

И при сохранении черновика, и при публикации документ целиком проверяется на сервере, и оба раза проверяется, что все использованные медиафайлы принадлежат этому боту. То, что пропустил браузер, всё равно отклонит сервер.

Подстановки

Подстановки записываются в двойных фигурных скобках и раскрываются в момент отправки:

Здравствуйте, {{profile.first_name}}! Заказ {{event.order_id}} уже в пути.

Возможны только четыре формы:

  • {{profile.<поле>}} – поле профиля получателя;
  • {{event.<поле>}} – поле текущего события;
  • {{system.unsubscribe_url}} – ссылка отписки для этого получателя;
  • {{system.current_date}} – текущая дата в формате ГГГГ-ММ-ДД.

Всё остальное отклоняется. Контент не может выполнять JavaScript, SQL, шаблонизатор или HTTP-запрос.

Поля profile и event работают по белому списку. Поле доступно, только если вызывающий контекст явно его опубликовал; наличия значения в базе недостаточно. Неизвестный или неопубликованный путь приводит к ошибке отрисовки «запрещённая подстановка», а не к тихой пустой строке.

Отсутствующее значение разрешённого поля тоже приводит к ошибке, если у документа нет запасного значения. Запасные значения хранятся в настройках документа в поле fallbacks, ключ – полный путь:

{ "fallbacks": { "profile.first_name": "друг" } }

Запасное значение принимается только для пути, который сам есть в белом списке, и ограничено 16 000 символов.

Экранирование выполняется автоматически и зависит от места вставки: внутри текста с HTML-форматированием значения экранируются как HTML, внутри URL кодируются процентами. Значения system.* внутри URL повторно не кодируются, потому что это уже готовые ссылки.

Условные блоки

Условие можно повесить на любой блок, а блок Условный контент объединяет несколько блоков под одним условием.

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

  • субъект: только profile или event;
  • операторы: eq, ne, gt, lt, ge, le, gte, lte, exists, not_exists, contains, not_contains, in, not_in, between, before, after, has_any, not_has_any;
  • условия с временным окном («за последние N дней» и подобные) недоступны.

Условие, которому нужны недоступные при отрисовке данные, помечается кодом condition_unsupported, некорректное – condition_invalid. Ранее опубликованные версии проходят ту же проверку перед отправкой, поэтому неподдерживаемое условие всплывает как ошибка проверки, а не как сбой доставки.

Проверка по каналу и предпросмотр

Проверить отрисовывает выбранную версию по реальным возможностям канала и возвращает два списка.

Ошибки блокируют публикацию и отправку:

  • text_too_long – текст длиннее лимита канала;
  • media_missing – у блока изображения, файла или видео нет ни файла, ни URL;
  • media_unsupported – канал не поддерживает такой тип вложения;
  • button_unsupported – в канале нет inline-кнопок, а у кнопки нет ссылки, до которой её можно упростить;
  • invalid_document – нарушено одно из структурных правил выше;
  • condition_invalid, condition_unsupported.

Предупреждения не блокируют отправку, но показывают, как контент упростится:

  • columns_flattened – в канале нет колонок, дочерние блоки пойдут друг за другом;
  • format_flattened – канал не поддерживает такое форматирование, текст уйдёт как обычный;
  • button_as_link – кнопка станет обычной ссылкой;
  • missing_image_alt – у изображения нет альтернативного текста;
  • vague_link_text – текст кнопки пустой или это «click here», «here», «link», «more».

Панель предпросмотра показывает результат для выбранного канала (Сайт, Email, Telegram, VK, WhatsApp) на десктопе и мобильном. Если выбрать реального получателя, контент отрисуется на его данных, и ошибки подстановок будут видны до отправки.

Возможности каналов различаются, поэтому один и тот же документ может быть чистым для одного канала и заблокированным для другого. Email, например, сохраняет колонки и HTML-форматирование, несёт изображения и файлы, но не видео, а кнопки превращает в ссылки (button_as_link).

Тестовая отправка

Тестовая отправка проходит ровно тот же путь проверки, отрисовки и очереди отправки, что и настоящая доставка, но для одного получателя. Произвольный адрес или chat id указать нельзя: получатель выбирается из списка уже доставляемых контактов бота.

Запрос отклоняется, если:

  • контакт не подтверждён (422);
  • контакт исключён из отправок, например отписался или адрес недоставляем (409);
  • документ изменился после загрузки (409);
  • канал недоступен в этой установке (422);
  • контент не отрисовывается для выбранного канала (422);
  • исчерпана квота канала (409);
  • за короткое время сделано слишком много тестовых отправок (429). Лимит считается на аккаунт: три подряд, дальше одна в 15 секунд.

Успешный вызов отвечает 202 и ставит сообщение в очередь; дальше его доставляет обычный механизм отправки.

Шаблоны

Шаблоны предлагают готовые заготовки. Выбор шаблона копирует его блоки в новый черновик: шаблон – это стартовая точка, а не живая связь, поэтому его последующие правки не затрагивают уже созданные документы.

В галерее видны шаблоны, поставляемые с установкой, и шаблоны этого бота; пока их нет, она пуста. Кнопки «сохранить как шаблон» пока нет: шаблоны бота создаются и удаляются через API (POST /api/bots/{botID}/content-templates).

Что делать, если

  1. «Запрещённая подстановка» – путь отсутствует в белом списке этого контекста или написан с опечаткой. Вставляйте подстановки через выбор, а не вручную.
  2. «Отсутствует подстановка» – у получателя нет значения для разрешённого поля. Добавьте запасное значение в настройках документа.
  3. Публикация возвращает 409 – документ изменил кто-то другой. Перезагрузите и опубликуйте снова.
  4. Архивация запрещена – на документ ещё ссылается включённый поп-ап, живая рассылка или идущая push-рассылка.
  5. Тестовая отправка недоступна – список получателей пуст, пока у бота нет хотя бы одного подтверждённого и не исключённого контакта в подключённом канале.

Что дальше