Presets API

พรีเซ็ตพุช (push preset) คือเทมเพลตการแจ้งเตือนแบบพุชที่สามารถนำกลับมาใช้ใหม่ได้ — เป็นอ็อบเจกต์เดียวกับที่คุณสร้างในตัวแก้ไขพุชของ Control Panel API นี้จัดการเฉพาะพรีเซ็ตพุชเท่านั้น; พรีเซ็ตของ SMS, WhatsApp, Kakao, LINE และ Viber แต่ละอย่างมีบริการพรีเซ็ตเฉพาะของตัวเอง ซึ่งไม่ครอบคลุมในที่นี้

ใช้ code ของพรีเซ็ตเพื่อส่งผ่าน Notify (payload preset) หรือ Customer Journey Send push point

URL พื้นฐาน

https://rpc-api.svc-nue.pushwoosh.com

Endpoints ทั้งหมดให้บริการผ่าน HTTPS การร้องขอและการตอบกลับใช้ application/json เว้นแต่จะระบุไว้เป็นอย่างอื่น

การยืนยันตัวตน

ทุกคำขอต้องมีเฮดเดอร์ Authorization พร้อมกับ Server API token ของคุณ:

Authorization: Api YOUR_API_TOKEN

ข้อตกลงทั่วไป

การตั้งชื่อฟิลด์: request bodies และ query/path parameters ยอมรับ lowerCamelCase (ตัวอย่างเช่น sendType, localizedProperties, searchByName) — เซิร์ฟเวอร์จะ unmarshal ทั้งสองรูปแบบ การตอบกลับจะถูก marshal โดยใช้ชื่อฟิลด์ของ proto เสมอ ในรูปแบบ snake_case (localized_properties, platform_properties, per_page และอื่นๆ) ตัวอย่างการตอบกลับและข้อมูลอ้างอิง Preset object ด้านล่างใช้รูปแบบนั้น
code: ทุกการตอบกลับของพรีเซ็ตจะมี code ของตัวเอง ซึ่งสร้างขึ้นเมื่อ Create ส่ง code นี้ไปยัง Get, Update, UpdatePartial, Delete, Clone และไปยัง messaging/journey APIs ข้างต้น
คีย์แพลตฟอร์ม: แมป platforms และ open_actions จะใช้ รหัสประเภทอุปกรณ์ (device type code) ที่เป็นตัวเลขเป็นคีย์ (1 สำหรับ iOS, 3 สำหรับ Android และอื่นๆ) platform_properties จะใช้ชื่อ enum ของแพลตฟอร์มเป็นคีย์แทน (IOS, ANDROID, BAIDU_ANDROID, HUAWEI_ANDROID, OSX — ซึ่งเป็นเพียงห้าแพลตฟอร์มที่ครอบคลุม)
ฟิลด์ที่ไม่ได้ระบุค่า: การตอบกลับของ Get, Create และ Clone จะรวมทุกฟิลด์ของ Preset object แม้ว่าจะว่างเปล่าหรือมีค่าเป็นศูนย์ List จะส่งคืนชุดฟิลด์ที่ลดลง — ดู List ด้านล่าง Update และ UpdatePartial จะไม่ส่งคืนฟิลด์พรีเซ็ตใดๆ เลย — ดู ข้อควรระวัง ในส่วนของมัน

การตอบกลับข้อผิดพลาด

สถานะ HTTP	ความหมาย
`400 Bad Request`	อาร์กิวเมนต์ไม่ถูกต้อง — ฟิลด์ที่จำเป็นขาดหายไปหรือมีรูปแบบไม่ถูกต้อง หรือเงื่อนไขเบื้องต้นไม่สำเร็จ (ตัวอย่างเช่น การโคลนโดยไม่มี `name`)
`401 Unauthorized`	เฮดเดอร์ `Authorization` ขาดหายไปหรือไม่ถูกต้อง
`403 Forbidden`	แอปพลิเคชันหรือพรีเซ็ตไม่ได้เป็นของบัญชีของผู้เรียก
`404 Not Found`	ไม่พบพรีเซ็ตหรือแอปพลิเคชัน
`500 Internal Server Error`	ความล้มเหลวที่ไม่คาดคิดฝั่งเซิร์ฟเวอร์

