Notify

POST https://api.pushwoosh.com/messaging/v2/notify

สร้างและกำหนดเวลาส่งข้อความเดียว

โครงสร้างคำขอ

ส่วน body ของคำขอคือ NotifyRequest ซึ่งมีหนึ่งในสองประเภทเท่านั้น:

• segment: กำหนดเป้าหมายไปยังกลุ่มเป้าหมาย (audience segment) ด้วยรหัส segment หรือ — โดยไม่ต้องสร้าง segment ก่อน — ด้วยนิพจน์ seglang หรือนิพจน์ตัวกรองแบบมีโครงสร้าง
• transactional: ส่งไปยังรายการที่ระบุชัดเจนของ hwids, user IDs, push tokens หรืออุปกรณ์ทดสอบ

Shape

{
  "segment": { ... },      // หรือ
  "transactional": { ... },
  "transaction_id": "unique-uuid"
}

ฟิลด์	ประเภท	คำอธิบาย
transaction_id	string	ตัวเลือก. Idempotency key สำหรับคำขอ — ทำงานได้ทั้งกับ segment และ transactional การเรียกซ้ำด้วย transaction_id เดียวกันภายใน 5 นาทีจะคืนค่า message_code เดิมแทนที่จะส่งข้อความซ้ำ ใช้ UUID หรือค่าอื่นที่ไม่ซ้ำกันสำหรับการส่งแต่ละครั้ง

เคล็ดลับ

ส่ง header X-Request-ID เพื่อเชื่อมโยงข้อความที่สร้างขึ้นกับคำขอของคุณสำหรับการติดตามแบบ end-to-end — ดูที่ Request ID

Only the key is checked, not the payload

การขจัดข้อมูลซ้ำซ้อนจะจับคู่กับ transaction_id เพียงอย่างเดียว หากการลองใหม่ใช้ transaction_id เดิมแต่ส่ง body ของ segment / transactional ที่แตกต่างกัน ระบบจะยังคงคืนค่า message_code เดิมและ body ใหม่จะถูกละทิ้งโดยไม่มีการแจ้งเตือน — จะไม่มีการเปรียบเทียบกับคำขอแรก ห้ามใช้ transaction_id ซ้ำกับข้อความที่แตกต่างกันในเชิงตรรกะ

เคล็ดลับ

นี่เป็นกลไกการขจัดข้อมูลซ้ำซ้อนแบบเดียวกับ transactionId ใน Messages API รุ่นเก่า โดยใช้หน้าต่างการจัดเก็บข้อมูล 5 นาทีเดียวกัน ดังนั้นคำขอที่ลองใหม่จะถูกขจัดข้อมูลซ้ำซ้อนทั้งใน /createMessage และ Notify เหมือนกัน ไม่เกี่ยวข้องกับ attribute transaction_id ใน event รายได้ PW_Conversion ซึ่ง Pushwoosh จะจัดเก็บตามที่เป็นอยู่และไม่ใช้สำหรับการขจัดข้อมูลซ้ำซ้อน

NotifySegment

กำหนดเป้าหมายผู้ใช้ที่ตรงกับ audience segment หรือนิพจน์ตัวกรอง ตั้งค่าเพียงหนึ่งใน code, expression หรือ filter_expression เท่านั้น สำหรับ expression และ filter_expression ไม่จำเป็นต้องสร้าง segment ไว้ล่วงหน้า — นิพจน์จะถูกประเมินผลแบบ inline สำหรับการส่งครั้งนี้เท่านั้น

Choosing between code and inline expressions

เฉพาะ segment ที่บันทึกไว้ซึ่งอ้างอิงโดย code เท่านั้นที่สามารถใช้การ precompilation ของ high-speed delivery ได้ expression และ filter_expression จะถูกประเมินผล ณ เวลาที่ส่งและจะไม่ถูก precompile เลย

