32 KiB

Raw Blame History

📚 Plugnmeet Server API Documentation

مستندات کامل API سرور کنفرانس ویدیویی Plugnmeet

این مستند راهنمای کامل API های Plugnmeet Server را شامل می‌شود که بر پایه LiveKit ساخته شده است.

📖 فهرست مطالب

🚀 Quick Check: Room Status

ساده‌ترین روش برای بررسی فعال بودن یک روم:

Endpoint

POST /auth/room/isRoomActive

Request

{
  "roomId": "your-room-id"
}

Response

{
  "status": true,
  "msg": "room is active",
  "isActive": true
}

cURL Example

#!/bin/bash
API_KEY="your-api-key"
SECRET="your-secret-key"
BODY='{"roomId":"algebra-1402"}'

# محاسبه HMAC-SHA256
SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

# ارسال درخواست
curl -X POST 'https://your-domain.com/auth/room/isRoomActive' \
  -H "API-KEY: $API_KEY" \
  -H "HASH-SIGNATURE: $SIG" \
  -H 'Content-Type: application/json' \
  -d "$BODY"

⭐ Core Features

Plugnmeet Server مجموعه کاملی از قابلیت‌های حرفه‌ای برای برگزاری کنفرانس‌های آنلاین را فراهم می‌کند:

🎥 Video Conferencing

✅ HD Audio/Video با کیفیت بالا
✅ Screen Sharing - اشتراک‌گذاری صفحه
✅ Virtual Backgrounds - پس‌زمینه مجازی
✅ Adaptive Streaming (Simulcast & Dynacast)

📊 Collaboration Tools

✅ Interactive Whiteboard با پشتیبانی از فایل‌های PDF/Office
✅ Shared Notepad - یادداشت مشترک
✅ Live Polls - نظرسنجی زنده
✅ Breakout Rooms - اتاق‌های گروهی

🎬 Recording & Streaming

✅ Cloud Recording - ضبط ابری با فرمت MP4
✅ RTMP Streaming - پخش زنده
✅ Ingress Support (RTMP/WHIP)

🛡️ Security & Control

✅ Waiting Room - اتاق انتظار
✅ Lock Settings - قفل کردن قابلیت‌ها
✅ User Management - مدیریت کاربران
✅ End-to-End Encryption

📈 Analytics & Monitoring

✅ Session Analytics - آنالیتیکس جلسات
✅ Participant Reports - گزارش شرکت‌کنندگان
✅ Real-time Monitoring

♿ Accessibility

✅ Speech-to-Text - گفتار به متن
✅ Real-time Translation (Azure)

🔐 Authentication

Plugnmeet از سه روش احراز هویت مختلف استفاده می‌کند:

1. `/auth` Endpoints (HMAC + JSON)

برای عملیات مدیریتی و ساخت توکن‌ها استفاده می‌شود.

Headers

API-KEY: your_api_key
HASH-SIGNATURE: hmac_sha256_hex_signature
Content-Type: application/json

محاسبه HMAC Signature

Bash/Shell:

SECRET="your-secret-key"
BODY='{"roomId":"test-room"}'
SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

Python:

import hmac
import hashlib
import json

secret = "your-secret-key"
body = {"roomId": "test-room"}
body_json = json.dumps(body)

signature = hmac.new(
    secret.encode('utf-8'),
    body_json.encode('utf-8'),
    hashlib.sha256
).hexdigest()

Node.js:

const crypto = require('crypto');

const secret = 'your-secret-key';
const body = JSON.stringify({ roomId: 'test-room' });

const signature = crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex');

2. `/api` Endpoints (Bearer Token + Protobuf)

برای کنترل‌های داخل جلسه استفاده می‌شود.

Headers

Authorization: <PNM_ACCESS_TOKEN>
Content-Type: application/octet-stream

توکن دسترسی از طریق /auth/room/getJoinToken دریافت می‌شود.

Request/Response Format

بدنه درخواست: Binary Protobuf (استفاده از SDK توصیه می‌شود)
پاسخ: Binary Protobuf

cURL Example با Protobuf

# ساخت فایل باینری با SDK
# سپس ارسال با curl
curl -X POST 'https://your-domain.com/api/recording' \
  -H "Authorization: $TOKEN" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @recording_req.bin \
  -o response.bin

