ออบเจ็กต์ Journey

เมธอด lifecycle, create และ update ทั้งหมดจะส่งคืนออบเจ็กต์ Journey ที่มีรูปร่างระดับบนสุดเหมือนกัน:

Shape

{
  "info": { ... },        // read-only metadata (responses only)
  "params": { ... },      // journey-wide configuration (create / update)
  "points": [ ... ],      // canvas nodes and their connections
  "comments": [ ... ]     // canvas comments
}

เมื่อคุณ สร้าง (create) หรือ อัปเดต (update) Journey คุณจะส่ง title, params, points และ comments การตอบกลับจะส่งคืน info (ซึ่งมี params) พร้อมด้วย points และ comments

Info

ข้อมูลเมตาของ Journey แบบอ่านอย่างเดียว (Read-only) ส่งคืนโดยทุกเมธอด v3 ไม่ใช่ส่วนหนึ่งของเนื้อหาคำขอ (request body)

ฟิลด์	ประเภท	คำอธิบาย
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	ระบุว่าเปิดใช้งานการเข้าแบบไดนามิก (dynamic entry) หรือไม่

JourneyParams

การกำหนดค่าทั่วทั้ง Journey ส่งเมื่อสร้าง/อัปเดต และส่งคืนภายใน info.params

ฟิลด์	ประเภท	คำอธิบาย
application_code	string	Application code ที่ Journey เป็นส่วนหนึ่ง จำเป็นต้องระบุเมื่อสร้าง
silent_hours	SilentHours	ช่วงเวลาที่ข้อความจะถูกระงับต่อช่องทาง
capping	EntryCapping	จำกัดความถี่ที่ผู้ใช้สามารถเข้าสู่ Journey ซ้ำได้
conversion_window	ConversionWindow	กรอบเวลาสำหรับการระบุ conversion ของเป้าหมาย
user_id_track_change_policy	UserIDTrackChangePolicy	วิธีจัดการเมื่อ ID ของผู้ใช้เปลี่ยนแปลงกลาง Journey

SilentHours

ระงับการส่งในช่วงเวลาที่กำหนด (quiet hours) กำหนดค่า ต่อช่องทาง (per channel): แต่ละช่องทางใช้ SilentHoursParams ของตัวเอง:

ฟิลด์	ประเภท	คำอธิบาย
push_params	SilentHoursParams	Silent hours สำหรับ push notifications
inapp_params	SilentHoursParams	Silent hours สำหรับ in-app messages
email_params	SilentHoursParams	Silent hours สำหรับอีเมล
sms_params	SilentHoursParams	Silent hours สำหรับ SMS
whatsapp_params	SilentHoursParams	Silent hours สำหรับ WhatsApp
line_params	SilentHoursParams	Silent hours สำหรับ LINE

แต่ละ SilentHoursParams คือ:

ฟิลด์	ประเภท	คำอธิบาย
enabled	bool	ระบุว่า silent hours มีผลกับช่องทางนี้หรือไม่
from_time	Time	เวลาเริ่มต้นของช่วงเวลาที่กำหนด: { "hour": 0–23, "minute": 0–59 }
to_time	Time	เวลาสิ้นสุดของช่วงเวลาที่กำหนด
week_days	bool[]	ค่าบูลีนเจ็ดค่าสำหรับวันที่กรอบเวลามีผล (วันจันทร์ = index 0)
behavior	enum	สิ่งที่ต้องทำเมื่อข้อความตกอยู่ในช่วง silent hours: WaitAndSend (พักไว้ แล้วส่งเมื่อสิ้นสุดช่วงเวลา), DropAndGo (ข้ามข้อความ แล้วดำเนิน Journey ต่อทันที) หรือ WaitAndDrop (รอจนสิ้นสุดช่วงเวลา แล้วดำเนินต่อโดยไม่ส่ง)

EntryCapping

จำกัดความถี่ที่ผู้ใช้คนเดียวกันสามารถเข้าสู่ Journey ได้