การ Delete พรีเซ็ตที่ยังคงถูกใช้โดย Send push point ของ journey ที่กำลังทำงานหรือหยุดชั่วคราวอยู่ จะส่งคืน 400 Bad Request (เป็น FailedPrecondition บน wire) — ไม่ใช่ 409 ให้ลบพรีเซ็ตออกจาก journey ก่อน

Endpoints

เมธอด	พาธ	คำอธิบาย
`POST`	`/api/presets`	สร้างพรีเซ็ตพุชใหม่
`GET`	`/api/presets`	แสดงรายการพรีเซ็ตพุชของแอปพลิเคชัน
`GET`	`/api/presets/{code}`	รับพรีเซ็ตพุชเดียว
`PUT`	`/api/presets/{code}`	อัปเดตพรีเซ็ตพุช (เขียนทับทั้งหมด)
`PUT`	`/api/presets/{code}:partial`	อัปเดตพรีเซ็ตพุช (บางส่วน)
`POST`	`/api/presets/{code}:clone`	โคลนพรีเซ็ตพุช
`DELETE`	`/api/presets/{code}`	ลบพรีเซ็ตพุช

สร้าง (Create)

สร้างพรีเซ็ตพุชใหม่ในแอปพลิเคชันและส่งคืนพร้อมกับ code ที่สร้างขึ้น

POST /api/presets

Request body

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`application`	string	ใช่	รหัสแอปพลิเคชัน (application code) ที่จะสร้างพรีเซ็ต
`name`	string	ใช่	ชื่อพรีเซ็ต
`sendType`	string	ไม่	ช่องทางของพรีเซ็ต (เช่น `push`)
`isV2`	boolean	ไม่	ปักหมุดแฟล็กต้นกำเนิดของพรีเซ็ต ละเว้นเพื่อตั้งค่าเริ่มต้นเป็น `true` (v2); ตั้งค่า `false` เฉพาะเมื่อต้องการสร้างพรีเซ็ต v1 แบบเก่า

ฟิลด์อื่นๆ ทั้งหมด — เนื้อหาที่แปล, แพลตฟอร์ม, deep link, inbox, หมวดหมู่ และอื่นๆ — จะใช้ร่วมกับ Update และมีเอกสารอธิบายไว้ครั้งเดียวในข้อมูลอ้างอิง Preset object ด้านล่าง

ตัวอย่างคำขอ

{
  "application": "XXXXX-XXXXX",
  "name": "20% discount",
  "platforms": { "1": true, "3": true },
  "localizedContent": {
    "default": "Get your 20% discount right now",
    "es": "Consigue tu 20% de descuento ahora mismo"
  },
  "localizedTitle": { "default": "Hi there" },
  "openAction": { "link": { "url": "https://example.com" } },
  "categories": ["promo"]
}

การตอบกลับ

ส่งคืน { "preset": { ... } } ซึ่งเป็น Preset object ที่สร้างขึ้น

รายการ (List)

แสดงรายการพรีเซ็ตพุชของแอปพลิเคชัน — เป็นชุดฟิลด์ที่ลดลง ไม่ใช่อ็อบเจกต์เต็ม — พร้อมการแบ่งหน้า, การเรียงลำดับ และการกรองตามชื่อหรือหมวดหมู่

GET /api/presets

