محفل آنلاین

مستندات API محفل آنلاین

وب‌سرویس REST برای ساخت اتاق و رویداد، صدور لینک ورود مستقیم، گزارش حضور، فهرست ضبط‌ها و دریافت رویدادها با وب‌هوک — نسخهٔ v1.

احراز هویت اتاق‌ها و رویدادها حضور ضبط‌ها لینک ورود وب‌هوک خطاها

شروع و احراز هویت

همهٔ درخواست‌ها به آدرس پایهٔ https://mahfel-online.ir/api/v1 فرستاده می‌شوند و با کلید API احراز هویت می‌شوند. کلید را مدیر سامانه در صفحهٔ «توسعه‌دهندگان» صادر می‌کند. کلید را در یکی از دو هدر زیر بفرستید:

X-Api-Key: YOUR_API_KEY

# یا
Authorization: Bearer YOUR_API_KEY

نمونهٔ فراخوان با curl:

curl -H "X-Api-Key: YOUR_API_KEY" \
     https://mahfel-online.ir/api/v1/ping

محدودیت نرخ: هر کلید حداکثر ۱۲۰ درخواست در دقیقه می‌تواند بفرستد؛ بیشتر از آن پاسخ ۴۰۱ می‌گیرید. کلید را فقط سمت سرور نگه دارید و هرگز در کد کلاینت/مرورگر قرار ندهید.

قالب پاسخ

پاسخ موفق JSON است و معمولاً فیلد ok: true دارد. در خطا، وضعیت HTTP مناسب با این بدنه برمی‌گردد:

{ "ok": false, "error": { "code": "unauthorized", "message": "..." } }

اتاق‌ها و رویدادها

GET/api/v1/ping

بررسی اعتبار کلید و سلامت سرویس.

{ "ok": true, "key": { "name": "my-app", "prefix": "mk_a1b2" }, "now": "..." }

POST/api/v1/rooms

ساخت رویداد و اتاق در یک فراخوان؛ لینک ورود سخنران هم در پاسخ می‌آید.

بدنهٔ درخواست

فیلد	نوع	توضیح
`title`	string *	عنوان رویداد (الزامی)
`description`	string	توضیح رویداد
`slug`	string	اسلاگ صفحهٔ ثبت‌نام `/e/{slug}`
`roomCode`	string	کد اتاق دلخواه (حروف/عدد/ـ/_)
`startsAt` / `endsAt`	datetime	زمان شروع/پایان (پیش‌فرض: الان تا ۲ ساعت بعد)
`capacity`	int	ظرفیت ثبت‌نام (۰ = نامحدود)
`admissionMinutes`	int	بازهٔ پذیرش قبل از شروع — دقیقه (۰ تا ۱۲۰، پیش‌فرض ۳۰)
`presenterName`	string	نام سخنران برای لینک ورود

POST /api/v1/rooms
{ "title": "وبینار معرفی محصول", "startsAt": "2026-10-20T18:00:00",
  "endsAt": "2026-10-20T20:00:00", "capacity": 200 }

{ "ok": true, "room": "r-abc123", "eventId": "...", "slug": "...",
  "registrationUrl": "https://mahfel-online.ir/e/...",
  "presenterJoinUrl": "https://mahfel-online.ir/room/...?jt=...",
  "startsAt": "...", "endsAt": "..." }

GET/api/v1/rooms

فهرست همهٔ اتاق‌ها/رویدادها؛ برای اتاق‌های زنده، تعداد شرکت‌کنندگان هم می‌آید (live).

GET/api/v1/rooms/{room}

جزئیات یک اتاق: اطلاعات رویداد متصل و فهرست شرکت‌کنندگان زنده.

DELETE/api/v1/rooms/{room}

پایان فوری جلسهٔ زنده (معادل end در سرویس‌های مشابه) و ارسال وب‌هوک room.ended.

GET/api/v1/rooms/{room}/participants

شرکت‌کنندگانِ زندهٔ اتاق با نام و زمان ورود.

گزارش حضور

GET/api/v1/rooms/{room}/attendance

گزارش حضور همهٔ نشست‌ها: زمان ورود/خروج، مدت حضور، تعداد پیام چت و دست بالا.

