یک صفحهٔ کنترل کوچک، دو سطح: API عمومیِ باز برای اتاق‌های لینک‌محور و API اجاره‌ای برای محصولاتی که اتاق‌ها مال خودشان است. JSON ورودی، JSON خروجی. قرارداد ماشین‌خوانِ زنده هم توسط خودِ API در /api/v1/openapi.yaml سرو می‌شود. همهٔ خروجی‌های این صفحه روی تولید تست شده‌اند.
https://api.videorayan.ir/v1/api/v1/*wss://rtc.videorayan.irhttps://videorayan.ir/r/{roomId}Content-Type: application/json؛ فیلدهای ناشناخته رد می‌شوند.Authorization: Bearer <key> می‌خواهند (کلیدها شبیه rtck_…اند).429.404 (ضد-کاوش)./api/v1/… را استفاده کنید — روی هر هاستِ *.videorayan.ir این مسیر به API پروکسی می‌شود؛ بدون CORS و بدون preflight.نام اتاق دستگیرهٔ عمومی آن است: ساخت دوباره با نام موجود، همان اتاق را برمی‌گرداند — برای لینک‌های همیشگی مثل community عالی است. خروجی‌های زیر عیناً از تولید است (۲۰۲۶-۱۰-۲۷).
/v1/public/rooms 201 Createdاتاق مرورگریِ رایگان بسازید؛ اگر نام وجود داشته باشد همان اتاق برمی‌گردد (idempotent). محدودیت نرخ به‌ازای هر IP اعمال می‌شود.
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
name | string | بله | ۱ تا ۶۴ نویسه؛ دستگیرهٔ عمومی اتاق. ساخت با نام موجود ← همان اتاق. |
password | string | خیر | ۱ تا ۶۴ نویسه؛ اگر ست شود، مهمان‌ها باید برای ورود ارائه‌اش کنند (بررسی سمت سرور). |
curl -s -X POST https://api.videorayan.ir/v1/public/rooms \ -H "Content-Type: application/json" -d '{"name":"community"}' {"roomId":"4843ba3a-e800-475a-b78c-7ae60c9d33d7","name":"community"}
خطاها: 400 اعتبارسنجی ({"error":"invalid_input"}) · 429 محدودیت نرخ
/v1/public/rooms/{ref} 200 OKقبل از ورود، اتاق را با UUID یا نام resolve کنید تا roomId رسمی، نام نمایشی و اینکه رمز لازم دارد یا نه را بدانید — دقیقاً کاری که صفحهٔ پیوستن می‌کند.
curl -s https://api.videorayan.ir/v1/public/rooms/community
{"roomId":"4843ba3a-e800-475a-b78c-7ae60c9d33d7","name":"community","needsPassword":false}
خطاها: 404 {"error":"room_not_found"} — مرجع ناشناخته یا منقضی‌شده.
/v1/guest/rooms/{ref}/tokens 201 Created{ref} می‌تواند UUID اتاق یا نام اتاق عمومی باشد. سقف شرکت‌کنندگان و انقضای اتاق سمت سرور اعمال می‌شود و هر صدور ثبت حسابرسی می‌شود. انسان‌ها با لینک https://videorayan.ir/r/{roomId} وارد می‌شوند.
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
identity | string | بله | ۱ تا ۴۰ نویسه؛ به بقیهٔ شرکت‌کنندگان نشان داده می‌شود و در اتاق باید یکتا باشد. |
password | string | اگر اتاق خصوصی است | ۱ تا ۶۴ نویسه؛ وقتی اتاق با رمز ساخته شده لازم است. |
curl -s -X POST https://api.videorayan.ir/v1/guest/rooms/community/tokens \ -H "Content-Type: application/json" -d '{"identity":"SaraDev"}' { "token": "eyJhbGciOiJIUzI1NiJ9.…", // LiveKit JWT, single-room scope "identity": "SaraDev", "roomName": "community", "expiresAt": "2026-10-27T14:03:34.433Z" // ~10 min TTL }
خطاها: 403 {"error":"wrong_password"} · 404 اتاق پیدا نشد · 409 اتاق پر یا پایان‌یافته · 429 محدودیت نرخ
هر اتاق متعلق به یک اجاره‌کننده است. با شناسهٔ همبستهٔ خودتان اتاق بسازید، توکن host/guest ضرب کنید، شرکت‌کنندگان زنده را ببینید و اتاق را سمت سرور پایان دهید. کلیدها (rtck_…) توسط اپراتور صادر می‌شوند و فقط در بک‌اند شما زندگی می‌کنند.
Authorization: Bearer rtck_live_9f2… # never ship this to a front-end
/v1/rooms 201 Createdهدر Idempotency-Key بفرستید (رشتهٔ یکتا، تا ۱۲۸ نویسه) — تلاش مجدد با همان کلید، به‌جای ساخت نسخهٔ تکراری، همان اتاق اصلی را برمی‌گرداند.
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
externalId | string ≤128 | خیر | مرجع خودتان (مثل appointment-123)؛ در هر پاسخ اتاق برمی‌گردد. |
maxParticipants | integer | خیر | پیش‌فرض ۳ (سقف فعلی سمت سرور). |
expiresInSeconds | integer | خیر | پیش‌فرض 7200 (۲ ساعت)؛ حداکثر تا ۲۴ ساعت (86400). بعد از انقضا، اتاق جمع می‌شود و توکن‌های کهنه کار نمی‌کنند. |
metadata | string ≤512 | خیر | حبابِ opaque برای دفترداری خودتان — کوچک نگهش دارید. |
{
"roomId": "b21b2f50-7a1d-4f6e-9c8f-3d2a1b4c5d6e",
"tenantId": "t_9a8b7c6d",
"externalId": "appointment-123",
"status": "active",
"maxParticipants": 3,
"createdAt": "2026-10-26T10:00:00.000Z",
"expiresAt": "2026-10-26T12:00:00.000Z"
}
خطاها: 401 کلید ناموجود/نامعتبر · 429 محدودیت نرخ
/v1/rooms/{roomId}/tokens 201 Createdاز بک‌اند، به‌ازای هر کاربر و درست قبل از ورودش صدایش بزنید. نقش host یا guest سمت سرور به دسترسی‌ها نگاشت می‌شود.
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
identity | string ≤128 | بله | یکتا در اتاق؛ به بقیه نشان داده می‌شود. |
name | string ≤128 | خیر | نام نمایشی خوانا برای انسان‌ها. |
role | host | guest | خیر | پیش‌فرض guest. |
ttlSeconds | integer | خیر | پیش‌فرض 600 (۱۰ دقیقه). توکن‌ها قابل تمدید نیستند — بعد از انقضا دوباره ضرب کنید. |
{
"token": "eyJhbGciOiJIUzI1NiJ9.…",
"wsUrl": "wss://rtc.videorayan.ir",
"identity": "host-1",
"expiresAt": "2026-10-27T14:07:29.974Z"
}
خطاها: 401 احراز هویت · 403 اتاق مال شما نیست · 404 اتاق ناشناخته · 409 اتاق پر یا پایان‌یافته
/v1/whoamiنام اجاره‌کنندهٔ پشت کلید شما را برمی‌گرداند (401 اگر نامعتبر باشد).
{"tenant":"acme"}
/v1/rooms/{id}/participantsهمهٔ کسانی که الان متصل‌اند (فقط اجاره‌کنندهٔ مالک). خطا: 403 اتاق مال شما نیست.
{"participants":[]}
/v1/rooms/{id}اتاق بسته می‌شود، همه قطع می‌شوند، توکن‌های جدید رد و ورود مجدد مسدود می‌شود. وضعیت: ended (یا expired توسط sweeper).
# empty body — the room is gone
بدنه‌های خطا قطعی‌اند و شکل‌های زیر عیناً از تولید ثبت شده‌اند. خطای اعتبارسنجی همیشه با کد 400 و برچسب invalid_input می‌آید.
| وضعیت | بدنهٔ واقعی | معنی | اقدام کلاینت |
|---|---|---|---|
400 | {"error":"invalid_input"} | اعتبارسنجی بدنه رد شد (طول فیلدها، فیلد ناشناخته) | بدنه را طبق مستندات اصلاح کنید |
401 | — | کلید اجاره‌ای ناموجود یا نامعتبر | هدر Authorization را بررسی و کلید را بچرخانید |
403 | {"error":"wrong_password"} | رمز اتاق اشتباه/ناموجود، یا اتاق مال شما نیست | رمز را دوباره بپرسید / مالکیت را بررسی کنید |
404 | {"error":"room_not_found"} | پیدا نشد — شامل کاوشِ بین‌اجاره‌ای (ضد-کاوش) | لینک را تازه کنید؛ کورکورانه retry نکنید |
409 | — | اتاق پر است یا پایان‌یافته/منقضی | «پر/تمام‌شده» را به کاربر نشان دهید |
429 | — | محدودیت نرخ (۱۲۰ در دقیقه به‌ازای هر IP یا کلید) | بک‌آف نمایی؛ به Retry-After احترام بگذارید |
پیش‌فرض حدود ۱۰ دقیقه (در پاسخ با expiresAt). مثل اعتبارنامه با آن رفتار کنید و به‌ازای هر جلسه تازه ضرب کنید.
اتاق‌های رایگان ۱۲ ساعت زنده می‌مانند؛ اتاق‌های اجاره‌ای تا ۲۴ ساعت. اتاق‌های منقضی هر ۶۰ ثانیه جمع‌آوری می‌شوند.
۱۲۰ درخواست در دقیقه به‌ازای هر IP (سطح عمومی) یا کلید. برای بودجهٔ بزرگ‌تر، درخواست منابع بدهید.
GET /v1/healthسرویس زنده است. بدون احراز هویت و بدون اطلاعات حساس — مانیتورهایتان را همین‌جا ببندید. پاسخ: {"status":"ok"}
GET /v1/openapi.yamlقرارداد زندهٔ OpenAPI 3.0، سرو‌شده توسط خودِ API کنترل. وارد Postman یا Insomnia کنید یا کلاینت تولید کنید.
openapi.json ایستانسخهٔ JSON ایستا که هر دو سطح عمومی و اجاره‌ای را پوشش می‌دهد: en.videorayan.ir/openapi.json
curl -fsS https://api.videorayan.ir/v1/health \ && curl -fsS https://videorayan.ir/api/v1/health \ && curl -fsS https://api.videorayan.ir/v1/openapi.yaml -o /dev/null -w "openapi: %{http_code}\n" # {"status":"ok"} {"status":"ok"} openapi: 200
/api/v1/* روی دامنهٔ اصلی است — روی *.videorayan.ir به API پروکسی می‌شود و مرورگرها اصلاً با CORS درگیر نمی‌شوند.اندپوینتی کم دارد یا پاسخی غافلگیرکننده دیدید؟ در اتاق اجتماعی زنده بگویید یا خط بازخورد را بنویسید — هر گزارش مستقیم به اپراتور می‌رسد و قرارداد را با هم بهتر می‌کنیم.
با API عمومیِ رایگان شروع کنید و وقتی مالکیت و نقش خواستید، به اتاق‌های اجاره‌ای برسید — کد کلاینت در هر دو یکی است.