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

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; 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.
regionOptional
string | null
eventTypesOptional
("gift" | "envelope" | "goodyBag" | "*")[]
minDiamondCountOptional
integer | nullIgnora los eventos que valen menos diamantes.
enabledOptional
boolean
Default: true
channelsOptional
object[]

Solicitud

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

Respuesta

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

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; 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.
regionOptional
string | null
eventTypesOptional
("gift" | "envelope" | "goodyBag" | "*")[]
minDiamondCountOptional
integer | nullIgnora los eventos que valen menos diamantes.
enabledOptional
boolean
Default: true
channelsOptional
object[]

Solicitud

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

Respuesta

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

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; 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.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; respeta Retry-After.

Enviar una notificación de prueba

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

Entrega un evento sintético a cada canal habilitado de la regla.

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.toktokdata.live/v1/alerts/rules/7d01133d-6ecb-5101-a9c0-e23e4755bad9/test" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Respuesta

200 OK
{  "enqueued": 1}

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; respeta Retry-After.
¿Te resultó útil esta página?