การอ้างอิง Payload

การอ้างอิงสำหรับข้อความ Payload ที่ใช้โดย Notify เมื่อส่งผ่านช่องทางที่ไม่ใช่อีเมล (push, SMS, Telegram, Kakao, LINE, Viber, WhatsApp, Facebook Messenger)

Payload

preset (string): รหัส push preset (รูปแบบ XXXXX-XXXXX) ที่จะนำไปใช้กับข้อความนี้
sms_preset (string): รหัส (รูปแบบ XXXXX-XXXXX) ของ SMS preset ที่บันทึกไว้ ข้อความต่อ locale ของมันจะถูกแก้ไขเป็น sms.body ของแต่ละ locale sms.body แบบอินไลน์สำหรับ locale ที่กำหนดจะแทนที่ preset สำหรับ locale นั้น preset ต้องเป็นของแอปพลิเคชันเดียวกับข้อความ
content (LocalizedContent): เนื้อหาข้อความ ไม่สามารถใช้ร่วมกับ silent ได้
silent (bool): ส่ง push แบบเงียบ (ข้อมูลเท่านั้น) ไปยังทุกแพลตฟอร์ม ไม่สามารถใช้ร่วมกับ content ได้ หากต้องการให้เงียบเฉพาะบางแพลตฟอร์ม ให้ตั้งค่า silent ภายใน content สำหรับ iOS หรือ Android แทน
custom_data (object): JSON รูปแบบอิสระที่ส่งต่อไปยัง SDK ของไคลเอ็นต์เป็นพารามิเตอร์ u จำนวนเต็มที่มีขนาดใหญ่มากอาจสูญเสียความแม่นยำ ดู จำนวนเต็มขนาดใหญ่ในข้อมูลที่กำหนดเอง
custom_data_raw (string): สตริงที่มีออบเจ็กต์ JSON ซึ่งส่งต่อไปยัง SDK ของไคลเอ็นต์เป็นพารามิเตอร์ u ตัวเลขในสตริงนี้จะคงค่าที่แน่นอนไว้ ไม่สามารถใช้ร่วมกับ custom_data ที่ไม่ว่างได้ ค่าที่ไม่ถูกต้องจะส่งคืน 400
open_action (OpenAction): การกระทำที่เกิดขึ้นเมื่อผู้ใช้เปิดการแจ้งเตือน
open_actions (map<Platform, OpenAction>): การแทนที่ open_action ต่อแพลตฟอร์ม คีย์คือค่า enum Platform ที่เป็นตัวเลข
voip_push (bool): การแจ้งเตือน iOS VoIP

{
  "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" } }
  }
}

จำนวนเต็มขนาดใหญ่ในข้อมูลที่กำหนดเอง

จำนวนเต็มที่มากกว่า 9007199254740992 จะสูญเสียความแม่นยำใน custom_data ใช้ custom_data_raw เพื่อให้ค่าแม่นยำ

custom_data เป็น google.protobuf.Struct (ออบเจ็กต์ทั่วไปที่คล้าย JSON) ซึ่งจัดเก็บทุกตัวเลขเป็น double ซึ่งเป็นเลขทศนิยมแบบ floating-point ขนาด 64 บิตที่แม่นยำเฉพาะจำนวนเต็มไม่เกิน 9007199254740992 จำนวนเต็มที่ใหญ่กว่านั้นจะถูกปัดเศษ: 5190090000030465245 จะไปถึงอุปกรณ์เป็น 5190090000030465000 สตริงไม่ได้รับผลกระทบ

หากต้องการให้จำนวนเต็มดังกล่าวแม่นยำ ให้ส่งสตริงที่มีออบเจ็กต์ JSON ใน custom_data_raw:

{ "payload": { "silent": true, "custom_data_raw": "{\"pushUID\": 5190090000030465245}" } }

กฎสำหรับ custom_data_raw:

