Объект Journey

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

Структура

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

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

Info

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

Поле	Тип	Описание
uuid	string	ID Journey.
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	Минимальное количество секунд между входами пользователя.

ConversionWindow

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

Point

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

Поле	Тип	Описание
uuid	string	Уникальный ID элемента в рамках Journey. Должен быть каноническим RFC 4122 UUID: 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": "Tag as engaged",
  "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.

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

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

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

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