База знаний GetMyBot

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

Как подготовить сообщение один раз и использовать его в рассылке или на сайте. Черновики, публикация, подстановки и проверка перед отправкой.

На этой странице

В разделе Контент можно подготовить сообщение и использовать его в нескольких местах. Например, одну опубликованную версию программы курса можно отправить через Telegram и VK. Текст, изображения и кнопки вместе называются документом контента. Для письма, всплывающего окна и пуш-уведомления создаются документы соответствующих типов.

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

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

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

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

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

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

Например, рассылка запланирована с версией 2. Правки черновика и публикация версии 3 не изменят её письмо. Чтобы использовать новый текст, выберите новую версию в настройках рассылки или всплывающего окна.

Сохранение защищено от параллельных правок: интерфейс отправляет версию и ревизию, которые он загрузил, а сервер отвечает 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.5 означает полуторный интервал. Проверьте переносы строк в большом и мобильном предпросмотре. Набор настроек зависит от канала; проверка сообщит об упрощении оформления или последовательной отправке колонок.

Исходный HTML письма

В письме можно переключаться между визуальным режимом и HTML. После изменения исходника дождитесь проверки. При ошибке исправьте HTML перед переключением в визуальный режим или сохранением.

Импорт может изменить неподдерживаемые элементы. Просмотрите результат и проверяйте письмо в почтовых клиентах получателей: их отображение HTML различается.

Изменение элемента письма

Выберите элемент в визуальном редакторе и измените доступные свойства в инспекторе: текст, ссылку, изображение или контейнер. Значения полей применяются после потери фокуса. У ссылки есть адрес перехода и видимая надпись; у изображения альтернативный текст описывает его для получателей, которые его не видят.

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

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

Что дальше