Gửi Web Push API

Tạo khoá VAPID và gửi thông báo Web Push tới subscription của trình duyệt, mã hoá payload theo RFC 8291, có TTL, urgency và topic.

GETPOSThttps://apibox.io.vn/v1/web-push

Tiện ích lập trình▶ Dùng thử online

Gọi không tham số (hoặc action=generate_keys) để nhận một cặp khoá VAPID P-256 mới dạng base64url: public_key dùng làm applicationServerKey khi gọi pushManager.subscribe() trên trình duyệt, private_key giữ ở máy chủ của bạn. Khoá chỉ được tạo cho phản hồi này, không bao giờ được lưu hay ghi log.

action=send gửi thông báo tới một subscription (JSON PushSubscription lấy từ trình duyệt: endpoint + keys.p256dh + keys.auth) hoặc tối đa 50 subscriptions. payload (văn bản hoặc JSON, tối đa 4.078 byte) được mã hoá aes128gcm (RFC 8291) bằng WebCrypto ECDH, HKDF, AES-GCM, và yêu cầu được ký bằng JWT VAPID ES256 (RFC 8292) từ đối tượng vapid của bạn (subject = địa chỉ liên hệ mailto: hoặc https:, public_key, private_key). Đặt ttl (giây, mặc định 86400), urgency (very-low, low, normal, high) và topic (thay thế tin chưa giao có cùng topic).

Mỗi kết quả có mã HTTP status của dịch vụ push; gone: true (404 / 410) nghĩa là subscription đã hết hạn và nên xoá. action=encrypt trả về body đã mã hoá và header mà không gửi, để gỡ lỗi hoặc tự gửi. Không có gì được lưu: subscription và khoá chỉ tồn tại trong yêu cầu.

Tham số

Tên	Vị trí	Kiểu	Bắt buộc	Mặc định
`action`	body\|query	string	không	`generate_keys`	`generate_keys` (mặc định khi không có subscription), `send` hoặc `encrypt` (tạo yêu cầu nhưng không gửi).
`subscription`	body	object	không		JSON PushSubscription: `{"endpoint": "https://...", "keys": {"p256dh": "...", "auth": "..."}}`.
`subscriptions`	body	array	không		Tối đa 50 subscription cho một lần gửi.
`payload`	body	string	không		Nội dung tin hoặc đối tượng JSON (tối đa 4.078 byte); bỏ trống để gửi push không dữ liệu.
`vapid`	body	object	không		`{"subject": "mailto:ban@example.com", "public_key": "...", "private_key": "..."}`, bắt buộc với `send`.
`ttl`	body\|query	number	không	`86400`	Số giây dịch vụ push giữ tin khi thiết bị offline (0-2.419.200).
`urgency`	body\|query	string	không	`normal`	`very-low`, `low`, `normal` hoặc `high`.
`topic`	body\|query	string	không		Tối đa 32 ký tự base64url; tin mới cùng topic thay thế tin chưa giao.

Ví dụ

curl -X POST "https://apibox.io.vn/v1/web-push" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"send","subscription":{"endpoint":"https://fcm.googleapis.com/fcm/send/abc","keys":{"p256dh":"BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4","auth":"BTBZMqHH6r4Tts7J_aSIgg"}},"payload":{"title":"Đơn hàng #1024","body":"Đã giao thành công"},"ttl":3600,"urgency":"high","vapid":{"subject":"mailto:ops@example.com","public_key":"BECWGWmqQ8K_C-FP8oHoC2GdtyNmQRTEHe8z3qsK5VDKHjkpMUG-RRrKyy-jczLPSqC1y15k6r_iPaGLt39VFOw","private_key":"(your private key)"}}'

