อ็อบเจกต์ Journey

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

{
  "info": { ... },        // metadata แบบอ่านอย่างเดียว (เฉพาะการตอบกลับ)
  "params": { ... },      // การกำหนดค่าทั่วทั้ง journey (สร้าง / อัปเดต)
  "points": [ ... ],      // โหนดบน canvas และการเชื่อมต่อ
  "comments": [ ... ]     // ความคิดเห็นบน canvas
}

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

Info

metadata ของ journey แบบอ่านอย่างเดียว ส่งคืนโดยทุกเมธอด 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

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

ฟิลด์	ประเภท	คำอธิบาย
`push_params`	`SilentHoursParams`	ช่วงเวลาห้ามส่งสำหรับ push notifications
`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[]	ค่าบูลีนเจ็ดค่าสำหรับวันที่ช่วงเวลาห้ามส่งมีผล (วันจันทร์ = index 0)
`behavior`	enum	สิ่งที่ต้องทำเมื่อข้อความตกอยู่ในช่วงเวลาห้ามส่ง: `WaitAndSend` (พักไว้ แล้วส่งเมื่อสิ้นสุดช่วงเวลา), `DropAndGo` (ข้ามข้อความ ดำเนินการ journey ต่อทันที), หรือ `WaitAndDrop` (รอจนสิ้นสุดช่วงเวลา แล้วดำเนินการต่อโดยไม่ส่ง)

EntryCapping

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

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

ขีดจำกัดจะนับจากช่วงเวลาที่ผู้ใช้เข้าสู่ journey และจะถูกติดตามต่อ user ID ดังนั้นอุปกรณ์ทั้งหมดของผู้ใช้คนหนึ่งจะใช้การเข้าร่วมเดียวกัน ในขณะที่ช่วงเวลายังคงอยู่ จุดเริ่มต้นจะปฏิเสธความพยายามในการเข้าเพิ่มเติมและนับเป็นข้อผิดพลาดแทนที่จะสร้าง traveler

พฤติกรรมสามอย่างที่ต้องคำนึงถึงเมื่อคุณเปลี่ยนการตั้งค่าเหล่านี้:

การออกจาก journey ก่อนกำหนดจะไม่ปลดปล่อยขีดจำกัด ผู้ใช้จะรอจนครบระยะเวลาเต็มแม้ว่าจะถึงจุดออกแล้วก็ตาม
period ที่เปลี่ยนแปลงจะมีผลกับการเข้าที่เกิดขึ้นหลังจากการอัปเดต ผู้ใช้ที่เข้ามาก่อนหน้านี้จะยังคงใช้ระยะเวลาที่มีผลบังคับใช้เมื่อพวกเขาเข้ามา
การตั้งค่า is_enabled เป็น false จะยกเลิกขีดจำกัดสำหรับผู้ใช้ทุกคนทันที

ConversionWindow

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

Point

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

ฟิลด์	ประเภท	คำอธิบาย
`uuid`	string	ID ที่ไม่ซ้ำกันของ point ภายใน journey ต้องเป็น RFC 4122 UUID แบบ canonical: เลขฐานสิบหก 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)

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

สาขาเริ่มต้น (แรก) จะมีชื่อว่า "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`, บวกหนึ่งสาขาต่อการตอบกลับด่วน คีย์คือค่าของการตอบกลับด่วนนั้นเอง
`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`	ส่งข้อความข้อมูลแบบเงียบ
`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`	อัปเดต user tags
`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

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