{ "ok": true, "room": "r-abc123", "attendance": [
  { "identity": "u-42", "name": "...", "role": "participant",
    "joinedAt": "...", "leftAt": "...", "minutes": 58,
    "chatMessages": 3, "raiseHands": 1 } ] }

ضبط‌ها

GET/api/v1/recordings

فهرست همهٔ ضبط‌ها؛ با پارامتر ?room={room} فقط ضبط‌های یک اتاق.

GET/api/v1/rooms/{room}/recordings

فهرست ضبط‌های یک اتاق خاص. برای هر ضبط: id، title، recordedBy، createdAt، durationSeconds، sizeBytes، inProgress، views، allowDownload و shareUrl (لینک اشتراک عمومی /r/{shareId} اگر فعال شده باشد).

لینک ورود مستقیم

لینک‌های ورود امضاشده کاربر را بدون فرم و با نقش مشخص وارد اتاق می‌کنند. توکن با HMAC-SHA256 و راز اختصاصی هر کلید امضا می‌شود و تا انقضایش معتبر است.

POST/api/v1/rooms/{room}/access

صدور لینک ورود برای یک کاربر؛ اگر اتاق به رویداد وصل باشد و mobile معتبر بدهید، ثبت‌نام رویداد هم انجام می‌شود.

فیلد	نوع	توضیح
`name`	string *	نام کاربر (الزامی، حداقل ۲ نویسه)
`mobile`	string	موبایل — برای ثبت‌نام رویداد
`role`	string	presenter \| moderator \| speaker \| participant \| audience
`ttlMinutes`	int	اعتبار لینک — دقیقه (۵ تا ۴۳۲۰۰، پیش‌فرض ۱۴۴۰)
`ticketId` / `discountCode`	string	برای ثبت‌نام رویداد

{ "ok": true, "room": "r-abc123", "name": "...", "role": "participant",
  "joinUrl": "https://mahfel-online.ir/room/...?jt=...",
  "expiresAt": "...", "registered": true, "registrationId": "..." }

POST/api/v1/join-links

صدور لینک ورود بدون ثبت‌نام — فقط room، name و اختیاری role و ttlMinutes.

وب‌هوک

با ثبت یک آدرس HTTPS، رویدادهای سامانه به‌صورت POST به شما می‌رسند.

GET/api/v1/webhooks

فهرست اشتراک‌ها + knownEvents (رویدادهای موجود).

POST/api/v1/webhooks

ساخت اشتراک: { "url": "https://…", "events": ["room.ended"] } — اگر events خالی باشد همهٔ رویدادها ارسال می‌شوند. در پاسخ secret اشتراک برمی‌گردد؛ آن را نگه دارید.

DELETE/api/v1/webhooks/{id} POST/api/v1/webhooks/{id}/test

حذف اشتراک و ارسال رویداد آزمایشی.

رویدادها

participant.joined · participant.left · event.created · event.registration · join_link.created · room.ended

امضای تحویل

بدنهٔ هر تحویل پاکت JSON است و با دو هدر می‌آید: X-Mahfel-Event (نوع رویداد) و X-Mahfel-Signature به شکل sha256={hex} — مقدار آن HMAC-SHA256 بدنهٔ خام با secret اشتراک است:

// C#
var sig = Convert.ToHexString(
    HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), rawBody)).ToLower();
// مقایسه با مقدار بعد از "sha256=" در هدر X-Mahfel-Signature

// بدنهٔ نمونه
{ "id": "evt_...", "type": "event.registration",
  "created_at": 1760600400,
  "data": { "event": "...", "room": "...", "name": "...", "mobile": "..." } }

کدهای خطا

HTTP	code	علت
400	`bad_request`	فیلد الزامی ناقص یا نامعتبر
401	`unauthorized`	کلید نامعتبر/منقضی یا عبور از سقف نرخ
404	`not_found`	اتاق/وب‌هوک یافت نشد
502	`media_error`	خطای سرویس رسانهٔ زنده

برای صدور کلید API با مدیر سامانه تماس بگیرید و راهنمای کاربری سامانه را در مرکز راهنما ببینید.