const res = await fetch('https://apibox.io.vn/v1/web-push', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "action": "send",
    "subscription": {
      "endpoint": "https://fcm.googleapis.com/fcm/send/abc",
      "keys": {
        "p256dh": "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4",
        "auth": "BTBZMqHH6r4Tts7J_aSIgg"
      }
    },
    "payload": {
      "title": "Đơn hàng #1024",
      "body": "Đã giao thành công"
    },
    "ttl": 3600,
    "urgency": "high",
    "vapid": {
      "subject": "mailto:ops@example.com",
      "public_key": "BECWGWmqQ8K_C-FP8oHoC2GdtyNmQRTEHe8z3qsK5VDKHjkpMUG-RRrKyy-jczLPSqC1y15k6r_iPaGLt39VFOw",
      "private_key": "(your private key)"
    }
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://apibox.io.vn/v1/web-push",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"action": "send", "subscription": {"endpoint": "https://fcm.googleapis.com/fcm/send/abc", "keys": {"p256dh": "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4", "auth": "BTBZMqHH6r4Tts7J_aSIgg"}}, "payload": {"title": "Đơn hàng #1024", "body": "Đã giao thành công"}, "ttl": 3600, "urgency": "high", "vapid": {"subject": "mailto:ops@example.com", "public_key": "BECWGWmqQ8K_C-FP8oHoC2GdtyNmQRTEHe8z3qsK5VDKHjkpMUG-RRrKyy-jczLPSqC1y15k6r_iPaGLt39VFOw", "private_key": "(your private key)"}},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/web-push');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"action":"send","subscription":{"endpoint":"https://fcm.googleapis.com/fcm/send/abc","keys":{"p256dh":"BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4","auth":"BTBZMqHH6r4Tts7J_aSIgg"}},"payload":{"title":"Đơn hàng #1024","body":"Đã giao thành công"},"ttl":3600,"urgency":"high","vapid":{"subject":"mailto:ops@example.com","public_key":"BECWGWmqQ8K_C-FP8oHoC2GdtyNmQRTEHe8z3qsK5VDKHjkpMUG-RRrKyy-jczLPSqC1y15k6r_iPaGLt39VFOw","private_key":"(your private key)"}}',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Kết quả trả về

{
  "sent": 0,
  "failed": 1,
  "gone": 1,
  "ttl": 3600,
  "urgency": "high",
  "topic": null,
  "payload_bytes": 61,
  "results": [
    {
      "index": 0,
      "host": "fcm.googleapis.com",
      "ok": false,
      "status": 410,
      "gone": true,
      "retry_after": null,
      "message_id": null,
      "response": "push subscription has unsubscribed or expired.\n"
    }
  ]
}

Ứng dụng

Gửi thông báo đơn hàng, giao hàng từ backend PHP, Apps Script hoặc no-code
Tạo khoá VAPID cho PWA mới mà không cần cài thư viện web-push
Dọn subscription hết hạn nhờ cờ gone
Gỡ lỗi service worker bằng một tin push mã hoá chuẩn

Hỏi đáp

Có lưu khoá riêng VAPID hay subscription của tôi không?

Không. Khoá và subscription chỉ dùng trong yêu cầu, không ghi vào bộ nhớ hay log. Hãy gửi kèm trong mỗi lần gọi.

Dùng được với trình duyệt nào?

Mọi trình duyệt hỗ trợ Push API chuẩn có VAPID: Chrome / Edge (FCM), Firefox (Mozilla autopush), Safari 16+ (Apple), Opera, Samsung Internet. Endpoint trong subscription quyết định dịch vụ push.

Mã 410 nghĩa là gì?

Dịch vụ push báo subscription không còn tồn tại (người dùng huỷ đăng ký hoặc xoá dữ liệu trình duyệt). Kết quả có gone: true; hãy xoá subscription đó khỏi cơ sở dữ liệu.

Gửi Web Push API

Tham số

Ví dụ

Kết quả trả về

Ứng dụng

Hỏi đáp

API liên quan

Tạo UUID

Phân tích biểu thức cron

Giờ & múi giờ