# Notify

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

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

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

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

- [`segment`](#notifysegment): กำหนดเป้าหมายไปยังกลุ่มเป้าหมาย (audience segment) ด้วยรหัส segment, นิพจน์ [seglang](/th/developer/api-reference/segmentation-filters-api/segmentation-language/) หรือนิพจน์ filter แบบมีโครงสร้าง
- [`transactional`](#notifytransactional): ส่งไปยังรายการที่ระบุอย่างชัดเจนของ hwids, user IDs, push tokens หรืออุปกรณ์ทดสอบ (test devices)

```json title="Shape"
{
  "segment": { ... }       // OR
  "transactional": { ... }
}
```

## NotifySegment

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

| Field | Type | Description |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | เวลาและวิธีการส่ง จำเป็น |
| `application` | string | [รหัสแอปพลิเคชัน (Application code)](/th/developer/api-reference/api-identifiers/#application-code) |
| `platforms` | array of [`Platform`](#platform-enum) | แพลตฟอร์มที่ข้อความจะส่งไปถึง |
| `code` | string | [รหัส Segment (Segment code)](/th/developer/api-reference/api-identifiers/#segment--filter-code) ไม่สามารถใช้ร่วมกับ `expression` และ `filter_expression` ได้ |
| `expression` | string | นิพจน์ [Seglang](/th/developer/api-reference/segmentation-filters-api/segmentation-language/) |
| `filter_expression` | `FilterExpression` | นิพจน์ filter แบบมีโครงสร้าง (ขั้นสูง) |
| `payload` | [`Payload`](/th/developer/api-reference/messaging-api-v2/payload-reference/) | Payload ของ Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber ไม่สามารถใช้ร่วมกับ `email_payload` ได้ |
| `email_payload` | [`EmailPayload`](/th/developer/api-reference/messaging-api-v2/email-payload-reference/) | Payload ของอีเมล |
| `campaign` | string | [รหัสแคมเปญ (Campaign code)](/th/developer/api-reference/api-identifiers/#campaign-code) เพื่อระบุว่าข้อความนี้เป็นของแคมเปญใด |
| `frequency_capping` | [`FrequencyCapping`](#frequencycapping) | การจำกัดความถี่ต่อผู้ใช้ |
| `send_rate` | [`SendRate`](#sendrate) | การควบคุมอัตราการส่ง |
| `message_type` | [`MessageType`](#messagetype-enum) | `MESSAGE_TYPE_MARKETING` (ค่าเริ่มต้น) หรือ `MESSAGE_TYPE_TRANSACTIONAL` ควบคุมการกรองกลุ่มควบคุม (control-group) |
| `dynamic_content_placeholders` | map<string, string> | แทนที่ placeholders ในเนื้อหา |
| `meta_data` | object | ข้อมูลเมตาแบบอิสระที่ส่งต่อไปยังระบบวิเคราะห์ข้อมูลปลายทาง |

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

```bash
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`](#schedule) | จำเป็น |
| `application` | string | [รหัสแอปพลิเคชัน (Application code)](/th/developer/api-reference/api-identifiers/#application-code) |
| `platforms` | array of [`Platform`](#platform-enum) | แพลตฟอร์มที่ข้อความจะส่งไปถึง |
| `test_devices` | bool | ถ้าเป็น `true` จะส่งไปยังอุปกรณ์ทดสอบของแอปเท่านั้น |
| `hwids` | `{ "list": [string, ...] }` | ส่งไปยัง [hwids](/th/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) เหล่านี้เท่านั้น |
| `users` | `{ "list": [string, ...] }` | ส่งไปยัง [user IDs](/th/developer/pushwoosh-knowledge-hub/users-userids/) เหล่านี้เท่านั้น |
| `push_tokens` | `{ "list": [string, ...] }` | ส่งไปยัง [push tokens](/th/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token) เหล่านี้เท่านั้น |
| `payload` | [`Payload`](/th/developer/api-reference/messaging-api-v2/payload-reference/) | Payload ของ Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber |
| `email_payload` | [`EmailPayload`](/th/developer/api-reference/messaging-api-v2/email-payload-reference/) | 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

```bash
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)

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

| Field | Type | Description |
|---|---|---|
| `message_code` | string | [รหัสข้อความ (message code)](/th/developer/api-reference/api-identifiers/#message-code) ที่ไม่ซ้ำกัน ใช้กับ [`/getMessageDetails`](/th/developer/api-reference/messages-api/#getmessagedetails) และ endpoints สถิติข้อความ |
| `unknown_identifiers` | array of string | ตัวระบุที่ไม่พบบนบัญชี จะมีข้อมูลก็ต่อเมื่อตั้งค่า `return_unknown_identifiers: true` ในชนิด `transactional` เท่านั้น |

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

### Schedule

```json
{
  "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`

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

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

### SendRate

```json
{ "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 และขั้นตอนที่สำคัญอื่นๆ ที่คล้ายกัน

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

<CardGrid>
  <LinkCard title="ยกเลิก (Cancel)" href="/developer/api-reference/messaging-api-v2/cancel/" />
  <LinkCard title="ข้อมูลอ้างอิง Payload" href="/developer/api-reference/messaging-api-v2/payload-reference/" />
  <LinkCard title="ข้อมูลอ้างอิง Email payload" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="การย้ายจาก v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>