ฟิลด์	ประเภท	คำอธิบาย
schedule	Schedule	จะส่งเมื่อไหร่และอย่างไร จำเป็น
application	string	Application code
platforms	array of Platform	แพลตฟอร์มที่ข้อความจะส่งไปถึง
code	string	Segment code ของ segment ที่บันทึกไว้ล่วงหน้า ไม่สามารถใช้ร่วมกับ expression และ filter_expression ได้
expression	string	นิพจน์ Seglang ซึ่งจะถูกประเมินผลสำหรับการส่งครั้งนี้เท่านั้น — ไม่จำเป็นต้องมี segment ที่บันทึกไว้ ไม่สามารถใช้ร่วมกับ code และ filter_expression ได้
filter_expression	FilterExpression	ตรรกะเดียวกับ expression แต่เป็น object ที่มีโครงสร้างแทนที่จะเป็นสตริง seglang ไม่สามารถใช้ร่วมกับ code และ expression ได้ สคีมา FilterExpression ไม่ได้เปิดเผยต่อสาธารณะ — โปรดขอจากฝ่ายสนับสนุนของ Pushwoosh หากคุณต้องการรูปแบบที่มีโครงสร้าง
payload	Payload	Payload ของ Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger ไม่สามารถใช้ร่วมกับ email_payload ได้
email_payload	EmailPayload	Payload ของอีเมล
campaign	string	Campaign code เพื่อระบุว่าข้อความนี้เป็นของแคมเปญใด
campaign_name	string	ชื่อภายในสำหรับข้อความนี้ แสดงเป็นชื่อหัวข้อแถวใน Message History และในการส่งออก ไม่เกี่ยวข้องกับ campaign ด้านบน ไม่จัดกลุ่มข้อความหรือส่งผลต่อการส่ง สูงสุด 255 ตัวอักษร ถูกตัดให้สั้นลง ละเว้นหรือปล่อยว่างไว้ เพื่อให้ชื่อหัวข้อแถวมาจากเนื้อหาของ payload เอง
frequency_capping	FrequencyCapping	การจำกัดความถี่ต่อผู้ใช้
send_rate	SendRate	การควบคุมอัตราการส่ง
message_type	MessageType	MESSAGE_TYPE_MARKETING (ค่าเริ่มต้น) หรือ MESSAGE_TYPE_TRANSACTIONAL ควบคุมการกรองของกลุ่มควบคุม (control-group)
dynamic_content_placeholders	map<string, string>	แทนที่ placeholders ในเนื้อหา
meta_data	object	ข้อมูลเมตาแบบอิสระที่ส่งต่อไปยังระบบวิเคราะห์ข้อมูลปลายทาง
use_latest_user_device	bool	เมื่อเป็น true จะส่งข้อความไปยังอุปกรณ์ที่ใช้งานล่าสุดของผู้ใช้แต่ละคน (อุปกรณ์ที่มี Last Application Open ล่าสุด) แทนที่จะส่งไปยังทุกอุปกรณ์ที่ตรงกับ segment ขอบเขตจะจำกัดอยู่ที่ platforms: จะพิจารณาเฉพาะอุปกรณ์บนแพลตฟอร์มเหล่านั้น และหากไม่มีอุปกรณ์ใดมีข้อมูล Last Application Open ระบบจะใช้อุปกรณ์แรกที่ตรงกันแทนที่จะยกเลิกการส่ง ค่าเริ่มต้นคือ false (ส่งไปยังทุกอุปกรณ์)