ฟิลด์	ประเภท	คำอธิบาย
is_enabled	bool	ระบุว่าเปิดใช้งานการจำกัดการเข้า (entry capping) หรือไม่
period	uint64	จำนวนวินาทีขั้นต่ำระหว่างการเข้าของผู้ใช้แต่ละครั้ง

ConversionWindow

ฟิลด์	ประเภท	คำอธิบาย
seconds	uint64	ระยะเวลาหลังจากเข้าสู่ Journey ที่การบรรลุเป้าหมายของผู้ใช้ยังคงนับเป็น conversion

Point

Point คือโหนดบน Journey canvas: จุดเริ่มต้น (entry point), ข้อความ, การหน่วงเวลา (delay), ตัวแยก (splitter) และอื่นๆ

ฟิลด์	ประเภท	คำอธิบาย
uuid	string	ID ที่ไม่ซ้ำกันของ point ภายใน Journey ต้องเป็น UUID ตามมาตรฐาน RFC 4122: เลขฐานสิบหก 32 หลักในกลุ่ม 8-4-4-4-12
title	string	ชื่อที่แสดงของ point
point_type	PointType	ประเภทของโหนด
outputs	array of PointOutput	การเชื่อมต่อไปยัง point ถัดไป
position	Position	พิกัดบน canvas
point_data	object	คีย์ที่ซ้อนกันเพียงหนึ่งคีย์ ซึ่งตรงกับ point_type (ดูตาราง ประเภท point)

หมายเหตุ

UUID ทั้งหมด (info.uuid, uuid ของทุก point และ next_point_uuid ของแต่ละ output) ต้องเป็น UUID ตามมาตรฐาน RFC 4122 (กลุ่มเลขฐานสิบหก 8-4-4-4-12)

PointOutput

Output ของ point คือสาขาขาออก คีย์ของมัน ไม่ใช่รูปแบบอิสระ ตัวตรวจสอบ (validator) คาดหวังชุดคีย์ที่แน่นอนสำหรับแต่ละประเภท point และจะปฏิเสธ Journey ที่มี point ที่มีจำนวน output ไม่ถูกต้องหรือมีคีย์ที่ไม่รู้จัก

ฟิลด์	ประเภท	คำอธิบาย
identity.key	string	คีย์ของสาขา ต้องเป็นไปตาม กฎของคีย์ output ด้านล่าง
identity.order	int	ลำดับการแสดงผลของสาขา
info.title	string	ป้ายกำกับสาขา (ไม่บังคับ)
info.next_point_uuid	string	UUID ของ point ถัดไปที่สาขานี้เชื่อมต่อถึง ไม่บังคับ — การเว้นว่างไว้จะสิ้นสุด Journey สำหรับผู้ใช้ เช่นเดียวกับ point terminator ที่ระบุอย่างชัดเจน

Output keys

สาขาเริ่มต้น (สาขาแรก) จะมีชื่อว่า "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	ไม่มี (ไม่มี output)
FILTER	default, output1
BOOLEAN_SPLITTER	default จากนั้น output1 … outputN (หนึ่งสาขาเพิ่มเติมต่อเงื่อนไข การแยกแบบใช่/ไม่ใช่แบบง่ายคือ default + output1)
WAIT (delay)	default การหน่วงเวลาแบบไดนามิกพร้อมการแยกสาขาจะเพิ่ม output1
WAIT_EVENT	default คือสาขาที่ event-not-triggered (เหตุการณ์ไม่ถูกทริกเกอร์) output1 (หรือหนึ่งสาขาต่อเงื่อนไขด้วยสคริปต์เงื่อนไข) คือเส้นทางที่ถูกทริกเกอร์
SEND_PUSH พร้อมตัวแยก	default, output1 (และ output2 เมื่อเปิดใช้งานทั้งตัวแยกข้อความและตัวแยกการจัดส่ง)
SEND_EMAIL / SEND_SMS / SEND_LINE / SEND_WHATSAPP พร้อมตัวแยก	default, output1
SEND_WHATSAPP พร้อม preset การตอบกลับด่วน	default พร้อมด้วยหนึ่งสาขาต่อการตอบกลับด่วน (quick reply) คีย์คือค่าของการตอบกลับด่วนนั้นเอง
AB_SPLITTER	output0, output1, output2, … (หนึ่งรายการต่อแต่ละรูปแบบ ไม่มีสาขา default)

