# การอ้างอิง Payload

การอ้างอิงสำหรับข้อความ `Payload` ที่ใช้โดย [`Notify`](/th/developer/api-reference/messaging-api-v2/notify/) เมื่อส่งผ่านช่องทางที่ไม่ใช่อีเมล (push, SMS, Telegram, Kakao, LINE, Viber, WhatsApp)

<Aside type="note">
สำหรับอีเมล โปรดดูที่ [การอ้างอิง Email payload](/th/developer/api-reference/messaging-api-v2/email-payload-reference/)
</Aside>

## Payload

- `preset` (string): รหัส [push preset](/th/product/content/push-presets/) (รูปแบบ `XXXXX-XXXXX`) ที่จะนำไปใช้กับข้อความนี้
- `sms_preset` (string): รหัส (รูปแบบ `XXXXX-XXXXX`) ของ [SMS preset](/th/product/content/sms-presets/) ที่บันทึกไว้ ข้อความต่อภาษาของมันจะถูกแก้ไขเป็น [`sms.body`](#sms-sms) ของแต่ละภาษา `sms.body` แบบอินไลน์สำหรับภาษาที่กำหนดจะแทนที่ preset สำหรับภาษานั้น preset ต้องเป็นของแอปพลิเคชันเดียวกับข้อความ
- `content` ([`LocalizedContent`](#localizedcontent)): เนื้อหาข้อความ ไม่สามารถใช้ร่วมกับ `silent` ได้
- `silent` (bool): ส่ง push แบบเงียบ (ข้อมูลเท่านั้น) ไม่สามารถใช้ร่วมกับ `content` ได้
- `custom_data` (object): JSON รูปแบบอิสระที่ส่งต่อไปยัง client SDK เป็นพารามิเตอร์ `u`
- `open_action` ([`OpenAction`](#openaction)): การกระทำที่เกิดขึ้นเมื่อผู้ใช้เปิดการแจ้งเตือน
- `open_actions` (map&lt;Platform, `OpenAction`&gt;): การแทนที่ `open_action` ต่อแพลตฟอร์ม คีย์คือค่า enum `Platform` ที่เป็นตัวเลข
- `voip_push` (bool): การแจ้งเตือน iOS VoIP

```json
{
  "payload": {
    "preset": "XXXXX-XXXXX",
    "content": { "localized_content": { "default": { "ios": { "title": "Hello", "body": "Tap to view" } } } },
    "custom_data": { "order_id": "42" },
    "open_action": { "link": { "url": "https://example.com/promo" } }
  }
}
```

## LocalizedContent

จับคู่รหัสภาษา → เนื้อหาต่อแพลตฟอร์ม คีย์คือรหัสสองตัวอักษร [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php) (ตัวอย่างเช่น `"en"`, `"es"`) บวกกับคีย์พิเศษ `"default"` สำหรับการแปลแบบครอบคลุมทั้งหมด ข้อยกเว้นสำหรับ ISO 639-1 คือ `"zh-Hant"` และ `"zh-Hans"` สำหรับภาษาจีนตัวเต็มและตัวย่อ

```json
{
  "localized_content": {
    "default": {
      "ios":     { "title": "Hello", "body": "Tap to view" },
      "android": { "title": "Hello", "body": "Tap to view" }
    },
    "es": {
      "ios":     { "title": "Hola",  "body": "Toca para ver" },
      "android": { "title": "Hola",  "body": "Toca para ver" }
    }
  }
}
```

### การเลือกภาษาสำหรับอุปกรณ์

เนื้อหาที่ส่งไปยังอุปกรณ์จะถูกเลือกตามลำดับนี้:

1.  การจับคู่ที่ตรงกันกับภาษาของอุปกรณ์
2.  คีย์ `"default"`
3.  คีย์ `"en"`
4.  ภาษาอื่นใดๆ ที่มีอยู่ใน map

ให้ระบุอย่างน้อยหนึ่งใน `"default"` หรือ `"en"` เพื่อให้อุปกรณ์ทุกเครื่องมีการสำรองที่แน่นอน หากคุณไม่คาดหวังว่าจะมีรูปแบบที่แตกต่างกันไปในแต่ละภาษา ให้ส่งเฉพาะ `"default"`

แต่ละรายการภาษาเป็นอ็อบเจกต์ `Content` ที่มีบล็อกต่อแพลตฟอร์มที่เป็นทางเลือก กรอกเฉพาะแพลตฟอร์มที่คุณต้องการกำหนดเป้าหมาย

| บล็อกแพลตฟอร์ม | ช่องทาง |
|---|---|
| `ios` | iOS push |
| `android` | Android (FCM) push |
| `huawei_android` | Huawei Android push |
| `baidu_android` | Baidu Android push |
| `mac_os` | macOS push |
| `amazon` | Amazon (ADM) push |
| `safari` | Safari web push |
| `chrome` | Chrome web push |
| `firefox` | Firefox web push |
| `ie` | Internet Explorer web push |
| `windows` | Windows push (tile / toast / badge) |
| `telegram` | ข้อความ Telegram |
| `kakao` | ข้อความ Kakao |
| `line` | ข้อความ LINE |
| `viber` | ข้อความ Viber |
| `whatsapp` | ข้อความ WhatsApp |
| `sms` | ข้อความ SMS |

## ฟิลด์ push ทั่วไป

ฟิลด์เหล่านี้ใช้ร่วมกันโดยบล็อก `ios`, `android`, `huawei_android`, `baidu_android`, `mac_os`, `amazon`, `safari`, `chrome` และ `firefox` (การรองรับแตกต่างกันไป ฟิลด์ที่ไม่ได้ใช้จะถูกละเว้นโดยแพลตฟอร์มที่เกี่ยวข้อง)

- `title` (string): หัวข้อการแจ้งเตือน
- `body` (string): เนื้อหาการแจ้งเตือน
- `time_to_live` (duration, เช่น `"3600s"`): ระยะเวลาที่เซิร์ฟเวอร์ push ควรเก็บการแจ้งเตือนไว้สำหรับอุปกรณ์ที่ออฟไลน์
- `sound` (string): ชื่อไฟล์เสียง
- `sound_enabled` (bool): เปิดหรือปิดเสียง
- `badges` (string): จำนวนป้าย (iOS) หรือที่คล้ายกัน
- `root_params` (object): การแทนที่ payload เฉพาะแพลตฟอร์มแบบดิบ
- `inbox` ([`Inbox`](#inbox)): รายการ [Message Inbox](/th/developer/guides/message-inbox/mobile-message-inbox/)

```json
{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "time_to_live": "3600s",
    "sound": "default",
    "sound_enabled": true,
    "badges": "+1"
  }
}
```

## iOS (`ios`)

- `subtitle` (string): หัวข้อย่อยการแจ้งเตือนของ iOS
- `is_critical` (bool): การแจ้งเตือนที่สำคัญ (ต้องมีการให้สิทธิ์)
- `attachment` (string): URL ของไฟล์แนบสื่อ
- `thread_id` (string): ตัวระบุเธรดสำหรับการแจ้งเตือนแบบกลุ่ม
- `trim_content` (bool): ตัดเนื้อหาให้พอดี
- `category_id` (string): ตัวระบุ `UNNotificationCategory` สำหรับการกระทำแบบโต้ตอบ
- `interruption_level` (string): `passive`, `active`, `time-sensitive` หรือ `critical`
- `collapse_id` (string): ตัวระบุการยุบของ APNs การแจ้งเตือนที่มี `collapse_id` เดียวกันจะแทนที่กันบนอุปกรณ์

```json
{
  "ios": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "attachment": "https://cdn.example.com/image.png",
    "interruption_level": "active",
    "thread_id": "promo"
  }
}
```

## Android (`android`, `huawei_android`, `baidu_android`)

- `icon` (string): ไอคอนขนาดเล็กของการแจ้งเตือน
- `banner` (string): URL รูปภาพขนาดใหญ่
- `delivery_priority` (`NORMAL` | `HIGH`): ลำดับความสำคัญในการส่งของ FCM
- `vibration` (bool): การสั่นเมื่อได้รับ
- `led_color` (string, hex): สี LED ของการแจ้งเตือน
- `icon_background_color` (string, hex): สีพื้นหลังของไอคอน
- `show_on_lockscreen` (bool): แสดงบนหน้าจอล็อก
- `custom_icon` (string): URL ของไอคอนที่กำหนดเอง
- `priority` ([`NotificationPriority`](#notificationpriority-enum)): ลำดับความสำคัญในถาด
- `group_id` (string): คีย์กลุ่มการแจ้งเตือน
- `collapse_key` (string): คีย์การยุบของ FCM การแจ้งเตือนที่มี `collapse_key` เดียวกันจะแทนที่กันในขณะที่อุปกรณ์ออฟไลน์

```json
{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "ic_notification",
    "banner": "https://cdn.example.com/banner.png",
    "led_color": "#FF0000",
    "priority": "PRIORITY_HIGH",
    "delivery_priority": "HIGH"
  }
}
```

## macOS (`mac_os`)

ใช้ฟิลด์ push ทั่วไปบวกกับ `subtitle` และ `action` (URL ที่เปิดเมื่อผู้ใช้คลิกการแจ้งเตือน)

```json
{
  "mac_os": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "action": "https://example.com/promo"
  }
}
```

## Amazon (`amazon`)

ใช้ฟิลด์ push ทั่วไปบวกกับ `custom_icon` และ `priority` ([`NotificationPriority`](#notificationpriority-enum))

```json
{
  "amazon": {
    "title": "Hello",
    "body": "Tap to view",
    "custom_icon": "https://cdn.example.com/icon.png",
    "priority": "PRIORITY_HIGH"
  }
}
```

## Safari (`safari`)

- `action` (string): URL ที่เปิดเมื่อผู้ใช้คลิกการแจ้งเตือน
- `url_arguments` (array of string): อาร์กิวเมนต์ URL ของ Safari ที่ใช้แทนที่ในเทมเพลต URL ของ Web Push

```json
{
  "safari": {
    "title": "Hello",
    "body": "Tap to view",
    "action": "https://example.com/promo",
    "url_arguments": ["promo", "2026"]
  }
}
```

## Chrome (`chrome`)

- `icon`, `image` (string): URL ไอคอนขนาดเล็กและรูปภาพขนาดใหญ่
- `duration` (duration): ตัวจับเวลาปิดอัตโนมัติ
- `button_text1` / `button_url1`, `button_text2` / `button_url2`: ปุ่มการกระทำสูงสุดสองปุ่ม

```json
{
  "chrome": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png",
    "image": "https://cdn.example.com/banner.png",
    "duration": "20s",
    "button_text1": "Open",
    "button_url1": "https://example.com/promo"
  }
}
```

## Firefox (`firefox`)

ใช้เฉพาะ `title`, `body`, `icon`, `root_params` และ `inbox`

```json
{
  "firefox": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png"
  }
}
```

## Windows (`windows`)

Windows ใช้รูปแบบที่แตกต่างกัน:

```json
{
  "windows": {
    "type": "TOAST",
    "template": { "title": "Hello", "body": "Tap to view" },
    "tag": "promo",
    "cache": true,
    "time_to_live": "3600s"
  }
}
```

- `type` คือ `TILE`, `TOAST` หรือ `BADGE`
- `template` (structured) หรือ `raw` (`{ "content": "<raw xml>" }`) — ต้องมีอย่างใดอย่างหนึ่งเท่านั้น

## Telegram (`telegram`)

- `body` (string): ข้อความ
- `content_variables` (string): ตัวแปรที่ถูกแปลงเป็นสตริง JSON สำหรับเทมเพลตฝั่งบอท

```json
{
  "telegram": {
    "body": "Hello from Pushwoosh",
    "content_variables": "{\"name\":\"John\"}"
  }
}
```

## Kakao (`kakao`)

- `content` (string): เนื้อหาข้อความ
- `template` (string): รหัสเทมเพลตที่ได้รับอนุมัติ
- `content_variables` (string): การผูกตัวแปรเทมเพลตที่ถูกแปลงเป็นสตริง JSON

```json
{
  "kakao": {
    "content": "Hello from Pushwoosh",
    "template": "welcome_v1",
    "content_variables": "{\"name\":\"John\"}"
  }
}
```

## LINE (`line`)

- `content` (string): เนื้อหาข้อความธรรมดา
- `template` (string): รหัสของเทมเพลต LINE ที่กำหนดค่าใน Pushwoosh Control Panel (ใช้เพื่อส่งรูปภาพ, carousel หรือ flex messages) สำหรับเนื้อหา rich content ให้กำหนดค่าเทมเพลตล่วงหน้าใน Control Panel และอ้างอิงที่นี่

ต้องตั้งค่าอย่างน้อยหนึ่งใน `content` หรือ `template`

```json
{
  "line": {
    "content": "Hello from Pushwoosh",
    "template": "promo_carousel"
  }
}
```

## Viber (`viber`)

ข้อความ Viber เป็นได้ทั้งข้อความธรรมดาหรือเทมเพลตธุรกรรมที่ได้รับอนุมัติล่วงหน้า (Omni Messaging / MStat) ที่อ้างอิงโดย id และภาษา

- `body` (string): ข้อความธรรมดา จำเป็นเมื่อไม่ได้ตั้งค่า `template_id`
- `template_id` (string): id ของเทมเพลตธุรกรรมที่ได้รับอนุมัติล่วงหน้า เมื่อตั้งค่าแล้ว จะมีความสำคัญเหนือ `body`
- `template_lang` (string): ภาษาของเทมเพลต จำเป็นเมื่อตั้งค่า `template_id`
- `template_params` (map&lt;string, string&gt;): การผูกค่าคีย์/ค่าที่ใช้แทนที่ในเทมเพลต เช่น `{ "name": "John", "code": "123456" }`
- `all_devices` (bool): `false` (ค่าเริ่มต้น) ส่งไปยังอุปกรณ์หลักของผู้ใช้เท่านั้น `true` ส่งไปยังอุปกรณ์ทั้งหมดของผู้ใช้

ต้องตั้งค่าอย่างน้อยหนึ่งใน `body` หรือ `template_id` เมื่อตั้งค่า `template_id` จำเป็นต้องมี `template_lang`

ระบุผู้รับ Viber เป็น hwids ในรูปแบบ `viber:<phone>` (E.164) ตัวอย่างเช่น `viber:+1234567890`

ข้อความธรรมดา:

```json
{
  "viber": {
    "body": "Hello from Pushwoosh"
  }
}
```

เทมเพลตธุรกรรม:

```json
{
  "viber": {
    "template_id": "e3dec4a0-c063-4b0f-96d5-cf9d629a7abe",
    "template_lang": "en",
    "template_params": {
      "name": "John",
      "code": "123456",
      "expires_in": "5 minutes"
    },
    "all_devices": false
  }
}
```

## WhatsApp (`whatsapp`)

ข้อความ WhatsApp จะส่งผ่าน Meta และอยู่ภายใต้กฎการส่งข้อความของ Meta การแบ่งแยกที่สำคัญคือระหว่างข้อความรูปแบบอิสระ (ส่งได้เฉพาะภายในหน้าต่างบริการลูกค้า 24 ชั่วโมงที่เปิดโดยข้อความขาเข้าจากผู้ใช้) และเทมเพลตที่ได้รับอนุมัติ (จำเป็นสำหรับการเริ่มต้นการส่งออกและสำหรับข้อความใดๆ นอกหน้าต่าง 24 ชั่วโมง)

- `content` (string): ข้อความรูปแบบอิสระ Meta จะส่งให้เฉพาะภายในหน้าต่าง 24 ชั่วโมงเท่านั้น
- `content_id` (string): ชื่อของเทมเพลต Meta ที่ได้รับอนุมัติล่วงหน้า (เช่น `"hello_world"`) จำเป็นสำหรับการเริ่มต้นการส่งออกหรือข้อความใดๆ นอกหน้าต่าง 24 ชั่วโมง
- `language` (string): ภาษาของเทมเพลตที่ต้องตรงกับภาษาที่ได้รับอนุมัติใน Meta (เช่น `"en_US"`, `"en_GB"`) มีความหมายเฉพาะเมื่อใช้ร่วมกับ `content_id` เท่านั้น สิ่งนี้ไม่ขึ้นอยู่กับคีย์ `LocalizedContent` ภายนอก คีย์ภายนอกจะเลือกเนื้อหาสำหรับอุปกรณ์ และ `language` จะเลือกภาษาของเทมเพลต Meta สำหรับเนื้อหานั้น
- `content_variables` (string): อ็อบเจกต์ JSON ที่จับคู่ตัวยึดตำแหน่งในเนื้อหา เช่น `"{\"1\":\"John\"}"`
- `button_url_variables` (string): อ็อบเจกต์ JSON ที่จับคู่ตัวยึดตำแหน่ง URL ของปุ่มโดยใช้ดัชนีของปุ่มเป็นคีย์ เช่น `"{\"0\":\"https://...\"}"`
- `header_variables` (string): อ็อบเจกต์ JSON ที่จับคู่ตัวยึดตำแหน่งในส่วนหัวโดยใช้ประเภทเป็นคีย์ เช่น `"{\"image\":\"https://...\"}"`

ต้องตั้งค่าอย่างน้อยหนึ่งใน `content` หรือ `content_id`

```json
{
  "whatsapp": {
    "content_id": "hello_world",
    "language": "en_US",
    "content_variables": "{\"1\":\"John\"}"
  }
}
```

## SMS (`sms`)

SMS มีบล็อกแพลตฟอร์มของตัวเองภายใน [`Content`](#localizedcontent) ของแต่ละภาษา ควบคู่ไปกับ `ios`, `android` และช่องทางการส่งข้อความอื่นๆ

- `body` (string): ข้อความ SMS สำหรับภาษานั้นๆ จำเป็นเมื่อมีบล็อก `sms` อยู่

มีสองวิธีในการระบุข้อความ:

- **Inline** — ตั้งค่า `sms.body` ต่อภาษาใน `localized_content`
- **จาก preset** — ตั้งค่า [`sms_preset`](#payload) ระดับ payload เป็นรหัส (รูปแบบ `XXXXX-XXXXX`) ของ [SMS preset](/th/product/content/sms-presets/) ที่บันทึกไว้ เนื้อหาต่อภาษาของมันจะถูกแก้ไขเป็น `sms.body` สำหรับแต่ละภาษาที่ preset กำหนด `sms.body` แบบอินไลน์สำหรับภาษาใดภาษาหนึ่งจะแทนที่ preset สำหรับภาษานั้น ดังนั้นคุณสามารถใช้ preset ซ้ำและยังคงปรับแต่งแต่ละภาษาได้

```json
{
  "payload": {
    "sms_preset": "XXXXX-XXXXX",
    "content": {
      "localized_content": {
        "default": { "sms": { "body": "Your order has shipped." } },
        "es":      { "sms": { "body": "Tu pedido ha sido enviado." } }
      }
    }
  }
}
```

## OpenAction
กำหนดการกระทำที่จะดำเนินการเมื่อผู้ใช้เปิดข้อความ

ต้องมีอย่างใดอย่างหนึ่งเท่านั้น:

- `rich_media` ([`RichMedia`](#richmedia)): เปิดหน้า [Rich Media](/th/product/content/in-apps/)
- `deep_link`: เปิด deep link: `{ "code": "flow-code", "params": { "key": "value" } }`
- `link` ([`Link`](#link)): เปิด URL

```json
{
  "open_action": {
    "deep_link": { "code": "flow-code", "params": { "promo": "summer" } }
  }
}
```

URL ของ deeplink และค่า `params` รองรับไวยากรณ์ [Liquid personalization](/th/developer/guides/personalization/liquid-templates/) — นิพจน์จะถูกประมวลผลก่อนที่จะเปิด deep link

### RichMedia


```json
{ "code": "XXXXX-XXXXX" }        // โดยรหัส Rich Media
{ "url":  "https://..." }        // โดย URL ระยะไกล
```

### Link


```json
{
  "url": "https://example.com/promo",
  "shortener": "BITLY"
}
```

`shortener` คือ `NONE` (ค่าเริ่มต้น) หรือ `BITLY`

## Inbox

กำหนดค่าลักษณะที่ข้อความจะปรากฏใน Message Inbox

```json
{
  "image_url": "https://cdn.example.com/inbox.png",
  "expiration_date": "2026-05-15T00:00:00Z"
}
```

- `image_url` (string): รูปภาพที่แสดงในรายการ inbox
- `expiration_date` (timestamp): เวลาที่รายการจะถูกลบออกจาก inbox

## NotificationPriority enum
ควบคุมลำดับความสำคัญของการแจ้งเตือนบนอุปกรณ์เป้าหมาย จาก `PRIORITY_MIN` (ต่ำสุด) ถึง `PRIORITY_MAX` (สูงสุด)

- `PRIORITY_UNSPECIFIED`
- `PRIORITY_MIN`
- `PRIORITY_LOW`
- `PRIORITY_DEFAULT`
- `PRIORITY_HIGH`
- `PRIORITY_MAX`

<Aside type="caution">
ส่ง `priority` เป็นหนึ่งในค่าสตริงข้างต้นเสมอ API ยังยอมรับค่าตัวเลขที่เทียบเท่าของ enum (1-5, ตรงกับลำดับข้างต้น) แต่การจับคู่นั้นเป็นรายละเอียด protobuf ภายใน ไม่ใช่สัญญาที่รองรับ — อย่าพึ่งพามัน

ค่า `priority` ที่ไม่รู้จัก (สตริงที่สะกดผิดหรือตัวเลขที่อยู่นอกช่วง) จะไม่ถูกปฏิเสธ: API จะละทิ้งมันอย่างเงียบๆ และการแจ้งเตือนจะถูกส่งโดยไม่มีฟิลด์ `priority` เลย แทนที่จะส่งคืนข้อผิดพลาด
</Aside>

## ตัวอย่าง: ส่ง push ไปยัง 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":     { "title": "Hello",   "body": "Hello, world!" },
              "android": { "title": "Hello",   "body": "Hello, world!" }
            },
            "es": {
              "ios":     { "title": "¡Hola!",  "body": "¡Hola, mundo!" },
              "android": { "title": "¡Hola!",  "body": "¡Hola, mundo!" }
            }
          }
        },
        "open_action": { "link": { "url": "https://example.com/promo" } }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'
```

## ตัวอย่าง: Transactional push โดย 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": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "ios":     { "title": "Your order", "body": "Order #42 has shipped." },
              "android": { "title": "Your order", "body": "Order #42 has shipped." }
            }
          }
        },
        "custom_data": { "order_id": "42" }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'
```