نکته: برخی endpoint های /api مانند convertWhiteboardFile و fileUpload از JSON استفاده می‌کنند.

3. Special Authentication Methods

LTI (Learning Tools Interoperability)

Authorization: <LTI_TOKEN>

مسیرها: /lti/v1/...

BigBlueButton Compatibility

نیازمند checksum محاسبه شده مطابق استاندارد BBB مسیرها: /:apiKey/bigbluebutton/api/...

📋 Room Management API

🏗️ Create Room

اتاق جلسه جدید ایجاد می‌کند.

Endpoint

POST /auth/room/create

Request Body

{
  "roomId": "algebra-class-1402",
  "maxParticipants": 50,
  "emptyTimeout": 300,
  "metadata": {
    "roomTitle": "کلاس جبر خطی",
    "welcomeMessage": "به کلاس جبر خوش آمدید",
    "defaultLockSettings": {
      "lockMicrophone": false,
      "lockWebcam": false,
      "lockScreenSharing": true,
      "lockChat": false,
      "lockChatSendMessage": false,
      "lockChatFileShare": false,
      "lockPrivateChat": false,
      "lockWhiteboard": true,
      "lockSharedNotepad": false
    },
    "roomFeatures": {
      "allowWebcams": true,
      "muteOnStart": false,
      "allowScreenSharing": true,
      "allowRecording": true,
      "allowRtmp": true,
      "allowViewOtherWebcams": true,
      "allowViewOtherParticipantsList": true,
      "adminOnlyWebcams": false,
      "allowPolls": true,
      "roomDuration": 0,
      "recordingFeatures": {
        "isAllow": true,
        "isAllowCloud": true,
        "enableAutoCloudRecording": false
      },
      "chatFeatures": {
        "allowChat": true,
        "allowFileUpload": true
      },
      "sharedNotePadFeatures": {
        "allowedSharedNotePad": true
      },
      "whiteboardFeatures": {
        "allowedWhiteboard": true,
        "preloadFile": ""
      },
      "breakoutRoomFeatures": {
        "isAllow": true,
        "allowedNumberRooms": 6
      },
      "displayExternalLinkFeatures": {
        "isAllow": true
      },
      "ingressFeatures": {
        "isAllow": false
      },
      "speechToTextTranslationFeatures": {
        "isAllow": true,
        "isAllowTranslation": true
      }
    },
    "webhookUrl": "https://your-domain.com/webhook",
    "isBreakoutRoom": false,
    "parentRoomId": ""
  }
}

Response

{
  "status": true,
  "msg": "room created successfully",
  "roomId": "algebra-class-1402"
}

🎫 Generate Join Token

توکن ورود کاربر به جلسه را ایجاد می‌کند.

Endpoint

POST /auth/room/getJoinToken

Request Body

{
  "roomId": "algebra-class-1402",
  "userInfo": {
    "userId": "student-123",
    "name": "علی احمدی",
    "isAdmin": false,
    "isHidden": false,
    "userMetadata": {
      "profilePic": "https://example.com/avatar.jpg",
      "lockSettings": {
        "lockMicrophone": false,
        "lockWebcam": false,
        "lockScreenSharing": true,
        "lockChat": false
      }
    }
  }
}

Response