สตริงต้องมีออบเจ็กต์ JSON อาร์เรย์ สตริง null หรือ JSON ที่ไม่ถูกต้องจะส่งคืน 400 (INVALID_ARGUMENT) พร้อมการละเมิดฟิลด์ที่ payload.custom_data_raw
หาก custom_data มีคีย์ใดๆ และมีการตั้งค่า custom_data_raw คำขอจะส่งคืน 400 ออบเจ็กต์ custom_data ที่ว่างจะถูกละเว้น
เช่นเดียวกับ custom_data จะแทนที่ข้อมูลที่กำหนดเองที่บันทึกไว้ใน push preset
ออบเจ็กต์จะถูกแปลงกลับเป็นข้อความ JSON ก่อนการส่ง ลำดับของคีย์จะไม่ถูกรักษาไว้และช่องว่างจะถูกลบออก ตัวเลขจะคงค่าที่แน่นอนไว้ แต่ข้อความต้นฉบับจะไม่ถูกรักษาไว้ทุกไบต์
ใน /messaging/v2/notify/batch custom_data_raw ที่ไม่ถูกต้องจะทำให้เฉพาะรายการของตัวเองล้มเหลว รายการอื่นๆ จะถูกส่ง

วิธีที่คุณส่งคำขอ:

REST: ไม่ต้องเปลี่ยนแปลงใดๆ สำหรับ /messaging/v2/notify และ /messaging/v2/notify/batch หาก custom_data มีจำนวนเต็มที่ double ไม่สามารถแสดงได้อย่างแม่นยำ API จะเก็บค่านั้นไว้โดยไม่สูญเสียโดยอัตโนมัติ คุณยังสามารถตั้งค่า custom_data_raw อย่างชัดเจนได้
gRPC: ไคลเอ็นต์สร้าง Struct เอง ดังนั้นความแม่นยำจะสูญเสียไปก่อนที่จะส่งคำขอ ให้กรอก custom_data_raw แทน custom_data

ปลายทางที่การแจ้งเตือนถูกส่งไป:

Android: SDK ส่ง u ให้แอปเป็นสตริงผ่าน PushMessage.getCustomData() ดังนั้นทุกหลักจะถูกรักษาไว้
Web push: Web SDK แยกวิเคราะห์ u ด้วย JSON.parse และทุกตัวเลขใน JavaScript เป็น double จำนวนเต็มขนาดใหญ่จะถูกปัดเศษในเบราว์เซอร์ไม่ว่า API จะเป็นอย่างไร ดังนั้นให้ส่งเป็นสตริง
Windows: toast ได้รับข้อมูล u เดียวกันกับแพลตฟอร์มอื่น และจำนวนเต็มที่ส่งผ่าน custom_data_raw จะมาถึงอย่างแม่นยำ

LocalizedContent

แมปรหัส locale กับเนื้อหาต่อแพลตฟอร์ม คีย์คือรหัสสองตัวอักษร ISO 639-1 (ตัวอย่างเช่น "en", "es") บวกกับคีย์พิเศษ "default" สำหรับการแปลแบบครอบคลุมทั้งหมด ข้อยกเว้นสำหรับ ISO 639-1 คือ "zh-Hant" และ "zh-Hans" สำหรับภาษาจีนตัวเต็มและตัวย่อ

{
  "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" }
    }
  }
}

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

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

ตรงกับภาษาของอุปกรณ์อย่างสมบูรณ์
คีย์ "default"
คีย์ "en"
locale อื่นๆ ที่มีอยู่ในแมป

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

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

บล็อกแพลตฟอร์ม	ช่องทาง
`ios`	iOS push
`android`	Android (FCM) push
`huawei_android`	Huawei 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
`fb_messenger`	ข้อความ Facebook Messenger
`sms`	ข้อความ SMS

ปุ่ม

แต่ละรายการภาษายังสามารถมี buttons ซึ่งเป็นปุ่มการดำเนินการสูงสุด 3 ปุ่มที่แสดงใต้พุชบน iOS, Android และ Huawei แพลตฟอร์มอื่นจะไม่สนใจปุ่มเหล่านี้ ปุ่มต้องใช้ iOS SDK 7.2.10 ขึ้นไปพร้อม Notification Service Extension และ Android SDK 6.17.0 ขึ้นไป

แต่ละ PushButton มีฟิลด์ต่อไปนี้:

