RoomScope

آخر تحديث

التنبيهات

قواعد التنبيه التي تنطلق عند أحداث LIVE (webhook، والبريد الإلكتروني، وداخل التطبيق، وTelegram).

تُصادَق كل عملية بمفتاح API (Authorization: Bearer <key>) وتستخدم الأخطاء الغلاف المشترك الموضّح في الأخطاء. مولَّد من مستند OpenAPI الخاص بواجهة API.

عرض عمليات تسليم التنبيهات

GET/v1/alerts/deliveries

صف لكل قاعدة وقناة وحدث: delivered أو failed (مع detail وعدد attempts) أو capped (أسقطه حد الخطة، مثل الحد الشهري للـ webhook)، الأحدث أولًا.

النطاقwebhook:manageوحدات الرصيدمجاني

معاملات الاستعلام

معاملات الاستعلام · GET /v1/alerts/deliveries
NameTypeDescription
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 المشكلة.
  • 401 مفتاح API مفقود أو غير معروف.
  • 403 المفتاح يفتقر إلى النطاق، أو أن الباقة لا تتضمن الميزة.
  • 429 تم تجاوز معدل الطلبات (في الثانية أو الدقيقة أو اليوم)؛ التزم بقيمة Retry-After.

عرض مرات إطلاق التنبيهات

GET/v1/alerts/fires

كل مرة طابقت فيها قاعدةٌ حدثًا، الأحدث أولًا، سواء سلّمته قناة أم لا (قارنها بعمليات التسليم).

النطاقwebhook:manageوحدات الرصيدمجاني

معاملات الاستعلام

معاملات الاستعلام · GET /v1/alerts/fires
NameTypeDescription
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 المشكلة.
  • 401 مفتاح API مفقود أو غير معروف.
  • 403 المفتاح يفتقر إلى النطاق، أو أن الباقة لا تتضمن الميزة.
  • 429 تم تجاوز معدل الطلبات (في الثانية أو الدقيقة أو اليوم)؛ التزم بقيمة Retry-After.

عرض قواعد التنبيه

GET/v1/alerts/rules

كل قواعد مساحة العمل مع قنواتها. لا تُرجَع أسرار التوقيع مرة أخرى أبدًا.

النطاق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 المشكلة.
  • 401 مفتاح API مفقود أو غير معروف.
  • 403 المفتاح يفتقر إلى النطاق، أو أن الباقة لا تتضمن الميزة.
  • 429 تم تجاوز معدل الطلبات (في الثانية أو الدقيقة أو اليوم)؛ التزم بقيمة Retry-After.

إنشاء قاعدة تنبيه

POST/v1/alerts/rules

تراقب القاعدة صانع محتوى واحدًا (أو منطقة كاملة) بحثًا عن أنواع أحداث معينة وترسل إلى قنواتها. ويُرجَع سر التوقيع لقناة webhook مرة واحدة فقط، في webhookSecrets.

النطاقwebhook:manageوحدات الرصيدمجاني

جسم الطلب

جسم الطلب · POST /v1/alerts/rules
NameTypeDescription
nameRequired
stringيظهر في الإشعارات.
creatorUniqueIdOptional
string | nullمراقبة صانع محتوى واحد؛ احذفه لمراقبة المنطقة بأكملها.
scopeOptional
"creator" | "any" | "watchlist" | "gifter_watchlist"ما تراقبه القاعدة: صانع المحتوى المحدد، أو كل الغرف (اختياريًا منطقة واحدة)، أو صناع المحتوى في قائمة متابعة مساحة العمل، أو قائمة متابعة الداعمين (قاعدة واحدة لكل مساحة عمل). الافتراضي creator عند تعيين creatorUniqueId، وإلا 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) وفحوص المضيف التي تعمل كل ساعة لصانع محتوى القاعدة أو قائمة متابعتها: host_quiet (لا LIVE منذ 3 أيام) و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 المشكلة.
  • 401 مفتاح API مفقود أو غير معروف.
  • 403 المفتاح يفتقر إلى النطاق، أو أن الباقة لا تتضمن الميزة.
  • 429 تم تجاوز معدل الطلبات (في الثانية أو الدقيقة أو اليوم)؛ التزم بقيمة Retry-After.

