Thông báo trình duyệt (Web Push)
Bật thông báo cho trình duyệt khách và gửi thử: quyền đồng ý, tệp trên website và khóa VAPID.
Trên trang này
Web Push hiển thị thông báo bằng trình duyệt. Trước tiên khách trên website có widget phải cho phép thông báo. Tính năng này khác với chuông thông báo và thông báo cho nhân viên trong GetMyBot.
Bước 1. Đặt service worker trên tên miền của bạn
Nhờ người quản trị website đặt tệp mybot-sw.js. Thiếu tệp này, trình duyệt không nhận và hiển thị được thông báo.
Service worker là script nhỏ mà trình duyệt dùng để nhận thông báo. Nó phải nằm trên website của bạn; script từ tên miền GetMyBot không điều khiển được thông báo của tên miền khác. Địa chỉ gồm giao thức và tên miền, không có đường dẫn trang, gọi là origin, ví dụ https://example.com.
-
Trong Widget → Web Push, tải
mybot-sw.js. -
Đặt tệp ở gốc mỗi origin có widget, đúng đường dẫn:
https://example.com/mybot-sw.js https://shop.example.com/mybot-sw.jsCài đặt Web Push liệt kê địa chỉ mong đợi cho từng liên kết thông báo được phép để bạn mở kiểm tra.
-
Mở URL tệp trong trình duyệt. Nó phải trả JavaScript qua HTTPS, không phải trang HTML,
404hay chuyển hướng. Với website một trang hoặc CDN, kiểm tra riêng rằng URL này không trảindex.html. -
Sau khi nền tảng cập nhật, tải tệp mới lên như tài nguyên tĩnh thông thường. Thay cài đặt Web Push hoặc xoay khóa không đòi cài lại tệp.
Widget chỉ đăng ký hoặc dùng lại worker tại /mybot-sw.js. Hai tham số định tuyến công khai mb_key và mb_api do widget tự thêm; bạn không cần nhập.
Nếu tự đăng ký worker
Để tự quản lý việc đăng ký hoặc giới hạn website có thể mở khi bấm thông báo:
navigator.serviceWorker.register("/mybot-sw.js?nav=https://shop.example.com");
nav nhận tối đa 8 HTTPS origin chính xác, cách nhau bằng dấu phẩy. Worker kiểm tra URL đích theo danh sách của nó và origin của chính nó, độc lập với danh sách phía máy chủ ở bước 2. Nếu widget thấy đăng ký này, nó giữ nav của bạn.
Nếu website đã có service worker
Widget không thay thế worker khác vì có thể làm hỏng website, và đăng ký push qua worker đó sẽ thiếu bộ xử lý thông báo và cú bấm. Nếu một worker khác đã kiểm soát trang, thử đăng ký sẽ báo «không khả dụng». Đặt mybot-sw.js trên site chưa có worker ở phạm vi gốc, hoặc liên hệ hỗ trợ trước khi kết hợp hai worker.
Bước 2. Bật Web Push cho bot
Web Push được cấu hình ở Widget, cạnh kênh web. Cần hai trường:
- Liên hệ VAPID: URL
mailto:hoặc HTTPS để dịch vụ push báo lỗi giao nhận, ví dụmailto:help@example.com. - Liên kết thông báo được phép: mỗi dòng một HTTPS origin. Cú bấm chỉ mở đường dẫn tương đối trên site hoặc đúng origin trong danh sách. Đây là trường bắt buộc; URL ngoài danh sách bị từ chối trước khi gửi.
Lần lưu đầu, máy chủ tạo cặp khóa VAPID. Trình duyệt nhận khóa công khai; khóa riêng không rời máy chủ và không được trả qua API. Giờ im lặng có trong API nhưng màn hình này chưa có trường chỉnh.
Bước 3. Xin quyền của khách
Khách phải tự đồng ý. Chỉ tải trang không đăng ký thông báo:
- Hộp thoại xin quyền của trình duyệt chỉ mở sau khi khách chủ động bấm nút thông báo trong widget.
- Nếu khách chưa bấm, họ không thấy lỗi; nếu trình duyệt không hỗ trợ hoặc quyền đã bị từ chối, mục này ẩn đến lần thử đầu.
- Tải widget chỉ cập nhật sự đồng ý đã có, không tự hiện hộp thoại, cài worker hoặc tạo đăng ký mới.
- Lần từ chối được giữ qua lần tải trang, kể cả khi trình duyệt còn giữ đối tượng đăng ký cũ.
Sau khi widget tải, mã trang của bạn cũng có thể gọi:
await window.mybot.push.subscribe(); // xin quyền và đăng ký
await window.mybot.push.unsubscribe(); // thu hồi trên máy chủ và trình duyệt
Đăng ký có trạng thái subscribed (hoạt động), revoked (khách đã hủy) hoặc expired (địa chỉ giao không còn hoạt động). GetMyBot và API hiển thị loại trình duyệt, ngôn ngữ, múi giờ, trạng thái và ngày. URL giao và khóa mã hóa được lưu mã hóa trên máy chủ, không hiện lại cho chủ sở hữu và không được trả qua API/MCP.
Gửi thử
Phần thử gửi một thông báo cho trình duyệt đăng ký gần nhất. Cần đồng thời:
- Web Push của bot đã bật.
- Ít nhất một đăng ký ở trạng thái
subscribed. - Một tài liệu loại Push đã xuất bản trong Studio nội dung; bản gửi thử dùng đúng phiên bản đã xuất bản đó.
Sau khi bấm gửi, GetMyBot trả ngay ID tin, còn việc giao chạy nền. Chọn đối tượng, lên lịch hoặc dừng phát chưa có trên màn hình nào.
Giới hạn nội dung thông báo
Vi phạm một giới hạn sẽ bị từ chối toàn bộ, không cắt ngắn tự động.
| Trường | Giới hạn |
|---|---|
title | Bắt buộc, 1–120 ký tự |
body | Bắt buộc, 1–512 ký tự |
tag | Tùy chọn, tối đa 128 ký tự |
actions | Tối đa 2; ID và nhãn mỗi nút 1–64 ký tự, không trùng |
icon_url, image_url | Chỉ HTTPS, không có userinfo hoặc dấu # |
navigation | Đường dẫn bắt đầu / hoặc đúng origin được phép |
data | Chỉ khóa action, campaign_id, content_id, experiment_id, message_id; mỗi giá trị tối đa 256 ký tự |
| Toàn bộ payload | Tối đa 3 KiB |
data bị từ chối nếu chứa bearer , secret, password, token= hoặc @, tránh đưa dữ liệu hồ sơ hay token vào thông báo. Payload tự đặt receipt_signature cũng bị từ chối; máy chủ tự thêm lúc giao. Máy chủ và worker coi URL dạng //host/path hoặc có dấu gạch chéo ngược là origin bên ngoài, không phải đường dẫn tương đối.
Giờ im lặng
Giờ im lặng là khoảng địa phương lặp lại khi việc giao được hoãn, không hủy; tin đi vào thời điểm hợp lệ đầu tiên. Dùng múi giờ của người nhận lưu cùng đăng ký, nếu thiếu dùng múi giờ bot. Khoảng có giờ kết thúc trước giờ bắt đầu đi qua nửa đêm. Thời điểm rơi vào giờ không tồn tại do đổi giờ được đẩy đến thời điểm hợp lệ tiếp theo.
Cấu hình này nằm trong Web Push qua REST API ở trường quiet_hours; giao diện GetMyBot chưa có trình sửa.
Giao nhận, thử lại và biên nhận
- Bộ xử lý nền nhận tin, giữ quyền xử lý tạm và thử lại tối đa 8 lần hoặc trong 24 giờ, tùy mốc nào đến trước.
429được thử lại theoRetry-After, tối đa 24 giờ. Hết giờ chờ và5xxđược thử lại với thời gian giãn cách ngẫu nhiên;4xxkhác là lỗi cuối.404hoặc410nghĩa là đăng ký biến mất: chuyển sangexpiredvà không thử tiếp.- Worker gửi biên nhận
clickkhi khách mở,closekhi khách đóng. Mỗi biên nhận được ký và gắn với một tin cùng một đăng ký, không thể dùng lại cho tin khác. - Báo cáo cấu hình đếm đăng ký theo trạng thái và lần mở. Hệ thống ghi
accepted,sent,failed,expired,clicked,closed; chúng cũng vào dòng sự kiện khách trong Người dùng.
Body trả về từ dịch vụ push không được lưu; lần giao lỗi chỉ giữ mã lý do từ danh sách cố định.
Xoay khóa VAPID
Đổi khóa VAPID vô hiệu hóa toàn bộ đăng ký hiện có. Giao diện hiển thị số trình duyệt bị ảnh hưởng và yêu cầu xác nhận riêng. Về kỹ thuật, yêu cầu đầu trả 409 với số đăng ký đang hoạt động. Sau xác nhận, hệ thống tạo cặp khóa mới và đăng ký cũ hết hiệu lực. Mỗi khách phải cho phép lại vì đăng ký trình duyệt gắn với khóa cũ.
Widget bỏ đăng ký dùng khóa cũ và tạo lại khi khách chủ động đồng ý lần sau, thay vì giữ đăng ký không còn hoạt động.
Ranh giới bảo mật
- GetMyBot chỉ gửi đến địa chỉ HTTPS công khai cổng 443. Loopback, mạng riêng, link-local, multicast và CGNAT bị từ chối; nếu tên miền có nhiều IP, tất cả phải công khai.
- DNS được kiểm tra lại mỗi lần giao; kết nối chỉ đến IP đã kiểm tra. Không theo chuyển hướng, giới hạn kích thước câu trả lời.
- Địa chỉ đăng ký trùng được nhận bằng dấu vân tay trong phạm vi tài khoản, nên bot này không thể biết một trình duyệt đã đăng ký bot khác hay chưa.
- Các endpoint trình duyệt nằm ngoài
/api, trong vùng tin cậy của widget: mỗi lần đều kiểm tra khóa widget đã ký, phiên widget và đúng origin trang, cùng dùng giới hạn yêu cầu của widget.
Dữ liệu và lưu giữ
Đăng ký trình duyệt và thông báo thuộc nhóm lưu giữ push, mặc định 180 ngày. Chúng tham gia hợp nhất người đăng ký, xuất và xóa dữ liệu cá nhân như dữ liệu khách khác.
Hỗ trợ trình duyệt và chẩn đoán
Cần đồng thời Notification, Service Worker và Push API. Chrome, Edge, Firefox hiện hành trên máy tính và Android hỗ trợ. Safari iOS chỉ hỗ trợ Web Push cho website khách đã thêm vào màn hình chính.
Nếu không nhận được thông báo:
- Mở
https://website-của-bạn/mybot-sw.jsvà kiểm tra tệp script, không phải404, chuyển hướng hoặc HTML. - Kiểm tra origin trang nằm trong danh sách widget được phép, URL thông báo nằm trong danh sách liên kết được phép.
- Xác nhận khách đã cấp quyền và không có worker khác đang kiểm soát trang.
- Sau xoay khóa, mọi khách phải đăng ký lại.
- Nếu không gửi thử được, kiểm tra đăng ký còn hoạt động và tài liệu Push đã xuất bản.
API và MCP
Các endpoint quản lý dùng PAT, xem REST API. Đọc cần scope web_push:read và quyền web_push.read của bot. Ghi cần web_push:write và web_push.write; bật còn cần integrations.secrets. MCP có bốn công cụ chỉ đọc, bao gồm danh sách đăng ký; xem MCP.
Bước tiếp theo
- Widget trên website: cài và kiểm tra widget.
- Studio nội dung: tài liệu Push để gửi.
- SDK khách hàng: cùng nội dung và chat trong ứng dụng di động.