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>	按类型统计的 point 数量。
campaign_type	CampaignType	用户进入该 Journey 的方式。
stop_reason	string	该 Journey 停止的原因（如果适用）。
last_edited_by	User	最后编辑该 Journey 的用户。
dynamic_entry	bool	是否启用了动态进入。

JourneyParams

Journey 范围的配置。在创建/更新时发送，并在 info.params 内返回。

字段	类型	描述
application_code	string	该 Journey 所属的 Application code。创建时必需。
silent_hours	SilentHours	每个渠道抑制消息发送的时间段。
capping	EntryCapping	用户可以重新进入该 Journey 的频率限制。
conversion_window	ConversionWindow	用于归因目标转化的时间窗口。
user_id_track_change_policy	UserIDTrackChangePolicy	如何处理用户在 Journey 中途 ID 发生变化的情况。

SilentHours

在静默时段内抑制发送。按渠道配置：每个渠道都有自己的 SilentHoursParams：

字段	类型	描述
push_params	SilentHoursParams	推送通知的静默时段。
inapp_params	SilentHoursParams	应用内消息的静默时段。
email_params	SilentHoursParams	电子邮件的静默时段。
sms_params	SilentHoursParams	短信的静默时段。
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（等待窗口结束，然后不发送消息继续 Journey）。

EntryCapping

限制同一用户进入该 Journey 的频率。

字段	类型	描述
is_enabled	bool	是否开启进入限制。
period	uint64	用户两次进入之间的最小分钟数。0 表示用户一生只能进入一次。

限制从用户进入该 Journey 的那一刻开始计算，并按用户 ID 进行跟踪，因此一个用户的所有设备共享一个进入记录。在限制期间，入口点会拒绝后续的进入尝试，并将其计为错误，而不是创建新的旅程者。

当您更改这些设置时，需要考虑三种行为：

• 提前离开该 Journey 不会解除限制。即使用户到达了退出点，也需要等待整个限制期结束。
• 更改后的 period 适用于更新后进入的用户。之前进入的用户将保留他们进入时生效的限制期。
• 将 is_enabled 设置为 false 会立即为所有用户解除限制。

注意

控制面板从 Campaign entry limit（营销活动进入限制）写入相同的字段，该字段提供 0（一生一次）、1440（每天一次）、10080（每周一次）、43800（每月一次）和 131500（每三个月一次）的选项。

ConversionWindow

字段	类型	描述
seconds	uint64	用户进入 Journey 后，其目标完成在多长时间内仍被计为一次转化。

Point

一个 point 是 Journey 画布上的一个节点：入口点、消息、延迟、分割器等等。

字段	类型	描述
uuid	string	该 Journey 中 point 的唯一 ID。必须是标准的 RFC 4122 UUID：32 个十六进制数字，格式为 8-4-4-4-12。
title	string	point 的显示名称。
point_type	PointType	节点的类型。
outputs	array of PointOutput	到下游 point 的连接。
position	Position	画布坐标。
point_data	object	只有一个嵌套键，与 point_type 匹配（参见 point 类型 表）。

注意

所有 UUID（info.uuid、每个 point 的 uuid 以及每个 output 的 next_point_uuid）都必须是标准的 RFC 4122 UUID（8-4-4-4-12 十六进制组）。

PointOutput

一个 point 的 outputs 是其传出分支。它们的键不是自由格式的。验证器期望每种 point 类型都有一组确切的键，并会拒绝那些 point 具有错误数量的 outputs 或无法识别的键的 Journey。

字段	类型	描述
identity.key	string	分支键。必须遵循下面的 output 键规则。
identity.order	int	分支的显示顺序。
info.title	string	可选的分支标签。
info.next_point_uuid	string	此分支连接到的下一个 point 的 UUID。可选 — 不设置此值将为用户结束该 Journey，效果与显式的 terminator point 相同。

Output 键

默认（第一个）分支始终命名为 "default"。其他分支命名为 "output1"、"output2" 等（前缀 output 后跟一个从 1 开始的索引）。有两种 point 类型打破了此规则，如下所述。

Point 类型	预期的 output 键
入口点（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	无（没有 outputs）
FILTER	default、output1
BOOLEAN_SPLITTER	default，然后是 output1 … outputN（每个条件一个额外分支。一个简单的“是/否”分割是 default + output1）
WAIT (delay)	default。带有分支分割的动态延迟会添加 output1
WAIT_EVENT	default 是事件未触发分支。output1（或者，在使用条件脚本时，每个条件一个分支）是触发路径
SEND_PUSH with a splitter	default、output1（当消息和送达分割器都开启时，还有 output2）
SEND_EMAIL / SEND_SMS / SEND_LINE / SEND_WHATSAPP with a splitter	default、output1
SEND_WHATSAPP with a quick-reply preset	default，外加每个快速回复一个分支。键是快速回复值本身
AB_SPLITTER	output0、output1、output2 等（每个变体一个。没有 default 分支）

Position

字段	类型	描述
x	float	画布上的水平坐标。
y	float	画布上的垂直坐标。

Point 类型和 point_data

point_data 是一个 one-of 结构：它只携带一个嵌套对象，其键由 point 的 point_type 决定。

point_type	point_data 键	用途
POINT_TYPE_START_BY_SEGMENT	start_by_segment	入口：匹配某个 segment 的用户。
POINT_TYPE_EVENT	message_bus	入口：触发某个 event 的用户。
POINT_TYPE_START_BY_API	start_by_api	入口：通过 Start by API 调用注入的用户。
POINT_TYPE_WAIT	delay	等待一个固定或动态的时间间隔。
POINT_TYPE_WAIT_EVENT	wait_event	等待直到某个 event 发生。
POINT_TYPE_SEND_PUSH	send_push	发送一条推送通知。
POINT_TYPE_SEND_EMAIL	send_email	发送一封电子邮件。
POINT_TYPE_SEND_SMS	send_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	显示一条应用内消息。
POINT_TYPE_BOOLEAN_SPLITTER	boolean_splitter	根据条件（segment、tags 或 event）分割用户。
POINT_TYPE_AB_SPLITTER	ab_splitter	将用户分割成 A/B 组。
POINT_TYPE_FILTER	filter	只允许匹配过滤器的用户继续。
POINT_TYPE_SET_TAGS	set_tags	更新用户 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 参考 中有详细文档。入口、计时、分割和操作点在那里有全面介绍。消息点在信封级别进行介绍，并附有相关渠道文档的链接。

示例 point

一个带有单个下游连接的“设置 tags”点：

{
  "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	评论是否已删除。

枚举

JourneyStatus 枚举

STATUS_DRAFT、STATUS_RUNNING、STATUS_FINISHED、STATUS_ARCHIVED、STATUS_PAUSED、STATUS_UNKNOWN。

CampaignType 枚举

• TriggerBased：用户因事件进入。
• AudienceBased：用户从 segment 进入。
• APIBased：用户通过 Start by API 调用进入。
• Mixed：多种进入类型。
• Unknown：未确定进入类型。

PointType 枚举

有关完整列表以及每种类型映射到的 point_data 键，请参见上方的 point 类型 表。

UserIDTrackChangePolicy 枚举

控制当用户在 Journey 中途其 User ID 发生变化时会发生什么：

• DEFAULT：默认行为。
• TRACK：在新 ID 下继续跟踪用户。
• DROP：当用户 ID 更改时，将其从该 Journey 中移除。

相关

Point 参考

创建和更新

生命周期