# Объект Journey

Методы [жизненного цикла](/ru/developer/api-reference/customer-journey-api/lifecycle/), а также [создания и обновления](/ru/developer/api-reference/customer-journey-api/create-update/) возвращают объект Journey с одинаковой структурой верхнего уровня:

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

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

## Info

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

| Поле | Тип | Описание |
|---|---|---|
| `uuid` | string | [ID Journey](/ru/developer/api-reference/api-identifiers/#journey-id). |
| `title` | string | Название Journey. |
| `status` | [`JourneyStatus`](#journeystatus-enum) | Текущее состояние. |
| `created_at` | string | Временная метка создания (ISO 8601). |
| `updated_at` | string | Временная метка последнего обновления (ISO 8601). |
| `is_first_activated` | bool | Было ли Journey запущено хотя бы один раз. |
| `params` | [`JourneyParams`](#journeyparams) | Конфигурация для всего Journey. |
| `category_uuid` | string | UUID категории или пустое значение, если категория не назначена. |
| `pointCounts` | map<string, uint32> | Количество точек по типам. |
| `campaign_type` | [`CampaignType`](#campaigntype-enum) | Как пользователи попадают в Journey. |
| `stop_reason` | string | Причина остановки Journey, если применимо. |
| `last_edited_by` | `User` | Пользователь, который последним редактировал Journey. |
| `dynamic_entry` | bool | Включен ли динамический вход. |

## JourneyParams

Конфигурация для всего Journey. Отправляется при создании/обновлении и возвращается внутри `info.params`.

| Поле | Тип | Описание |
|---|---|---|
| `application_code` | string | [Код приложения](/ru/developer/api-reference/api-identifiers/#application-code), к которому относится Journey. Обязательно при создании. |
| `silent_hours` | [`SilentHours`](#silenthours) | Часы, в течение которых сообщения не отправляются, для каждого канала. |
| `capping` | [`EntryCapping`](#entrycapping) | Ограничения на частоту повторного входа пользователя в Journey. |
| `conversion_window` | [`ConversionWindow`](#conversionwindow) | Окно для атрибуции конверсий по целям. |
| `user_id_track_change_policy` | [`UserIDTrackChangePolicy`](#useridtrackchangepolicy-enum) | Как обрабатывать изменение 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](https://www.rfc-editor.org/rfc/rfc4122) UUID: 32 шестнадцатеричных цифры в группах 8-4-4-4-12. |
| `title` | string | Отображаемое имя точки. |
| `point_type` | [`PointType`](#pointtype-enum) | Тип узла. |
| `outputs` | array of [`PointOutput`](#pointoutput) | Соединения с последующими точками. |
| `position` | [`Position`](#position) | Координаты на холсте. |
| `point_data` | object | Ровно один вложенный ключ, соответствующий `point_type` (см. таблицу [типов точек](#point-types-and-point_data)). |

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

### PointOutput

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

| Поле | Тип | Описание |
|---|---|---|
| `identity.key` | string | Ключ ветви. Должен соответствовать [правилам для ключей выходов](#output-keys) ниже. |
| `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](/ru/developer/api-reference/customer-journey-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. |

<Aside type="note">
Полезные данные `point_data` для каждого типа задокументированы в [справочнике по точкам (Point)](/ru/developer/api-reference/customer-journey-api/point-reference/). Точки входа, времени, разделения и действия полностью описаны там. Точки сообщений описаны на уровне общей структуры со ссылками на документацию по соответствующим каналам.
</Aside>

### Пример точки

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

```json
{
  "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`](#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`, которому соответствует каждый тип, см. в таблице [типов точек](#point-types-and-point_data) выше.

### UserIDTrackChangePolicy enum

Определяет, что происходит с пользователем, находящимся в середине Journey, когда его [User ID](/ru/developer/api-reference/api-identifiers/#user-id) меняется:

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

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

<CardGrid>
  <LinkCard title="Справочник по точкам (Point)" href="/developer/api-reference/customer-journey-api/point-reference/" />
  <LinkCard title="Создание и обновление" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="Жизненный цикл" href="/developer/api-reference/customer-journey-api/lifecycle/" />
</CardGrid>