# 节点参考

每个 [point (节点)](/zh/developer/api-reference/customer-journey-api/journey-object/#point) 都带有一个 `point_data` 对象，该对象中只有一个嵌套键，与节点的 `point_type` 相匹配（请参阅 [point-type → key 映射](/zh/developer/api-reference/customer-journey-api/journey-object/#point-types-and-point_data)）。本页记录了每个键下的结构。

<Aside type="note">
下文完整记录了进入、计时、拆分、操作和转化节点。

对于消息传递节点（`send_*`、`inapp`），本页仅涵盖结构性字段：引用哪个 preset 或内容，以及传递哪些渠道设置。
消息内容本身在 preset 中定义，并记录在 [Presets API](/zh/developer/api-reference/presets-api/) 和各渠道的文档中。
某些字段引用了嵌套对象，这些对象反映了 Customer Journey 构建器中的控件。
</Aside>
## 进入节点

一个 Journey 至少需要一个进入节点。所有进入节点都有一个 `default` 输出。

### start_by_segment

让匹配某个细分的用户进入。`POINT_TYPE_START_BY_SEGMENT`。

| 字段 | 类型 | 描述 |
|---|---|---|
| `application_code` | string | [Application code (应用代码)](/zh/developer/api-reference/api-identifiers/#application-code)。 |
| `filter_code` | string | 定义受众的 [Segment/filter code (细分/筛选器代码)](/zh/developer/api-reference/api-identifiers/#segment--filter-code)。 |
| `repeat` | `SegmentRepeat` | 可选的重复进入计划（请参阅 [SegmentRepeat](#segmentrepeat)）。 |
| `start_at` | timestamp | 在此时间（ISO 8601）之前不处理。 |
| `is_deactivated` | bool | 此进入节点是否已关闭。 |

### message_bus (事件进入)

当用户触发事件时进入。`POINT_TYPE_EVENT`。

| 字段 | 类型 | 描述 |
|---|---|---|
| `event_name` | string | 要监听的 [Event name (事件名称)](/zh/developer/api-reference/api-identifiers/#event-name)。 |
| `application_code` | string | [Application code (应用代码)](/zh/developer/api-reference/api-identifiers/#application-code)。 |
| `event_conditions` | `PointEventCondition[]` | 与事件属性匹配的条件。 |
| `active_period` | `Period` | 触发器处于活动状态的时间窗口。 |
| `multi_entry` | `MultiEntry` | 用户如何可以多次进入（请参阅 [MultiEntry](#multientry)）。 |
| `attribute_entry` | `AttributeEntry` | 注册事件属性中携带的用户 ID，而不是触发事件的用户（请参阅 [AttributeEntry](#attributeentry)）。 |
| `allow_reenter` | bool | 用户是否可以重新进入 Journey。 |

##### AttributeEntry

注册事件属性中携带的 [User ID (用户 ID)](/zh/developer/api-reference/api-identifiers/#user-id)，而不是触发事件的用户。这与 Customer Journey 构建器中的 [来自事件属性的用户](/zh/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/#users-from-an-event-attribute) 功能相对应。

| 字段 | 类型 | 描述 |
|---|---|---|
| `enabled` | bool | 是否注册事件属性中指定的用户，而不是触发事件的用户。 |
| `attribute_name` | string | 包含要注册的 User ID（或 User ID 列表）的事件属性名称。 |

### start_by_api

由 [Start by API](/zh/developer/api-reference/customer-journey-api/start-by-api/) 调用提供的进入节点。`POINT_TYPE_START_BY_API`。

| 字段 | 类型 | 描述 |
|---|---|---|
| `application_code` | string | [Application code (应用代码)](/zh/developer/api-reference/api-identifiers/#application-code)。 |
| `attributes` | string[] | 可以在 [Start by API](/zh/developer/api-reference/customer-journey-api/start-by-api/#request-body) 请求的 `attribute_values` 中传递的自定义属性名称。 |
| `is_deactivated` | bool | 此进入节点是否已关闭。 |

## 计时节点

### delay (wait)

将每个用户暂停一个固定或计算出的时间间隔。`POINT_TYPE_WAIT`。`point_data.delay` 对象会精确设置以下时间间隔键之一：

| 时间间隔键 | 类型 | 描述 |
|---|---|---|
| `sec` | uint64 | 等待固定的秒数。 |
| `exact_time` | [`ExactTime`](#time-objects) | 等待到一天中的某个时间（`hour`、`minute`）。 |
| `exact_date_time` | [`ExactDateTime`](#time-objects) | 等待到某个绝对日期和时间。 |
| `exact_week_days_time` | `ExactWeekDaysTime` | 等待到特定工作日的特定时间（星期一 `0` … 星期日 `6` → `ExactTime` 的映射）。 |
| `dynamic_time` | [`DynamicTime`](#dynamictime) | 相对于标签或事件中的值进行等待。 |

带有 `split_branches: true` 的 `dynamic_time` 会添加一个 `output1` 分支（请参阅 [output keys (输出键)](/zh/developer/api-reference/customer-journey-api/journey-object/#output-keys)）。

#### DynamicTime

| 字段 | 类型 | 描述 |
|---|---|---|
| `from` | enum `DynamicTimeFrom` | 基础时间是来自标签还是事件。 |
| `direction` | enum `DynamicTimeDirection` | 在基础时间之前或之后的偏移量。 |
| `duration` | uint64 | 偏移量的大小。 |
| `unit` | enum `DynamicTimeUnit` | `duration` 的单位（分钟、小时、天等）。 |
| `split_branches` | bool | 当用户的计算时间不同时，将他们拆分到不同的分支。 |
| `tag_name` | string | 包含基础时间的标签（当 `from` 是标签时）。 |
| `event_name` / `event_attribute` / `point_id` | string | 基础时间的事件源（当 `from` 是事件时）。 |

### wait_event

等待用户触发事件（或超时）。`POINT_TYPE_WAIT_EVENT`。`default` 输出是**未触发**路径。触发路径是 `output1`，或者在使用脚本时，每个条件对应一个分支。

| 字段 | 类型 | 描述 |
|---|---|---|
| `events` | `PointWaitEventInfo[]` | 等待的事件。 |
| `conditions_script` | string | 用于复杂多事件逻辑的可选脚本。其解析出的条件名称将成为输出键。 |
| `multi_entry` | `MultiEntry` | 重新进入行为。 |

## 拆分和筛选节点

### boolean_splitter

根据条件将用户路由到不同分支。`POINT_TYPE_BOOLEAN_SPLITTER`。

| 字段 | 类型 | 描述 |
|---|---|---|
| `application_code` | string | [Application code (应用代码)](/zh/developer/api-reference/api-identifiers/#application-code)。 |
| `split_strategy` | enum | `SPLIT_FILTER`（按细分）、`SPLIT_TAGS`（按标签条件）或 `SPLIT_EVENTS`（按事件条件）。 |
| `load_policy` | enum | `ALL`（用户的任何设备都可以匹配）或 `FILTER`（仅当前设备）。 |
| `filter_code` | string | 细分代码，当 `split_strategy` 为 `SPLIT_FILTER` 时。 |
| `filter_expressions` | `FilterExpression[]` | 标签条件，当 `split_strategy` 为 `SPLIT_TAGS` 时：每个表达式对应一个额外的 `output` 分支。 |
| `event` | `BooleanSplitterEventInfo` | 事件条件，当 `split_strategy` 为 `SPLIT_EVENTS` 时：每个条件对应一个额外的 `output` 分支。 |

### ab_splitter

将用户随机拆分到加权的变体中。`POINT_TYPE_AB_SPLITTER`。输出键为 `output0`、`output1` 等（`split` 中的每个条目对应一个，从 0 开始索引。没有 `default`）。

| 字段 | 类型 | 描述 |
|---|---|---|
| `split` | uint32[] | 每个分支的百分比。总和必须为 100。索引 `i` 映射到输出键 `output{i}`。 |
| `auto_select_winner` | bool | 是否自动选择获胜分支。 |
| `winner_strategy` | enum | `ANY_GOAL` 或 `SPECIFIC_GOAL`。 |
| `goal_uuid` | string | 用于确定获胜者的目标（与 `SPECIFIC_GOAL` 一起使用）。 |
| `winner_split` | uint32 | 获胜分支编号（从 1 开始，`0` = 尚无获胜者）。 |

### filter

仅允许匹配的用户继续（`default`），将其余用户路由到 `output1`。`POINT_TYPE_FILTER`。

| 字段 | 类型 | 描述 |
|---|---|---|
| `filter` | enum `Filter` | 预定义的检查：`EMAIL_EXISTS`、`PUSH_TOKEN_EXISTS`、`SMS_TOKEN_EXISTS`、`WHATSAPP_TOKEN_EXISTS`、`LINE_TOKEN_EXISTS` 或 `CUSTOM`。 |
| `filter_raw` | string | 自定义筛选器表达式，当 `filter` 为 `CUSTOM` 时。 |

## 操作节点

### set_tags

更新用户身上的标签。`POINT_TYPE_SET_TAGS`。

| 字段 | 类型 | 描述 |
|---|---|---|
| `application_code` | string | [Application code (应用代码)](/zh/developer/api-reference/api-identifiers/#application-code)。 |
| `tags` | [`Tag`](#tag)[] | 要写入的标签。 |

#### Tag

| 字段 | 类型 | 描述 |
|---|---|---|
| `name` | string | 标签名称。 |
| `type` | enum `TagType` | 数据类型和操作：`TYPE_STRING`、`TYPE_INTEGER`、`TYPE_DATE`、`TYPE_BOOLEAN`、`TYPE_LIST`、`TYPE_LIST_APPEND`、`TYPE_LIST_REMOVE`、`TYPE_DYNAMIC` 等。 |
| _value_ | oneof | 与 `type` 匹配的精确一个值键：`str`、`int`、`bool`、`date`、`price`、`version`、`timezone`、`list` 或 `dynamic`。 |

### web_hook

发送一个出站 HTTP 请求。`POINT_TYPE_WEBHOOK`。单个 `default` 输出。

| 字段 | 类型 | 描述 |
|---|---|---|
| `method` | string | HTTP 方法（`GET`、`POST`、`PUT` 等）。 |
| `url` | string | 目标 URL。 |
| `request_template` | string | 请求正文模板。支持 [Liquid](/zh/developer/api-reference/messaging-api-v2/payload-reference/) 模板。 |
| `headers` | map&lt;string, string&gt; | HTTP 标头。 |
| `disabled` | bool | 只读。当 Pushwoosh 在重复错误后自动禁用 webhook 时为 `true`。 |
| `reactivate` | bool | 只写。设置为 `true` 以重新启用已禁用的 webhook。 |

## 转化节点

### goal_event

跟踪一个转化目标。`POINT_TYPE_GOAL_EVENT`。没有输出。

| 字段 | 类型 | 描述 |
|---|---|---|
| `event_name` | string | 目标事件名称。 |
| `application_code` | string | [Application code (应用代码)](/zh/developer/api-reference/api-identifiers/#application-code)。 |
| `event_conditions` | `PointEventCondition[]` | 与目标事件属性匹配的条件。 |
| `is_throw_out` | bool | 达到目标后是否将用户从 Journey 中移除。 |
| `is_cancel_event` | bool | 这是否是一个负向（取消）目标。 |

## 退出节点

### terminator

为用户结束 Journey。`POINT_TYPE_EXIT`。空对象（`{}`），没有输出。

```json
{ "point_type": "POINT_TYPE_EXIT", "point_data": { "terminator": {} }, "outputs": [] }
```

## 消息传递节点

所有消息传递节点都通过一个渠道发送，并共享一个通用信封。除非启用了拆分器，否则每个节点都有一个 `default` 输出（请参阅 [output keys (输出键)](/zh/developer/api-reference/customer-journey-api/journey-object/#output-keys)）。

通用字段：

| 字段 | 类型 | 描述 |
|---|---|---|
| `application_code` | string | [Application code (应用代码)](/zh/developer/api-reference/api-identifiers/#application-code)。 |
| `preset_code` | string | 要发送的 [Preset](/zh/developer/api-reference/presets-api/) (模板)。`inapp` 使用 `richmedia_code` 代替。 |
| `content` / `title` | string | 内联消息内容，当不使用 preset 时（取决于渠道）。 |
| `campaign_code` | string | 用于跟踪的 [Campaign code (营销活动代码)](/zh/developer/api-reference/api-identifiers/#campaign-code)。如果省略，则自动创建。 |
| `split_params` | [`BehaviorSplitter`](#behaviorsplitter) | 可选：等待交互并据此进行分支。 |
| `message_type` | enum | [营销 vs 事务性](/zh/product/messaging-channels/marketing-vs-transactional/) 消息类型（控制对照组处理）。 |

节点类型及其值得注意的额外字段：

| 节点类型 | `point_data` 键 | 注意事项 |
|---|---|---|
| `POINT_TYPE_SEND_PUSH` | `send_push` | `split_params`（行为）加上一个送达拆分器最多可以产生三个输出。`send_by_user_id`、`wait_optimal_time`。 |
| `POINT_TYPE_SEND_EMAIL` | `send_email` | `liquid_template_params`、`personalise`。请参阅 [Email API](/zh/developer/api-reference/email-api/)。 |
| `POINT_TYPE_SEND_SMS` | `send_sms` | 请参阅 [SMS](/zh/developer/api-reference/sms/)。 |
| `POINT_TYPE_SEND_WHATSAPP` | `send_whatsapp` | 快速回复 preset 会为每个回复添加一个输出（键 = 回复值）。请参阅 [WhatsApp](/zh/developer/api-reference/whatsapp/)。 |
| `POINT_TYPE_SEND_TELEGRAM` | `send_telegram` | Telegram 渠道。 |
| `POINT_TYPE_SEND_KAKAO` | `send_kakao` | 请参阅 [Kakao](/zh/developer/api-reference/kakao/)。 |
| `POINT_TYPE_SEND_LINE` | `send_line` | 请参阅 [LINE API](/zh/developer/api-reference/line-api/)。 |
| `POINT_TYPE_SEND_DATA` | `send_data` | 静默数据消息（无 UI）。 |
| `POINT_TYPE_INAPP` | `inapp` | 使用 `richmedia_code`、`expire_in_days`、`capping`。 |

## 共享类型

### SegmentRepeat

| 字段 | 类型 | 描述 |
|---|---|---|
| `enabled` | bool | 是否开启重复进入。 |
| `frequency` | string | `daily`、`weekly`、`monthly` 或 `dates`。 |
| `every` | uint32 | 每 N 个周期重复一次。 |
| `dates` | string[] | 特定日期，当 `frequency` 为 `dates` 时。 |
| `time` | `SegmentRepeatTime` | 当天时间配置。 |

### 时间对象

- `ExactTime`: `{ "hour": 0–23, "minute": 0–59 }`。
- `ExactDateTime`: `{ "year", "month": 1–12, "day": 1–31, "hour": 0–23, "minute": 0–59 }`。

### BehaviorSplitter

| 字段 | 类型 | 描述 |
|---|---|---|
| `enabled` | bool | 是否等待交互并据此进行分支。 |
| `interval` | uint64 | 等待交互的秒数。 |

### MultiEntry

控制一个用户在 Journey 中可以同时拥有多少个活动会话。这与 Customer Journey 构建器中的 [控制用户可以同时拥有的会话数量](/zh/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/#control-how-many-sessions-a-user-can-have-at-the-same-time) 功能相对应。由 [事件进入节点](#message_bus-event-entry) 和 [wait_event](#wait_event) 使用。

| 字段 | 类型 | 描述 |
|---|---|---|
| `enabled` | bool | 用户是否可以同时拥有多个活动会话。`false`：每个用户一个活动会话。`true`：每个用户多个活动会话。 |
| `attribute_name` | string | 可选。限定每个会话范围的事件属性。设置后，用户可以为该属性的每个不同值拥有一个活动会话（例如，每个 `order_id` 一个）。具有相同值的事件共享一个会话。留空则将用户的所有进入归为一类。 |

## 相关内容

<CardGrid>
  <LinkCard title="Journey 对象" href="/developer/api-reference/customer-journey-api/journey-object/" />
  <LinkCard title="创建和更新" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="Presets API" href="/developer/api-reference/presets-api/" />
</CardGrid>