id (string): ID ของปุ่มที่แอปของคุณได้รับเมื่อแตะ สูงสุด 64 อักขระ ไม่มีช่องว่าง และไม่ซ้ำกันภายในพุช จำเป็นสำหรับ ACTION_OPEN และ ACTION_CUSTOM หากไม่ระบุสำหรับการดำเนินการอื่น Pushwoosh จะตั้งค่าเป็น btn_1, btn_2 และต่อไปเรื่อยๆ
label (string): ข้อความบนปุ่ม ยาว 1 ถึง 64 อักขระ
action (enum): ACTION_OPEN เปิดแอป, ACTION_URL เปิด url, ACTION_DEEPLINK เปิด deep link, ACTION_CUSTOM ส่ง id ไปยังแอปของคุณ และแอปของคุณจะจัดการเอง
url (string): ที่อยู่ http หรือ https แบบสมบูรณ์สำหรับ ACTION_URL หรือ deep link ที่มี scheme สำหรับ ACTION_DEEPLINK
platform_urls (map): deep link แยกตามแพลตฟอร์มสำหรับ ACTION_DEEPLINK โดยใช้รหัสแพลตฟอร์มเป็นคีย์: 1 iOS, 3 Android, 17 Huawei
style (enum): STYLE_DEFAULT หรือ STYLE_DESTRUCTIVE สไตล์ destructive จะแสดงปุ่มเป็นสีแดงบน iOS

{
  "localized_content": {
    "default": {
      "ios": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "android": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "buttons": [
        { "id": "track", "label": "Track order", "action": "ACTION_DEEPLINK", "url": "myapp://orders/42" },
        { "id": "cancel", "label": "Cancel order", "action": "ACTION_CUSTOM", "style": "STYLE_DESTRUCTIVE" }
      ]
    }
  }
}

ฟิลด์พุชทั่วไป

ฟิลด์เหล่านี้ใช้ร่วมกันโดยบล็อก ios, android, huawei_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): การแทนที่เพย์โหลดเฉพาะแพลตฟอร์มแบบดิบ
inbox (Inbox): รายการ Message Inbox

{
  "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 เดียวกันจะแทนที่กันบนอุปกรณ์
silent (bool): ส่ง push ของ iOS แบบเงียบ (ข้อมูลเท่านั้น) ในขณะที่แพลตฟอร์มอื่นในข้อความเดียวกันได้รับการแจ้งเตือนปกติ ตั้งค่าภายใน content จึงทำงานร่วมกับ content ได้ หากต้องการให้ทุกแพลตฟอร์มเงียบ ให้ใช้ silent ระดับบนสุดแทน ซึ่งจะแทนที่ content ตั้งค่าใน locale ใดก็ได้เพื่อให้มีผลกับทุก locale

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

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): ลำดับความสำคัญในถาด
group_id (string): คีย์กลุ่มการแจ้งเตือน
collapse_key (string): คีย์การยุบของ FCM การแจ้งเตือนที่มี collapse_key เดียวกันจะแทนที่กันในขณะที่อุปกรณ์ออฟไลน์
silent (bool): ส่ง push ไปยังแพลตฟอร์มนี้แบบเงียบ (ข้อมูลเท่านั้น) ในขณะที่แพลตฟอร์มอื่นในข้อความเดียวกันได้รับการแจ้งเตือนปกติ ตั้งค่าภายใน content จึงทำงานร่วมกับ content ได้ หากต้องการให้ทุกแพลตฟอร์มเงียบ ให้ใช้ silent ระดับบนสุดแทน ซึ่งจะแทนที่ content ตั้งค่าใน locale ใดก็ได้เพื่อให้มีผลกับทุก locale บล็อก baidu_android ก็รองรับ silent เช่นกันโดยมีลักษณะการทำงานเหมือนกัน

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

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

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

Amazon (`amazon`)

ใช้ฟิลด์พุชทั่วไปบวกกับ custom_icon และ priority (NotificationPriority)

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

