Notify

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

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

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

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

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

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

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

การขจัดข้อมูลซ้ำซ้อนจะจับคู่กับ 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 สำหรับการส่งครั้งนี้เท่านั้น

ฟิลด์	ประเภท	คำอธิบาย
`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`	การควบคุมอัตราการส่ง
`silent_hours`	`SilentHours`	ไม่บังคับ ส่งข้อความโดยไม่ใช้ silent hours ของแอปพลิเคชัน
`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` (ส่งไปยังทุกอุปกรณ์)
`geo_zone`	`GeoZone`	ไม่บังคับ จำกัดกลุ่มเป้าหมายให้เหลือเฉพาะอุปกรณ์ที่ตำแหน่งที่บันทึกไว้ล่าสุดอยู่ภายในวงกลมที่คุณกำหนดในคำขอนี้ ใช้ร่วมกับ `code`, `expression` หรือ `filter_expression` แบบ AND: อุปกรณ์ต้องตรงกับ segment และอยู่ภายในวงกลม อุปกรณ์ที่ไม่มีตำแหน่งที่บันทึกไว้จะถูกข้าม ใช้ไม่ได้ใน `NotifyTransactional`
`control_group`	string	โค้ดหรือชื่อของกลุ่ม hold-out เฉพาะของการส่งนี้ที่จะใช้กับข้อความนี้ ฟิลด์นี้ไม่ได้จำกัดว่าcontrol groupsใดจะถูกนำมาใช้ เพราะ control group ที่เปิดใช้งานทุกกลุ่มของแอปพลิเคชันจะกันผู้ใช้ออกจากการส่งทางการตลาดไม่ว่าจะตั้งฟิลด์นี้หรือไม่ก็ตาม ใช้ร่วมกับ `holdout_percentage` ไม่ได้
`holdout_percentage`	uint32	ดึงสัดส่วนนี้ของเซกเมนต์ ตั้งแต่ `1` ถึง `20` ไปไว้ใน control group ที่ใช้เฉพาะกับการส่งนี้ เพิ่มเติมจาก control group ที่เปิดใช้งานของแอปพลิเคชัน เพื่อวัดผลของแคมเปญเดียวโดยไม่ต้องใช้ control group ที่ใช้ร่วมกัน ค่า `0` (ค่าเริ่มต้น) หมายถึงปิดใช้งาน ใช้ร่วมกับ `control_group` ไม่ได้

Pushwoosh ตั้งชื่อกลุ่ม holdout เป็น __holdout_<campaign code> (หรือ __holdout_<message code> สำหรับการส่งที่ไม่มี campaign) และนำกลุ่มเดิมนี้กลับมาใช้ซ้ำด้วยเปอร์เซ็นต์เดิมกับการส่งครั้งถัดไปทุกครั้งที่ใช้โค้ดเดียวกัน การสุ่มเลือกจะถูกตรึงไว้ตั้งแต่ครั้งแรกที่สร้างกลุ่ม กลุ่มนี้จะไม่ปรากฏใน Settings > Control groups และการปรับขนาด สุ่มใหม่ ปิดใช้งาน หรือลบกลุ่มนี้จะส่งคืน FailedPrecondition เนื่องจากการเปลี่ยนแปลงระหว่างการวัดผลจะทำให้การเปรียบเทียบไม่ถูกต้อง

อุปกรณ์ที่ถูกดึงเข้ากลุ่ม holdout จะถูกกันออกจากการส่งในลักษณะเดียวกับcontrol groupsของแอปพลิเคชัน อุปกรณ์เหล่านี้จะไม่ได้รับข้อความ และ tracking log จะบันทึกการตัดออกเป็น Device is in control group เมื่อ message_type เป็น MESSAGE_TYPE_TRANSACTIONAL การกันออกนี้จะถูกข้ามไปทั้งหมด เช่นเดียวกับ control group ของแอปพลิเคชัน

การตั้งค่า holdout_percentage พร้อมกับ control_group หรือ holdout_percentage ที่มากกว่า 20 จะส่งคืน 400:

{
  "code": 3,
  "message": "invalid argument",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "holdout_percentage",
          "description": "holdout_percentage and control_group are mutually exclusive"
        }
      ]
    },
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "InvalidHoldoutPercentage",
      "domain": "api.pushwoosh.com",
      "metadata": {}
    }
  ]
}

