Notify

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

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

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

ส่วน body ของ request คือ NotifyRequest ที่มีหนึ่งในสองชนิดนี้เท่านั้น:

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

Shape

{
  "segment": { ... }       // OR
  "transactional": { ... }
}

NotifySegment

กำหนดเป้าหมายผู้ใช้ที่ตรงกับกลุ่มเป้าหมาย (audience segment) หรือนิพจน์ filter

Field	Type	Description
schedule	Schedule	เวลาและวิธีการส่ง จำเป็น
application	string	รหัสแอปพลิเคชัน (Application code)
platforms	array of Platform	แพลตฟอร์มที่ข้อความจะส่งไปถึง
code	string	รหัส Segment (Segment code) ไม่สามารถใช้ร่วมกับ expression และ filter_expression ได้
expression	string	นิพจน์ Seglang
filter_expression	FilterExpression	นิพจน์ filter แบบมีโครงสร้าง (ขั้นสูง)
payload	Payload	Payload ของ Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber ไม่สามารถใช้ร่วมกับ email_payload ได้
email_payload	EmailPayload	Payload ของอีเมล
campaign	string	รหัสแคมเปญ (Campaign code) เพื่อระบุว่าข้อความนี้เป็นของแคมเปญใด
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	ข้อมูลเมตาแบบอิสระที่ส่งต่อไปยังระบบวิเคราะห์ข้อมูลปลายทาง

ตัวอย่าง: ส่งไปยัง 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

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

Field	Type	Description
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
email_payload	EmailPayload	Payload ของอีเมล
return_unknown_identifiers	bool	เมื่อเป็น true ส่วน unknown_identifiers ในการตอบกลับจะแสดงรายการตัวระบุที่ไม่พบ
use_latest_user_device	bool	ใช้ได้เฉพาะเมื่อคุณกำหนดเป้าหมายเป็น users เท่านั้น เมื่อเป็น true ข้อความจะถูกส่งไปยังอุปกรณ์ที่ใช้งานล่าสุดของผู้ใช้แต่ละคน — อุปกรณ์ที่มี Last Application Open ล่าสุด — แทนที่จะส่งไปยังทุกอุปกรณ์ที่ผูกกับ user ID นั้น ค่าเริ่มต้นคือ false (ส่งไปยังทุกอุปกรณ์)
campaign, 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
    }
  }'

การตอบกลับ (Response)

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

Field	Type	Description
message_code	string	รหัสข้อความ (message code) ที่ไม่ซ้ำกัน ใช้กับ /getMessageDetails และ endpoints สถิติข้อความ
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"
}

Field	Type	Description
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): หลีกเลี่ยงผู้ใช้ที่ถึงขีดจำกัดแล้ว (แต่ยังคงนับรวมในสถิติ)

สำคัญ

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

SendRate

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

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

Platform enum

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

MessageType enum

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

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

ยกเลิก (Cancel)

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

ข้อมูลอ้างอิง Email payload

การย้ายจาก v1