최종 업데이트
알림
LIVE 이벤트에 반응하는 알림 규칙(webhook, 이메일, 앱 내 알림, Telegram).
모든 작업은 API key로 인증하며 (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 key가 없거나 알 수 없는 key입니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.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 key가 없거나 알 수 없는 key입니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.429요청 속도를 초과했습니다(초당, 분당 또는 일일).Retry-After를 따르세요.
알림 규칙 목록 조회
GET
/v1/alerts/rules워크스페이스의 모든 규칙과 채널. 서명 secret은 다시 반환되지 않습니다.
스코프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 key가 없거나 알 수 없는 key입니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.429요청 속도를 초과했습니다(초당, 분당 또는 일일).Retry-After를 따르세요.
알림 규칙 만들기
POST
/v1/alerts/rules규칙은 크리에이터 한 명(또는 지역 전체)의 지정된 이벤트 유형을 지켜보고 채널로 전송합니다. webhook 채널의 서명 secret은 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 key가 없거나 알 수 없는 key입니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.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 key가 없거나 알 수 없는 key입니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.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 key가 없거나 알 수 없는 key입니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.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 key가 없거나 알 수 없는 key입니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.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 key가 없거나 알 수 없는 key입니다.403key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.429요청 속도를 초과했습니다(초당, 분당 또는 일일).Retry-After를 따르세요.
이 페이지가 도움이 되었나요?