آموزش استفاده از API آی‌روم

در بخش API در تنظیمات حساب، یک کلید ایجاد و مقدار کامل آن را کپی کنید. این مقدار فقط هنگام ایجاد کلید نمایش داده می‌شود. کلید را در تنظیمات امن سرور، مثلاً در متغیر محیطی، ذخیره کنید و درخواست‌ها را از سرور برنامهٔ خود بفرستید. کلید نباید در کد مرورگر یا اپلیکیشن کاربر قرار بگیرد.

curl 'https://iroom.live/api/v1/licences' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

در آرایهٔ data، لایسنس موردنظر را انتخاب کنید. مقدار id آن، همان شناسه‌ای است که در آدرس درخواست‌های بعدی استفاده می‌کنید. مقدار is_usable باید true باشد تا بتوانید با اتاق‌ها و اطلاعات آن لایسنس کار کنید.

اگر فهرست لایسنس‌ها خالی است، ابتدا اشتراک API تهیه کنید. ایجاد کلید API به‌تنهایی باعث ایجاد یا فعال‌شدن اشتراک نمی‌شود.

در مثال‌ها، YOUR_API_KEY را با کلید کامل خود جایگزین کنید. عبارت‌هایی مانند {licence} و {room} محل قرار دادن شناسه هستند؛ آن‌ها را همراه با آکولاد حذف کنید و شناسهٔ دریافت‌شده از API را بنویسید.

اتاق (Room) فضایی است که لینک ورود، اعضا و تنظیمات دسترسی آن را مدیریت می‌کنید. می‌توانید با همان لینک، در زمان‌های مختلف جلسه برگزار کنید. هر بار برگزاری، یک جلسهٔ جداگانه (Conference) محسوب می‌شود و شناسه، زمان شروع و پایان، فایل‌ها و گزارش‌های مربوط به خود را دارد.

برای مثال، یک اتاق برای جلسات هفتگی تیم ایجاد می‌کنید. جلسهٔ این هفته و جلسهٔ هفتهٔ بعد در همان اتاق برگزار می‌شوند، اما شناسه و گزارش حضور و غیاب آن‌ها جداست.

curl -X POST 'https://iroom.live/api/v1/licences/{licence}/rooms' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_NEW_UUID' \
  -d '{
    "title": "Product weekly meeting",
    "client_reference": "team-product",
    "access_type": "restricted",
    "admins": ["organizer@gmail.com"],
    "artifacts": {
      "recording": true,
      "attendance_report": true
    }
  }'

برای ایجاد هر اتاق جدید، یک شناسهٔ یکتا با قالب UUID تولید کنید و آن را به‌جای YOUR_NEW_UUID در هدر Idempotency-Key قرار دهید. این هدر از ایجاد اتاق تکراری هنگام ارسال مجدد همان درخواست جلوگیری می‌کند.

اگر به‌دلیل قطع ارتباط پاسخی دریافت نکردید، درخواست را با همان مقدار هدر و همان بدنهٔ JSON دوباره بفرستید. برای ایجاد اتاق دیگری، مقدار جدیدی تولید کنید. فیلد اختیاری client_reference برای نگه‌داری شناسهٔ داخلی برنامهٔ شما، مثلاً شناسهٔ یک کلاس، است و جایگزین Idempotency-Key نمی‌شود.

• در پاسخ ایجاد اتاق، data.id شناسهٔ اتاق و data.join_url لینک ورود است. هر دو را ذخیره کنید. برای درخواست‌های بعدی از شناسهٔ اتاق استفاده کنید؛ کد موجود در لینک ورود جایگزین این شناسه نیست.
• در درخواست ایجاد اتاق، می‌توانید ایمیل حداکثر چهار مدیر را در آرایهٔ admins بفرستید. پس از دریافت پاسخ، مقدار status هر فرد را در data.members بررسی کنید. فقط مقدار active به معنی فعال‌بودن عضویت اوست. اگر عضویت فعال نیست، جزئیات failure را نیز بخوانید.
• برای دریافت فهرست جلسات یک اتاق، درخواست GET /licences/{licence}/rooms/{room}/conferences را ارسال کنید. شناسهٔ هر جلسه را برای دریافت گزارش همان جلسه نگه دارید. مسیرهایی که در این راهنما به‌صورت کوتاه نوشته شده‌اند، بعد از /api/v1 قرار می‌گیرند.

