RoomScope

Última actualización

Alertas

Reglas de alerta que se activan con eventos de LIVE (webhook, correo, dentro de la app, Telegram).

Cada operación se autentica con una clave de API (Authorization: Bearer <key>) y los errores usan el sobre compartido que se describe en Errores. Generado a partir del documento OpenAPI de la API.

Listar entregas de alertas

GET/v1/alerts/deliveries

Una fila por regla, canal y evento: delivered, failed (con detail y los attempts realizados) o capped (un límite del plan, como el límite mensual de webhooks, la descartó), las más recientes primero.

Alcancewebhook:manageCréditosGratis

Parámetros de consulta

Parámetros de consulta · GET /v1/alerts/deliveries
NameTypeDescription
ruleIdOptional
stringSolo esta regla (UUID).
statusOptional
"delivered" | "failed" | "capped"Solo este resultado.
sinceOptional
stringHora ISO 8601; solo filas más nuevas.
limitOptional
integerFilas que devolver. Rango 1–200.
Default: 50

Solicitud

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

Respuesta

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

Errores

  • 400 Parámetro o cuerpo no válido; code indica el problema.
  • 401 Clave de API ausente o desconocida.
  • 403 La clave no tiene el alcance, o el plan no incluye la función.
  • 429 Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respeta Retry-After.

Listar disparos de alertas

GET/v1/alerts/fires

Cada vez que una regla coincidió con un evento, los más recientes primero, lo haya entregado o no un canal (compáralo con las entregas).

Alcancewebhook:manageCréditosGratis

Parámetros de consulta

Parámetros de consulta · GET /v1/alerts/fires
NameTypeDescription
ruleIdOptional
stringSolo esta regla (UUID).
sinceOptional
stringHora ISO 8601; solo filas más nuevas.
limitOptional
integerFilas que devolver. Rango 1–200.
Default: 50

Solicitud

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

Respuesta

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

Errores

  • 400 Parámetro o cuerpo no válido; code indica el problema.
  • 401 Clave de API ausente o desconocida.
  • 403 La clave no tiene el alcance, o el plan no incluye la función.
  • 429 Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respeta Retry-After.

Listar reglas de alerta

GET/v1/alerts/rules

Todas las reglas del espacio de trabajo con sus canales. Los secretos de firma nunca se vuelven a devolver.

Alcancewebhook:manageCréditosGratis

Solicitud

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

Respuesta

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

Errores

  • 400 Parámetro o cuerpo no válido; code indica el problema.
  • 401 Clave de API ausente o desconocida.
  • 403 La clave no tiene el alcance, o el plan no incluye la función.
  • 429 Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respeta Retry-After.

Crear una regla de alerta

POST/v1/alerts/rules

Una regla monitorea a un creador (o a toda una región) para ciertos tipos de evento y entrega a sus canales. El secreto de firma de un canal de webhook se devuelve una sola vez, en webhookSecrets.

Alcancewebhook:manageCréditosGratis

Cuerpo de la solicitud

Cuerpo de la solicitud · POST /v1/alerts/rules
NameTypeDescription
nameRequired
stringSe muestra en las notificaciones.
creatorUniqueIdOptional
string | nullMonitorea a un creador; omítelo para toda la región.
scopeOptional
"creator" | "any" | "watchlist" | "gifter_watchlist"Qué vigila la regla: el creador fijado, todas las salas (opcionalmente una región), los creadores de la watchlist del workspace o la watchlist de gifters (una regla por workspace). Por defecto es creator cuando hay creatorUniqueId; si no, any.
regionOptional
string | null
eventTypesOptional
("gift" | "envelope" | "goodyBag" | "live_start" | "live_end" | "host_quiet" | "league_change" | "diamond_target" | "follower_milestone" | "*")[]Eventos LIVE (gift, envelope, goodyBag, live_start, live_end) y comprobaciones de host cada hora para el creador o la watchlist de la regla: host_quiet (sin LIVE durante 3 días), league_change, diamond_target (un día del ranking alcanzó minDiamondCount) y follower_milestone (superó un múltiplo de minFollowerMilestone).
minDiamondCountOptional
integer | nullIgnora los eventos que valen menos diamantes.
minFollowerMilestoneOptional
integer | nullPaso de seguidores para follower_milestone (p. ej. 10000).
enabledOptional
boolean
Default: true
channelsOptional
object[]

Solicitud

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