Position

ฟิลด์	ประเภท	คำอธิบาย
x	float	พิกัดแนวนอนบน canvas
y	float	พิกัดแนวตั้งบน canvas

ประเภท point และ point_data

point_data เป็นแบบ one-of: มันมีออบเจ็กต์ซ้อนกันเพียงหนึ่งรายการซึ่งคีย์ถูกกำหนดโดย point_type ของ point

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	ส่ง push notification
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	ส่งข้อความ Telegram
POINT_TYPE_SEND_KAKAO	send_kakao	ส่งข้อความ Kakao
POINT_TYPE_SEND_LINE	send_line	ส่งข้อความ LINE
POINT_TYPE_SEND_DATA	send_data	ส่งข้อความข้อมูลแบบเงียบ (silent data message)
POINT_TYPE_INAPP	inapp	แสดง in-app message
POINT_TYPE_BOOLEAN_SPLITTER	boolean_splitter	แยกผู้ใช้ตามเงื่อนไข (segment, tag หรือ event)
POINT_TYPE_AB_SPLITTER	ab_splitter	แยกผู้ใช้เป็นกลุ่ม A/B
POINT_TYPE_FILTER	filter	อนุญาตให้เฉพาะผู้ใช้ที่ตรงกับตัวกรอง (filter) ดำเนินการต่อ
POINT_TYPE_SET_TAGS	set_tags	อัปเดต tag ของผู้ใช้
POINT_TYPE_WEBHOOK	web_hook	ส่งคำขอ HTTP ขาออก
POINT_TYPE_GOAL_EVENT	goal_event	ติดตามเป้าหมาย conversion
POINT_TYPE_AUDIENCE_SYNC	audience_sync	ซิงค์ผู้ใช้กับ audience ภายนอก
POINT_TYPE_EXIT	terminator	ออกจาก Journey

หมายเหตุ

เพย์โหลด point_data สำหรับแต่ละประเภทมีเอกสารประกอบอยู่ใน Point reference จุดเริ่มต้น (Entry), การกำหนดเวลา (timing), การแยก (splitting) และจุดดำเนินการ (action points) ได้รับการครอบคลุมอย่างเต็มที่ในนั้น จุดส่งข้อความ (Messaging points) ได้รับการครอบคลุมในระดับ envelope พร้อมลิงก์ไปยังเอกสารของช่องทางที่เกี่ยวข้อง

ตัวอย่าง point

point “set tags” ที่มีการเชื่อมต่อดาวน์สตรีมเดียว:

{
  "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	พิกัดบน canvas
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: ผู้ใช้เข้าสู่ระบบเมื่อมี event
• AudienceBased: ผู้ใช้เข้าสู่ระบบจาก segment
• APIBased: ผู้ใช้เข้าสู่ระบบผ่านการเรียก Start by API
• Mixed: มีประเภทการเข้ามากกว่าหนึ่งประเภท
• Unknown: ไม่ได้กำหนดประเภทการเข้า

PointType enum

ดูตาราง ประเภท point ด้านบนสำหรับรายการทั้งหมดและคีย์ point_data ที่แต่ละรายการแมปไป

UserIDTrackChangePolicy enum

ควบคุมสิ่งที่เกิดขึ้นกับผู้ใช้ที่อยู่ระหว่าง Journey เมื่อ User ID ของพวกเขาเปลี่ยนแปลง:

• DEFAULT: พฤติกรรมเริ่มต้น
• TRACK: ติดตามผู้ใช้ต่อไปภายใต้ ID ใหม่
• DROP: นำผู้ใช้ออกจาก Journey เมื่อ ID ของพวกเขาเปลี่ยนแปลง

ที่เกี่ยวข้อง

ข้อมูลอ้างอิง Point

สร้างและอัปเดต

วงจรชีวิต (Lifecycle)