برای افزودن هر فرد به فهرست اعضای اتاق، چه با نقش مهمان و چه با نقش مدیر، باید ایمیل حساب گوگل او را ارسال کنید. آدرس Gmail قابل استفاده است. ایمیل سازمانی نیز در صورتی قابل استفاده است که به یک حساب گوگل تعلق داشته باشد. فرد باید با همان حساب وارد جلسه شود تا دسترسی تعیین‌شده برای او اعمال شود.

برای فعال‌کردن دسترسی آزاد، هنگام ایجاد اتاق مقدار access_type را برابر open قرار دهید. برای تغییر اتاق موجود نیز همین مقدار را در بدنهٔ درخواست PATCH /licences/{licence}/rooms/{room} بفرستید.

ورود بدون حساب گوگل فقط مربوط به مهمانی است که با لینک وارد اتاق آزاد می‌شود. اگر می‌خواهید فردی را از طریق API به فهرست اعضا اضافه کنید یا به او نقش مدیر بدهید، همچنان به ایمیل حساب گوگل او نیاز دارید.

مسیر پایهٔ جدول: /api/v1/licences/{licence}/rooms/{room}. هر درخواست افزودن عضو فقط یک ایمیل می‌پذیرد. برای تغییر نقش، مقدار role باید admin یا guest باشد.

ممکن است در اولین درخواست پس از پایان جلسه، فایل‌ها یا گزارش کامل حضور و غیاب هنوز آماده نباشند. آی‌روم این اطلاعات را به‌روزرسانی می‌کند و برنامهٔ شما باید نسخهٔ جدید آن‌ها را دریافت کند. بنابراین اگر پاسخ API خالی بود، فوراً نتیجه نگیرید که جلسه فایل یا شرکت‌کننده‌ای نداشته است.

این بررسی را فقط برای اولین جلسهٔ اتاق انجام ندهید. هر بار که در همان اتاق جلسهٔ دیگری برگزار شود، اطلاعات و گزارش‌های جدیدی به آن اضافه می‌شود. برای دریافت تغییرات می‌توانید از روش‌های زیر استفاده کنید:

پاسخ API، اطلاعاتی را نشان می‌دهد که در زمان درخواست در آی‌روم موجود است. درخواست‌های مکرر باعث نمی‌شوند فایل یا گزارش زودتر آماده شود. وب‌هوک نیز پس از ثبت تغییر در آی‌روم ارسال می‌شود؛ دریافت آن لزوماً هم‌زمان با پایان جلسه نیست.

• ممکن است پاسخ در چند صفحه ارائه شود. مقدار meta.next_cursor را در پارامتر cursor درخواست بعدی بفرستید. این کار را تا زمانی ادامه دهید که مقدار آن null شود. در نوبت بعدیِ بررسی دوره‌ای، دوباره از صفحهٔ اول شروع کنید؛ cursor فقط برای ادامهٔ صفحه‌بندی است.
• شناسهٔ هر فایل و جلسه را در پایگاه دادهٔ خود ذخیره کنید و مشخص کنید به کدام اتاق و لایسنس تعلق دارد. اگر اطلاعات همان شناسه را دوباره دریافت کردید، رکورد قبلی را به‌روزرسانی کنید؛ رکورد جدید نسازید.
• وضعیت فایل در فیلد status مشخص می‌شود: pending یعنی هنوز آماده نیست، available یعنی در دسترس است، expired یعنی مهلت نگه‌داری آن تمام شده و removed یعنی حذف شده است. زمان انقضا را از expires_at و زمان آخرین به‌روزرسانی اطلاعات فایل را از synced_at بخوانید.
• لینک مشاهدهٔ فایل در view_url قرار دارد. بازشدن این لینک به مجوز دسترسی کاربر به همان فایل بستگی دارد؛ دسترسی آزاد اتاق به معنی عمومی‌بودن فایل‌ها نیست. مقدار download_url نیز ممکن است null باشد، پس همیشه وجود لینک دانلود را فرض نکنید.
• اگر در اطلاعات جلسه، مقدار attendance_synced_at برابر null است، گزارش حضور و غیاب هنوز دریافت نشده است. در این وضعیت، صفر بودن تعداد شرکت‌کنندگان به معنی خالی‌بودن جلسه نیست.

با فعال‌کردن وب‌هوک، آی‌روم تغییرات انتخاب‌شده را به سرور شما اطلاع می‌دهد. این اعلان به‌صورت یک درخواست POST با بدنهٔ JSON به آدرسی ارسال می‌شود که در تنظیمات ثبت کرده‌اید.

