LiqaOSوثائق المطوّرين English

وثائق واجهة 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
الحقلالنوعمطلوبالقواعد
titlestringنعمحتى 255 حرفًا.
external_idstring أو nullلاحتى 191 حرفًا. معرّفك أنت للغرفة، فريد لكل عميل. انظر أدناه.
opens_atISO-8601 أو nullلاقبل هذه اللحظة تجيب الغرفة not_open. انظر نافذة الغرفة.
closes_atISO-8601 أو nullلايجب أن تكون بعد opens_at إذا وُجدت الاثنتان. بعد هذه اللحظة تجيب الغرفة closed، وتنتهي عندها صلاحية الروابط.
waiting_roombooleanلاالافتراضي true.
whiteboardbooleanلاهل للغرفة سبورة (انظر السبورة). هذا مفتاح الغرفة نفسها ويبدأ true؛ وتعمل السبورة ما دامت ميزة السبورة مفعّلة لحسابك أيضًا (يستطيع المشغّل تعطيلها لحسابك كله، بما فيه الغرف القائمة). وتعيد الغرفة الحقل features وفيه ما هو مفعّل الآن.
max_participantsintegerلامن 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قائمتا هذه الغرفة وحدها، لا قائمتا حسابك.
statusscheduled قبل 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_idstringنعمحتى 191 حرفًا. معرّفك لهذا الشخص. شخص واحد لكل external_id في الغرفة.
namestringنعمحتى 255 حرفًا. يراه الآخرون في الغرفة.
rolestringنعمhost أو participant أو observer.
avatar_urlURL أو nullلاعنوان صحيح حتى 2048 حرفًا.

الاستجابة: 201 في المرة الأولى، و200 إن كان external_id موجودًا في الغرفة.

الحقلالمعنى
participant_idمعرّف الشخص عند LiqaOS في هذه الغرفة.
join_urlhttps://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:statestatewaiting (طلب الدخول)، admitted (سُمح له ويتصل)، in_room (متصل)، left (غادر الشخص)، ended (انتهت الغرفة أو أُغلقت).
liqaos:participantevent وname وrole وexternal_idالقيمة event هي joined أو left حين يتصل شخص آخر بالغرفة أو يغادرها والشخص فيها؛ وwaiting حين يطلب أحدهم الدخول (تُرسل إلى صفحة المضيف وحدها، والدور فيها participant).
liqaos:contentkey وurlشارك مضيف محتوى (انظر محتواك على مسرح الغرفة). يمكنك الرد بـ liqaos:content-url.
liqaos:content-stoppedkeyلم يعد المحتوى الذي يحمل هذا key على المسرح، أيًّا كان السبب: أوقفه المضيف بنفسه، أو أرسلت صفحتك liqaos:stop-content، أو حلّ محتوى آخر محلّه، أو غادر من شاركه، أو انتهت الغرفة، أو غادر هذا الشخص. تابع الحالة الفعلية من هذه الرسالة بدل ما أرسلته صفحتك آخر مرة.
liqaos:boardopen (boolean)فُتحت السبورة أو أُغلقت في هذه الغرفة (على يد مضيف، أو بالرسالتين liqaos:board-open وliqaos:board-close). انظر السبورة.

الرسائل: من صفحتك إلى الغرفة

