Cập nhật lần cuối
Cảnh báo
Luật cảnh báo kích hoạt theo sự kiện LIVE (webhook, email, trong app, Telegram).
Mọi thao tác đều xác thực bằng API key (Authorization: Bearer <key>) và lỗi dùng chung envelope được mô tả trong Lỗi. Được tạo từ tài liệu OpenAPI của API.
Liệt kê các lần giao cảnh báo
/v1/alerts/deliveriesMỗi quy tắc, kênh và sự kiện một dòng: delivered, failed (kèm detail và số attempts đã thử) hoặc capped (bị giới hạn của gói chặn, ví dụ giới hạn webhook mỗi tháng), mới nhất trước.
Tham số query
| Name | Type | Description |
|---|---|---|
ruleIdOptional | string | Chỉ quy tắc này (UUID). |
statusOptional | "delivered" | "failed" | "capped" | Chỉ kết quả này. |
sinceOptional | string | Thời điểm ISO 8601; chỉ các dòng mới hơn. |
limitOptional | integer | Số dòng trả về. Khoảng giá trị 1–200. Default: 50 |
Request
curl "https://api.next.toktokdata.live/v1/alerts/deliveries" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "items": [ { "id": "5a7e0b0c-2d55-5f11-8b0e-0d0a3c5e6f70", "source": "alert", "ruleId": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "ruleName": "Envelopes from Linh", "channelType": "webhook", "eventType": "envelope", "status": "failed", "attempts": 4, "detail": "retry exhausted: webhook HTTP 503", "isTest": false, "createdAt": "2026-11-06T09:58:13.410Z" }, { "id": "a3d9c6e1-4b2f-5c8e-9a71-2e5b8d0f4c13", "source": "alert", "ruleId": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "ruleName": "Envelopes from Linh", "channelType": "in_app", "eventType": "envelope", "status": "delivered", "attempts": 1, "detail": null, "isTest": false, "createdAt": "2026-11-06T09:58:12.512Z" } ], "observedAt": "2026-11-06T09:58:13.410Z", "provenance": { "observedAt": "2026-11-06T10:00:00.000Z", "freshness": "near_realtime", "source": "workspace_alert_history", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "alert-history-v1", "window": null }}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.
Liệt kê các lần cảnh báo khớp
/v1/alerts/firesMỗi lần một quy tắc khớp một sự kiện, mới nhất trước, dù kênh có giao được hay không (so sánh với các lần giao).
Tham số query
| Name | Type | Description |
|---|---|---|
ruleIdOptional | string | Chỉ quy tắc này (UUID). |
sinceOptional | string | Thời điểm ISO 8601; chỉ các dòng mới hơn. |
limitOptional | integer | Số dòng trả về. Khoảng giá trị 1–200. Default: 50 |
Request
curl "https://api.next.toktokdata.live/v1/alerts/fires" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "items": [ { "id": "1c3b5e86-0f43-5a3e-9d3c-5f6a1f0e7b21", "ruleId": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "ruleName": "Envelopes from Linh", "eventType": "envelope", "roomId": "7568123456789012345", "creatorUniqueId": "linh.live", "channelCount": 2, "isTest": false, "firedAt": "2026-11-06T09:58:12.104Z" } ], "observedAt": "2026-11-06T09:58:12.104Z", "provenance": { "observedAt": "2026-11-06T10:00:00.000Z", "freshness": "near_realtime", "source": "workspace_alert_history", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "alert-history-v1", "window": null }}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.
Liệt kê luật cảnh báo
/v1/alerts/rulesMọi luật của workspace cùng các kênh của chúng. Signing secret không bao giờ được trả về lần nữa.
Request
curl "https://api.next.toktokdata.live/v1/alerts/rules" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "rules": [ { "id": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "name": "Envelopes from Linh", "creatorUniqueId": "linh.live", "scope": "creator", "gifterKey": null, "region": null, "eventTypes": [ "envelope" ], "minScore": null, "minRate": null, "minDiamondCount": 100, "minFollowerMilestone": null, "goodyBagAllowAllViewers": null, "goodyBagMaxRequiredLevel": null, "enabled": true, "createdAt": "2026-11-01T10:51:45.582Z", "updatedAt": "2026-11-01T10:51:45.582Z", "channels": [ { "id": "3d0d4dc5-6993-55ab-a1cd-ffbe7db95507", "channelType": "in_app", "target": null, "enabled": true, "hasSigningSecret": false } ] } ], "provenance": { "observedAt": "2026-11-01T10:00:00.000Z", "freshness": "near_realtime", "source": "workspace_alert_rules", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "alert-rules-v1", "window": null }}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.
Tạo luật cảnh báo
/v1/alerts/rulesMột luật theo dõi một creator (hoặc cả một khu vực) cho các loại sự kiện và gửi tới các kênh của nó. Signing secret của kênh webhook chỉ được trả về một lần, trong webhookSecrets.
Body của request
| Name | Type | Description |
|---|---|---|
nameRequired | string | Hiển thị trong thông báo. |
creatorUniqueIdOptional | string | null | Theo dõi một creator; bỏ trống để theo dõi toàn khu vực. |
scopeOptional | "creator" | "any" | "watchlist" | "gifter_watchlist" | Quy tắc theo dõi gì: creator được chỉ định, mọi phòng (có thể giới hạn một khu vực), các creator trong watchlist của workspace, hoặc watchlist gifter (một quy tắc cho mỗi workspace). Mặc định là creator khi có creatorUniqueId, nếu không là any. |
regionOptional | string | null | |
eventTypesOptional | ("gift" | "envelope" | "goodyBag" | "live_start" | "live_end" | "host_quiet" | "league_change" | "diamond_target" | "follower_milestone" | "*")[] | Sự kiện LIVE (gift, envelope, goodyBag, live_start, live_end) và các kiểm tra host chạy mỗi giờ cho creator hoặc watchlist của quy tắc: host_quiet (không LIVE trong 3 ngày), league_change, diamond_target (một ngày bảng đạt minDiamondCount) và follower_milestone (vượt một bội số của minFollowerMilestone). |
minDiamondCountOptional | integer | null | Bỏ qua các sự kiện có giá trị ít kim cương hơn. |
minFollowerMilestoneOptional | integer | null | Bước người theo dõi cho follower_milestone (ví dụ 10000). |
enabledOptional | boolean | Default: true |
channelsOptional | object[] |
Request
curl -X POST "https://api.next.toktokdata.live/v1/alerts/rules" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Envelopes from Linh","creatorUniqueId":"linh.live","eventTypes":["envelope"],"minDiamondCount":100,"channels":[{"channelType":"webhook","target":"https://example.com/hooks/roomscope"}]}'Response
{ "rule": { "id": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "name": "Envelopes from Linh", "creatorUniqueId": "linh.live", "scope": "creator", "gifterKey": null, "region": null, "eventTypes": [ "envelope" ], "minScore": null, "minRate": null, "minDiamondCount": 100, "minFollowerMilestone": null, "goodyBagAllowAllViewers": null, "goodyBagMaxRequiredLevel": null, "enabled": true, "createdAt": "2026-11-01T10:51:45.582Z", "updatedAt": "2026-11-01T10:51:45.582Z", "channels": [ { "id": "3d0d4dc5-6993-55ab-a1cd-ffbe7db95507", "channelType": "in_app", "target": null, "enabled": true, "hasSigningSecret": false } ] }, "webhookSecrets": []}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.
Cập nhật luật cảnh báo
/v1/alerts/rules/{rule_id}Chỉ gửi các trường cần đổi; channels thay thế toàn bộ danh sách.
Tham số path
| Name | Type | Description |
|---|---|---|
rule_idRequired | string | Id của luật cảnh báo (UUID). |
Body của request
| Name | Type | Description |
|---|---|---|
nameOptional | string | Hiển thị trong thông báo. |
creatorUniqueIdOptional | string | null | Theo dõi một creator; bỏ trống để theo dõi toàn khu vực. |
scopeOptional | "creator" | "any" | "watchlist" | "gifter_watchlist" | Quy tắc theo dõi gì: creator được chỉ định, mọi phòng (có thể giới hạn một khu vực), các creator trong watchlist của workspace, hoặc watchlist gifter (một quy tắc cho mỗi workspace). Mặc định là creator khi có creatorUniqueId, nếu không là any. |
regionOptional | string | null | |
eventTypesOptional | ("gift" | "envelope" | "goodyBag" | "live_start" | "live_end" | "host_quiet" | "league_change" | "diamond_target" | "follower_milestone" | "*")[] | Sự kiện LIVE (gift, envelope, goodyBag, live_start, live_end) và các kiểm tra host chạy mỗi giờ cho creator hoặc watchlist của quy tắc: host_quiet (không LIVE trong 3 ngày), league_change, diamond_target (một ngày bảng đạt minDiamondCount) và follower_milestone (vượt một bội số của minFollowerMilestone). |
minDiamondCountOptional | integer | null | Bỏ qua các sự kiện có giá trị ít kim cương hơn. |
minFollowerMilestoneOptional | integer | null | Bước người theo dõi cho follower_milestone (ví dụ 10000). |
enabledOptional | boolean | Default: true |
channelsOptional | object[] |
Request
curl -X PATCH "https://api.next.toktokdata.live/v1/alerts/rules/7d01133d-6ecb-5101-a9c0-e23e4755bad9" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled":false}'Response
{ "id": "7d01133d-6ecb-5101-a9c0-e23e4755bad9", "name": "Envelopes from Linh", "creatorUniqueId": "linh.live", "scope": "creator", "gifterKey": null, "region": null, "eventTypes": [ "envelope" ], "minScore": null, "minRate": null, "minDiamondCount": 100, "minFollowerMilestone": null, "goodyBagAllowAllViewers": null, "goodyBagMaxRequiredLevel": null, "enabled": true, "createdAt": "2026-11-01T10:51:45.582Z", "updatedAt": "2026-11-01T10:51:45.582Z", "channels": [ { "id": "3d0d4dc5-6993-55ab-a1cd-ffbe7db95507", "channelType": "in_app", "target": null, "enabled": true, "hasSigningSecret": false } ]}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.
Xóa luật cảnh báo
/v1/alerts/rules/{rule_id}Xóa luật và các kênh của nó. Không trả về body.
Tham số path
| Name | Type | Description |
|---|---|---|
rule_idRequired | string | Id của luật cảnh báo (UUID). |
Request
curl -X DELETE "https://api.next.toktokdata.live/v1/alerts/rules/7d01133d-6ecb-5101-a9c0-e23e4755bad9" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
204 không có body.
Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.
Gửi thông báo thử
/v1/alerts/rules/{rule_id}/testGửi ngay một sự kiện mẫu tới mọi kênh đang bật của quy tắc và trả về kết quả từng kênh trong results (delivered, failed hoặc capped, kèm detail). Các lần khớp và lần giao thử được ghi với isTest: true.
Tham số path
| Name | Type | Description |
|---|---|---|
rule_idRequired | string | Id của luật cảnh báo (UUID). |
Request
curl -X POST "https://api.next.toktokdata.live/v1/alerts/rules/7d01133d-6ecb-5101-a9c0-e23e4755bad9/test" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "enqueued": 2, "results": [ { "channelId": "3d0d4dc5-6993-55ab-a1cd-ffbe7db95507", "channelType": "in_app", "status": "delivered", "detail": null }, { "channelId": "9e1f2a3b-4c5d-5e6f-8a7b-0c1d2e3f4a5b", "channelType": "discord", "status": "failed", "detail": "discord HTTP 404" } ]}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.
Hoạt động cảnh báo trong 24 giờ qua
/v1/alerts/statsSố quy tắc đang bật, số lần khớp và số lần giao theo kết quả trong 24 giờ qua (không tính lần thử).
Request
curl "https://api.next.toktokdata.live/v1/alerts/stats" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "rulesActive": 3, "fired24h": 41, "delivered24h": 78, "failed24h": 2, "capped24h": 0, "provenance": { "observedAt": "2026-11-06T10:00:00.000Z", "freshness": "near_realtime", "source": "workspace_alert_history", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "alert-history-v1", "window": { "from": "2026-11-05T10:00:00.000Z", "to": "2026-11-06T10:00:00.000Z", "label": "24h" } }}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.