คู่มือ Push API (Sender Token)

ภาพรวม

ใช้ Sender Token เพื่อส่งการแจ้งเตือนผ่าน API ของระบบหลังบ้าน (ควรใช้ฝั่งเซิร์ฟเวอร์เท่านั้น และเก็บโทเค็นนี้เป็นความลับ)

Endpoint

รายละเอียด Payload

ตัวอย่าง

การตอบกลับ

ตัวอย่าง Response เมื่อ Firebase พร้อมใช้งาน

{
  "ok": true,
  "successCount": 1,
  "failureCount": 0
}

{
  "ok": true,
  "simulated": true,
  "sent": 1,
  "message_id": "message-uuid-for-rich-message"
}

สำหรับข้อความ Rich ในโหมด Firebase ค่า message_id จะอยู่ใน metadata ของ FCM เพื่อให้ Receiver ดึงรายละเอียดจาก Backend; ผู้เรียก API ควรใช้ค่า success/failure เป็นผลการส่งหลัก

การตอบกลับกรณีเกิดข้อผิดพลาด

Markdown และ Interactive Action

ข้อความ Markdown ใช้ได้กับ Sender ทุก policy โดยต้องส่ง body แบบ Plain เป็น fallback เสมอ ส่วนปุ่ม Interactive ใช้ได้เฉพาะ Sender ที่ตั้งเป็น verified_target และต้องยืนยัน Target ก่อน

ตัวอย่าง Interactive Push

curl -X POST "https://notipush.app/api/send-push" \
     -H "Content-Type: application/json" \
     -d '{
           "sender_token": "YOUR_SENDER_TOKEN",
           "title": "ยืนยันรายการ",
           "body": "กรุณาเปิดแอปเพื่อยืนยันรายการ",
           "content_type": "markdown",
           "body_markdown": "**รายละเอียดรายการ**\n\nยอดรวม: **1,000 บาท**",
           "target_id": "TARGET_ID",
           "request_id": "REQUEST_ID",
           "expires_at": "EXPIRY_ISO8601_WITHIN_24_HOURS",
           "actions": [
             { "id": "approve", "label": "อนุมัติ", "style": "primary" },
             { "id": "deny", "label": "ปฏิเสธ", "style": "danger" }
           ],
           "data": { "custom_tag": "billing" }
         }'

Verified Target และ Webhook

หากใช้ actions ระบบ Sender ต้องตั้งค่า verification URL, action webhook URL และ secret ผ่านหน้า Sender Integration ก่อนเปิดใช้ verified_target โดย URL ต้องเป็น HTTPS port 443 และห้ามมี redirect ไปยัง private address

Verification callback

เมื่อ Receiver ลงทะเบียน Target แบบ protected ระบบจะส่ง signed POST ไปยัง verification URL ของคุณ ให้ตอบ JSON นี้เมื่อรหัสถูกต้องและ Target ผูกกับผู้ใช้ของคุณแล้ว

POST https://YOUR_INTEGRATION_HOST/notipush/verify
X-NotiPush-Event-ID: EVENT_UUID
X-NotiPush-Timestamp: UNIX_TIMESTAMP
X-NotiPush-Signature: v1=HMAC_SHA256_HEX

{
  "event_id": "EVENT_UUID",
  "type": "subscription.verify",
  "sender_id": "SENDER_UUID",
  "notify_token": "NOTIFY_TOKEN_UUID",
  "target_id": "TARGET_ID",
  "verification_code": "ONE_TIME_CODE",
  "receiver_install_id": "INSTALL_UUID",
  "platform": "android",
  "timestamp": "2026-09-11T00:00:00.000Z"
}

HTTP 200
{ "verified": true, "external_subject_id": "EXTERNAL_SUBJECT_ID" }

Action webhook

เมื่อ Receiver กด action ระบบจะบันทึก event ก่อน แล้วส่ง signed POST ไปยัง action webhook แบบ asynchronous; endpoint ของคุณต้องใช้ event_id ทำ idempotency

POST https://YOUR_INTEGRATION_HOST/notipush/action
X-NotiPush-Event-ID: EVENT_UUID
X-NotiPush-Timestamp: UNIX_TIMESTAMP
X-NotiPush-Signature: v1=HMAC_SHA256_HEX

{
  "event_id": "EVENT_UUID",
  "type": "notification.action",
  "sender_id": "SENDER_UUID",
  "message_id": "MESSAGE_UUID",
  "request_id": "REQUEST_ID",
  "action_id": "approve",
  "target_id": "TARGET_ID",
  "external_subject_id": "EXTERNAL_SUBJECT_ID",
  "receiver_install_id": "INSTALL_UUID",
  "responded_at": "2026-09-11T00:00:00.000Z"
}

ตรวจลายเซ็นด้วย HMAC-SHA256 บนค่า UNIX_TIMESTAMP + '.' + raw JSON body และยอมรับเฉพาะ timestamp ที่อยู่ในหน้าต่างเวลาที่ระบบของคุณกำหนด

