最後更新
提醒
在 LIVE 事件發生時觸發的提醒規則(Webhook、電子郵件、應用程式內、Telegram)。
所有操作都以 API 金鑰進行身分驗證 (Authorization: Bearer <key>) ;錯誤一律使用共通的錯誤格式,說明請見 錯誤. 本頁由 API 的 OpenAPI 文件產生。
列出警示傳送
GET
/v1/alerts/deliveries每個規則、管道與事件一列:delivered、failed(附 detail 與已嘗試次數 attempts)或 capped(方案上限如每月 webhook 上限將其捨棄),由新到舊。
權限範圍webhook:manage點數免費
查詢參數
| Name | Type | Description |
|---|---|---|
ruleIdOptional | string | 只看此規則(UUID)。 |
statusOptional | "delivered" | "failed" | "capped" | 只看此結果。 |
sinceOptional | string | ISO 8601 時間;只取較新的列。 |
limitOptional | integer | 回傳的列數。 範圍 1–200. Default: 50 |
請求
curl "https://api.next.toktokdata.live/v1/alerts/deliveries" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
200 OK
{ "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 }}錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
列出警示觸發
GET
/v1/alerts/fires每次規則符合事件的紀錄,由新到舊,不論管道是否已傳送(可與傳送紀錄比對)。
權限範圍webhook:manage點數免費
查詢參數
| Name | Type | Description |
|---|---|---|
ruleIdOptional | string | 只看此規則(UUID)。 |
sinceOptional | string | ISO 8601 時間;只取較新的列。 |
limitOptional | integer | 回傳的列數。 範圍 1–200. Default: 50 |
請求
curl "https://api.next.toktokdata.live/v1/alerts/fires" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
200 OK
{ "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 }}錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
列出提醒規則
GET
/v1/alerts/rules工作區的所有規則及其通道。簽章密鑰絕不會再次回傳。
權限範圍webhook:manage點數免費
請求
curl "https://api.next.toktokdata.live/v1/alerts/rules" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
200 OK
{ "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 }}錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
建立提醒規則
POST
/v1/alerts/rules規則會針對特定事件類型觀察一位創作者(或整個地區),並推送到其通道。Webhook 通道的簽章密鑰只會在 webhookSecrets 中回傳一次。
權限範圍webhook:manage點數免費
請求主體
| Name | Type | Description |
|---|---|---|
nameRequired | string | 顯示於通知中。 |
creatorUniqueIdOptional | string | null | 觀察單一創作者;省略則代表整個地區。 |
scopeOptional | "creator" | "any" | "watchlist" | "gifter_watchlist" | 規則監看的對象:指定的創作者、所有房間(可選擇單一地區)、工作區 watchlist 中的創作者,或 gifter watchlist(每個工作區一條規則)。有 creatorUniqueId 時預設為 creator,否則為 any。 |
regionOptional | string | null | |
eventTypesOptional | ("gift" | "envelope" | "goodyBag" | "live_start" | "live_end" | "host_quiet" | "league_change" | "diamond_target" | "follower_milestone" | "*")[] | LIVE 事件(gift、envelope、goodyBag、live_start、live_end),以及針對規則的創作者或 watchlist 每小時執行的主播檢查:host_quiet(3 天未開 LIVE)、league_change、diamond_target(某個榜單日達到 minDiamondCount)與 follower_milestone(超過 minFollowerMilestone 的倍數)。 |
minDiamondCountOptional | integer | null | 忽略鑽石值低於此數的事件。 |
minFollowerMilestoneOptional | integer | null | follower_milestone 的追蹤者級距(例如 10000)。 |
enabledOptional | boolean | Default: true |
channelsOptional | object[] |
請求
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"}]}'回應
201 Created
{ "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": []}錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
更新提醒規則
PATCH
/v1/alerts/rules/{rule_id}只需傳送要變更的欄位;channels 會取代整個清單。
權限範圍webhook:manage點數免費
路徑參數
| Name | Type | Description |
|---|---|---|
rule_idRequired | string | 提醒規則 ID(UUID)。 |
請求主體
| Name | Type | Description |
|---|---|---|
nameOptional | string | 顯示於通知中。 |
creatorUniqueIdOptional | string | null | 觀察單一創作者;省略則代表整個地區。 |
scopeOptional | "creator" | "any" | "watchlist" | "gifter_watchlist" | 規則監看的對象:指定的創作者、所有房間(可選擇單一地區)、工作區 watchlist 中的創作者,或 gifter watchlist(每個工作區一條規則)。有 creatorUniqueId 時預設為 creator,否則為 any。 |
regionOptional | string | null | |
eventTypesOptional | ("gift" | "envelope" | "goodyBag" | "live_start" | "live_end" | "host_quiet" | "league_change" | "diamond_target" | "follower_milestone" | "*")[] | LIVE 事件(gift、envelope、goodyBag、live_start、live_end),以及針對規則的創作者或 watchlist 每小時執行的主播檢查:host_quiet(3 天未開 LIVE)、league_change、diamond_target(某個榜單日達到 minDiamondCount)與 follower_milestone(超過 minFollowerMilestone 的倍數)。 |
minDiamondCountOptional | integer | null | 忽略鑽石值低於此數的事件。 |
minFollowerMilestoneOptional | integer | null | follower_milestone 的追蹤者級距(例如 10000)。 |
enabledOptional | boolean | Default: true |
channelsOptional | object[] |
請求
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}'回應
200 OK
{ "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 } ]}錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
刪除提醒規則
DELETE
/v1/alerts/rules/{rule_id}刪除規則及其通道。不回傳任何主體。
權限範圍webhook:manage點數免費
路徑參數
| Name | Type | Description |
|---|---|---|
rule_idRequired | string | 提醒規則 ID(UUID)。 |
請求
curl -X DELETE "https://api.next.toktokdata.live/v1/alerts/rules/7d01133d-6ecb-5101-a9c0-e23e4755bad9" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
204 回應,不含主體。
錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
傳送測試通知
POST
/v1/alerts/rules/{rule_id}/test立即向規則所有啟用的管道傳送一個範例事件,並在 results 中回傳每個管道的結果(delivered、failed 或 capped,附 detail)。測試觸發與傳送會以 isTest: true 記錄。
權限範圍webhook:manage點數免費
路徑參數
| Name | Type | Description |
|---|---|---|
rule_idRequired | string | 提醒規則 ID(UUID)。 |
請求
curl -X POST "https://api.next.toktokdata.live/v1/alerts/rules/7d01133d-6ecb-5101-a9c0-e23e4755bad9/test" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
200 OK
{ "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" } ]}錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
過去 24 小時的警示活動
GET
/v1/alerts/stats過去 24 小時的啟用規則數、觸發數與各結果的傳送數(不含測試)。
權限範圍webhook:manage點數免費
請求
curl "https://api.next.toktokdata.live/v1/alerts/stats" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
200 OK
{ "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" } }}錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
這個頁面對你有幫助嗎?