Respuesta

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

Errores

  • 400 Parámetro o cuerpo no válido; code indica el problema.
  • 401 Clave de API ausente o desconocida.
  • 403 La clave no tiene el alcance, o el plan no incluye la función.
  • 429 Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respeta Retry-After.

Actualizar una regla de alerta

PATCH/v1/alerts/rules/{rule_id}

Envía solo los campos que quieres cambiar; channels reemplaza la lista completa.

Alcancewebhook:manageCréditosGratis

Parámetros de ruta

Parámetros de ruta · PATCH /v1/alerts/rules/{rule_id}
NameTypeDescription
rule_idRequired
stringID de la regla de alerta (UUID).

Cuerpo de la solicitud

Cuerpo de la solicitud · PATCH /v1/alerts/rules/{rule_id}
NameTypeDescription
nameOptional
stringSe muestra en las notificaciones.
creatorUniqueIdOptional
string | nullMonitorea a un creador; omítelo para toda la región.
scopeOptional
"creator" | "any" | "watchlist" | "gifter_watchlist"Qué vigila la regla: el creador fijado, todas las salas (opcionalmente una región), los creadores de la watchlist del workspace o la watchlist de gifters (una regla por workspace). Por defecto es creator cuando hay creatorUniqueId; si no, any.
regionOptional
string | null
eventTypesOptional
("gift" | "envelope" | "goodyBag" | "live_start" | "live_end" | "host_quiet" | "league_change" | "diamond_target" | "follower_milestone" | "*")[]Eventos LIVE (gift, envelope, goodyBag, live_start, live_end) y comprobaciones de host cada hora para el creador o la watchlist de la regla: host_quiet (sin LIVE durante 3 días), league_change, diamond_target (un día del ranking alcanzó minDiamondCount) y follower_milestone (superó un múltiplo de minFollowerMilestone).
minDiamondCountOptional
integer | nullIgnora los eventos que valen menos diamantes.
minFollowerMilestoneOptional
integer | nullPaso de seguidores para follower_milestone (p. ej. 10000).
enabledOptional
boolean
Default: true
channelsOptional
object[]

Solicitud

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

Respuesta

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

Errores

  • 400 Parámetro o cuerpo no válido; code indica el problema.
  • 401 Clave de API ausente o desconocida.
  • 403 La clave no tiene el alcance, o el plan no incluye la función.
  • 429 Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respeta Retry-After.

Eliminar una regla de alerta

DELETE/v1/alerts/rules/{rule_id}

Elimina la regla y sus canales. No devuelve cuerpo.

Alcancewebhook:manageCréditosGratis

Parámetros de ruta

Parámetros de ruta · DELETE /v1/alerts/rules/{rule_id}
NameTypeDescription
rule_idRequired
stringID de la regla de alerta (UUID).

Solicitud

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

Respuesta

204 sin cuerpo.

Errores

  • 400 Parámetro o cuerpo no válido; code indica el problema.
  • 401 Clave de API ausente o desconocida.
  • 403 La clave no tiene el alcance, o el plan no incluye la función.
  • 429 Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respeta Retry-After.

Enviar una notificación de prueba

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

Entrega ahora un evento de prueba a cada canal activo de la regla y devuelve cómo fue cada uno en results (delivered, failed o capped, con detail). Los disparos y entregas de prueba se registran con isTest: true.

Alcancewebhook:manageCréditosGratis

Parámetros de ruta

Parámetros de ruta · POST /v1/alerts/rules/{rule_id}/test
NameTypeDescription
rule_idRequired
stringID de la regla de alerta (UUID).

Solicitud

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

Respuesta

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

Errores

  • 400 Parámetro o cuerpo no válido; code indica el problema.
  • 401 Clave de API ausente o desconocida.
  • 403 La clave no tiene el alcance, o el plan no incluye la función.
  • 429 Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respeta Retry-After.

Actividad de alertas en las últimas 24 horas

GET/v1/alerts/stats

Reglas activas, disparos y entregas por resultado en las últimas 24 horas (sin pruebas).

Alcancewebhook:manageCréditosGratis

Solicitud

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

Respuesta

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

Errores

  • 400 Parámetro o cuerpo no válido; code indica el problema.
  • 401 Clave de API ausente o desconocida.
  • 403 La clave no tiene el alcance, o el plan no incluye la función.
  • 429 Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respeta Retry-After.
¿Te resultó útil esta página?