{
  "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: ปุ่มดำเนินการสูงสุดสองปุ่ม

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

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

Windows (`windows`)

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

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

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

Telegram (`telegram`)

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

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

Kakao (`kakao`)

content (string): เนื้อหาข้อความ
template (string): รหัสเทมเพลตที่ได้รับอนุมัติ
content_variables (string): การผูกตัวแปรเทมเพลตที่แปลงเป็นสตริง 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) สำหรับเนื้อหา rich content ให้กำหนดค่าเทมเพลตล่วงหน้าใน Control Panel และอ้างอิงที่นี่

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

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

Viber (`viber`)

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

body (string): ข้อความธรรมดา จำเป็นเมื่อไม่ได้ตั้งค่า template_id เว้นแต่จะตั้งค่า image ไว้ จำเป็นเมื่อมีปุ่มหรือ carousel
image (string): URL สาธารณะของรูปภาพ จะถูกละเว้นเมื่อตั้งค่า template_id
button_caption (string): ข้อความบนปุ่ม ไม่เกิน 30 อักขระ ตั้งค่าคู่กับ button_action ต้องมี body จะถูกละเว้นเมื่อตั้งค่า template_id
button_action (string): ลิงก์ของปุ่ม: URL แบบ http:// หรือ https://, deep link แบบ viber:// หรือโทเค็น Omni เช่น {lp-100} (ตัวยึดตำแหน่งของลิงก์ติดตามที่ Omni Messaging แปลงค่าในขณะส่ง) ตั้งค่าคู่กับ button_caption
carousel (object): การ์ดที่ปัดดูได้ 2–5 ใบซึ่งแสดงอยู่ใต้ body ใช้ร่วมกับ image, button_caption, button_action หรือ template_id ไม่ได้ ดู Carousel
template_id (string): id ของเทมเพลตธุรกรรมที่ได้รับการอนุมัติล่วงหน้า เมื่อตั้งค่าแล้ว จะมีความสำคัญเหนือกว่า body
template_lang (string): locale ของเทมเพลต จำเป็นเมื่อตั้งค่า template_id
template_params (map<string, string>): การผูกค่าคีย์/ค่าที่ใช้แทนที่ในเทมเพลต เช่น { "name": "John", "code": "123456" }
all_devices (bool): false (ค่าเริ่มต้น) ส่งไปยังอุปกรณ์หลักของผู้ใช้เท่านั้น true ส่งไปยังอุปกรณ์ทั้งหมดของผู้ใช้

ต้องตั้งค่าอย่างน้อยหนึ่งอย่างระหว่าง body, image หรือ template_id เมื่อตั้งค่า template_id แล้ว template_lang จะเป็นสิ่งจำเป็น

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

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

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

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

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

Carousel

carousel.items มีการ์ด 2 ถึง 5 ใบ หากต้องการตั้งค่า carousel ใน journey แทน ดู ส่ง carousel การ์ดแต่ละใบมีฟิลด์ต่อไปนี้:

title (string): ชื่อการ์ด 2–38 อักขระ จำเป็น
image (string): URL สาธารณะของรูปภาพแบบ http:// หรือ https:// จำเป็น
primary_button (object): ปุ่มหลัก จำเป็น
secondary_button (object): ปุ่มที่สอง ไม่บังคับ

ปุ่มแต่ละปุ่มมีสองฟิลด์ และทั้งสองฟิลด์จำเป็นเมื่อมีปุ่มนั้น:

caption (string): ข้อความบนปุ่ม ไม่เกิน 10 อักขระสำหรับ primary_button และไม่เกิน 12 อักขระสำหรับ secondary_button
action (string): ลิงก์ของปุ่ม: URL ที่มี scheme (http://, https://, viber://) หรือโทเค็น Omni เช่น {lp-100} ซึ่งเป็นค่าเดียวกับ button_action

คำขอที่ละเมิดกฎข้อใดข้อหนึ่งเหล่านี้จะถูกปฏิเสธด้วย INVALID_ARGUMENT รายละเอียด google.rpc.BadRequest จะระบุชื่อฟิลด์ เช่น viber.carousel.items[0].title

ตัวอย่าง:

{
  "viber": {
    "body": "New arrivals are in. Swipe to see them.",
    "carousel": {
      "items": [
        {
          "title": "Running shoes",
          "image": "https://example.com/img/shoes.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/shoes" },
          "secondary_button": { "caption": "Details", "action": "{lp-100}" }
        },
        {
          "title": "Sports backpack",
          "image": "https://example.com/img/backpack.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/backpack" }
        }
      ]
    }
  }
}

