Journey 객체

수명 주기, 생성 및 업데이트 메서드는 모두 동일한 최상위 구조를 가진 journey 객체를 반환합니다:

구조

{
  "info": { ... },        // 읽기 전용 메타데이터 (응답에만 해당)
  "params": { ... },      // Journey 전체 구성 (생성/업데이트)
  "points": [ ... ],      // 캔버스 노드 및 연결
  "comments": [ ... ]     // 캔버스 주석
}

Journey를 생성하거나 업데이트할 때 title, params, points, comments를 전송합니다. 응답은 info( params 포함)와 points, comments를 반환합니다.

정보

읽기 전용 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>	유형별 포인트 수.
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	Journey 중간에 사용자 ID가 변경될 때 처리하는 방법.

SilentHours

조용한 시간 동안 메시지 전송을 억제합니다. 채널별로 구성되며, 각 채널은 자체 SilentHoursParams를 가집니다:

필드	유형	설명
push_params	SilentHoursParams	푸시 알림에 대한 자동 전송 제한 시간.
inapp_params	SilentHoursParams	인앱 메시지에 대한 자동 전송 제한 시간.
email_params	SilentHoursParams	이메일에 대한 자동 전송 제한 시간.
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[]	해당 기간이 적용되는 요일에 대한 7개의 불리언 값 (월요일 = 인덱스 0).
behavior	enum	메시지가 자동 전송 제한 시간 내에 있을 때 수행할 작업: WaitAndSend (기간이 끝날 때까지 보류 후 전송), DropAndGo (메시지를 건너뛰고 즉시 Journey를 계속), 또는 WaitAndDrop (기간이 끝날 때까지 기다린 후 메시지를 보내지 않고 계속).

EntryCapping

동일한 사용자가 Journey에 진입할 수 있는 빈도를 제한합니다.

필드	유형	설명
is_enabled	bool	진입 제한이 켜져 있는지 여부.
period	uint64	사용자 진입 사이의 최소 시간(분). 0은 사용자가 평생 한 번만 진입할 수 있음을 의미합니다.

제한은 사용자가 Journey에 진입한 순간부터 계산되며, 사용자 ID별로 추적되므로 한 사용자의 모든 기기는 단일 진입을 공유합니다. 기간이 지속되는 동안 진입 지점은 추가 진입 시도를 거부하고 여행자를 생성하는 대신 오류로 계산합니다.

이 설정을 변경할 때 고려해야 할 세 가지 동작:

• Journey를 조기에 떠나도 제한이 해제되지 않습니다. 사용자는 종료 지점에 도달한 후에도 전체 기간을 기다립니다.
• 변경된 period는 업데이트 후의 진입에 적용됩니다. 이전에 진입한 사용자는 진입 시점에 유효했던 기간을 유지합니다.
• is_enabled를 false로 설정하면 모든 사용자에 대해 즉시 제한이 해제됩니다.

참고

Control Panel은 캠페인 진입 제한에서 동일한 필드를 작성하며, 0(평생 한 번), 1440(하루에 한 번), 10080(일주일에 한 번), 43800(한 달에 한 번), 131500(3개월에 한 번)을 제공합니다.

ConversionWindow

필드	유형	설명
seconds	uint64	사용자가 Journey에 진입한 후 목표 달성이 전환으로 계산되는 기간(초).

Point

포인트는 Journey 캔버스의 노드입니다: 진입 지점, 메시지, 지연, 분기점 등.

필드	유형	설명
uuid	string	Journey 내에서 포인트의 고유 ID. 정식 RFC 4122 UUID여야 합니다: 8-4-4-4-12 그룹의 32개 16진수 숫자.
title	string	포인트의 표시 이름.
point_type	PointType	노드의 종류.
outputs	array of PointOutput	하위 포인트로의 연결.
position	Position	캔버스 좌표.
point_data	object	point_type과 일치하는 정확히 하나의 중첩된 키 (포인트 유형 및 point_data 표 참조).

참고

모든 UUID(info.uuid, 모든 포인트 uuid, 각 출력의 next_point_uuid)는 정식 RFC 4122 UUID(8-4-4-4-12 16진수 그룹)여야 합니다.

PointOutput

포인트의 출력은 나가는 분기입니다. 키는 자유 형식이 아닙니다. 유효성 검사기는 각 포인트 유형에 대해 정확한 키 세트를 예상하며, 포인트에 잘못된 수의 출력이 있거나 인식할 수 없는 키가 있는 Journey를 거부합니다.

필드	유형	설명
identity.key	string	분기 키. 아래의 출력 키 규칙을 따라야 합니다.
identity.order	int	분기의 표시 순서.
info.title	string	선택적 분기 레이블.
info.next_point_uuid	string	이 분기가 연결되는 다음 포인트의 UUID. 선택 사항 — 설정하지 않으면 명시적인 terminator 포인트와 동일하게 사용자의 Journey가 종료됩니다.

출력 키

기본(첫 번째) 분기는 항상 "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는 one-of입니다: 포인트의 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	푸시 알림 전송.
POINT_TYPE_SEND_EMAIL	send_email	이메일 전송.
POINT_TYPE_SEND_SMS	send_sms	SMS 전송.
POINT_TYPE_SEND_WHATSAPP	send_whatsapp	WhatsApp 메시지 전송.
POINT_TYPE_SEND_TELEGRAM	send_telegram	텔레그램 메시지 전송.
POINT_TYPE_SEND_KAKAO	send_kakao	카카오 메시지 전송.
POINT_TYPE_SEND_LINE	send_line	LINE 메시지 전송.
POINT_TYPE_SEND_DATA	send_data	자동 데이터 메시지 전송.
POINT_TYPE_INAPP	inapp	인앱 메시지 표시.
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 중간에 있을 때 사용자 ID가 변경될 때 발생하는 일을 제어합니다:

• DEFAULT: 기본 동작.
• TRACK: 새 ID로 사용자를 계속 추적합니다.
• DROP: ID가 변경될 때 Journey에서 사용자를 제거합니다.

관련 항목

포인트 참조

생성 및 업데이트

수명 주기