تخطَّ إلى المحتوى
Documentation

APIمرجع خادم RTC

عنوان URL الأساسي: https://api.rtc.champrep.com

تغطي هذه المرجع مسارات التكامل المدعومة بمفاتيحAPI مشاريع RTC. عمليات تسجيل الدخول إلى وحدة التحكم، وإعداد المؤسسة، وإدارة المفاتيح، وإدارة النظام الأساسي ليست مسارات تكامل باستخدام مفتاح الخادم. قم بإدارتها من خلال واجهة المستخدم المناسبة بدلاً من نسخ رموز جلسة المتصفح إلى البرامج النصية.

إرسال Authorization: Bearer YOUR_RTC_API_KEY وبالنسبة لنصوص JSON، Content-Type: application/json. تستخدم الأمثلة عناصر نائبة، ولا تستخدم أبدًا بيانات اعتماد صالحة. تظل المفاتيح مقيدة بمشروعها ووصول الخطة الحالية.

قواعد الطلب والاستجابة

Section titled “قواعد الطلب والاستجابة”
  • المعرفات هي سلاسل UUID. استخدم المعرفات التي ترجعها RTC، وليس أسماء العرض.
  • يتم اقتطاع الأسماء ولا يُسمح إلا بما بين 1 و80 حرفًا.
  • يقتصر حجم نصوص JSON على 64 كيلوبايت وترفض الحقول غير المعروفة.
  • تُرجع نقاط نهاية القوائم مصفوفات JSON، الأحدث أولاً. ?limit (1-200) يحدد حجم الصفحة؛ وعند وجود المزيد من العناصر، فإن X-Next-Cursor يحتوي رأس الاستجابة على المؤشر الذي سيتم إرجاعه كـ ?cursor.
  • لا تعتمد على حقول الاستجابة غير الموثقة أو قم بإنشاء عناوين URL للوسائط/التخزين.
  • لا توفر عمليات التغيير عقدًا عامًا لمفتاح الإيدمبوتنس. قم بمطابقة النتائج قبل إعادة المحاولة بعد انتهاء المهلة أو انقطاع الاتصال.

الطريقة والمسارالنطاق المطلوبالنتيجة
GET /v1/projectsأي مفتاح مشروع صالحمصفوفة مُفلترة حسب المشروع
GET /v1/roomsrooms:readمصفوفة الغرف
POST /v1/roomsrooms:write201، غرفة تم إنشاؤها
POST /v1/rooms/{roomId}/endrooms:write{ "ended": true }
POST /v1/rooms/{roomId}/tokenstokens:writeمجموعة بيانات اعتماد المشاركين
GET /v1/recordingsrecordings:readمصفوفة التسجيل
POST /v1/recordingsrecordings:write202، التسجيل في قائمة الانتظار
POST /v1/recordings/{recordingId}/stoprecordings:write{ "stopping": true }
POST /v1/recordings/{recordingId}/tracks/{trackId}/downloadrecordings:readرابط التنزيل المؤقت
POST /v1/recordings/{recordingId}/transcriptrecordings:write202، يُطلب النص (نسخ)
GET /v1/recordings/{recordingId}/transcriptrecordings:readالنص في صيغة JSON، أو ملف يحتوي على ?format=vtt, srt أو txt
GET /v1/transcriptsrecordings:readنصوصك وحالتها، بدون نص
GET /v1/usageأي مفتاح مشروع صالحالاستخدام المكتمل والحدود المسموح بها
GET /v1/webhooks/endpoints, GET /v1/webhooks/deliverieswebhooks:readنقاط النهاية وسجل التسليم (webhooks)
POST, PATCH /v1/webhooks/endpoints…، وإعادة التشغيل والاختباراتwebhooks:writeإدارة نقاط النهاية (webhooks)
POST /v1/joinلا شيء (رمز انضمام)مجموعة بيانات اعتماد المشارك (رموز الانضمام)
GET /v1/error-codesلا شيءالـ كتالوج رموز الأخطاء

تستخدم الردود الناجحة 200 ما لم يُذكر خلاف ذلك. كلا مساري القراءة اللتين لا يحتويان على نطاق مسمى لا يزالان يتطلبان مفتاح مشروع صالحًا لم تنته صلاحيته ووصولًا إلى الخدمة.

GET /v1/projects تُرجع فقط المشروع المرتبط بالمفتاح. يتم إنشاء المشروع في وحدة التحكم.

بالنسبة لـ POST /v1/rooms، أرسل:

{
"projectId": "00000000-0000-4000-8000-000000000001",
"name": "Customer conversation",
"maxParticipants": 4
}

projectId و name مطلوبة. maxParticipants هو اختياري، والقيمة الافتراضية هي 8، ويجب أن يكون عددًا صحيحًا لا يقل عن 2 ضمن الحد المسموح به في خطتك. قم بتعيين قيمة أصغر صراحةً إذا كانت خطتك لا تسمح بالقيمة الافتراضية. تتضمن الاستجابة الغرفة الجديدة id, projectId, name, maxParticipants, status (open)، و createdAt.

GET /v1/rooms تسرد غرف المشروع الخاصة بالمفتاح. قم بإنهاء الغرفة باستخدام POST /v1/rooms/{roomId}/end، بدون نص. يؤدي إنهاء الغرفة إلى منع عمليات الانضمام الجديدة و قطع الاتصال بالجلسات النشطة. كما يطلب إيقاف مهام التسجيل النشطة. يؤدي تكرار العملية على غرفة تم إنهاؤها إلى إرجاع 404؛ فهي ليست استجابة نجاح متجانسة. لا توجد حاليًا أي طريقة لإعادة تسمية الغرفة أو إعادة فتحها أو حذفها.

