آخر تحديث
التنبيهات
قواعد التنبيه التي تنطلق عند أحداث LIVE (webhook، والبريد الإلكتروني، وداخل التطبيق، وTelegram).
تُصادَق كل عملية بمفتاح API (Authorization: Bearer <key>) وتستخدم الأخطاء الغلاف المشترك الموضّح في الأخطاء. مولَّد من مستند OpenAPI الخاص بواجهة API.
عرض عمليات تسليم التنبيهات
/v1/alerts/deliveriesصف لكل قاعدة وقناة وحدث: delivered أو failed (مع detail وعدد attempts) أو capped (أسقطه حد الخطة، مثل الحد الشهري للـ webhook)، الأحدث أولًا.
معاملات الاستعلام
| 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"الاستجابة
{ "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.
عرض مرات إطلاق التنبيهات
/v1/alerts/firesكل مرة طابقت فيها قاعدةٌ حدثًا، الأحدث أولًا، سواء سلّمته قناة أم لا (قارنها بعمليات التسليم).
معاملات الاستعلام
| 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"الاستجابة
{ "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.
عرض قواعد التنبيه
/v1/alerts/rulesكل قواعد مساحة العمل مع قنواتها. لا تُرجَع أسرار التوقيع مرة أخرى أبدًا.
الطلب
curl "https://api.next.toktokdata.live/v1/alerts/rules" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"الاستجابة
{ "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.
إنشاء قاعدة تنبيه
/v1/alerts/rulesتراقب القاعدة صانع محتوى واحدًا (أو منطقة كاملة) بحثًا عن أنواع أحداث معينة وترسل إلى قنواتها. ويُرجَع سر التوقيع لقناة webhook مرة واحدة فقط، في webhookSecrets.
جسم الطلب
| Name | Type | Description |
|---|---|---|
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"}]}'الاستجابة
{ "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.
تحديث قاعدة تنبيه
/v1/alerts/rules/{rule_id}أرسل الحقول المراد تغييرها فقط؛ ويستبدل channels القائمة بأكملها.
معاملات المسار
| Name | Type | Description |
|---|---|---|
rule_idRequired | string | معرّف قاعدة التنبيه (UUID). |
جسم الطلب
| Name | Type | Description |
|---|---|---|
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}'الاستجابة
{ "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.
حذف قاعدة تنبيه
/v1/alerts/rules/{rule_id}يحذف القاعدة وقنواتها. لا يُرجع أي جسم.
معاملات المسار
| Name | Type | Description |
|---|---|---|
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.
إرسال إشعار تجريبي
/v1/alerts/rules/{rule_id}/testيسلّم الآن حدثًا تجريبيًا إلى كل قناة مفعّلة في القاعدة ويعيد نتيجة كل قناة في results (delivered أو failed أو capped مع detail). تُسجَّل مرات الإطلاق والتسليم التجريبية مع isTest: true.
معاملات المسار
| Name | Type | Description |
|---|---|---|
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"الاستجابة
{ "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 ساعة
/v1/alerts/statsالقواعد المفعّلة ومرات الإطلاق وعمليات التسليم حسب النتيجة خلال آخر 24 ساعة (دون الاختبارات).
الطلب
curl "https://api.next.toktokdata.live/v1/alerts/stats" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"الاستجابة
{ "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.