RoomScope

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

GET/v1/alerts/deliveries

Mỗ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.

Scopewebhook:manageCreditMiễn phí

Tham số query

Tham số query · GET /v1/alerts/deliveries
NameTypeDescription
ruleIdOptional
stringChỉ quy tắc này (UUID).
statusOptional
"delivered" | "failed" | "capped"Chỉ kết quả này.
sinceOptional
stringThời điểm ISO 8601; chỉ các dòng mới hơn.
limitOptional
integerSố 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

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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Liệt kê các lần cảnh báo khớp

GET/v1/alerts/fires

Mỗ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).

Scopewebhook:manageCreditMiễn phí

Tham số query

Tham số query · GET /v1/alerts/fires
NameTypeDescription
ruleIdOptional
stringChỉ quy tắc này (UUID).
sinceOptional
stringThời điểm ISO 8601; chỉ các dòng mới hơn.
limitOptional
integerSố 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

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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Liệt kê luật cảnh báo

GET/v1/alerts/rules

Mọ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.

Scopewebhook:manageCreditMiễn phí

Request

curl "https://api.next.toktokdata.live/v1/alerts/rules" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Tạo luật cảnh báo

POST/v1/alerts/rules

Mộ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.

Scopewebhook:manageCreditMiễn phí

Body của request

Body của request · POST /v1/alerts/rules
NameTypeDescription
nameRequired
stringHiển thị trong thông báo.
creatorUniqueIdOptional
string | nullTheo 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 | nullBỏ qua các sự kiện có giá trị ít kim cương hơn.
minFollowerMilestoneOptional
integer | nullBướ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

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": []}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Cập nhật luật cảnh báo

PATCH/v1/alerts/rules/{rule_id}

Chỉ gửi các trường cần đổi; channels thay thế toàn bộ danh sách.

Scopewebhook:manageCreditMiễn phí

Tham số path

Tham số path · PATCH /v1/alerts/rules/{rule_id}
NameTypeDescription
rule_idRequired
stringId của luật cảnh báo (UUID).

Body của request

Body của request · PATCH /v1/alerts/rules/{rule_id}
NameTypeDescription
nameOptional
stringHiển thị trong thông báo.
creatorUniqueIdOptional
string | nullTheo 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 | nullBỏ qua các sự kiện có giá trị ít kim cương hơn.
minFollowerMilestoneOptional
integer | nullBướ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

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    }  ]}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Xóa luật cảnh báo

DELETE/v1/alerts/rules/{rule_id}

Xóa luật và các kênh của nó. Không trả về body.

Scopewebhook:manageCreditMiễn phí

Tham số path

Tham số path · DELETE /v1/alerts/rules/{rule_id}
NameTypeDescription
rule_idRequired
stringId 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

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Gửi thông báo thử

POST/v1/alerts/rules/{rule_id}/test

Gử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.

Scopewebhook:manageCreditMiễn phí

Tham số path

Tham số path · POST /v1/alerts/rules/{rule_id}/test
NameTypeDescription
rule_idRequired
stringId 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

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"    }  ]}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Hoạt động cảnh báo trong 24 giờ qua

GET/v1/alerts/stats

Số 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ử).

Scopewebhook:manageCreditMiễn phí

Request

curl "https://api.next.toktokdata.live/v1/alerts/stats" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

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"    }  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.
Trang này có hữu ích không?