Объект Journey

Методы жизненного цикла, а также создания и обновления возвращают объект Journey с одинаковой структурой верхнего уровня:

Структура

{
  "info": { ... },        // метаданные только для чтения (только в ответах)
  "params": { ... },      // общие настройки Journey (создание/обновление)
  "points": [ ... ],      // узлы на холсте и их соединения
  "comments": [ ... ]     // комментарии на холсте
}

При создании или обновлении Journey вы отправляете title, params, points и comments. Ответы возвращают info (который содержит params), а также points и comments.

Info

Метаданные Journey, доступные только для чтения. Возвращаются каждым методом v3. Не являются частью тела запроса.

Поле	Тип	Описание
uuid	string	Journey ID.
title	string	Название Journey.
status	JourneyStatus	Текущее состояние.
created_at	string	Временная метка создания (ISO 8601).
updated_at	string	Временная метка последнего обновления (ISO 8601).
is_first_activated	bool	Была ли Journey запущена хотя бы один раз.
params	JourneyParams	Общие настройки Journey.
category_uuid	string	UUID категории или пусто, если категория не задана.
pointCounts	map<string, uint32>	Количество точек по типам.
campaign_type	CampaignType	Как пользователи попадают в Journey.
stop_reason	string	Причина остановки Journey, если применимо.
last_edited_by	User	Пользователь, который последним редактировал Journey.
dynamic_entry	bool	Включен ли динамический вход.

JourneyParams

Общие настройки Journey. Отправляются при создании/обновлении и возвращаются внутри info.params.

Поле	Тип	Описание
application_code	string	Код приложения, к которому относится Journey. Обязательно при создании.
silent_hours	SilentHours	Часы, в течение которых отправка сообщений приостанавливается, для каждого канала.
capping	EntryCapping	Ограничения на частоту повторного входа пользователя в Journey.
conversion_window	ConversionWindow	Окно для атрибуции конверсий по целям.
user_id_track_change_policy	UserIDTrackChangePolicy	Как обрабатывать изменение ID пользователя в середине Journey.

SilentHours

Приостанавливает отправку в тихие часы. Настраивается для каждого канала: каждый канал принимает свои собственные SilentHoursParams:

Поле	Тип	Описание
push_params	SilentHoursParams	Тихие часы для push-уведомлений.
inapp_params	SilentHoursParams	Тихие часы для in-app сообщений.
email_params	SilentHoursParams	Тихие часы для email.
sms_params	SilentHoursParams	Тихие часы для SMS.
whatsapp_params	SilentHoursParams	Тихие часы для WhatsApp.
line_params	SilentHoursParams	Тихие часы для LINE.

Каждый SilentHoursParams представляет собой:

Поле	Тип	Описание
enabled	bool	Применяются ли тихие часы к этому каналу.
from_time	Time	Начало тихого окна: { "hour": 0–23, "minute": 0–59 }.
to_time	Time	Конец тихого окна.
week_days	bool[]	Семь булевых значений для дней, когда применяется окно (понедельник = индекс 0).
behavior	enum	Что делать, если сообщение попадает в тихие часы: WaitAndSend (удержать, затем отправить по окончании окна), DropAndGo (пропустить сообщение, немедленно продолжить Journey) или WaitAndDrop (подождать окончания окна, затем продолжить без отправки).

EntryCapping

Ограничивает, как часто один и тот же пользователь может входить в Journey.

Поле	Тип	Описание
is_enabled	bool	Включено ли ограничение на вход.
period	uint64	Минимальное количество минут между входами пользователя. 0 означает, что пользователь может войти только один раз за все время.

Ограничение отсчитывается с момента входа пользователя в Journey и отслеживается по User ID, поэтому все устройства одного пользователя используют один и тот же вход. Пока длится период, точка входа отклоняет дальнейшие попытки входа и считает их ошибками, а не создает нового “путешественника” (traveler).

Три аспекта поведения, которые следует учитывать при изменении этих настроек:

• Ранний выход из Journey не снимает ограничение. Пользователь ожидает полного периода, даже после достижения точки выхода.
• Измененный period применяется к входам, совершенным после обновления. Пользователи, вошедшие ранее, сохраняют период, который действовал на момент их входа.
• Установка is_enabled в false немедленно снимает ограничение для всех пользователей.

Примечание

Control Panel записывает то же поле из Campaign entry limit, которое предлагает 0 (один раз за все время), 1440 (один раз в день), 10080 (один раз в неделю), 43800 (один раз в месяц) и 131500 (один раз в три месяца).

ConversionWindow

Поле	Тип	Описание
seconds	uint64	Как долго после входа в Journey достижение цели пользователем все еще считается конверсией.

Point

Точка (point) — это узел на холсте Journey: точка входа, сообщение, задержка, сплиттер и т. д.

Поле	Тип	Описание
uuid	string	Уникальный ID точки в Journey. Должен быть каноническим UUID по RFC 4122: 32 шестнадцатеричных цифры в группах 8-4-4-4-12.
title	string	Отображаемое имя точки.
point_type	PointType	Тип узла.
outputs	array of PointOutput	Соединения с последующими точками.
position	Position	Координаты на холсте.
point_data	object	Ровно один вложенный ключ, соответствующий point_type (см. таблицу типов точек).

Примечание

Все UUID (info.uuid, uuid каждой точки и next_point_uuid каждого выхода) должны быть каноническими UUID по RFC 4122 (8-4-4-4-12 группы шестнадцатеричных цифр).

PointOutput

Выходы точки — это ее исходящие ветви. Их ключи не являются произвольными. Валидатор ожидает точный набор ключей для каждого типа точки и отклоняет Journey, если у точки неверное количество выходов или ключ, который он не распознает.

Поле	Тип	Описание
identity.key	string	Ключ ветви. Должен соответствовать правилам для ключей вывода ниже.
identity.order	int	Порядок отображения ветви.
info.title	string	Необязательная метка ветви.
info.next_point_uuid	string	UUID следующей точки, к которой подключается эта ветвь. Необязательно — если оставить пустым, Journey для пользователя завершится, так же как и при явной точке terminator.

Ключи вывода

Ветвь по умолчанию (первая) всегда называется "default". Дополнительные ветви называются "output1", "output2", … (префикс output, за которым следует индекс, начинающийся с 1). Два типа точек нарушают это правило, что отмечено ниже.

Тип точки	Ожидаемые ключи вывода
Точки входа (START_BY_SEGMENT, START_BY_API, EVENT), INAPP, SET_TAGS, WEBHOOK, AUDIENCE_SYNC и точки сообщений без сплиттера (SEND_PUSH, SEND_EMAIL, SEND_SMS, SEND_WHATSAPP, SEND_LINE, SEND_KAKAO, SEND_TELEGRAM, SEND_DATA)	default
GOAL_EVENT, EXIT	нет (без выходов)
FILTER	default, output1
BOOLEAN_SPLITTER	default, затем output1 … outputN (одна дополнительная ветвь на каждое условие. Простое разделение да/нет — это default + output1)
WAIT (задержка)	default. Динамическая задержка с разделением ветвей добавляет output1
WAIT_EVENT	default — это ветвь для случая, когда событие не сработало. output1 (или, при использовании скрипта условий, одна ветвь на каждое условие) — это путь для сработавшего события
SEND_PUSH со сплиттером	default, output1 (и output2, когда включены оба сплиттера — для сообщения и для доставки)
SEND_EMAIL / SEND_SMS / SEND_LINE / SEND_WHATSAPP со сплиттером	default, output1
SEND_WHATSAPP с пресетом быстрых ответов	default, плюс одна ветвь на каждый быстрый ответ. Ключом является само значение быстрого ответа
AB_SPLITTER	output0, output1, output2, … (по одной на каждый вариант. Ветви default нет)

Position

Поле	Тип	Описание
x	float	Горизонтальная координата на холсте.
y	float	Вертикальная координата на холсте.

Типы точек и point_data

point_data — это структура типа “один из”: она содержит ровно один вложенный объект, ключ которого определяется point_type точки.

