Presets API

Push preset คือเทมเพลตการแจ้งเตือนแบบพุชที่สามารถนำกลับมาใช้ใหม่ได้ ซึ่งเป็นอ็อบเจกต์เดียวกับที่คุณสร้างในตัวแก้ไขพุชของ Control Panel API นี้จัดการเฉพาะ push presets เท่านั้น ส่วนพรีเซ็ตของ 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

ข้อตกลง

การตั้งชื่อฟิลด์: ส่วนเนื้อหาของคำขอและพารามิเตอร์ของ query/path ยอมรับ lowerCamelCase (ตัวอย่างเช่น sendType, localizedProperties, searchByName) — เซิร์ฟเวอร์จะ unmarshal ทั้งสองรูปแบบ การตอบกลับจะถูก marshaled โดยใช้ชื่อฟิลด์ proto ในรูปแบบ snake_case เสมอ (localized_properties, platform_properties, per_page และอื่นๆ) ตัวอย่างการตอบกลับและการอ้างอิง Preset object ด้านล่างใช้รูปแบบนั้น
code: การตอบกลับของพรีเซ็ตทุกรายการจะมี code ของตัวเอง ซึ่งสร้างขึ้นเมื่อ Create ส่ง code นี้ไปยัง Get, Update, UpdatePartial, Delete, Clone และไปยัง API การส่งข้อความ/journey ที่กล่าวถึงข้างต้น
คีย์แพลตฟอร์ม: แมป platforms และ open_actions จะใช้ device type code ที่เป็นตัวเลขเป็นคีย์ (1 สำหรับ iOS, 3 สำหรับ Android และอื่นๆ) ส่วน platform_properties จะใช้ชื่อ enum ของแพลตฟอร์มเป็นคีย์แทน (IOS, 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`	สร้าง push preset ใหม่
`GET`	`/api/presets`	แสดงรายการ push presets ของแอปพลิเคชัน
`GET`	`/api/presets/{code}`	ดึงข้อมูล push preset รายการเดียว
`PUT`	`/api/presets/{code}`	อัปเดต push preset (เขียนทับทั้งหมด)
`PUT`	`/api/presets/{code}:partial`	อัปเดต push preset (บางส่วน)
`POST`	`/api/presets/{code}:clone`	โคลน push preset
`DELETE`	`/api/presets/{code}`	ลบ push preset

สร้าง

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

POST /api/presets

เนื้อหาของคำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`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 ที่สร้างขึ้น

รายการ

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

GET /api/presets

พารามิเตอร์ของ Query

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`application`	string	ใช่	Application code ที่จะแสดงรายการพรีเซ็ต
`orderBy`	string	ไม่	`NAME` (ค่าเริ่มต้น), `CREATED` หรือ `UPDATED`
`orderDirection`	string	ไม่	`ASC` (ค่าเริ่มต้น) หรือ `DESC`
`page`	integer	ไม่	ดัชนีหน้าแบบเริ่มต้นที่ศูนย์
`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
}

ดึงข้อมูล

ส่งคืน push preset รายการเดียวตาม code ของมัน โดยมีทุกฟิลด์ของ Preset object ที่ระบุค่าไว้

GET /api/presets/{code}

พารามิเตอร์ของ Path

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

การตอบกลับ

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

อัปเดต

เขียนทับ push preset ที่มีอยู่ตาม code ด้วยฟิลด์ที่ให้มา

PUT /api/presets/{code}

พารามิเตอร์ของ Path

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

เนื้อหาของคำขอ

ฟิลด์เดียวกับ 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 หากคุณต้องการให้กลุ่มแรกถูกปล่อยไว้ไม่เปลี่ยนแปลงเมื่อละเว้นด้วยเช่นกัน

การตอบกลับ

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

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

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

PUT /api/presets/{code}:partial

พารามิเตอร์ของ Path

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

เนื้อหาของคำขอ

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

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

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

การตอบกลับ

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

โคลน

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

POST /api/presets/{code}:clone

เนื้อหาของคำขอ

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

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

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

การตอบกลับ

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

ลบ

ลบ push preset อย่างถาวรตาม code

DELETE /api/presets/{code}

พารามิเตอร์ของ Path

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

กล่องข้อความ

ฟิลด์	ประเภท	คำอธิบาย
`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	Campaign code ที่พรีเซ็ตนี้ถูกระบุแหล่งที่มา
`filter_code`	string	Segment / Filter code ที่พรีเซ็ตนี้กำหนดเป้าหมายโดยค่าเริ่มต้น
`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` / `huawei_android_silent`	boolean	แฟล็กพุชแบบเงียบ (ข้อมูลเท่านั้น) ต่อแพลตฟอร์ม

PlatformProperties object

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

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

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

Notify

การอ้างอิง Payload

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