ตัวอย่าง: ส่งไปยัง segment

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "code": "active_users",
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "ios":     { "body": "Hello!" },
              "android": { "body": "Hello!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

NotifyTransactional

ส่งไปยังรายชื่อผู้รับที่ระบุไว้อย่างชัดเจน

ฟิลด์	ประเภท	คำอธิบาย
schedule	Schedule	จำเป็น
application	string	Application code
platforms	array of Platform	แพลตฟอร์มที่ข้อความจะส่งไปถึง
test_devices	bool	ถ้าเป็น true จะส่งไปยังอุปกรณ์ทดสอบของแอปเท่านั้น
hwids	{ "list": [string, ...] }	ส่งไปยัง hwids เหล่านี้เท่านั้น
users	{ "list": [string, ...] }	ส่งไปยัง user IDs เหล่านี้เท่านั้น
push_tokens	{ "list": [string, ...] }	ส่งไปยัง push tokens เหล่านี้เท่านั้น
payload	Payload	Payload ของ Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger
email_payload	EmailPayload	Payload ของอีเมล
return_unknown_identifiers	bool	เมื่อเป็น true unknown_identifiers ในการตอบกลับจะแสดงรายการตัวระบุที่ไม่พบ
use_latest_user_device	bool	ใช้ได้เฉพาะเมื่อคุณกำหนดเป้าหมายเป็น users เท่านั้น มีพฤติกรรมเช่นเดียวกับใน NotifySegment ข้างต้น — ส่งหนึ่งข้อความต่อผู้ใช้แทนที่จะเป็นหนึ่งข้อความต่ออุปกรณ์ โดยจำกัดขอบเขตอยู่ที่ platforms ค่าเริ่มต้นคือ false
campaign, campaign_name, frequency_capping, send_rate, message_type, dynamic_content_placeholders, meta_data		ดูที่ NotifySegment ด้านบน

test_devices, hwids, users และ push_tokens ไม่สามารถใช้ร่วมกันได้ ต้องตั้งค่าเพียงหนึ่งอย่างเท่านั้น

ตัวอย่าง: Transactional ตาม user IDs

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "users": { "list": ["user-123", "user-456"] },
      "payload": {
        "content": {
          "localized_content": {
            "en": { "ios": { "body": "Your order has shipped." } }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
      "return_unknown_identifiers": true,
      "use_latest_user_device": true
    }
  }'

การตอบกลับ

{
  "result": {
    "message_code": "XXXXX-XXXXX-XXXXX",
    "unknown_identifiers": []
  }
}

ฟิลด์	ประเภท	คำอธิบาย
message_code	string	message code ที่ไม่ซ้ำกัน ใช้กับ /getMessageDetails และ endpoint สถิติข้อความ
unknown_identifiers	array of string	ตัวระบุที่ไม่พบบนบัญชี จะถูกเติมข้อมูลก็ต่อเมื่อตั้งค่า return_unknown_identifiers: true ในประเภท transactional เท่านั้น

ประเภทที่ใช้ร่วมกัน

Schedule

{
  "at": "2026-05-01T12:00:00Z",
  "follow_user_timezone": true,
  "past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}

ฟิลด์	ประเภท	คำอธิบาย
at	timestamp	เวลาส่งที่แน่นอน (RFC 3339) หากเป็นเวลาในอดีต ข้อความจะถูกส่งทันที สามารถตั้งล่วงหน้าได้สูงสุด 14 วัน
after	duration	ทางเลือกแทน at ส่งหลังจากเวลาที่กำหนดนับจาก “ตอนนี้” (เช่น "3600s")
follow_user_timezone	bool	เมื่อเป็น true อุปกรณ์แต่ละเครื่องจะได้รับข้อความ ณ เวลา at ตามเขตเวลาท้องถิ่นของตน
past_timezones_behaviour	enum	PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY (ค่าเริ่มต้น), PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND หรือ PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY จะมีความหมายก็ต่อเมื่อ follow_user_timezone เป็น true เท่านั้น

FrequencyCapping

การจำกัดความถี่ต่อผู้ใช้สำหรับการส่งข้อความการตลาด หากต้องการปิดใช้งานการจำกัด ให้ละเว้น frequency_capping ทั้งหมด หรือส่ง days: 0 พร้อมกับ count: 0

{ "days": 7, "count": 3, "exclude": false, "avoid": true }

• days (int, 1–30 หรือ 0 เพื่อปิดใช้งานการจำกัด): กรอบเวลาย้อนหลัง ต้องส่งพร้อมกับ count — หากตัวใดตัวหนึ่งเป็น 0 อีกตัวก็ต้องเป็น 0 ด้วย การส่งตัวหนึ่งเป็น 0 ในขณะที่อีกตัวไม่เป็นศูนย์จะคืนค่า 400
• count (int, 1 หรือสูงกว่า หรือ 0 เพื่อปิดใช้งานการจำกัด): จำนวนข้อความสูงสุดที่อนุญาตภายใน days กฎการจับคู่เหมือนกับ days ข้างต้น
• exclude (bool): ไม่รวมผู้ใช้ที่ถึงขีดจำกัดแล้วอย่างเด็ดขาด
• avoid (bool): หลีกเลี่ยงผู้ใช้ที่ถึงขีดจำกัดแล้วอย่างนุ่มนวล (พวกเขายังคงถูกนับในสถิติ)

Important

การส่ง days และ count ที่มีค่าศูนย์ไม่ตรงกัน (เช่น {"days": 0, "count": 5}) จะคืนค่า 400 การตรวจสอบนี้เป็นการเปลี่ยนแปลงที่สำคัญ (breaking change) ของ Notify — client ที่เคยอาศัยการที่ค่า 0 ตัวเดียวถูกละเว้นไปโดยไม่มีการแจ้งเตือน ตอนนี้จะได้รับข้อผิดพลาดแทน

SendRate

{ "value": 500, "bucket": "1s", "avoid": false }

ควบคุมอัตราการส่ง value คือจำนวนข้อความต่อ bucket; bucket ทั่วไปคือ "1s"

Platform enum

IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP, VIBER, FB_MESSENGER.

MessageType enum

• MESSAGE_TYPE_UNSPECIFIED: เทียบเท่ากับ MESSAGE_TYPE_MARKETING
• MESSAGE_TYPE_MARKETING: อยู่ภายใต้การกรองของกลุ่มควบคุม (control-group) และการจำกัดความถี่
• MESSAGE_TYPE_TRANSACTIONAL: ข้ามการกรองของกลุ่มควบคุมและการจำกัดความถี่ ใช้สำหรับการยืนยันคำสั่งซื้อ, OTPs และขั้นตอนที่สำคัญอื่นๆ ที่คล้ายกัน

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

Notify batch

Cancel

การอ้างอิง Payload

การอ้างอิง Email payload

การย้ายจาก v1