رویدادها
همهٔ مسیرها نسبت به https://app.lobbe.ai/api/v1 هستند و هر درخواست Authorization: Bearer $LOBBE_TOKEN را می‌فرستد. مرجع API همهٔ مسیرها را فهرست می‌کند و فیلدهای x-lobbe-* را توضیح می‌دهد.
GET /events
Section titled “GET /events”آنچه پس از یک نشانگر برای جلسه‌های صاحب حساب رخ داده است: ساخته‌شدن، انتظار برای نام‌گذاری، آماده‌شدن، شکست، تغییر و حذف.
| ویژگی | مقدار |
|---|---|
| دسترسی‌ها | recordings:read یا recordings:write |
| دقیقه مصرف می‌کند | خیر |
| سقف درخواست‌ها | read: ۶۰۰ درخواست در هر ۱۰ دقیقه برای هر توکن |
| پاسخ موفق | 200 |
پارامترها
Section titled “پارامترها”| نام | محل | نوع | الزامی | توضیح |
|---|---|---|---|---|
after |
query |
"latest" | string |
خیر | از کجا خوانده شود: مقدار nextCursor صفحهٔ قبل، بی‌تغییر، یا latest که از همین حالا شروع می‌کند (بدون رویداد، با نشانگری برای پرسیدن‌های بعدی). اگر نباشد، از قدیمی‌ترین رویدادی که خواندنِ از نو برمی‌گرداند، حدود دو ساعت پس از آغاز بازهٔ ۳۰ روزه‌ای که رویدادها نگه داشته می‌شوند. نشانگری که از این بازه قدیمی‌تر باشد پاسخ 410 CURSOR_EXPIRED می‌گیرد: نخست با after=latest نشانگر تازه‌ای بگیرید، بعد عقب‌ماندگی را از listReadyRecordings جبران کنید و سپس از همان نشانگر تازه به بعد بخوانید. مقدار نادرست پاسخ 400 می‌گیرد |
limit |
query |
integer |
خیر | تعداد رویدادهایی که برمی‌گردد، از ۱ تا ۵۰۰ (پیش‌فرض ۱۰۰) |
پاسخ 200
Section titled “پاسخ 200”آنچه از after به این سو برای جلسه‌هایی که این توکن به آن‌ها دسترسی دارد رخ داده است، از قدیمی‌ترین. با دسترسی recordings:read، جلسه‌های خود صاحب حساب (نه جلسه‌های سری‌هایی که عضوشان است)؛ اگر توکن فقط recordings:write داشته باشد، جلسه‌هایی که همین توکن فرستاده است.
| فیلد | نوع | همیشه می‌آید | توضیح |
|---|---|---|---|
schemaVersion |
1 |
بله | در نسخهٔ ۱ API همیشه 1 |
events[] |
object[] |
بله | رویدادهای این صفحه، از قدیمی‌ترین؛ برای یک جلسه، به همان ترتیبی که تغییرهایش رخ داد. هیچ رویدادی محتوای جلسه را همراه ندارد: فقط شناسه‌ها، وضعیت جلسه، کد خطا یا نوع تغییر |
events[] (type: "recording.created") |
object |
جلسه‌ای دریافت شد | |
events[].id |
string |
بله | شناسهٔ خود رویداد که در هر بار خواندن یکسان است: با آن رویدادی را که قبلاً پردازش کرده‌اید کنار بگذارید. این شناسه نشانگر نیست (برای صفحهٔ بعد از nextCursor استفاده کنید) |
events[].recordingId |
string |
بله | شناسهٔ جلسه‌ای که رویداد دربارهٔ آن است |
events[].seriesId |
string | null |
بله | سری‌ای که جلسه هنگام این تغییر در آن بود؛ اگر در هیچ سری‌ای نبود یا سری‌ها خاموش باشند null است |
events[].occurredAt |
string |
بله | زمان رخ دادن تغییر (ISO 8601، به وقت UTC)؛ به‌جای مرتب‌کردن بر اساس آن، ترتیب همین فهرست را دنبال کنید |
events[].type |
"recording.created" |
بله | recording.created: جلسه کامل دریافت شد، چه در برنامه ضبط شده باشد، چه بارگذاری شده باشد و چه با توکن فرستاده شده باشد |
events[].data |
object |
بله | status جلسه پس از این تغییر |
events[].data.status |
"QUEUED" | "TRANSCRIBING" | "NAMING" | "GENERATING" | "READY" | "FAILED" |
بله | جلسه کجاست: QUEUED، TRANSCRIBING، NAMING (در انتظار نام گوینده‌ها)، GENERATING (لُب در حال ساخت است)، سپس READY؛ یا FAILED |
events[] (type: "recording.naming_required") |
object |
جلسه‌ای منتظر نام‌گذاری است | |
events[].id |
string |
بله | شناسهٔ خود رویداد که در هر بار خواندن یکسان است: با آن رویدادی را که قبلاً پردازش کرده‌اید کنار بگذارید. این شناسه نشانگر نیست (برای صفحهٔ بعد از nextCursor استفاده کنید) |
events[].recordingId |
string |
بله | شناسهٔ جلسه‌ای که رویداد دربارهٔ آن است |
events[].seriesId |
string | null |
بله | سری‌ای که جلسه هنگام این تغییر در آن بود؛ اگر در هیچ سری‌ای نبود یا سری‌ها خاموش باشند null است |
events[].occurredAt |
string |
بله | زمان رخ دادن تغییر (ISO 8601، به وقت UTC)؛ به‌جای مرتب‌کردن بر اساس آن، ترتیب همین فهرست را دنبال کنید |
events[].type |
"recording.naming_required" |
بله | recording.naming_required: جلسه در مرحلهٔ NAMING است و منتظر نام گوینده‌ها یا رد شدن (skipRecordingNaming) است؛ هر بار که نام‌گذاری دوباره باز شود دوباره فرستاده می‌شود |
events[].data |
object |
بله | status جلسه پس از این تغییر |
events[].data.status |
"QUEUED" | "TRANSCRIBING" | "NAMING" | "GENERATING" | "READY" | "FAILED" |
بله | جلسه کجاست: QUEUED، TRANSCRIBING، NAMING (در انتظار نام گوینده‌ها)، GENERATING (لُب در حال ساخت است)، سپس READY؛ یا FAILED |
events[] (type: "recording.ready") |
object |
لُب جلسه‌ای آماده شد | |
events[].id |
string |
بله | شناسهٔ خود رویداد که در هر بار خواندن یکسان است: با آن رویدادی را که قبلاً پردازش کرده‌اید کنار بگذارید. این شناسه نشانگر نیست (برای صفحهٔ بعد از nextCursor استفاده کنید) |
events[].recordingId |
string |
بله | شناسهٔ جلسه‌ای که رویداد دربارهٔ آن است |
events[].seriesId |
string | null |
بله | سری‌ای که جلسه هنگام این تغییر در آن بود؛ اگر در هیچ سری‌ای نبود یا سری‌ها خاموش باشند null است |
events[].occurredAt |
string |
بله | زمان رخ دادن تغییر (ISO 8601، به وقت UTC)؛ به‌جای مرتب‌کردن بر اساس آن، ترتیب همین فهرست را دنبال کنید |
events[].type |
"recording.ready" |
بله | recording.ready: لُب جلسه برای نخستین بار ساخته شد و جلسهٔ کامل آن را می‌توان خواند؛ ساخت دوبارهٔ بعدی recording.updated با regenerated است، هرگز یک recording.ready دیگر |
events[].data |
object |
بله | status جلسه پس از این تغییر |
events[].data.status |
"QUEUED" | "TRANSCRIBING" | "NAMING" | "GENERATING" | "READY" | "FAILED" |
بله | جلسه کجاست: QUEUED، TRANSCRIBING، NAMING (در انتظار نام گوینده‌ها)، GENERATING (لُب در حال ساخت است)، سپس READY؛ یا FAILED |
events[] (type: "recording.failed") |
object |
جلسه‌ای ناموفق شد | |
events[].id |
string |
بله | شناسهٔ خود رویداد که در هر بار خواندن یکسان است: با آن رویدادی را که قبلاً پردازش کرده‌اید کنار بگذارید. این شناسه نشانگر نیست (برای صفحهٔ بعد از nextCursor استفاده کنید) |
events[].recordingId |
string |
بله | شناسهٔ جلسه‌ای که رویداد دربارهٔ آن است |
events[].seriesId |
string | null |
بله | سری‌ای که جلسه هنگام این تغییر در آن بود؛ اگر در هیچ سری‌ای نبود یا سری‌ها خاموش باشند null است |
events[].occurredAt |
string |
بله | زمان رخ دادن تغییر (ISO 8601، به وقت UTC)؛ به‌جای مرتب‌کردن بر اساس آن، ترتیب همین فهرست را دنبال کنید |
events[].type |
"recording.failed" |
بله | recording.failed: جلسه به‌طور قطعی ناموفق شد؛ شکستی که لُب هنوز خودش دوباره امتحانش می‌کند هرگز فرستاده نمی‌شود. پس از retryRecording جلسه بی‌آنکه رویداد جداگانه‌ای داشته باشد ادامه می‌دهد و رویداد بعدی‌اش از پی آن می‌آید |
events[].data |
object |
بله | status جلسه و دلیل شکست آن |
events[].data.status |
"QUEUED" | "TRANSCRIBING" | "NAMING" | "GENERATING" | "READY" | "FAILED" |
بله | جلسه کجاست: QUEUED، TRANSCRIBING، NAMING (در انتظار نام گوینده‌ها)، GENERATING (لُب در حال ساخت است)، سپس READY؛ یا FAILED |
events[].data.error |
object |
بله | چرا جلسه ناموفق شد |
events[].data.error.code |
string |
بله | کد شکست، مثلاً NO_SPEECH یا AUDIO_CORRUPT |
events[].data.error.retryable |
boolean |
بله | این‌که retryRecording کمکی می‌کند یا نه: برای جلسهٔ بدون گفتار یا با صدای آسیب‌دیده false است |
events[] (type: "recording.updated") |
object |
جلسه‌ای تغییر کرد: جلسه‌ای آماده، یا جلسهٔ حذف‌شده‌ای که برگشت | |
events[].id |
string |
بله | شناسهٔ خود رویداد که در هر بار خواندن یکسان است: با آن رویدادی را که قبلاً پردازش کرده‌اید کنار بگذارید. این شناسه نشانگر نیست (برای صفحهٔ بعد از nextCursor استفاده کنید) |
events[].recordingId |
string |
بله | شناسهٔ جلسه‌ای که رویداد دربارهٔ آن است |
events[].seriesId |
string | null |
بله | سری‌ای که جلسه هنگام این تغییر در آن بود؛ اگر در هیچ سری‌ای نبود یا سری‌ها خاموش باشند null است |
events[].occurredAt |
string |
بله | زمان رخ دادن تغییر (ISO 8601، به وقت UTC)؛ به‌جای مرتب‌کردن بر اساس آن، ترتیب همین فهرست را دنبال کنید |
events[].type |
"recording.updated" |
بله | recording.updated: جلسه‌ای READY تغییر کرد و data.change می‌گوید چگونه؛ ویرایش جلسه‌ای که هنوز در جریان است با recording.ready همان جلسه می‌آید. استثنا restored است که پس از یک recording.deleted می‌آید: جلسه با همان وضعیتی که داشت برگشت، پس data.status آن می‌تواند هر وضعیتی باشد |
events[].data |
object |
بله | status جلسه و نوع تغییر |
events[].data.status |
"QUEUED" | "TRANSCRIBING" | "NAMING" | "GENERATING" | "READY" | "FAILED" |
بله | جلسه کجاست: QUEUED، TRANSCRIBING، NAMING (در انتظار نام گوینده‌ها)، GENERATING (لُب در حال ساخت است)، سپس READY؛ یا FAILED |
events[].data.change |
"regenerated" | "renamed" | "transcript_edited" | "speakers_renamed" | "series_changed" | "restored" |
بله | نوع تغییر، هرگز خود تغییر: regenerated (لُب دوباره ساخته شد)، renamed (عنوان تغییر کرد)، transcript_edited (صاحب جلسه رونوشت را اصلاح کرد)، speakers_renamed (نام یک گوینده تغییر کرد)، series_changed (جلسه به سری‌ای رفت، از سری بیرون آمد یا سری‌اش عوض شد) یا restored (جلسهٔ حذف‌شده برگشت) |
events[] (type: "recording.deleted") |
object |
جلسه‌ای حذف شد | |
events[].id |
string |
بله | شناسهٔ خود رویداد که در هر بار خواندن یکسان است: با آن رویدادی را که قبلاً پردازش کرده‌اید کنار بگذارید. این شناسه نشانگر نیست (برای صفحهٔ بعد از nextCursor استفاده کنید) |
events[].recordingId |
string |
بله | شناسهٔ جلسه‌ای که رویداد دربارهٔ آن است |
events[].seriesId |
string | null |
بله | سری‌ای که جلسه هنگام این تغییر در آن بود؛ اگر در هیچ سری‌ای نبود یا سری‌ها خاموش باشند null است |
events[].occurredAt |
string |
بله | زمان رخ دادن تغییر (ISO 8601، به وقت UTC)؛ به‌جای مرتب‌کردن بر اساس آن، ترتیب همین فهرست را دنبال کنید |
events[].type |
"recording.deleted" |
بله | recording.deleted: جلسه حذف شد، در هر وضعیتی؛ از آن پس خواندن جلسهٔ کامل آن پاسخ 404 می‌گیرد، مگر این‌که جلسه برگردانده شود |
events[].data |
object |
بله | status جلسه پس از این تغییر |
events[].data.status |
"QUEUED" | "TRANSCRIBING" | "NAMING" | "GENERATING" | "READY" | "FAILED" |
بله | جلسه کجاست: QUEUED، TRANSCRIBING، NAMING (در انتظار نام گوینده‌ها)، GENERATING (لُب در حال ساخت است)، سپس READY؛ یا FAILED |
nextCursor |
string |
بله | همیشه هست: آن را به‌عنوان after بفرستید تا رویدادهای بعدی را بگیرید. صفحه‌ای که به آخرین رویداد رسیده باشد نشانگری از همین لحظه می‌گیرد، پس پرسیدن پی‌درپی از حسابی که رویداد تازه‌ای ندارد هرگز به 410 نمی‌رسد |
خطاها با { error: { code, message, details? } } پاسخ داده می‌شوند و code قرارداد است: خطاها را ببینید.