الرسالةالحقولالأثر
liqaos:share-contentkey وurl وtitle وcontrols اختياريًا (قيمة منطقية)للمضيف فقط. تعرض url على مسرح الغرفة للجميع. تُهمل إذا لم يكن الشخص مضيفًا. بالقيمة controls: false تعلن صفحتك أنها تدير المحتوى بنفسها (زر إيقاف خاص بها)، فلا ترسم الغرفة عنصر «إيقاف المشاركة» الخاص بها على مسرح المضيف؛ وبدونها ترسمه الغرفة.
liqaos:content-urlkey وurlرد على liqaos:content: عنوان هذا الشخص الخاص للمحتوى نفسه.
liqaos:stop-contentلا شيءللمضيف فقط. تزيل المحتوى من مسرح الغرفة.
liqaos:leaveلا شيءيغادر الشخص الغرفة.
liqaos:compacton (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' }); }

محتواك على مسرح الغرفة

يستطيع المضيف أن يعرض إحدى صفحاتك على مسرح الغرفة للجميع بجوار الأشخاص. لا تجلب الغرفة الصفحة بنفسها: يحمّلها متصفح كل شخص داخل إطار.

  1. ترسل صفحتك (التي تضمّن الغرفة) liqaos:share-content ومعها key يعرّف هذا المحتوى وurl وtitle. لا تعمل بها إلا غرفة مضيف.
  2. يجب أن يكون العنوان http أو https وأن يكون أصله أحد content_origins (حسابك مع الغرفة). غير ذلك يُرفض ويرى الشخص تنبيهًا.
  3. ترسل غرفة المضيف المحتوى إلى بقية من في الغرفة عبر اتصال الوسائط. ومن يصل متأخرًا يستلمه أيضًا.
  4. قبل العرض ترسل غرفة كل شخص liqaos:content إلى صفحتها الأم هي. فإن ردّت صفحتك بـ liqaos:content-url (بالـ key نفسه) خلال 1.5 ثانية عرضت الغرفة ذلك العنوان بدل المشترك. بهذا يحصل كل مشاهد على رابط خاص به، كعنوان فيه رمزه الشخصي. ويجب أن يكون الرد أيضًا ضمن content_origins وإلا أُهمل واستُخدم العنوان المشترك.
  5. الرسالة 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المعنى
403board_disabledلا سبورة لهذه الغرفة.
409room_endedانتهت الغرفة أو أُغلقت. وسبورتها مغلقة كذلك، للقراءة أيضًا.
403not_admittedلم يُسمح للشخص بدخول الغرفة.
403host_onlyهذا الإجراء للمضيف وحده.
403board_read_onlyلا يحق للشخص الرسم.
422board_items_limit وboard_pages_limit وboard_file_too_big وboard_room_full60 عنصرًا، أو 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.
roomid و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

الخوارزمية:

  1. قسّم الترويسة عند الفواصل إلى t (وقت يونكس بالثواني) وv1 (64 خانة سداسية عشرية).
  2. كوّن النص t + "." + body حيث body هو جسم الطلب الخام كما وصل تمامًا (لا JSON أُعيد ترميزه).
  3. احسب HMAC-SHA256 لذلك النص بمفتاح هو سرّ الإشعارات (whsec_…) وأخرجه بأحرف سداسية عشرية صغيرة.
  4. قارنه بـ v1 بمقارنة زمنها ثابت.
  5. ارفض الطلب إذا بعد 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متى
401unauthenticatedمفتاح مفقود أو خاطئ أو موقوف.
404not_foundالغرفة غير موجودة أو لعميل آخر؛ أو المسار غير موجود.
405method_not_allowedالمسار موجود لكن ليس بهذه الطريقة.
402subscription_inactiveإنشاء غرفة أو إضافة مشارك والاشتراك موقوف أو ملغى أو منتهٍ أو غير موجود، أو متأخر السداد بعد مهلة السماح. يحمل الجسم الحقل status. انظر الخطط والحدود.
402quota_exceededإنشاء غرفة أو إضافة مشارك جديد بعد أن استنفدت خطة تتوقف عند مخصصها دقائق المشاركين لهذا الشهر. يحمل الجسم included_minutes وused_minutes وresets_at.
409room_endedتعديل غرفة أُنهيت أو إضافة مشارك إليها.
409room_fullليس نداءً من عندك: هو ما يصيب محاولة مضيف، داخل الغرفة، أن يُدخل شخصًا ينتظر ولا مقعد شاغرًا. وتبيّن له قائمة الانتظار السبب.
409room_closedإضافة مشارك بعد closes_at.
422validation_failedحقل ناقص أو خاطئ؛ يسرد errors كل حقل.
422external_id_takenغرفة أخرى لديك تستخدم هذا external_id (في التعديل فقط).
429rate_limitedطلبات كثيرة. انظر أدناه.
429concurrent_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

  • التسجيل بأي شكل. لا تُخزَّن الوسائط.
  • قبول الأشخاص أو رفضهم أو كتمهم عبر الواجهة؛ يفعل المضيفون ذلك داخل الغرفة.
  • سرد الغرف أو حذفها، وسرد غرفك.
  • إصدار مفاتيح الواجهة أو تدويرها أو إلغاؤها، وتدوير سرّ الإشعارات، وتغيير عنوان الإشعارات أو أصول الحساب أو الخطة عبر الواجهة؛ يتولى المشغّل ذلك عند الطلب.
  • إعادة إرسال إشعار تُرك بعد فشل محاولاته.
  • تقسيم القوائم إلى صفحات.