تحديث قاعدة تنبيه

PATCH/v1/alerts/rules/{rule_id}

أرسل الحقول المراد تغييرها فقط؛ ويستبدل channels القائمة بأكملها.

النطاقwebhook:manageوحدات الرصيدمجاني

معاملات المسار

معاملات المسار · PATCH /v1/alerts/rules/{rule_id}
NameTypeDescription
rule_idRequired
stringمعرّف قاعدة التنبيه (UUID).

جسم الطلب

جسم الطلب · PATCH /v1/alerts/rules/{rule_id}
NameTypeDescription
nameOptional
stringيظهر في الإشعارات.
creatorUniqueIdOptional
string | nullمراقبة صانع محتوى واحد؛ احذفه لمراقبة المنطقة بأكملها.
scopeOptional
"creator" | "any" | "watchlist" | "gifter_watchlist"ما تراقبه القاعدة: صانع المحتوى المحدد، أو كل الغرف (اختياريًا منطقة واحدة)، أو صناع المحتوى في قائمة متابعة مساحة العمل، أو قائمة متابعة الداعمين (قاعدة واحدة لكل مساحة عمل). الافتراضي creator عند تعيين creatorUniqueId، وإلا 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) وفحوص المضيف التي تعمل كل ساعة لصانع محتوى القاعدة أو قائمة متابعتها: host_quiet (لا LIVE منذ 3 أيام) و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 المشكلة.
  • 401 مفتاح API مفقود أو غير معروف.
  • 403 المفتاح يفتقر إلى النطاق، أو أن الباقة لا تتضمن الميزة.
  • 429 تم تجاوز معدل الطلبات (في الثانية أو الدقيقة أو اليوم)؛ التزم بقيمة Retry-After.

حذف قاعدة تنبيه

DELETE/v1/alerts/rules/{rule_id}

يحذف القاعدة وقنواتها. لا يُرجع أي جسم.

النطاقwebhook:manageوحدات الرصيدمجاني

معاملات المسار

معاملات المسار · DELETE /v1/alerts/rules/{rule_id}
NameTypeDescription
rule_idRequired
stringمعرّف قاعدة التنبيه (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 المشكلة.
  • 401 مفتاح API مفقود أو غير معروف.
  • 403 المفتاح يفتقر إلى النطاق، أو أن الباقة لا تتضمن الميزة.
  • 429 تم تجاوز معدل الطلبات (في الثانية أو الدقيقة أو اليوم)؛ التزم بقيمة Retry-After.

إرسال إشعار تجريبي

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

يسلّم الآن حدثًا تجريبيًا إلى كل قناة مفعّلة في القاعدة ويعيد نتيجة كل قناة في results (delivered أو failed أو capped مع detail). تُسجَّل مرات الإطلاق والتسليم التجريبية مع isTest: true.

النطاقwebhook:manageوحدات الرصيدمجاني

معاملات المسار

معاملات المسار · POST /v1/alerts/rules/{rule_id}/test
NameTypeDescription
rule_idRequired
stringمعرّف قاعدة التنبيه (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 المشكلة.
  • 401 مفتاح API مفقود أو غير معروف.
  • 403 المفتاح يفتقر إلى النطاق، أو أن الباقة لا تتضمن الميزة.
  • 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 المشكلة.
  • 401 مفتاح API مفقود أو غير معروف.
  • 403 المفتاح يفتقر إلى النطاق، أو أن الباقة لا تتضمن الميزة.
  • 429 تم تجاوز معدل الطلبات (في الثانية أو الدقيقة أو اليوم)؛ التزم بقيمة Retry-After.
هل كانت هذه الصفحة مفيدة؟