Dasturchilar uchun

Davra API

Davra'ni boshqa tizimlarga (masalan, onlayn ta'lim platformasiga) ulash uchun: uchrashuv yaratish, qatnashchilarga rol bilan shaxsiy havola berish, uchrashuvni saytingizga joylash va hodisalar haqida xabar olish (webhook).

1. Kalit (API key)

Kalit serverdagi app/config.json faylida, apiKeys bo'limida turadi (o'rnatish skripti ham oxirida ko'rsatadi). Har bir so'rovga sarlavha qo'shing:

Authorization: Bearer dvr_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

2. So'rovlar

Xatoliklar: {"error": {"code": "meeting_not_found", "message": "…"}} va tegishli HTTP holat kodi (400, 401, 404, 429…).

Uchrashuv yaratish

curl -X POST https://SIZNING-DOMEN/api/v1/meetings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "title": "Matematika — 5-dars",
    "passcode": "",
    "externalId": "course-15/lesson-5",
    "durationMinutes": 80,
    "settings": { "waitingRoom": true, "muteOnEntry": true, "allowShare": false }
  }'

Hammasi ixtiyoriy. externalId — o'z tizimingizdagi ID (masalan, dars raqami), ro'yxatda qaytadi.

Javob:

{
  "code": "kxp-mtrq-avd",
  "title": "Matematika — 5-dars",
  "url": "https://SIZNING-DOMEN/m/kxp-mtrq-avd",
  "hostKey": "…",                                   // faqat shu javobda keladi
  "hostUrl": "https://SIZNING-DOMEN/m/kxp-mtrq-avd#host=…",
  "settings": { … }, "createdAt": 1792300000000
}

Vaqt cheklovi

Vaqt tugashi bilan uchrashuv hamma uchun avtomatik yakunlanadi va havola orqali qayta kirib bo'lmaydi. Ekranda hamma qolgan vaqtni ko'rib turadi, tugashiga 5 va 1 daqiqa qolganda ogohlantirish chiqadi.

Javobda: durationMinutes, endsAt, startedAt, endTime (hisoblangan tugash vaqti yoki null), expired (vaqti tugaganmi). Davom etayotgan uchrashuvga PATCH bilan berilgan yangi vaqt darhol ta'sir qiladi:

curl -X PATCH https://SIZNING-DOMEN/api/v1/meetings/kxp-mtrq-avd \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "durationMinutes": 90 }'

Qoidalar (settings)

Shaxsiy kirish havolasi (rol bilan)

Ta'lim tizimida har bir foydalanuvchiga o'z havolasini bering: ism avtomatik qo'yiladi, parol so'ralmaydi, kutish zali o'tkazib yuboriladi (agar skipWaitingRoom: false bo'lmasa).

curl -X POST https://SIZNING-DOMEN/api/v1/meetings/kxp-mtrq-avd/join-links \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Aziz Rahimov", "role": "participant", "userId": "1042", "expiresInMinutes": 240 }'

Rollar: host (mezbon), cohost (yordamchi mezbon), participant (ishtirokchi). Javobdagi url ni foydalanuvchiga bering. userId webhook va qatnashchilar ro'yxatida qaytadi.

PHP misol

<?php
function davra($method, $path, $body = null) {
    $ch = curl_init('https://SIZNING-DOMEN' . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('DAVRA_KEY'), 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS     => $body ? json_encode($body) : null,
    ]);
    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $res;
}

$meeting = davra('POST', '/api/v1/meetings', ['title' => 'Fizika — 3-dars', 'durationMinutes' => 80, 'settings' => ['waitingRoom' => true]]);
$teacher = davra('POST', "/api/v1/meetings/{$meeting['code']}/join-links", ['name' => 'Ustoz', 'role' => 'host']);
$student = davra('POST', "/api/v1/meetings/{$meeting['code']}/join-links", ['name' => 'Aziz', 'role' => 'participant', 'userId' => 1042]);
// $teacher['url'] va $student['url'] — kirish havolalari

3. Saytingizga joylash (iframe)

<iframe src="https://SIZNING-DOMEN/m/kxp-mtrq-avd#t=…shaxsiy-token…"
        allow="camera; microphone; display-capture; fullscreen; autoplay; clipboard-write"
        style="width:100%; height:720px; border:0; border-radius:16px"></iframe>

Joylashtirilgan uchrashuv ota sahifaga xabar yuboradi (window.postMessage):

window.addEventListener('message', (e) => {
  if (e.data && e.data.source === 'davra') {
    // e.data.type: "waiting" | "joined" | "left"   (left: e.data.reason = "left" | "ended" | "time_up" | "removed" …)
    // "timer" (e.data.endTime), "timeWarning" (e.data.minutesLeft = 5 | 1)
    console.log(e.data.type, e.data);
  }
});

4. Webhook — hodisalar haqida xabar

app/config.json da "webhookUrl": "https://sizning-tizim/davra-hook" ni yozing va xizmatni qayta ishga tushiring (systemctl restart davra). Har bir hodisa JSON ko'rinishida POST qilinadi:

{ "id": "evt_…", "event": "participant.joined", "createdAt": "2026-10-18T10:00:00Z",
  "data": { "code": "kxp-mtrq-avd", "participant": { "id": "…", "name": "Aziz", "role": "participant", "userId": "1042" } } }

Imzoni tekshiring (webhookSecret — config.json da):

<?php
$body = file_get_contents('php://input');
preg_match('/t=(\d+),v1=([0-9a-f]+)/', $_SERVER['HTTP_X_DAVRA_SIGNATURE'] ?? '', $m);
$expected = hash_hmac('sha256', $m[1] . '.' . $body, getenv('DAVRA_WEBHOOK_SECRET'));
if (!$m || !hash_equals($expected, $m[2]) || abs(time() - (int) $m[1]) > 300) {
    http_response_code(401); exit;
}
$event = json_decode($body, true);
// … davomatni saqlash va h.k.
http_response_code(200);

Javob 2xx bo'lmasa, xabar 5 soniya, 30 soniya va 2 daqiqadan so'ng qayta yuboriladi.