{
  "status": true,
  "msg": "token generated",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Integration Example

<!DOCTYPE html>
<html>
<head>
  <title>Join Meeting</title>
</head>
<body>
  <script>
    // توکن از سرور دریافت شده
    const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    const meetingUrl = `https://your-domain.com/login?access_token=${token}`;
    
    // هدایت کاربر به جلسه
    window.location.href = meetingUrl;
  </script>
</body>
</html>

✅ Check Room Status

Endpoint

POST /auth/room/isRoomActive

Request

{
  "roomId": "algebra-class-1402"
}

Response

{
  "status": true,
  "msg": "room is active",
  "isActive": true
}

📊 Get Active Room Info

اطلاعات کامل یک روم فعال و لیست شرکت‌کنندگان آن را برمی‌گرداند.

Endpoint

POST /auth/room/getActiveRoomInfo

Request

{
  "roomId": "algebra-class-1402"
}

Response

{
  "status": true,
  "msg": "success",
  "room": {
    "roomInfo": {
      "sid": "RM_xxxxxxxxxxxx",
      "roomId": "algebra-class-1402",
      "name": "algebra-class-1402",
      "emptyTimeout": 300,
      "maxParticipants": 50,
      "creationTime": "1699123456",
      "metadata": "{...}"
    },
    "participantsInfo": [
      {
        "sid": "PA_xxxxxxxxxxxx",
        "identity": "student-123",
        "name": "علی احمدی",
        "state": 0,
        "joinedAt": "1699123500"
      }
    ]
  }
}

📋 List All Active Rooms

لیست تمام روم‌های فعال را برمی‌گرداند.

Endpoint

POST /auth/room/getActiveRoomsInfo

Request

{}

Response

{
  "status": true,
  "msg": "success",
  "rooms": [
    {
      "roomId": "algebra-class-1402",
      "sid": "RM_xxxxxxxxxxxx",
      "numParticipants": 15,
      "creationTime": "1699123456"
    },
    {
      "roomId": "physics-class-1402",
      "sid": "RM_yyyyyyyyyyyy",
      "numParticipants": 8,
      "creationTime": "1699123789"
    }
  ]
}

🛑 End Room

جلسه را به پایان می‌رساند و تمام شرکت‌کنندگان را خارج می‌کند.

Endpoint

POST /auth/room/endRoom

Request

{
  "roomId": "algebra-class-1402"
}

Response

{
  "status": true,
  "msg": "room ended successfully"
}

📜 Fetch Past Rooms

لیست روم‌های گذشته را با امکان فیلتر و صفحه‌بندی برمی‌گرداند.

Endpoint

POST /auth/room/fetchPastRooms

Request

{
  "roomIds": ["algebra-class-1402", "physics-class-1402"],
  "from": 0,
  "limit": 20,
  "orderBy": "DESC"
}

Request Parameters

Parameter	Type	Description
`roomIds`	`string[]`	لیست شناسه‌های روم (اختیاری)
`from`	`number`	شروع صفحه‌بندی
`limit`	`number`	تعداد نتایج (حداکثر 100)
`orderBy`	`string`	ترتیب: `ASC` یا `DESC`

Response

{
  "status": true,
  "msg": "success",
  "result": {
    "totalRooms": 45,
    "from": 0,
    "limit": 20,
    "orderBy": "DESC",
    "roomsList": [
      {
        "roomId": "algebra-class-1402",
        "sid": "RM_xxxxxxxxxxxx",
        "roomTitle": "کلاس جبر خطی",
        "creationTime": "1699123456",
        "ended": "1699127056",
        "roomDuration": 3600
      }
    ]
  }
}

🎬 Recording Management API

📋 Fetch Recordings

لیست ضبط‌های انجام شده را دریافت می‌کند.

Endpoint

POST /auth/recording/fetch

Request

{
  "roomIds": ["algebra-class-1402"],
  "from": 0,
  "limit": 20,
  "orderBy": "DESC"
}

Response

{
  "status": true,
  "msg": "success",
  "result": {
    "totalRecordings": 5,
    "from": 0,
    "limit": 20,
    "orderBy": "DESC",
    "recordings": [
      {
        "recordId": "rec_xxxxxxxxxxxx",
        "roomId": "algebra-class-1402",
        "roomSid": "RM_xxxxxxxxxxxx",
        "filePath": "/recordings/algebra-class-1402_20231105.mp4",
        "fileSize": 524288000,
        "creationTime": "1699123456",
        "roomCreationTime": "1699120000",
        "recordingDuration": 3600
      }
    ]
  }
}

📄 Get Recording Info

اطلاعات کامل یک ضبط را برمی‌گرداند.

Endpoint

POST /auth/recording/recordingInfo

Request

{
  "recordId": "rec_xxxxxxxxxxxx"
}

Response

{
  "status": true,
  "msg": "success",
  "recordingInfo": {
    "recordId": "rec_xxxxxxxxxxxx",
    "roomId": "algebra-class-1402",
    "filePath": "/recordings/algebra-class-1402_20231105.mp4",
    "fileSize": 524288000,
    "creationTime": "1699123456"
  }
}

🗑️ Delete Recording

یک ضبط را حذف می‌کند.

Endpoint

POST /auth/recording/delete

Request

{
  "recordId": "rec_xxxxxxxxxxxx"
}

Response

{
  "status": true,
  "msg": "recording deleted successfully"
}

🔗 Get Download Token

توکن موقت برای دانلود فایل ضبط شده ایجاد می‌کند.

Endpoint

POST /auth/recording/getDownloadToken

Request

{
  "recordId": "rec_xxxxxxxxxxxx"
}

Response

{
  "status": true,
  "msg": "token generated",
  "token": "download_token_xxxxxxxxxxxx"
}

Download File

# دانلود فایل با توکن
curl -o recording.mp4 \
  "https://your-domain.com/download/recording/download_token_xxxxxxxxxxxx"

📈 Analytics API

📋 Fetch Analytics

لیست آنالیتیکس جلسات را دریافت می‌کند.

Endpoint

POST /auth/analytics/fetch

Request

{
  "roomIds": ["algebra-class-1402"],
  "from": 0,
  "limit": 20
}

Response

{
  "status": true,
  "msg": "success",
  "result": {
    "totalAnalytics": 10,
    "analyticsList": [
      {
        "analyticsId": "ana_xxxxxxxxxxxx",
        "roomId": "algebra-class-1402",
        "roomSid": "RM_xxxxxxxxxxxx",
        "fileId": "file_xxxxxxxxxxxx",
        "fileName": "analytics_algebra-class-1402_20231105.json",
        "filePath": "/analytics/algebra-class-1402_20231105.json",
        "fileSize": 102400,
        "creationTime": "1699127056"
      }
    ]
  }
}

🗑️ Delete Analytics

Endpoint

POST /auth/analytics/delete

Request

{
  "analyticsId": "ana_xxxxxxxxxxxx"
}

🔗 Get Download Token

Endpoint

POST /auth/analytics/getDownloadToken

Request

{
  "analyticsId": "ana_xxxxxxxxxxxx"
}

Response

{
  "status": true,
  "msg": "token generated",
  "token": "analytics_token_xxxxxxxxxxxx"
}

Download Analytics File

curl -o analytics.json \
  "https://your-domain.com/download/analytics/analytics_token_xxxxxxxxxxxx"

🎮 In-Meeting Controls API

نکته مهم: تمام endpoint های این بخش نیازمند Bearer Token در هدر Authorization هستند و از Binary Protobuf استفاده می‌کنند (مگر در موارد خاص که JSON ذکر شده باشد).

🔐 Verify Token

توکن کاربر را تایید کرده و اطلاعات اتصال را برمی‌گرداند.

Endpoint

POST /api/verifyToken

Request (Protobuf)

message VerifyTokenReq {}

Response (Protobuf)

message VerifyTokenRes {
  bool status = 1;
  string msg = 2;
  string roomId = 3;
  string userId = 4;
  string roomSid = 5;
  repeated string natsWsUrls = 6;
  string natsSubject = 7;
  string serverVersion = 8;
}

🎬 Recording & RTMP Control

Start/Stop Recording

Endpoint:

POST /api/recording

Request (Protobuf):

message RecordingReq {
  string sid = 1;          // Room SID
  RecordingTasks task = 2;  // START_RECORDING | STOP_RECORDING
  string rtmpUrl = 3;      // برای RTMP
}

enum RecordingTasks {
  START_RECORDING = 0;
  STOP_RECORDING = 1;
  START_RTMP = 2;
  STOP_RTMP = 3;
}

Response (Protobuf):

message RecordingRes {
  bool status = 1;
  string msg = 2;
}

🛑 End Room

اتاق را از داخل جلسه به پایان می‌رساند (فقط ادمین).

Endpoint

POST /api/endRoom

Request (Protobuf)

message RoomEndReq {
  string roomId = 1;
}

🔒 Update Lock Settings

تنظیمات قفل کاربران را تغییر می‌دهد (فقط ادمین).

Endpoint

POST /api/updateLockSettings

Request (Protobuf)

message UpdateUserLockSettingsReq {
  string roomSid = 1;
  string roomId = 2;
  string userId = 3;     // "all" برای همه | شناسه کاربر خاص
  string service = 4;     // mic | webcam | screenShare | chat | etc.
  string direction = 5;   // "lock" | "unlock"
}

Available Services

mic - میکروفون
webcam - وب‌کم
screenShare - اشتراک‌گذاری صفحه
chat - چت
sendChatMsg - ارسال پیام در چت
chatFile - ارسال فایل در چت
privateChat - چت خصوصی
whiteboard - وایت‌برد
sharedNotepad - یادداشت مشترک

🔇 Mute/Unmute Track

میکروفون یک یا تمام کاربران را قطع یا وصل می‌کند (فقط ادمین).

Endpoint

POST /api/muteUnmuteTrack

Request (Protobuf)

message MuteUnMuteTrackReq {
  string sid = 1;        // Room SID
  string roomId = 2;
  string userId = 3;     // "all" برای همه | شناسه کاربر
  string trackSid = 4;   // اختیاری
  bool muted = 5;        // true = mute | false = unmute
}

👤 Remove Participant

کاربر را از جلسه حذف می‌کند (فقط ادمین).

Endpoint

POST /api/removeParticipant

Request (Protobuf)

message RemoveParticipantReq {
  string sid = 1;
  string roomId = 2;
  string userId = 3;
  string msg = 4;        // پیام برای کاربر
  bool blockUser = 5;    // مسدود کردن دائمی
}

🎤 Switch Presenter

نقش ارائه‌دهنده را به کاربر می‌دهد یا می‌گیرد (فقط ادمین).

Endpoint

POST /api/switchPresenter

Request (Protobuf)

message SwitchPresenterReq {
  string userId = 1;
  SwitchPresenterTask task = 2;  // PROMOTE | DEMOTE
}

enum SwitchPresenterTask {
  PROMOTE = 0;
  DEMOTE = 1;
}

🎨 Advanced Features

🔗 External Display Link

لینک خارجی را برای تمام شرکت‌کنندگان نمایش می‌دهد (فقط ادمین).

Endpoint

POST /api/externalDisplayLink

Request (Protobuf)

message ExternalDisplayLinkReq {
  ExternalDisplayLinkTask task = 1;  // START_EXTERNAL_LINK | STOP_EXTERNAL_LINK
  string url = 2;
}

🎵 External Media Player

ویدیو یا صدای خارجی را پخش می‌کند (فقط ادمین).

Endpoint

POST /api/externalMediaPlayer

Request (Protobuf)

message ExternalMediaPlayerReq {
  ExternalMediaPlayerTask task = 1;  // START_PLAYBACK | STOP_PLAYBACK
  string url = 2;
  bool isPresentation = 3;
}

نکته: می‌توانید فایل را با /api/fileUpload آپلود کرده و لینک /download/uploadedFile/... را استفاده کنید.

🚪 Waiting Room

Approve Users

کاربران در اتاق انتظار را تایید می‌کند (فقط ادمین).

Endpoint:

POST /api/waitingRoom/approveUsers

Request (Protobuf):

message ApproveWaitingUsersReq {
  repeated string userIds = 1;
}

Update Waiting Room Message

Endpoint:

POST /api/waitingRoom/updateMsg

Request (Protobuf):

message UpdateWaitingRoomMessageReq {
  string message = 1;
}

📊 Polls (نظرسنجی)

Create Poll

نظرسنجی جدید ایجاد می‌کند (فقط ادمین).

Endpoint:

POST /api/polls/create

Request (Protobuf):

message CreatePollReq {
  string question = 1;
  repeated PollOption options = 2;
  bool isAnonymous = 3;
  bool allowMultipleVotes = 4;
}

message PollOption {
  uint64 id = 1;
  string text = 2;
}

List Polls

Endpoint:

GET /api/polls/listPolls

Response: Binary Protobuf

Submit Poll Response

Endpoint:

POST /api/polls/submitResponse

Request (Protobuf):

message SubmitPollResponseReq {
  string pollId = 1;
  repeated uint64 selectedOptionIds = 2;
}

Get Poll Results

Endpoint:

GET /api/polls/pollResponsesResult/:pollId

Response: Binary Protobuf با نتایج نظرسنجی

🏢 Breakout Rooms (اتاق‌های گروهی)

Create Breakout Rooms

Endpoint:

POST /api/breakoutRoom/create

Request (Protobuf):

message CreateBreakoutRoomsReq {
  uint64 duration = 1;
  repeated BreakoutRoom rooms = 2;
}

message BreakoutRoom {
  string id = 1;
  string title = 2;
  repeated string userIds = 3;
}

Join Breakout Room

Endpoint:

POST /api/breakoutRoom/join

Request (Protobuf):

message JoinBreakoutRoomReq {
  string breakoutRoomId = 1;
}

List Breakout Rooms

Endpoint:

GET /api/breakoutRoom/listRooms

End Breakout Room

Endpoint:

POST /api/breakoutRoom/endRoom

Request (Protobuf):

message EndBreakoutRoomReq {
  string breakoutRoomId = 1;
}

End All Breakout Rooms

Endpoint:

POST /api/breakoutRoom/endAllRooms

📡 Ingress (RTMP/WHIP Input)

ورودی استریم خارجی ایجاد می‌کند.

Endpoint

POST /api/ingress/create

Request (Protobuf)

message CreateIngressReq {
  IngressInput inputType = 1;  // RTMP_INPUT | WHIP_INPUT
  string participantName = 2;
  string roomId = 3;
}

enum IngressInput {
  RTMP_INPUT = 0;
  WHIP_INPUT = 1;
}

Response (Protobuf)

message CreateIngressRes {
  bool status = 1;
  string msg = 2;
  string ingressId = 3;
  string url = 4;
  string streamKey = 5;
}

Usage Example

پس از دریافت url و streamKey:

# استریم با FFmpeg
ffmpeg -re -i input.mp4 \
  -c:v libx264 -c:a aac \
  -f flv "rtmp://url/stream_key"

🗣️ Speech Services (Azure)

Enable/Disable Speech Service

Endpoint:

POST /api/speechServices/serviceStatus

Request (Protobuf):

message SpeechToTextTranslationReq {
  bool enabled = 1;
}

Get Azure Token

Endpoint:

POST /api/speechServices/azureToken

Request (Protobuf):

message GenerateAzureTokenReq {
  string userSid = 1;
}

📁 File Upload & Whiteboard

Upload File (Resumable)

برای آپلود فایل‌های بزرگ به صورت chunk به chunk.

Endpoint:

POST /api/fileUpload?resumable=true&roomSid=xxx&roomId=xxx&userId=xxx

Headers:

Authorization: <TOKEN>
Content-Type: multipart/form-data

Response: part_uploaded or error

Merge Uploaded Chunks

Endpoint:

POST /api/uploadedFileMerge

Request (JSON):

{
  "roomSid": "RM_xxxxxxxxxxxx",
  "roomId": "algebra-class-1402",
  "resumableIdentifier": "unique-file-id",
  "resumableFilename": "document.pdf",
  "resumableTotalChunks": 10
}

Response (JSON):

{
  "status": true,
  "msg": "file merged successfully",
  "filePath": "/uploads/document.pdf",
  "fileName": "document.pdf",
  "fileExtension": "pdf"
}

Convert Whiteboard File

فایل‌های PDF/Office را به تصاویر برای وایت‌برد تبدیل می‌کند.

پیش‌نیاز: libreoffice و mupdf-tools (mutool) باید روی سرور نصب باشند.

Endpoint:

POST /api/convertWhiteboardFile

Request (JSON):

{
  "roomSid": "RM_xxxxxxxxxxxx",
  "roomId": "algebra-class-1402",
  "filePath": "/uploads/document.pdf",
  "userId": "teacher-123"
}

Response (JSON):

{
  "status": true,
  "msg": "file converted successfully",
  "fileName": "document",
  "fileId": "file_xxxxxxxxxxxx",
  "filePath": "/whiteboard/document/",
  "totalPages": 15
}

🔧 Other Services

🔔 Webhook

برای دریافت رویدادهای LiveKit.

Endpoint:

POST /webhook

Headers:

Authorization: <LIVEKIT_WEBHOOK_TOKEN>

Webhook Events:

room_started - شروع روم
room_finished - پایان روم
participant_joined - ورود کاربر
participant_left - خروج کاربر
track_published - انتشار track
track_unpublished - حذف track
recording_started - شروع ضبط
recording_finished - پایان ضبط
و بیشتر...

❤️ Health Check

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

Endpoint:

GET /healthCheck

Response:

Healthy

سرویس‌های بررسی شده:

✅ Database (MySQL/MariaDB)
✅ Redis
✅ NATS

📥 Download Services

Download Uploaded File

GET /download/uploadedFile/:sid/*

Download Recording

GET /download/recording/:token

Download Analytics

GET /download/analytics/:token

🔄 Compatibility APIs

🟦 BigBlueButton (BBB) Compatibility

Plugnmeet از API های BigBlueButton پشتیبانی می‌کند.

Base Path:

/:apiKey/bigbluebutton/api

Available Endpoints:

GET/POST /create - ایجاد جلسه
GET/POST /join - ورود به جلسه
GET/POST /isMeetingRunning - بررسی فعال بودن
GET/POST /getMeetingInfo - اطلاعات جلسه
GET/POST /getMeetings - لیست جلسات
GET/POST /end - پایان جلسه
GET/POST /getRecordings - لیست ضبط‌ها
GET/POST /deleteRecordings - حذف ضبط
GET/POST /publishRecordings - انتشار ضبط
GET/POST /updateRecordings - به‌روزرسانی ضبط

Authentication: نیازمند checksum مطابق استاندارد BBB

Example (BBB Join)

API_KEY="your-api-key"
SECRET="your-secret"
MEETING_ID="test-meeting"
USER_NAME="Ali"

# ساخت query string
QUERY="meetingID=${MEETING_ID}&fullName=${USER_NAME}"

# محاسبه checksum
CHECKSUM=$(echo -n "join${QUERY}${SECRET}" | sha1sum | awk '{print $1}')

# URL نهایی
URL="https://your-domain.com/${API_KEY}/bigbluebutton/api/join?${QUERY}&checksum=${CHECKSUM}"

echo "Join URL: $URL"

🎓 LTI (Learning Tools Interoperability)

برای یکپارچگی با سیستم‌های LMS.

Base Path:

/lti/v1

LTI Landing

POST /lti/v1

LTI API Endpoints

نیازمند هدر Authorization خاص LTI:

POST /lti/v1/api/room/join - ورود به روم
POST /lti/v1/api/room/isActive - بررسی فعال بودن
POST /lti/v1/api/room/end - پایان روم
POST /lti/v1/api/recording/fetch - لیست ضبط‌ها
POST /lti/v1/api/recording/download - دانلود ضبط
POST /lti/v1/api/recording/delete - حذف ضبط

🛠️ SDKs & Tools

Official SDKs

PHP SDK

composer require mynaparrot/plugnmeet-sdk-php

<?php
require 'vendor/autoload.php';

use Mynaparrot\Plugnmeet\Parameters\CreateRoomParameters;
use Mynaparrot\Plugnmeet\PlugNmeet;

$plugnmeet = new PlugNmeet(
    'https://your-domain.com',
    'your-api-key',
    'your-secret'
);

// ایجاد روم
$params = new CreateRoomParameters();
$params->roomId = 'test-room';
$params->metadata->roomTitle = 'کلاس آزمایشی';

$result = $plugnmeet->room->create($params);

JavaScript/Node.js SDK

npm install plugnmeet-sdk-js

const { PlugNmeet } = require('plugnmeet-sdk-js');

const plugnmeet = new PlugNmeet({
  host: 'https://your-domain.com',
  apiKey: 'your-api-key',
  apiSecret: 'your-secret'
});

// ایجاد روم
const result = await plugnmeet.room.create({
  roomId: 'test-room',
  metadata: {
    roomTitle: 'کلاس آزمایشی'
  }
});

// تولید توکن ورود
const token = await plugnmeet.room.getJoinToken({
  roomId: 'test-room',
  userInfo: {
    userId: 'user-123',
    name: 'علی احمدی',
    isAdmin: false
  }
});

Docker Deployment

docker run -d \
  --name plugnmeet-server \
  -p 8080:8080 \
  -v $PWD/config.yaml:/config.yaml \
  mynaparrot/plugnmeet-server \
  --config /config.yaml

📚 Additional Resources

Documentation

🌐 Official Website: https://www.plugnmeet.org
📖 Full Documentation: https://www.plugnmeet.org/docs
🔧 Installation Guide: https://www.plugnmeet.org/docs/installation
👨‍💻 Developer Guide: https://www.plugnmeet.org/docs/developer-guide

Community & Support

💬 Discord: https://discord.gg/2X2ZaCHu4C
🐛 GitHub Issues: https://github.com/mynaparrot/plugNmeet-server/issues
📧 Email Support: [email protected]

Source Code

🖥️ Server: https://github.com/mynaparrot/plugNmeet-server
🎨 Client: https://github.com/mynaparrot/plugNmeet-client
🎬 Recorder: https://github.com/mynaparrot/plugNmeet-recorder

📝 Notes & Best Practices

Performance Tips

✅ از Redis برای caching استفاده کنید
✅ برای مقیاس‌پذیری از Load Balancer استفاده کنید
✅ ضبط‌ها را در storage خارجی (S3, MinIO) ذخیره کنید
✅ از CDN برای سرویس‌دهی فایل‌های استاتیک استفاده کنید

Security Best Practices

🔒 HTTPS را فعال کنید (الزامی)
🔒 apiKey و secret را محرمانه نگه دارید
🔒 از CORS Policy مناسب استفاده کنید
🔒 توکن‌ها را با expiration time محدود تولید کنید
🔒 Webhook signature را همیشه تایید کنید

Rate Limiting

/auth endpoints: 100 req/min per IP
/api endpoints: 1000 req/min per token
File uploads: 10 MB/s per user

🎯 Quick Start Checklist

LiveKit Server راه‌اندازی شده
Redis نصب و پیکربندی شده
MySQL/MariaDB آماده است
فایل config.yaml تنظیم شده
Plugnmeet Server در حال اجراست
Client UI در دسترس است
Test meeting ایجاد و تست شده
Webhook تنظیم شده (اختیاری)
Recording تست شده (اختیاری)

🎉 نسخه و تاریخچه تغییرات

نسخه فعلی مستند: 2.0.0
آخرین به‌روزرسانی: نوامبر 2024

برای مشاهده تاریخچه کامل تغییرات به فایل CHANGELOG.md مراجعه کنید.

ساخته شده با ❤️ توسط MynaParrot

Website • GitHub • Discord

32 KiB Raw Blame History

📚 Plugnmeet Server API Documentation

📖 فهرست مطالب

🚀 شروع سریع

🔐 احراز هویت و امنیت

🎯 API Reference

🔧 سایر سرویس‌ها

🚀 Quick Check: Room Status

Endpoint

Request

Response

cURL Example

⭐ Core Features

🎥 Video Conferencing

📊 Collaboration Tools

🎬 Recording & Streaming

🛡️ Security & Control

📈 Analytics & Monitoring

♿ Accessibility

🔐 Authentication

1. /auth Endpoints (HMAC + JSON)

Headers

محاسبه HMAC Signature

2. /api Endpoints (Bearer Token + Protobuf)

Headers

Request/Response Format

cURL Example با Protobuf

3. Special Authentication Methods

LTI (Learning Tools Interoperability)

BigBlueButton Compatibility

📋 Room Management API

🏗️ Create Room

Endpoint

Request Body

Response

🎫 Generate Join Token

Endpoint

Request Body

Response

Integration Example

✅ Check Room Status

Endpoint

Request

Response

📊 Get Active Room Info

Endpoint

Request

Response

📋 List All Active Rooms

Endpoint

Request

Response

🛑 End Room

Endpoint

Request

Response

📜 Fetch Past Rooms

Endpoint

Request

Request Parameters

Response

🎬 Recording Management API

📋 Fetch Recordings

Endpoint

Request

Response

📄 Get Recording Info

Endpoint

Request

Response

🗑️ Delete Recording

Endpoint

Request

Response

🔗 Get Download Token

Endpoint

Request

Response

Download File

📈 Analytics API

32 KiB

Raw Blame History

1. `/auth` Endpoints (HMAC + JSON)

2. `/api` Endpoints (Bearer Token + Protobuf)