Query parameters

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`application`	string	ใช่	รหัสแอปพลิเคชันที่จะแสดงรายการพรีเซ็ต
`orderBy`	string	ไม่	`NAME` (ค่าเริ่มต้น), `CREATED` หรือ `UPDATED`
`orderDirection`	string	ไม่	`ASC` (ค่าเริ่มต้น) หรือ `DESC`
`page`	integer	ไม่	ดัชนีหน้าแบบศูนย์ (zero-based)
`perPage`	integer	ไม่	ขนาดหน้า ค่าเริ่มต้นคือ `100` เมื่อละเว้นหรือเป็น `0`
`searchByName`	string	ไม่	การจับคู่สตริงย่อยที่ไม่คำนึงถึงตัวพิมพ์เล็ก-ใหญ่บนชื่อพรีเซ็ต หรือ code (`ILIKE %value%`)
`searchByCategory`	array of strings	ไม่	ทำซ้ำพารามิเตอร์เพื่อกรองตามหมวดหมู่หลายรายการ เช่น `?searchByCategory=promo&searchByCategory=lifecycle`
`showHidden`	boolean	ไม่	รวมพรีเซ็ตที่ทำเครื่องหมาย `hidden`

การตอบกลับ

แต่ละรายการจะมีเพียง: name, code, platforms, localized_content (ข้อความธรรมดาต่อภาษา — ไม่ใช่ localized_properties), localized_title, localized_subtitle, banner, icon, categories, journey_uuid, custom_data, is_v2, created, updated ฟิลด์อื่นๆ ทั้งหมดของ Preset object — localized_properties, platform_properties, deeplink, richmedia, url และอื่นๆ — จะถูกละเว้น แม้ว่าจะตั้งค่าไว้ในพรีเซ็ตก็ตาม

ฟิลด์	ประเภท	คำอธิบาย
`presets`	array of objects	หน้าปัจจุบันของพรีเซ็ต ในรูปแบบที่ลดลงตามที่อธิบายไว้ข้างต้น
`page`	integer	ดัชนีหน้าที่ส่งคืน
`per_page`	integer	ขนาดหน้าที่ใช้สำหรับการตอบกลับนี้
`total`	integer	จำนวนพรีเซ็ตทั้งหมดที่ตรงกับตัวกรอง ในทุกหน้า

ตัวอย่างการตอบกลับ

