RoomScope

최종 업데이트

알림

LIVE 이벤트에 반응하는 알림 규칙(webhook, 이메일, 앱 내 알림, Telegram).

모든 작업은 API key로 인증하며 (Authorization: Bearer <key>) 오류 응답은 다음 문서에서 설명하는 공통 오류 형식을 따릅니다: 오류. 이 페이지는 API의 OpenAPI 문서에서 생성되었습니다.

알림 규칙 목록 조회

GET/v1/alerts/rules

워크스페이스의 모든 규칙과 채널. 서명 secret은 다시 반환되지 않습니다.

스코프webhook:manage크레딧무료

요청

curl "https://api.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",      "region": null,      "eventTypes": [        "envelope"      ],      "minScore": null,      "minRate": null,      "minDiamondCount": 100,      "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에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다. Retry-After를 따르세요.

알림 규칙 만들기

POST/v1/alerts/rules

규칙은 크리에이터 한 명(또는 지역 전체)의 지정된 이벤트 유형을 지켜보고 채널로 전송합니다. webhook 채널의 서명 secret은 webhookSecrets에 한 번만 반환됩니다.

스코프webhook:manage크레딧무료

요청 본문

요청 본문 · POST /v1/alerts/rules
NameTypeDescription
nameRequired
string알림에 표시됩니다.
creatorUniqueIdOptional
string | null크리에이터 한 명을 지켜봅니다. 생략하면 지역 전체를 대상으로 합니다.
regionOptional
string | null
eventTypesOptional
("gift" | "envelope" | "goodyBag" | "*")[]
minDiamondCountOptional
integer | null다이아몬드 값이 이보다 작은 이벤트는 무시합니다.
enabledOptional
boolean
Default: true
channelsOptional
object[]

요청

curl -X POST "https://api.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",    "region": null,    "eventTypes": [      "envelope"    ],    "minScore": null,    "minRate": null,    "minDiamondCount": 100,    "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에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다. Retry-After를 따르세요.

알림 규칙 수정

PATCH/v1/alerts/rules/{rule_id}

변경할 필드만 보내세요. channels는 전체 목록을 대체합니다.

스코프webhook:manage크레딧무료

경로 파라미터

경로 파라미터 · PATCH /v1/alerts/rules/{rule_id}
NameTypeDescription
rule_idRequired
string알림 규칙 ID(UUID).

요청 본문

요청 본문 · PATCH /v1/alerts/rules/{rule_id}
NameTypeDescription
nameOptional
string알림에 표시됩니다.
creatorUniqueIdOptional
string | null크리에이터 한 명을 지켜봅니다. 생략하면 지역 전체를 대상으로 합니다.
regionOptional
string | null
eventTypesOptional
("gift" | "envelope" | "goodyBag" | "*")[]
minDiamondCountOptional
integer | null다이아몬드 값이 이보다 작은 이벤트는 무시합니다.
enabledOptional
boolean
Default: true
channelsOptional
object[]

요청

curl -X PATCH "https://api.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",  "region": null,  "eventTypes": [    "envelope"  ],  "minScore": null,  "minRate": null,  "minDiamondCount": 100,  "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에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다. Retry-After를 따르세요.

알림 규칙 삭제

DELETE/v1/alerts/rules/{rule_id}

규칙과 채널을 삭제합니다. 본문을 반환하지 않습니다.

스코프webhook:manage크레딧무료

경로 파라미터

경로 파라미터 · DELETE /v1/alerts/rules/{rule_id}
NameTypeDescription
rule_idRequired
string알림 규칙 ID(UUID).

요청

curl -X DELETE "https://api.toktokdata.live/v1/alerts/rules/7d01133d-6ecb-5101-a9c0-e23e4755bad9" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

응답

204 응답을 반환하며 본문은 없습니다.

오류

  • 400 파라미터 또는 본문이 잘못되었습니다. code에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다. Retry-After를 따르세요.

테스트 알림 보내기

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

규칙의 활성화된 모든 채널로 가상 이벤트를 전송합니다.

스코프webhook:manage크레딧무료

경로 파라미터

경로 파라미터 · POST /v1/alerts/rules/{rule_id}/test
NameTypeDescription
rule_idRequired
string알림 규칙 ID(UUID).

요청

curl -X POST "https://api.toktokdata.live/v1/alerts/rules/7d01133d-6ecb-5101-a9c0-e23e4755bad9/test" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

응답

200 OK
{  "enqueued": 1}

오류

  • 400 파라미터 또는 본문이 잘못되었습니다. code에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다. Retry-After를 따르세요.
이 페이지가 도움이 되었나요?