point_type	ключ point_data	Назначение
POINT_TYPE_START_BY_SEGMENT	start_by_segment	Вход: пользователи, соответствующие сегменту.
POINT_TYPE_EVENT	message_bus	Вход: пользователи, вызвавшие событие.
POINT_TYPE_START_BY_API	start_by_api	Вход: пользователи, добавленные через вызов Start by API.
POINT_TYPE_WAIT	delay	Ожидание фиксированного или динамического интервала.
POINT_TYPE_WAIT_EVENT	wait_event	Ожидание наступления события.
POINT_TYPE_SEND_PUSH	send_push	Отправка push-уведомления.
POINT_TYPE_SEND_EMAIL	send_email	Отправка email.
POINT_TYPE_SEND_SMS	send_sms	Отправка SMS.
POINT_TYPE_SEND_WHATSAPP	send_whatsapp	Отправка сообщения WhatsApp.
POINT_TYPE_SEND_TELEGRAM	send_telegram	Отправка сообщения Telegram.
POINT_TYPE_SEND_KAKAO	send_kakao	Отправка сообщения Kakao.
POINT_TYPE_SEND_LINE	send_line	Отправка сообщения LINE.
POINT_TYPE_SEND_DATA	send_data	Отправка тихого сообщения с данными.
POINT_TYPE_INAPP	inapp	Показ in-app сообщения.
POINT_TYPE_BOOLEAN_SPLITTER	boolean_splitter	Разделение пользователей по условию (сегмент, теги или событие).
POINT_TYPE_AB_SPLITTER	ab_splitter	Разделение пользователей на A/B группы.
POINT_TYPE_FILTER	filter	Разрешить продолжать только пользователям, соответствующим фильтру.
POINT_TYPE_SET_TAGS	set_tags	Обновление тегов пользователя.
POINT_TYPE_WEBHOOK	web_hook	Отправка исходящего HTTP-запроса.
POINT_TYPE_GOAL_EVENT	goal_event	Отслеживание цели конверсии.
POINT_TYPE_AUDIENCE_SYNC	audience_sync	Синхронизация пользователей с внешней аудиторией.
POINT_TYPE_EXIT	terminator	Выход из Journey.

Примечание

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

Пример точки

Точка “установить теги” с одним последующим соединением:

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "title": "Отметить как вовлеченного",
  "point_type": "POINT_TYPE_SET_TAGS",
  "position": { "x": 480, "y": 120 },
  "outputs": [
    {
      "identity": { "key": "default", "order": 0 },
      "info": { "title": "", "next_point_uuid": "ffffffff-1111-2222-3333-444444444444" }
    }
  ],
  "point_data": {
    "set_tags": {
      "application_code": "XXXXX-XXXXX",
      "tags": [ { "name": "engaged", "value": "true" } ]
    }
  }
}

JourneyComment

Поле	Тип	Описание
id	string	UUID комментария.
message	string	Текст комментария.
position	Position	Координаты на холсте.
index	int	Порядок отображения.
created_at	string	Временная метка создания (ISO 8601).
deleted	bool	Удален ли комментарий.

Перечисления (Enums)

JourneyStatus enum

STATUS_DRAFT, STATUS_RUNNING, STATUS_FINISHED, STATUS_ARCHIVED, STATUS_PAUSED, STATUS_UNKNOWN.

CampaignType enum

• TriggerBased: пользователи входят по событию.
• AudienceBased: пользователи входят из сегмента.
• APIBased: пользователи входят через вызов Start by API.
• Mixed: более одного типа входа.
• Unknown: тип входа не определен.

PointType enum

Полный список и ключ point_data, которому соответствует каждый тип, см. в таблице типов точек выше.

UserIDTrackChangePolicy enum

Определяет, что происходит с пользователем, который находится в середине Journey, когда его User ID изменяется:

• DEFAULT: поведение по умолчанию.
• TRACK: продолжать отслеживать пользователя под новым ID.
• DROP: удалить пользователя из Journey при изменении его ID.

Связанные материалы

Справочник по точкам

Создание и обновление

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