ตัวอย่าง: ส่งไปยัง 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` ในการตอบกลับจะแสดงรายการตัวระบุที่ไม่พบ
`registration_type`	`RegistrationType`	สิ่งที่จะทำกับ `hwids` ที่ยังไม่ได้ลงทะเบียนใน Pushwoosh ค่าเริ่มต้นคือ `REGISTRATION_TYPE_DEFAULT` ซึ่งจะข้าม hwid เหล่านั้น ตั้งค่าเป็น `REGISTRATION_TYPE_FORCE` เพื่อลงทะเบียนและส่งไปยังที่อยู่อีเมลหรือหมายเลขโทรศัพท์ใหม่ในคำขอเดียวกัน
`use_latest_user_device`	bool	ใช้ได้เฉพาะเมื่อคุณกำหนดเป้าหมายเป็น `users` เท่านั้น มีพฤติกรรมเช่นเดียวกับใน `NotifySegment` ข้างต้น — ส่งหนึ่งข้อความต่อผู้ใช้แทนที่จะเป็นหนึ่งข้อความต่ออุปกรณ์ โดยจำกัดขอบเขตอยู่ที่ `platforms` ค่าเริ่มต้นคือ `false`
`campaign`, `campaign_name`, `frequency_capping`, `send_rate`, `silent_hours`, `message_type`, `dynamic_content_placeholders`, `meta_data`		ดูที่ `NotifySegment` ด้านบน

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

ส่งไปยังที่อยู่อีเมลและหมายเลขโทรศัพท์ใหม่

สำหรับอีเมล, SMS, WhatsApp, LINE, Viber และ Kakao ตัว hwid คือปลายทางเอง เช่น ที่อยู่อีเมลหรือหมายเลขโทรศัพท์ หากต้องการส่งไปยัง hwid ที่ยังไม่ได้ลงทะเบียน ให้ใส่ไว้ใน hwids และตั้งค่า registration_type เป็น REGISTRATION_TYPE_FORCE Pushwoosh จะลงทะเบียน hwid นั้นและส่งข้อความในคำขอเดียวกัน คุณจึงไม่ต้องเรียก /registerDevice หรือ /registerEmail แยกต่างหากก่อน

registration_type ใช้ได้กับ hwids เท่านั้น เมื่อใช้ users ระบบจะไม่สร้าง user ID ที่ไม่รู้จัก ไม่ว่าจะตั้งค่า registration_type เป็นค่าใดก็ตาม

เขียน hwid แต่ละรายการในรูปแบบเดียวกับที่ /registerDevice จัดเก็บสำหรับช่องทางนั้น:

ช่องทาง	รูปแบบ hwid	ตัวอย่าง
อีเมล	ที่อยู่อีเมล	`new.customer@example.com`
SMS	หมายเลขโทรศัพท์ในรูปแบบสากล	`+14155552671`
WhatsApp	หมายเลขโทรศัพท์ที่มีคำนำหน้า `whatsapp:`	`whatsapp:+14155552671`
Kakao	หมายเลขโทรศัพท์ที่มีคำนำหน้า `kakao:`	`kakao:+821012345678`
Viber	หมายเลขโทรศัพท์ที่มีคำนำหน้า `viber:` Pushwoosh จะเพิ่มคำนำหน้าให้หากไม่มี	`viber:+14155552671`
LINE	LINE user ID	`U4af4980629a1b2c3d4e5f6a7b8c9d0e1`

คงคำนำหน้า whatsapp: และ kakao: ไว้ หากไม่มีคำนำหน้าเหล่านี้ หมายเลขจะถูกอ่านเป็น hwid ของ SMS หากหมายเลขนั้นลงทะเบียนสำหรับ SMS ไว้แล้ว การส่งจะพบ hwid ของ SMS ซึ่งไม่ตรงกับแพลตฟอร์มเป้าหมาย และผู้รับจะถูกข้าม

Pushwoosh ตรวจสอบหมายเลขโทรศัพท์เฉพาะเมื่อใช้ return_unknown_identifiers: true เท่านั้น ในกรณีนี้ hwid ของ SMS, WhatsApp หรือ Kakao ที่ไม่ใช่หมายเลขโทรศัพท์ที่ถูกต้องจะไม่ถูกลงทะเบียนและจะถูกส่งกลับมาใน unknown_identifiers หากไม่มี flag นี้ ค่าจะถูกลงทะเบียนตามที่เป็นอยู่

REGISTRATION_TYPE_FORCE ไม่ลงทะเบียน hwid บนแพลตฟอร์ม push, Telegram หรือ Facebook Messenger เนื่องจากแพลตฟอร์มเหล่านี้ต้องใช้ token จาก SDK หรือจากแอปส่งข้อความ hwid ที่ไม่รู้จักบนแพลตฟอร์มเหล่านี้จะถูกทิ้งไปโดยไม่มีการแจ้ง ไม่ถูกส่งกลับมาใน unknown_identifiers และจะไม่มีสิ่งใดถูกส่งไปยัง hwid นั้น

สำหรับ WhatsApp การลงทะเบียนหมายเลขไม่ได้เปิดหน้าต่างบริการลูกค้า 24 ชั่วโมง หมายเลขที่ยังไม่เคยส่งข้อความหาคุณจะรับได้เฉพาะเทมเพลตที่ได้รับอนุมัติล่วงหน้าซึ่งตั้งค่าไว้ใน whatsapp.content_id เท่านั้น ไม่ใช่ whatsapp.content แบบอิสระ

ตัวอย่าง: ส่งไปยังที่อยู่อีเมลใหม่

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": ["EMAIL"],
      "hwids": { "list": ["new.customer@example.com"] },
      "registration_type": "REGISTRATION_TYPE_FORCE",
      "email_payload": {
        "subject": { "en": "Welcome aboard" },
        "body": "<p>Thanks for signing up!</p>"
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
      "return_unknown_identifiers": true
    }
  }'

ตัวอย่าง: 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	ตัวระบุที่ไม่พบบนบัญชี จะถูกเติมข้อมูลเฉพาะในการส่งแบบ `transactional` ที่ใช้ `return_unknown_identifiers: true` หรือกำหนดเป้าหมายด้วย `push_tokens` เท่านั้น ตัวระบุที่ลงทะเบียนผ่าน `REGISTRATION_TYPE_FORCE` จะไม่แสดงในรายการ

/getMessageDetails จะไม่พบข้อความ transactional ที่ส่งทันทีถึงผู้ใช้น้อยกว่า 10 รายและอุปกรณ์น้อยกว่า 10 เครื่อง เนื่องจากข้อความดังกล่าวจะไม่ถูกจัดเก็บ ดูข้อความที่ส่งทันทีถึงผู้รับน้อยกว่า 10 ราย

ไม่พบผู้รับ

เมื่อใช้ return_unknown_identifiers: true หรือกำหนดเป้าหมายด้วย push_tokens Pushwoosh จะค้นหาผู้รับแต่ละรายก่อนสร้างข้อความ หากไม่มีผู้รับรายใดลงทะเบียนไว้เลย Notify จะคืนค่า HTTP 400 พร้อมข้อผิดพลาดนี้ และจะไม่มีการสร้างข้อความ:

{
  "code": 9,
  "message": "No recipients found",
  "details": [ ... ]
}

หากพบผู้รับอย่างน้อยหนึ่งราย คำขอจะสำเร็จและผู้รับที่เหลือจะแสดงอยู่ใน unknown_identifiers หากต้องการส่งไปยังที่อยู่อีเมลหรือหมายเลขโทรศัพท์ใหม่แทน ให้ตั้งค่า registration_type เป็น REGISTRATION_TYPE_FORCE

สำหรับอีเมล ที่อยู่ที่ไม่ถูกต้องและที่อยู่ที่เคย bounce มาก่อนจะถูกนำออกก่อนการตรวจสอบนี้ โดยไม่แสดงใน unknown_identifiers หากไม่เหลือที่อยู่ใดเลยหลังจากนั้น Notify จะคืนค่า 200 พร้อม message_code แต่จะไม่มีการสร้างข้อความและไม่มีสิ่งใดถูกส่ง

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

Schedule

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

ฟิลด์	ประเภท	คำอธิบาย
`at`	timestamp	เวลาส่งที่แน่นอน (RFC 3339) สามารถตั้งล่วงหน้าได้สูงสุด 30 วัน เมื่อไม่ได้ตั้งค่า `follow_user_timezone` หรือตั้งเป็น `false` ค่า `at` ที่เป็นเวลาในอดีตจะถูกแทนที่ด้วยเวลาที่ได้รับคำขอ ข้อความจึงถูกส่งทันทีถึงทุกคน เมื่อใช้ `follow_user_timezone: true` ค่า `at` ที่เป็นเวลาในอดีตจะคงไว้ตามเดิม ดูข้อควรระวังด้านล่าง
`after`	duration	ทางเลือกแทน `at` ส่งหลังจากเวลาที่กำหนดนับจาก “ตอนนี้” (เช่น `"3600s"`) สูงสุด 30 วัน
`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` หรือมีการตั้งค่า `best_time_to_send` เท่านั้น
`best_time_to_send`	timestamp	ไม่บังคับ ใช้กับการส่งแบบเซกเมนต์เท่านั้น แต่ละอุปกรณ์จะได้รับข้อความในชั่วโมงที่ดีที่สุดของตัวเองภายใน 24 ชั่วโมงนับจากเวลานี้ อุปกรณ์ที่ไม่มีชั่วโมงที่ดีที่สุดจะได้รับข้อความในวันที่และเวลาของ `at` / `after` ตามเขตเวลาท้องถิ่นของตน ดูเวลาที่ดีที่สุดในการส่ง

เมื่อใช้ follow_user_timezone: true ค่า at ที่เป็นเวลาในอดีตจะไม่ถูกเลื่อนเป็น “ตอนนี้” วันที่และเวลา UTC ของค่านี้ยังคงถูกแบ่งเป็นช่วงเวลาท้องถิ่นของแต่ละอุปกรณ์ เขตเวลาที่เวลาท้องถิ่นนั้นยังมาไม่ถึงจะได้รับข้อความ ณ เวลานั้น ส่วนเขตเวลาที่เวลานั้นผ่านไปแล้วจะเป็นไปตาม past_timezones_behaviour แทน คือส่งทันที ข้าม (DO_NOT_SEND) หรือเลื่อนไปหนึ่งวัน (NEXT_DAY) ณ เวลาท้องถิ่นเดิมนั้น การแบ่งแบบเดียวกันนี้ใช้กับการส่งสำรองของ best_time_to_send ด้วย

เวลาที่ดีที่สุดในการส่ง

best_time_to_send คือฟิลด์ใน API ที่ทำงานเทียบเท่าตัวเลือกเวลาที่ดีที่สุดใน Control Panel ส่วน at / after กำหนดการส่งสำรองสำหรับอุปกรณ์ที่มีข้อมูลไม่เพียงพอสำหรับหาชั่วโมงที่ดีที่สุด Pushwoosh จะใช้วันที่และเวลา UTC ของ at / after และส่งข้อความสำรอง ณ วันที่และเวลานั้นตามเขตเวลาท้องถิ่นของแต่ละอุปกรณ์ เช่นเดียวกับ follow_user_timezone: true การทำงานนี้เกิดขึ้นโดยอัตโนมัติ: ไม่ต้องตั้งค่า follow_user_timezone เพราะค่า true จะถูกปฏิเสธด้วย BestTimeToSendWithUserTimezone ในตัวอย่างด้านล่าง อุปกรณ์ที่ไม่มีชั่วโมงที่ดีที่สุดจะได้รับข้อความเวลา 18:00 ตามเวลาท้องถิ่นในวันที่ 1 พฤษภาคม หากเวลาท้องถิ่นนั้นผ่านไปแล้วเมื่อเริ่มการส่ง จะใช้ past_timezones_behaviour

{
  "at": "2026-05-01T18:00:00Z",
  "best_time_to_send": "2026-05-01T00:00:00Z"
}

Pushwoosh จะปฏิเสธคำขอด้วย 400 เว้นแต่จะเป็นไปตามเงื่อนไขทั้งหมดต่อไปนี้:

คำขอใช้ประเภท segment การส่งแบบ transactional ไม่รองรับ best_time_to_send
ไม่ได้ตั้งค่า follow_user_timezone หรือตั้งเป็น false
เวลาส่งจาก at / after อยู่ในอนาคต at ที่เป็นเวลาในอดีต after: "0s" หรือการไม่ระบุ after จะถือเป็น “ส่งทันที” และถูกปฏิเสธ
best_time_to_send ต้องไม่เร็วกว่าชั่วโมงเต็มถัดไป และไม่เกิน 30 วันล่วงหน้า ค่านี้จะถูกปัดลงเป็นชั่วโมงเต็ม
เวลาส่งจาก at / after ต้องไม่ช้ากว่า best_time_to_send บวก 24 ชั่วโมง

reason ของข้อผิดพลาด (ในรายละเอียด ErrorInfo) จะระบุการตรวจสอบที่ไม่ผ่าน:

`reason`	สาเหตุ
`BestTimeToSendWithUserTimezone`	`follow_user_timezone` เป็น `true`
`BestTimeToSendTooEarly`	`best_time_to_send` เร็วกว่าชั่วโมงเต็มถัดไป
`BestTimeToSendTooFarInFuture`	`best_time_to_send` เกิน 30 วันล่วงหน้า
`SendDateAfterBestTimeToSend`	`at` / `after` ช้ากว่า `best_time_to_send` บวก 24 ชั่วโมง
`BestTimeToSendNotAllowed`	มีการตั้งค่า `best_time_to_send` ในการส่งแบบ `transactional`
`BestTimeToSendWithSendNow`	`at` / `after` มีค่าเป็น “ตอนนี้” (`at` ในอดีตหรือ `after` เป็นศูนย์)

GeoZone

วงกลมแบบใช้ครั้งเดียวสำหรับ geo_zone ซึ่งกำหนดไว้ในคำขอเอง ไม่ใช่ geozone ที่บันทึกไว้: แคมเปญตามตำแหน่งที่ตั้ง และ Geozones API ไม่ได้เกี่ยวข้อง และไม่มีสิ่งใดถูกจัดเก็บในแอปพลิเคชัน

{ "lat": 40.7128, "lng": -74.006, "range": 500 }

ฟิลด์	ประเภท	คำอธิบาย
`lat`	double	ละติจูดของจุดศูนย์กลางวงกลม หน่วยเป็นองศา จำเป็น
`lng`	double	ลองจิจูดของจุดศูนย์กลางวงกลม หน่วยเป็นองศา จำเป็น
`range`	double	รัศมีของวงกลมเป็นเมตร จำเป็น

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

SendRate

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

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

SilentHours

{ "avoid": true }

โดยค่าเริ่มต้น ข้อความ marketing จะเป็นไปตาม silent hours ของแอปพลิเคชัน: ในช่วงเวลาเงียบ ข้อความจะถูกพักไว้จนกว่าช่วงเวลาดังกล่าวจะสิ้นสุด หรือไม่ถูกส่งเลย ขึ้นอยู่กับการตั้งค่าของช่องทาง ตั้งค่า avoid เป็น true เพื่อส่งข้อความนี้แม้อยู่ในช่วงเวลาเงียบ ข้อความที่มี message_type เป็น MESSAGE_TYPE_TRANSACTIONAL จะไม่ถูกพักไว้โดย silent hours จึงไม่จำเป็นต้องใช้ฟิลด์นี้

Platform enum

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

RegistrationType enum

REGISTRATION_TYPE_DEFAULT: ข้ามตัวระบุที่ยังไม่ได้ลงทะเบียนใน Pushwoosh ค่าเริ่มต้น
REGISTRATION_TYPE_NONE: ส่งไปยัง hwid ทุกรายการที่ระบุโดยไม่บันทึกอุปกรณ์สำหรับ hwid นั้น
REGISTRATION_TYPE_FORCE: ลงทะเบียน hwid ที่ไม่รู้จักแต่ละรายการเป็นอุปกรณ์บนช่องทางเป้าหมาย แล้วส่งไปยัง hwid นั้น ใช้กับอีเมล, SMS, WhatsApp, LINE, Viber และ Kakao

MessageType enum

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

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

Notify batch

Cancel

การอ้างอิง Payload

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

การย้ายจาก v1