ถอนสิทธิ์ Target ผ่าน API

ใช้ endpoint นี้จากระบบของคุณเมื่อ Target ไม่ควรรับแจ้งเตือนอีกต่อไป เช่น เปลี่ยนผู้ใช้หรือยกเลิกสิทธิ์ ระบบจะ revoke เฉพาะ verified subscription ของ Target นั้น และไม่ลบประวัติ

curl -X POST "https://notipush.app/api/sender/targets/revoke" \
     -H "Content-Type: application/json" \
     -d '{
           "sender_token": "YOUR_SENDER_TOKEN",
           "target_id": "TARGET_ID"
         }'

{ "ok": true, "revoked_count": 1 }

ต้องส่ง Target เดียวเท่านั้น (ห้าม comma หรือ array) และ endpoint นี้ใช้ Sender Token จึงควรเรียกจาก server ของคุณเท่านั้น

ลิงก์ลงทะเบียน (Registration Link)

คุณสามารถสร้างลิงก์สำหรับให้ผู้รับ (Receiver) สแกนหรือกดเปิดเพื่อเพิ่มช่องรับแจ้งเตือนได้อัตโนมัติ โดยใส่ Notify Token และ Target ID (ถ้าต้องการ) ลงในลิงก์

รูปแบบลิงก์ (Web URL)

ใช้ลิงก์นี้ได้ทั้งบนเว็บ, แอป และ QR Code — จะ redirect ไปเปิดแอป Receiver อัตโนมัติ หรือพาไป App Store/Play Store หากยังไม่ได้ติดตั้ง

หากต้องการระบุ Target ID ด้วย:

สร้าง QR Code จากลิงก์

นำลิงก์ที่สร้างด้านบนไปสร้าง QR Code ด้วยเว็บไซต์ หรือ Library ในภาษาโปรแกรมของคุณ ไม่มี endpoint สำหรับสร้าง QR Code บนเซิร์ฟเวอร์ ผู้รับสแกน QR Code แล้วจะเปิดแอป Receiver พร้อมลงทะเบียนอัตโนมัติ

ตัวอย่าง: สร้าง QR Code ด้วย Python

import qrcode

notify_token = "YOUR_NOTIFY_TOKEN"
target_id = "room-101"  # Optional

url = f"https://notipush.app/r/?t={notify_token}&tg={target_id}"
img = qrcode.make(url)
img.save("notipush_qr.png")
print(f"QR Code saved: {url}")

ตัวอย่าง: สร้าง QR Code ด้วย JavaScript (Node.js)

const QRCode = require('qrcode');

const notifyToken = "YOUR_NOTIFY_TOKEN";
const targetId = "room-101"; // Optional

const url = `https://notipush.app/r/?t=${notifyToken}&tg=${targetId}`;
QRCode.toFile('notipush_qr.png', url, (err) => {
  if (err) throw err;
  console.log(`QR Code saved: ${url}`);
});

การใช้ Target ID (ส่งเจาะจงอุปกรณ์/กลุ่ม)

Target ID คือค่าที่ระบบของคุณ (Sender) เป็นคนกำหนดขึ้นมา ฝังไว้ในลิงก์หรือ QR Code ตอนที่ผู้รับลงทะเบียน เมื่อจำเป็นต้องส่งแจ้งเตือนเจาะจง คุณระบุ target_id ใน API call แล้วเฉพาะอุปกรณ์ที่ลงทะเบียนด้วย ID นั้นเท่านั้นที่จะได้รับ

ขั้นตอนการใช้งาน

ตัวอย่างการใช้งานจริง

ตัวอย่าง API: ส่งหาเป้าหมายเดียว

curl -X POST "https://notipush.app/api/send-push" \
     -H "Content-Type: application/json" \
     -d '{
           "sender_token": "YOUR_SENDER_TOKEN",
           "title": "ห้อง 101 — อาหารพร้อมเสิร์ฟ",
           "body": "กรุณามารับที่เคาน์เตอร์ชั้น 1",
           "target_ids": ["room-101"]
         }'

ตัวอย่าง API: ส่งหาหลายเป้าหมาย

curl -X POST "https://notipush.app/api/send-push" \
     -H "Content-Type: application/json" \
     -d '{
           "sender_token": "YOUR_SENDER_TOKEN",
           "title": "แจ้งเตือนฉุกเฉิน",
           "body": "กรุณาอพยพออกจากอาคารทันที",
           "target_ids": ["floor-1", "floor-2", "emergency"]
         }'

💡 ไม่ใส่ target_ids = ส่งหาทุกคนที่ติดตามช่องนี้ (Broadcast)  |  ใส่ target_ids = ส่งหาอุปกรณ์ที่ลงทะเบียนด้วย ID ใดๆ ในรายการ (array มีค่าเดียวก็ได้สำหรับเป้าหมายเดียว)