{
  "presets": [
    { "name": "20% discount", "code": "AAAAA-BBBBB", "platforms": { "1": true, "3": true }, "categories": ["promo"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

รับ (Get)

ส่งคืนพรีเซ็ตพุชเดียวตาม code พร้อมกับทุกฟิลด์ของ Preset object ที่ถูกเติมค่า

GET /api/presets/{code}

Path parameters

พารามิเตอร์	ประเภท	คำอธิบาย
`code`	string	code ของพรีเซ็ต

การตอบกลับ

ส่งคืน { "preset": { ... } } ซึ่งเป็น Preset object แบบเต็ม

อัปเดต (Update)

เขียนทับพรีเซ็ตพุชที่มีอยู่ตาม code ด้วยฟิลด์ที่ให้มา

PUT /api/presets/{code}

Path parameters

พารามิเตอร์	ประเภท	คำอธิบาย
`code`	string	code ของพรีเซ็ตที่จะเขียนทับ

Request body

ฟิลด์เดียวกับ Create (ลบ application) บวกกับฟิลด์ที่เหลือของ Preset object sendType ได้รับการยอมรับแต่จะถูกละเว้น — ช่องทางของพรีเซ็ตไม่สามารถเปลี่ยนแปลงได้หลังจากการสร้าง

Update จะสร้างคุณสมบัติเนื้อหาของพรีเซ็ตใหม่ทั้งหมดในทุกการเรียก: localizedProperties, platformProperties, openAction/openActions, deeplink, deeplinkParams, richmedia, url, campaignCode, filterCode, geoZones, sendRate, cappingCount/cappingDays, ฟิลด์ notification*Url ทั้งสาม, remotePage, wnsContent, originalUrl, แฟล็ก *Silent ทั้งสี่, inboxImage/inboxIcon/inboxDays/inboxDate, banner, icon, customData และ isV2 — หากละเว้นฟิลด์ใดๆ เหล่านี้ มันจะถูกล้าง (หรือสำหรับ isV2 จะถูกรีเซ็ตเป็น true)

name, platforms, categories, localizedTitle, localizedSubtitle และ localizedContent เป็นข้อยกเว้น: แต่ละฟิลด์จะถูกแก้ไขเมื่อคุณส่งมันเท่านั้น และจะถูกปล่อยไว้ไม่เปลี่ยนแปลงเมื่อละเว้น

ใช้ UpdatePartial หากคุณต้องการให้กลุ่มแรกถูกปล่อยไว้ไม่เปลี่ยนแปลงเมื่อละเว้นเช่นกัน

การตอบกลับ

อ็อบเจกต์ว่างเปล่าเมื่อสำเร็จ: {}

อัปเดตบางส่วน (UpdatePartial)

อัปเดตเฉพาะฟิลด์ที่ให้มาของพรีเซ็ตพุชที่มีอยู่ตาม code โดยปล่อยฟิลด์ที่ไม่ได้ตั้งค่าไว้ไม่เปลี่ยนแปลง

PUT /api/presets/{code}:partial

Path parameters

พารามิเตอร์	ประเภท	คำอธิบาย
`code`	string	code ของพรีเซ็ตที่จะแพตช์

Request body

ฟิลด์เดียวกับ Update ลบ application ซึ่งแตกต่างจาก Update ทุกฟิลด์ที่นี่ — รวมถึง localizedProperties, platformProperties, categories และส่วนที่เหลือของกลุ่มคุณสมบัติเนื้อหาที่ระบุไว้ใน ข้อควรระวังของ Update — จะถูกปล่อยไว้ไม่เปลี่ยนแปลงเมื่อละเว้น และจะถูกแก้ไขเมื่อคุณส่งมันเท่านั้น (ฟิลด์ map/array ที่คุณส่งยังคงแทนที่ค่าที่มีอยู่สำหรับฟิลด์นั้นทั้งหมด มันแค่ไม่ส่งผลกระทบต่อสิ่งที่คุณไม่ได้รวมไว้) sendType ก็ได้รับการยอมรับแต่จะถูกละเว้นเช่นกัน

ตัวอย่างคำขอ

{
  "sendRate": 500,
  "cappingCount": 3,
  "cappingDays": 7
}

การตอบกลับ

เป็นอ็อบเจกต์ว่างเปล่าเช่นกัน — ดู ข้อควรระวังข้างต้น

โคลน (Clone)

ทำซ้ำพรีเซ็ตพุชที่มีอยู่ ภายใต้ชื่อใหม่ ไปยังแอปพลิเคชันเดียวกัน

POST /api/presets/{code}:clone

Request body

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`code`	string	ใช่	Code ของพรีเซ็ตต้นฉบับที่จะทำซ้ำ
`name`	string	ใช่	ชื่อสำหรับพรีเซ็ตใหม่

ตัวอย่างคำขอ

{ "code": "AAAAA-BBBBB", "name": "20% discount (copy)" }

การตอบกลับ

ส่งคืน { "preset": { ... } } ซึ่งเป็น Preset object ใหม่

ลบ (Delete)

ลบพรีเซ็ตพุชอย่างถาวรตาม code

DELETE /api/presets/{code}

Path parameters

พารามิเตอร์	ประเภท	คำอธิบาย
`code`	string	code ของพรีเซ็ตที่จะลบ

การตอบกลับ

อ็อบเจกต์ว่างเปล่าเมื่อสำเร็จ: {}

การอ้างอิงอ็อบเจกต์

ชื่อฟิลด์ด้านล่างตรงกับสิ่งที่ Get, Create, Update และ Clone ส่งคืนจริง — ชื่อฟิลด์ proto แบบ snake_case (ดู ข้อตกลงทั่วไป) รูปแบบ lowerCamelCase ที่ใช้ในตัวอย่างคำขอด้านบนทำงานในลักษณะเดียวกันกับอินพุต

Preset object

ข้อมูลระบุตัวตน

ฟิลด์	ประเภท	คำอธิบาย
`code`	string	สร้างขึ้นเมื่อ `Create` ใช้ระบุพรีเซ็ตนี้ในที่อื่นๆ ทั้งหมดใน API
`name`	string	ชื่อพรีเซ็ต
`send_type`	string	ช่องทางของพรีเซ็ต (เช่น `push`)
`is_v2`	boolean	`true` สำหรับพรีเซ็ตที่สร้างหรือย้ายไปยังโมเดลเนื้อหา v2
`system`	boolean	ทำเครื่องหมายพรีเซ็ตว่าเป็นพรีเซ็ตของระบบ/ภายใน
`hidden`	boolean	ซ่อนพรีเซ็ตจากผลลัพธ์ `List` (ส่ง `showHidden: true` เพื่อรวมไว้)
`created`	string (RFC 3339)	ประทับเวลาที่สร้าง
`updated`	string (RFC 3339)	ประทับเวลาที่อัปเดตล่าสุด

การกำหนดเป้าหมายและเนื้อหา

ฟิลด์	ประเภท	คำอธิบาย
`platforms`	map<string, boolean>	แพลตฟอร์มที่พรีเซ็ตกำหนดเป้าหมาย โดยใช้ รหัสประเภทอุปกรณ์ เป็นคีย์ (เช่น `"1"` สำหรับ iOS)
`localized_properties`	map<string, object>	ภาษา → เนื้อหา rich ต่อแพลตฟอร์ม มีรูปแบบเดียวกับ `LocalizedContent` บน payload ของ `Notify` — หนึ่งรายการต่อบล็อกแพลตฟอร์ม (`ios`, `android` และอื่นๆ) นี่เป็นวิธีหลักในการตั้งค่าเนื้อหาพุชเฉพาะแพลตฟอร์ม
`localized_title` / `localized_subtitle` / `localized_content`	map<string, string>	ภาษา → ข้อความธรรมดา เป็นทางเลือกที่ง่ายกว่า `localized_properties` สำหรับหัวข้อ, หัวข้อย่อย และเนื้อหาเมื่อคุณไม่ต้องการการแทนที่ต่อแพลตฟอร์ม
`platform_properties`	map<string, object>	การแทนที่ต่อแพลตฟอร์มแบบเก่า โดยใช้ชื่อ enum ของแพลตฟอร์มเป็นคีย์ (`IOS`, `ANDROID`, `BAIDU_ANDROID`, `HUAWEI_ANDROID`, `OSX`) ดู PlatformProperties object ด้านล่าง
`open_action`	`OpenAction`	การกระทำที่ถูกทริกเกอร์เมื่อผู้ใช้เปิดการแจ้งเตือน ใช้กับทุกแพลตฟอร์ม ไม่สามารถใช้ร่วมกับ `open_actions` — การตอบกลับจะตั้งค่าเพียงหนึ่งอย่างเท่านั้น
`open_actions`	map<string, `OpenAction`>	การแทนที่ `open_action` ต่อแพลตฟอร์ม โดยใช้ รหัสประเภทอุปกรณ์ เป็นคีย์
`deeplink`	string	รหัส Deep Link
`deeplink_params`	map<string, string>	พารามิเตอร์ที่ส่งไปยัง deep link
`richmedia`	string	รหัส Rich Media ที่เปิดโดยการแจ้งเตือน
`url`	string	URL ที่เปิดโดยการแจ้งเตือน หากไม่ได้ใช้ deep link หรือ Rich Media

Inbox

ฟิลด์	ประเภท	คำอธิบาย
`inbox_image`	string	URL รูปภาพที่แสดงในรายการ Message Inbox
`inbox_icon`	string	URL ไอคอนที่แสดงในรายการ Message Inbox
`inbox_days`	integer	จำนวนวันที่รายการจะอยู่ใน Message Inbox
`inbox_date`	string (RFC 3339)	วันหมดอายุที่ชัดเจนสำหรับรายการ Message Inbox เป็นทางเลือกแทน `inbox_days`

การจัดระเบียบและข้อมูลเมตา

ฟิลด์	ประเภท	คำอธิบาย
`categories`	array of strings	ชื่อหมวดหมู่ที่พรีเซ็ตถูกแท็กด้วย
`campaign_code`	string	รหัสแคมเปญ ที่พรีเซ็ตนี้ถูกระบุแหล่งที่มา
`filter_code`	string	รหัส Segment / Filter ที่พรีเซ็ตนี้กำหนดเป้าหมายโดยค่าเริ่มต้น
`geo_zones`	string	การกำหนดเป้าหมาย Geozone หากพรีเซ็ตถูกทริกเกอร์ตามตำแหน่งทางภูมิศาสตร์
`journey_uuid`	string	UUID ของ Customer Journey ที่เป็นเจ้าของพรีเซ็ตนี้ หากสร้างจาก Send push point ของ journey
`custom_data`	object	JSON รูปแบบอิสระที่ส่งต่อไปยัง client SDK เป็นพารามิเตอร์ `u`
`banner`	string	URL รูปภาพขนาดใหญ่ / ไฟล์แนบ
`icon`	string	URL ไอคอนการแจ้งเตือนที่กำหนดเอง

ขีดจำกัดการส่ง

ฟิลด์	ประเภท	คำอธิบาย
`send_rate`	integer	การควบคุมปริมาณการส่งที่ใช้พรีเซ็ตนี้ ในหน่วยข้อความ/วินาที — เทียบเท่ากับ `SendRate` ของ `Notify` ในระดับพรีเซ็ต
`capping_count` / `capping_days`	integer	ขีดจำกัดความถี่ต่อผู้ใช้สำหรับพรีเซ็ตนี้ — เทียบเท่ากับ `count` / `days` ของ `FrequencyCapping` ของ `Notify` ในระดับพรีเซ็ต

Webhooks

ฟิลด์	ประเภท	คำอธิบาย
`notification_sent_url`	string	URL ที่เรียกกลับเมื่อมีการส่งการแจ้งเตือนที่ใช้พรีเซ็ตนี้
`notification_delivered_url`	string	URL ที่เรียกกลับเมื่อมีการส่งมอบการแจ้งเตือนที่ใช้พรีเซ็ตนี้
`notification_click_url`	string	URL ที่เรียกกลับเมื่อมีการคลิกการแจ้งเตือนที่ใช้พรีเซ็ตนี้

ฟิลด์แบบเก่า

สิ่งเหล่านี้มาจากโมเดลพรีเซ็ต v1 ถูกเติมค่าเพื่อความเข้ากันได้กับ Control Panel มากกว่าสำหรับการผสานรวมใหม่

ฟิลด์	ประเภท	คำอธิบาย
`remote_page`	string	การอ้างอิงหน้าเว็บระยะไกลแบบเก่า
`wns_content`	string	JSON เทมเพลต toast ของ Windows แบบเก่า ตามที่ยอมรับโดยเมธอด `createPreset`/`getPreset` ของ v1
`original_url`	string	ค่าของ `url` ก่อนการย่อ เมื่อ `url` ถูกแทนที่ด้วยลิงก์ที่ย่อแล้ว
`ios_silent` / `android_silent` / `baidu_android_silent` / `huawei_android_silent`	boolean	แฟล็กพุชแบบเงียบ (ข้อมูลเท่านั้น) ต่อแพลตฟอร์ม

PlatformProperties object

ฟิลด์ที่มีในแต่ละรายการ platform_properties (IOS, ANDROID, BAIDU_ANDROID, HUAWEI_ANDROID, OSX):

ฟิลด์	ประเภท	คำอธิบาย
`badge`	string	การแทนที่จำนวน badge
`sound`	string	ชื่อไฟล์เสียง
`sound_off`	boolean	ปิดเสียงการแจ้งเตือน
`priority`	string	ลำดับความสำคัญในถาด (Android/Baidu/Huawei เท่านั้น)
`delivery_priority`	string	ลำดับความสำคัญในการส่ง `NORMAL` หรือ `HIGH` (Android/Baidu/Huawei เท่านั้น)
`ios_interruption_level`	string	`passive`, `active`, `time-sensitive` หรือ `critical` (iOS เท่านั้น)

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

Notify

การอ้างอิง Payload

การอ้างอิงพอยต์ Customer Journey