WhatsApp (`whatsapp`)

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

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

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

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

Facebook Messenger (`fb_messenger`)

ข้อความ Facebook Messenger จะส่งผ่าน Meta และอยู่ภายใต้กฎการส่งข้อความของ Meta: เนื้อหารูปแบบอิสระจะถูกส่งเฉพาะภายในหน้าต่างบริการลูกค้า 24 ชั่วโมงที่เปิดโดยข้อความขาเข้าจากผู้ใช้เท่านั้น นอกหน้าต่างนั้น ให้ตั้งค่า message_tag เป็นหนึ่งในกรณีการใช้งานที่ได้รับอนุมัติจาก Meta มิฉะนั้น Meta จะปฏิเสธการส่ง

body (string): ข้อความธรรมดา จำเป็นต้องระบุ เว้นแต่คุณตั้งค่า message
message (string): ออบเจ็กต์ message ของ Meta Send API แบบสมบูรณ์ในรูปแบบสตริง JSON ซึ่งมีข้อความ ไฟล์แนบ เทมเพลต หรือการตอบกลับด่วน เมื่อตั้งค่าแล้ว Pushwoosh จะส่งออบเจ็กต์นี้แทน body
message_tag (string): จำเป็นต้องระบุนอกหน้าต่าง 24 ชั่วโมง หนึ่งใน CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE, HUMAN_AGENT

{
  "fb_messenger": {
    "body": "Hello from Pushwoosh",
    "message_tag": "ACCOUNT_UPDATE"
  }
}

