Объект 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 следующей точки, с которой соединяется эта ветвь.

Ключи выходов

Ветвь по умолчанию (первая) всегда называется "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 для каждого типа задокументированы в справочнике по точкам (Point). Точки входа, времени, разделения и действия полностью описаны там. Точки сообщений описаны на уровне общей структуры со ссылками на документацию по соответствующим каналам.

Пример точки

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

{
  "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.

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

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

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

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