هر اعلان که در ادامه «رویداد» نامیده می‌شود، نوع تغییر و شناسهٔ اطلاعات مرتبط را دارد. برای مثال، رویداد report.updated مشخص می‌کند گزارش کدام جلسه تغییر کرده است، اما ردیف‌های گزارش را ارسال نمی‌کند. سرور شما باید پس از دریافت رویداد، گزارش آن جلسه را با یک درخواست جداگانه از API بگیرد.

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

   این مسیر باید درخواست POST با بدنهٔ JSON را بپذیرد و از اینترنت، با HTTPS روی پورت ۴۴۳، در دسترس باشد. نمی‌توانید از آدرس شبکهٔ داخلی یا localhost استفاده کنید. آدرس ثبت‌شده باید مستقیماً پاسخ بدهد و نباید درخواست را به آدرس دیگری هدایت کند.

2. آدرس و رویدادهای موردنظر را در پنل ثبت کنید.

   در بخش وب‌هوک‌ها در تنظیمات حساب، روی «افزودن وب‌هوک» بزنید. آدرس دریافت را وارد کنید، لایسنس‌ها و رویدادهایی را که می‌خواهید دنبال کنید انتخاب کنید و وب‌هوک را فعال کنید.

3. اتصال را آزمایش کنید.

   در پنل، از بخش «آزمایش اتصال» یک رویداد آزمایشی ارسال کنید و نتیجه را در «سوابق ارسال» ببینید. در این رویداد مقدار is_test برابر true است. شناسه‌های آن نمونه هستند؛ دریافت و پاسخ‌دادن به درخواست را بررسی کنید، اما با این شناسه‌ها برای گرفتن فایل، عضو یا گزارش به API درخواست نفرستید.

4. اطلاعات موجود را یک‌بار از API بگیرید.

   وب‌هوک فقط تغییرات مرتبط پس از ثبت و فعال‌سازی را ارسال می‌کند. برای دریافت اطلاعات قبلی، پس از فعال‌سازی وب‌هوک، فهرست جلسات، فایل‌ها و گزارش‌های موجود را از API بگیرید. هم‌زمان، دریافت رویدادهای جدید را نیز ادامه دهید.

در رویداد report.updated، اگر report_type برابر attendance بود، گزارش حضور و غیاب را از مسیر attendance بگیرید. اگر مقدار آن audit_log بود، از مسیر audit-events استفاده کنید. هر دو مسیر زیرمجموعهٔ جلسهٔ مشخص‌شده در conference_id هستند.

در حال حاضر وب‌هوک جداگانه‌ای برای ایجاد اتاق یا پایان جلسه وجود ندارد. برای اطلاع از جلسات جدید، فهرست conferences اتاق را به‌صورت دوره‌ای دریافت کنید.

{
  "id": "d8e8e646-4caa-408b-8783-eef01eb7a93e",
  "type": "report.updated",
  "version": 1,
  "occurred_at": "2026-09-08T11:00:00+00:00",
  "is_test": false,
  "data": {
    "licence_key": "lic_0123456789abcdef",
    "room_id": "7031f075-4f99-43d1-85d4-8bbb8d26df48",
    "conference_id": "f9c9e28a-cf51-4600-a5c1-b0b91465c1e0",
    "report_type": "attendance"
  }
}

نحوهٔ پاسخ‌دادن و مدیریت ارسال‌های تکراری

• ممکن است یک رویداد را چند بار دریافت کنید یا ترتیب دریافت با ترتیب وقوع تغییرات متفاوت باشد. مقدار id رویدادهای پردازش‌شده را در پایگاه داده نگه دارید تا یک رویداد دوباره پردازش نشود. در ارسال مجدد، شناسه و بدنه تغییر نمی‌کنند. این سابقه را دست‌کم سه ماه نگه دارید تا ارسال مجدد رویدادهای قدیمی هم باعث پردازش تکراری نشود.
• پس از ذخیرهٔ رویداد، یک پاسخ HTTP با کد 2xx، مثلاً 200 یا 204، برگردانید. برای فرستادن این پاسخ منتظر تکمیل پردازش و دریافت گزارش نمانید. اگر نتوانستید رویداد را ذخیره کنید، پاسخ موفق ندهید؛ پس از دریافت پاسخ موفق، آی‌روم ارسال را انجام‌شده در نظر می‌گیرد.
• اگر ارسال به‌دلیل خطای شبکه ناموفق باشد، یا سرور شما کد 408، 429، 500، 502، 503 یا 504 برگرداند، آی‌روم دوباره تلاش می‌کند. در هر دورهٔ ارسال، حداکثر ۱۰ تلاش انجام می‌شود که درخواست اول هم جزو آن‌هاست. برای سایر پاسخ‌های ناموفق، از جمله 3xx و 401، ارسال خودکار تکرار نمی‌شود.
• اگر ارسال ناموفق شد، ابتدا مشکل سرور دریافت را برطرف کنید. سپس در بخش «سوابق ارسال»، جزئیات درخواست را ببینید و روی «ارسال مجدد» بزنید. وب‌هوک باید فعال باشد. خطاهای زیاد ممکن است باعث غیرفعال‌شدن خودکار وب‌هوک شوند؛ در این حالت، پس از رفع مشکل آن را دوباره فعال کنید.
• ممکن است پس از رویداد حذف، درخواست دریافت همان عضو یا فایل پاسخ 404 بدهد. نوع رویداد و آخرین فهرست اعضا یا فایل‌ها را بررسی کنید. اگر مورد حذف شده است، اطلاعات ذخیره‌شده در برنامهٔ خود را اصلاح کنید و درخواست دریافت آن را مرتب تکرار نکنید.