สำหรับช่องทางนี้ ไม่มีตัวระบุอุปกรณ์แยกต่างหาก: hwid, push_token และ user_id ทั้งหมดจะถูกแก้ไขเป็นค่าเดียวกัน คือ Page-Scoped ID (PSID) ของผู้รับใน Meta กำหนดเป้าหมายการสนทนาที่เฉพาะเจาะจงด้วยหนึ่งในนั้นใน NotifyTransactional

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": ["FB_MESSENGER"],
      "hwids": { "list": ["<recipient-psid>"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "fb_messenger": { "body": "Hello from Pushwoosh" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" }
    }
  }'

SMS (`sms`)

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

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

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

อินไลน์ — ตั้งค่า sms.body ต่อ locale ใน localized_content
จาก preset — ตั้งค่า sms_preset ระดับเพย์โหลดเป็นรหัส (รูปแบบ XXXXX-XXXXX) ของ SMS preset ที่บันทึกไว้ เนื้อหาต่อ locale ของมันจะถูกแก้ไขเป็น sms.body สำหรับแต่ละ locale ที่ preset กำหนด sms.body แบบอินไลน์สำหรับ locale จะแทนที่ preset สำหรับ locale นั้น ทำให้คุณสามารถใช้ preset ซ้ำและยังคงปรับแต่งแต่ละภาษาได้

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

MMS

การเพิ่ม subject และ file_urls ลงในบล็อก sms จะเปลี่ยนข้อความเป็น MMS มีเพียง AbleMobile เท่านั้นที่มี endpoint สำหรับ MMS — ผู้ให้บริการ SMS รายอื่นจะละเว้นทั้งสองฟิลด์และส่งเฉพาะ body ที่เป็นข้อความธรรมดา

subject (string): หัวเรื่อง MMS ต้องมีอย่างน้อยหนึ่งรายการใน file_urls — หัวเรื่องที่ไม่มีไฟล์แนบจะถูกปฏิเสธ รองรับอักขระ ASCII ได้สูงสุด 40 ตัว หรือ 13 ตัวหากหัวเรื่องมีอักขระที่ไม่ใช่ ASCII
file_urls (array of string): URL ไฟล์แนบสูงสุด 3 รายการ แต่ละรายการต้องเป็น URL https แบบสมบูรณ์ที่ลงท้ายด้วย .jpg หรือ .gif — .jpeg และ .png จะถูกปฏิเสธโดยการตรวจสอบความถูกต้อง แม้ว่าจะเป็นไฟล์ JPEG หรือ PNG จริงก็ตาม เนื่องจากผู้ให้บริการไม่สามารถถอดรหัสได้ นอกจากนี้แต่ละไฟล์ต้องมีขนาดไม่เกิน 200 KB AbleMobile จะปฏิเสธการส่งทั้งหมดหากมีไฟล์แนบใดหนักกว่านี้
message_at (int): ดัชนีใน file_urls (เริ่มต้นที่ 0) ที่ข้อความ SMS จะแสดงหลังจากนั้น

subject และ file_urls รองรับ การปรับแต่ง Liquid เช่นเดียวกับ body

{
  "sms": {
    "body": "Your order has shipped.",
    "subject": "Order update",
    "file_urls": [
      "https://cdn.example.com/shipping-label.jpg",
      "https://cdn.example.com/tracking-map.gif"
    ],
    "message_at": 1
  }
}

RCS

การเพิ่ม rcs ลงในบล็อก sms จะส่งเทมเพลตเนื้อหาของ Twilio ผ่าน RCS (Rich Communication Services) แทน body Twilio จะส่งเทมเพลตเป็นข้อความ RCS และใช้ SMS ที่สร้างจากประเภท twilio/text ของเทมเพลตเป็นทางสำรอง ไม่ใช่จาก body เทมเพลตที่ไม่มีประเภท twilio/text จะส่งถึงเฉพาะโทรศัพท์ที่รองรับ RCS เท่านั้น

rcs.content_sid (string): SID ของเทมเพลตเนื้อหา Twilio คือ HX ตามด้วยอักขระฐานสิบหก 32 ตัว รับได้จาก ListRcsTemplates หรือ Twilio Console
rcs.content_variables (string): ออบเจ็กต์ JSON ของตัวแปรเทมเพลตที่แปลงเป็นสตริง เช่น "{\"1\": \"{FirstName|CapitalizeFirst|there}\"}" ค่ารองรับแท็กและ การปรับแต่ง Liquid ตัวแปรที่คุณไม่ได้ระบุจะใช้ค่าเริ่มต้นของเทมเพลต

ยังคงต้องระบุ body ในบล็อก sms ที่มี rcs

คำขอจะถูกปฏิเสธ เว้นแต่แอปพลิเคชันจะส่ง SMS ผ่าน Twilio ด้วย Account SID, Auth token และ Messaging Service SID ของตัวเองที่ตั้งค่าไว้ใน การกำหนดค่าแพลตฟอร์ม SMS แอปพลิเคชันที่ใช้ข้อมูลรับรอง Twilio ที่ Pushwoosh จัดเตรียมให้ไม่สามารถส่ง RCS ได้

SMS preset สามารถมีเทมเพลตต่อ locale ได้ เมื่อมี sms_preset ในเพย์โหลด เทมเพลตของ preset จะถูกใช้กับทุก locale ที่คำขอไม่ได้ระบุ rcs.content_sid ของตัวเอง

{
  "sms": {
    "body": "Your order has shipped.",
    "rcs": {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "content_variables": "{\"1\": \"{FirstName|CapitalizeFirst|there}\", \"2\": \"A-1042\"}"
    }
  }
}

แสดงรายการเทมเพลต RCS

ListRcsTemplates ส่งคืนเทมเพลตเนื้อหา Twilio ของแอปพลิเคชันที่สามารถส่งผ่าน RCS ได้ โดยอ่านด้วยข้อมูลรับรอง Twilio ของแอปพลิเคชันเอง

GET https://rpc-api.svc-nue.pushwoosh.com/api/sms_presets:rcs_templates?application=XXXXX-XXXXX
Authorization: Api YOUR_API_TOKEN

application (string, query): รหัสแอปพลิเคชัน รูปแบบ XXXXX-XXXXX

การตอบกลับมีอาร์เรย์ templates โดยจะแสดงเฉพาะเทมเพลตที่มีประเภทเนื้อหา RCS อย่างน้อยหนึ่งประเภท: twilio/card, twilio/carousel, twilio/quick-reply, twilio/call-to-action หรือ twilio/media

ฟิลด์	ประเภท	คำอธิบาย
`content_sid`	string	SID ของเทมเพลต ซึ่งเป็นค่าสำหรับ `rcs.content_sid`
`friendly_name`	string	ชื่อเทมเพลตใน Twilio
`language`	string	รหัสภาษาของเทมเพลต
`types`	array of string	ประเภทเนื้อหา Twilio ที่เทมเพลตกำหนด เช่น `twilio/card` และ `twilio/text`
`variables`	object	ตัวแปรของเทมเพลตพร้อมค่าเริ่มต้น
`has_sms_fallback`	boolean	`true` เมื่อเทมเพลตมีประเภท `twilio/text` ซึ่งเป็น SMS ที่โทรศัพท์ที่ไม่รองรับ RCS จะได้รับ

{
  "templates": [
    {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "friendly_name": "order_shipped_card",
      "language": "en",
      "types": ["twilio/card", "twilio/text"],
      "variables": { "1": "there", "2": "your order" },
      "has_sms_fallback": true
    }
  ]
}

ListRcsTemplates ส่งคืนข้อผิดพลาดต่อไปนี้:

สถานะ HTTP	สาเหตุ
`400 Bad Request`	แอปพลิเคชันไม่มี Account SID และ Auth token ของ Twilio เป็นของตัวเอง (`FailedPrecondition`)
`401 Unauthorized`	Twilio ปฏิเสธข้อมูลรับรองของแอปพลิเคชัน (`Unauthenticated`)
`503 Service Unavailable`	Twilio Content API ส่งคืนข้อผิดพลาดอื่น (`Unavailable`)

OpenAction

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

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

rich_media (RichMedia): เปิดหน้า Rich Media
deep_link: เปิด deep link: { "code": "flow-code", "params": { "key": "value" } }
link (Link): เปิด URL

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

URL ของ deeplink และค่า params รองรับไวยากรณ์ การปรับแต่ง Liquid — นิพจน์จะถูกประมวลผลก่อนที่จะเปิด deep link

RichMedia

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

Link

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

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

Inbox

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

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

image_url (string): รูปภาพที่แสดงในรายการ inbox
expiration_date (timestamp): เวลาที่รายการจะถูกลบออกจาก inbox
expires_in (duration, เช่น "604800s"): ระยะเวลาที่รายการจะอยู่ใน inbox นับจากวันที่ส่ง (send_date ที่กำหนดไว้ หรือเวลาที่ส่งคำขอสำหรับการส่งทันที) ต้องเป็นค่าบวก จะถูกละเว้นเมื่อตั้งค่า expiration_date ไว้

หากต้องการกำหนดอายุแบบสัมพัทธ์แทนวันที่ตายตัว ให้ส่งเฉพาะ expires_in:

{
  "image_url": "https://cdn.example.com/inbox.png",
  "expires_in": "604800s"
}

หากบัญชีของคุณมีอายุสูงสุดของ inbox กำหนดไว้ expiration_date หรือ expires_in ที่เกินกว่านั้นจะถูกปฏิเสธ

NotificationPriority enum

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

PRIORITY_UNSPECIFIED
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

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

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

ตัวอย่าง: ส่งพุชไปยังเซกเมนต์

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"
    }
  }'

ตัวอย่าง: พุชธุรกรรมตาม User ID

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"
    }
  }'

การอ้างอิง Payload

Payload

จำนวนเต็มขนาดใหญ่ในข้อมูลที่กำหนดเอง

LocalizedContent

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

ปุ่ม

ฟิลด์พุชทั่วไป

iOS (ios)

Android (android, huawei_android)

macOS (mac_os)

Amazon (amazon)

Safari (safari)

Chrome (chrome)

Firefox (firefox)

Windows (windows)

Telegram (telegram)

Kakao (kakao)

LINE (line)

Viber (viber)