إصدار بيانات اعتماد المشاركين

Section titled “إصدار بيانات اعتماد المشاركين”

POST /v1/rooms/{roomId}/tokens يقبل كائن JSON اختياري:

{ "canPublish": false }

canPublish القيمة الافتراضية هي true. اضبطه على false لعميل الاستقبال فقط. يجب أن تكون الغرفة مفتوحة وتابعة لمشروع المفتاح. تحتوي الاستجابة على:

الحقلالمعنى
tokenرمز مشارك حساس وقصير الأمد
participantIdالمعرف المخصص لعملية الانضمام هذه
expiresInمدة صلاحية بيانات اعتماد الانضمام بالثواني، حاليًا 300
urlعنوان URL للإشارة للعميل
iceServersتكوين ICE، بما في ذلك بيانات اعتماد الترحيل المؤقتة

اطلب بيانات اعتماد جديدة لكل عملية انضمام وإعادة اتصال. لا تستنتج نجاح القبول من إصدار الرمز المميز: حيث يتم التحقق من حالة الغرفة وسعتها والتفويض أيضًا عند الانضمام. انظر تدفق العميل الكامل.

مهام التسجيل والتنزيلات

Section titled “مهام التسجيل والتنزيلات”

ابدأ بـ POST /v1/recordings و { "roomId": "ROOM_UUID" }. الـ 202 تتضمن الاستجابة تسجيلاً id و status: "queued"؛ وهذا لا يعني وجود ملف قابل للتنزيل بالفعل. يؤدي وجود تسجيل نشط مكرر لنفس الغرفة إلى إرجاع 409.

GET /v1/recordings تُرجع المهام المُصفّاة حسب المشروع، بما في ذلك id, roomId, status، و tracks. تتضمن بيانات تعريف المسار id, kind, source, participantId، و bytes. استخدم معرّفات التتبع التي ترجعها RTC.

أوقف مهمة في قائمة الانتظار أو مهمة تسجيل باستخدام POST /v1/recordings/{recordingId}/stop، بدون نص. استطلع القائمة أو استخدم recording.ready webhook لتحديد اكتمال العملية. المهمة التي تكون بالفعل قيد المعالجة، أو جاهزة، أو فاشلة ليست هدفًا نشطًا للإيقاف وتُرجع 404.

بالنسبة لمسار جاهز، انشر إلى /download المسار. الرد هو { "url": "TEMPORARY_DOWNLOAD_URL", "expiresIn": 300 }. احصل على عنوان URL المُرجع دون تغيير لتنزيل بايتات المرفق. عنوان URL نفسه يصرح بالوصول حتى انتهاء الصلاحية؛ تعامل معه كبيانات اعتماد. إنه لا رابط عام دائم. انظر أمن التسجيل وتنسيقاته.

GET /v1/usage تُرجع:

الحقلالمعنى
participantSecondsمجموع مدد جلسات المشاركين المكتملة ضمن النطاق
sessionsعدد الاتصالات المكتملة ضمن النطاق
periodall-time لهذه عدادات الأنشطة
billingStatusتشير إلى الفوترة المدارة مركزيًّا
quotasقرارات الاستحقاق الحالية لميزات RTC في مساحة العمل

اقسم ثواني المشاركين على 60 لعرض دقائق المشاركين. لا تمثل عدادات النشاط هذه فاتورةً أو عددًا مباشرًا للمشاركين. يقوم مفتاح المشروع بتصفية النشاط الخاص بمشروعه، بينما تنتمي المخصصات إلى مساحة العمل المالكة. قد يتم تحديث استخدام الفوترة بشكل غير متزامن؛ استخدم نظام الفوترة المركزي للحصول على معلومات الاشتراك والفواتير.

تُرجع الأخطاء JSON error سلسلة نصية و code، والتي يتم إرسالها أيضًا في X-Error-Code رأس الرسالة. أرسل RTC-Version: 2026-11-01 لغلاف الخطأ المنظم. انظر الأخطاء بالنسبة للأشكال وكتالوج الكود، حدود المعدل لـ 429، و إصدارات لما قد يتغير في إطار /v1. لا تعتمد على نص الرسالة بالضبط.

الحالةالتحقق أو الإجراء
400الحقول المطلوبة، أو معرّفات UUID، أو الحقول غير المعروفة، أو نطاقات الإدخال
401بيانات اعتماد مفقودة، أو غير صالحة، أو تم إلغاؤها، أو منتهية الصلاحية
403نطاق المفتاح، أو الوصول إلى المشروع، أو استحقاق الخطة، أو الحصة المخصصة
404المورد غير موجود، أو خارج النطاق، أو ليس في الحالة المطلوبة
409عملية متعارضة، مثل تسجيل نشط
413يتجاوز حجم نص الطلب الحد الأقصى المسموح به
429تحديد معدل الاستخدام؛ تراجع وامتثل Retry-After عند توفيرها
5xxفشل مؤقت في الخدمة؛ أعد محاولة القراءة مع التراجع وقم بمطابقة عمليات الكتابة

لا تقم أبدًا بفحص موارد عميل آخر للتمييز بين رفض الوصول و الغياب. اتبع إرشادات استكشاف الأخطاء وإصلاحها.