در مستندات API ما، برای هر عملیات، آدرس درخواست، متد HTTP، ورودی‌های لازم و ساختار پاسخ نوشته شده است. می‌توانید مستندات را بدون ورود به حساب بخوانید. برای ارسال درخواست از داخل مستندات، باید کلید API معتبر وارد کنید.

1. عملیات موردنظر را پیدا کنید.

   ابتدا بخش لایسنس‌ها را باز کنید و درخواست دریافت فهرست را ببینید. سپس به بخش اتاق‌ها، اعضا، جلسات یا فایل‌ها بروید. هر عملیات با ترکیب متد، مانند GET یا POST، و آدرس درخواست مشخص می‌شود.

2. پارامترها و بدنهٔ درخواست را آماده کنید.

   در بخش پارامترهای مسیر (Path parameters)، شناسهٔ لایسنس، اتاق یا جلسه را وارد کنید. پارامترهای صفحه‌بندی در بخش Query parameters قرار می‌گیرند. برای ایجاد یا ویرایش، بخش بدنهٔ درخواست (Request body) را ببینید. ساختار داده (Schema) مشخص می‌کند هر فیلد چه نوعی دارد، چه مقادیری می‌پذیرد و آیا ارسال آن الزامی است.

3. کلید API را در بخش احراز هویت وارد کنید.

   در قسمت احراز هویت (Authentication)، مقدار کامل کلید را وارد کنید. در این قسمت فقط خود کلید لازم است؛ ابزار مستندات کلمهٔ Bearer را به هدر اضافه می‌کند. اگر درخواست را در برنامهٔ خود می‌سازید، هدر را به‌صورت Authorization: Bearer YOUR_API_KEY ارسال کنید.

4. درخواست را اجرا و پاسخ را بررسی کنید.

   می‌توانید نمونهٔ cURL یا کد زبان موردنظر را کپی و مقادیر نمونه را با اطلاعات خود جایگزین کنید. پیش از اجرا، هدرهای الزامی را بررسی کنید؛ برای ایجاد اتاق، Idempotency-Key هم لازم است. سپس کد وضعیت HTTP و بدنهٔ پاسخ را با توضیحات مستندات مقایسه کنید.

   درخواست‌هایی که از داخل مستندات اجرا می‌کنید واقعی هستند؛ مثلاً درخواست ایجاد اتاق، در حساب شما اتاق ایجاد می‌کند. برای شروع، درخواست خواندنیِ دریافت فهرست لایسنس‌ها را اجرا کنید.

5. تعریف API را در ابزار توسعه وارد کنید.

   فایل OpenAPI JSON شامل تعریف مسیرها، ورودی‌ها و پاسخ‌های API است. می‌توانید آن را در ابزاری مانند Postman وارد کنید تا درخواست‌ها بر اساس این تعریف ساخته شوند. کلید API در این فایل قرار ندارد و باید آن را جداگانه در ابزار تنظیم کنید.

در رابط کاربری، وضعیت اطلاعات را روشن نمایش دهید. برای فایلی که هنوز آماده نشده، پیام «در حال آماده‌سازی» مناسب است؛ فایل منقضی یا حذف‌شده باید وضعیت جداگانه داشته باشد. هنگام دریافت اطلاعات نیز نشان دهید که درخواست در حال انجام است و زمان آخرین دریافت موفق را نمایش دهید.