وثائق واجهة LiqaOS
يدير LiqaOS غرف الفيديو لمنتجك. يُنشئ خادمك الغرفة ورابط انضمام لكل شخص، وتعرض صفحتك الغرفة داخل إطار iframe، ويُخبر LiqaOS خادمك بما جرى عبر الإشعارات. العنوان الأساسي: https://liqaos.academito.online
الشيفرة وأسماء الحقول وطرق HTTP تبقى بالإنجليزية ومن اليسار إلى اليمين في كل مكان من هذه الصفحة، لأنها تُكتب كما هي في برامجك.
نظرة عامة
يعرف LiqaOS أربعة أشياء فقط: العملاء (أنت)، والغرف، والمشاركين، والدقائق. ولا يعرف شيئًا عن مستخدميك أو بياناتك: تُعرّف كل شخص بمعرّف من عندك هو external_id، ويعيده إليك LiqaOS في كل استجابة وفي كل إشعار.
الأدوار
| الدور | ما يستطيعه صاحبه |
|---|---|
host (مضيف) | يُسمح له بالدخول دائمًا مهما كانت غرفة الانتظار أو السعة. يقبل المنتظرين أو يرفضهم، ويكتم ميكروفون أي شخص، وينهي الغرفة للجميع، ويعرض محتواك على مسرح الغرفة. ينشر الكاميرا والميكروفون والشاشة. |
participant (مشارك) | ينشر الكاميرا والميكروفون والشاشة ويرسل البيانات. يدخل عبر غرفة الانتظار إن كانت الغرفة تستخدمها. |
observer (مراقب) | يشاهد ويستمع فقط ولا ينشر شيئًا. يمرّ بغرفة الانتظار مثل المشارك. |
غرفة الانتظار
حين تكون waiting_room: true (وهو الافتراضي) فإن المشارك أو المراقب الذي يفتح رابطه يطلب الدخول فتصبح حالته waiting، ثم يقبله المضيف أو يرفضه من داخل الغرفة. يسمع المضيف صوتًا ويرى بطاقة لكل منتظر. وحين تكون false يُسمح للجميع عند الوصول ما دامت الغرفة مفتوحة وغير ممتلئة. من سُمح له ثم انقطع يعود دون أن يطلب من جديد، ومن رفضه المضيف يبقى مرفوضًا على ذلك الرابط.
القبول والرفض يتمّان داخل الغرفة على يد مضيف. لا يوجد في الإصدار 1 نداء API لهما؛ يعلم خادمك بهما عبر الإشعارات participant.waiting وparticipant.admitted وparticipant.denied.
ما لا يفعله LiqaOS
- لا يُخزَّن أي وسائط. لا يوجد تسجيل في الإصدار 1.
- لا يدير مستخدميك ولا حساباتهم ولا صلاحياتهم: أنت تقرّر من يحصل على رابط وبأي دور.
- لا يجلب محتواك ولا يحتفظ به: الصفحة التي تعرضها على مسرح الغرفة يحمّلها متصفح كل شخص بنفسه داخل إطار معزول (انظر محتواك على مسرح الغرفة).
بداية سريعة
١. احصل على مفتاح
يُصدر المفاتيح مشغّل LiqaOS؛ لا توجد شاشة ذاتية الخدمة في الإصدار 1. اطلب من المشغّل حساب عميل، وأخبره بما يلي:
- أصول الصفحات التي ستضمّن الغرفة (
embed_origins)، مثلhttps://app.example.com؛ - أصول الصفحات التي ستعرضها على مسرح الغرفة (
content_origins) إن وُجدت؛ - العنوان الذي يستقبل الإشعارات (
webhook_url) إن وُجد.
ينشئ المشغّل الحساب من لوحة المشغّل ويسلّمك السرّين اللذين تعرضهما:
API key: lq_live_<40 random characters>
Webhook secret: whsec_<40 random characters>
يُعرض المفتاح وسرّ الإشعارات مرة واحدة فقط. يحفظ LiqaOS بصمة SHA-256 للمفتاح فقط، ويحفظ السرّ مشفّرًا بحيث لا يُعرض ثانية. احفظهما فورًا في مخزن أسرار خادمك. وإن ضاع مفتاح فاطلب من المشغّل مفتاحًا جديدًا (انظر المفاتيح).
تُكتب الأصول بصيغة scheme://host[:port] دون أي شيء بعدها: https://app.example.com وليس https://app.example.com/rooms.
٢. أنشئ غرفة
curl -X POST https://liqaos.academito.online/api/v1/rooms \
-H "Authorization: Bearer $LIQAOS_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"external_id": "consult-2041",
"title": "Follow-up consultation",
"opens_at": "2026-12-01T08:50:00Z",
"closes_at": "2026-12-01T10:00:00Z",
"waiting_room": true,
"max_participants": 4,
"metadata": { "department": "cardiology" }
}'
الاستجابة 201 ومعها الغرفة:
{
"id": "01JD5Q8K3Z7M2V9X4B6N1C0HTA",
"external_id": "consult-2041",
"title": "Follow-up consultation",
"opens_at": "2026-12-01T08:50:00Z",
"closes_at": "2026-12-01T10:00:00Z",
"waiting_room": true,
"whiteboard": true,
"features": { "whiteboard": true, "screen_share": true, "pip": true },
"max_participants": 4,
"metadata": { "department": "cardiology" },
"embed_origins": [],
"content_origins": [],
"status": "scheduled",
"started_at": null,
"ended_at": null,
"created_at": "2026-11-08T12:00:00Z"
}
٣. أضف مشاركًا
curl -X POST https://liqaos.academito.online/api/v1/rooms/01JD5Q8K3Z7M2V9X4B6N1C0HTA/participants \
-H "Authorization: Bearer $LIQAOS_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"external_id": "user-17",
"name": "Dr. Salma Haddad",
"role": "host"
}'
{
"participant_id": "01JD5QB2W4R8T6Y0E3F5G7H9JK",
"join_url": "https://liqaos.academito.online/j/<64 random characters>",
"expires_at": "2026-12-01T10:00:00Z"
}
استدعِه مرة لكل شخص. الرابط join_url لذلك الشخص وحده: هو مفتاحه إلى الغرفة.
٤. افتح الرابط أو ضمّنه
وجّه الشخص إلى join_url، أو ضعه في iframe داخل صفحة أصلها ضمن embed_origins (انظر تضمين الغرفة).
التسلسل نفسه على خادمك (Node.js)
// Node.js 18 or later. Run it on your server, never in a browser: it holds the API key.
const BASE = 'https://liqaos.academito.online';
const KEY = process.env.LIQAOS_KEY; // lq_live_...
async function call(method, path, body) {
const res = await fetch(BASE + path, {
method,
headers: {
Authorization: `Bearer ${KEY}`,
'Content-Type': 'application/json',
Accept: 'application/json',
},
body: body ? JSON.stringify(body) : undefined,
});
const json = await res.json();
if (!res.ok) throw new Error(`${res.status} ${json.code}: ${json.message}`);
return json;
}
// 1. The room. The same external_id always returns the same room.
const room = await call('POST', '/api/v1/rooms', {
external_id: 'consult-2041',
title: 'Follow-up consultation',
closes_at: '2026-12-01T10:00:00Z',
});
// 2. One join link per person.
const host = await call('POST', `/api/v1/rooms/${room.id}/participants`, {
external_id: 'user-17',
name: 'Dr. Salma Haddad',
role: 'host',
});
const guest = await call('POST', `/api/v1/rooms/${room.id}/participants`, {
external_id: 'user-52',
name: 'Omar Nasser',
role: 'participant',
});
// 3. Give each person their own link (or put it in an iframe, see "Embedding").
console.log('host ', host.join_url);
console.log('guest', guest.join_url);
المصادقة
يحمل كل نداء تحت /api/v1 مفتاحك في ترويسة bearer:
Authorization: Bearer lq_live_<40 random characters>
- يبدأ المفتاح بـ
lq_live_ثم 40 حرفًا عشوائيًا. - المفتاح المفقود، أو الذي لا يبدأ بـ
lq_live_، أو المجهول، أو الملغى، أو مفتاح عميل حجب المشغّل حسابه، تحصل كلها على الجواب نفسه:401وunauthenticated. - أبقِ المفتاح على خادمك. لا تضعه في صفحة ولا في تطبيق ولا في مستودع شيفرة.
{
"code": "unauthenticated",
"message": "A valid API key is required."
}
المفاتيح
- يجوز أن يكون لديك عدة مفاتيح في وقت واحد، كمفتاح لكل خادم أو لكل بيئة، فيُستبدل أحدها دون إيقاف البقية. يُفحص كل مفتاح على حدة ويعمل باسم العميل نفسه؛ وحدّ 120 طلبًا في الدقيقة محسوب للعميل كله.
- يُصدر المشغّل المفاتيح ويدوّرها ويلغيها، وأنت تطلب ذلك منه. يُعرض المفتاح الجديد مرة واحدة للمشغّل، فيسلّمه إليك. والتدوير يعطيك مفتاحًا جديدًا مكان القديم، ويتوقف القديم عن العمل فورًا. وإن لم تحتمل انقطاعًا فاطلب أولًا مفتاحًا إضافيًا، وانتقل إليه، ثم اطلب إلغاء القديم. المفتاح الملغى يجيب
401. - سرّ الإشعارات يدوّره المشغّل أيضًا. يُعرض مرة واحدة، وتتحقق بعدها من التواقيع بالقيمة الجديدة، فغيّر شيفرة التحقق عندك في الوقت نفسه.
- لا يحتفظ LiqaOS إلا ببصمة المفتاح، فلا يمكن عرضه ثانية. وإن ضاع مفتاح أو تسرّب فاطلب مفتاحًا جديدًا وإلغاء القديم.
اصطلاحات عامة
- الطلبات والاستجابات بصيغة JSON (
Content-Type: application/json). الاستجابات كائنات ومصفوفات مجرّدة دون غلافdata. - الأوقات لحظات بصيغة ISO-8601. يجيب LiqaOS بالتوقيت العالمي UTC مع
Zفي النهاية (2026-12-01T10:00:00Z). أرسل أنت دائمًا إزاحة صريحة أوZ. - المعرّفات (
idوparticipant_id) من نوع ULID بطول 26 حرفًا. عاملها كنصوص مبهمة. - لكل رفض
codeتقرؤه الآلة وmessage. اعتمد علىcode؛ الرسالة للبشر وهي بالإنجليزية. - غرفة عميل آخر غير موجودة بالنسبة إليك: تجيب
404 not_foundكغرفة لم تُنشأ قط. - القوائم غير مقسّمة إلى صفحات.
مرجع الواجهة
كل المسارات تحت /api/v1 وتحتاج ترويسة Authorization. يحق لكل مفتاح 120 طلبًا في الدقيقة (انظر الأخطاء والحدود).
إنشاء غرفة
POST/api/v1/rooms| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
title | string | نعم | حتى 255 حرفًا. |
external_id | string أو null | لا | حتى 191 حرفًا. معرّفك أنت للغرفة، فريد لكل عميل. انظر أدناه. |
opens_at | ISO-8601 أو null | لا | قبل هذه اللحظة تجيب الغرفة not_open. انظر نافذة الغرفة. |
closes_at | ISO-8601 أو null | لا | يجب أن تكون بعد opens_at إذا وُجدت الاثنتان. بعد هذه اللحظة تجيب الغرفة closed، وتنتهي عندها صلاحية الروابط. |
waiting_room | boolean | لا | الافتراضي true. |
whiteboard | boolean | لا | هل للغرفة سبورة (انظر السبورة). هذا مفتاح الغرفة نفسها ويبدأ true؛ وتعمل السبورة ما دامت ميزة السبورة مفعّلة لحسابك أيضًا (يستطيع المشغّل تعطيلها لحسابك كله، بما فيه الغرف القائمة). وتعيد الغرفة الحقل features وفيه ما هو مفعّل الآن. |
max_participants | integer | لا | من 1 إلى 1000. الافتراضي 50. |
metadata | كائن JSON أو null | لا | ما تريد استرجاعه لاحقًا. لا يقرؤه LiqaOS. |
embed_origins | مصفوفة أصول | لا | حتى 10، كل أصل حتى 255 حرفًا بصيغة scheme://host[:port]. تُضاف إلى قائمة حسابك لهذه الغرفة وحدها. |
content_origins | مصفوفة أصول | لا | القواعد نفسها. تُضاف إلى قائمة حسابك لهذه الغرفة وحدها. |
إعادة الطلب آمنة بحسب external_id. إن وُجدت غرفة بهذا external_id أعاد النداء الغرفة نفسها بالرمز 200 بدل 201، وتُهمل بقية الحقول المرسلة (استخدم PATCH لتعديل غرفة). يُتحقق من الطلب أولًا، فيجب أن يكون الطلب المكرّر صحيحًا أيضًا. نداءان متزامنان بالمعرّف نفسه ينتهيان بغرفة واحدة.
أصول خاصة بالغرفة. إن كانت صفحاتك موزعة على مضيفين كثيرين (مضيف لكل عميل لديك مثلًا) فسمِّ في embed_origins المضيف الذي يضمّن هذه الغرفة، وفي content_origins المضيفين الذين يجوز عرض صفحاتهم. تُضاف إلى قوائم حسابك لهذه الغرفة وحدها. تُعرض في الاستجابة بعد توحيد شكلها (أحرف صغيرة وبلا شرطة مائلة أخيرة)، وتُحذف المشوّهة من المخرجات.
الاستجابة 201 (أُنشئت) أو 200 (موجودة): كائن الغرفة.
| الحقل | المعنى |
|---|---|
id | معرّف الغرفة عند LiqaOS (ULID). |
external_id | معرّفك، أو null. |
title وwaiting_room وwhiteboard وmax_participants وmetadata | كما حُفظت. |
opens_at وcloses_at | بتوقيت UTC، أو null. |
embed_origins وcontent_origins | قائمتا هذه الغرفة وحدها، لا قائمتا حسابك. |
status | scheduled قبل opens_at؛ open بعدها؛ live ما دام شخص واحد على الأقل متصلًا؛ ended متى أُنهيت الغرفة أو مرّ closes_at. |
started_at | لحظة اتصال أول شخص، أو null. |
ended_at | لحظة إنهاء الغرفة عبر /end أو على يد مضيف، أو null. تبقى null لغرفة مرّ وقت إغلاقها فقط. |
created_at | بتوقيت UTC. |
الأخطاء: 401 و402 subscription_inactive (لا يمكن للاشتراك أن يبدأ شيئًا جديدًا) و402 quota_exceeded (استُنفد المخصص في خطة تتوقف عنده) و422 validation_failed و429 rate_limited أو 429 concurrent_rooms_limit (بلغت الخطة حدّها من الاجتماعات في الوقت نفسه). والنداء الذي يحمل external_id معروفًا يعيد الغرفة الموجودة ولا يُعدّ غرفة جديدة: فلا يُرفض بسبب المخصص ولا بسبب حدّ الغرف، لكن يجب أن يكون الاشتراك صالحًا. انظر الخطط والحدود.
قراءة غرفة
GET/api/v1/rooms/{room}القيمة {room} هي id الغرفة (وليست external_id). تعيد كائن الغرفة أعلاه. الأخطاء: 401 و404 not_found و429.
تعديل غرفة
PATCH/api/v1/rooms/{room}تقبل حقول الإنشاء نفسها؛ كل حقل اختياري ولا يتغيّر إلا ما ترسله. وإذا أُرسل title فلا يجوز أن يكون null.
curl -X PATCH https://liqaos.academito.online/api/v1/rooms/01JD5Q8K3Z7M2V9X4B6N1C0HTA \
-H "Authorization: Bearer $LIQAOS_KEY" \
-H "Content-Type: application/json" \
-d '{ "closes_at": "2026-12-01T11:00:00Z" }'
- تحريك
closes_atيحرّك معه انتهاء صلاحية روابط كل المشاركين إلى الوقت الجديد. وضعهاnullيمنح كل رابط 24 ساعة من الآن. - يُقارَن
closes_atبـopens_atكما سيكون بعد التعديل، بما في ذلك قيمة لم ترسلها. - الغرفة التي مرّ وقت إغلاقها دون أن يُنهيها أحد ما زال تعديلها ممكنًا، وبهذه الطريقة تمدّدها.
- تغيير
external_idإلى معرّف تستخدمه غرفة أخرى لديك يفشل بالرمز422 external_id_taken.
تعيد الغرفة. الأخطاء: 401 و404 و409 room_ended (أُنهيت الغرفة صراحةً فلا تُعدَّل) و422 validation_failed أو external_id_taken و429.
إنهاء غرفة
POST/api/v1/rooms/{room}/endبلا جسم. تنهي الغرفة للجميع: يزيلها LiqaOS من خادم الوسائط فيُقطع اتصال كل من فيها؛ وتُرفض كل محاولة انضمام لاحقة بالحالة ended؛ ويُعلَّم المنتظرون والمقبولون بأنهم غادروا؛ وتُغلق فترات الاستخدام المفتوحة؛ ويصل خادمك الإشعار room.ended.
curl -X POST https://liqaos.academito.online/api/v1/rooms/01JD5Q8K3Z7M2V9X4B6N1C0HTA/end \
-H "Authorization: Bearer $LIQAOS_KEY"
تعيد الغرفة بالحالة status: "ended". استدعاؤها ثانية على غرفة منتهية لا يغيّر شيئًا ولا يرسل إشعارًا ثانيًا. وإن تعذّر الوصول إلى خادم الوسائط فإن الغرفة تُنهى عند LiqaOS رغم ذلك وتُرفض الانضمامات الجديدة، لكن المتصلين فعلًا قد لا يُقطع اتصالهم فورًا.
الأخطاء: 401 و404 و429.
إضافة مشارك
POST/api/v1/rooms/{room}/participants| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
external_id | string | نعم | حتى 191 حرفًا. معرّفك لهذا الشخص. شخص واحد لكل external_id في الغرفة. |
name | string | نعم | حتى 255 حرفًا. يراه الآخرون في الغرفة. |
role | string | نعم | host أو participant أو observer. |
avatar_url | URL أو null | لا | عنوان صحيح حتى 2048 حرفًا. |
الاستجابة: 201 في المرة الأولى، و200 إن كان external_id موجودًا في الغرفة.
| الحقل | المعنى |
|---|---|
participant_id | معرّف الشخص عند LiqaOS في هذه الغرفة. |
join_url | https://liqaos.academito.online/j/<token>. الرمز token لا يظهر إلا في هذه الاستجابة: يحفظ LiqaOS بصمته فقط. |
expires_at | لحظة توقف الرابط: closes_at الغرفة، أو بعد 24 ساعة من الآن إن لم يكن للغرفة إغلاق. |
الإصدار المتكرر. نداء جديد بالـ external_id نفسه يعطي رابطًا جديدًا ويتوقف الرابط القديم فورًا. يُحدَّث الاسم والدور والصورة. وتبقى حالة قبول الشخص كما هي، فلا بأس بإعادة الإصدار عند كل تحميل للصفحة: من رفضه المضيف لا يصبح مرحَّبًا به، ومن قُبل لا ينتظر مرتين. وتنتهي الجلسات المفتوحة بالرابط القديم معه.
الأخطاء: 401 و404 و409 room_ended (أُنهيت الغرفة) و409 room_closed (مرّ closes_at) و402 subscription_inactive و402 quota_exceeded (شخص جديد في خطة تتوقف عند مخصصها) و422 validation_failed و429 rate_limited. الغرفة التي لم تُفتح بعد تقبل المشاركين. وإعادة إصدار رابط لـ external_id موجود في الغرفة ليست شخصًا جديدًا ولا تُحسب من المخصص، لكنها تحتاج إلى اشتراك صالح. انظر الخطط والحدود.
قائمة المشاركين
GET/api/v1/rooms/{room}/participantsتعيد مصفوفة بكل من أُضيف إلى الغرفة، الأقدم أولًا.
[
{
"participant_id": "01JD5QB2W4R8T6Y0E3F5G7H9JK",
"external_id": "user-17",
"name": "Dr. Salma Haddad",
"role": "host",
"avatar_url": null,
"state": "in_room",
"joined_at": "2026-12-01T08:58:12Z",
"left_at": null
},
{
"participant_id": "01JD5QC7M1N3P5Q7R9S2T4V6WX",
"external_id": "user-52",
"name": "Omar Nasser",
"role": "participant",
"avatar_url": "https://app.example.com/avatars/52.png",
"state": "waiting",
"joined_at": null,
"left_at": null
}
]
| الحالة | المعنى |
|---|---|
invited | معه رابط ولم يطلب الدخول. |
waiting | طلب الدخول ولم يجبه مضيف. |
admitted | سُمح له (من مضيف أو تلقائيًا) ولم يتصل بعد. من سُمح له ولم يتصل أبدًا يتوقف عن حجز مقعد بعد 10 دقائق. |
denied | رفضه مضيف. نهائي لذلك الرابط. |
in_room | متصل الآن. joined_at مضبوط. |
left | كان في الغرفة وغادر، أو انتهت الغرفة. left_at مضبوط. |
الحقلان joined_at وleft_at بتوقيت UTC أو null. الأخطاء: 401 و404 و429.
الاستخدام
GET/api/v1/rooms/{room}/usage{
"participant_minutes": 47.5,
"peak_participants": 3
}
participant_minutes: مجموع الوقت الذي قضاه كل الأشخاص متصلين، بالدقائق، مقرّبًا إلى منزلتين. من هو متصل الآن يُحسب حتى هذه اللحظة.peak_participants: أكبر عدد من المتصلين في اللحظة نفسها. التسليم في الثانية نفسها (يخرج واحد ويدخل آخر) لا يُحسب اثنين.
الاستخدام لكل غرفة. اجمع غرف الفترة للحصول على إجماليك. الأخطاء: 401 و404 و429.
نافذة الغرفة وروابط الانضمام
الحقلان opens_at وcloses_at اختياريان. الغرفة التي بلا أيٍّ منهما مفتوحة من إنشائها حتى تُنهى.
| اللحظة | ما يراه من يفتح رابطه |
|---|---|
قبل opens_at | الغرفة لم تُفتح بعد (الحالة not_open). تعيد الصفحة الفحص بنفسها وتُدخل الشخص حين تُفتح الغرفة. ينتظر المضيفون أيضًا. ويمكنك إضافة المشاركين مسبقًا. |
من opens_at إلى closes_at | دخول عادي: تنطبق غرفة الانتظار والسعة والقبول. |
بعد closes_at | الغرفة مغلقة (الحالة closed). لا يدخل أحد. تقرأ status القيمة ended. ويُرفض إضافة مشاركين جدد بـ 409 room_closed. |
| بعد إنهاء صريح | الحالة ended. |
| الغرفة ممتلئة | الحالة full للمشاركين والمراقبين (لا يُرد المضيفون أبدًا). يحجز المقعدَ من هو متصل أو من قُبل خلال آخر 10 دقائق. |
من كان داخل الغرفة حين يمرّ closes_at تظهر له شاشة الإغلاق عند الفحص التالي الذي تجريه الغرفة كل 30 ثانية. استدعِ إنهاء غرفة إذا أردت أن تتوقف الغرفة في لحظة محددة بالضبط.
مرور closes_at وحده لا يرسل إشعار room.ended. يُرسل هذا الإشعار حين تُنهى الغرفة عبر /end أو على يد مضيف.
مدة صلاحية رابط الانضمام
- الرابط صالح حتى
closes_atالغرفة. وللغرفة التي بلا إغلاق يكون كل رابط صالحًا 24 ساعة من لحظة إصداره. - تعديل
closes_atيحرّك انتهاء كل الروابط معه. - الرابط المنتهي (والغرفة ما زالت قائمة) يجيب
410 token_expiredوتعرض الصفحة شاشة رابط غير صالح. أصدر رابطًا جديدًا بـ إضافة مشارك. - الرابط المجهول، أو الذي حلّ محلّه رابط أحدث للشخص نفسه، يبدو كالرابط غير الصالح:
404 invalid_token. - بعد أن يفتح الشخص الرابط تعمل الصفحة بجلسة مدتها ساعتان مرتبطة بذلك الرابط. وتذكرة الوسائط ساعتان وتجددها الصفحة.
تضمين الغرفة
الإطار iframe
ضع join_url الخاص بالمشارك في iframe بهذه الأذونات تمامًا:
<iframe
id="room"
src="https://liqaos.academito.online/j/JOIN_TOKEN"
title="Video room"
allow="camera; microphone; display-capture; fullscreen; autoplay; picture-in-picture"
style="width:100%; height:600px; border:0">
</iframe>
بدون allow يمنع المتصفح الكاميرا والميكروفون ومشاركة الشاشة داخل الإطار.
ما يجب أن تسمح به صفحتك
- يجب أن يكون أصلك مدرجًا. لا يسمح LiqaOS بتضمين الغرفة إلا لـ
embed_origins(حسابك مع الغرفة). يرسلframe-ancestors 'self'يتبعها تلك الأصول. الصفحة التي لا يطابق أصلها (النظام والمضيف والمنفذ بالضبط) أيًّا منها يظهر لها إطار فارغ. - ترويسة
Content-Security-Policyعندك، إن أرسلتها بـframe-srcأوdefault-src، يجب أن تسمح بـhttps://liqaos.academito.online. - ترويسة
Permissions-Policyعندك، إن أرسلتها، يجب أن تفوّض الأجهزة إلى LiqaOS، وإلا حجبها المتصفح قبل النظر فيallowالإطار.
# Headers your own page may send. Add only what you already use.
# Content-Security-Policy: let the page frame LiqaOS.
Content-Security-Policy: frame-src https://liqaos.academito.online
# Permissions-Policy: if you send this header at all, delegate the devices to LiqaOS.
Permissions-Policy: camera=(self "https://liqaos.academito.online"), microphone=(self "https://liqaos.academito.online"), display-capture=(self "https://liqaos.academito.online"), fullscreen=(self "https://liqaos.academito.online"), picture-in-picture=(self "https://liqaos.academito.online"), autoplay=(self "https://liqaos.academito.online")
للاطلاع، هذا ما يرسله LiqaOS مع صفحة الغرفة (الأصول في السطر الأول هي أصول الغرفة):
Content-Security-Policy: frame-ancestors 'self' https://app.example.com
Permissions-Policy: camera=(self), microphone=(self), display-capture=(self), fullscreen=(self), picture-in-picture=(self), autoplay=(self)
Referrer-Policy: no-referrer
Cache-Control: no-store
X-Content-Type-Options: nosniff
يجب أن تُخدَّم صفحتك عبر HTTPS (أو localhost أثناء التطوير): لا تمنح المتصفحات الكاميرا والميكروفون إلا للصفحات الآمنة.
النافذة العائمة
حين يغادر الشخص تبويب الاجتماع (تبويب آخر أو تطبيق آخر أو متصفح مصغَّر)، يمكن للغرفة إبقاء الاجتماع ظاهرًا في نافذة صغيرة عائمة فيها أزرار الميكروفون والكاميرا والمغادرة وطريق للعودة إلى الاجتماع. وإغلاق هذه النافذة يعيد الشخص إلى المتصفح فقط، ويستمر الاتصال. وما يحصل عليه الشخص يختلف باختلاف المتصفح، ولا يحتاج شيء منه إلى نداء للخادم:
- الغرفة مفتوحة كصفحة مستقلة (Chrome وEdge على الحاسوب): نافذة يرسمها LiqaOS بأزرارها الخاصة.
- الغرفة داخل iframe عندك، وChrome على أندرويد: نافذة «صورة داخل صورة» الخاصة بالمتصفح تعرض المتحدث أو الشاشة المشاركة، مع أزرار الميكروفون والكاميرا وإنهاء المكالمة من المتصفح. لا يسمح المتصفح لصفحة بفتح نافذتها العائمة الخاصة إلا إن كانت صفحة عليا، ولهذا يحصل الإطار على هذه الصورة.
- Safari: الفيديو وحده دون أزرار، فلا يتيح Safari إضافتها.
- Firefox وأي متصفح لا يدعم الميزة: لا يظهر الزر.
لتعرض الغرفة المضمَّنة هذه الميزة يلزم أن يحوي allow في الـ iframe القيمة picture-in-picture (وهي في المقتطف أعلاه)، وألا تحجبها ترويسة Permissions-Policy عندك. وحيث تحجبها السياسة لا تعرض الغرفة الزر. وتدخل بعض المتصفحات النافذة من تلقاء نفسها حين ينتقل الشخص إلى غيرها؛ وهذا قرار المتصفح ولا تحتاج الغرفة فيه إلى شيء من صفحتك.
الرسائل: من الغرفة إلى صفحتك
تتحدث الغرفة مع صفحتك عبر window.postMessage. كل رسالة كائن يبدأ type فيه بـ liqaos:.
| الرسالة | الحقول | متى |
|---|---|---|
liqaos:ready | لا شيء | حُمّلت الغرفة. تُرسل أولًا قبل أن تعرف الغرفة أصلك، فهي الرسالة الوحيدة التي هدفها *. لا تحمل شيئًا خاصًا. |
liqaos:state | state | waiting (طلب الدخول)، admitted (سُمح له ويتصل)، in_room (متصل)، left (غادر الشخص)، ended (انتهت الغرفة أو أُغلقت). |
liqaos:participant | event وname وrole وexternal_id | القيمة event هي joined أو left حين يتصل شخص آخر بالغرفة أو يغادرها والشخص فيها؛ وwaiting حين يطلب أحدهم الدخول (تُرسل إلى صفحة المضيف وحدها، والدور فيها participant). |
liqaos:content | key وurl | شارك مضيف محتوى (انظر محتواك على مسرح الغرفة). يمكنك الرد بـ liqaos:content-url. |
liqaos:content-stopped | key | لم يعد المحتوى الذي يحمل هذا key على المسرح، أيًّا كان السبب: أوقفه المضيف بنفسه، أو أرسلت صفحتك liqaos:stop-content، أو حلّ محتوى آخر محلّه، أو غادر من شاركه، أو انتهت الغرفة، أو غادر هذا الشخص. تابع الحالة الفعلية من هذه الرسالة بدل ما أرسلته صفحتك آخر مرة. |
liqaos:board | open (boolean) | فُتحت السبورة أو أُغلقت في هذه الغرفة (على يد مضيف، أو بالرسالتين liqaos:board-open وliqaos:board-close). انظر السبورة. |
الرسائل: من صفحتك إلى الغرفة
| الرسالة | الحقول | الأثر |
|---|---|---|
liqaos:share-content | key وurl وtitle وcontrols اختياريًا (قيمة منطقية) | للمضيف فقط. تعرض url على مسرح الغرفة للجميع. تُهمل إذا لم يكن الشخص مضيفًا. بالقيمة controls: false تعلن صفحتك أنها تدير المحتوى بنفسها (زر إيقاف خاص بها)، فلا ترسم الغرفة عنصر «إيقاف المشاركة» الخاص بها على مسرح المضيف؛ وبدونها ترسمه الغرفة. |
liqaos:content-url | key وurl | رد على liqaos:content: عنوان هذا الشخص الخاص للمحتوى نفسه. |
liqaos:stop-content | لا شيء | للمضيف فقط. تزيل المحتوى من مسرح الغرفة. |
liqaos:leave | لا شيء | يغادر الشخص الغرفة. |
liqaos:compact | on (boolean) | ينتقل إلى التخطيط الصغير العائم (true) أو يعود (false). |
liqaos:board-open | لا شيء | للمضيف فقط. تفتح السبورة لكل من في الغرفة. تُتجاهل من غير المضيف، وفي غرفة لا سبورة لها. |
liqaos:board-close | لا شيء | للمضيف فقط. تغلق السبورة عن الجميع. يبقى الرسم على السبورة. |
الأصول التي يُتحقق منها
- داخل الغرفة لا تُقبل رسالة إلا من الصفحة التي تضمّنها (
event.sourceهو النافذة الأم)، وبشرط أن يكون أصل تلك الصفحة هو ما يبلّغ عنه المتصفح للصفحة الأم، وأن يكون ضمنembed_originsإن كان للغرفة قائمة. وتُسقَط رسائل الأصول والنوافذ الأخرى بصمت. - الرسائل الصادرة من الغرفة تُرسل إلى ذلك الأصل وحده ولا تُرسل بـ
*(باستثناءliqaos:ready). - في صفحتك تحقّق من أن
event.origin === 'https://liqaos.academito.online'وأنevent.source === iframe.contentWindow، وأرسل بهذا الأصل بالضبط فيtargetOrigin. - المتصفحات التي لا تكشف للإطار أصلَ الصفحة المضمِّنة (لا تملك
location.ancestorOrigins) تترك الغرفة عاجزة عن تسمية صفحتها الأم إلى أن تسمع من أحدembed_originsالمدرجة. أرسل رسالة عند وصولliqaos:readyكما في المثال. وإن كان للغرفة أصل تضمين واحد فقط أمكنها الرد فورًا.
مثال
const LIQAOS = 'https://liqaos.academito.online';
const frame = document.getElementById('room');
function send(message) {
// Always an exact target origin, never '*'.
frame.contentWindow.postMessage(message, LIQAOS);
}
window.addEventListener('message', (event) => {
// Both checks, every time: the right origin, and our own iframe.
if (event.origin !== LIQAOS || event.source !== frame.contentWindow) return;
const m = event.data;
if (!m || typeof m.type !== 'string') return;
switch (m.type) {
case 'liqaos:ready':
// The room has loaded. Anything you send now is heard.
send({ type: 'liqaos:compact', on: false });
break;
case 'liqaos:state':
console.log('state:', m.state); // waiting, admitted, in_room, left, ended
break;
case 'liqaos:participant':
console.log(m.event, m.name, m.role, m.external_id); // joined, left, waiting
break;
case 'liqaos:content':
// A host shared content. Answer within 1.5 seconds with this viewer's own URL.
send({ type: 'liqaos:content-url', key: m.key, url: m.url + '?viewer=' + encodeURIComponent(currentUserId) });
break;
case 'liqaos:content-stopped':
// The content with this key is off the stage, whatever the reason: follow the real state.
markContentStopped(m.key);
break;
}
});
// Host only: show a page of yours on the stage for everyone.
function shareContent() {
send({
type: 'liqaos:share-content',
key: 'agenda-1',
url: 'https://app.example.com/shared/agenda/1',
title: 'Agenda',
controls: false, // this page has its own stop button, so the room draws none
});
}
function stopContent() { send({ type: 'liqaos:stop-content' }); }
function leaveRoom() { send({ type: 'liqaos:leave' }); }
محتواك على مسرح الغرفة
يستطيع المضيف أن يعرض إحدى صفحاتك على مسرح الغرفة للجميع بجوار الأشخاص. لا تجلب الغرفة الصفحة بنفسها: يحمّلها متصفح كل شخص داخل إطار.
- ترسل صفحتك (التي تضمّن الغرفة)
liqaos:share-contentومعهاkeyيعرّف هذا المحتوى وurlوtitle. لا تعمل بها إلا غرفة مضيف. - يجب أن يكون العنوان
httpأوhttpsوأن يكون أصله أحدcontent_origins(حسابك مع الغرفة). غير ذلك يُرفض ويرى الشخص تنبيهًا. - ترسل غرفة المضيف المحتوى إلى بقية من في الغرفة عبر اتصال الوسائط. ومن يصل متأخرًا يستلمه أيضًا.
- قبل العرض ترسل غرفة كل شخص
liqaos:contentإلى صفحتها الأم هي. فإن ردّت صفحتك بـliqaos:content-url(بالـkeyنفسه) خلال 1.5 ثانية عرضت الغرفة ذلك العنوان بدل المشترك. بهذا يحصل كل مشاهد على رابط خاص به، كعنوان فيه رمزه الشخصي. ويجب أن يكون الرد أيضًا ضمنcontent_originsوإلا أُهمل واستُخدم العنوان المشترك. - الرسالة
liqaos:stop-contentتزيله عن الجميع. وكلما غادر المحتوى المسرح، لهذا السبب أو لغيره، تُعلم غرفة كل شخص صفحتها بالرسالةliqaos:content-stoppedومعهاkey. ومن لم يكن مضمَّنًا في صفحة لك يرى العنوان المشترك دائمًا.
افتراضيًا ترسم غرفة المضيف عنصر «إيقاف المشاركة». وإن كان لصفحتك عنصر تحكم خاص بها فأرسل controls: false مع liqaos:share-content، وأرسل liqaos:stop-content بنفسك.
ما يجب أن تسمح به صفحة المحتوى
- تُعرض في iframe بالخصائص
sandbox="allow-scripts allow-same-origin allow-forms allow-popups"وallow="fullscreen". تعمل السكربتات والنماذج والنوافذ المنبثقة وأصلها الخاص؛ ولا يعمل الانتقال بالصفحة العليا ولا التنزيلات ولا الكاميرا أو الميكروفون. - يجب أن تسمح بتضمينها في LiqaOS: لا ترسل
X-Frame-Options: DENYولاSAMEORIGIN، واسمح بأصل LiqaOS فيframe-ancestors:
Content-Security-Policy: frame-ancestors 'self' https://liqaos.academito.online
# And no X-Frame-Options: DENY or SAMEORIGIN on that page.
قد تعامل المتصفحات ملفات الارتباط لصفحة معروضة داخل موقع آخر معاملة ملفات الطرف الثالث. فضّل عنوانًا خاصًا بالشخص (جواب content-url) على الاعتماد على ملف ارتباط لتسجيل الدخول.
السبورة
يمكن أن تكون لكل غرفة سبورة يراها كل من فيها في اللحظة نفسها. يفتحها المضيف من شريط أدوات الغرفة، أو تفتحها صفحتك بالرسالة liqaos:board-open. وهي مفعّلة افتراضيًا؛ أنشئ الغرفة بـ whiteboard: false (أو اطلب من المشغّل تعطيل الميزة لحسابك كله، بما فيه الغرف القائمة) إن لم ترد السبورة.
من يرسم
- المضيف يرسم دائمًا، وهو وحده من يفتح السبورة ويغلقها، ويضيف الصفحات والصور وملفات PDF والنصوص، ويحرّك العناصر، ويمسح الصفحة، ويختار من يرسم غيره.
- المشاركون يشاهدون حتى يسمح لهم المضيف بالرسم، واحدًا واحدًا، وله أن يسحب الإذن في أي لحظة. ومن سُمح له يرسم ويتراجع عن خطوطه هو فقط.
- المراقبون يشاهدون فقط. لا يرسمون أبدًا، ويرفض الخادم ذلك مهما فعلت الصفحة.
كل قاعدة من هذه يفرضها LiqaOS في كل طلب؛ وما تفعله الغرفة هو إخفاء الأزرار التي لا يملكها الشخص.
ما يوضع عليها
- صفحات (حتى 50) لكل منها خلفيتها، ورسم بالقلم والأشكال والممحاة والملصقات.
- صور وملفات PDF (تُعرض صفحة واحدة في كل مرة ويقلّبها المضيف) ونصوص. تتسع السبورة لـ 60 عنصرًا منها، ويصل حجم الملف الواحد إلى 15 ميغابايت، ومجموع ملفات الغرفة الواحدة إلى 200 ميغابايت. وتُعاد ترميز الصورة في LiqaOS ولا تُحفظ كما أُرسلت.
- الملفات خاصة بالغرفة. ليس لها عنوان عام، ولا يقرؤها إلا من هو داخل الغرفة.
أن تعلم بها صفحتك
ترسل الغرفة إلى صفحتك الرسالة liqaos:board مع open: true أو false كلما فُتحت السبورة أو أُغلقت. استعملها لتفسح مكانًا للسبورة، كأن تنقل الغرفة إلى التخطيط الكبير ما دامت مفتوحة (liqaos:compact مع on: false). ولصفحتك أن ترسل liqaos:board-open وliqaos:board-close؛ وهما تعملان في غرفة المضيف فقط.
تتشارك السبورة المسرح مع الشاشة المشتركة والمحتوى المشترك (liqaos:share-content): يُعرض ما وصل أخيرًا، ويعود السابق حين ينتهي. وفتح السبورة يحلّ محلّ المحتوى المشترك، وتُعلِم الغرفة صفحتك بذلك بالرسالة liqaos:content-stopped.
كم تُحفظ
تُحفظ سبورة الغرفة (الرسم والملفات) 30 يومًا (وهذا الافتراضي) بعد أن تنتهي الغرفة أو تُغلق، ثم تُحذف نهائيًا. ولا يصل شيء منها إلى خادمك: الإشعارات لا تحمل الرسوم.
أخطاء قد تصادفها
يتولاها تطبيق الغرفة عنك؛ ولا تهمّك إلا إن قرأت الـ API مباشرة. وكلها تردّ بـ code وmessage بلغة الطلب (Accept-Language).
| الحالة | code | المعنى |
|---|---|---|
| 403 | board_disabled | لا سبورة لهذه الغرفة. |
| 409 | room_ended | انتهت الغرفة أو أُغلقت. وسبورتها مغلقة كذلك، للقراءة أيضًا. |
| 403 | not_admitted | لم يُسمح للشخص بدخول الغرفة. |
| 403 | host_only | هذا الإجراء للمضيف وحده. |
| 403 | board_read_only | لا يحق للشخص الرسم. |
| 422 | board_items_limit وboard_pages_limit وboard_file_too_big وboard_room_full | 60 عنصرًا، أو 50 صفحة، أو ملف فوق 15 ميغابايت، أو استُنفدت 200 ميغابايت من ملفات الغرفة. |
الإشعارات (Webhooks)
إن كان لحسابك webhook_url أرسل LiqaOS إليه طلب POST لكل حدث من الأحداث أدناه. وبدون webhook_url لا يُرسل شيء. يضبط المشغّل هذا العنوان عند إنشاء الحساب.
الحمولة
{
"id": "01JD5R4P8A2C4E6G8J0L2N4Q6S",
"type": "participant.admitted",
"created_at": "2026-12-01T08:59:40Z",
"room": {
"id": "01JD5Q8K3Z7M2V9X4B6N1C0HTA",
"external_id": "consult-2041"
},
"participant": {
"participant_id": "01JD5QC7M1N3P5Q7R9S2T4V6WX",
"external_id": "user-52",
"name": "Omar Nasser",
"role": "participant"
}
}
| الحقل | المعنى |
|---|---|
id | معرّف فريد لهذا الحدث. استخدمه لمنع التكرار. |
type | أحد الأحداث أدناه. |
created_at | لحظة إنشاء الحدث بتوقيت UTC. |
room | id وexternal_id (أو null). |
participant | لأحداث المشاركين فقط: participant_id وexternal_id وname وrole. |
الأحداث
| النوع | متى يُرسل |
|---|---|
room.started | يتصل أول شخص. تعود الغرفة إلى حالة open حين تفرغ ويمكن أن تبدأ من جديد، فقد يصلك هذا الحدث أكثر من مرة للغرفة الواحدة. |
room.ended | تُنهى الغرفة عبر /end أو على يد مضيف (مرة واحدة للغرفة). |
participant.waiting | يطلب شخص الدخول ويبدأ الانتظار. |
participant.admitted | يقبل مضيف شخصًا منتظرًا. لا يُرسل لمن يُسمح لهم تلقائيًا (المضيفون، أو الغرف بلا غرفة انتظار). |
participant.denied | يرفض مضيف شخصًا منتظرًا. |
participant.joined | يتصل شخص بالغرفة. |
participant.left | ينقطع اتصال شخص. |
تُبلَّغ الأحداث participant.joined وparticipant.left وroom.started من خادم الوسائط وقد تصل متأخرة قليلًا. ترتيب وصول الأحداث المختلفة غير مضمون؛ استعمل created_at.
التسليم وإعادة المحاولة
- الجسم JSON، والترويسة
Content-Typeهيapplication/json. - أجب بأي حالة 2xx خلال 10 ثوانٍ. لا تُتبع إعادة التوجيه، فالحالة
3xxتُعدّ فشلًا. - عند أي جواب آخر أو انتهاء المهلة أو خطأ اتصال يعيد LiqaOS المحاولة بعد دقيقة، ثم بعد 5 دقائق، ثم بعد 30 دقيقة من المحاولة السابقة. أي أربع محاولات في المجموع؛ وبعد الأخيرة يُترك التسليم ويُسجَّل عند LiqaOS. لا توجد نقطة لإعادة الإرسال في الإصدار 1.
- تحمل إعادة المحاولة
idالحدث نفسه وجسمه نفسه، مع طابع زمني وتوقيع جديدين. - التسليم «مرة واحدة على الأقل»: قد يصلك الحدث نفسه مرتين. احفظ المعرّفات
idالتي عالجتها وتجاهل المكرر.
التوقيع
لكل طلب ترويسة:
LiqaOS-Signature: t=1796115580,v1=3f1c0b7e5a9d4c2e8b6a0f1d3c5e7a9b2d4f6081a3c5e7092b4d6f8a0c1e3a5b
الخوارزمية:
- قسّم الترويسة عند الفواصل إلى
t(وقت يونكس بالثواني) وv1(64 خانة سداسية عشرية). - كوّن النص
t + "." + bodyحيثbodyهو جسم الطلب الخام كما وصل تمامًا (لا JSON أُعيد ترميزه). - احسب HMAC-SHA256 لذلك النص بمفتاح هو سرّ الإشعارات (
whsec_…) وأخرجه بأحرف سداسية عشرية صغيرة. - قارنه بـ
v1بمقارنة زمنها ثابت. - ارفض الطلب إذا بعد
tعن ساعتك أكثر من 5 دقائق. لا يفرض LiqaOS مهلة بنفسه؛ الخمس دقائق توصية، ولا تضرّ بإعادة المحاولة لأن كل محاولة توقَّع بـtجديد.
PHP
<?php
// $secret is your webhook secret (whsec_...). Read the BODY EXACTLY as received, before any JSON decoding.
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_LIQAOS_SIGNATURE'] ?? '';
if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m)) {
http_response_code(400); exit;
}
[, $timestamp, $signature] = $m;
if (abs(time() - (int) $timestamp) > 300) { // replay protection: 5 minutes
http_response_code(400); exit;
}
$expected = hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $signature)) { // constant-time comparison
http_response_code(401); exit;
}
$event = json_decode($body, true);
// De-duplicate on $event['id'] here, then handle $event['type'].
http_response_code(200);
Node.js
// Express. The raw body is needed, so do not put express.json() in front of this route.
import crypto from 'node:crypto';
import express from 'express';
const SECRET = process.env.LIQAOS_WEBHOOK_SECRET; // whsec_...
const app = express();
app.post('/hooks/liqaos', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.get('LiqaOS-Signature') || '';
const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header);
if (!match) return res.sendStatus(400);
const [, timestamp, signature] = match;
// Replay protection: 5 minutes.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(400);
const expected = crypto
.createHmac('sha256', SECRET)
.update(`${timestamp}.`)
.update(req.body) // a Buffer: the bytes exactly as received
.digest('hex');
const ok =
expected.length === signature.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
if (!ok) return res.sendStatus(401);
const event = JSON.parse(req.body.toString('utf8'));
// De-duplicate on event.id here, then handle event.type.
res.sendStatus(200);
});
app.listen(3000);
Python
# Flask. request.get_data() returns the body exactly as received.
import hashlib, hmac, os, re, time
from flask import Flask, request, abort
SECRET = os.environ["LIQAOS_WEBHOOK_SECRET"] # whsec_...
app = Flask(__name__)
@app.post("/hooks/liqaos")
def liqaos_webhook():
body = request.get_data()
match = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", request.headers.get("LiqaOS-Signature", ""))
if not match:
abort(400)
timestamp, signature = match.groups()
if abs(time.time() - int(timestamp)) > 300: # replay protection: 5 minutes
abort(400)
expected = hmac.new(SECRET.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, signature): # constant-time comparison
abort(401)
event = request.get_json(force=True)
# De-duplicate on event["id"] here, then handle event["type"].
return "", 200
الأخطاء والحدود
لكل خطأ الشكل {"code": "...", "message": "..."}؛ وتضيف أخطاء التحقق الحقل errors.
{
"code": "validation_failed",
"message": "The title field is required.",
"errors": {
"title": ["The title field is required."]
}
}
| الحالة | code | متى |
|---|---|---|
| 401 | unauthenticated | مفتاح مفقود أو خاطئ أو موقوف. |
| 404 | not_found | الغرفة غير موجودة أو لعميل آخر؛ أو المسار غير موجود. |
| 405 | method_not_allowed | المسار موجود لكن ليس بهذه الطريقة. |
| 402 | subscription_inactive | إنشاء غرفة أو إضافة مشارك والاشتراك موقوف أو ملغى أو منتهٍ أو غير موجود، أو متأخر السداد بعد مهلة السماح. يحمل الجسم الحقل status. انظر الخطط والحدود. |
| 402 | quota_exceeded | إنشاء غرفة أو إضافة مشارك جديد بعد أن استنفدت خطة تتوقف عند مخصصها دقائق المشاركين لهذا الشهر. يحمل الجسم included_minutes وused_minutes وresets_at. |
| 409 | room_ended | تعديل غرفة أُنهيت أو إضافة مشارك إليها. |
| 409 | room_full | ليس نداءً من عندك: هو ما يصيب محاولة مضيف، داخل الغرفة، أن يُدخل شخصًا ينتظر ولا مقعد شاغرًا. وتبيّن له قائمة الانتظار السبب. |
| 409 | room_closed | إضافة مشارك بعد closes_at. |
| 422 | validation_failed | حقل ناقص أو خاطئ؛ يسرد errors كل حقل. |
| 422 | external_id_taken | غرفة أخرى لديك تستخدم هذا external_id (في التعديل فقط). |
| 429 | rate_limited | طلبات كثيرة. انظر أدناه. |
| 429 | concurrent_rooms_limit | إنشاء غرفة وعدد الغرف الحيّة قد بلغ ما تسمح به الخطة. يحمل الجسم limit. لا تخلطه بـ rate_limited: اعتمد على code. |
الفشل من جهة الخادم يجيب بحالة 5xx؛ أعد المحاولة مع تأخير متصاعد. إنشاء غرفة أو مشارك آمن للإعادة لأن كليهما مفتاحه external_id.
حدّ الطلبات
يحق لكل مفتاح 120 طلبًا في الدقيقة على كل مسارات /api/v1. وما زاد عن ذلك يجيب 429 مع ترويسة Retry-After (بالثواني) والرقم نفسه في retry_after داخل الجسم. الطلبات المرفوضة لمفتاح خاطئ لا تُحسب على مفتاح أحد.
{
"code": "rate_limited",
"message": "Too many requests.",
"retry_after": 23
}
الخطط والحدود
لكل حساب اشتراك في خطة يختارها المشغّل. تُنسخ شروطه عند بدئه، فلا يغيّر تعديلٌ لاحق على الخطة ما بيع لك من قبل. وللأسعار انظر قسم الأسعار في الصفحة الرئيسية. تسري ثلاثة حدود، ويجوز أن يكون أيٌّ منها بلا حد في خطتك، وللمشغّل أن يضبط لحسابك قيمة مختلفة.
| الحد | معناه | عند بلوغه |
|---|---|---|
| دقائق المشاركين في الشهر | مجموع الوقت الذي يقضيه الأشخاص متصلين. الخطة إما تتوقف عند مخصصها، أو لها سعر للزيادة: فتُحاسَب الدقائق الزائدة ولا تُرفض أبدًا. | 402 quota_exceeded عند إنشاء غرفة وعند إضافة مشارك جديد. |
| الاجتماعات في الوقت نفسه | الغرف التي فيها أشخاص الآن. لا تُحسب الغرفة المجدولة ولا المنتهية. | 429 concurrent_rooms_limit عند إنشاء غرفة. ويُفحص الحد ثانية حين يصل أول شخص إلى غرفة لم تصبح حيّة بعد: فإن ملأت غرف حيّة أخرى ما تسمح به الخطة رُفض دخوله بالرمز نفسه، ويحاول من جديد بعد أن تنتهي إحداها. أما الغرفة الحيّة فلا تُرفض أبدًا. |
| الأشخاص في الاجتماع الواحد | تقبل الغرفة الأصغر بين max_participants الخاص بها وحد الخطة. المضيفون يُقبلون دائمًا. | يحصل القادم على الحالة full وتعرضها صفحة الغرفة؛ ومن يحاول من المضيفين إدخال شخص ينتظر يتلقى room_full داخل الغرفة. |
HTTP 402
{ "code": "subscription_inactive", "message": "The subscription is not active.", "status": "past_due" }
HTTP 402
{ "code": "quota_exceeded", "message": "The monthly participant-minutes of the plan are used up.",
"included_minutes": 1000, "used_minutes": 1000, "resets_at": "2026-12-01T00:00:00Z" }
HTTP 429
{ "code": "concurrent_rooms_limit", "message": "The plan allows only 2 rooms at the same time.", "limit": 2 }
- الاشتراك. إنشاء غرفة أو إضافة مشارك يحتاج إلى اشتراك صالح: تجريبي أو فعّال، أو متأخر السداد ضمن مهلة سماح (7 أيام بعد أول تاريخ استحقاق لم يُسدَّد). وإلا فالجواب
402 subscription_inactiveمعstatusيساويsuspendedأوcancelledأوexpiredأوpast_dueأوnone(لا اشتراك أصلًا). - لا يُقطع شيء جارٍ. لا تُجرى الفحوص إلا حيث يبدأ شيء جديد: غرفة أو مشارك أو مقعد. فالرابط الذي صدر من قبل يظل يُفتح، ومن هو داخل الغرفة يبقى فيها حتى بعد بلوغ حد.
- إعادة إصدار الرابط لا تُحسب. استدعاء إضافة مشارك ثانية لـ
external_idموجود في الغرفة ليس شخصًا جديدًا. واستدعاء إنشاء غرفة ثانية بـexternal_idمعروف يعيد الغرفة الموجودة ولا يُحسب كذلك. وكلاهما يحتاج إلى اشتراك صالح. - كيف تُحسب دقائق المشاركين. كل اتصال لشخص فترة واحدة من دخوله إلى خروجه (والمفتوحة تمتد إلى اللحظة). تُجمع فترات كل غرفك داخل الشهر بالثواني، ثم يُقرَّب المجموع إلى دقائق كاملة مرة واحدة إلى الأعلى، فمن يدخل أربع مرات لا تُحسب عليه أربع دقائق مقرّبة. والشهر هو الشهر الميلادي محسوبًا من يوم بدء الاشتراك. ويعرض
GET /rooms/{room}/usageدقائق غرفة واحدة بمنزلتين عشريتين. - حجب الحساب أمر مختلف. إن حجب المشغّل الحساب نفسه أجاب مفتاحك
401كأي مفتاح مجهول.
الحدود في لمحة
| البند | الحد |
|---|---|
| الطلبات لكل مفتاح | 120 في الدقيقة |
| الأشخاص في الغرفة | max_participants من 1 إلى 1000، الافتراضي 50، ولا يزيد على حد الخطة (المضيفون يُسمح لهم دائمًا) |
| الدقائق، والغرف الحيّة معًا | بحسب الخطة: انظر الخطط والحدود |
| أصول خاصة بالغرفة | 10 لـ embed_origins و10 لـ content_origins |
| صلاحية رابط الانضمام | حتى closes_at، أو 24 ساعة |
| جلسة المتصفح / تذكرة الوسائط | ساعتان لكل منهما، وتجددهما صفحة الغرفة |
| مهلة جواب الإشعار | 10 ثوانٍ |
قائمة الأمان
- يبقى مفتاح الواجهة وسرّ الإشعارات على خادمك في مخزن أسرار، بعيدًا عن المستودعات والسجلات. يُعرضان مرة واحدة.
- استدعِ الواجهة من خادمك فقط. لا تستدعها من متصفح ولا من تطبيق.
- الرابط
join_urlبمثابة بيانات اعتماد لشخص واحد. أعطه لذلك الشخص وحده، ولا تسجّله، ولا تضعه في مكان يقرؤه غيره. من يحمله يستطيع الدخول باسم ذلك الشخص ما دام صالحًا. - أصدر الروابط حين يوشك الشخص على الانضمام لا قبلها بأسابيع. إعادة الإصدار رخيصة وتُبطل الرابط القديم.
- امنح أضيق دور يكفي:
observerلمن يشاهد فقط. - أبقِ
embed_originsقصيرة ما استطعت: أصول دقيقة وبـhttpsفقط. ولا تدرج أصلًا لا تتحكم به. - تحقّق من توقيع كل إشعار، وافحص الطابع الزمني، وامنع التكرار بالمعرّف
id، واستخدمwebhook_urlبـ HTTPS. أجب بسرعة وأنجز العمل بعد ذلك. - في شيفرة
postMessageتحقّق منevent.originوevent.source، ولا ترسل بـ*أبدًا. - هيّئ صفحات محتواك لتُعرض على كثيرين: عناوين خاصة بكل شخص، ولا أسرار في العنوان المشترك.
- تُرسل صفحة الانضمام مع
Referrer-Policy: no-referrerوCache-Control: no-storeلأن الرابط يحمل الرمز.
أسئلة شائعة
تظهر الغرفة إطارًا فارغًا
رفض المتصفح عرض الصفحة في الإطار. افحص بهذا الترتيب: (١) أصل الصفحة التي فيها iframe، كما في شريط العنوان تمامًا (النظام والمضيف والمنفذ)، موجود في embed_origins الحساب أو embed_origins الغرفة؛ (٢) سياسة Content-Security-Policy في صفحتك تسمح بـ frame-src https://liqaos.academito.online؛ (٣) الرابط هو join_url كاملًا. تُسمّي لك وحدة تحكم المتصفح التوجيه الذي منع العرض. والرابط الذي لا يعرفه LiqaOS لا يقبل التضمين إلا في LiqaOS نفسه، فالرمز الخاطئ يبدو فارغًا أيضًا.
تُرفض الكاميرا أو الميكروفون
- في الـ iframe الخاصية
allowمن تضمين الغرفة. - إن كانت صفحتك ترسل
Permissions-Policyفهي تسمّيhttps://liqaos.academito.onlineفيcameraوmicrophone. - صفحتك على HTTPS.
- لم يحجب الشخص الكاميرا لموقعك في المتصفح، ولا يستخدم الجهاز برنامج آخر.
- المراقبون بلا كاميرا ولا ميكروفون بالتصميم.
انتهت صلاحية رابط الانضمام
الرابط صالح حتى closes_at الغرفة (أو 24 ساعة من إصداره إن لم يكن للغرفة إغلاق). استدعِ إضافة مشارك ثانية بالـ external_id نفسه للحصول على رابط جديد. وإن كانت الغرفة نفسها قد أُغلقت أو أُنهيت رأى الشخص ذلك، وتحتاج إلى غرفة جديدة (أو إلى PATCH بـ closes_at أبعد إن كان الوقت قد مرّ فقط دون إنهاء).
ينتظر الشخص ولا يُدخله أحد
مع غرفة الانتظار يجب أن يقبله مضيف من داخل الغرفة، فلا بد من حضور مضيف. أضف المضيف بالدور host، أو أنشئ الغرفة بـ waiting_room: false.
تقول الغرفة إنها لم تُفتح
الوقت الحالي قبل opens_at. تنتظر الصفحة وتدخل بنفسها حين تُفتح الغرفة.
تقول الغرفة إنها ممتلئة
بلغ عدد المتصلين، أو من قُبلوا في آخر 10 دقائق، الأصغر بين max_participants الغرفة وحد الخطة للأشخاص في الاجتماع الواحد. ارفع max_participants بـ PATCH، أو اسأل المشغّل عن الخطة. لا يُرد المضيفون أبدًا. ويُبلَّغ المضيف الذي يحاول إدخال شخص ينتظر ولا مقعد شاغرًا بأن الاجتماع ممتلئ.
أتلقى 402 subscription_inactive
لا يستطيع اشتراكك أن يبدأ شيئًا جديدًا. اقرأ status: القيمة past_due تعني أن فاتورة متأخرة بعد مهلة السماح؛ وsuspended وcancelled وexpired تعني أن الاشتراك أُوقف أو انتهى؛ وnone تعني أنه لا اشتراك للحساب. تواصل مع المشغّل. أما الغرف والروابط التي عندك فتظل تعمل.
أتلقى 402 quota_exceeded
خطتك تتوقف عند دقائق المشاركين الشهرية وقد استُنفدت. يبيّن الجواب كم كان المخصص وكم استُهلك، وresets_at هو موعد بدء المخصص من جديد. اطلب من المشغّل خطة بدقائق أكثر أو خطة تحاسب على الزيادة. ولا يُخرَج من هم داخل الغرف.
أتلقى 429 concurrent_rooms_limit
بلغ عدد الغرف التي فيها أشخاص الآن ما تسمح به خطتك. أنشئ الغرفة لاحقًا أو اسأل المشغّل عن الخطة. والغرفة الحيّة فعلًا لا تُرفض أبدًا.
أتلقى 429 rate_limited
تجاوزت 120 طلبًا في الدقيقة لهذا المفتاح. انتظر عدد الثواني في Retry-After. ولا تستطلع GET /rooms/{room}/participants لمعرفة الحضور؛ استخدم الإشعارات.
لا تصل الإشعارات
تأكد أن لحسابك webhook_url (اسأل المشغّل)، وأنه يجيب 2xx دون إعادة توجيه وخلال 10 ثوانٍ، وأن جدار الحماية عندك يسمح بوصول LiqaOS. تُعاد المحاولة للإشعار الفاشل بعد 1 و5 و30 دقيقة ثم يُترك. وإن بدأ الفشل بعد أن دوّر المشغّل سرّ الإشعارات فحدّث السرّ في شيفرة التحقق عندك.
ضاع مفتاح الواجهة أو سرّ الإشعارات
لا يمكن عرضهما ثانية. اطلب من المشغّل مفتاحًا جديدًا (وإلغاء الضائع)، أو تدوير سرّ الإشعارات؛ وتُعرض القيمة الجديدة مرة واحدة.
يفشل فحص التوقيع دائمًا
السبب في الغالب هو الجسم: وقّع البايتات الخام كما وصلت لا JSON أُعيد ترميزه، وتأكد أن أي وسيط لم يحللها أو يقصّها. النص الموقّع هو t + "." + body.
لا تصل صفحتي رسائل الغرفة
قارن الأصل بالضبط: يجب أن يساوي event.origin القيمة https://liqaos.academito.online. استمع قبل أن يُحمَّل الإطار، وتحقق أن event.source هو نافذة الإطار.
تُهمل الغرفة رسائل liqaos:* التي أرسلها
استخدم أصل LiqaOS بالضبط في targetOrigin، وتأكد أن أصل صفحتك أحد embed_origins الغرفة. والرسالتان share-content وstop-content تعملان في غرفة مضيف فقط، ويجب أن يكون العنوان ضمن content_origins.
غير متاح في الإصدار 1
- التسجيل بأي شكل. لا تُخزَّن الوسائط.
- قبول الأشخاص أو رفضهم أو كتمهم عبر الواجهة؛ يفعل المضيفون ذلك داخل الغرفة.
- سرد الغرف أو حذفها، وسرد غرفك.
- إصدار مفاتيح الواجهة أو تدويرها أو إلغاؤها، وتدوير سرّ الإشعارات، وتغيير عنوان الإشعارات أو أصول الحساب أو الخطة عبر الواجهة؛ يتولى المشغّل ذلك عند الطلب.
- إعادة إرسال إشعار تُرك بعد فشل محاولاته.
- تقسيم القوائم إلى صفحات.